Add more signature framework documentation.

doc/signatures.rst

@@ -34,7 +34,7 @@ Let's look at an example signature first:
 
 This signature asks Bro to match the regular expression ``.*root`` on
 all TCP connections going to port 80. When the signature triggers, Bro
-will raise an event ``signature_match`` of the form:
+will raise an event :bro:id:`signature_match` of the form:
 
 .. code:: bro
 
@@ -45,20 +45,20 @@ triggered the match, ``msg`` is the string specified by the
 signature's event statement (``Found root!``), and data is the last
 piece of payload which triggered the pattern match.
 
-To turn such ``signature_match`` events into actual alarms, you can
+To turn such :bro:id:`signature_match` events into actual alarms, you can
-load Bro's ``signature.bro`` script. This script contains a default
+load Bro's :doc:`/scripts/base/frameworks/signatures/main` script.
-event handler that raises ``SensitiveSignature`` :doc:`Notices <notice>`
+This script contains a default event handler that raises
+:bro:enum:`Signatures::Sensitive_Signature` :doc:`Notices <notice>`
 (as well as others; see the beginning of the script).
 
 As signatures are independent of Bro's policy scripts, they are put
 into their own file(s). There are two ways to specify which files
 contain signatures: By using the ``-s`` flag when you invoke Bro, or
-by extending the Bro variable ``signatures_files`` using the ``+=``
+by extending the Bro variable :bro:id:`signature_files` using the ``+=``
 operator. If a signature file is given without a path, it is searched
 along the normal ``BROPATH``. The default extension of the file name
 is ``.sig``, and Bro appends that automatically when neccesary.
 
-
 Signature language
 ==================
 
@@ -90,7 +90,7 @@ one of ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``; and
 against. The following keywords are defined:
 
 ``src-ip``/``dst-ip <cmp> <address-list>``
-    Source and destination address, repectively. Addresses can be
+    Source and destination address, respectively. Addresses can be
     given as IP addresses or CIDR masks.
 
 ``src-port``/``dst-port`` ``<int-list>``
@@ -126,7 +126,7 @@ CIDR notation for netmasks and is translated into a corresponding
 bitmask applied to the packet's value prior to the comparison (similar
 to the optional ``& integer``).
 
-Putting all together, this is an example conditiation that is
+Putting all together, this is an example condition that is
 equivalent to ``dst- ip == 1.2.3.4/16, 5.6.7.8/24``:
 
 .. code:: bro-sig
@@ -134,7 +134,7 @@ equivalent to ``dst- ip == 1.2.3.4/16, 5.6.7.8/24``:
     header ip[16:4] == 1.2.3.4/16, 5.6.7.8/24
 
 Internally, the predefined header conditions are in fact just
-short-cuts and mappend into a generic condition.
+short-cuts and mapped into a generic condition.
 
 Content Conditions
 ~~~~~~~~~~~~~~~~~~
@@ -265,7 +265,7 @@ Actions define what to do if a signature matches. Currently, there are
 two actions defined:
 
 ``event <string>``
-    Raises a ``signature_match`` event. The event handler has the
+    Raises a :bro:id:`signature_match` event. The event handler has the
     following type:
 
     .. code:: bro
@@ -339,10 +339,10 @@ Things to keep in mind when writing signatures
   respectively. Generally, Bro follows `flex's regular expression
   syntax
   <http://www.gnu.org/software/flex/manual/html_chapter/flex_7.html>`_.
-  See the DPD signatures in ``policy/sigs/dpd.bro`` for some examples
+  See the DPD signatures in ``base/frameworks/dpd/dpd.sig`` for some examples
   of fairly complex payload patterns.
 
-* The data argument of the ``signature_match`` handler might not carry
+* The data argument of the :bro:id:`signature_match` handler might not carry
   the full text matched by the regular expression. Bro performs the
   matching incrementally as packets come in; when the signature
   eventually fires, it can only pass on the most recent chunk of data.

scripts/base/frameworks/signatures/main.bro

