main.zeek

NetControl

Zeek’s NetControl framework.

This plugin-based framework allows to control the traffic that Zeek monitors as well as, if having access to the forwarding path, the traffic the network forwards. By default, the framework lets everything through, to both Zeek itself as well as on the network. Scripts can then add rules to impose restrictions on entities, such as specific connections or IP addresses.

This framework has two APIs: a high-level and low-level. The high-level API provides convenience functions for a set of common operations. The low-level API provides full flexibility.

Namespace: NetControl
Imports: base/frameworks/netcontrol/plugin.zeek, base/frameworks/netcontrol/types.zeek

Summary

Types

`NetControl::Info`: `record`	The record type defining the column fields of the NetControl log.
`NetControl::InfoCategory`: `enum`	Type of an entry in the NetControl log.
`NetControl::InfoState`: `enum`	State of an entry in the NetControl log.

Redefinitions

Log::ID: enum

The framework’s logging stream identifier.

NetControl::LOG

NetControl::Rule: record

New Fields

NetControl::Rule

_plugin_ids: set [count] &default = { } &optional: Internally set to the plugins handling the rule.
_active_plugin_ids: set [count] &default = { } &optional: Internally set to the plugins on which the rule is currently active.
_no_expire_plugins: set [count] &default = { } &optional: Internally set to plugins where the rule should not be removed upon timeout.
_added: bool &default = F &optional: Track if the rule was added successfully by all responsible plugins.

Events

`NetControl::init`: `event`	Event that is used to initialize plugins.
`NetControl::init_done`: `event`	Event that is raised once all plugins activated in `NetControl::init` have finished their initialization.
`NetControl::log_netcontrol`: `event`	Event that can be handled to access the `NetControl::Info` record as it is sent on to the logging framework.
`NetControl::rule_added`: `event`	Confirms that a rule was put in place by a plugin.
`NetControl::rule_destroyed`: `event`	This event is raised when a rule is deleted from the NetControl framework, because it is no longer in use.
`NetControl::rule_error`: `event`	Reports an error when operating on a rule.
`NetControl::rule_exists`: `event`	Signals that a rule that was supposed to be put in place was already existing at the specified plugin.
`NetControl::rule_new`: `event`	This event is raised when a new rule is created by the NetControl framework due to a call to add_rule.
`NetControl::rule_removed`: `event`	Reports that a plugin reports a rule was removed due to a remove_rule function call.
`NetControl::rule_timeout`: `event`	Reports that a rule was removed from a plugin due to a timeout.

Hooks

`NetControl::log_policy`: `Log::PolicyHook`	A default logging policy hook for the stream.
`NetControl::rule_policy`: `hook`	Hook that allows the modification of rules passed to add_rule before they are passed on to the plugins.

Functions

`NetControl::activate`: `function`	Activates a plugin.
`NetControl::add_rule`: `function`	Installs a rule.
`NetControl::clear`: `function`	Flushes all state by calling `NetControl::remove_rule` on all currently active rules.
`NetControl::delete_rule`: `function`	Deletes a rule without removing it from the backends to which it has been added before.
`NetControl::find_rules_addr`: `function`	Searches all rules affecting a certain IP address.
`NetControl::find_rules_subnet`: `function`	Searches all rules affecting a certain subnet.
`NetControl::plugin_activated`: `function`	Function called by plugins once they finished their activation.
`NetControl::quarantine_host`: `function`	Quarantines a host.
`NetControl::redirect_flow`: `function`	Redirects a uni-directional flow to another port.
`NetControl::remove_rule`: `function`	Removes a rule.
`NetControl::whitelist_address`: `function`	Allows all traffic involving a specific IP address to be forwarded.
`NetControl::whitelist_subnet`: `function`	Allows all traffic involving a specific IP subnet to be forwarded.

Detailed Interface

Types

NetControl::Info 

Type

record

ts: time &log: Time at which the recorded activity occurred.
rule_id: string &log &optional: ID of the rule; unique during each Zeek run.
category: NetControl::InfoCategory &log &optional: Type of the log entry.
cmd: string &log &optional: The command the log entry is about.
state: NetControl::InfoState &log &optional: State the log entry reflects.
action: string &log &optional: String describing an action the entry is about.
target: NetControl::TargetType &log &optional: The target type of the action.
entity_type: string &log &optional: Type of the entity the log entry is about.
entity: string &log &optional: String describing the entity the log entry is about.
mod: string &log &optional: String describing the optional modification of the entry (e.h. redirect)
msg: string &log &optional: String with an additional message.
priority: int &log &optional: Number describing the priority of the log entry.
expire: interval &log &optional: Expiry time of the log entry.
location: string &log &optional: Location where the underlying action was triggered.
plugin: string &log &optional: Plugin triggering the log entry.

