Navigation

The protocol-independent events that the C/C++ core of Bro can generate.

This is mostly events not related to a specific transport- or
application-layer protocol, but also includes a few that may be generated
by more than one protocols analyzer (like events generated by both UDP and
TCP analysis.)

Generated when an operating system has been fingerprinted. Bro uses p0f to fingerprint endpoints passively,
and it raises this event for each system identified. The p0f fingerprints are
defined by passive_fingerprint_file.

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.

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.

When a bro_init handler executes, Bro has not yet seen any input
packets and therefore 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.

Generated when a TCP connection terminated, passing on statistics about the
two endpoints. This event is always generated when Bro flushes the internal
connection state, independent of how a connection terminates.

Generated for unexpected activity related to a specific connection. When
Bro’s packet analysis encounters activity that does not conform to a
protocol’s specification, it raises one of the *_weird events to report
that. This event is raised if the activity is tied directly to a specific
connection.

Name:

A unique name for the specific type of “weird” situation. Bro’s default
scripts use this name in filtering policies that specify which
“weirds” are worth reporting.

“Weird” activity is much more common in real-world network traffic
than one would intuitively expect. While in principle, any protocol
violation could be an attack attempt, it’s much more likely that an
endpoint’s implementation interprets an RFC quite liberally.

Generated for a new connection received from the communication subsystem.
Remote peers can inject packets into Bro’s packet loop, for example via
Broccoli. The communication system
raises this event with the first packet of a connection coming in this way.

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
script-level cleanup that needs to be performed for every connection. This
event is generated not only for TCP sessions but also for UDP and ICMP
flows.

Generated when a TCP connection timed out. This event is raised when
no activity was seen for an interval of at least
tcp_connection_linger, and either one endpoint has already
closed the connection or one side never became active.

The precise semantics of this event can be unintuitive as it only
covers a subset of cases where a connection times out. Often, handling
connection_state_remove is the better option. That one will be
generated reliably when an interval of tcp_inactivity_timeout has
passed without any activity seen (but also for all other ways a
connection may terminate).

Generated when Bro detects a gap in a reassembled TCP payload stream. This
event is raised when Bro, while reassembling a payload stream, determines
that a chunk of payload is missing (e.g., because the responder has already
acknowledged it, even though Bro didn’t see it).

C:

The connection.

Is_orig:

True if the gap is on the originator’s side.

Seq:

The sequence number where the gap starts.

Length:

The number of bytes missing.

Note

Content gaps tend to occur occasionally for various reasons, including
broken TCP stacks. If, however, one finds lots of them, that typically
means that there is a problem with the monitoring infrastructure such as
a tap dropping packets, split routing on the path, or reordering at the
tap.

Generated when an internal DNS lookup produced a different result than in
the past. Bro keeps an internal DNS cache for host names and IP addresses
it has already resolved. This event is generated when a subsequent lookup
returns a different answer than we have stored in the cache.

Dm:

A record describing the new resolver result.

Old_addrs:

Addresses that used to be part of the returned set for the query
described by dm, but are not anymore.

New_addrs:

Addresses that were not part of the returned set for the query
described by dm, but now are.

Generated when an internal DNS lookup returned zero answers even though it
had succeeded in the past. Bro keeps an internal DNS cache for host names
and IP addresses it has already resolved. This event is generated when
on a subsequent lookup we receive an answer that is empty even
though we have already stored a result in the cache.

Generated when an internal DNS lookup succeeded but an earlier attempt
did not. Bro keeps an internal DNS cache for host names and IP
addresses it has already resolved. This event is generated when a subsequent
lookup produces an answer for a query that was marked as failed in the cache.

Generated when an internal DNS lookup got no answer even though it had
succeeded in the past. Bro keeps an internal DNS cache for host names and IP
addresses it has already resolved. This event is generated when a
subsequent lookup does not produce an answer even though we have
already stored a result in the cache.

Generated when an internal DNS lookup produces the same result as last time.
Bro keeps an internal DNS cache for host names and IP addresses it has
already resolved. This event is generated when a subsequent lookup returns
the same result as stored in the cache.

Dm:

A record describing the new resolver result (which matches the old one).

Provide all metadata that has been inferred about a particular file
from inspection of the initial content that been seen at the beginning
of the file. The analysis can be augmented at this time via
Files::add_analyzer. The amount of data fed into the file
sniffing can be increased or decreased by changing either
default_file_bof_buffer_size or the bof_buffer_size field
in an fa_file record. The event will be raised even if content inspection
has been unable to infer any metadata, in which case the fields in meta
will be left all unset.

Generated after a call to send_state when all data has been
successfully sent to the remote side. While this event is
intended primarily for use by Bro’s communication framework, it can also
trigger additional code if helpful.

