base/frameworks/tunnels/main.zeek

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

Imports

base/protocols/conn/removal-hooks.zeek

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.

Hooks

Tunnel::finalize_tunnel: Conn::RemovalHook

Tunnel finalization hook.

Tunnel::log_policy: Log::PolicyHook

A default logging policy hook for the stream.

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.

Hooks

Tunnel::finalize_tunnel
Type

Conn::RemovalHook

Tunnel finalization hook. Remaining Tunnel info may get logged when it’s called.

Tunnel::log_policy
Type

Log::PolicyHook

A default logging policy hook for the stream.

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.

Parameters
  • 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.

Parameters
  • 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.