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.

FieldRequired?ValidationDescription
event_typeYesThis field must be DHCP_LEASE, in order to indicate the type of Universal Event.The event type of this Universal Event.
versionYesThe 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.
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.
client_hostnameYesUse 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_ipYesThis 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.
operationYesThis 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_addressNoThis must be a 6 byte MAC Address encoded as 6 hexadecimal octets. Currently, The following format is: 02:42:c9:a9:cd:b6The mac address of the DHCP client. This is the CHADDR (Client hardware address) in the DHCP ACK packet.
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

NOTE - Case sensitivity

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

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":"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
}