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.

Field

Required?

Validation

Description

event_type

Yes

This field must be INGRESS_AUTHENTICATION in order to indicate the type of Universal Event.

The event type of this Universal Event.

version

Yes

InsightIDR 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.

time

Yes

Must be a valid ISO 8601 extended timestamp with millisecond precision, such as the following:
yyyy-MM-ddTHH: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 ingress authentication. If the account matches any known accounts associated with a user in InsightIDR, the ingress authentication activity will be attributed to that user.

account_domain

No

The value must either be null or nonempty, such as CORP

The Active Directory domain of the account.

source_ip

Yes

This 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_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, Marketing Wiki

The target service or application of the authentication attempt. The value of this field appears when hovering over the Ingress icon.

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 line 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