main.zeek

PacketFilter

This script supports how Zeek sets its BPF capture filter. By default Zeek sets a capture filter that allows all traffic. If a filter is set on the command line, that filter takes precedence over the default open filter and all filters defined in Zeek scripts with the capture_filters and restrict_filters variables.

Namespace: PacketFilter
Imports: base/frameworks/analyzer, base/frameworks/notice, base/frameworks/packet-filter/utils.zeek

Summary

Redefinable Options

`PacketFilter::default_capture_filter`: `string` `&redef`	The BPF filter that is used by default to define what traffic should be captured.
`PacketFilter::enable_auto_protocol_capture_filters`: `bool` `&redef`	Enables the old filtering approach of “only watch common ports for analyzed protocols”.
`PacketFilter::max_filter_compile_time`: `interval` `&redef`	The maximum amount of time that you’d like to allow for BPF filters to compile.
`PacketFilter::restricted_filter`: `string` `&redef`	Filter string which is unconditionally and’ed to the beginning of every dynamically built filter.
`PacketFilter::unrestricted_filter`: `string` `&redef`	Filter string which is unconditionally or’ed to the beginning of every dynamically built filter.

State Variables

PacketFilter::current_filter: string

This is where the default packet filter is stored and it should not normally be modified by users.

Types

`PacketFilter::FilterPlugin`: `record`	A data structure to represent filter generating plugins.
`PacketFilter::Info`: `record`	The record type defining columns to be logged in the packet filter logging stream.

Redefinitions

Log::ID: enum

Add the packet filter logging stream.

PacketFilter::LOG

Notice::Type: enum

Add notice types related to packet filter errors.

PacketFilter::Compile_Failure: This notice is generated if a packet filter cannot be compiled.
PacketFilter::Install_Failure: Generated if a packet filter fails to install.
PacketFilter::Too_Long_To_Compile_Filter: Generated when a notice takes too long to compile.

PcapFilterID: enum

Hooks

PacketFilter::log_policy: Log::PolicyHook

A default logging policy hook for the stream.

Functions

`PacketFilter::exclude`: `function`	Install a BPF filter to exclude some traffic.
`PacketFilter::exclude_for`: `function`	Install a temporary filter to traffic which should not be passed through the BPF filter.
`PacketFilter::install`: `function`	Call this function to build and install a new dynamically built packet filter.
`PacketFilter::register_filter_plugin`: `function`	API function to register a new plugin for dynamic restriction filters.
`PacketFilter::remove_exclude`: `function`	Remove a previously added exclude filter fragment by name.

Detailed Interface

Redefinable Options

PacketFilter::default_capture_filter 

Type: string
Attributes: &redef
Default: "ip or not ip"

The BPF filter that is used by default to define what traffic should be captured. Filters defined in restrict_filters will still be applied to reduce the captured traffic.

PacketFilter::enable_auto_protocol_capture_filters 

Type: bool
Attributes: &redef
Default: F

Enables the old filtering approach of “only watch common ports for analyzed protocols”.

Unless you know what you are doing, leave this set to F.

PacketFilter::max_filter_compile_time 

Type: interval
Attributes: &redef
Default: 100.0 msecs

The maximum amount of time that you’d like to allow for BPF filters to compile. If this time is exceeded, compensation measures may be taken by the framework to reduce the filter size. This threshold being crossed also results in the PacketFilter::Too_Long_To_Compile_Filter notice.

PacketFilter::restricted_filter 

Type: string
Attributes: &redef
Default: ""

Filter string which is unconditionally and’ed to the beginning of every dynamically built filter. This is mostly used when a custom filter is being used but MPLS or VLAN tags are on the traffic.

PacketFilter::unrestricted_filter 

Type: string
Attributes: &redef
Default: ""

Filter string which is unconditionally or’ed to the beginning of every dynamically built filter.

State Variables

PacketFilter::current_filter 

Type: string
Default: "<not set yet>"

This is where the default packet filter is stored and it should not normally be modified by users.

Types

PacketFilter::FilterPlugin 

Type

record

func: function ()void: A function that is directly called when generating the complete filter.

A data structure to represent filter generating plugins.

PacketFilter::Info 

Type

record

ts: time &log: The time at which the packet filter installation attempt was made.
node: string &log &optional: This is a string representation of the node that applied this packet filter. It’s mostly useful in the context of dynamically changing filters on clusters.
filter: string &log: The packet filter that is being set.
init: bool &log &default = F &optional: Indicate if this is the filter set during initialization.
success: bool &log &default = T &optional: Indicate if the filter was applied successfully.
failure_reason: string &log &optional: A string reason why the filter failed to be created/installed.

The record type defining columns to be logged in the packet filter logging stream.

Hooks

PacketFilter::log_policy 

Type: Log::PolicyHook

A default logging policy hook for the stream.

Functions

PacketFilter::exclude 

Type: function (filter_id: string, filter: string) : bool

Install a BPF filter to exclude some traffic. The filter should positively match what is to be excluded, it will be wrapped in a “not”.

Parameters

filter_id – An arbitrary string that can be used to identify the filter.
filter – A BPF expression of traffic that should be excluded.

Returns

A boolean value to indicate if the filter was successfully installed or not.

PacketFilter::exclude_for 

Type: function (filter_id: string, filter: string, span: interval) : bool

Install a temporary filter to traffic which should not be passed through the BPF filter. The filter should match the traffic you don’t want to see (it will be wrapped in a “not” condition).

Parameters

filter_id – An arbitrary string that can be used to identify the filter.
filter – A BPF expression of traffic that should be excluded.
length – The duration for which this filter should be put in place.

Returns

A boolean value to indicate if the filter was successfully installed or not.

PacketFilter::install 

Type: function () : bool

Call this function to build and install a new dynamically built packet filter.

PacketFilter::register_filter_plugin 

Type: function (fp: PacketFilter::FilterPlugin) : void

API function to register a new plugin for dynamic restriction filters.

PacketFilter::remove_exclude 

Type: function (filter_id: string) : bool

Remove a previously added exclude filter fragment by name. The traffic that was being filtered will be allowed through the filter after calling this function.

Parameters: filter_id – The name given to the filter fragment which you’d like to remove.
Returns: A boolean value to indicate if a filter fragment with the given name actually installed.