Navigation

Bro can connect with network devices like, for example, switches
or soft- and hardware firewalls using the NetControl framework. The
NetControl framework provides a flexible, unified interface for active
response and hides the complexity of heterogeneous network equipment
behind a simple task-oriented API, which is easily usable via Bro
scripts. This document gives an overview of how to use the NetControl
framework in different scenarios; to get a better understanding of how
it can be used in practice, it might be worthwhile to take a look at
the unit tests.

The basic architecture of the NetControl framework is shown in the figure above.
Conceptually, the NetControl framework sits between the user provided scripts
(which use the Bro event engine) and the network device (which can either be a
hardware or software device), that is used to implement the commands.

The NetControl framework supports a number of high-level calls, like the
NetControl::drop_address function, or a lower level rule
syntax. After a rule has been added to the NetControl framework, NetControl
sends the rule to one or several of its backends. Each backend is responsible
to communicate with a single hard- or software device. The NetControl framework
tracks rules throughout their entire lifecycle and reports the status (like
success, failure and timeouts) back to the user scripts.

In this section, we will introduce the high level NetControl API. As mentioned
above, NetControl uses backends to communicate with the external devices that
will implement the rules. You will need at least one active backend before you
can use NetControl. For our examples, we will just use the debug plugin to
create a backend. This plugin outputs all actions that are taken to the standard
output.

Backends should be initialized in the NetControl::init event, calling
the NetControl::activate function after the plugin instance has been
initialized. The debug plugin can be initialized as follows:

After at least one backend has been added to the NetControl framework, the
framework can be used and will send added rules to the added backend.

The NetControl framework contains several high level functions that allow users
to drop connections of certain addresses and networks, shunt network traffic,
etc. The following table shows and describes all of the currently available
high-level functions.

Calling this function causes all packets of a specific source IP to be
blocked. This function uses catch-and-release functionality and the IP
address is only dropped for a short amount of time to conserve rule
space in the network hardware. It is immediately re-dropped when it is
seen again in traffic. See Catch and Release for
more information.

Calling this function allows Bro to quarantine a host by sending DNS
traffic to a host with a special DNS server, which resolves all queries
as pointing to itself. The quarantined host is only allowed between the
special server, which will serve a warning message detailing the next
steps for the user.

Calling this function causes NetControl to push a whitelist entry for a
subnet to the networking hardware.

After adding a backend, all of these functions can immediately be used and will
start sending the rules to the added backend(s). To give a very simple example,
the following script will simply block the traffic of all connections that it
sees being established:

Running this script on a file containing one connection will cause the debug
plugin to print one line to the standard output, which contains information
about the rule that was added. It will also cause creation of netcontrol.log,
which contains information about all actions that are taken by NetControl:

In our case, netcontrol.log contains several NetControl::MESSAGE
entries, which show that the debug plugin has been initialized and added.
Afterwards, there are two NetControl::RULE entries; the first shows
that the addition of a rule has been requested (state is
NetControl::REQUESTED). The following line shows that the rule was
successfully added (the state is NetControl::SUCCEEDED). The
remainder of the log line gives more information about the added rule, which in
our case applies to a specific 5-tuple.

In addition to the netcontrol.log, the drop commands also create a second,
additional log called netcontrol_drop.log. This log file is much more succinct and
only contains information that is specific to drops that are enacted by
NetControl:

While this example of blocking all connections is usually not very useful, the
high-level API gives an easy way to take action, for example when a host is
identified doing some harmful activity. To give a more realistic example, the
following code automatically blocks a recognized SSH guesser:

As already mentioned in the last section, in addition to the high-level API, the
NetControl framework also supports a Rule based API which allows greater
flexibility while adding rules. Actually, all the high-level functions are
implemented using this lower-level rule API; the high-level functions simply
convert their arguments into the lower-level rules and then add the rules
directly to the NetControl framework (by calling NetControl::add_rule).

Rules are defined as a NetControl::Rule record. Rules have a type,
which specifies what kind of action is taken. The possible actions are to
drop packets, to modify them, to redirect or to whitelist them.
The target of a rule specifies if the rule is applied in the forward path,
and affects packets as they are forwarded through the network, or if it affects
the monitor path and only affects the packets that are sent to Bro, but not
the packets that traverse the network. The entity specifies the address,
connection, etc. that the rule applies to. In addition, each rule has a
timeout (which can be left empty), a priority (with higher priority rules
overriding lower priority rules). Furthermore, a location string with more
text information about each rule can be provided.

There are a couple more fields that are only needed for some rule types. For
example, when you insert a redirect rule, you have to specify the port that
packets should be redirected to. All these fields are shown in the
NetControl::Rule documentation.

