Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-08 09:38:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Copy docs into Zeek repo directly

Browse source 
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.
This commit is contained in:
Tim Wojtulewicz 2025-09-15 15:52:18 -07:00
parent 83f1e74643
commit ded98cd373
1074 changed files with 169319 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/scripts/base/protocols/dhcp/__load__.zeek.rst Normal file
View file

@ -0,0 +1,14 @@
:tocdepth: 3
base/protocols/dhcp/__load__.zeek
=================================
:Imports: :doc:`base/protocols/dhcp/consts.zeek </scripts/base/protocols/dhcp/consts.zeek>`, :doc:`base/protocols/dhcp/main.zeek </scripts/base/protocols/dhcp/main.zeek>`
Summary
~~~~~~~
Detailed Interface
~~~~~~~~~~~~~~~~~~

231
doc/scripts/base/protocols/dhcp/consts.zeek.rst Normal file
View file

@ -0,0 +1,231 @@
:tocdepth: 3
base/protocols/dhcp/consts.zeek
===============================
.. zeek:namespace:: DHCP
Types, errors, and fields for analyzing DHCP data. A helper file
for DHCP analysis scripts.
:Namespace: DHCP
Summary
~~~~~~~
Constants
#########
================================================================================================ ===================================
:zeek:id:`DHCP::message_types`: :zeek:type:`table` :zeek:attr:`&default` = :zeek:type:`function` Types of DHCP messages.
:zeek:id:`DHCP::option_types`: :zeek:type:`table` :zeek:attr:`&default` = :zeek:type:`function` Option types mapped to their names.
================================================================================================ ===================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Constants
#########
.. zeek:id:: DHCP::message_types
:source-code: base/protocols/dhcp/consts.zeek 9 9
:Type: :zeek:type:`table` [:zeek:type:`count`] of :zeek:type:`string`
:Attributes: :zeek:attr:`&default` = :zeek:type:`function`
:Default:
::
{
[2] = "OFFER",
[14] = "BULKLEASEQUERY",
[6] = "NAK",
[15] = "LEASEQUERYDONE",
[16] = "ACTIVELEASEQUERY",
[8] = "INFORM",
[9] = "FORCERENEW",
[1] = "DISCOVER",
[11] = "LEASEUNASSIGNED",
[7] = "RELEASE",
[5] = "ACK",
[10] = "LEASEQUERY",
[4] = "DECLINE",
[12] = "LEASEUNKNOWN",
[13] = "LEASEACTIVE",
[18] = "TLS",
[3] = "REQUEST",
[17] = "LEASEQUERYSTATUS"
}
Types of DHCP messages. See :rfc:`1533`, :rfc:`3203`,
:rfc:`4388`, :rfc:`6926`, and :rfc:`7724`.
.. zeek:id:: DHCP::option_types
:source-code: base/protocols/dhcp/consts.zeek 31 31
:Type: :zeek:type:`table` [:zeek:type:`count`] of :zeek:type:`string`
:Attributes: :zeek:attr:`&default` = :zeek:type:`function`
:Default:
::
{
[39] = "Keepalive Data",
[73] = "Finger-Server",
[46] = "NETBIOS Node Type",
[28] = "Broadcast Address",
[212] = "OPTION_6RD",
[9] = "LPR Server",
[68] = "Home-Agent-Addrs",
[53] = "DHCP Msg Type",
[71] = "NNTP-Server",
[52] = "Overload",
[41] = "NIS Servers",
[17] = "Root Path",
[119] = "Domain Search",
[81] = "Client FQDN",
[88] = "BCMCS Controller Domain Name list",
[29] = "Mask Discovery",
[133] = "IEEE 802.1D/p Layer 2 Priority",
[176] = "IP Telephone (Tentatively Assigned - 2005-06-23)",
[213] = "OPTION_V4_ACCESS_DOMAIN",
[54] = "DHCP Server Id",
[95] = "LDAP",
[90] = "Authentication",
[252] = "auto-proxy-config",
[146] = "RDNSS Selection",
[86] = "NDS Tree Name",
[1] = "Subnet Mask",
[116] = "Auto-Config",
[158] = "OPTION_V4_PCP_SERVER",
[35] = "ARP Timeout",
[135] = "HTTP Proxy for phone-specific applications",
[3] = "Router",
[114] = "URL",
[140] = "OPTION-IPv4_FQDN-MoS",
[44] = "NETBIOS Name Srv",
[129] = "PXE - undefined (vendor specific)",
[34] = "Trailers",
[45] = "NETBIOS Dist Srv",
[14] = "Merit Dump File",
[31] = "Router Discovery",
[82] = "Relay Agent Information",
[56] = "DHCP Message",
[7] = "Log Server",
[66] = "Server-Name",
[26] = "MTU Interface",
[128] = "PXE - undefined (vendor specific)",
[175] = "Etherboot (Tentatively Assigned - 2005-06-23)",
[47] = "NETBIOS Scope",
[70] = "POP3-Server",
[93] = "Client System",
[2] = "Time Offset",
[132] = "IEEE 802.1Q VLAN ID",
[72] = "WWW-Server",
[24] = "MTU Timeout",
[69] = "SMTP-Server",
[99] = "GEOCONF_CIVIC",
[161] = "OPTION_MUD_URL_V4 (TEMPORARY - registered 2016-11-17)",
[61] = "Client Id",
[60] = "Class Id",
[51] = "Address Time",
[37] = "Default TCP TTL",
[18] = "Extension File",
[157] = "data-source",
[0] = "Pad",
[220] = "Subnet Allocation Option",
[137] = "OPTION_V4_LOST",
[94] = "Client NDI",
[19] = "Forward On/Off",
[20] = "SrcRte On/Off",
[33] = "Static Route",
[75] = "StreetTalk-Server",
[67] = "Bootfile-Name",
[30] = "Mask Supplier",
[15] = "Domain Name",
[77] = "User-Class",
[64] = "NIS-Domain-Name",
[211] = "Reboot Time",
[91] = "client-last-transaction-time option",
[156] = "dhcp-state",
[177] = "PacketCable and CableHome (replaced by 122)",
[97] = "UUID/GUID",
[55] = "Parameter List",
[21] = "Policy Filter",
[221] = "Virtual Subnet Selection (VSS) Option",
[4] = "Time Server",
[124] = "V-I Vendor Class",
[130] = "PXE - undefined (vendor specific)",
[12] = "Hostname",
[155] = "query-end-time",
[58] = "Renewal Time",
[134] = "Diffserv Code Point (DSCP) for VoIP signalling and media streams",
[80] = "Rapid Commit",
[150] = "TFTP server address",
[76] = "STDA-Server",
[25] = "MTU Plateau",
[142] = "OPTION-IPv4_Address-ANDSF",
[16] = "Swap Server",
[255] = "End",
[59] = "Rebinding Time",
[210] = "Path Prefix",
[38] = "Keepalive Time",
[154] = "query-start-time",
[63] = "NetWare/IP Option",
[42] = "NTP Servers",
[57] = "DHCP Max Msg Size",
[78] = "Directory Agent",
[98] = "User-Auth",
[113] = "Netinfo Tag",
[11] = "RLP Server",
[22] = "Max DG Assembly",
[43] = "Vendor Specific",
[136] = "OPTION_PANA_AGENT",
[144] = "GeoLoc",
[40] = "NIS Domain",
[151] = "status-code",
[208] = "PXELINUX Magic",
[36] = "Ethernet",
[6] = "Domain Server",
[141] = "SIP UA Configuration Service Domains",
[125] = "V-I Vendor-Specific Information",
[8] = "Quotes Server",
[23] = "Default IP TTL",
[27] = "MTU Subnet",
[145] = "FORCERENEW_NONCE_CAPABLE",
[83] = "iSNS",
[122] = "CCC",
[159] = "OPTION_V4_PORTPARAMS",
[92] = "associated-ip option",
[10] = "Impress Server",
[65] = "NIS-Server-Addr",
[13] = "Boot File Size",
[32] = "Router Request",
[74] = "IRC-Server",
[62] = "NetWare/IP Domain",
[101] = "TCode",
[89] = "BCMCS Controller IPv4 address option",
[118] = "Subnet Selection Option",
[138] = "OPTION_CAPWAP_AC_V4",
[160] = "DHCP Captive-Portal",
[139] = "OPTION-IPv4_Address-MoS",
[120] = "SIP Servers DHCP Option",
[152] = "base-time",
[50] = "Address Request",
[79] = "Service Scope",
[121] = "Classless Static Route Option",
[48] = "X Window Font",
[85] = "NDS Servers",
[49] = "X Window Manager",
[209] = "Configuration File",
[112] = "Netinfo Address",
[5] = "Name Server",
[100] = "PCode",
[117] = "Name Service Search",
[123] = "GeoConf Option",
[131] = "PXE - undefined (vendor specific)",
[87] = "NDS Context",
[153] = "start-time-of-state"
}
Option types mapped to their names.

