base/frameworks/tunnels/main.bro

Tunnel

This script handles the tracking/logging of tunnels (e.g. Teredo, AYIYA, or IP-in-IP such as 6to4 where “IP” is either IPv4 or IPv6).

For any connection that occurs over a tunnel, information about its encapsulating tunnels is also found in the tunnel field of connection.

Namespace:Tunnel Source File:/scripts/base/frameworks/tunnels/main.bro

Summary

Redefinable Options

Tunnel::expiration_interval: interval &redef

The amount of time a tunnel is not used in establishment of new connections before it is considered inactive/expired.

State Variables

Tunnel::active: table &read_expire = Tunnel::expiration_interval &expire_func = Tunnel::expire

Currently active tunnels.

Types

Tunnel::Action: enum	Types of interesting activity that can occur with a tunnel.
Tunnel::Info: record	The record type which contains column fields of the tunnel log.

Redefinitions

Log::ID: enum	The tunnel logging stream identifier.
likely_server_ports: set &redef

Functions

Tunnel::close: function	Removes a single tunnel from the Tunnel::active table and logs the closing/expiration of the tunnel.
Tunnel::expire: function	Logs a single tunnel “connection” with action Tunnel::EXPIRE and removes it from the Tunnel::active table.
Tunnel::register: function	Logs a single tunnel “connection” with action Tunnel::DISCOVER if it’s not already in the Tunnel::active table and adds it if not.
Tunnel::register_all: function	Logs all tunnels in an encapsulation chain with action Tunnel::DISCOVER that aren’t already in the Tunnel::active table and adds them if not.

Detailed Interface

Redefinable Options

Tunnel::expiration_interval

Type:interval Attributes:&redef Default:1.0 hr

The amount of time a tunnel is not used in establishment of new connections before it is considered inactive/expired.

State Variables

Tunnel::active

Type:table [conn_id] of Tunnel::Info Attributes:&read_expire = Tunnel::expiration_interval &expire_func = Tunnel::expire Default:{}

Currently active tunnels. That is, tunnels for which new, encapsulated connections have been seen in the interval indicated by Tunnel::expiration_interval.

Types

Tunnel::Action

Type:

enum

Tunnel::DISCOVER

A new tunnel (encapsulating “connection”) has been seen.

Tunnel::CLOSE

A tunnel connection has closed.

Tunnel::EXPIRE

No new connections over a tunnel happened in the amount of time indicated by Tunnel::expiration_interval.

Types of interesting activity that can occur with a tunnel.

Tunnel::Info

Type:

record

ts: time &log

Time at which some tunnel activity occurred.

uid: string &log &optional

The unique identifier for the tunnel, which may correspond to a connection’s uid field for non-IP-in-IP tunnels. This is optional because there could be numerous connections for payload proxies like SOCKS but we should treat it as a single tunnel.

id: conn_id &log

The tunnel “connection” 4-tuple of endpoint addresses/ports. For an IP tunnel, the ports will be 0.

tunnel_type: Tunnel::Type &log

The type of tunnel.

action: Tunnel::Action &log

The type of activity that occurred.

The record type which contains column fields of the tunnel log.

Functions

Tunnel::close

Type:function (tunnel: Tunnel::Info, action: Tunnel::Action) : void

Removes a single tunnel from the Tunnel::active table and logs the closing/expiration of the tunnel.

Tunnel:The tunnel which has closed or expired. Action:The specific reason for the tunnel ending.

Tunnel::expire

Type:function (t: table [conn_id] of Tunnel::Info, idx: conn_id) : interval

Logs a single tunnel “connection” with action Tunnel::EXPIRE and removes it from the Tunnel::active table.

T:A table of tunnels. Idx:The index of the tunnel table corresponding to the tunnel to expire. Returns:0secs, which when this function is used as an &expire_func, indicates to remove the element at idx immediately.

Tunnel::register

Type:function (ec: Tunnel::EncapsulatingConn) : void

Logs a single tunnel “connection” with action Tunnel::DISCOVER if it’s not already in the Tunnel::active table and adds it if not.

Tunnel::register_all

Type:function (ecv: EncapsulatingConnVector) : void

Logs all tunnels in an encapsulation chain with action Tunnel::DISCOVER that aren’t already in the Tunnel::active table and adds them if not.