Merge branch 'topic/robin/event-dumper'

Changes:

   - Changing semantics of the new_event() meta event: it's raised
     only for events that have a handler defined. There are too many
     checks in Bro that prevent events wo/ handler from being even
     prepared to raise to do that differently.

   - Adding test case.

* topic/robin/event-dumper:
  New script misc/dump-events.bro, along with core support, that dumps events Bro is raising in an easily readable form.
  Prettyfing Describe() for record types.

CHANGES

@@ -1,4 +1,14 @@
 
+2.2-38 | 2013-12-04 12:10:54 -0800
+
+  * New script misc/dump-events.bro, along with core support, that
+    dumps events Bro is raising in an easily readable form for
+    debugging. (Robin Sommer)
+
+  * Prettyfing Describe() for record types. If a record type has a
+    name and ODesc is set to short, we now print the name instead of
+    the full field list. (Robin Sommer)
+
 2.2-35 | 2013-12-04 10:10:32 -0800
 
   * Rework the automated script-reference documentation generation

VERSION

@@ -1 +1 @@
-2.2-35
+2.2-38

scripts/base/init-bare.bro

@@ -507,7 +507,7 @@ type script_id: record {
 ##    directly and then remove this alias.
 type id_table: table[string] of script_id;
 
-## Meta-information about a record-field.
+## Meta-information about a record field.
 ##
 ## .. bro:see:: record_fields record_field_table
 type record_field: record {
@@ -529,6 +529,25 @@ type record_field: record {
 ##    directly and then remove this alias.
 type record_field_table: table[string] of record_field;
 
+## Meta-information about a parameter to a function/event.
+##
+## .. bro:see:: call_argument_vector new_event
+type call_argument: record {
+	name: string;	##< The name of the parameter.
+	type_name: string;	##< The name of the parameters's type.
+	default_val: any &optional;	##< The value of the :bro:attr:`&default` attribute if defined.
+
+	## The value of the parameter as passed into a given call instance.
+	## Might be unset in the case a :bro:attr:`&default` attribute is
+	## defined.
+	value: any &optional;
+};
+
+## Vector type used to capture parameters of a function/event call.
+##
+## .. bro:see:: call_argument new_event
+type call_argument_vector: vector of call_argument;
+
 # todo:: Do we still need these here? Can they move into the packet filter
 # framework?
 #

scripts/policy/misc/dump-events.bro

@@ -0,0 +1,40 @@
+##! This script dumps the events that Bro raises out to standard output in a
+##! readable form. This is for debugging only and allows to understand events and
+##! their parameters as Bro processes input. Note that it will show only events
+##! for which a handler is defined.
+
+module DumpEvents;
+
+export {
+	## If true, include event arguments in output.
+	const include_args = T &redef;
+
+	## Only include events matching the given pattern into output. By default, the
+	## pattern matches all events.
+	const include = /.*/ &redef;
+}
+
+event new_event(name: string, args: call_argument_vector)
+	{
+	if ( include !in name )
+		return;
+
+	print fmt("%17.6f %s", network_time(), name);
+
+	if ( ! include_args || |args| == 0 )
+		return;
+
+	for ( i in args )
+		{
+		local a = args[i];
+
+		local proto = fmt("%s: %s", a$name, a$type_name);
+
+		if ( a?$value )
+			print fmt("                  [%d] %-18s = %s", i, proto, a$value);
+		else
+			print fmt("                  | %-18s = %s [default]", proto, a$value);
+		}
+
+	print "";
+	}

src/EventHandler.cc

@@ -3,6 +3,7 @@
 #include "Func.h"
 #include "Scope.h"
 #include "RemoteSerializer.h"
+#include "NetVar.h"
 
 EventHandler::EventHandler(const char* arg_name)
 	{
@@ -56,6 +57,9 @@ void EventHandler::Call(val_list* vl, bool no_remote)
 	DEBUG_MSG("Event: %s\n", Name());
 #endif
 
+	if ( new_event )
+		NewEvent(vl);
+
 	if ( ! no_remote )
 		{
 		loop_over_list(receivers, i)
@@ -75,6 +79,56 @@ void EventHandler::Call(val_list* vl, bool no_remote)
 		}
 	}
 
+void EventHandler::NewEvent(val_list* vl)
+	{
+	if ( ! new_event )
+		return;
+
+	if ( this == new_event.Ptr() )
+		// new_event() is the one event we don't want to report.
+		return;
+
+	RecordType* args = FType()->Args();
+	VectorVal* vargs = new VectorVal(call_argument_vector);
+
+	for ( int i = 0; i < args->NumFields(); i++ )
+		{
+		const char* fname = args->FieldName(i);
+		BroType* ftype = args->FieldType(i);
+		Val* fdefault = args->FieldDefault(i);
+
+		RecordVal* rec = new RecordVal(call_argument);
+		rec->Assign(0, new StringVal(fname));
+
+		ODesc d;
+		d.SetShort();
+		ftype->Describe(&d);
+		rec->Assign(1, new StringVal(d.Description()));
+
+		if ( fdefault )
+			{
+			Ref(fdefault);
+			rec->Assign(2, fdefault);
+			}
+
+		if ( i < vl->length() && (*vl)[i] )
+			{
+			Val* val = (*vl)[i];
+			Ref(val);
+			rec->Assign(3, val);
+			}
+
+		vargs->Assign(i, rec);
+		}
+
+	val_list* mvl = new val_list(2);
+	mvl->append(new StringVal(name));
+	mvl->append(vargs);
+
+	Event* ev = new Event(new_event, mvl);
+	mgr.Dispatch(ev);
+	}
+
 void EventHandler::AddRemoteHandler(SourceID peer)
 	{
 	receivers.append(peer);

src/EventHandler.h

@@ -49,6 +49,8 @@ public:
 	static EventHandler* Unserialize(UnserialInfo* info);
 
 private:
+	void NewEvent(val_list* vl);	// Raise new_event() meta event.
+
 	const char* name;
 	Func* local;
 	FuncType* type;

src/NetVar.cc

@@ -235,6 +235,8 @@ RecordType* script_id;
 TableType* id_table;
 RecordType* record_field;
 TableType* record_field_table;
+RecordType* call_argument;
+VectorType* call_argument_vector;
 
 StringVal* cmd_line_bpf_filter;
 
@@ -528,4 +530,6 @@ void init_net_var()
 	id_table = internal_type("id_table")->AsTableType();
 	record_field = internal_type("record_field")->AsRecordType();
 	record_field_table = internal_type("record_field_table")->AsTableType();
+	call_argument_vector = internal_type("call_argument_vector")->AsVectorType();
+	call_argument = internal_type("call_argument")->AsRecordType();
 	}

src/NetVar.h

@@ -239,6 +239,8 @@ extern RecordType* script_id;
 extern TableType* id_table;
 extern RecordType* record_field;
 extern TableType* record_field_table;
+extern RecordType* call_argument;
+extern VectorType* call_argument_vector;
 
 extern StringVal* cmd_line_bpf_filter;
 

src/Type.cc

@@ -1035,10 +1035,16 @@ void RecordType::Describe(ODesc* d) const
 	{
 	if ( d->IsReadable() )
 		{
-		d->AddSP("record {");
-		DescribeFields(d);
-		d->SP();
-		d->Add("}");
+		if ( d->IsShort() && GetName().size() )
+			d->Add(GetName());
+
+		else
+			{
+			d->AddSP("record {");
+			DescribeFields(d);
+			d->SP();
+			d->Add("}");
+			}
 		}
 
 	else

src/event.bif

@@ -1,9 +1,9 @@
 ##! The protocol-independent events that the C/C++ core of Bro can generate.
-##! 
+##!
 ##! This is mostly events not related to a specific transport- or
 ##! application-layer protocol, but also includes a few that may be generated
 ##! by more than one protocols analyzer (like events generated by both UDP and
-##! TCP analysis.) 
+##! TCP analysis.)
 
 #
 # Documentation conventions:
@@ -1007,6 +1007,17 @@ event dns_mapping_lost_name%(dm: dns_mapping%);
 ##    dns_mapping_valid
 event dns_mapping_altered%(dm: dns_mapping, old_addrs: addr_set, new_addrs: addr_set%);
 
+## A meta event generated for events that Bro raises. This will report all events
+## for which at least one handler is defined.
+##
+## Note that handling this meta event is expensive and should be limited to
+## debugging purposes.
+##
+## name: The name of the event.
+##
+## params: The event's parameters.
+event new_event%(name: string, params: call_argument_vector%);
+
 ## Deprecated. Will be removed.
 event root_backdoor_signature_found%(c: connection%);
 

testing/btest/Baseline/scripts.policy.misc.dump-events/all-events-no-args.log

@@ -0,0 +1,36 @@
+         0.000000 bro_init
+         0.000000 filter_change_tracking
+1170717505.366729 ChecksumOffloading::check
+1170717505.366729 filter_change_tracking
+1170717505.366729 new_connection
+1170717505.548308 connection_established
+1170717505.549109 ssl_client_hello
+1170717505.734145 protocol_confirmation
+1170717505.734145 ssl_server_hello
+1170717505.735416 x509_certificate
+1170717505.735416 x509_certificate
+1170717505.934612 ssl_established
+1170717508.515696 new_connection
+1170717508.696747 connection_established
+1170717508.697180 ssl_client_hello
+1170717508.881857 protocol_confirmation
+1170717508.881857 ssl_server_hello
+1170717508.883051 x509_certificate
+1170717508.883051 x509_certificate
+1170717509.082241 ssl_established
+1170717511.541455 new_connection
+1170717511.722589 connection_established
+1170717511.722913 ssl_client_hello
+1170717511.908619 protocol_confirmation
+1170717511.908619 ssl_server_hello
+1170717511.909717 x509_certificate
+1170717511.909717 x509_certificate
+1170717512.108799 ssl_established
+1170717528.851698 ChecksumOffloading::check
+1170717528.851698 connection_state_remove
+1170717531.882302 net_done
+1170717531.882302 filter_change_tracking
+1170717531.882302 connection_state_remove
+1170717531.882302 connection_state_remove
+1170717531.882302 bro_done
+1170717531.882302 ChecksumOffloading::check

testing/btest/scripts/policy/misc/dump-events.bro

@@ -0,0 +1,7 @@
+# @TEST-EXEC: bro -r $TRACES/ssl.v3.trace policy/misc/dump-events.bro >all-events.log
+# @TEST-EXEC: bro -r $TRACES/ssl.v3.trace policy/misc/dump-events.bro DumpEvents::include_args=F >all-events-no-args.log
+# @TEST-EXEC: bro -r $TRACES/ssl.v3.trace policy/misc/dump-events.bro DumpEvents::include=/ssl_/ >ssl-events.log
+# 
+# @TEST-EXEC: btest-diff all-events.log
+# @TEST-EXEC: btest-diff all-events-no-args.log
+# @TEST-EXEC: btest-diff ssl-events.log