Navigation

base/frameworks/notice/main.bro

GLOBAL

Notice

This is the notice framework which enables Bro to “notice” things which
are odd or potentially bad. Decisions of the meaning of various notices
need to be done per site because Bro does not ship with assumptions about
what is bad activity for sites. More extensive documentation about using
the notice framework can be found in Notice Framework.

Frequently files can be “described” to give a bit more
context. This field will typically be automatically filled
out from an fa_file record. For example, if a notice was
related to a file over HTTP, the URL of the request would
be shown.

By adding chunks of text into this element, other scripts
can expand on notices that are being emailed. The normal
way to add text is to extend the vector by handling the
Notice::notice event and modifying the notice in
place.

Adding a string “token” to this set will cause the notice
framework’s built-in emailing functionality to delay sending
the email until either the token has been removed or the
email has been delayed for Notice::max_email_delay.

This field is to be provided when a notice is generated for
the purpose of deduplicating notices. The identifier string
should be unique for a single instance of the notice. This
field should be filled out in almost all cases when
generating notices to define when a notice is conceptually
a duplicate of a previous notice.

For example, an SSL certificate that is going to expire soon
should always have the same identifier no matter the client
IP address that connected and resulted in the certificate
being exposed. In this case, the resp_h, resp_p, and hash
of the certificate would be used to create this value. The
hash of the cert is included because servers can return
multiple certificates on the same port.

Another example might be a host downloading a file which
triggered a notice because the MD5 sum of the file it
downloaded was known by some set of intelligence. In that
case, the orig_h (client) and MD5 sum would be used in this
field to dedup because if the same file is downloaded over
and over again you really only want to know about it a
single time. This makes it possible to send those notices
to email without worrying so much about sending thousands
of emails.

For certain software, a version changing may matter. In that
case, this notice will be generated. Software that matters
if the version changes can be configured with the
Software::interesting_version_changes variable.

Port scans detect that an attacking host appears to be
scanning a single victim host on several ports. This notice
is generated when an attacking host attempts to connect to
Scan::port_scan_threshold
unique ports on a single host over the previous
Scan::port_scan_interval time range.

Omitting comments is fine, and so is mixing ## and ##<, but
it’s probably best to use only one style consistently.

Scripts creating new notices need to redef this enum to add their
own specific notice types which would then get used when they call
the NOTICE function. The convention is to give a general
category along with the specific notice separating words with
underscores and using leading capitals on each word except for
abbreviations which are kept in all capitals. For example,
SSH::Password_Guessing is for hosts that have crossed a threshold of
failed SSH logins.

Hooks

This is the event that is called as the entry point to the
notice framework by the global NOTICE function. By the
time this event is generated, default values have already been
filled out in the Notice::Info record and the notice
policy has also been applied.