base/frameworks/packet-filter/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.

Notice::Type: enum

Add notice types related to packet filter errors.

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.