Add more notice framework documentation.

scripts/base/frameworks/notice/actions/email_admin.bro

@@ -1,3 +1,8 @@
+##! Adds a new notice action type which can be used to email notices
+##! to the administrators of a particular address space as set by
+##! :bro:id:`Site::local_admins` if the notice contains a source
+##! or destination address that lies within their space.
+
 @load ../main
 @load base/utils/site
 

scripts/base/frameworks/notice/actions/page.bro

@@ -1,3 +1,5 @@
+##! Allows configuration of a pager email address to which notices can be sent.
+
 @load ../main
 
 module Notice;

scripts/base/frameworks/notice/actions/pp-alarms.bro

@@ -1,6 +1,6 @@
-#! Notice extension that mails out a pretty-printed version of alarm.log
+##! Notice extension that mails out a pretty-printed version of alarm.log
-#! in regular intervals, formatted for better human readability. If activated,
+##! in regular intervals, formatted for better human readability. If activated,
-#! that replaces the default summary mail having the raw log output.
+##! that replaces the default summary mail having the raw log output.
 
 @load base/frameworks/cluster
 @load ../main
@@ -15,8 +15,8 @@ export {
 	## :bro:id:`Notice::mail_dest`.
 	const mail_dest_pretty_printed = "" &redef;
 
-        ## If an address from one of these networks is reported, we mark
+	## If an address from one of these networks is reported, we mark
-	## the entry with an addition quote symbol (i.e., ">"). Many MUAs
+	## the entry with an addition quote symbol (that is, ">"). Many MUAs
 	## then highlight such lines differently.
 	global flag_nets: set[subnet] &redef;
 

scripts/base/frameworks/notice/cluster.bro

@@ -1,4 +1,6 @@
-##! Implements notice functionality across clusters.
+##! Implements notice functionality across clusters.  Worker nodes
+##! will disable notice/alarm logging streams and forward notice
+##! events to the manager node for logging/processing.
 
 @load ./main
 @load base/frameworks/cluster
@@ -7,10 +9,15 @@ module Notice;
 
 export {
 	## This is the event used to transport notices on the cluster.
+	##
+	## n: The notice information to be sent to the cluster manager for
+	##    further processing.
 	global cluster_notice: event(n: Notice::Info);
 }
 
+## Manager can communicate notice suppression to workers.
 redef Cluster::manager2worker_events += /Notice::begin_suppression/;
+## Workers needs need ability to forward notices to manager.
 redef Cluster::worker2manager_events += /Notice::cluster_notice/;
 
 @if ( Cluster::local_node_type() != Cluster::MANAGER )

scripts/base/frameworks/notice/main.bro

@@ -2,8 +2,7 @@
 ##! 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 documetation about using
-##! the notice framework can be found in the documentation section of the
+##! the notice framework can be found in :doc:`/notice`.
-##! http://www.bro-ids.org/ website.
 
 module Notice;
 
@@ -21,10 +20,10 @@ export {
 	## 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
 	## :bro:id:`NOTICE` function.  The convention is to give a general category
-	## along with the specific notice separating words with underscores and using
+	## along with the specific notice separating words with underscores and
-	## leading capitals on each word except for abbreviations which are kept in
+	## using leading capitals on each word except for abbreviations which are
-	## all capitals.  For example, SSH::Login is for heuristically guessed 
+	## kept in all capitals.  For example, SSH::Login is for heuristically
-	## successful SSH logins.
+	## guessed successful SSH logins.
 	type Type: enum {
 		## Notice reporting a count of how often a notice occurred.
 		Tally,
@@ -49,22 +48,33 @@ export {
 	};
 	
 	## The notice framework is able to do automatic notice supression by 
-	## utilizing the $identifier field in :bro:type:`Info` records.
+	## utilizing the $identifier field in :bro:type:`Notice::Info` records.
 	## Set this to "0secs" to completely disable automated notice suppression.
 	const default_suppression_interval = 1hrs &redef;
 	
 	type Info: record {
+		## An absolute time indicating when the notice occurred, defaults
+		## to the current network time.
 		ts:             time           &log &optional;
+
+		## A connection UID which uniquely identifies the endpoints
+		## concerned with the notice.
 		uid:            string         &log &optional;
+
+		## A connection 4-tuple identifying the endpoints concerned with the
+		## notice.
 		id:             conn_id        &log &optional;
 		
-		## These are shorthand ways of giving the uid and id to a notice.  The
+		## A shorthand way of giving the uid and id to a notice.  The
 		## reference to the actual connection will be deleted after applying
 		## the notice policy.
 		conn:           connection     &optional;
+		## A shorthand way of giving the uid and id to a notice.  The
+		## reference to the actual connection will be deleted after applying
+		## the notice policy.
 		iconn:          icmp_conn      &optional;
 		
-		## The :bro:enum:`Notice::Type` of the notice.
+		## The type of the notice.
 		note:           Type           &log;
 		## The human readable message for the notice.
 		msg:            string         &log &optional;
@@ -141,8 +151,9 @@ export {
 	
 	## This is the record that defines the items that make up the notice policy.
 	type PolicyItem: record {
-		## This is the exact positional order in which the :bro:type:`PolicyItem`
+		## This is the exact positional order in which the
-		## records are checked.  This is set internally by the notice framework.
+		## :bro:type:`Notice::PolicyItem` records are checked.
+		## This is set internally by the notice framework.
 		position: count                            &log &optional;
 		## Define the priority for this check.  Items are checked in ordered
 		## from highest value (10) to lowest value (0).
@@ -163,8 +174,8 @@ export {
 		suppress_for: interval                     &log &optional;
 	};
 	
-	## This is the where the :bro:id:`Notice::policy` is defined.  All notice
+	## Defines a notice policy that is extensible on a per-site basis.
-	## processing is done through this variable.
+	## All notice processing is done through this variable.
 	const policy: set[PolicyItem] = {
 		[$pred(n: Notice::Info) = { return (n$note in Notice::ignored_types); },
 		 $halt=T, $priority = 9],
@@ -193,8 +204,9 @@ export {
 	
 	## Local system sendmail program.
 	const sendmail            = "/usr/sbin/sendmail" &redef;
-	## Email address to send notices with the :bro:enum:`ACTION_EMAIL` action
+	## Email address to send notices with the :bro:enum:`Notice::ACTION_EMAIL`
-	## or to send bulk alarm logs on rotation with :bro:enum:`ACTION_ALARM`.
+	## action or to send bulk alarm logs on rotation with
+	## :bro:enum:`Notice::ACTION_ALARM`.
 	const mail_dest           = ""                   &redef;
 	
 	## Address that emails will be from.
@@ -207,14 +219,20 @@ export {
 	## A log postprocessing function that implements emailing the contents
 	## of a log upon rotation to any configured :bro:id:`Notice::mail_dest`.
 	## The rotated log is removed upon being sent.
+	##
+	## info: A record containing the rotated log file information.
+	##
+	## Returns: True.
 	global log_mailing_postprocessor: function(info: Log::RotationInfo): bool;
 
 	## This is the event that is called as the entry point to the 
 	## notice framework by the global :bro:id:`NOTICE` function.  By the time 
 	## this event is generated, default values have already been filled out in
 	## the :bro:type:`Notice::Info` record and synchronous functions in the 
-	## :bro:id:`Notice:sync_functions` have already been called.  The notice
+	## :bro:id:`Notice::sync_functions` have already been called.  The notice
 	## policy has also been applied.
+	##
+	## n: The record containing notice data.
 	global notice: event(n: Info);
 
 	## This is a set of functions that provide a synchronous way for scripts 
@@ -231,30 +249,55 @@ export {
 	const sync_functions: set[function(n: Notice::Info)] = set() &redef;
 	
 	## This event is generated when a notice begins to be suppressed.
+	##
+	## n: The record containing notice data regarding the notice type
+	##    about to be suppressed.
 	global begin_suppression: event(n: Notice::Info);
+
 	## This event is generated on each occurence of an event being suppressed.
+	##
+	## n: The record containing notice data regarding the notice type
+	##    being suppressed.
 	global suppressed: event(n: Notice::Info);
+
 	## This event is generated when a notice stops being suppressed.
+	##
+	## n: The record containing notice data regarding the notice type
+	##    that was being suppressed.
 	global end_suppression: event(n: Notice::Info);
 	
 	## Call this function to send a notice in an email.  It is already used
-	## by default with the built in :bro:enum:`ACTION_EMAIL` and
+	## by default with the built in :bro:enum:`Notice::ACTION_EMAIL` and
-	## :bro:enum:`ACTION_PAGE` actions.
+	## :bro:enum:`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*.
 	global email_notice_to: function(n: Info, dest: string, extend: bool);
 
 	## 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
 	global email_headers: function(subject_desc: string, dest: string): string;
 	
-	## This event can be handled to access the :bro:type:`Info`
+	## This event can be handled to access the :bro:type:`Notice::Info`
 	## record as it is sent on to the logging framework.
+	##
+	## rec: The record containing notice data before it is logged.
 	global log_notice: event(rec: Info);
 	
-	## This is an internal wrapper for the global NOTICE function.  Please 
+	## This is an internal wrapper for the global :bro:id:`NOTICE` function;
 	## disregard.
+	##
+	## n: The record of notice data.
 	global internal_NOTICE: function(n: Notice::Info);
 }
 
@@ -410,7 +453,8 @@ event notice(n: Notice::Info) &priority=-5
 	}
 	
 ## This determines if a notice is being suppressed.  It is only used 
-## internally as part of the mechanics for the global NOTICE function.
+## internally as part of the mechanics for the global :bro:id:`NOTICE`
+## function.
 function is_being_suppressed(n: Notice::Info): bool
 	{
 	if ( n?$identifier && [n$note, n$identifier] in suppressing )

scripts/base/frameworks/notice/weird.bro

@@ -1,3 +1,12 @@
+##! This script provides a default set of actions to take for "weird activity"
+##! events generated from Bro's event engine.  Weird activity is defined as
+##! unusual or exceptional activity that can indicate malformed connections,
+##! traffic that doesn't conform to a particular protocol, malfunctioning
+##! or misconfigured hardware, or even an attacker attempting to avoid/confuse
+##! a sensor.  Without context, it's hard to judge whether a particular
+##! category of weird activity is interesting, but this script provides
+##! a starting point for the user.
+
 @load base/utils/conn-ids
 @load base/utils/site
 @load ./main
@@ -5,6 +14,7 @@
 module Weird;
 
 export {
+	## The weird logging stream identifier.
 	redef enum Log::ID += { LOG };
 	
 	redef enum Notice::Type += {
@@ -12,6 +22,7 @@ export {
 		Activity,
 	};
 	
+	## The record type which contains the column fields of the weird log.
 	type Info: record {
 		## The time when the weird occurred.
 		ts:     time    &log;
@@ -32,19 +43,32 @@ export {
 		peer:   string  &log &optional;
 	};
 
+	## Types of actions that may be taken when handling weird activity events.
 	type Action: enum {
+		## A dummy action indicating the user does not care what internal
+		## decision is made regarding a given type of weird.
 		ACTION_UNSPECIFIED,
+		## No action is to be taken.
 		ACTION_IGNORE,
+		## Log the weird event every time it occurs.
 		ACTION_LOG,
+		## Log the weird event only once.
 		ACTION_LOG_ONCE,
+		## Log the weird event once per connection.
 		ACTION_LOG_PER_CONN,
+		## Log the weird event once per originator host.
 		ACTION_LOG_PER_ORIG,
+		## Always generate a notice associated with the weird event.
 		ACTION_NOTICE, 
+		## Generate a notice associated with the weird event only once.
 		ACTION_NOTICE_ONCE,
+		## Generate a notice for the weird event once per connection.
 		ACTION_NOTICE_PER_CONN,
+		## Generate a notice for the weird event once per originator host.
 		ACTION_NOTICE_PER_ORIG, 
 	};
 
+	## A table specifying default/recommended actions per weird type.
 	const actions: table[string] of Action = {
 		["unsolicited_SYN_response"]            = ACTION_IGNORE,
 		["above_hole_data_without_any_acks"]    = ACTION_LOG,
@@ -201,7 +225,7 @@ export {
 		["fragment_overlap"]                    = ACTION_LOG_PER_ORIG,
 		["fragment_protocol_inconsistency"]     = ACTION_LOG,
 		["fragment_size_inconsistency"]         = ACTION_LOG_PER_ORIG,
-		## These do indeed happen!
+		# These do indeed happen!
 		["fragment_with_DF"]                    = ACTION_LOG,
 		["incompletely_captured_fragment"]      = ACTION_LOG,
 		["bad_IP_checksum"]                     = ACTION_LOG_PER_ORIG,
@@ -215,8 +239,8 @@ export {
 	## and weird name into this set.
 	const ignore_hosts: set[addr, string] &redef;
 
-	# But don't ignore these (for the weird file), it's handy keeping
+	## Don't ignore repeats for weirds in this set.  For example,
-	# track of clustered checksum errors.
+	## it's handy keeping track of clustered checksum errors.
 	const weird_do_not_ignore_repeats = {
 		"bad_IP_checksum", "bad_TCP_checksum", "bad_UDP_checksum",
 		"bad_ICMP_checksum",
@@ -236,7 +260,11 @@ export {
 	## A state set which tracks unique weirds solely by the name to reduce
 	## duplicate notices from being raised.
 	global did_notice: set[string, string] &create_expire=1day &redef;
-	
+
+	## Handlers of this event are invoked one per write to the weird
+	## logging stream before the data is actually written.
+	##
+	## rec: The weird columns about to be logged to the weird stream.
 	global log_weird: event(rec: Info);
 }