diff --git a/scripts/base/frameworks/analyzer/main.bro b/scripts/base/frameworks/analyzer/main.bro index 8d2df76e4f..50ff6b775d 100644 --- a/scripts/base/frameworks/analyzer/main.bro +++ b/scripts/base/frameworks/analyzer/main.bro @@ -1,43 +1,90 @@ - +##! 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 active a particular +##! analyzer for new connections. +##! +##! Protocol analyzers are identified by unique tags of type +##! :bro:type:`Analyzer::Tag`, such as :bro:enum:`Analyzer::ANALYZER_HTTP` and +##! :bro: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. +##! +##! .. todo: ``The ANALYZER_*`` are in fact not yet documented, we need to add that +##! to Broxygen. module Analyzer; -# Analyzer::Tag is defined in types.bif, and automatically extended by plugins -# as they are loaded. - export { - ## XXX + ## If true, all available analyzers are initially disabled at startup. One can + ## then selectively enable them with :bro:id:`enable_analyzer`. global disable_all = F &redef; - ## XXX. + ## 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. global enable_analyzer: function(tag: Analyzer::Tag) : bool; - ## XXX. + ## 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. global disable_analyzer: function(tag: Analyzer::Tag) : bool; - ## XXX. + ## 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 sucessfully registered. global register_for_ports: function(tag: Analyzer::Tag, ports: set[port]) : bool; - ## XXX. + ## Registers an individual well-known port for an analyzer. If a future connection + ## on this 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. + ## + ## p: The well-known port to associate with the analyzer. + ## + ## Returns: True if the port was sucessfully registered. global register_for_port: function(tag: Analyzer::Tag, p: port) : bool; - ## XXX. + ## 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. global registered_ports: function(tag: Analyzer::Tag) : set[port]; - ## XXX + ## 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. global all_registered_ports: function() : table[Analyzer::Tag] of set[port]; - ## Translate an analyzer type to an ASCII string. + ## Translates an analyzer type to a string with the analyzer's. ## - ## atype: The analyzer tag. + ## tag: The analyzer tag. ## - ## Returns: The analyzer *aid* as string. - global name: function(atype: Analyzer::Tag) : string; + ## Returns: The analyzer name corresponding to the tag. + global name: function(tag: Analyzer::Tag) : string; - ## Schedules an analyzer for a future connection from a given IP address and - ## port. The function ignores the scheduling request if the connection did - ## not occur within the specified time interval. + ## 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. + ## 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*. ## @@ -45,13 +92,15 @@ export { ## ## analyzer: The analyzer ID. ## - ## tout: The timeout interval after which to ignore the scheduling request. + ## tout: A timeout interval after which the scheduling request will be + ## discarded if the connection has not yet been seen. ## ## Returns: True if succesful. global schedule_analyzer: function(orig: addr, resp: addr, resp_p: port, analyzer: Analyzer::Tag, tout: interval) : bool; - ## Analyzers to disable at startup. + ## A set of analyzers to disable by at startup. The default set + ## contains legacy analyzers that are no longer supported. global disabled_analyzers: set[Analyzer::Tag] = { ANALYZER_INTERCONN, ANALYZER_STEPPINGSTONE, diff --git a/src/analyzer/Analyzer.h b/src/analyzer/Analyzer.h index f509f79941..3800307c82 100644 --- a/src/analyzer/Analyzer.h +++ b/src/analyzer/Analyzer.h @@ -28,23 +28,39 @@ typedef list analyzer_list; typedef uint32 ID; typedef void (Analyzer::*analyzer_timer_func)(double t); - /** - * XXX - */ +/** + * Class to receive processed output from an anlyzer. + */ class OutputHandler { public: + /** + * Destructor. + */ virtual ~OutputHandler() { } + /** + * Hook for receiving packet data. Parameters are the same as for + * Analyzer::DeliverPacket(). + */ virtual void DeliverPacket(int len, const u_char* data, bool orig, int seq, const IP_Hdr* ip, int caplen) { } + + /** + * Hook for receiving stream data. Parameters are the same as for + * Analyzer::DeliverStream(). + */ virtual void DeliverStream(int len, const u_char* data, bool orig) { } + + /** + * Hook for receiving notification of stream gaps. Parameters are the + * same as for Analyzer::Undelivered(). + */ virtual void Undelivered(int seq, int len, bool orig) { } }; - /** * Main analyzer interface. *