base/frameworks/netcontrol/main.bro

NetControl

Bro’s NetControl framework.

This plugin-based framework allows to control the traffic that Bro 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 Bro 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.bro, base/frameworks/netcontrol/types.bro
Source File:/scripts/base/frameworks/netcontrol/main.bro

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  

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::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 Bro 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.

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.

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.

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.

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.

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::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.

R:The rule to be added.

Functions

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

Activates a plugin.

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.

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.

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.

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 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.

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 bro_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.

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.

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.

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.

A:The address to be whitelisted.
T:How long to whitelist it, with 0 being indefinitely.
Location:An optional string describing whitelist was triddered.
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.

S:The subnet to be whitelisted.
T:How long to whitelist it, with 0 being indefinitely.
Location:An optional string describing whitelist was triddered.
Returns:The id of the inserted rule on success and zero on failure.
Copyright 2016, The Bro Project. Last updated on December 19, 2018. Created using Sphinx 1.8.2.