The record type defining the column fields of the NetControl log.

NetControl::InfoCategory 

Type

enum

NetControl::MESSAGE: A log entry reflecting a framework message.

NetControl::ERROR: A log entry reflecting a framework message.

NetControl::RULE: A log entry about a rule.

Type of an entry in the NetControl log.

NetControl::InfoState 

Type

enum

NetControl::REQUESTED: The request to add/remove a rule was sent to the respective backend.

NetControl::SUCCEEDED: A rule was successfully added by a backend.

NetControl::EXISTS: A backend reported that a rule was already existing.

NetControl::FAILED: A rule addition failed.

NetControl::REMOVED: A rule was successfully removed by a backend.

NetControl::TIMEOUT: A rule timeout was triggered by the NetControl framework or a backend.

State of an entry in the NetControl log.

Events

NetControl::init 

Type: event ()

Event that is used to initialize plugins. Place all plugin initialization related functionality in this event.

NetControl::init_done 

Type: event ()

Event that is raised once all plugins activated in NetControl::init have finished their initialization.

NetControl::log_netcontrol 

Type: event (rec: NetControl::Info)

Event that can be handled to access the NetControl::Info record as it is sent on to the logging framework.

NetControl::rule_added 

Type: event (r: NetControl::Rule, p: NetControl::PluginState, msg: string &default = "" &optional)

Confirms that a rule was put in place by a plugin.

Parameters

r – The rule now in place.
p – The state for the plugin that put it into place.
msg – An optional informational message by the plugin.

NetControl::rule_destroyed 

Type: event (r: NetControl::Rule)

This event is raised when a rule is deleted from the NetControl framework, because it is no longer in use. This can be caused by the fact that a rule was removed by all plugins to which it was added, by the fact that it timed out or due to rule errors.

To get the cause of a rule remove, catch the rule_removed, rule_timeout and rule_error events.

NetControl::rule_error 

Type: event (r: NetControl::Rule, p: NetControl::PluginState, msg: string &default = "" &optional)

Reports an error when operating on a rule.

Parameters

r – The rule that encountered an error.
p – The state for the plugin that reported the error.
msg – An optional informational message by the plugin.

NetControl::rule_exists 

Type: event (r: NetControl::Rule, p: NetControl::PluginState, msg: string &default = "" &optional)

Signals that a rule that was supposed to be put in place was already existing at the specified plugin. Rules that already have been existing continue to be tracked like normal, but no timeout calls will be sent to the specified plugins. Removal of the rule from the hardware can still be forced by manually issuing a remove_rule call.

Parameters

r – The rule that was already in place.
p – The plugin that reported that the rule already was in place.
msg – An optional informational message by the plugin.

NetControl::rule_new 

Type: event (r: NetControl::Rule)

This event is raised when a new rule is created by the NetControl framework due to a call to add_rule. From this moment, until the rule_destroyed event is raised, the rule is tracked internally by the NetControl framework.

Note that this event does not mean that a rule was successfully added by any backend; it just means that the rule has been accepted and addition to the specified backend is queued. To get information when rules are actually installed by the hardware, use the rule_added, rule_exists, rule_removed, rule_timeout and rule_error events.

NetControl::rule_removed 

Type: event (r: NetControl::Rule, p: NetControl::PluginState, msg: string &default = "" &optional)

Reports that a plugin reports a rule was removed due to a remove_rule function call.

Parameters

r – The rule now removed.
p – The state for the plugin that had the rule in place and now removed it.
msg – An optional informational message by the plugin.

NetControl::rule_timeout 

Type: event (r: NetControl::Rule, i: NetControl::FlowInfo, p: NetControl::PluginState)

Reports that a rule was removed from a plugin due to a timeout.

Parameters

r – The rule now removed.
i – Additional flow information, if supported by the protocol.
p – The state for the plugin that had the rule in place and now removed it.
msg – An optional informational message by the plugin.

Hooks

NetControl::log_policy 

Type: Log::PolicyHook

A default logging policy hook for the stream.

NetControl::rule_policy 

Type: hook (r: NetControl::Rule) : bool

Hook that allows the modification of rules passed to add_rule before they are passed on to the plugins. If one of the hooks uses break, the rule is ignored and not passed on to any plugin.

Parameters: r – The rule to be added.

Functions

NetControl::activate 

Type: function (p: NetControl::PluginState, priority: int) : void

Activates a plugin.

Parameters

p – The plugin to activate.
priority – The higher the priority, the earlier this plugin will be checked whether it supports an operation, relative to other plugins.

NetControl::add_rule 

