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.

FieldRequired?ValidationDescription
event_typeYesVPN_SESSION_IP_ASSIGNEDThe event type of this Universal Event.
versionYesInsightIDR 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.
timeYesMust be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZThe ISO 8601 extended timestamp.
accountYesThis should be a non- empty string, such as jdoeThe 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_domainNoThe value must either be null or nonempty, such as CORPThe Active Directory domain of the account.
assigned_ipYesThis 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_dataNoMust 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.

FieldRequired?ValidationDescription
event_typeYesVPN_SESSION_IP_ASSIGNEDThe event type of this Universal Event.
versionYesInsightIDR 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.
timeYesMust be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZThe ISO 8601 extended timestamp.
accountYesThis should be a non- empty string, such as jdoeThe 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_domainNoThe value must either be null or nonempty, such as CORPThe Active Directory domain of the account.
assigned_ipYesThis 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_ipYesThis 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_resultYesThis must be either ‘SUCCESS’ or ‘FAILURE’.The authentication result.
authentication_targetYesMust be a unique string value per application or service. Alphanumeric characters, spaces, and the characters _ - ( ) . are valid in this string. For example, Boston Office VPNA 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_dataNoMust 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.

FieldRequired?ValidationDescription
event_typeYesThis field must be VPN_SESSION_TERMINATION in order to indicate the type of Universal Event.The event type of this Universal Event.
versionYesInsightIDR 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.
timeYesMust be a valid ISO 8601 extended timestamp with millisecond precision, such as the following: yyyy-MM-dd'T'HH:mm:ss.SSSZThe ISO 8601 extended timestamp.
accountYesThis should be a non- empty string, such as jdoeThe 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_domainNoThe value must either be null or nonempty, such as CORPThe Active Directory domain of the account.
custom_dataNoMust 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:

1
{
2
"event_type": "VPN_SESSION_IP_ASSIGNED",
3
"version": "v1",
4
"time": "2018-06-07T18:18:31.123Z",
5
"account": "jdoe",
6
"assigned_ip": "10.6.100.40",
7
"source_ip": "33.5.100.40",
8
"authentication_result": "SUCCESS",
9
"authentication_target": "Boston Office VPN"
10
}

Or:

1
{
2
"event_type": "VPN_SESSION_IP_ASSIGNED",
3
"version": "v1",
4
"time": "2018-06-07T18:18:31.123Z",
5
"account": "jdoe",
6
"account_domain": "CORP",
7
"assigned_ip": "10.6.100.40"
8
}

Or:

1
{
2
"event_type": "VPN_SESSION_IP_ASSIGNED",
3
"version": "v1",
4
"time": "2018-06-07T18:18:31.123Z",
5
"account": "jdoe",
6
"account_domain": "CORP",
7
"assigned_ip": "10.6.100.40",
8
"custom_data": {
9
"key":"value"
10
}
11
}
12

Or:

1
2
{
3
"event_type": "VPN_SESSION_TERMINATION",
4
"version": "v1",
5
"time": "2018-06-07T18:18:31.123Z",
6
"account": "jdoe",
7
"account_domain": "CORP"
8
}