@@ -1,30 +1,36 @@
-##! Script level signature support.
+##! Script level signature support.  See the
+##! :doc:`signature documentation </signatures>` for more information about
+##! Bro's signature engine.
 
 @load base/frameworks/notice
 
 module Signatures;
 
 export {
+	## Add various signature-related notice types.
 	redef enum Notice::Type += {
-		## Generic for alarm-worthy
+		## Generic notice type for notice-worthy signature matches.
 		Sensitive_Signature,
 		## Host has triggered many signatures on the same host.  The number of 
-		## signatures is defined by the :bro:id:`vert_scan_thresholds` variable.
+		## signatures is defined by the
+		## :bro:id:`Signatures::vert_scan_thresholds` variable.
 		Multiple_Signatures,
-		## Host has triggered the same signature on multiple hosts as defined by the
+		## Host has triggered the same signature on multiple hosts as defined
-		## :bro:id:`horiz_scan_thresholds` variable.
+		## by the :bro:id:`Signatures::horiz_scan_thresholds` variable.
 		Multiple_Sig_Responders,
-		## The same signature has triggered multiple times for a host.  The number 
+		## The same signature has triggered multiple times for a host.  The
-		## of times the signature has be trigger is defined by the 
+		## number of times the signature has been triggered is defined by the 
-		## :bro:id:`count_thresholds` variable.  To generate this notice, the
+		## :bro:id:`Signatures::count_thresholds` variable. To generate this
-		## :bro:enum:`SIG_COUNT_PER_RESP` action must be set for the signature.
+		## notice, the :bro:enum:`Signatures::SIG_COUNT_PER_RESP` action must
+		## bet set for the signature.
 		Count_Signature,
 		## Summarize the number of times a host triggered a signature.  The 
-		## interval between summaries is defined by the :bro:id:`summary_interval` 
+		## interval between summaries is defined by the
-		## variable.
+		## :bro:id:`Signatures::summary_interval` variable.
 		Signature_Summary,
 	};
 
+	## The signature logging stream identifier.
 	redef enum Log::ID += { LOG };
 
 	## These are the default actions you can apply to signature matches.
@@ -39,8 +45,8 @@ export {
 		SIG_QUIET,
 		## Generate a notice.
 		SIG_LOG,
-		## The same as :bro:enum:`SIG_FILE`, but ignore for aggregate/scan
+		## The same as :bro:enum:`Signatures::SIG_LOG`, but ignore for
-		## processing.
+		## aggregate/scan processing.
 		SIG_FILE_BUT_NO_SCAN,
 		## Generate a notice and set it to be alarmed upon.
 		SIG_ALARM,
@@ -49,22 +55,33 @@ export {
 		## Alarm once and then never again.
 		SIG_ALARM_ONCE,
 		## Count signatures per responder host and alarm with the 
-		## :bro:enum:`Count_Signature` notice if a threshold defined by
+		## :bro:enum:`Signatures::Count_Signature` notice if a threshold
-		## :bro:id:`count_thresholds` is reached.
+		## defined by :bro:id:`Signatures::count_thresholds` is reached.
 		SIG_COUNT_PER_RESP,
 		## Don't alarm, but generate per-orig summary.
 		SIG_SUMMARY,
 	};
 
+	## The record type which contains the column fields of the signature log.
 	type Info: record {
+		## The network time at which a signature matching type of event to
+		## be logged has occurred.
 		ts:         time         &log;
+		## The host which triggered the signature match event.
 		src_addr:   addr         &log &optional;
+		## The host port on which the signature-matching activity occurred.
 		src_port:   port         &log &optional;
+		## The destination host which was sent the payload that triggered the
+		## signature match.
 		dst_addr:   addr         &log &optional;
+		## The destination host port which was sent the payload that triggered
+		## the signature match.
 		dst_port:   port         &log &optional;
 		## Notice associated with signature event
 		note:       Notice::Type &log;
+		## The name of the signature that matched.
 		sig_id:     string       &log &optional;
+		## A more descriptive message of the signature-matching event.
 		event_msg:  string       &log &optional;
 		## Extracted payload data or extra message.
 		sub_msg:    string       &log &optional;
@@ -82,22 +99,26 @@ export {
 	## Signature IDs that should always be ignored.
 	const ignored_ids = /NO_DEFAULT_MATCHES/ &redef;
 	
-	## Alarm if, for a pair [orig, signature], the number of different 
+	## Generate a notice if, for a pair [orig, signature], the number of
-	## responders has reached one of the thresholds.
+	## different responders has reached one of the thresholds.
 	const horiz_scan_thresholds = { 5, 10, 50, 100, 500, 1000 } &redef;
 
-	## Alarm if, for a pair [orig, resp], the number of different signature 
+	## Generate a notice if, for a pair [orig, resp], the number of different
-	## matches has reached one of the thresholds.
+	## signature matches has reached one of the thresholds.
 	const vert_scan_thresholds = { 5, 10, 50, 100, 500, 1000 } &redef;
 
-	## Alarm if a :bro:enum:`SIG_COUNT_PER_RESP` signature is triggered as 
+	## Generate a notice if a :bro:enum:`Signatures::SIG_COUNT_PER_RESP`
-	## often as given by one of these thresholds.
+	## signature is triggered as often as given by one of these thresholds.
 	const count_thresholds = { 5, 10, 50, 100, 500, 1000, 10000, 1000000, } &redef;
 	
-	## The interval between when :bro:id:`Signature_Summary` notices are 
+	## The interval between when :bro:enum:`Signatures::Signature_Summary`
-	## generated.
+	## notice are generated.
 	const summary_interval = 1 day &redef;
 
+	## This event can be handled to access/alter data about to be logged
+	## to the signature logging stream.
+	##
+	## rec: The record of signature data about to be logged.
 	global log_signature: event(rec: Info);
 }