mirror of
https://github.com/zeek/zeek.git
synced 2025-10-10 18:48:20 +00:00
Adding some first doc strings to event.bif.
Still trying to find the right style.
This commit is contained in:
Robin Sommer
parent
5991eaa564
commit
fa9125f61a
1 changed files with 186 additions and 2 deletions
188
src/event.bif
188
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%);
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue