Rapid7 Universal VPN
If Rapid7 does not support the logging format of your VPN solution, you can still send data into InsightIDR’s User Behavior Analytics engine to trigger legacy detection rules, so long as you transform your logs to meet this universal event format (UEF) contract.
The Universal VPN event source supports multiple event types:
- VPN_SESSION_IP_ASSIGNED
- VPN_SESSION_TERMINATION
Need help transforming your logs?
Read instructions on transforming your logs in this Rapid7 blog post or on the Transform Logs to UEF help page.
Required Fields for VPN_SESSION_IP_ASSIGNED
When you initiate a VPN session, you must send InsightIDR a VPN_SESSION_IP_ASSIGNED event with the particular IP address assigned to the account.
Do not send VPN session events from devices where multiple user accounts use a single IP.
InsightIDR only supports monitoring VPN sessions when the assigned IP is fixed to a single user throughout their VPN session, and then returned to a pool when the VPN session terminates. If this is not followed, it will lead to unexpected behaviors and detections in the product.
| Field | Required? | Validation | Description |
|---|---|---|---|
| event_type | Yes | VPN_SESSION_IP_ASSIGNED | The event type of this Universal Event. |
| version | Yes | InsightIDR currently supports version “v1”. | The version of the VPN_SESSION_IP_ASSIGNED event_type. New versions may be added in the future with documented fields added, removed, or modified. |
| time | Yes | Must be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZ | The ISO 8601 extended timestamp. |
| account | Yes | This should be a non- empty string, such as jdoe | The account associated with the VPN session. If the account matches any known accounts associated with a user, InsightIDR will attribute the VPN session to that user. |
| account_domain | No | The value must either be null or nonempty, such as CORP | The Active Directory domain of the account. |
| assigned_ip | Yes | This must be an IPv4 address or IPv4 mapped IPv6 address. | The IP address that this account is assigned for the duration of the VPN session. |
| custom_data | No | Must be a JSON object. | Use this field to send any additional information. This data will be available for log search and LEQL queries. |
Required Fields for VPN_SESSION_IP_ASSIGNED with Ingress
You can optionally send the following additional fields with the VPN_SESSION_IP_ASSIGNED event, which enables InsightIDR to detect and visualize ingress activity from this event:
- source_ip
- authentication_target
- authentication_result
If all three fields are present and valid (in addition to the regular VPN fields), the Universal VPN event source will also interpret a Universal VPN Event as both a VPN action and ingress activity as defined in the Rapid7 Universal Ingress Authentication document.
If one or more of these three fields are present but missing data, InsightIDR will drop the VPN and Ingress event entirely.
All optional fields must be present and valid in order for the VPN and Ingress event in order to be accepted.
| Field | Required? | Validation | Description |
|---|---|---|---|
| event_type | Yes | VPN_SESSION_IP_ASSIGNED | The event type of this Universal Event. |
| version | Yes | InsightIDR currently supports version “v1”. | The version of the VPN_SESSION_IP_ASSIGNED event_type. New versions may be added in the future with documented fields added, removed, or modified. |
| time | Yes | Must be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZ | The ISO 8601 extended timestamp. |
| account | Yes | This should be a non- empty string, such as jdoe | The account associated with the VPN session. If the account matches any known accounts associated with a user, InsightIDR will attribute the VPN session to that user. |
| account_domain | No | The value must either be null or nonempty, such as CORP | The Active Directory domain of the account. |
| assigned_ip | Yes | This must be an IPv4 address or IPv4 mapped IPv6 address. | The IP address that this account is assigned for the duration of the VPN session. |
| source_ip | Yes | This must be an IPv4 address or IPv4 mapped IPv6 address. | The source IP address of the authentication. InsightIDR will only consider IP addresses that are public/routable IPs as valid ingress activity. |
| authentication_result | Yes | This must be either ‘SUCCESS’ or ‘FAILURE’. | The authentication result. |
| authentication_target | Yes | Must be a unique string value per application or service. Alphanumeric characters, spaces, and the characters _ - ( ) . are valid in this string. For example, Boston Office VPN | A name of the VPN where the authentication attempt happened. The value of this field appears when hovering over the Ingress icon. Can also be a general value like vpn. |
| custom_data | No | Must be a JSON object. | Additional information about the VPN event, it is not used in interpreting the event. Will show up in log search in source_data. |
Required Fields for VPN_SESSION_TERMINATION
When you terminate a VPN session, you must send a VPN_SESSION_TERMINATION event with the account whose session is being terminated. Once the session has been terminated, InsightIDR will no longer attribute activity to the user based on IP address that was assigned when the session was initiated.
If your log does not include the necessary info to produce VPN_SESSION_TERMINATION events, the assigned IP will be transferred over to the new session when the IP is observed by another VPN_SESSION_IP_ASSIGNED event.
| Field | Required? | Validation | Description |
|---|---|---|---|
| event_type | Yes | This field must be VPN_SESSION_TERMINATION in order to indicate the type of Universal Event. | The event type of this Universal Event. |
| version | Yes | InsightIDR currently supports version “v1”. | The VPN_SESSION_TERMINATION event version. New versions may be added in the future with documented fields added, removed, or modified. |
| time | Yes | Must be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZ | The ISO 8601 extended timestamp. |
| account | Yes | This should be a non- empty string, such as jdoe | The account associated with the VPN session. If the account matches any known accounts associated with a user, InsightIDR will find any existing IP mappings for that user and delete them. |
| account_domain | No | The value must either be null or nonempty, such as CORP | The Active Directory domain of the account. |
| custom_data | No | Must be a JSON object. | Use this field to send any additional information. This data will be available for log search and LEQL queries. |
Example Format
You must send events to the InsightIDR collector in UTF-8 format, with each log entry representing a single event, and a newline delimiting each event.
For example: {"event_type":"VPN_SESSION_IP_ASSIGNED","version":"v1","time":"2018-06-07T18:18:31.123Z","account":"jdoe","assigned_ip":"10.6.100.40","source_ip":"33.5.45.40","authentication_result":"SUCCESS","authentication_target":"Boston Office VPN"}
Each event sent to InsightIDR must not contain newline characters; InsightIDR only permits newlines that delimit separate Universal Events.
Here are some examples of Universal VPN Events with readable formatting:
Or:
Or:
Or: