Rapid7 Universal Ingress Authentication

If Rapid7 does not support the logging format of your ingress authentications, you can still send data into InsightIDR so long as you transform your logs to meet this universal event format (UEF) contract.

Ingress authentications are any activity where a user account can be observed authenticating to a protected system from an IP on the public Internet. For example, when a user account uses the VPN to log in, checks their email on their mobile phone, or accesses cloud services like Google Apps, etc.

InsightIDR will use this activity for incident detection (Multiple Country Authentications, Ingress from Disabled Account, etc), visualization on the Ingress Locations map and dashboards, as well as investigations in Log Search.

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

Ensure that your Ingress Authentication logs contain the following fields so that you can construct a valid UEF Ingress Authentication object. Objects that violate the UEF will not be ingested by InsightIDR and will be unavailable for log search.

FieldRequired?ValidationDescription
event_typeYesThis field must be INGRESS_AUTHENTICATION in order to indicate the type of Universal Event.The event type of this Universal Event.
versionYesInsightIDR currently supports version v1.The version of the INGRESS_AUTHENTICATION event_type. New versions may be added in the future with documented fields added, removed, or modified.
timeYesThis must be a valid ISO 8601 extended timestamp with millisecond precision, such as the following:yyyy-MM-ddTHH #SS.SSSZThe ISO 8601 extended timestamp.
account_domainNoThe value must either be null or nonempty, such as CORPThe Active Directory domain of the account.
source_ipYesThis must be an IPv4 address or IPv4 mapped IPv6 address.The source IP address of the authentication. Only IP addresses that are public IPs (routable IPs) will be considered as valid ingress activity.
authentication_resultYesThis must be either ‘SUCCESS’ or ‘FAILURE’.The authentication result.
authentication_targetYesThis field must be a unique string value for each application or service. There is an upper character limit of 50 characters. Alphanumeric characters, spaces, and the characters _ - ( ) . are valid in this string. For example, Marketing WikiThe target service or application of the authentication attempt. The value of this field appears when hovering over the Ingress icon.
custom_dataNoThis 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":"INGRESS_AUTHENTICATION","version": "v1","time": "2018-06-07T18:18:31.1Z","account":"jdoe","account_domain":"CORP","source_ip":"10.6.102.53","authentication_result": "SUCCESS","authentication_target":"Marketing Wiki"}

Each event sent to InsightIDR must not contain newline characters.

Here are some examples of a Universal Ingress Authentication Event with readable formatting:

1
2
{
3
"version": "v1",
4
"event_type": "INGRESS_AUTHENTICATION",
5
"time": "2018-06-07T18:18:31.123Z",
6
"account": "jdoe",
7
"account_domain": "CORP",
8
"source_ip": "130.26.110.4",
9
"authentication_result": "SUCCESS",
10
"authentication_target": "Marketing Wiki"
11
}
12

Or:

1
{
2
"version": "v1",
3
"event_type": "INGRESS_AUTHENTICATION",
4
"time": "2018-06-07T18:18:31.99Z",
5
"account": "jdoe",
6
"account_domain": "CORP",
7
"source_ip": "130.26.110.4",
8
"authentication_result": "FAILURE",
9
"authentication_target": "Marketing Wiki",
10
"custom_data": {
11
"arbitrary_field": "arbitrary_value",
12
"arbitrary_number": 123
13
}
14
}
15