Finished SSL & syslog autodocs.

scripts/base/protocols/ssl/consts.bro

@@ -1,23 +1,27 @@
 module SSL;
 
 export {
-
 	const SSLv2  = 0x0002;
 	const SSLv3  = 0x0300;
 	const TLSv10 = 0x0301;
 	const TLSv11 = 0x0302;
+	## Mapping between the constants and string values for SSL/TLS versions.
 	const version_strings: table[count] of string = {
 		[SSLv2] = "SSLv2",
 		[SSLv3] = "SSLv3",
 		[TLSv10] = "TLSv10",
 		[TLSv11] = "TLSv11",
 	} &default="UNKNOWN";
-
+	
+	## Mapping between numeric codes and human readable strings for alert 
+	## levels.
 	const alert_levels: table[count] of string = {
 		[1] = "warning",
 		[2] = "fatal",
 	} &default=function(i: count):string { return fmt("unknown-%d", i); };
-
+	
+	## Mapping between numeric codes and human readable strings for alert 
+	## descriptions..
 	const alert_descriptions: table[count] of string = {
 		[0] = "close_notify",
 		[10] = "unexpected_message",
@@ -50,8 +54,11 @@ export {
 		[114] = "bad_certificate_hash_value",
 		[115] = "unknown_psk_identity",
 	} &default=function(i: count):string { return fmt("unknown-%d", i); };
-
-	# http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml
+	
+	## Mapping between numeric codes and human readable strings for SSL/TLS
+	## extensions.
+	## ..note: More information can be found here:
+	##         http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml
 	const extensions: table[count] of string = {
 		[0] = "server_name",
 		[1] = "max_fragment_length",
@@ -299,11 +306,10 @@ export {
 	const SSL_RSA_WITH_DES_CBC_MD5 = 0xFF82;
 	const SSL_RSA_WITH_3DES_EDE_CBC_MD5 = 0xFF83;
 	const TLS_EMPTY_RENEGOTIATION_INFO_SCSV = 0x00FF;
-
-	# --- This is a table of all known cipher specs.
-	# --- It can be used for detecting unknown ciphers and for
-	# --- converting the cipher spec constants into a human readable format.
-
+	
+	## This is a table of all known cipher specs.  It can be used for 
+	## detecting unknown ciphers and for converting the cipher spec constants 
+	## into a human readable format.
 	const cipher_desc: table[count] of string = {
 		# --- sslv20 ---
 		[SSLv20_CK_RC4_128_EXPORT40_WITH_MD5] =
@@ -530,7 +536,8 @@ export {
 		[SSL_RSA_FIPS_WITH_DES_CBC_SHA_2] = "SSL_RSA_FIPS_WITH_DES_CBC_SHA_2",
 		[SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA_2] = "SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA_2",
 	} &default="UNKNOWN";
-
+	
+	## Mapping between the constants and string values for SSL/TLS errors.
 	const x509_errors: table[count] of string = {
 		[0]  = "ok",
 		[1]  = "unable to get issuer cert",

scripts/base/protocols/ssl/main.bro

@@ -1,4 +1,5 @@
-##! Base SSL analysis script.
+##! Base SSL analysis script.  This script logs information about the SSL/TLS
+##! handshaking and encryption establishment process.
 
 @load ./consts
 
@@ -12,44 +13,53 @@ export {
 		ts:               time             &log;
 		uid:              string           &log;
 		id:               conn_id          &log;
+		## SSL/TLS version the server offered.
 		version:          string           &log &optional;
+		## SSL/TLS cipher suite the server chose.
 		cipher:           string           &log &optional;
+		## Value of the Server Name Indicator SSL/TLS extension.  It 
+		## indicates the server name that the client was requesting.
 		server_name:      string           &log &optional;
+		## Session ID offered by the client for session resumption.
 		session_id:       string           &log &optional;
+		## Subject of the X.509 certificate offered by the server.
 		subject:          string           &log &optional;
+		## NotValidBefore field value from the server certificate.
 		not_valid_before: time             &log &optional;
+		## NotValidAfter field value from the serve certificate.
 		not_valid_after:  time             &log &optional;
+		## Last alert that was seen during the connection.
 		last_alert:       string           &log &optional;
-
+		
+		## Full binary server certificate stored in DER format.
 		cert:             string           &optional;
+		## Chain of certificates offered by the server to validate its 
+		## complete signing chain.
 		cert_chain:       vector of string &optional;
 
-		## This stores the analyzer id used for the analyzer instance attached
+		## The analyzer ID used for the analyzer instance attached
 		## to each connection.  It is not used for logging since it's a
 		## meaningless arbitrary number.
 		analyzer_id:      count            &optional;
 	};
-
-	## This is where the default root CA bundle is defined.  By loading the
+	
+	## The default root CA bundle.  By loading the
 	## mozilla-ca-list.bro script it will be set to Mozilla's root CA list.
 	const root_certs: table[string] of string = {} &redef;
-
+	
 	## If true, detach the SSL analyzer from the connection to prevent
 	## continuing to process encrypted traffic. Helps with performance
 	## (especially with large file transfers).
 	const disable_analyzer_after_detection = T &redef;
-
+	
 	## The openssl command line utility.  If it's in the path the default
 	## value will work, otherwise a full path string can be supplied for the
 	## utility.
 	const openssl_util = "openssl" &redef;
-
+	
+	## Event that can be handled to access the SSL
+	## record as it is sent on to the logging framework.
 	global log_ssl: event(rec: Info);
-
-	const ports = {
-		443/tcp, 563/tcp, 585/tcp, 614/tcp, 636/tcp,
-		989/tcp, 990/tcp, 992/tcp, 993/tcp, 995/tcp, 5223/tcp
-	} &redef;
 }
 
 redef record connection += {
@@ -76,6 +86,11 @@ redef capture_filters += {
 	["xmpps"] = "tcp port 5223",
 };
 
+const ports = {
+	443/tcp, 563/tcp, 585/tcp, 614/tcp, 636/tcp,
+	989/tcp, 990/tcp, 992/tcp, 993/tcp, 995/tcp, 5223/tcp
+};
+
 redef dpd_config += {
 	[[ANALYZER_SSL]] = [$ports = ports]
 };

scripts/base/protocols/syslog/consts.bro

@@ -1,6 +1,9 @@
+##! Constants definitions for syslog.
+
 module Syslog;
 
 export {
+	## Mapping between the constants and string values for syslog facilities.
 	const facility_codes: table[count] of string = {
 		[0]  = "KERN",
 		[1]  = "USER",
@@ -27,7 +30,8 @@ export {
 		[22] =  "LOCAL6",
 		[23] =  "LOCAL7",
 	} &default=function(c: count): string { return fmt("?-%d", c); };
-
+	
+	## Mapping between the constants and string values for syslog severities.
 	const severity_codes: table[count] of string = {
 		[0] = "EMERG",
 		[1] = "ALERT",

scripts/base/protocols/syslog/main.bro

@@ -1,4 +1,5 @@
-##! Core script support for logging syslog messages.
+##! Core script support for logging syslog messages.  This script represents 
+##! one syslog message as one logged record.
 
 @load ./consts
 
@@ -12,16 +13,19 @@ export {
 		ts:        time            &log;
 		uid:       string          &log;
 		id:        conn_id         &log;
+		## Protocol over which the message was seen.
 		proto:     transport_proto &log;
+		## Syslog facility for the message.
 		facility:  string          &log;
+		## Syslog severity for the message.
 		severity:  string          &log;
+		## The plain text message.
 		message:   string          &log;
 	};
-	
-	const ports = { 514/udp } &redef;
 }
 
 redef capture_filters += { ["syslog"] = "port 514" };
+const ports = { 514/udp } &redef;
 redef dpd_config += { [ANALYZER_SYSLOG_BINPAC] = [$ports = ports] };
 
 redef likely_server_ports += { 514/udp };