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.
Namespaces: | GLOBAL, Notice |
---|---|
Source File: | /scripts/base/frameworks/notice/main.bro |
Notice::alarmed_types: set &redef | Alarmed notice types. |
Notice::default_suppression_interval: interval &redef | The notice framework is able to do automatic notice suppression by utilizing the identifier field in Notice::Info records. |
Notice::emailed_types: set &redef | Emailed notice types. |
Notice::ignored_types: set &redef | Ignored notice types. |
Notice::mail_dest: string &redef | Email address to send notices with the Notice::ACTION_EMAIL action or to send bulk alarm logs on rotation with Notice::ACTION_ALARM. |
Notice::mail_from: string &redef | Address that emails will be from. |
Notice::mail_subject_prefix: string &redef | Text string prefixed to the subject of all emails sent out. |
Notice::max_email_delay: interval &redef | The maximum amount of time a plugin can delay email from being sent. |
Notice::not_suppressed_types: set &redef | Types that should be suppressed for the default suppression interval. |
Notice::reply_to: string &redef | Reply-to address used in outbound email. |
Notice::sendmail: string &redef | Local system sendmail program. |
Notice::type_suppression_intervals: table &redef | This table can be used as a shorthand way to modify suppression intervals for entire notice types. |
Notice::Action: enum | These are values representing actions that can be taken with notices. |
Notice::ActionSet: set | Type that represents a set of actions. |
Notice::FileInfo: record | Contains a portion of fa_file that’s also contained in Notice::Info. |
Notice::Info: record | The record type that is used for representing and logging notices. |
Notice::Type: enum | 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. |
Notice::begin_suppression: event | This event is generated when a notice begins to be suppressed. |
Notice::log_notice: event | This event can be handled to access the Notice::Info record as it is sent on to the logging framework. |
Notice::suppressed: event | This event is generated on each occurrence of an event being suppressed. |
Notice::notice: hook | This is the event that is called as the entry point to the notice framework by the global NOTICE function. |
Notice::policy: hook | The hook to modify notice handling. |
NOTICE: function | This is the entry point in the global namespace for the notice framework. |
Notice::create_file_info: function | Creates a record containing a subset of a full fa_file record. |
Notice::email_headers: function | Constructs mail headers to which an email body can be appended for sending with sendmail. |
Notice::email_notice_to: function | Call this function to send a notice in an email. |
Notice::internal_NOTICE: function | This is an internal wrapper for the global NOTICE function; disregard. |
Notice::is_being_suppressed: function | A function to determine if an event is supposed to be suppressed. |
Notice::log_mailing_postprocessor: function | A log postprocessing function that implements emailing the contents of a log upon rotation to any configured Notice::mail_dest. |
Notice::populate_file_info: function | Populates file-related fields in a notice info record. |
Notice::populate_file_info2: function | Populates file-related fields in a notice info record. |
Type : | set [Notice::Type] |
---|---|
Attributes : | &redef |
Default : | {} |
Alarmed notice types.
Type : | interval |
---|---|
Attributes : | &redef |
Default : | 1.0 hr |
The notice framework is able to do automatic notice suppression by utilizing the identifier field in Notice::Info records. Set this to “0secs” to completely disable automated notice suppression.
Type : | set [Notice::Type] |
---|---|
Attributes : | &redef |
Default : | {} |
Emailed notice types.
Type : | set [Notice::Type] |
---|---|
Attributes : | &redef |
Default : | {} |
Ignored notice types.
Type : | string |
---|---|
Attributes : | &redef |
Default : | "" |
Email address to send notices with the Notice::ACTION_EMAIL action or to send bulk alarm logs on rotation with Notice::ACTION_ALARM.
Note that this is overridden by the BroControl MailTo option.
Type : | string |
---|---|
Attributes : | &redef |
Default : | "Big Brother <bro@localhost>" |
Address that emails will be from.
Note that this is overridden by the BroControl MailFrom option.
Type : | string |
---|---|
Attributes : | &redef |
Default : | "[Bro]" |
Text string prefixed to the subject of all emails sent out.
Note that this is overridden by the BroControl MailSubjectPrefix option.
Type : | interval |
---|---|
Attributes : | &redef |
Default : | 15.0 secs |
The maximum amount of time a plugin can delay email from being sent.
Type : | set [Notice::Type] |
---|---|
Attributes : | &redef |
Default : | {} |
Types that should be suppressed for the default suppression interval.
Type : | string |
---|---|
Attributes : | &redef |
Default : | "" |
Reply-to address used in outbound email.
Type : | string |
---|---|
Attributes : | &redef |
Default : | "/usr/sbin/sendmail" |
Local system sendmail program.
Note that this is overridden by the BroControl SendMail option.
Type : | table [Notice::Type] of interval |
---|---|
Attributes : | &redef |
Default : | {} |
This table can be used as a shorthand way to modify suppression intervals for entire notice types.
Type : |
|
---|
These are values representing actions that can be taken with notices.
Type : | set [Notice::Action] |
---|
Type that represents a set of actions.
Type : |
---|
Contains a portion of fa_file that’s also contained in Notice::Info.
Type : |
|
---|
The record type that is used for representing and logging notices.
Type : |
|
---|
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.
Type : | event (ts: time, suppress_for: interval, note: Notice::Type, identifier: string) |
---|
This event is generated when a notice begins to be suppressed.
Ts : | time indicating then when the notice to be suppressed occured. |
---|---|
Suppress_for : | length of time that this notice should be suppressed. |
Note : | The Notice::Type of the notice. |
Identifier : | The identifier string of the notice that should be suppressed. |
Type : | event (rec: Notice::Info) |
---|
This event can be handled to access the Notice::Info record as it is sent on to the logging framework.
Rec : | The record containing notice data before it is logged. |
---|
Type : | event (n: Notice::Info) |
---|
This event is generated on each occurrence of an event being suppressed.
N : | The record containing notice data regarding the notice type being suppressed. |
---|
Type : | hook (n: Notice::Info) : bool |
---|
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.
N : | The record containing notice data. |
---|
Type : | hook (n: Notice::Info) : bool |
---|
The hook to modify notice handling.
Type : | function (n: Notice::Info) : void |
---|
This is the entry point in the global namespace for the notice framework.
Type : | function (f: fa_file) : Notice::FileInfo |
---|
Creates a record containing a subset of a full fa_file record.
F : | record containing metadata about a file. |
---|---|
Returns : | record containing a subset of fields copied from f. |
Type : | function (subject_desc: string, dest: string) : string |
---|
Constructs mail headers to which an email body can be appended for sending with sendmail.
Subject_desc : | a subject string to use for the mail. |
---|---|
Dest : | recipient string to use for the mail. |
Returns : | a string of mail headers to which an email body can be appended. |
Type : | function (n: Notice::Info, dest: string, extend: bool) : void |
---|
Call this function to send a notice in an email. It is already used by default with the built in Notice::ACTION_EMAIL and Notice::ACTION_PAGE actions.
N : | The record of notice data to email. |
---|---|
Dest : | The intended recipient of the notice email. |
Extend : | Whether to extend the email using the email_body_sections field of n. |
Type : | function (n: Notice::Info) : void |
---|
This is an internal wrapper for the global NOTICE function; disregard.
N : | The record of notice data. |
---|
Type : | function (n: Notice::Info) : bool |
---|
A function to determine if an event is supposed to be suppressed.
N : | The record containing the notice in question. |
---|
Type : | function (info: Log::RotationInfo) : bool |
---|
A log postprocessing function that implements emailing the contents of a log upon rotation to any configured Notice::mail_dest. The rotated log is removed upon being sent.
Info : | A record containing the rotated log file information. |
---|---|
Returns : | True. |
Type : | function (f: fa_file, n: Notice::Info) : void |
---|
Populates file-related fields in a notice info record.
F : | record containing metadata about a file. |
---|---|
N : | a notice record that needs file-related fields populated. |
Type : | function (fi: Notice::FileInfo, n: Notice::Info) : void |
---|
Populates file-related fields in a notice info record.
Fi : | record containing metadata about a file. |
---|---|
N : | a notice record that needs file-related fields populated. |