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¶
The record type defining the column fields of the NetControl log. |
|
Type of an entry in the NetControl log. |
|
State of an entry in the NetControl log. |
Redefinitions¶
The framework’s logging stream identifier. |
|
|
Events¶
Event that is used to initialize plugins. |
|
Event that is raised once all plugins activated in |
|
Event that can be handled to access the |
|
Confirms that a rule was put in place by a plugin. |
|
This event is raised when a rule is deleted from the NetControl framework, because it is no longer in use. |
|
Reports an error when operating on a rule. |
|
Signals that a rule that was supposed to be put in place was already existing at the specified plugin. |
|
This event is raised when a new rule is created by the NetControl framework due to a call to add_rule. |
|
Reports that a plugin reports a rule was removed due to a remove_rule function call. |
|
Reports that a rule was removed from a plugin due to a timeout. |
Hooks¶
A default logging policy hook for the stream. |
|
Hook that allows the modification of rules passed to add_rule before they are passed on to the plugins. |
Functions¶
Activates a plugin. |
|
Installs a rule. |
|
Flushes all state by calling |
|
Deletes a rule without removing it from the backends to which it has been added before. |
|
Searches all rules affecting a certain IP address. |
|
Searches all rules affecting a certain subnet. |
|
Function called by plugins once they finished their activation. |
|
Quarantines a host. |
|
Redirects a uni-directional flow to another port. |
|
Removes a rule. |
|
Allows all traffic involving a specific IP address to be forwarded. |
|
Allows all traffic involving a specific IP subnet to be forwarded. |
Detailed Interface¶
Types¶
- NetControl::Info¶
- Type
-
- 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.
- ts:
The record type defining the column fields of the NetControl log.
- NetControl::InfoCategory¶
- Type
-
- 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
-
- 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
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¶
-
Flushes all state by calling
NetControl::remove_rule
on all currently active rules.
- NetControl::delete_rule¶
-
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
ofNetControl::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
ofNetControl::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 directy 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
ofstring
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¶
-
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¶
-
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¶
-
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.