Merge remote-tracking branch 'origin/master' into topic/bernhard/software

Conflicts:
	scripts/base/frameworks/software/main.bro
	scripts/policy/protocols/ftp/software.bro

scripts/policy/protocols/ssh/detect-bruteforcing.bro

@@ -1,3 +1,5 @@
+##! Detect hosts which are doing password guessing attacks and/or password
+##! bruteforcing over SSH.
 
 @load base/protocols/ssh
 @load base/frameworks/metrics
@@ -9,17 +11,17 @@ module SSH;
 export {
 	redef enum Notice::Type += {
 		## Indicates that a host has been identified as crossing the 
-		## :bro:id:`password_guesses_limit` threshold with heuristically
+		## :bro:id:`SSH::password_guesses_limit` threshold with heuristically
 		## determined failed logins.
 		Password_Guessing,
 		## Indicates that a host previously identified as a "password guesser"
-		## has now had a heuristically successful login attempt.
+		## has now had a heuristically successful login attempt.  This is not
+		## currently implemented.
 		Login_By_Password_Guesser,
 	};
 	
 	redef enum Metrics::ID  += {
-		## This metric is to measure failed logins with the hope of detecting
-		## bruteforcing hosts.
+		## Metric is to measure failed logins.
 		FAILED_LOGIN,
 	};
 
@@ -37,7 +39,7 @@ export {
 	## client subnets and the yield value represents server subnets.
 	const ignore_guessers: table[subnet] of subnet &redef;
 
-	## Keeps track of hosts identified as guessing passwords.
+	## Tracks hosts identified as guessing passwords.
 	global password_guessers: set[addr] 
 		&read_expire=guessing_timeout+1hr &synchronized &redef;
 }

scripts/policy/protocols/ssh/geo-data.bro

@@ -1,5 +1,4 @@
-##! This implements all of the additional information and geodata detections 
-##! for SSH analysis.
+##! Geodata based detections for SSH analysis.
 
 @load base/frameworks/notice
 @load base/protocols/ssh
@@ -19,8 +18,8 @@ export {
 		remote_location: geo_location &log &optional;
 	};
 	
-	## The set of countries for which you'd like to throw notices upon 
-	## successful login
+	## The set of countries for which you'd like to generate notices upon 
+	## successful login.
 	const watched_countries: set[string] = {"RO"} &redef;
 }
 

scripts/policy/protocols/ssh/interesting-hostnames.bro

@@ -10,9 +10,9 @@ module SSH;
 
 export {
 	redef enum Notice::Type += {
-		## Generated if a login originates or responds with a host and the 
+		## Generated if a login originates or responds with a host where the 
 		## reverse hostname lookup resolves to a name matched by the 
-		## :bro:id:`interesting_hostnames` regular expression.
+		## :bro:id:`SSH::interesting_hostnames` regular expression.
 		Interesting_Hostname_Login,
 	};
 	
@@ -36,7 +36,9 @@ event SSH::heuristic_successful_login(c: connection)
 			if ( interesting_hostnames in hostname )
 				{
 				NOTICE([$note=Interesting_Hostname_Login,
-				        $msg=fmt("Interesting login from hostname: %s", hostname),
+				        $msg=fmt("Possible SSH login involving a %s %s with an interesting hostname.",
+				                 Site::is_local_addr(host) ? "local" : "remote",
+				                 host == c$id$orig_h ? "client" : "server"),
 				        $sub=hostname, $conn=c]);
 				}
 			}

scripts/policy/protocols/ssh/software.bro

@@ -1,4 +1,4 @@
-##! This script extracts SSH client and server information from SSH 
+##! Extracts SSH client and server information from SSH 
 ##! connections and forwards it to the software framework.
 
 @load base/frameworks/software
@@ -7,7 +7,9 @@ module SSH;
 
 export {
 	redef enum Software::Type += {
+		## Identifier for SSH clients in the software framework.
 		SERVER,
+		## Identifier for SSH servers in the software framework.
 		CLIENT,
 	};
 }