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.