To give an example on how to construct your own rule, we are going to write
our own version of the NetControl::drop_connection function. The only
difference between our function and the one provided by NetControl is the fact
that the NetControl function has additional functionality, e.g. for logging.

Once again, we are going to test our function with a simple example that simply
drops all connections on the network:

netcontrol-4-drop.brofunctionour_drop_connection(c:conn_id,t:interval){# As a first step, create the NetControl::Entity that we want to blocklocale=NetControl::Entity($ty=NetControl::CONNECTION,$conn=c);# Then, use the entity to create the rule to drop the entity in the forward pathlocalr=NetControl::Rule($ty=NetControl::DROP,$target=NetControl::FORWARD,$entity=e,$expire=t);# Add the rulelocalid=NetControl::add_rule(r);if(id=="")print"Error while dropping";}eventNetControl::init(){localdebug_plugin=NetControl::create_debug(T);NetControl::activate(debug_plugin,0);}eventconnection_established(c:connection){our_drop_connection(c$id,20 secs);}

The last example shows that NetControl::add_rule returns a string
identifier that is unique for each rule (uniqueness is not preserved across
restarts of Bro). This rule id can be used to later remove rules manually using
NetControl::remove_rule.

Similar to NetControl::add_rule, all the high-level functions also
return their rule IDs, which can be removed in the same way.

The NetControl framework offers a number of different ways to interact with
rules. Before a rule is applied by the framework, a number of different hooks
allow you to either modify or discard rules before they are added. Furthermore,
a number of events can be used to track the lifecycle of a rule while it is
being managed by the NetControl framework. It is also possible to query and
access the current set of active rules.

The hook NetControl::rule_policy provides the mechanism for modifying
or discarding a rule before it is sent onwards to the backends. Hooks can be
thought of as multi-bodied functions and using them looks very similar to
handling events. In contrast to events, they are processed immediately. Like
events, hooks can have priorities to sort the order in which they are applied.
Hooks can use the break keyword to show that processing should be aborted;
if any NetControl::rule_policy hook uses break, the rule will be
discarded before further processing.

Here is a simple example which tells Bro to discard all rules for connections
originating from the 192.168.* network:

In addition to the hooks, the NetControl framework offers a variety of events
that are raised by the framework to allow users to track rules, as well as the
state of the framework.

We already encountered and used one event of the NetControl framework,
NetControl::init, which is used to initialize the framework. After
the framework has finished initialization and will start accepting rules, the
NetControl::init_done event will be raised.

When rules are added to the framework, the following events will be called in
this order:

This event is the pendant to NetControl::rule_added, and
reports that a rule is no longer being tracked by the NetControl framework.
This happens, for example, when a rule was removed from all backends.

Consider, for example, the case where a Bro instance monitors the traffic at the
border, before any firewall or switch rules were applied. In this case, Bro will
still be able to see connection attempts of already blocked IP addresses. In this
case, NetControl::find_rules_addr could be used to check if an
address already was blocked in the past.

Here is a simple example, which uses a trace that contains two connections from
the same IP address. After the first connection, the script recognizes that the
address is already blocked in the second connection.

Notice that the functions return vectors because it is possible that several
rules exist simultaneously that affect one IP; either there could be
rules with different priorities, or rules for the subnet that an IP address is
part of.

We already mentioned earlier that in addition to the
NetControl::drop_connection and NetControl::drop_address
functions, which drop a connection or address for a specified amount of time,
NetControl also comes with a blocking function that uses an approach called
catch and release.

Catch and release is a blocking scheme that conserves valuable rule space in
your hardware. Instead of using long-lasting blocks, catch and release first
only installs blocks for a short amount of time (typically a few minutes). After
these minutes pass, the block is lifted, but the IP address is added to a
watchlist and the IP address will immediately be re-blocked again (for a longer
amount of time), if it is seen reappearing in any traffic, no matter if the new
traffic triggers any alert or not.

This makes catch and release blocks similar to normal, longer duration blocks,
while only requiring a small amount of space for the currently active rules. IP
addresses that only are seen once for a short time are only blocked for a few
minutes, monitored for a while and then forgotten. IP addresses that keep
appearing will get re-blocked for longer amounts of time.

In contrast to the other high-level functions that we documented so far, the
catch and release functionality is much more complex and adds a number of
different specialized functions to NetControl. The documentation for catch and
release is contained in the file
base/frameworks/netcontrol/catch-and-release.bro.

Note that you do not have to provide the block time for catch and release;
instead, catch and release uses the time intervals specified in
NetControl::catch_release_intervals (by default 10 minutes, 1 hour,
24 hours, 7 days). That means when an address is first blocked, it is blocked
for 10 minutes and monitored for 1 hour. If the address reappears after the
first 10 minutes, it is blocked for 1 hour and then monitored for 24 hours, etc.

Catch and release adds its own new logfile in addition to the already existing
ones (netcontrol_catch_release.log):

In the API part of the documentation, we exclusively used the debug plugin,
which simply outputs its actions to the screen. In addition to this debugging
plugin, Bro ships with a small number of plugins that can be used to interface
the NetControl framework with your networking hard- and software.

This plugin provides a generic way to send NetControl commands using the
new Bro communication library (Broker). External programs can receive
the rules and take action; we provide an example script that calls
command-line programs triggered by NetControl. The source of this
plugin is contained in base/frameworks/netcontrol/plugins/broker.bro.

In the API reference part of this document, we already used the debug plugin. To
use the plugin, we first had to instantiate it by calling
NetControl::create_debug and then add it to NetControl by
calling NetControl::activate.

As we already hinted before, NetControl supports having several plugins that are
active at the same time. The second argument to the NetControl::activate
function is the priority of the backend that was just added. Each rule is sent
to all plugins in order, from highest priority to lowest priority. The backend
can then choose if it accepts the rule and pushes it out to the hardware that it
manages. Or, it can opt to reject the rule. In this case, the NetControl
framework will try to apply the rule to the backend with the next lower
priority. If no backend accepts a rule, the rule insertion is marked as failed.

The choice if a rule is accepted or rejected stays completely with each plugin.
The debug plugin we used so far just accepts all rules. However, for other
plugins you can specify what rules they will accept. Consider, for example, a
network with two OpenFlow switches. The first switch forwards packets from the
network to the external world, the second switch sits in front of your Bro
cluster to provide packet shunting. In this case, you can add two OpenFlow
backends to NetControl. When you create the instances using
NetControl::create_openflow, you set the monitor and forward
attributes of the configuration in NetControl::OfConfig
appropriately. Afterwards, one of the backends will only accept rules for the
monitor path; the other backend will only accept rules for the forward path.

Commonly, plugins also support predicate functions, that allow the user to
specify restrictions on the rules that they will accept. This can for example be
used if you have a network where certain switches are responsible for specified
subnets. The predicate can examine the subnet of the rule and only accept the
rule if the rule matches the subnet that the specific switch is responsible for.

To give an example, the following script adds two backends to NetControl. One
backend is the NetControl debug backend, which just outputs the rules to the
console. The second backend is an OpenFlow backend, which uses the OpenFlow
debug mode that outputs the openflow rules to openflow.log. The OpenFlow
backend uses a predicate function to only accept rules with a source address in
the 192.168.17.0/24 network; all other rules will be passed on to the debug
plugin. We manually block a few addresses in the
NetControl::init_done event to verify the correct functionality.

As you can see, only the single block affecting the 192.168.17.0/24 network is
output to the command line. The other two lines are handled by the OpenFlow
plugin. We can verify this by looking at netcontrol.log. The plugin column shows
which plugin handled a rule and reveals that two rules were handled by OpenFlow:

You might have asked yourself what happens when you add two or more with the
same priority. In this case, the rule is sent to all the backends
simultaneously. This can be useful, for example when you have redundant
switches that should keep the same rule state.

Now that we know which plugins exist, and how they can be added to NetControl,
it is time to discuss how we can interface Bro with actual hardware. The typical
way to accomplish this is to use the Bro communication library (Broker), which
can be used to exchange Bro events with external programs and scripts. The
NetControl plugins can use Broker to send events to external programs, which can
then take action depending on these events.

The following figure shows this architecture with the example of the OpenFlow
plugin. The OpenFlow plugin uses Broker to send events to an external Python
script, which uses the Ryu SDN controller to
communicate with the Switch.

NetControl and OpenFlow architecture (click to enlarge).

The Python scripts that are used to interface with the available NetControl
plugins are contained in the bro-netcontrol repository (github link).
The repository contains scripts for the OpenFlow as well as the acld plugin.
Furthermore, it contains a script for the broker plugin which can be used to
call configureable command-line programs when used with the broker plugin.

The repository also contains documentation on how to install these connectors.
The netcontrol directory contains an API that allows you to write your own
connectors to the broker plugin.

Note

Note that the API of the Broker communication library is not finalized yet.
You might have to rewrite any scripts for use in future Bro versions.

In addition to using the plugins that are part of NetControl, you can write your
own plugins to interface with hard- or software that we currently do not support
out of the box.

Creating your own plugin is easy; besides a bit of boilerplate, you only need to
create two functions: one that is called when a rule is added, and one that is
called when a rule is removed. The following script creates a minimal plugin
that just outputs a rule when it is added or removed. Note that you have to
raise the NetControl::rule_added and
NetControl::rule_removed events in your plugin to let NetControl know
when a rule was added and removed successfully.