Type: function (r: NetControl::Rule) : string

Installs a rule.

Parameters: r – The rule to install.
Returns: If successful, returns an ID string unique to the rule that can later be used to refer to it. If unsuccessful, returns an empty string. The ID is also assigned to r$id. Note that “successful” means “a plugin knew how to handle the rule”, it doesn’t necessarily mean that it was indeed successfully put in place, because that might happen asynchronously and thus fail only later.

NetControl::clear 

Type: function () : void

Flushes all state by calling NetControl::remove_rule on all currently active rules.

NetControl::delete_rule 

Type: function (id: string, reason: string &default = "" &optional) : bool

Deletes a rule without removing it from the backends to which it has been added before. This means that no messages will be sent to the switches to which the rule has been added; if it is not removed from them by a separate mechanism, it will stay installed and not be removed later.

Parameters

id – The rule to delete, specified as the ID returned by NetControl::add_rule.
reason – Optional string argument giving information on why the rule was deleted.

Returns

True if removal is successful, or sent to manager. False if the rule could not be found.

NetControl::find_rules_addr 

Type: function (ip: addr) : vector of NetControl::Rule

Searches all rules affecting a certain IP address.

This function works on both the manager and workers of a cluster. Note that on the worker, the internal rule variables (starting with _) will not reflect the current state.

Parameters: ip – The ip address to search for.
Returns: vector of all rules affecting the IP address.

NetControl::find_rules_subnet 

Type: function (sn: subnet) : vector of NetControl::Rule

Searches all rules affecting a certain subnet.

A rule affects a subnet, if it covers the whole subnet. Note especially that this function will not reveal all rules that are covered by a subnet.

For example, a search for 192.168.17.0/8 will reveal a rule that exists for 192.168.0.0/16, since this rule affects the subnet. However, it will not reveal a more specific rule for 192.168.17.1/32, which does not directly affect the whole subnet.

This function works on both the manager and workers of a cluster. Note that on the worker, the internal rule variables (starting with _) will not reflect the current state.

Parameters: sn – The subnet to search for.
Returns: vector of all rules affecting the subnet.

NetControl::plugin_activated 

Type: function (p: NetControl::PluginState) : void

Function called by plugins once they finished their activation. After all plugins defined in zeek_init finished to activate, rules will start to be sent to the plugins. Rules that scripts try to set before the backends are ready will be discarded.

NetControl::quarantine_host 

Type: function (infected: addr, dns: addr, quarantine: addr, t: interval, location: string &default = "" &optional) : vector of string

Quarantines a host. This requires a special quarantine server, which runs a HTTP server explaining the quarantine and a DNS server which resolves all requests to the quarantine server. DNS queries from the host to the network DNS server will be rewritten and will be sent to the quarantine server instead. Only http communication infected to quarantinehost is allowed. All other network communication is blocked.

Parameters

infected – the host to quarantine.
dns – the network dns server.
quarantine – the quarantine server running a dns and a web server.
t – how long to leave the quarantine in place.

Returns

Vector of inserted rules on success, empty list on failure.

NetControl::redirect_flow 

Type: function (f: flow_id, out_port: count, t: interval, location: string &default = "" &optional) : string

Redirects a uni-directional flow to another port.

Parameters

f – The flow to redirect.
out_port – Port to redirect the flow to.
t – How long to leave the redirect in place, with 0 being indefinitely.
location – An optional string describing where the redirect was triggered.

Returns

The id of the inserted rule on success and zero on failure.

NetControl::remove_rule 

Type: function (id: string, reason: string &default = "" &optional) : bool

Removes a rule.

Parameters

id – The rule to remove, specified as the ID returned by NetControl::add_rule.
reason – Optional string argument giving information on why the rule was removed.

Returns

True if successful, the relevant plugin indicated that it knew how to handle the removal. Note that again “success” means the plugin accepted the removal. It might still fail to put it into effect, as that might happen asynchronously and thus go wrong at that point.

NetControl::whitelist_address 

Type: function (a: addr, t: interval, location: string &default = "" &optional) : string

Allows all traffic involving a specific IP address to be forwarded.

Parameters

a – The address to be whitelisted.
t – How long to whitelist it, with 0 being indefinitely.
location – An optional string describing whitelist was triggered.

Returns

The id of the inserted rule on success and zero on failure.

NetControl::whitelist_subnet 

Type: function (s: subnet, t: interval, location: string &default = "" &optional) : string

Allows all traffic involving a specific IP subnet to be forwarded.

Parameters

s – The subnet to be whitelisted.
t – How long to whitelist it, with 0 being indefinitely.
location – An optional string describing whitelist was triggered.

Returns

The id of the inserted rule on success and zero on failure.