:tocdepth: 3

base/frameworks/analyzer/main.zeek
==================================
.. zeek:namespace:: 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
:zeek:type:`Analyzer::Tag`, such as :zeek:enum:`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 :zeek:type:`AllAnalyzers::Tag` enum
type. This type contains duplicates of all of the :zeek:type:`Analyzer::Tag`,
:zeek:type:`PacketAnalyzer::Tag` and :zeek:type:`Files::Tag` enum values
and can be used for arguments to function/hook/event definitions where they
need to handle any analyzer type. See :zeek:id:`Analyzer::register_for_ports`
for an example.

:Namespace: Analyzer
:Imports: :doc:`base/bif/analyzer.bif.zeek </scripts/base/bif/analyzer.bif.zeek>`, :doc:`base/bif/file_analysis.bif.zeek </scripts/base/bif/file_analysis.bif.zeek>`, :doc:`base/bif/packet_analysis.bif.zeek </scripts/base/bif/packet_analysis.bif.zeek>`, :doc:`base/frameworks/packet-filter/utils.zeek </scripts/base/frameworks/packet-filter/utils.zeek>`

Summary
~~~~~~~
State Variables
###############
============================================================================== ===================================================================
:zeek:id:`Analyzer::disable_all`: :zeek:type:`bool` :zeek:attr:`&redef`        If true, all available analyzers are initially disabled at startup.
:zeek:id:`Analyzer::disabled_analyzers`: :zeek:type:`set` :zeek:attr:`&redef`  A set of analyzers to disable by default at startup.
:zeek:id:`Analyzer::ports`: :zeek:type:`table`                                 A table of ports mapped to analyzers that handle those ports.
:zeek:id:`Analyzer::requested_analyzers`: :zeek:type:`set` :zeek:attr:`&redef` A set of protocol, packet or file analyzer tags requested to
                                                                               be enabled during startup.
============================================================================== ===================================================================

Events
######
======================================================== ========================================================================
:zeek:id:`Analyzer::analyzer_failed`: :zeek:type:`event` Event that is raised when an analyzer raised a service violation and was
                                                         removed.
======================================================== ========================================================================

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


Detailed Interface
~~~~~~~~~~~~~~~~~~
State Variables
###############
.. zeek:id:: Analyzer::disable_all
   :source-code: base/frameworks/analyzer/main.zeek 28 28

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``F``

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

.. zeek:id:: Analyzer::disabled_analyzers
   :source-code: base/frameworks/analyzer/main.zeek 156 156

   :Type: :zeek:type:`set` [:zeek:type:`AllAnalyzers::Tag`]
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: Analyzer::ports
   :source-code: base/frameworks/analyzer/main.zeek 164 164

   :Type: :zeek:type:`table` [:zeek:type:`AllAnalyzers::Tag`] of :zeek:type:`set` [:zeek:type:`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).

.. zeek:id:: Analyzer::requested_analyzers
   :source-code: base/frameworks/analyzer/main.zeek 174 174

   :Type: :zeek:type:`set` [:zeek:type:`AllAnalyzers::Tag`]
   :Attributes: :zeek:attr:`&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 :zeek:see:`Analyzer::disable_all`, this set
   set allows to record analyzers to be enabled during Zeek startup.
   
   This set can be added to via :zeek:see:`redef`.

Events
######
.. zeek:id:: Analyzer::analyzer_failed
   :source-code: base/frameworks/analyzer/main.zeek 191 191

   :Type: :zeek:type:`event` (ts: :zeek:type:`time`, atype: :zeek:type:`AllAnalyzers::Tag`, info: :zeek:type:`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.
   

   :param ts: time at which the violation occurred
   

   :param atype: atype: The analyzer tag, such as ``Analyzer::ANALYZER_HTTP``.
   

   :param info: Details about the violation. This record should include a :zeek:type:`connection`