Generated for unexpected activity related to a pair of hosts, but independent
of a specific connection. When Bro’s packet analysis encounters activity
that does not conform to a protocol’s specification, it raises one of
the *_weird events to report that. This event is raised if the activity
is related to a pair of hosts, yet not to a specific connection between
them.

Name:

A unique name for the specific type of “weird” situation. Bro’s default
scripts use this name in filtering policies that specify which
“weirds” are worth reporting.

“Weird” activity is much more common in real-world network traffic
than one would intuitively expect. While in principle, any protocol
violation could be an attack attempt, it’s much more likely that an
endpoint’s implementation interprets an RFC quite liberally.

This event is handled to provide feedback to the file analysis framework
about how to identify the logical “file” to which some data/input
belongs. All incoming data to the framework is buffered, and depends
on a handler for this event to return a string value that uniquely
identifies a file. Among all handlers of this event, the last one to
call set_file_handle will “win”.

Generated regularly for the purpose of profiling Bro’s processing. This event
is raised for every load_sample_freq packet. For these packets,
Bro records script-level functions executed during their processing as well
as further internal locations. By sampling the processing in this form, one
can understand where Bro spends its time.

Samples:

A set with functions and locations seen during the processing of
the sampled packet.

CPU:

The CPU time spent on processing the sampled packet.

Dmem:

The difference in memory usage caused by processing the sampled packet.

Generated for unexpected activity that is not tied to a specific connection
or pair of hosts. When Bro’s packet analysis encounters activity that
does not conform to a protocol’s specification, it raises one of the
*_weird events to report that. This event is raised if the activity is
not tied directly to a specific connection or pair of hosts.

Name:

A unique name for the specific type of “weird” situation. Bro’s default
scripts use this name in filtering policies that specify which
“weirds” are worth reporting.

“Weird” activity is much more common in real-world network traffic
than one would intuitively expect. While in principle, any protocol
violation could be an attack attempt, it’s much more likely that an
endpoint’s implementation interprets an RFC quite liberally.

Generated for every new connection. This 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.

Generated for all packets that make it into Bro’s connection processing. In
contrast to raw_packet this filters out some more packets that don’t
pass certain sanity checks.

This is a very low-level and expensive event that should be avoided when at all
possible. It’s usually infeasible to handle when processing even medium volumes
of traffic in real-time. That said, if you work from a trace and want to do some
packet-level analysis, it may come in handy.

Generated for every packet that has a non-empty transport-layer payload.
This is a very low-level and expensive event that should be avoided when
at all possible. It’s usually infeasible to handle when processing even
medium volumes of traffic in real-time. It’s even worse than
new_packet. That said, if you work from a trace and want to
do some packet-level analysis, it may come in handy.

Generated when a protocol analyzer confirms that a connection is indeed
using that protocol. Bro’s dynamic protocol detection heuristically activates
analyzers as soon as it believes a connection could be using a particular
protocol. It is then left to the corresponding analyzer to verify whether
that is indeed the case; if so, this event will be generated.

C:

The connection.

Atype:

The type of the analyzer confirming that its protocol is in
use. The value is one of the Analyzer::ANALYZER_* constants. For example,
Analyzer::ANALYZER_HTTP means the HTTP analyzer determined that it’s indeed
parsing an HTTP connection.

Aid:

A unique integer ID identifying the specific instance of the
analyzer atype that is analyzing the connection c. The ID can
be used to reference the analyzer when using builtin functions like
disable_analyzer.

Generated when a protocol analyzer determines that a connection it is parsing
is not conforming to the protocol it expects. Bro’s dynamic protocol
detection heuristically activates analyzers as soon as it believes a
connection could be using a particular protocol. It is then left to the
corresponding analyzer to verify whether that is indeed the case; if not,
the analyzer will trigger this event.

C:

The connection.

Atype:

The type of the analyzer confirming that its protocol is in
use. The value is one of the Analyzer::ANALYZER_* constants. For example,
Analyzer::ANALYZER_HTTP means the HTTP analyzer determined that it’s indeed
parsing an HTTP connection.

Aid:

A unique integer ID identifying the specific instance of the
analyzer atype that is analyzing the connection c. The ID can
be used to reference the analyzer when using builtin functions like
disable_analyzer.

Bro’s default scripts use this event to disable an analyzer via
disable_analyzer if it’s parsing the wrong protocol. That’s
however a script-level decision and not done automatically by the event
engine.

Generated for every packet Bro sees that have a valid link-layer header. This
is a very very low-level and expensive event that should be avoided when at all
possible. It’s usually infeasible to handle when processing even medium volumes
of traffic in real-time. That said, if you work from a trace and want to do some
packet-level analysis, it may come in handy.

Generated when a remote connection’s initial handshake has been completed.
This event is intended primarily for use by Bro’s communication framework,
but it can also trigger additional code if helpful.

