From fa9125f61a113f7a00e8e6ac716dc5ad48bc8e39 Mon Sep 17 00:00:00 2001 From: Robin Sommer Date: Thu, 17 Nov 2011 16:59:53 -0800 Subject: [PATCH] Adding some first doc strings to event.bif. Still trying to find the right style. --- src/event.bif | 188 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 186 insertions(+), 2 deletions(-) diff --git a/src/event.bif b/src/event.bif index d953ac78fe..1da2420083 100644 --- a/src/event.bif +++ b/src/event.bif @@ -1,35 +1,219 @@ +# Documentation conventions: +# +# - Short initial sentence (which doesn't need to be a sentence), starting +# with "Generated ..." +# +# - Use past tense for activity that has already occured. + +## Generated at Bro initialization time. The event engine generates this +## event just before normal input processing begins. It can be used to execute +## one-time initialization code at startup. At the time a handler runs, Bro will +## have executed any global initializations and statements. +## +## .. note:: When a ``bro_init`` handler executes, Bro has not yet seen any +## input packets and therefore :bro:id:`network_time` is not initialized yet. An +## artifact of that is that any timer installed in a ``bro_init`` handler will fire +## immediately with the first packet. The standard way to work around that is to +## ignore the first time the timer fires and immediately reschedule. +## +## see:: bro_done event bro_init%(%); + +## Generated at Bro termination time. The event engine generates this event when +## Bro is about to terminate, either due to having exhausted reading its input +## trace file(s), receiving a termination signal, or because Bro was run without +## a network input source and has finished executing any global statements. +## This event is generated after :bro:id:`net_done`, which gets only raised when +## processing network traffic. +## +## .. note:: If Bro terminates due to an invocation of :bro:id:`exit`, then this +## event is not generated. +## +## see:: net_done bro_init event bro_done%(%); +# TODO. event dns_mapping_valid%(dm: dns_mapping%); event dns_mapping_unverified%(dm: dns_mapping%); event dns_mapping_new_name%(dm: dns_mapping%); event dns_mapping_lost_name%(dm: dns_mapping%); -event dns_mapping_name_changed%(old_dm: dns_mapping, new_dm: dns_mapping%); +# event dns_mapping_name_changed%(old_dm: dns_mapping, new_dm: dns_mapping%); event dns_mapping_altered%(dm: dns_mapping, old_addrs: addr_set, new_addrs: addr_set%); +## Generated for every new connection. The event is raised with the first packet +## of a previously unknown connection. Bro uses a flow-based definition of +## "connection" here that includes not only TCP sessions but also UDP and ICMP +## flows. +## +## c: The connection. +## +## .. note:: Handling this event is potentially expensive. For example, during a +## SYN flooding attack, every spoofed SYN packet will lead to a new new_connection +## event. +## +## see:: *connection* event new_connection%(c: connection%); + +## Generated when reassembly starts for a TCP connection. The event is raised +## at the moment when Bro's TCP analyzer enables stream reassembly for a +## connection. +## +## c: The connection. +## +## see:: *connection* event new_connection_contents%(c: connection%); -event new_packet%(c: connection, p: pkt_hdr%); + +## Generated for an unsuccessful connection attempt. The event is raised when an +## originator unsuccessfully attempted to establish a connection. "Unsuccessful" +## is defined as at least :bro:id:`tcp_attempt_delay` seconds having elapsed since +## the originator first sent a connection establishment packet to the destination +## without seeing a reply. +## +## c: The connection. +## +## see:: connection_*, new_connection*, partial_connection. event connection_attempt%(c: connection%); + +## Generated for an established TCP connection. The event is raised when the +## initial 3-way TCP handshake has successfully finished for a connection. +## +## c: The connection. +## +## see:: *connection* event connection_established%(c: connection%); + +## Generated for a new active TCP connection if Bro did not see the initial +## handshake. The event is raised when Bro has observed traffic from each endpoint, +## but the activity did not begin with the usual connection establishment. +## +## c: The connection. +## +## see:: *connection* event partial_connection%(c: connection%); + +## TODO. +## +## see:: *connection* event connection_partial_close%(c: connection%); + +## Generated for a TCP connection that finished normally. The event is raised +## when a regular FIN handshake from both endpoints was observed. +## +## c: The connection. +## +## see:: *connection* event connection_finished%(c: connection%); + +## TODO. +## +## see:: *connection* event connection_half_finished%(c: connection%); + +## Generated for a rejected TCP connection. The event is raised when an originator +## attempted to setup a TCP connection but the responder replied with a RST packet +## denying it. +## +## c: The connection. +## +## .. note:: If the responder does not respond at all, :bro:id:`connection_attempt` +## is raised instead. If the responder initially accepts the connection but +## aborts it later, Bro first generates :bro:id:`connection_established` and then +## :bro:id:`connection_reset`. +## +## see:: *connection* event connection_rejected%(c: connection%); + +## Generated when an endpoint aborted a TCP connection. The event is raised +## when one endpoint of an established TCP connection aborted by sending a RST +## packet. +## +## c: The connection. +## +## see:: *connection* event connection_reset%(c: connection%); + +## TODO +## +## see:: *connection* event connection_pending%(c: connection%); + +## Generated when a connection's internal state is about to be removed from +## memory. Bro generates this event reliably once for every connection when it +## is about to delete the internal state. As such, the event is well-suited for +## scrip-level cleanup that needs to be performed for every connection. The +## ``connection_state_remove`` event is generated not only for TCP sessions but +## also for UDP and ICMP flows. +## +## c: The connection. +## +## see:: *connection* event connection_state_remove%(c: connection%); + +## Generated for a SYN packet. Bro raises this event for every SYN packet seen by +## its TCP analyzer. +## +## c: The connection. +## +## pkt: Information extracted from the SYN packet. +## +## .. note:: This event has quite low-level semantics and can potentially be +## expensive to generate. It should only be used if one really needs the +## specific information passed into the handler via the ``pkt`` argument. If +## not, handling one of the other ``connection_*`` events is typically the +## better approach. +## +## see:: *connection* event connection_SYN_packet%(c: connection, pkt: SYN_packet%); + +## Generated for the first ACK packet seen for a TCP connection from +## its *orginator*. +## +## c: The connection. +## +## pkt: Information extracted from the SYN packet. +## +## .. note:: This event has quite low-level semantics and should be used only +## rarely. +## +## see:: *connection* event connection_first_ACK%(c: connection%); + +## Generated when a TCP connection timed out. This event is raised when no activity +## was seen for an interval of at least :bro:id:`tcp_connection_linger`, and +## either one endpoint has already closed the connection or one side never +## never became active. +## +## c: The connection. +## +## .. note:: The precise semantics of this event can be unintuitive as it +## only covers a subset of cases where a connection times out. Often, handling +## :bro:id:`connection_state_remove` is the better option. That one will be +## generated reliably when an interval of ``tcp_inactivity_timeout`` has passed +## with out any activity seen (but also for all other ways a connection may +## terminate). +## +## see:: *connection* event connection_timeout%(c: connection%); + +## Generated when a connection 4-tuple is reused. The event is raised when Bro +## sees a new TCP session or UDP flow using a 4-tuple matching that of an earlier +## connection it still consideres active. +## +## c: The connection. +## +## see:: *connection* event connection_reused%(c: connection%); + + + event connection_status_update%(c: connection%); event connection_EOF%(c: connection, is_orig: bool%); event connection_external%(c: connection, tag: string%); + event expected_connection_seen%(c: connection, a: count%); +event new_packet%(c: connection, p: pkt_hdr%); + event protocol_confirmation%(c: connection, atype: count, aid: count%); event protocol_violation%(c: connection, atype: count, aid: count, reason: string%);