From 32f37c9f6d151d73a47c2a0e558fcbd37b47f49c Mon Sep 17 00:00:00 2001
From: Gregor Maier <gregor@icir.org>
Date: Sun, 7 Aug 2011 12:26:19 -0700
Subject: [PATCH] Documenting tunnel decapsulation.

Haven't tested the autodoc output yet.
---
 scripts/base/bro.init                | 17 +++++---
 scripts/policy/frameworks/tunnel.bro | 61 ++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+), 5 deletions(-)
 create mode 100644 scripts/policy/frameworks/tunnel.bro

diff --git a/scripts/base/bro.init b/scripts/base/bro.init
index cf34a763c5..a6b0ff3890 100644
--- a/scripts/base/bro.init
+++ b/scripts/base/bro.init
@@ -83,8 +83,14 @@ type AnalyzerID: count;
 
 module Tunnel;
 export {
+	## Records the identity of a the parent of a tunneled connection. 
 	type parent_t: record {
+		## The 4-tuple of the tunnel "connection". In case of an IP-in-IP
+		## tunnel the ports will be set to 0. The direction (i.e., orig and
+		## resp) of the parent are set according to the tunneled connection
+		## and not according to the side that established the tunnel. 
 		cid: conn_id;
+		## The type of tunnel.
 		tunnel_type: tunneltype_t;
 	} &log;
 } # end export
@@ -1495,20 +1501,21 @@ const parse_udp_tunnels = F &redef;
 
 module Tunnel;
 export {
-	# Whether to decapsulate IP tunnels (IPinIP, 6in4, 6to4)
+	## Whether to decapsulate IP tunnels (IPinIP, 6in4, 6to4)
 	const decapsulate_ip = F &redef;
 
-	# Whether to decapsulate URDP tunnels (e.g., Teredo, IPv4 in UDP)
+	## Whether to decapsulate URDP tunnels (e.g., Teredo, IPv4 in UDP)
 	const decapsulate_udp = F &redef;
 
-	# If decapsulating UDP: the set of ports for which to do so
+	## If decapsulating UDP: the set of ports for which to do so. 
+	## Can be overridden by :bro:id:`Tunnel::udp_tunnel_allports`
 	const udp_tunnel_ports: set[port] = { 
 		3544/udp,    # Teredo 
 		5072/udp,    # AYIAY
 	} &redef;
 
-	# If udp_tunnel_allports is T udp_tunnel_ports is ignored and we
-	# check every UDP packet for tunnels. 
+	## If udp_tunnel_allports is T :bro:id:`udp_tunnel_ports` is ignored and we
+	## check every UDP packet for tunnels. 
 	const udp_tunnel_allports = F &redef;
 } # end export
 module GLOBAL;
diff --git a/scripts/policy/frameworks/tunnel.bro b/scripts/policy/frameworks/tunnel.bro
new file mode 100644
index 0000000000..80e46c31a4
--- /dev/null
+++ b/scripts/policy/frameworks/tunnel.bro
@@ -0,0 +1,61 @@
+##! Handle tunneled connections.  
+##! 
+##! Bro can decapsulate IPinIP and IPinUDP tunnels, were "IP" can be either
+##! IPv4 or IPv6. The most common case will be decapsulating Teredo, 6to4,
+##! 6in4, and AYIAY. 
+##! 
+##! Decapsulation happens early in a packets processing, right after IP
+##! defragmentation but before there is a connection context. The tunnel
+##! headers are stripped from packet and the identity of the parent is 
+##! is stored as the ``tunnel_parent`` member of :bro:type:`connection`, 
+##! which is of type :bro:type:`parent_t`. 
+##! 
+##! *Limitation:* The decapsulated packets are not fed through the 
+##! defragmenter again. 
+##! 
+##! 
+
+module Tunnel; 
+
+redef use_connection_compressor = F;
+redef Tunnel::decapsulate_ip = T;
+redef Tunnel::decapsulate_udp = T;
+redef Tunnel::udp_tunnel_allports = T;
+
+export {
+	redef enum Log::ID += { TUNNEL };
+
+	## This record will be logged 
+	type Info : record {
+		## This is the time of the first record
+		ts:       time            &log;
+		## The uid of the child connection, i.e. the connection in the tunnel
+		uid:      string          &log;
+		## The connection id of the child
+		id:       conn_id         &log;
+		## The child's transport protocol
+		proto:    transport_proto &log;
+		## The parent connection of IP-pair
+		parent:   parent_t        &log;
+	};
+	global log_conn: event(rec: Info);
+}
+
+event bro_init()
+	{
+	Log::create_stream(TUNNEL, [$columns=Info, $ev=log_conn]);
+	}
+
+event new_connection(c: connection)
+	{
+	if (c?$tunnel_parent)
+		{
+		local info: Info;
+		info$ts = c$start_time;
+		info$uid = c$uid;
+		info$id = c$id;
+		info$proto = get_port_transport_proto(c$id$resp_p);
+		info$parent = c$tunnel_parent;
+		Log::write(TUNNEL, info);
+		}
+	}