Fix broken/missing documentation.

doc/logging.rst

@@ -89,8 +89,7 @@ Note the fields that are set for the filter:
         are generated by taking the stream's ID and munging it slightly.
         :bro:enum:`Conn::LOG` is converted into ``conn``,
         :bro:enum:`PacketFilter::LOG` is converted into
-        ``packet_filter``, and :bro:enum:`Notice::POLICY_LOG` is
+        ``packet_filter``.
-        converted into ``notice_policy``.
 
     ``include``
         A set limiting the fields to the ones given. The names

doc/notice.rst

@@ -86,21 +86,21 @@ directly make modifications to the :bro:see:`Notice::Info` record
 given as the argument to the hook.
 
 Here's a simple example which tells Bro to send an email for all notices of
-type :bro:see:`SSH::Login` if the server is 10.0.0.1:
+type :bro:see:`SSH::Password_Guessing` if the server is 10.0.0.1:
 
 .. code:: bro
 
     hook Notice::policy(n: Notice::Info)
       {
-      if ( n$note == SSH::Login && n$id$resp_h == 10.0.0.1 )
+      if ( n$note == SSH::Password_Guessing && n$id$resp_h == 10.0.0.1 )
         add n$actions[Notice::ACTION_EMAIL];
       }
 
 .. note::
 
-    Keep in mind that the semantics of the SSH::Login notice are
+    Keep in mind that the semantics of the SSH::Password_Guessing notice are
-    such that it is only raised when Bro heuristically detects a successful
+    such that it is only raised when Bro heuristically detects a failed
-    login. No apparently failed logins will raise this notice.
+    login.
 
 Hooks can also have priorities applied to order their execution like events
 with a default priority of 0.  Greater values are executed first.  Setting
@@ -110,7 +110,7 @@ a hook body to run before default hook bodies might look like this:
 
     hook Notice::policy(n: Notice::Info) &priority=5
       {
-      if ( n$note == SSH::Login && n$id$resp_h == 10.0.0.1 )
+      if ( n$note == SSH::Password_Guessing && n$id$resp_h == 10.0.0.1 )
         add n$actions[Notice::ACTION_EMAIL];
       }
 
@@ -173,16 +173,16 @@ Raising Notices
 
 A script should raise a notice for any occurrence that a user may want
 to be notified about or take action on. For example, whenever the base
-SSH analysis scripts sees an SSH session where it is heuristically
+SSH analysis scripts sees enough failed logins to a given host, it
-guessed to be a successful login, it raises a Notice of the type
+raises a notice of the type :bro:see:`SSH::Password_Guessing`.  The code
-:bro:see:`SSH::Login`. The code in the base SSH analysis script looks
+in the base SSH analysis script which raises the notice looks like this:
-like this:
 
 .. code:: bro
 
-    NOTICE([$note=SSH::Login,
+    NOTICE([$note=Password_Guessing,
-            $msg="Heuristically detected successful SSH login.",
+            $msg=fmt("%s appears to be guessing SSH passwords (seen in %d connections).", key$host, r$num),
-            $conn=c]);
+            $src=key$host,
+            $identifier=cat(key$host)]);
 
 :bro:see:`NOTICE` is a normal function in the global namespace which
 wraps a function within the ``Notice`` namespace. It takes a single

doc/scripts/builtins.rst

@@ -402,6 +402,31 @@ The Bro scripting language supports the following built-in types.
         if ( r?$s )
             ...
 
+.. bro:type:: opaque
+
+    A data type whose actual representation/implementation is
+    intentionally hidden, but whose values may be passed to certain
+    functions that can actually access the internal/hidden resources.
+    Opaque types are differentiated from each other by qualifying them
+    like ``opaque of md5`` or ``opaque of sha1``.  Any valid identifier
+    can be used as the type qualifier.
+
+    An example use of this type is the set of built-in functions which
+    perform hashing:
+
+    .. code:: bro
+
+        local handle: opaque of md5 = md5_hash_init();
+        md5_hash_update(handle, "test");
+        md5_hash_update(handle, "testing");
+        print md5_hash_finish(handle);
+
+    Here the opaque type is used to provide a handle to a particular
+    resource which is calculating an MD5 checksum incrementally over
+    time, but the details of that resource aren't relevant, it's only
+    necessary to have a handle as a way of identifying it and
+    distinguishing it from other such resources.
+
 .. bro:type:: file
 
     Bro supports writing to files, but not reading from them.  For

scripts/base/frameworks/logging/main.bro