Functions
#########
.. zeek:id:: Analyzer::all_registered_ports
   :source-code: base/frameworks/analyzer/main.zeek 265 268

   :Type: :zeek:type:`function` () : :zeek:type:`table` [:zeek:type:`AllAnalyzers::Tag`] of :zeek:type:`set` [:zeek:type:`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.

.. zeek:id:: Analyzer::analyzer_to_bpf
   :source-code: base/frameworks/analyzer/main.zeek 304 314

   :Type: :zeek:type:`function` (tag: :zeek:type:`Analyzer::Tag`) : :zeek:type:`string`

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

   :param tag: The analyzer tag.
   

   :returns: BPF filter string.

.. zeek:id:: Analyzer::disable_analyzer
   :source-code: base/frameworks/analyzer/main.zeek 224 233

   :Type: :zeek:type:`function` (tag: :zeek:type:`AllAnalyzers::Tag`) : :zeek:type:`bool`

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

   :param tag: The tag of the analyzer to disable.
   

   :returns: True if the analyzer was successfully disabled.

.. zeek:id:: Analyzer::enable_analyzer
   :source-code: base/frameworks/analyzer/main.zeek 213 222

   :Type: :zeek:type:`function` (tag: :zeek:type:`AllAnalyzers::Tag`) : :zeek:type:`bool`

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

   :param tag: The tag of the analyzer to enable.
   

   :returns: True if the analyzer was successfully enabled.

.. zeek:id:: Analyzer::get_bpf
   :source-code: base/frameworks/analyzer/main.zeek 316 324

   :Type: :zeek:type:`function` () : :zeek:type:`string`

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

.. zeek:id:: Analyzer::get_tag
   :source-code: base/frameworks/analyzer/main.zeek 293 296

   :Type: :zeek:type:`function` (name: :zeek:type:`string`) : :zeek:type:`AllAnalyzers::Tag`

   Translates an analyzer's name to a tag enum value.
   
   The analyzer is assumed to exist; call
   :zeek:see:`Analyzer::has_tag` first to verify that name is a
   valid analyzer name.
   

   :param name: The analyzer name.
   

   :returns: The analyzer tag corresponding to the name.

.. zeek:id:: Analyzer::has_tag
   :source-code: base/frameworks/analyzer/main.zeek 288 291

   :Type: :zeek:type:`function` (name: :zeek:type:`string`) : :zeek:type:`bool`

   Check whether the given analyzer name exists.
   
   This can be used before calling :zeek:see:`Analyzer::get_tag` to
   verify that the given name as string is a valid analyzer name.
   

   :param name: The analyzer name.
   

   :returns: True if the given name is a valid analyzer, else false.

.. zeek:id:: Analyzer::kind
   :source-code: base/frameworks/analyzer/main.zeek 275 286

   :Type: :zeek:type:`function` (atype: :zeek:type:`AllAnalyzers::Tag`) : :zeek:type:`string`

   Translates an analyzer type to a string with the analyzer's type.
   
   Possible values are "protocol", "packet", "file", or "unknown".
   

   :param tag: The analyzer tag.
   

   :returns: The analyzer kind corresponding to the tag.

.. zeek:id:: Analyzer::name
   :source-code: base/frameworks/analyzer/main.zeek 270 273

   :Type: :zeek:type:`function` (atype: :zeek:type:`AllAnalyzers::Tag`) : :zeek:type:`string`

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

   :param tag: The analyzer tag.
   

   :returns: The analyzer name corresponding to the tag.

.. zeek:id:: Analyzer::register_for_port
   :source-code: base/frameworks/analyzer/main.zeek 248 258

   :Type: :zeek:type:`function` (tag: :zeek:type:`Analyzer::Tag`, p: :zeek:type:`port`) : :zeek:type:`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.
   

   :param tag: The tag of the analyzer.
   

   :param p: The well-known port to associate with the analyzer.
   

   :returns: True if the port was successfully registered.

.. zeek:id:: Analyzer::register_for_ports
   :source-code: base/frameworks/analyzer/main.zeek 235 246

   :Type: :zeek:type:`function` (tag: :zeek:type:`Analyzer::Tag`, ports: :zeek:type:`set` [:zeek:type:`port`]) : :zeek:type:`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.
   

   :param tag: The tag of the analyzer.
   

   :param ports: The set of well-known ports to associate with the analyzer.
   

   :returns: True if the ports were successfully registered.

.. zeek:id:: Analyzer::registered_ports
   :source-code: base/frameworks/analyzer/main.zeek 260 263

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

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

   :param tag: The tag of the analyzer.
   

   :returns: The set of ports.

.. zeek:id:: Analyzer::schedule_analyzer
   :source-code: base/frameworks/analyzer/main.zeek 299 302

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

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

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

   :param resp: The IP address responding to a connection from *orig*.
   

   :param resp_p: The destination port at *resp*.
   

   :param analyzer: The analyzer ID.
   

   :param tout: A timeout interval after which the scheduling request will be
         discarded if the connection has not yet been seen.
   

   :returns: True if successful.