Generated for communication log messages. While this event is
intended primarily for use by Bro’s communication framework, it can also
trigger additional code if helpful. This event is equivalent to
remote_log except the message is with respect to a certain peer.

Generated when a remote peer has answered to our ping. This event is part of
Bro’s infrastructure for measuring communication latency. One can send a ping
by calling send_ping and when a corresponding reply is received,
this event will be raised.

P:

The peer sending us the pong.

Seq:

The sequence number passed to the original send_ping call.
The number is sent back by the peer in its response.

D1:

The time interval between sending the ping and receiving the pong. This
is the latency of the complete path.

D2:

The time interval between sending out the ping to the network and its
reception at the peer. This is the network latency.

D3:

The time interval between when the peer’s child process received the
ping and when its parent process sent the pong. This is the
processing latency at the peer.

Generated if state synchronization detects an inconsistency. While this
event is intended primarily for use by Bro’s communication framework, it can
also trigger additional code if helpful. This event is only raised if
remote_check_sync_consistency is false.

Operation:

The textual description of the state operation performed.

Id:

The name of the Bro script identifier that was operated on.

Expected_old:

A textual representation of the value of id that was
expected to be found before the operation was carried out.

Real_old:

A textual representation of the value of id that was actually
found before the operation was carried out. The difference between
real_old and expected_old is the inconsistency being reported.

Generated when Bro detects a TCP retransmission inconsistency. When
reassembling a TCP stream, Bro buffers all payload until it sees the
responder acking it. If during that time, the sender resends a chunk of
payload but with different content than originally, this event will be
raised. In addition, if tcp_max_old_segments is larger than zero,
mismatches with that older still-buffered data will likewise trigger the event.

C:

The connection showing the inconsistency.

T1:

The original payload.

T2:

The new payload.

Tcp_flags:

A string with the TCP flags of the packet triggering the
inconsistency. In the string, each character corresponds to one
set flag, as follows: S -> SYN; F -> FIN; R -> RST;
A -> ACK; P -> PUSH. This string will not always be set,
only if the information is available; it’s “best effort”.

Generated when a connection is seen that is marked as being expected.
The function Analyzer::schedule_analyzer tells Bro to expect a
particular connection to come up, and which analyzer to associate with it.
Once the first packet of such a connection is indeed seen, this event is
raised.

C:

The connection.

A:

The analyzer that was scheduled for the connection with the
Analyzer::schedule_analyzer call. When the event is raised, that
analyzer will already have been activated to process the connection. The
count is one of the ANALYZER_* constants, e.g., ANALYZER_HTTP.

Generated when a signature matches. Bro’s signature engine provides
high-performance pattern matching separately from the normal script
processing. If a signature with an event action matches, this event is
raised.

See the user manual for more information
about Bro’s signature engine.

State:

Context about the match, including which signatures triggered the
event and the connection for which the match was found.

Msg:

The message passed to the event signature action.

Data:

The last chunk of input that triggered the match. Note that the
specifics here are not well-defined as Bro does not buffer any input.
If a match is split across packet boundaries, only the last chunk
triggering the match will be passed on to the event.

Generated when a protocol analyzer finds an identification of a software
used on a system but cannot parse it. This is a protocol-independent event
that is fed by different analyzers. For example, the HTTP analyzer reports
user-agent and server software by raising this event if it cannot parse them
directly (if it can software_version_found will be generated
instead).

C:

The connection.

Host:

The host running the reported software.

Descr:

The raw (unparsed) software identification string as extracted from
the protocol.

Generated when a protocol analyzer finds an identification of a software
used on a system. This is a protocol-independent event that is fed by
different analyzers. For example, the HTTP analyzer reports user-agent and
server software by raising this event. Different from
software_version_found and software_parse_error, this
event is always raised, independent of whether Bro can parse the version
string.

Generated when a protocol analyzer finds an identification of a software
used on a system. This is a protocol-independent event that is fed by
different analyzers. For example, the HTTP analyzer reports user-agent and
server software by raising this event, assuming it can parse it (if not,
software_parse_error will be generated instead).

C:

The connection.

Host:

The host running the reported software.

S:

A description of the software found.

Descr:

The raw (unparsed) software identification string as extracted from
the protocol.

Generated for a connection whose tunneling has changed. This could
be from a previously seen connection now being encapsulated in a tunnel,
or from the outer encapsulation changing. Note that connection c’s
tunnel field is NOT automatically/internally assigned to the new
encapsulation value of e after this event is raised. If the desired
behavior is to track the latest tunnel encapsulation per-connection,
then a handler of this event should assign e to c$tunnel (which Bro’s
default scripts are doing).

Generated when a UDP session for a supported protocol has finished. Some of
Bro’s application-layer UDP analyzers flag the end of a session by raising
this event. Currently, the analyzers for DNS, NTP, Netbios, Syslog, AYIYA,
Teredo, and GTPv1 support this.