main.zeek

DHCP

Analyze DHCP traffic and provide a log that is organized around the idea of a DHCP “conversation” defined by messages exchanged within a relatively short period of time using the same transaction ID. The log will have information from clients and servers to give a more complete picture of what happened.

Namespace: DHCP
Imports: base/frameworks/cluster, base/protocols/dhcp/consts.zeek

Summary

Runtime Options

`DHCP::max_msg_types_per_log_entry`: `count` `&redef`	The maximum number of msg_types allowed in a single log entry.
`DHCP::max_txid_watch_time`: `interval` `&redef`	The maximum amount of time that a transaction ID will be watched for to try and tie messages together into a single DHCP transaction narrative.
`DHCP::max_uids_per_log_entry`: `count` `&redef`	The maximum number of uids allowed in a single log entry.

State Variables

DHCP::log_info: DHCP::Info

This is a global variable that is only to be used in the DHCP::aggregate_msgs event.

Types

DHCP::Info: record

The record type which contains the column fields of the DHCP log.

Redefinitions

`DHCP::Info`: `record`	New Fields `DHCP::Info` last_message_ts: `time` `&optional`
`Log::ID`: `enum`	`DHCP::LOG`
`connection`: `record`	New Fields `connection` dhcp: `DHCP::Info` `&optional`
`likely_server_ports`: `set` `&redef`

Events

`DHCP::aggregate_msgs`: `event`	This event is used internally to distribute data around clusters since DHCP doesn’t follow the normal “connection” model used by most protocols.
`DHCP::log_dhcp`: `event`	Event that can be handled to access the DHCP record as it is sent on to the logging framework.

Hooks

DHCP::log_policy: Log::PolicyHook

Detailed Interface

Runtime Options

DHCP::max_msg_types_per_log_entry 

Type: count
Attributes: &redef
Default: 50

The maximum number of msg_types allowed in a single log entry.

DHCP::max_txid_watch_time 

Type: interval
Attributes: &redef
Default: 30.0 secs

The maximum amount of time that a transaction ID will be watched for to try and tie messages together into a single DHCP transaction narrative.

DHCP::max_uids_per_log_entry 

Type: count
Attributes: &redef
Default: 10

The maximum number of uids allowed in a single log entry.

State Variables

DHCP::log_info 

Type

DHCP::Info

Default

{
   ts=<uninitialized>
   uids={

   }
   client_addr=<uninitialized>
   server_addr=<uninitialized>
   client_port=<uninitialized>
   server_port=<uninitialized>
   mac=<uninitialized>
   host_name=<uninitialized>
   client_fqdn=<uninitialized>
   domain=<uninitialized>
   requested_addr=<uninitialized>
   assigned_addr=<uninitialized>
   lease_time=<uninitialized>
   client_message=<uninitialized>
   server_message=<uninitialized>
   msg_types=[]
   duration=0 secs
   client_chaddr=<uninitialized>
   last_message_ts=<uninitialized>
   msg_orig=[]
   client_software=<uninitialized>
   server_software=<uninitialized>
   circuit_id=<uninitialized>
   agent_remote_id=<uninitialized>
   subscriber_id=<uninitialized>
}

This is a global variable that is only to be used in the DHCP::aggregate_msgs event. It can be used to avoid looking up the info record for a transaction ID in every event handler for DHCP::aggregate_msgs.

Types

DHCP::Info 

Type

record

ts: time &log: The earliest time at which a DHCP message over the associated connection is observed.
uids: set [string] &log: A series of unique identifiers of the connections over which DHCP is occurring. This behavior with multiple connections is unique to DHCP because of the way it uses broadcast packets on local networks.
client_addr: addr &log &optional: IP address of the client. If a transaction is only a client sending INFORM messages then there is no lease information exchanged so this is helpful to know who sent the messages. Getting an address in this field does require that the client sources at least one DHCP message using a non-broadcast address.
server_addr: addr &log &optional: IP address of the server involved in actually handing out the lease. There could be other servers replying with OFFER messages which won’t be represented here. Getting an address in this field also requires that the server handing out the lease also sources packets from a non-broadcast IP address.
client_port: port &optional: Client port number seen at time of server handing out IP (expected as 68/udp).
server_port: port &optional: Server port number seen at time of server handing out IP (expected as 67/udp).
mac: string &log &optional: Client’s hardware address.
host_name: string &log &optional: Name given by client in Hostname option 12.
client_fqdn: string &log &optional: FQDN given by client in Client FQDN option 81.
domain: string &log &optional: Domain given by the server in option 15.
requested_addr: addr &log &optional: IP address requested by the client.
assigned_addr: addr &log &optional: IP address assigned by the server.
lease_time: interval &log &optional: IP address lease interval.
client_message: string &log &optional: Message typically accompanied with a DHCP_DECLINE so the client can tell the server why it rejected an address.
server_message: string &log &optional: Message typically accompanied with a DHCP_NAK to let the client know why it rejected the request.
msg_types: vector of string &log &default = [] &optional: The DHCP message types seen by this DHCP transaction
duration: interval &log &default = 0 secs &optional: Duration of the DHCP “session” representing the time from the first message to the last.
client_chaddr: string &optional: The CHADDR field sent by the client.

last_message_ts: time &optional

msg_orig: vector of addr &log &default = [] &optional

(present if policy/protocols/dhcp/msg-orig.zeek is loaded)

The address that originated each message from the msg_types field.

client_software: string &log &optional

(present if policy/protocols/dhcp/software.zeek is loaded)

Software reported by the client in the vendor_class option.

server_software: string &log &optional

(present if policy/protocols/dhcp/software.zeek is loaded)

Software reported by the server in the vendor_class option.

circuit_id: string &log &optional

(present if policy/protocols/dhcp/sub-opts.zeek is loaded)

Added by DHCP relay agents which terminate switched or permanent circuits. It encodes an agent-local identifier of the circuit from which a DHCP client-to-server packet was received. Typically it should represent a router or switch interface number.

agent_remote_id: string &log &optional

(present if policy/protocols/dhcp/sub-opts.zeek is loaded)

A globally unique identifier added by relay agents to identify the remote host end of the circuit.

subscriber_id: string &log &optional

(present if policy/protocols/dhcp/sub-opts.zeek is loaded)

The subscriber ID is a value independent of the physical network configuration so that a customer’s DHCP configuration can be given to them correctly no matter where they are physically connected.

The record type which contains the column fields of the DHCP log.

Events

DHCP::aggregate_msgs 

Type: event (ts: time, id: conn_id, uid: string, is_orig: bool, msg: DHCP::Msg, options: DHCP::Options)

This event is used internally to distribute data around clusters since DHCP doesn’t follow the normal “connection” model used by most protocols. It can also be handled to extend the DHCP log. DHCP::log_info.

DHCP::log_dhcp 

Type: event (rec: DHCP::Info)

Event that can be handled to access the DHCP record as it is sent on to the logging framework.

Hooks

DHCP::log_policy 

Type: Log::PolicyHook