DNS policy scripts documentation cleanup/tweaks.

doc/scripts/CMakeLists.txt

@@ -129,9 +129,15 @@ endmacro(REST_TARGET)
 # Schedule Bro scripts for which to generate documentation.
 # Note: the script may be located in a subdirectory off of one of the main
 # directories in BROPATH.  In that case, just list the script as 'foo/bar.bro'
-rest_target(${POLICY_SRC_DIR} conn.bro                          user)
+rest_target(${POLICY_SRC_DIR} conn.bro                         user)
-rest_target(${POLICY_SRC_DIR} dns.bro                           user)
+rest_target(${POLICY_SRC_DIR} site.bro                         user)
-rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro             internal)
+rest_target(${POLICY_SRC_DIR} dns.bro                          policy/dns-index)
+rest_target(${POLICY_SRC_DIR} dns/auth-addl.bro                policy/dns-index)
+rest_target(${POLICY_SRC_DIR} dns/base.bro                     policy/dns-index)
+rest_target(${POLICY_SRC_DIR} dns/consts.bro                   policy/dns-index)
+rest_target(${POLICY_SRC_DIR} dns/detect.bro                   policy/dns-index)
+rest_target(${POLICY_SRC_DIR} dns/passive-replication.bro      policy/dns-index)
+rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro            internal)
 
 # Finding out what scripts bro will generate documentation for by default
 # can be done like: `bro --doc-scripts --exec ""`

doc/scripts/source/index.rst

@@ -11,11 +11,12 @@ Contents:
 
    common
    builtins
-   policy/index
    default
    bifs
    user
+   policy/dns-index
    internal
+   policy/index
 
 Indices and tables
 ==================

doc/scripts/source/policy/dns-index.rst

@@ -0,0 +1,3 @@
+DNS Policy Scripts
+==================
+

doc/scripts/source/user.rst

@@ -1,3 +1,3 @@
-User-Facing Policy Scripts
+Other User-Facing Policy Scripts
-==========================
+================================
 

policy/dns/base.bro

@@ -1,4 +1,5 @@
 @load functions
+@load dns/consts
 
 module DNS;
 
@@ -277,4 +278,4 @@ event connection_state_remove(c: connection) &priority=-5
 	for ( trans_id in c$dns_state$pending )
 		Log::write(DNS, c$dns_state$pending[trans_id]);
 	}
-	
+	

policy/dns/detect.bro

@@ -1,8 +1,12 @@
 ##! Script for detecting strange activity within DNS.
-##! Detections:
+##!
-##!   * Raise a notice for responses from remote hosts that resolve to local 
+##! Notices raised:
-##!     hosts but the name is not considered to be within a local zone.
+##!
-##!       - local_zones variable **must** be set appropriately for this detection.
+##!   * :bro:enum:`DNS::DNS_ExternalName`
+##!
+##!     A remote host resolves to a local host, but the name is not considered
+##!     to be within a local zone.  :bro:id:`local_zones` variable **must**
+##!     be set appropriately for this detection.
 
 @load dns/base
 @load notice
@@ -10,9 +14,9 @@
 module DNS;
 
 redef enum Notice::Type += { 
-	# Raised when a non-local name is found to be pointing at a local host.
+	## Raised when a non-local name is found to be pointing at a local host.
-	#  This only works appropriately when all of your authoritative DNS 
+	## This only works appropriately when all of your authoritative DNS
-	#  servers are located in your "local_nets".
+	## servers are located in your :bro:id:`local_nets`.
 	DNS_ExternalName, 
 	};
 

policy/dns/passive-replication.bro

@@ -1,10 +1,11 @@
 ##! Script for logging passive DNS replication-type data.
-##! For a definition of what passive DNS repliction is, see here::
+##! For a definition of what passive DNS repliction is, see here:
-##!     https://sie.isc.org/
+##! https://sie.isc.org/
-
+##!
-## NOTE: This is a major hack job.
+##! .. note:: NOTE: This is a major hack job.
-## TODO: two queries within the create_expire with different results will
+##!
-##       cause only one to be logged.
+##! TODO: two queries within the create_expire with different results will
+##! cause only one to be logged.
 
 @load dns/base
 
@@ -30,4 +31,4 @@ event bro_init()
 			},
 		$include=set("ts", "query", "answers")
 		]);
-	}
+	}

policy/notice-action-filters.bro

@@ -1,4 +1,4 @@
-## A few predefined notice_action_filters (see notice.bro).
+##! A few predefined notice_action_filters (see notice.bro).
 @load notice
 @load functions