mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
42e4072673
This does not really have many user-facing changes. The one big change is that users now should initialize plugins in the NetControl::init() event instead of bro_init. Once all plugins finished initializing and the NetControl framework starts operations, the NetControl::init_done() event is raised. Rules that are sent to NetControl before the plugins have finished initializing are ignored - this is important when several plugins that require external connections have to be initialized at the beginning. Without this delay, rules could end up at the wrong plugin.
88 lines
3.6 KiB
Text
88 lines
3.6 KiB
Text
|
|
module NetControl;
|
|
|
|
@load ./types
|
|
|
|
export {
|
|
## State for a plugin instance.
|
|
type PluginState: record {
|
|
## Table for a plugin to store custom, instance-specfific state.
|
|
config: table[string] of string &default=table();
|
|
|
|
## Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally.
|
|
_id: count &optional;
|
|
|
|
## Set internally.
|
|
_priority: int &default=+0;
|
|
|
|
## Set internally. Signifies if the plugin has returned that it has activated succesfully
|
|
_activated: bool &default=F;
|
|
};
|
|
|
|
# Definition of a plugin.
|
|
#
|
|
# Generally a plugin needs to implement only what it can support. By
|
|
# returning failure, it indicates that it can't support something and the
|
|
# the framework will then try another plugin, if available; or informn the
|
|
# that the operation failed. If a function isn't implemented by a plugin,
|
|
# that's considered an implicit failure to support the operation.
|
|
#
|
|
# If plugin accepts a rule operation, it *must* generate one of the reporting
|
|
# events ``rule_{added,remove,error}`` to signal if it indeed worked out;
|
|
# this is separate from accepting the operation because often a plugin
|
|
# will only know later (i.e., asynchrously) if that was an error for
|
|
# something it thought it could handle.
|
|
type Plugin: record {
|
|
# Returns a descriptive name of the plugin instance, suitable for use in logging
|
|
# messages. Note that this function is not optional.
|
|
name: function(state: PluginState) : string;
|
|
|
|
## If true, plugin can expire rules itself. If false,
|
|
## framework will manage rule expiration.
|
|
can_expire: bool;
|
|
|
|
# One-time initialization function called when plugin gets registered, and
|
|
# before any other methods are called.
|
|
#
|
|
# If this function is provided, NetControl assumes that the plugin has to
|
|
# perform, potentially lengthy, initialization before the plugin will become
|
|
# active. In this case, the plugin has to call ``NetControl::plugin_activated``,
|
|
# once initialization finishes.
|
|
init: function(state: PluginState) &optional;
|
|
|
|
# One-time finalization function called when a plugin is shutdown; no further
|
|
# functions will be called afterwords.
|
|
done: function(state: PluginState) &optional;
|
|
|
|
# Implements the add_rule() operation. If the plugin accepts the rule,
|
|
# it returns true, false otherwise. The rule will already have its
|
|
# ``id`` field set, which the plugin may use for identification
|
|
# purposes.
|
|
add_rule: function(state: PluginState, r: Rule) : bool &optional;
|
|
|
|
# Implements the remove_rule() operation. This will only be called for
|
|
# rules that the plugins has previously accepted with add_rule(). The
|
|
# ``id`` field will match that of the add_rule() call. Generally,
|
|
# a plugin that accepts an add_rule() should also accept the
|
|
# remove_rule().
|
|
remove_rule: function(state: PluginState, r: Rule) : bool &optional;
|
|
|
|
# A transaction groups a number of operations. The plugin can add them internally
|
|
# and postpone putting them into effect until committed. This allows to build a
|
|
# configuration of multiple rules at once, including replaying a previous state.
|
|
transaction_begin: function(state: PluginState) &optional;
|
|
transaction_end: function(state: PluginState) &optional;
|
|
};
|
|
|
|
# Table for a plugin to store instance-specific configuration information.
|
|
#
|
|
# Note, it would be nicer to pass the Plugin instance to all the below, instead
|
|
# of this state table. However Bro's type resolver has trouble with refering to a
|
|
# record type from inside itself.
|
|
redef record PluginState += {
|
|
## The plugin that the state belongs to. (Defined separately
|
|
## because of cyclic type dependency.)
|
|
plugin: Plugin &optional;
|
|
};
|
|
|
|
}
|