23
doc/scripts/base/protocols/dhcp/index.rst Normal file
View file

@ -0,0 +1,23 @@
:orphan:
Package: base/protocols/dhcp
============================
Support for Dynamic Host Configuration Protocol (DHCP) analysis.
:doc:`/scripts/base/protocols/dhcp/__load__.zeek`
:doc:`/scripts/base/protocols/dhcp/consts.zeek`
Types, errors, and fields for analyzing DHCP data. A helper file
for DHCP analysis scripts.
:doc:`/scripts/base/protocols/dhcp/main.zeek`
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.

360
doc/scripts/base/protocols/dhcp/main.zeek.rst Normal file
View file

@ -0,0 +1,360 @@
:tocdepth: 3
base/protocols/dhcp/main.zeek
=============================
.. zeek:namespace:: 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: :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/protocols/dhcp/consts.zeek </scripts/base/protocols/dhcp/consts.zeek>`
Summary
~~~~~~~
Runtime Options
###############
==================================================================================== ================================================================
:zeek:id:`DHCP::max_msg_types_per_log_entry`: :zeek:type:`count` :zeek:attr:`&redef` The maximum number of msg_types allowed in a single log entry.
:zeek:id:`DHCP::max_txid_watch_time`: :zeek:type:`interval` :zeek:attr:`&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.
:zeek:id:`DHCP::max_uids_per_log_entry`: :zeek:type:`count` :zeek:attr:`&redef` The maximum number of uids allowed in a single log entry.
==================================================================================== ================================================================
State Variables
###############
================================================== ========================================================
:zeek:id:`DHCP::log_info`: :zeek:type:`DHCP::Info` This is a global variable that is only to be used in the
:zeek:see:`DHCP::aggregate_msgs` event.
================================================== ========================================================
Types
#####
============================================ =================================================================
:zeek:type:`DHCP::Info`: :zeek:type:`record` The record type which contains the column fields of the DHCP log.
============================================ =================================================================
Redefinitions
#############
==================================================================== ===========================================================
:zeek:type:`DHCP::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`DHCP::Info`
last_message_ts: :zeek:type:`time` :zeek:attr:`&optional`
:zeek:type:`Log::ID`: :zeek:type:`enum`
* :zeek:enum:`DHCP::LOG`
:zeek:type:`connection`: :zeek:type:`record`
:New Fields: :zeek:type:`connection`
dhcp: :zeek:type:`DHCP::Info` :zeek:attr:`&optional`
:zeek:id:`likely_server_ports`: :zeek:type:`set` :zeek:attr:`&redef`
==================================================================== ===========================================================
Events
######
=================================================== ================================================================
:zeek:id:`DHCP::aggregate_msgs`: :zeek:type:`event` This event is used internally to distribute data around clusters
since DHCP doesn't follow the normal "connection" model used by
most protocols.
:zeek:id:`DHCP::log_dhcp`: :zeek:type:`event` Event that can be handled to access the DHCP
record as it is sent on to the logging framework.
=================================================== ================================================================
Hooks
#####
========================================================= =
:zeek:id:`DHCP::log_policy`: :zeek:type:`Log::PolicyHook`
========================================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: DHCP::max_msg_types_per_log_entry
:source-code: base/protocols/dhcp/main.zeek 98 98
:Type: :zeek:type:`count`
:Attributes: :zeek:attr:`&redef`
:Default: ``50``
The maximum number of msg_types allowed in a single log entry.
.. zeek:id:: DHCP::max_txid_watch_time
:source-code: base/protocols/dhcp/main.zeek 92 92
:Type: :zeek:type:`interval`
:Attributes: :zeek:attr:`&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.
.. zeek:id:: DHCP::max_uids_per_log_entry
:source-code: base/protocols/dhcp/main.zeek 95 95
:Type: :zeek:type:`count`
:Attributes: :zeek:attr:`&redef`
:Default: ``10``
The maximum number of uids allowed in a single log entry.
State Variables
###############
.. zeek:id:: DHCP::log_info
:source-code: base/protocols/dhcp/main.zeek 110 110
:Type: :zeek: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
:zeek:see:`DHCP::aggregate_msgs` event. It can be used to avoid
looking up the info record for a transaction ID in every event handler
for :zeek:see:`DHCP::aggregate_msgs`.
Types
#####
.. zeek:type:: DHCP::Info
:source-code: base/protocols/dhcp/main.zeek 18 87
:Type: :zeek:type:`record`
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
The earliest time at which a DHCP message over the
associated connection is observed.
.. zeek:field:: uids :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&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.
.. zeek:field:: client_addr :zeek:type:`addr` :zeek:attr:`&log` :zeek:attr:`&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.
.. zeek:field:: server_addr :zeek:type:`addr` :zeek:attr:`&log` :zeek:attr:`&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.
.. zeek:field:: client_port :zeek:type:`port` :zeek:attr:`&optional`
Client port number seen at time of server handing out IP (expected
as 68/udp).
.. zeek:field:: server_port :zeek:type:`port` :zeek:attr:`&optional`
Server port number seen at time of server handing out IP (expected
as 67/udp).
.. zeek:field:: mac :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Client's hardware address.
.. zeek:field:: host_name :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Name given by client in Hostname option 12.
.. zeek:field:: client_fqdn :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
FQDN given by client in Client FQDN option 81.
.. zeek:field:: domain :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Domain given by the server in option 15.
.. zeek:field:: requested_addr :zeek:type:`addr` :zeek:attr:`&log` :zeek:attr:`&optional`
IP address requested by the client.
.. zeek:field:: assigned_addr :zeek:type:`addr` :zeek:attr:`&log` :zeek:attr:`&optional`
IP address assigned by the server.
.. zeek:field:: lease_time :zeek:type:`interval` :zeek:attr:`&log` :zeek:attr:`&optional`
IP address lease interval.
.. zeek:field:: client_message :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Message typically accompanied with a DHCP_DECLINE
so the client can tell the server why it rejected
an address.
.. zeek:field:: server_message :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Message typically accompanied with a DHCP_NAK to let
the client know why it rejected the request.
.. zeek:field:: msg_types :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
The DHCP message types seen by this DHCP transaction
.. zeek:field:: duration :zeek:type:`interval` :zeek:attr:`&log` :zeek:attr:`&default` = ``0 secs`` :zeek:attr:`&optional`
Duration of the DHCP "session" representing the
time from the first message to the last.
.. zeek:field:: client_chaddr :zeek:type:`string` :zeek:attr:`&optional`
The CHADDR field sent by the client.
.. zeek:field:: last_message_ts :zeek:type:`time` :zeek:attr:`&optional`
.. zeek:field:: msg_orig :zeek:type:`vector` of :zeek:type:`addr` :zeek:attr:`&log` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/dhcp/msg-orig.zeek` is loaded)
The address that originated each message from the
`msg_types` field.
.. zeek:field:: client_software :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/dhcp/software.zeek` is loaded)
Software reported by the client in the `vendor_class` option.
.. zeek:field:: server_software :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/dhcp/software.zeek` is loaded)
Software reported by the server in the `vendor_class` option.
.. zeek:field:: circuit_id :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/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.
.. zeek:field:: agent_remote_id :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/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.
.. zeek:field:: subscriber_id :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/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
######
.. zeek:id:: DHCP::aggregate_msgs
:source-code: base/protocols/dhcp/main.zeek 104 104
:Type: :zeek:type:`event` (ts: :zeek:type:`time`, id: :zeek:type:`conn_id`, uid: :zeek:type:`string`, is_orig: :zeek:type:`bool`, msg: :zeek:type:`DHCP::Msg`, options: :zeek:type:`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.
:zeek:see:`DHCP::log_info`.
.. zeek:id:: DHCP::log_dhcp
:source-code: policy/protocols/dhcp/software.zeek 40 65
:Type: :zeek:type:`event` (rec: :zeek:type:`DHCP::Info`)
Event that can be handled to access the DHCP
record as it is sent on to the logging framework.
Hooks
#####
.. zeek:id:: DHCP::log_policy
:source-code: base/protocols/dhcp/main.zeek 15 15
:Type: :zeek:type:`Log::PolicyHook`