main.zeek

Analyzer

Framework for managing Zeek’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.

Analyzer tags are also inserted into a global AllAnalyzers::Tag enum type. This type contains duplicates of all of the Analyzer::Tag, PacketAnalyzer::Tag and Files::Tag enum values and can be used for arguments to function/hook/event definitions where they need to handle any analyzer type. See Analyzer::register_for_ports for an example.

Namespace:: Analyzer
Imports:: base/bif/analyzer.bif.zeek, base/bif/file_analysis.bif.zeek, base/bif/packet_analysis.bif.zeek, base/frameworks/packet-filter/utils.zeek

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.
`Analyzer::ports`: `table`	A table of ports mapped to analyzers that handle those ports.
`Analyzer::requested_analyzers`: `set` `&redef`	A set of protocol, packet or file analyzer tags requested to be enabled during startup.

Events

Analyzer::analyzer_failed: event

Event that is raised when an analyzer raised a service violation and was removed.

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::has_tag`: `function`	Check whether the given analyzer name exists.
`Analyzer::kind`: `function`	Translates an analyzer type to a string with the analyzer’s type.
`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 [AllAnalyzers::Tag]

Attributes:

&redef

Default:

{
   AllAnalyzers::ANALYZER_ANALYZER_TCPSTATS
}

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

Analyzer::ports 

Type:: table [AllAnalyzers::Tag] of set [port]
Default:: {}

A table of ports mapped to analyzers that handle those ports. This is used by BPF filtering and DPD. Session analyzers can add to this using Analyzer::register_for_port(s) and packet analyzers can add to this using PacketAnalyzer::register_for_port(s).

Analyzer::requested_analyzers 

Type:: set [AllAnalyzers::Tag]
Attributes:: &redef
Default:: {}

A set of protocol, packet or file analyzer tags requested to be enabled during startup.

By default, all analyzers in Zeek are enabled. When all analyzers are disabled through Analyzer::disable_all, this set set allows to record analyzers to be enabled during Zeek startup.

This set can be added to via redef.

Events

Analyzer::analyzer_failed 

Type:: event (ts: time, atype: AllAnalyzers::Tag, info: AnalyzerViolationInfo)

Event that is raised when an analyzer raised a service violation and was removed.

The event is also raised if the analyzer already was no longer active by the time that the violation was handled - so if it happens at the very end of a connection.

Currently this event is only raised for protocol analyzers, as packet and file analyzers are never actively removed/disabled.

Parameters:

ts – time at which the violation occurred
atype – atype: The analyzer tag, such as Analyzer::ANALYZER_HTTP.
info – Details about the violation. This record should include a connection

Functions

Analyzer::all_registered_ports 

Type:: function () : table [AllAnalyzers::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.

Parameters:: tag – The analyzer tag.
Returns:: BPF filter string.

Analyzer::disable_analyzer 

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

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

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

Analyzer::enable_analyzer 

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

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

Parameters:: 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) : AllAnalyzers::Tag

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

The analyzer is assumed to exist; call Analyzer::has_tag first to verify that name is a valid analyzer name.

Parameters:: name – The analyzer name.
Returns:: The analyzer tag corresponding to the name.

Analyzer::has_tag 

Type:: function (name: string) : bool

Check whether the given analyzer name exists.

This can be used before calling Analyzer::get_tag to verify that the given name as string is a valid analyzer name.

Parameters:: name – The analyzer name.
Returns:: True if the given name is a valid analyzer, else false.

Analyzer::kind 

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

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

Possible values are “protocol”, “packet”, “file”, or “unknown”.

Parameters:: tag – The analyzer tag.
Returns:: The analyzer kind corresponding to the tag.

Analyzer::name 

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

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

Parameters:: 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.

Parameters:

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, server_ports: set [port], non_server_ports: set [port] &default = { } &optional) : 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.

Parameters:

tag – The tag of the analyzer.
server_ports – The set of well-known server ports to associate with the analyzer. These ports will automatically be added to likely_server_ports.
non_server_ports – The set of well-known non-server ports (e.g., client ports) to associate with the analyzer. These ports will not be added to likely_server_ports.

Returns:

True if the ports were successfully registered.

Analyzer::registered_ports 

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

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

Parameters:: 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.

Parameters:

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.