@@ -195,7 +195,7 @@ export {
 	##
 	## Returns: True if a new stream was successfully removed.
 	##
-	## .. bro:see:: Log:create_stream
+	## .. bro:see:: Log::create_stream
 	global remove_stream: function(id: ID) : bool;
 
 	## Enables a previously disabled logging stream.  Disabled streams

scripts/base/frameworks/notice/main.bro

@@ -431,9 +431,6 @@ hook Notice::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 :bro:id:`NOTICE`
-## function.
 function is_being_suppressed(n: Notice::Info): bool
 	{
 	if ( n?$identifier && [n$note, n$identifier] in suppressing )

scripts/base/frameworks/sumstats/main.bro

@@ -99,7 +99,7 @@ export {
 		reducers:           set[Reducer];
 
 		## Provide a function to calculate a value from the
-		## :bro:see:`Result` structure which will be used
+		## :bro:see:`SumStats::Result` structure which will be used
 		## for thresholding.
 		## This is required if a $threshold value is given.
 		threshold_val:      function(key: SumStats::Key, result: SumStats::Result): count &optional;

scripts/base/frameworks/sumstats/plugins/last.bro

@@ -16,7 +16,8 @@ export {
 
 	redef record ResultVal += {
 		## This is the queue where elements are maintained.  Use the
-		## :bro:see:`SumStats::get_elements` function to get a vector of the current element values.
+		## :bro:see:`SumStats::get_last` function to get a vector of
+		## the current element values.
 		last_elements: Queue::Queue &optional;
 	};
 

scripts/base/protocols/dns/main.bro

@@ -101,20 +101,21 @@ export {
 	##
 	## is_query: Indicator for if this is being called for a query or a response.
 	global set_session: hook(c: connection, msg: dns_msg, is_query: bool);
+
+	## A record type which tracks the status of DNS queries for a given
+	## :bro:type:`connection`.
+	type State: record {
+		## Indexed by query id, returns Info record corresponding to
+		## query/response which haven't completed yet.
+		pending: table[count] of Queue::Queue;
+
+		## This is the list of DNS responses that have completed based on the
+		## number of responses declared and the number received.  The contents
+		## of the set are transaction IDs.
+		finished_answers: set[count];
+	};
 }
 
-## A record type which tracks the status of DNS queries for a given
-## :bro:type:`connection`.
-type State: record {
-	## Indexed by query id, returns Info record corresponding to
-	## query/response which haven't completed yet.
-	pending: table[count] of Queue::Queue;
-
-	## This is the list of DNS responses that have completed based on the
-	## number of responses declared and the number received.  The contents
-	## of the set are transaction IDs.
-	finished_answers: set[count];
-};
 
 redef record connection += {
 	dns:       Info  &optional;

scripts/base/utils/queue.bro

@@ -16,7 +16,7 @@ export {
 
 	## Initialize a queue record structure.
 	##
-	## s: A :bro:record:`Settings` record configuring the queue.
+	## s: A record which configures the queue.
 	##
 	## Returns: An opaque queue record.
 	global init:       function(s: Settings &default=[]): Queue;

scripts/policy/misc/detect-traceroute/main.bro

@@ -32,8 +32,8 @@ export {
 	const icmp_time_exceeded_threshold = 3 &redef;
 
 	## Interval at which to watch for the
-	## :bro:id:`ICMPTimeExceeded::icmp_time_exceeded_threshold` variable to be crossed.
+	## :bro:id:`Traceroute::icmp_time_exceeded_threshold` variable to be
-	## At the end of each interval the counter is reset.
+	## crossed.  At the end of each interval the counter is reset.
 	const icmp_time_exceeded_interval = 3min &redef;
 
 	## The log record for the traceroute log.

scripts/policy/misc/scan.bro

@@ -13,17 +13,18 @@ module Scan;
 
 export {
 	redef enum Notice::Type += {
-		## Address scans detect that a host appears to be scanning some number of
+		## Address scans detect that a host appears to be scanning some number
-		## destinations on a single port. This notice is generated when more than
+		## of destinations on a single port. This notice is generated when more
-		## :bro:id:`addr_scan_threshold` unique hosts are seen over the previous
+		## than :bro:id:`Scan::addr_scan_threshold` unique hosts are seen over
-		## :bro:id:`addr_scan_interval` time range.
+		## the previous :bro:id:`Scan::addr_scan_interval` time range.
 		Address_Scan,
 
 		## 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 :bro:id:`port_scan_threshold`
+		## an attacking host attempts to connect to
+		## :bro:id:`Scan::port_scan_threshold`
 		## unique ports on a single host over the previous
-		## :bro:id:`port_scan_interval` time range.
+		## :bro:id:`Scan::port_scan_interval` time range.
 		Port_Scan,
 	};
 

src/bro.bif

@@ -2923,7 +2923,7 @@ function bytestring_to_hexstr%(bytestring: string%): string
 ##
 ## Returns: The encoded version of *s*.
 ##
-## .. bro:see:: encode_base64_custom, decode_base64
+## .. bro:see:: encode_base64_custom decode_base64
 function encode_base64%(s: string%): string
 	%{
 	BroString* t = encode_base64(s->AsString());
@@ -2946,7 +2946,7 @@ function encode_base64%(s: string%): string
 ##
 ## Returns: The encoded version of *s*.
 ##
-## .. bro:see:: encode_base64, decode_base64_custom
+## .. bro:see:: encode_base64 decode_base64_custom
 function encode_base64_custom%(s: string, a: string%): string
 	%{
 	BroString* t = encode_base64(s->AsString(), a->AsString());
@@ -2965,7 +2965,7 @@ function encode_base64_custom%(s: string, a: string%): string
 ##
 ## Returns: The decoded version of *s*.
 ##
-## .. bro:see:: decode_base64_custom, encode_base64
+## .. bro:see:: decode_base64_custom encode_base64
 function decode_base64%(s: string%): string
 	%{
 	BroString* t = decode_base64(s->AsString());
@@ -2988,7 +2988,7 @@ function decode_base64%(s: string%): string
 ##
 ## Returns: The decoded version of *s*.
 ##
-## .. bro:see:: decode_base64, encode_base64_custom
+## .. bro:see:: decode_base64 encode_base64_custom
 function decode_base64_custom%(s: string, a: string%): string
 	%{
 	BroString* t = decode_base64(s->AsString(), a->AsString());

src/event.bif

@@ -7042,6 +7042,7 @@ event file_gap%(f: fa_file, offset: count, len: count%);
 ## This event is generated each time file analysis is ending for a given file.
 ##
 ## f: The file.
+##
 ## .. bro:see:: file_new file_over_new_connection file_timeout file_gap
 event file_state_remove%(f: fa_file%);