base/frameworks/packet-filter/main.bro

PacketFilter

This script supports how Bro sets its BPF capture filter. By default Bro 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 Bro scripts with the capture_filters and restrict_filters variables.

Namespace:PacketFilter Imports:base/frameworks/analyzer, base/frameworks/notice, base/frameworks/packet-filter/utils.bro Source File:/scripts/base/frameworks/packet-filter/main.bro

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

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.

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.

The record type defining columns to be logged in the packet filter logging 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”.

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).

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.