base/frameworks/netcontrol/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::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_added_policy: hook

Hook that allows the modification of rule states after they are returned from the plugins and have been added to the rules database.

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_added_policy
Type

hook (r: NetControl::Rule, p: NetControl::PluginState, exists: bool, msg: string) : bool

Hook that allows the modification of rule states after they are returned from the plugins and have been added to the rules database. This allows low-level modification of the handling of rules like, e.g., changing rule expiration depending on context.

Parameters
  • r – The rule now in place.

  • p – The state for the plugin that put it into place.

  • exists – If the adding plugin flagged the rule as already existing.

  • msg – An optional informational message by the plugin.

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.