Rapid7 Universal DHCP

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

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 DHCP logs contain the following fields so that you can construct a valid UEF DHCP object. Objects that violate the UEF will not be ingested by InsightIDR and will be unavailable for log search.

See https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol for more information about DHCP protocols.

Field

Required?

Validation

Description

event_type

Yes

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

The event type of this Universal Event.

version

Yes

The only currently supported version for the DHCP_LEASE event_type is v1.

The DHCP_LEASE event_type is versioned. 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.

client_hostname

Yes

Use a fully qualified domain name if possible. Otherwise, short hostnames are accepted.

The hostname of the DHCP client, as present in DHCP option 12.

client_ip

Yes

This must be an IPv4 address or IPv4 mapped IPv6 address.

The address of the DHCP client as present in the YIADDR field of a DHCPACK.

operation

Yes

This field must be OBTAIN or RELEASE.

The DHCP operation.

OBTAIN correlates directly to a DHCP ACK, or if DHCP server is creating a new lease or renewing an existing lease.

RELEASE correlates directly to a DHCP RELEASE.

client_mac_address

No

This must be a 6 byte MAC Address encoded as 6 hexadecimal octets.

Currently, The following format is:
02:42:c9:a9:cd:b6

The mac address of the DHCP client.

This is the CHADDR (Client hardware address) in the DHCP ACK packet.

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

NOTE - Case sensitivity

Be aware that InsightIDR regards these log lines as case sensitive.

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":"DHCP_LEASE","version": “v1”,"time": "2018-06-07T18:18:31.1Z","client_hostname":"pc.acme.com","client_ip":"10.6.102.53","operation": "OBTAIN"}

Each event sent to InsightIDR must not contain newline characters.

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

1
2
{
3
"version": "v1",
4
"event_type": "DHCP_LEASE",
5
"time": "2018-06-07T18:18:31.1234+0300",
6
"client_hostname": "pc.acme.com",
7
"client_ip": "10.6.102.53",
8
"operation": "OBTAIN"
9
}

Or:

1
{
2
"version": "v1",
3
"event_type": "DHCP_LEASE",
4
"time": "2018-06-07T18:18:31.123Z",
5
"client_hostname": "pc.acme.com",
6
"client_ip": "10.6.102.53",
7
"operation": "OBTAIN",
8
"client_mac_address": "02:42:c9:a9:cd:b6",
9
"custom_data": {
10
"location": "Vancouver Office",
11
"dhcp_server_number": 1
12
}
13
}