base/frameworks/analyzer/main.bro

Analyzer

Framework for managing Bro’s protocol analyzers.

The analyzer framework allows to dynamically enable or disable analyzers, as well as to manage the well-known ports which automatically activate a particular analyzer for new connections.

Protocol analyzers are identified by unique tags of type Analyzer::Tag, such as Analyzer::ANALYZER_HTTP. These tags are defined internally by the analyzers themselves, and documented in their analyzer-specific description along with the events that they generate.

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

Summary

State Variables

Analyzer::disable_all: bool &redef	If true, all available analyzers are initially disabled at startup.
Analyzer::disabled_analyzers: set &redef	A set of analyzers to disable by default at startup.

Functions

Analyzer::all_registered_ports: function	Returns a table of all ports-to-analyzer mappings currently registered.
Analyzer::analyzer_to_bpf: function	Automatically creates a BPF filter for the specified protocol based on the data supplied for the protocol through the Analyzer::register_for_ports function.
Analyzer::disable_analyzer: function	Disables an analyzer.
Analyzer::enable_analyzer: function	Enables an analyzer.
Analyzer::get_bpf: function	Create a BPF filter which matches all of the ports defined by the various protocol analysis scripts as “registered ports” for the protocol.
Analyzer::get_tag: function	Translates an analyzer’s name to a tag enum value.
Analyzer::name: function	Translates an analyzer type to a string with the analyzer’s name.
Analyzer::register_for_port: function	Registers an individual well-known port for an analyzer.
Analyzer::register_for_ports: function	Registers a set of well-known ports for an analyzer.
Analyzer::registered_ports: function	Returns a set of all well-known ports currently registered for a specific analyzer.
Analyzer::schedule_analyzer: function	Schedules an analyzer for a future connection originating from a given IP address and port.

Detailed Interface

State Variables

Analyzer::disable_all

Type:bool Attributes:&redef Default:F

If true, all available analyzers are initially disabled at startup. One can then selectively enable them with Analyzer::enable_analyzer.

Analyzer::disabled_analyzers

Type:set [Analyzer::Tag] Attributes:&redef Default:

{
   Analyzer::ANALYZER_TCPSTATS,
   Analyzer::ANALYZER_BACKDOOR,
   Analyzer::ANALYZER_STEPPINGSTONE,
   Analyzer::ANALYZER_INTERCONN
}

A set of analyzers to disable by default at startup. The default set contains legacy analyzers that are no longer supported.

Functions

Analyzer::all_registered_ports

Type:function () : table [Analyzer::Tag] of set [port]

Returns a table of all ports-to-analyzer mappings currently registered.

Returns:A table mapping each analyzer to the set of ports registered for it.

Analyzer::analyzer_to_bpf

Type:function (tag: Analyzer::Tag) : string

Automatically creates a BPF filter for the specified protocol based on the data supplied for the protocol through the Analyzer::register_for_ports function.

Tag:The analyzer tag. Returns:BPF filter string.

Analyzer::disable_analyzer

Type:function (tag: Analyzer::Tag) : bool

Disables an analyzer. Once disabled, the analyzer will not be used further for analysis of future connections.

Tag:The tag of the analyzer to disable. Returns:True if the analyzer was successfully disabled.

Analyzer::enable_analyzer

Type:function (tag: Analyzer::Tag) : bool

Enables an analyzer. Once enabled, the analyzer may be used for analysis of future connections as decided by Bro’s dynamic protocol detection.

Tag:The tag of the analyzer to enable. Returns:True if the analyzer was successfully enabled.

Analyzer::get_bpf

Type:function () : string

Create a BPF filter which matches all of the ports defined by the various protocol analysis scripts as “registered ports” for the protocol.

Analyzer::get_tag

Type:function (name: string) : Analyzer::Tag

Translates an analyzer’s name to a tag enum value.

Name:The analyzer name. Returns:The analyzer tag corresponding to the name.

Analyzer::name

Type:function (atype: Analyzer::Tag) : string

Translates an analyzer type to a string with the analyzer’s name.

Tag:The analyzer tag. Returns:The analyzer name corresponding to the tag.

Analyzer::register_for_port

Type:function (tag: Analyzer::Tag, p: port) : bool

Registers an individual well-known port for an analyzer. If a future connection on this port is seen, the analyzer will be automatically assigned to parsing it. The function adds to all ports already registered, it doesn’t replace them.

Tag:The tag of the analyzer. P:The well-known port to associate with the analyzer. Returns:True if the port was successfully registered.

Analyzer::register_for_ports

Type:function (tag: Analyzer::Tag, ports: set [port]) : bool

Registers a set of well-known ports for an analyzer. If a future connection on one of these ports is seen, the analyzer will be automatically assigned to parsing it. The function adds to all ports already registered, it doesn’t replace them.

Tag:The tag of the analyzer. Ports:The set of well-known ports to associate with the analyzer. Returns:True if the ports were successfully registered.

Analyzer::registered_ports

Type:function (tag: Analyzer::Tag) : set [port]

Returns a set of all well-known ports currently registered for a specific analyzer.

Tag:The tag of the analyzer. Returns:The set of ports.

Analyzer::schedule_analyzer

Type:function (orig: addr, resp: addr, resp_p: port, analyzer: Analyzer::Tag, tout: interval) : bool

Schedules an analyzer for a future connection originating from a given IP address and port.

Orig:The IP address originating a connection in the future. 0.0.0.0 can be used as a wildcard to match any originator address. Resp:The IP address responding to a connection from orig. Resp_p:The destination port at resp. Analyzer:The analyzer ID. Tout:A timeout interval after which the scheduling request will be discarded if the connection has not yet been seen. Returns:True if successful.