diff --git a/CHANGES b/CHANGES index 355b58f8fc..2fd5229d98 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,8 @@ +2.5-855 | 2018-08-17 16:34:51 -0500 + + * Add script to support the old DHCP events (Vlad Grigorescu) + 2.5-852 | 2018-08-17 15:15:55 -0500 * BIT-466: add redef += support to vectors (Jon Siwek, Corelight) diff --git a/NEWS b/NEWS index bb9ea619c8..ee7ae0cdaa 100644 --- a/NEWS +++ b/NEWS @@ -350,6 +350,13 @@ Changed Functionality - dhcp_release - dhcp_inform + - A new script, policy/protocols/dhcp/deprecated_events.bro, may be loaded + to aid those transitioning away from the list of "removed" events above. + The script provides definitions for the old events and automatically + generates them from a dhcp_message handler, thus providing equivalent + functionality to the previous Bro release. Such usage emits deprecation + warnings. + - Removed policy/misc/known-devices.bro script and thus known_devices.log will no longer be created. diff --git a/VERSION b/VERSION index 6aa99abe08..363ccfc578 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.5-852 +2.5-855 diff --git a/scripts/broxygen/__load__.bro b/scripts/broxygen/__load__.bro index dbc175c2a8..2c89631e76 100644 --- a/scripts/broxygen/__load__.bro +++ b/scripts/broxygen/__load__.bro @@ -6,6 +6,7 @@ @load frameworks/control/controller.bro @load frameworks/files/extract-all-files.bro @load policy/misc/dump-events.bro +@load policy/protocols/dhcp/deprecated_events.bro @load ./example.bro diff --git a/scripts/policy/protocols/dhcp/deprecated_events.bro b/scripts/policy/protocols/dhcp/deprecated_events.bro new file mode 100644 index 0000000000..941e5c72c3 --- /dev/null +++ b/scripts/policy/protocols/dhcp/deprecated_events.bro @@ -0,0 +1,272 @@ +##! Bro 2.6 removed certain DHCP events, but scripts in the Bro +##! ecosystem are still relying on those events. As a transition, this +##! script will handle the new event, and generate the old events, +##! which are marked as deprecated. Note: This script should be +##! removed in the next Bro version after 2.6. + +@load base/protocols/dhcp + +## A DHCP message. +## +## .. note:: This type is included to support the deprecated events dhcp_ack, +## dhcp_decline, dhcp_discover, dhcp_inform, dhcp_nak, dhcp_offer, +## dhcp_release and dhcp_request and is thus similarly deprecated +## itself. Use :bro:see:`dhcp_message` instead. +## +## .. bro:see:: dhcp_message dhcp_ack dhcp_decline dhcp_discover +## dhcp_inform dhcp_nak dhcp_offer dhcp_release dhcp_request +type dhcp_msg: record { + op: count; ##< Message OP code. 1 = BOOTREQUEST, 2 = BOOTREPLY + m_type: count; ##< The type of DHCP message. + xid: count; ##< Transaction ID of a DHCP session. + h_addr: string; ##< Hardware address of the client. + ciaddr: addr; ##< Original IP address of the client. + yiaddr: addr; ##< IP address assigned to the client. +}; + +## A list of router addresses offered by a DHCP server. +## +## .. note:: This type is included to support the deprecated events dhcp_ack +## and dhcp_offer and is thus similarly deprecated +## itself. Use :bro:see:`dhcp_message` instead. +## +## .. bro:see:: dhcp_message dhcp_ack dhcp_offer +type dhcp_router_list: table[count] of addr; + +## Generated for DHCP messages of type *DHCPDISCOVER* (client broadcast to locate +## available servers). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## req_addr: The specific address requested by the client. +## +## host_name: The value of the host name option, if specified by the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_decline dhcp_ack dhcp_nak dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_discover: event(c: connection, msg: dhcp_msg, req_addr: addr, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPOFFER* (server to client in response +## to DHCPDISCOVER with offer of configuration parameters). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## mask: The subnet mask specified by the message. +## +## router: The list of routers specified by the message. +## +## lease: The least interval specified by the message. +## +## serv_addr: The server address specified by the message. +## +## host_name: Optional host name value. May differ from the host name requested +## from the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_request dhcp_decline +## dhcp_ack dhcp_nak dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_offer: event(c: connection, msg: dhcp_msg, mask: addr, router: dhcp_router_list, lease: interval, serv_addr: addr, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPREQUEST* (Client message to servers either +## (a) requesting offered parameters from one server and implicitly declining offers +## from all others, (b) confirming correctness of previously allocated address after, +## e.g., system reboot, or (c) extending the lease on a particular network address.) +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## req_addr: The client address specified by the message. +## +## serv_addr: The server address specified by the message. +## +## host_name: The value of the host name option, if specified by the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_decline +## dhcp_ack dhcp_nak dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_request: event(c: connection, msg: dhcp_msg, req_addr: addr, serv_addr: addr, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPDECLINE* (Client to server indicating +## network address is already in use). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## host_name: Optional host name value. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_ack dhcp_nak dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_decline: event(c: connection, msg: dhcp_msg, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPACK* (Server to client with configuration +## parameters, including committed network address). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## mask: The subnet mask specified by the message. +## +## router: The list of routers specified by the message. +## +## lease: The least interval specified by the message. +## +## serv_addr: The server address specified by the message. +## +## host_name: Optional host name value. May differ from the host name requested +## from the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_decline dhcp_nak dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +global dhcp_ack: event(c: connection, msg: dhcp_msg, mask: addr, router: dhcp_router_list, lease: interval, serv_addr: addr, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPNAK* (Server to client indicating client's +## notion of network address is incorrect (e.g., client has moved to new subnet) or +## client's lease has expired). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## host_name: Optional host name value. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_decline dhcp_ack dhcp_release dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_nak: event(c: connection, msg: dhcp_msg, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPRELEASE* (Client to server relinquishing +## network address and cancelling remaining lease). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## host_name: The value of the host name option, if specified by the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_decline dhcp_ack dhcp_nak dhcp_inform +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +global dhcp_release: event(c: connection, msg: dhcp_msg, host_name: string) &deprecated; + +## Generated for DHCP messages of type *DHCPINFORM* (Client to server, asking only for +## local configuration parameters; client already has externally configured network +## address). +## +## c: The connection record describing the underlying UDP flow. +## +## msg: The parsed type-independent part of the DHCP message. +## +## host_name: The value of the host name option, if specified by the client. +## +## .. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request +## dhcp_decline dhcp_ack dhcp_nak dhcp_release +## +## .. note:: This event has been deprecated, and will be removed in the next version. +## Use dhcp_message instead. +## +## .. note:: Bro does not support broadcast packets (as used by the DHCP +## protocol). It treats broadcast addresses just like any other and +## associates packets into transport-level flows in the same way as usual. +## +global dhcp_inform: event(c: connection, msg: dhcp_msg, host_name: string) &deprecated; + +event dhcp_message(c: connection, is_orig: bool, msg: DHCP::Msg, options: DHCP::Options) + { + local old_msg: dhcp_msg = [$op=msg$op, $m_type=msg$m_type, $xid=msg$xid, + $h_addr=msg$chaddr, $ciaddr=msg$ciaddr, $yiaddr=msg$yiaddr]; + + local routers = dhcp_router_list(); + + if ( options?$routers ) + for ( i in options$routers ) + routers[|routers|] = options$routers[i]; + + # These fields are technically optional, but aren't listed as such in the event. + # We give it some defaults in order to suppress errors. + local ar = ( options?$addr_request ) ? options$addr_request : 0.0.0.0; + local hn = ( options?$host_name ) ? options$host_name : ""; + local le = ( options?$lease ) ? options$lease : 0 secs; + local sm = ( options?$subnet_mask ) ? options$subnet_mask : 255.255.255.255; + local sa = ( options?$serv_addr ) ? options$serv_addr : 0.0.0.0; + + switch ( DHCP::message_types[msg$m_type] ) { + case "DISCOVER": + event dhcp_discover(c, old_msg, ar, hn); + break; + case "OFFER": + event dhcp_offer(c, old_msg, sm, routers, le, sa, hn); + break; + case "REQUEST": + event dhcp_request(c, old_msg, ar, sa, hn); + break; + case "DECLINE": + event dhcp_decline(c, old_msg, hn); + break; + case "ACK": + event dhcp_ack(c, old_msg, sm, routers, le, sa, hn); + break; + case "NAK": + event dhcp_nak(c, old_msg, hn); + break; + case "RELEASE": + event dhcp_release(c, old_msg, hn); + break; + case "INFORM": + event dhcp_inform(c, old_msg, hn); + break; + default: + # This isn't a weird, it's just a DHCP message type the old scripts don't handle + break; + } + } diff --git a/scripts/test-all-policy.bro b/scripts/test-all-policy.bro index 7bdd2d4997..9ccfdaa670 100644 --- a/scripts/test-all-policy.bro +++ b/scripts/test-all-policy.bro @@ -60,6 +60,7 @@ @load protocols/conn/mac-logging.bro @load protocols/conn/vlan-logging.bro @load protocols/conn/weirds.bro +#@load protocols/dhcp/deprecated_events.bro @load protocols/dhcp/msg-orig.bro @load protocols/dhcp/software.bro @load protocols/dhcp/sub-opts.bro diff --git a/testing/btest/Baseline/coverage.bare-mode-errors/errors b/testing/btest/Baseline/coverage.bare-mode-errors/errors index e69de29bb2..8664c8a4d1 100644 --- a/testing/btest/Baseline/coverage.bare-mode-errors/errors +++ b/testing/btest/Baseline/coverage.bare-mode-errors/errors @@ -0,0 +1,16 @@ +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 245: deprecated (dhcp_discover) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 248: deprecated (dhcp_offer) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 251: deprecated (dhcp_request) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 254: deprecated (dhcp_decline) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 257: deprecated (dhcp_ack) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 260: deprecated (dhcp_nak) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 263: deprecated (dhcp_release) +warning in /home/jon/projects/bro/bro/testing/btest/../../scripts/policy/protocols/dhcp/deprecated_events.bro, line 266: deprecated (dhcp_inform) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 245: deprecated (dhcp_discover) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 248: deprecated (dhcp_offer) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 251: deprecated (dhcp_request) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 254: deprecated (dhcp_decline) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 257: deprecated (dhcp_ack) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 260: deprecated (dhcp_nak) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 263: deprecated (dhcp_release) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 266: deprecated (dhcp_inform) diff --git a/testing/btest/Baseline/doc.broxygen.all_scripts/.stderr b/testing/btest/Baseline/doc.broxygen.all_scripts/.stderr index 2bc5465045..34c0d82da2 100644 --- a/testing/btest/Baseline/doc.broxygen.all_scripts/.stderr +++ b/testing/btest/Baseline/doc.broxygen.all_scripts/.stderr @@ -1,2 +1,10 @@ +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 245: deprecated (dhcp_discover) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 248: deprecated (dhcp_offer) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 251: deprecated (dhcp_request) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 254: deprecated (dhcp_decline) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 257: deprecated (dhcp_ack) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 260: deprecated (dhcp_nak) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 263: deprecated (dhcp_release) +warning in /home/jon/projects/bro/bro/scripts/policy/protocols/dhcp/deprecated_events.bro, line 266: deprecated (dhcp_inform) error in /home/jon/projects/bro/bro/scripts/policy/frameworks/control/controller.bro, line 22: The '' control command is unknown. , line 1: received termination signal diff --git a/testing/btest/coverage/bare-mode-errors.test b/testing/btest/coverage/bare-mode-errors.test index 27e10373ea..24f3aced9d 100644 --- a/testing/btest/coverage/bare-mode-errors.test +++ b/testing/btest/coverage/bare-mode-errors.test @@ -6,4 +6,4 @@ # # @TEST-EXEC: test -d $DIST/scripts # @TEST-EXEC: for script in `find $DIST/scripts/ -name \*\.bro`; do bro -b --parse-only $script >>errors 2>&1; done -# @TEST-EXEC: btest-diff errors +# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff errors