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.

Copyright 2016, The Bro Project. Last updated on January 10, 2019. Created using Sphinx 1.7.5.