Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-06 08:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Fix various typos in the NetControl docs

Browse source 
Also fixed warnings that were seen while building the docs
with "make doc".
This commit is contained in:
Daniel Thayer 2016-11-08 15:25:28 -06:00
parent 261c6907d8
commit 3057d2b8fb
12 changed files with 159 additions and 164 deletions
Download patch file Download diff file Expand all files Collapse all files

46
doc/frameworks/netcontrol.rst
View file

@ -31,12 +31,12 @@ NetControl Architecture
NetControl architecture (click to enlarge). NetControl architecture (click to enlarge).
The basic architecture of the NetControl framework is shown in the figure above. The basic architecture of the NetControl framework is shown in the figure above.
Conceptually, the NetControl framework sits inbetween the user provided scripts 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 (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. hardware or software device), that is used to implement the commands.
The NetControl framework supports a number of high-level calls, like the The NetControl framework supports a number of high-level calls, like the
:bro:see:`NetControl::drop_address` function, or lower a lower level rule :bro:see:`NetControl::drop_address` function, or a lower level rule
syntax. After a rule has been added to the NetControl framework, NetControl 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 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 to communicate with a single hard- or software device. The NetControl framework
@ -90,16 +90,12 @@ high-level functions.
* - :bro:see:`NetControl::drop_address` * - :bro:see:`NetControl::drop_address`
- Calling this function causes NetControl to block all packets involving - Calling this function causes NetControl to block all packets involving
an IP address from being forwarded an IP address from being forwarded.
* - :bro:see:`NetControl::drop_connection` * - :bro:see:`NetControl::drop_connection`
- Calling this function stops all packets of a specific connection - Calling this function stops all packets of a specific connection
(identified by its 5-tuple) from being forwarded. (identified by its 5-tuple) from being forwarded.
* - :bro:see:`NetControl::drop_address`
- Calling this function causes NetControl to block all packets involving
an IP address from being forwarded
* - :bro:see:`NetControl::drop_address_catch_release` * - :bro:see:`NetControl::drop_address_catch_release`
- Calling this function causes all packets of a specific source IP to be - Calling this function causes all packets of a specific source IP to be
blocked. This function uses catch-and-release functionality and the IP blocked. This function uses catch-and-release functionality and the IP
@ -114,7 +110,7 @@ high-level functions.
resources by shunting flows that have been identified as being benign. resources by shunting flows that have been identified as being benign.
* - :bro:see:`NetControl::redirect_flow` * - :bro:see:`NetControl::redirect_flow`
- Calling this function causes NetControl to redirect an uni-directional - Calling this function causes NetControl to redirect a uni-directional
flow to another port of the networking hardware. flow to another port of the networking hardware.
* - :bro:see:`NetControl::quarantine_host` * - :bro:see:`NetControl::quarantine_host`
@ -122,7 +118,7 @@ high-level functions.
traffic to a host with a special DNS server, which resolves all queries 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 as pointing to itself. The quarantined host is only allowed between the
special server, which will serve a warning message detailing the next special server, which will serve a warning message detailing the next
steps for the user steps for the user.
* - :bro:see:`NetControl::whitelist_address` * - :bro:see:`NetControl::whitelist_address`
- Calling this function causes NetControl to push a whitelist entry for an - Calling this function causes NetControl to push a whitelist entry for an
@ -227,14 +223,14 @@ 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 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 *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, the packets that traverse the network. The *entity* specifies the address,
connection, etc. that the rule applies to. In addition, each notice has a 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 *timeout* (which can be left empty), a *priority* (with higher priority rules
overriding lower priority rules). Furthermore, a *location* string with more overriding lower priority rules). Furthermore, a *location* string with more
text information about each rule can be provided. text information about each rule can be provided.
There are a couple more fields that only needed for some rule types. For 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 example, when you insert a redirect rule, you have to specify the port that
packets should be redirected too. All these fields are shown in the packets should be redirected to. All these fields are shown in the
:bro:see:`NetControl::Rule` documentation. :bro:see:`NetControl::Rule` documentation.
To give an example on how to construct your own rule, we are going to write To give an example on how to construct your own rule, we are going to write
@ -243,7 +239,7 @@ difference between our function and the one provided by NetControl is the fact
that the NetControl function has additional functionality, e.g. for logging. 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 Once again, we are going to test our function with a simple example that simply
drops all connections on the Network: drops all connections on the network:
.. btest-include:: ${DOC_ROOT}/frameworks/netcontrol-4-drop.bro .. btest-include:: ${DOC_ROOT}/frameworks/netcontrol-4-drop.bro
@ -254,7 +250,7 @@ drops all connections on the Network:
The last example shows that :bro:see:`NetControl::add_rule` returns a string The last example shows that :bro:see:`NetControl::add_rule` returns a string
identifier that is unique for each rule (uniqueness is not preserved across identifier that is unique for each rule (uniqueness is not preserved across
restarts or Bro). This rule id can be used to later remove rules manually using restarts of Bro). This rule id can be used to later remove rules manually using
:bro:see:`NetControl::remove_rule`. :bro:see:`NetControl::remove_rule`.
Similar to :bro:see:`NetControl::add_rule`, all the high-level functions also Similar to :bro:see:`NetControl::add_rule`, all the high-level functions also
@ -264,7 +260,7 @@ Interacting with Rules
---------------------- ----------------------
The NetControl framework offers a number of different ways to interact with 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 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, 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 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 being managed by the NetControl framework. It is also possible to query and
@ -276,7 +272,7 @@ Rule Policy
The hook :bro:see:`NetControl::rule_policy` provides the mechanism for modifying The hook :bro:see:`NetControl::rule_policy` provides the mechanism for modifying
or discarding a rule before it is sent onwards to the backends. Hooks can be 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 thought of as multi-bodied functions and using them looks very similar to
handling events. In difference to events, they are processed immediately. Like 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. 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; Hooks can use the ``break`` keyword to show that processing should be aborted;
if any :bro:see:`NetControl::rule_policy` hook uses ``break``, the rule will be if any :bro:see:`NetControl::rule_policy` hook uses ``break``, the rule will be
@ -315,7 +311,7 @@ this order:
* - :bro:see:`NetControl::rule_new` * - :bro:see:`NetControl::rule_new`
- Signals that a new rule is created by the NetControl framework due to - Signals that a new rule is created by the NetControl framework due to
:bro:see:`NetControl::add_rule`. At this point of time, the rule has not :bro:see:`NetControl::add_rule`. At this point, the rule has not
yet been added to any backend. yet been added to any backend.
* - :bro:see:`NetControl::rule_added` * - :bro:see:`NetControl::rule_added`
@ -328,15 +324,15 @@ this order:
* - :bro:see:`NetControl::rule_timeout` * - :bro:see:`NetControl::rule_timeout`
- Signals that a rule timeout was reached. If the hardware does not support - Signals that a rule timeout was reached. If the hardware does not support
automatic timeouts, the NetControl framework will automatically call automatic timeouts, the NetControl framework will automatically call
bro:see:`NetControl::remove_rule`. :bro:see:`NetControl::remove_rule`.
* - :bro:see:`NetControl::rule_removed` * - :bro:see:`NetControl::rule_removed`
- Signals that a new rule has successfully been removed a backend. - Signals that a new rule has successfully been removed a backend.
* - :bro:see:`NetControl::rule_destroyed` * - :bro:see:`NetControl::rule_destroyed`
- This event is the pendant to :bro:see:`NetControl::rule_added`, and - This event is the pendant to :bro:see:`NetControl::rule_added`, and
reports that a rule is no longer be tracked by the NetControl framework. reports that a rule is no longer being tracked by the NetControl framework.
This happens, for example, when a rule was removed from all backend. This happens, for example, when a rule was removed from all backends.
* - :bro:see:`NetControl::rule_error` * - :bro:see:`NetControl::rule_error`
- This event is raised whenever an error occurs during any rule operation. - This event is raised whenever an error occurs during any rule operation.
@ -385,7 +381,7 @@ NetControl also comes with a blocking function that uses an approach called
Catch and release is a blocking scheme that conserves valuable rule space in 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 your hardware. Instead of using long-lasting blocks, catch and release first
only installs blocks for short amount of times (typically a few minutes). After 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 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 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 amount of time), if it is seen reappearing in any traffic, no matter if the new
@ -397,7 +393,7 @@ 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 minutes, monitored for a while and then forgotten. IP addresses that keep
appearing will get re-blocked for longer amounts of time. appearing will get re-blocked for longer amounts of time.
In difference to the other high-level functions that we documented so far, the 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 catch and release functionality is much more complex and adds a number of
different specialized functions to NetControl. The documentation for catch and different specialized functions to NetControl. The documentation for catch and
release is contained in the file release is contained in the file
@ -481,7 +477,7 @@ The plugins that currently ship with NetControl are:
plugin is contained in :doc:`/scripts/base/frameworks/netcontrol/plugins/acld.bro`. plugin is contained in :doc:`/scripts/base/frameworks/netcontrol/plugins/acld.bro`.
* - PacketFilter plugin * - PacketFilter plugin
- This plugin adds uses the Bro process-level packet filter (see - This plugin uses the Bro process-level packet filter (see
:bro:see:`install_src_net_filter` and :bro:see:`install_src_net_filter` and
:bro:see:`install_dst_net_filter`). Since the functionality of the :bro:see:`install_dst_net_filter`). Since the functionality of the
PacketFilter is limited, this plugin is mostly for demonstration purposes. The source of this PacketFilter is limited, this plugin is mostly for demonstration purposes. The source of this
@ -496,7 +492,7 @@ Activating plugins
In the API reference part of this document, we already used the debug plugin. To 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 use the plugin, we first had to instantiate it by calling
:bro:see:`NetControl::NetControl::create_debug` and then add it to NetControl by :bro:see:`NetControl::create_debug` and then add it to NetControl by
calling :bro:see:`NetControl::activate`. calling :bro:see:`NetControl::activate`.
As we already hinted before, NetControl supports having several plugins that are As we already hinted before, NetControl supports having several plugins that are
@ -607,7 +603,7 @@ Writing plugins
In addition to using the plugins that are part of NetControl, you can write your 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 own plugins to interface with hard- or software that we currently do not support
out of the Box. out of the box.
Creating your own plugin is easy; besides a bit of boilerplate, you only need to 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 create two functions: one that is called when a rule is added, and one that is

42
scripts/base/frameworks/netcontrol/catch-and-release.bro
View file

@ -10,39 +10,39 @@ export {
redef enum Log::ID += { CATCH_RELEASE }; redef enum Log::ID += { CATCH_RELEASE };
## Thhis record is used is used for storing information about current blocks that are ## This record is used for storing information about current blocks that are
## part of catch and release. ## part of catch and release.
type BlockInfo: record { type BlockInfo: record {
## Absolute time indicating until when a block is inserted using NetControl ## Absolute time indicating until when a block is inserted using NetControl.
block_until: time &optional; block_until: time &optional;
## Absolute time indicating until when an IP address is watched to reblock it ## Absolute time indicating until when an IP address is watched to reblock it.
watch_until: time; watch_until: time;
## Number of times an IP address was reblocked ## Number of times an IP address was reblocked.
num_reblocked: count &default=0; num_reblocked: count &default=0;
## Number indicating at which catch and release interval we currently are ## Number indicating at which catch and release interval we currently are.
current_interval: count; current_interval: count;
## ID of the inserted block, if any. ## ID of the inserted block, if any.
current_block_id: string; current_block_id: string;
## User specified string ## User specified string.
location: string &optional; location: string &optional;
}; };
## The enum that contains the different kinds of messages that are logged by ## The enum that contains the different kinds of messages that are logged by
## catch and release ## catch and release.
type CatchReleaseActions: enum { type CatchReleaseActions: enum {
## Log lines marked with info are purely informational; no action was taken ## Log lines marked with info are purely informational; no action was taken.
INFO, INFO,
## A rule for the specified IP address already existed in NetControl (outside ## A rule for the specified IP address already existed in NetControl (outside
## of catch-and-release). Catch and release did not add a new rule, but is now ## of catch-and-release). Catch and release did not add a new rule, but is now
## watching the IP address and will add a new rule after the current rule expired. ## watching the IP address and will add a new rule after the current rule expires.
ADDED, ADDED,
## A drop was requested by catch and release ## A drop was requested by catch and release.
DROP, DROP,
## A address was succesfully blocked by catch and release ## An address was successfully blocked by catch and release.
DROPPED, DROPPED,
## An address was unblocked after the timeout expired ## An address was unblocked after the timeout expired.
UNBLOCK, UNBLOCK,
## An address was forgotten because it did not reappear within the `watch_until` interval ## An address was forgotten because it did not reappear within the `watch_until` interval.
FORGOTTEN, FORGOTTEN,
## A watched IP address was seen again; catch and release will re-block it. ## A watched IP address was seen again; catch and release will re-block it.
SEEN_AGAIN SEEN_AGAIN
@ -52,7 +52,7 @@ export {
type CatchReleaseInfo: record { type CatchReleaseInfo: record {
## The absolute time indicating when the action for this log-line occured. ## The absolute time indicating when the action for this log-line occured.
ts: time &log; ts: time &log;
## The rule id that this log lone refers to. ## The rule id that this log line refers to.
rule_id: string &log &optional; rule_id: string &log &optional;
## The IP address that this line refers to. ## The IP address that this line refers to.
ip: addr &log; ip: addr &log;
@ -85,7 +85,7 @@ export {
## ##
## a: The address to be dropped. ## a: The address to be dropped.
## ##
## t: How long to drop it, with 0 being indefinitly. ## t: How long to drop it, with 0 being indefinitely.
## ##
## location: An optional string describing where the drop was triggered. ## location: An optional string describing where the drop was triggered.
## ##
@ -101,17 +101,17 @@ export {
## ##
## a: The address to be unblocked. ## a: The address to be unblocked.
## ##
## reason: A reason for the unblock ## reason: A reason for the unblock.
## ##
## Returns: True if the address was unblocked. ## Returns: True if the address was unblocked.
global unblock_address_catch_release: function(a: addr, reason: string &default="") : bool; global unblock_address_catch_release: function(a: addr, reason: string &default="") : bool;
## This function can be called to notify the cach and release script that activity by ## This function can be called to notify the catch and release script that activity by
## an IP address was seen. If the respective IP address is currently monitored by catch and ## an IP address was seen. If the respective IP address is currently monitored by catch and
## release and not blocked, the block will be re-instated. See the documentation of watch_new_connection ## release and not blocked, the block will be reinstated. See the documentation of watch_new_connection
## which events the catch and release functionality usually monitors for activity. ## which events the catch and release functionality usually monitors for activity.
## ##
## a: The address that was seen and should be re-dropped if it is being watched ## a: The address that was seen and should be re-dropped if it is being watched.
global catch_release_seen: function(a: addr); global catch_release_seen: function(a: addr);
## Get the :bro:see:`NetControl::BlockInfo` record for an address currently blocked by catch and release. ## Get the :bro:see:`NetControl::BlockInfo` record for an address currently blocked by catch and release.
@ -144,7 +144,7 @@ export {
## should have been blocked. ## should have been blocked.
const catch_release_warn_blocked_ip_encountered = F &redef; const catch_release_warn_blocked_ip_encountered = F &redef;
## Time intervals for which a subsequent drops of the same IP take ## Time intervals for which subsequent drops of the same IP take
## effect. ## effect.
const catch_release_intervals: vector of interval = vector(10min, 1hr, 24hrs, 7days) &redef; const catch_release_intervals: vector of interval = vector(10min, 1hr, 24hrs, 7days) &redef;
@ -160,7 +160,7 @@ export {
global catch_release_encountered: event(a: addr); global catch_release_encountered: event(a: addr);
} }
# set that is used to only send seen notifications to the master every ~30 seconds. # Set that is used to only send seen notifications to the master every ~30 seconds.
global catch_release_recently_notified: set[addr] &create_expire=30secs; global catch_release_recently_notified: set[addr] &create_expire=30secs;
event bro_init() &priority=5 event bro_init() &priority=5

6
scripts/base/frameworks/netcontrol/cluster.bro
View file

@ -23,7 +23,7 @@ redef Cluster::manager2worker_events += /NetControl::rule_(added|removed|timeout
function activate(p: PluginState, priority: int) function activate(p: PluginState, priority: int)
{ {
# we only run the activate function on the manager. # We only run the activate function on the manager.
if ( Cluster::local_node_type() != Cluster::MANAGER ) if ( Cluster::local_node_type() != Cluster::MANAGER )
return; return;
@ -38,8 +38,8 @@ function add_rule(r: Rule) : string
return add_rule_impl(r); return add_rule_impl(r);
else else
{ {
# we sync rule entities accross the cluster, so we # We sync rule entities accross the cluster, so we
# acually can test if the rule already exists. If yes, # actually can test if the rule already exists. If yes,
# refuse insertion already at the node. # refuse insertion already at the node.
if ( [r$entity, r$ty] in rule_entities ) if ( [r$entity, r$ty] in rule_entities )

16
scripts/base/frameworks/netcontrol/drop.bro
View file

@ -11,34 +11,34 @@ export {
## ##
## a: The address to be dropped. ## a: The address to be dropped.
## ##
## t: How long to drop it, with 0 being indefinitly. ## t: How long to drop it, with 0 being indefinitely.
## ##
## location: An optional string describing where the drop was triggered. ## location: An optional string describing where the drop was triggered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global drop_address: function(a: addr, t: interval, location: string &default="") : string; global drop_address: function(a: addr, t: interval, location: string &default="") : string;
## Stops all packets involving an connection address from being forwarded. ## Stops all packets involving a connection address from being forwarded.
## ##
## c: The connection to be dropped. ## c: The connection to be dropped.
## ##
## t: How long to drop it, with 0 being indefinitly. ## t: How long to drop it, with 0 being indefinitely.
## ##
## location: An optional string describing where the drop was triggered. ## location: An optional string describing where the drop was triggered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global drop_connection: function(c: conn_id, t: interval, location: string &default="") : string; global drop_connection: function(c: conn_id, t: interval, location: string &default="") : string;
type DropInfo: record { type DropInfo: record {
## Time at which the recorded activity occurred. ## Time at which the recorded activity occurred.
ts: time &log; ts: time &log;
## ID of the rule; unique during each Bro run ## ID of the rule; unique during each Bro run.
rule_id: string &log; rule_id: string &log;
orig_h: addr &log; ##< The originator's IP address. orig_h: addr &log; ##< The originator's IP address.
orig_p: port &log &optional; ##< The originator's port number. orig_p: port &log &optional; ##< The originator's port number.
resp_h: addr &log &optional; ##< The responder's IP address. resp_h: addr &log &optional; ##< The responder's IP address.
resp_p: port &log &optional; ##< The responder's port number. resp_p: port &log &optional; ##< The responder's port number.
## Expiry time of the shunt ## Expiry time of the shunt.
expire: interval &log; expire: interval &log;
## Location where the underlying action was triggered. ## Location where the underlying action was triggered.
location: string &log &optional; location: string &log &optional;
@ -47,7 +47,7 @@ export {
## Hook that allows the modification of rules passed to drop_* before they ## Hook that allows the modification of rules passed to drop_* before they
## are passed on. If one of the hooks uses break, the rule is ignored. ## are passed on. If one of the hooks uses break, the rule is ignored.
## ##
## r: The rule to be added ## r: The rule to be added.
global NetControl::drop_rule_policy: hook(r: Rule); global NetControl::drop_rule_policy: hook(r: Rule);
## Event that can be handled to access the :bro:type:`NetControl::ShuntInfo` ## Event that can be handled to access the :bro:type:`NetControl::ShuntInfo`

84
scripts/base/frameworks/netcontrol/main.bro
View file

@ -7,7 +7,7 @@
##! restrictions on entities, such as specific connections or IP addresses. ##! 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 ##! This framework has two APIs: a high-level and low-level. The high-level API
##! provides convinience functions for a set of common operations. The ##! provides convenience functions for a set of common operations. The
##! low-level API provides full flexibility. ##! low-level API provides full flexibility.
module NetControl; module NetControl;
@ -25,7 +25,7 @@ export {
## Activates a plugin. ## Activates a plugin.
## ##
## p: The plugin to acticate. ## p: The plugin to activate.
## ##
## priority: The higher the priority, the earlier this plugin will be checked ## priority: The higher the priority, the earlier this plugin will be checked
## whether it supports an operation, relative to other plugins. ## whether it supports an operation, relative to other plugins.
@ -48,37 +48,37 @@ export {
## Allows all traffic involving a specific IP address to be forwarded. ## Allows all traffic involving a specific IP address to be forwarded.
## ##
## a: The address to be whitelistet. ## a: The address to be whitelisted.
## ##
## t: How long to whitelist it, with 0 being indefinitly. ## t: How long to whitelist it, with 0 being indefinitely.
## ##
## location: An optional string describing whitelist was triddered. ## location: An optional string describing whitelist was triddered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global whitelist_address: function(a: addr, t: interval, location: string &default="") : string; global whitelist_address: function(a: addr, t: interval, location: string &default="") : string;
## Allows all traffic involving a specific IP subnet to be forwarded. ## Allows all traffic involving a specific IP subnet to be forwarded.
## ##
## s: The subnet to be whitelistet. ## s: The subnet to be whitelisted.
## ##
## t: How long to whitelist it, with 0 being indefinitly. ## t: How long to whitelist it, with 0 being indefinitely.
## ##
## location: An optional string describing whitelist was triddered. ## location: An optional string describing whitelist was triddered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global whitelist_subnet: function(s: subnet, t: interval, location: string &default="") : string; global whitelist_subnet: function(s: subnet, t: interval, location: string &default="") : string;
## Redirects an uni-directional flow to another port. ## Redirects a uni-directional flow to another port.
## ##
## f: The flow to redirect. ## f: The flow to redirect.
## ##
## out_port: Port to redirect the flow to ## out_port: Port to redirect the flow to.
## ##
## t: How long to leave the redirect in place, with 0 being indefinitly. ## t: How long to leave the redirect in place, with 0 being indefinitely.
## ##
## location: An optional string describing where the redirect was triggered. ## location: An optional string describing where the redirect was triggered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global redirect_flow: function(f: flow_id, out_port: count, t: interval, location: string &default="") : string; global redirect_flow: function(f: flow_id, out_port: count, t: interval, location: string &default="") : string;
## Quarantines a host. This requires a special quarantine server, which runs a HTTP server explaining ## Quarantines a host. This requires a special quarantine server, which runs a HTTP server explaining
@ -87,13 +87,13 @@ export {
## instead. Only http communication infected to quarantinehost is allowed. All other network communication ## instead. Only http communication infected to quarantinehost is allowed. All other network communication
## is blocked. ## is blocked.
## ##
## infected: the host to quarantine ## infected: the host to quarantine.
## ##
## dns: the network dns server ## dns: the network dns server.
## ##
## quarantine: the quarantine server running a dns and a web server ## quarantine: the quarantine server running a dns and a web server.
## ##
## t: how long to leave the quarantine in place ## t: how long to leave the quarantine in place.
## ##
## Returns: Vector of inserted rules on success, empty list on failure. ## Returns: Vector of inserted rules on success, empty list on failure.
global quarantine_host: function(infected: addr, dns: addr, quarantine: addr, t: interval, location: string &default="") : vector of string; global quarantine_host: function(infected: addr, dns: addr, quarantine: addr, t: interval, location: string &default="") : vector of string;
@ -111,7 +111,7 @@ export {
## ##
## r: The rule to install. ## r: The rule to install.
## ##
## Returns: If succesful, returns an ID string unique to the rule that can ## 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 ## later be used to refer to it. If unsuccessful, returns an empty
## string. The ID is also assigned to ``r$id``. Note that ## string. The ID is also assigned to ``r$id``. Note that
## "successful" means "a plugin knew how to handle the rule", it ## "successful" means "a plugin knew how to handle the rule", it
@ -126,19 +126,19 @@ export {
## ##
## reason: Optional string argument giving information on why the rule was removed. ## reason: Optional string argument giving information on why the rule was removed.
## ##
## Returns: True if succesful, the relevant plugin indicated that it knew ## Returns: True if successful, the relevant plugin indicated that it knew
## how to handle the removal. Note that again "success" means the ## how to handle the removal. Note that again "success" means the
## plugin accepted the removal. They might still fail to put it ## plugin accepted the removal. It might still fail to put it
## into effect, as that might happen asynchronously and thus go ## into effect, as that might happen asynchronously and thus go
## wrong at that point. ## wrong at that point.
global remove_rule: function(id: string, reason: string &default="") : bool; global remove_rule: function(id: string, reason: string &default="") : bool;
## Deletes a rule without removing in from the backends to which it has been ## Deletes a rule without removing it from the backends to which it has been
## added before. This mean that no messages will be sent to the switches to which ## 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, ## 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. ## it will stay installed and not be removed later.
## ##
## id: The rule to delete, specified as the ID returned by :bro:see:`add_rule` . ## id: The rule to delete, specified as the ID returned by :bro:see:`NetControl::add_rule`.
## ##
## reason: Optional string argument giving information on why the rule was deleted. ## reason: Optional string argument giving information on why the rule was deleted.
## ##
@ -152,9 +152,9 @@ export {
## the worker, the internal rule variables (starting with _) will not reflect the ## the worker, the internal rule variables (starting with _) will not reflect the
## current state. ## current state.
## ##
## ip: The ip address to search for ## ip: The ip address to search for.
## ##
## Returns: vector of all rules affecting the IP address ## Returns: vector of all rules affecting the IP address.
global find_rules_addr: function(ip: addr) : vector of Rule; global find_rules_addr: function(ip: addr) : vector of Rule;
## Searches all rules affecting a certain subnet. ## Searches all rules affecting a certain subnet.
@ -171,9 +171,9 @@ export {
## the worker, the internal rule variables (starting with _) will not reflect the ## the worker, the internal rule variables (starting with _) will not reflect the
## current state. ## current state.
## ##
## sn: The subnet to search for ## sn: The subnet to search for.
## ##
## Returns: vector of all rules affecting the subnet ## Returns: vector of all rules affecting the subnet.
global find_rules_subnet: function(sn: subnet) : vector of Rule; global find_rules_subnet: function(sn: subnet) : vector of Rule;
###### Asynchronous feedback on rules. ###### Asynchronous feedback on rules.
@ -201,7 +201,7 @@ export {
global rule_exists: event(r: Rule, p: PluginState, msg: string &default=""); global rule_exists: event(r: Rule, p: PluginState, msg: string &default="");
## Reports that a plugin reports a rule was removed due to a ## Reports that a plugin reports a rule was removed due to a
## remove: function() vall. ## remove_rule function call.
## ##
## r: The rule now removed. ## r: The rule now removed.
## ##
@ -234,9 +234,9 @@ export {
## This event is raised when a new rule is created by the NetControl framework ## 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 ## 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 framewory. ## is raised, the rule is tracked internally by the NetControl framework.
## ##
## Note that this event does not mean that a rule was succesfully added by ## 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 ## 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 ## 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 ## installed by the hardware, use the rule_added, rule_exists, rule_removed, rule_timeout
@ -248,15 +248,15 @@ export {
## was removed by all plugins to which it was added, by the fact that it timed out ## was removed by all plugins to which it was added, by the fact that it timed out
## or due to rule errors. ## or due to rule errors.
## ##
## To get the cause or a rule remove, hook the rule_removed, rule_timeout and ## To get the cause of a rule remove, catch the rule_removed, rule_timeout and
## rule_error calls. ## rule_error events.
global rule_destroyed: event(r: Rule); global rule_destroyed: event(r: Rule);
## Hook that allows the modification of rules passed to add_rule before they ## 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 ## are passed on to the plugins. If one of the hooks uses break, the rule is
## ignored and not passed on to any plugin. ## ignored and not passed on to any plugin.
## ##
## r: The rule to be added ## r: The rule to be added.
global NetControl::rule_policy: hook(r: Rule); global NetControl::rule_policy: hook(r: Rule);
##### Plugin functions ##### Plugin functions
@ -279,19 +279,19 @@ export {
## State of an entry in the NetControl log. ## State of an entry in the NetControl log.
type InfoState: enum { type InfoState: enum {
REQUESTED, ##< The request to add/remove a rule was sent to the respective backend REQUESTED, ##< The request to add/remove a rule was sent to the respective backend.
SUCCEEDED, ##< A rule was succesfully added by a backend SUCCEEDED, ##< A rule was successfully added by a backend.
EXISTS, ##< A backend reported that a rule was already existing EXISTS, ##< A backend reported that a rule was already existing.
FAILED, ##< A rule addition failed FAILED, ##< A rule addition failed.
REMOVED, ##< A rule was succesfully removed by a backend REMOVED, ##< A rule was successfully removed by a backend.
TIMEOUT, ##< A rule timeout was triggered by the NetControl framework or a backend TIMEOUT, ##< A rule timeout was triggered by the NetControl framework or a backend.
}; };
## The record type defining the column fields of the NetControl log. ## The record type defining the column fields of the NetControl log.
type Info: record { type Info: record {
## Time at which the recorded activity occurred. ## Time at which the recorded activity occurred.
ts: time &log; ts: time &log;
## ID of the rule; unique during each Bro run ## ID of the rule; unique during each Bro run.
rule_id: string &log &optional; rule_id: string &log &optional;
## Type of the log entry. ## Type of the log entry.
category: InfoCategory &log &optional; category: InfoCategory &log &optional;
@ -311,9 +311,9 @@ export {
mod: string &log &optional; mod: string &log &optional;
## String with an additional message. ## String with an additional message.
msg: string &log &optional; msg: string &log &optional;
## Number describing the priority of the log entry ## Number describing the priority of the log entry.
priority: int &log &optional; priority: int &log &optional;
## Expiry time of the log entry ## Expiry time of the log entry.
expire: interval &log &optional; expire: interval &log &optional;
## Location where the underlying action was triggered. ## Location where the underlying action was triggered.
location: string &log &optional; location: string &log &optional;
@ -333,7 +333,7 @@ redef record Rule += {
_active_plugin_ids: set[count] &default=count_set(); _active_plugin_ids: set[count] &default=count_set();
## Internally set to plugins where the rule should not be removed upon timeout. ## Internally set to plugins where the rule should not be removed upon timeout.
_no_expire_plugins: set[count] &default=count_set(); _no_expire_plugins: set[count] &default=count_set();
## Track if the rule was added succesfully by all responsible plugins. ## Track if the rule was added successfully by all responsible plugins.
_added: bool &default=F; _added: bool &default=F;
}; };

10
scripts/base/frameworks/netcontrol/plugin.bro
View file

@ -9,7 +9,7 @@ export {
## ##
## Individual plugins commonly extend this record to suit their needs. ## Individual plugins commonly extend this record to suit their needs.
type PluginState: record { type PluginState: record {
## Table for a plugin to store custom, instance-specfific state. ## Table for a plugin to store custom, instance-specific state.
config: table[string] of string &default=table(); config: table[string] of string &default=table();
## Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally. ## Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally.
@ -18,14 +18,14 @@ export {
## Set internally. ## Set internally.
_priority: int &default=+0; _priority: int &default=+0;
## Set internally. Signifies if the plugin has returned that it has activated succesfully ## Set internally. Signifies if the plugin has returned that it has activated succesfully.
_activated: bool &default=F; _activated: bool &default=F;
}; };
## Definition of a plugin. ## Definition of a plugin.
## ##
## Generally a plugin needs to implement only what it can support. By ## Generally a plugin needs to implement only what it can support. By
## returning failure, it indicates that it can't support something and the ## returning failure, it indicates that it can't support something and
## the framework will then try another plugin, if available; or inform the ## the framework will then try another plugin, if available; or inform the
## that the operation failed. If a function isn't implemented by a plugin, ## that the operation failed. If a function isn't implemented by a plugin,
## that's considered an implicit failure to support the operation. ## that's considered an implicit failure to support the operation.
@ -33,7 +33,7 @@ export {
## If plugin accepts a rule operation, it *must* generate one of the reporting ## If plugin accepts a rule operation, it *must* generate one of the reporting
## events ``rule_{added,remove,error}`` to signal if it indeed worked out; ## events ``rule_{added,remove,error}`` to signal if it indeed worked out;
## this is separate from accepting the operation because often a plugin ## this is separate from accepting the operation because often a plugin
## will only know later (i.e., asynchrously) if that was an error for ## will only know later (i.e., asynchronously) if that was an error for
## something it thought it could handle. ## something it thought it could handle.
type Plugin: record { type Plugin: record {
## Returns a descriptive name of the plugin instance, suitable for use in logging ## Returns a descriptive name of the plugin instance, suitable for use in logging
@ -64,7 +64,7 @@ export {
add_rule: function(state: PluginState, r: Rule) : bool &optional; add_rule: function(state: PluginState, r: Rule) : bool &optional;
## Implements the remove_rule() operation. This will only be called for ## Implements the remove_rule() operation. This will only be called for
## rules that the plugins has previously accepted with add_rule(). The ## rules that the plugin has previously accepted with add_rule(). The
## ``id`` field will match that of the add_rule() call. Generally, ## ``id`` field will match that of the add_rule() call. Generally,
## a plugin that accepts an add_rule() should also accept the ## a plugin that accepts an add_rule() should also accept the
## remove_rule(). ## remove_rule().

2
scripts/base/frameworks/netcontrol/plugins/README
View file

@ -1 +1 @@
Plugins for the NetControl framework Plugins for the NetControl framework.

30
scripts/base/frameworks/netcontrol/plugins/acld.bro
View file

@ -17,24 +17,24 @@ export {
}; };
type AcldConfig: record { type AcldConfig: record {
## The acld topic used to send events to ## The acld topic to send events to.
acld_topic: string; acld_topic: string;
## Broker host to connect to ## Broker host to connect to.
acld_host: addr; acld_host: addr;
## Broker port to connect to ## Broker port to connect to.
acld_port: port; acld_port: port;
## Do we accept rules for the monitor path? Default false ## Do we accept rules for the monitor path? Default false.
monitor: bool &default=F; monitor: bool &default=F;
## Do we accept rules for the forward path? Default true ## Do we accept rules for the forward path? Default true.
forward: bool &default=T; forward: bool &default=T;
## Predicate that is called on rule insertion or removal. ## Predicate that is called on rule insertion or removal.
## ##
## p: Current plugin state ## p: Current plugin state.
## ##
## r: The rule to be inserted or removed ## r: The rule to be inserted or removed.
## ##
## Returns: T if the rule can be handled by the current backend, F otherwhise ## Returns: T if the rule can be handled by the current backend, F otherwise.
check_pred: function(p: PluginState, r: Rule): bool &optional; check_pred: function(p: PluginState, r: Rule): bool &optional;
}; };
@ -43,27 +43,27 @@ export {
redef record PluginState += { redef record PluginState += {
acld_config: AcldConfig &optional; acld_config: AcldConfig &optional;
## The ID of this acld instance - for the mapping to PluginStates ## The ID of this acld instance - for the mapping to PluginStates.
acld_id: count &optional; acld_id: count &optional;
}; };
## Hook that is called after a rule is converted to an acld rule. ## Hook that is called after a rule is converted to an acld rule.
## The hook may modify the rule before it is sent to acld. ## The hook may modify the rule before it is sent to acld.
## Setting the acld command to F will cause the rule to be rejected ## Setting the acld command to F will cause the rule to be rejected
## by the plugin ## by the plugin.
## ##
## p: Current plugin state ## p: Current plugin state.
## ##
## r: The rule to be inserted or removed ## r: The rule to be inserted or removed.
## ##
## ar: The acld rule to be inserted or removed ## ar: The acld rule to be inserted or removed.
global NetControl::acld_rule_policy: hook(p: PluginState, r: Rule, ar: AclRule); global NetControl::acld_rule_policy: hook(p: PluginState, r: Rule, ar: AclRule);
## Events that are sent from us to Broker ## Events that are sent from us to Broker.
global acld_add_rule: event(id: count, r: Rule, ar: AclRule); global acld_add_rule: event(id: count, r: Rule, ar: AclRule);
global acld_remove_rule: event(id: count, r: Rule, ar: AclRule); global acld_remove_rule: event(id: count, r: Rule, ar: AclRule);
## Events that are sent from Broker to us ## Events that are sent from Broker to us.
global acld_rule_added: event(id: count, r: Rule, msg: string); global acld_rule_added: event(id: count, r: Rule, msg: string);
global acld_rule_removed: event(id: count, r: Rule, msg: string); global acld_rule_removed: event(id: count, r: Rule, msg: string);
global acld_rule_exists: event(id: count, r: Rule, msg: string); global acld_rule_exists: event(id: count, r: Rule, msg: string);

22
scripts/base/frameworks/netcontrol/plugins/broker.bro
View file

@ -1,4 +1,4 @@
##! Broker plugin for the netcontrol framework. Sends the raw data structures ##! Broker plugin for the NetControl framework. Sends the raw data structures
##! used in NetControl on to Broker to allow for easy handling, e.g., of ##! used in NetControl on to Broker to allow for easy handling, e.g., of
##! command-line scripts. ##! command-line scripts.
@ -13,25 +13,25 @@ module NetControl;
export { export {
## This record specifies the configuration that is passed to :bro:see:`NetControl::create_broker`. ## This record specifies the configuration that is passed to :bro:see:`NetControl::create_broker`.
type BrokerConfig: record { type BrokerConfig: record {
## The broker topic used to send events to ## The broker topic to send events to.
topic: string &optional; topic: string &optional;
## Broker host to connect to ## Broker host to connect to.
host: addr &optional; host: addr &optional;
## Broker port to connect to ## Broker port to connect to.
bport: port &optional; bport: port &optional;
## Do we accept rules for the monitor path? Default true ## Do we accept rules for the monitor path? Default true.
monitor: bool &default=T; monitor: bool &default=T;
## Do we accept rules for the forward path? Default true ## Do we accept rules for the forward path? Default true.
forward: bool &default=T; forward: bool &default=T;
## Predicate that is called on rule insertion or removal. ## Predicate that is called on rule insertion or removal.
## ##
## p: Current plugin state ## p: Current plugin state.
## ##
## r: The rule to be inserted or removed ## r: The rule to be inserted or removed.
## ##
## Returns: T if the rule can be handled by the current backend, F otherwhise ## Returns: T if the rule can be handled by the current backend, F otherwise.
check_pred: function(p: PluginState, r: Rule): bool &optional; check_pred: function(p: PluginState, r: Rule): bool &optional;
}; };
@ -39,9 +39,9 @@ export {
global create_broker: function(config: BrokerConfig, can_expire: bool) : PluginState; global create_broker: function(config: BrokerConfig, can_expire: bool) : PluginState;
redef record PluginState += { redef record PluginState += {
## OpenFlow controller for NetControl Broker plugin ## OpenFlow controller for NetControl Broker plugin.
broker_config: BrokerConfig &optional; broker_config: BrokerConfig &optional;
## The ID of this broker instance - for the mapping to PluginStates ## The ID of this broker instance - for the mapping to PluginStates.
broker_id: count &optional; broker_id: count &optional;
}; };

26
scripts/base/frameworks/netcontrol/plugins/openflow.bro
View file

@ -9,11 +9,11 @@ module NetControl;
export { export {
## This record specifies the configuration that is passed to :bro:see:`NetControl::create_openflow`. ## This record specifies the configuration that is passed to :bro:see:`NetControl::create_openflow`.
type OfConfig: record { type OfConfig: record {
monitor: bool &default=T; ##< accept rules that target the monitor path monitor: bool &default=T; ##< Accept rules that target the monitor path.
forward: bool &default=T; ##< accept rules that target the forward path forward: bool &default=T; ##< Accept rules that target the forward path.
idle_timeout: count &default=0; ##< default OpenFlow idle timeout idle_timeout: count &default=0; ##< Default OpenFlow idle timeout.
table_id: count &optional; ##< default OpenFlow table ID. table_id: count &optional; ##< Default OpenFlow table ID.
priority_offset: int &default=+0; ##< add this to all rule priorities. Can be useful if you want the openflow priorities be offset from the netcontrol priorities without having to write a filter function. priority_offset: int &default=+0; ##< Add this to all rule priorities. Can be useful if you want the openflow priorities be offset from the netcontrol priorities without having to write a filter function.
## Predicate that is called on rule insertion or removal. ## Predicate that is called on rule insertion or removal.
## ##
@ -21,7 +21,7 @@ export {
## ##
## r: The rule to be inserted or removed. ## r: The rule to be inserted or removed.
## ##
## Returns: T if the rule can be handled by the current backend, F otherwhise. ## Returns: T if the rule can be handled by the current backend, F otherwise.
check_pred: function(p: PluginState, r: Rule): bool &optional; check_pred: function(p: PluginState, r: Rule): bool &optional;
## This predicate is called each time an OpenFlow match record is created. ## This predicate is called each time an OpenFlow match record is created.
@ -34,10 +34,10 @@ export {
## ##
## m: The openflow match structures that were generated for this rules. ## m: The openflow match structures that were generated for this rules.
## ##
## Returns: The modified OpenFlow match structures that will be used in place the structures passed in m. ## Returns: The modified OpenFlow match structures that will be used in place of the structures passed in m.
match_pred: function(p: PluginState, e: Entity, m: vector of OpenFlow::ofp_match): vector of OpenFlow::ofp_match &optional; match_pred: function(p: PluginState, e: Entity, m: vector of OpenFlow::ofp_match): vector of OpenFlow::ofp_match &optional;
## This predicate is called before an FlowMod message is sent to the OpenFlow ## This predicate is called before a FlowMod message is sent to the OpenFlow
## device. It can modify the FlowMod message before it is passed on. ## device. It can modify the FlowMod message before it is passed on.
## ##
## p: Current plugin state. ## p: Current plugin state.
@ -46,14 +46,14 @@ export {
## ##
## m: The OpenFlow FlowMod message. ## m: The OpenFlow FlowMod message.
## ##
## Returns: The modified FloMod message that is used in lieu of m. ## Returns: The modified FlowMod message that is used in lieu of m.
flow_mod_pred: function(p: PluginState, r: Rule, m: OpenFlow::ofp_flow_mod): OpenFlow::ofp_flow_mod &optional; flow_mod_pred: function(p: PluginState, r: Rule, m: OpenFlow::ofp_flow_mod): OpenFlow::ofp_flow_mod &optional;
}; };
redef record PluginState += { redef record PluginState += {
## OpenFlow controller for NetControl OpenFlow plugin ## OpenFlow controller for NetControl OpenFlow plugin.
of_controller: OpenFlow::Controller &optional; of_controller: OpenFlow::Controller &optional;
## OpenFlow configuration record that is passed on initialization ## OpenFlow configuration record that is passed on initialization.
of_config: OfConfig &optional; of_config: OfConfig &optional;
}; };
@ -66,11 +66,11 @@ export {
duration_sec: double &default=0.0; duration_sec: double &default=0.0;
}; };
## the time interval after which an openflow message is considered to be timed out ## The time interval after which an openflow message is considered to be timed out
## and we delete it from our internal tracking. ## and we delete it from our internal tracking.
const openflow_message_timeout = 20secs &redef; const openflow_message_timeout = 20secs &redef;
## the time interval after we consider a flow timed out. This should be fairly high (or ## The time interval after we consider a flow timed out. This should be fairly high (or
## even disabled) if you expect a lot of long flows. However, one also will have state ## even disabled) if you expect a lot of long flows. However, one also will have state
## buildup for quite a while if keeping this around... ## buildup for quite a while if keeping this around...
const openflow_flow_timeout = 24hrs &redef; const openflow_flow_timeout = 24hrs &redef;

10
scripts/base/frameworks/netcontrol/shunt.bro
View file

@ -11,21 +11,21 @@ export {
## ##
## f: The flow to shunt. ## f: The flow to shunt.
## ##
## t: How long to leave the shunt in place, with 0 being indefinitly. ## t: How long to leave the shunt in place, with 0 being indefinitely.
## ##
## location: An optional string describing where the shunt was triggered. ## location: An optional string describing where the shunt was triggered.
## ##
## Returns: The id of the inserted rule on succes and zero on failure. ## Returns: The id of the inserted rule on success and zero on failure.
global shunt_flow: function(f: flow_id, t: interval, location: string &default="") : string; global shunt_flow: function(f: flow_id, t: interval, location: string &default="") : string;
type ShuntInfo: record { type ShuntInfo: record {
## Time at which the recorded activity occurred. ## Time at which the recorded activity occurred.
ts: time &log; ts: time &log;
## ID of the rule; unique during each Bro run ## ID of the rule; unique during each Bro run.
rule_id: string &log; rule_id: string &log;
## Flow ID of the shunted flow ## Flow ID of the shunted flow.
f: flow_id &log; f: flow_id &log;
## Expiry time of the shunt ## Expiry time of the shunt.
expire: interval &log; expire: interval &log;
## Location where the underlying action was triggered. ## Location where the underlying action was triggered.
location: string &log &optional; location: string &log &optional;

27
scripts/base/frameworks/netcontrol/types.bro
View file

@ -1,4 +1,4 @@
##! This file defines the that are used by the NetControl framework. ##! This file defines the types that are used by the NetControl framework.
##! ##!
##! The most important type defined in this file is :bro:see:`NetControl::Rule`, ##! The most important type defined in this file is :bro:see:`NetControl::Rule`,
##! which is used to describe all rules that can be expressed by the NetControl framework. ##! which is used to describe all rules that can be expressed by the NetControl framework.
@ -17,17 +17,16 @@ export {
## that have a :bro:see:`NetControl::RuleType` of :bro:enum:`NetControl::WHITELIST`. ## that have a :bro:see:`NetControl::RuleType` of :bro:enum:`NetControl::WHITELIST`.
const whitelist_priority: int = +5 &redef; const whitelist_priority: int = +5 &redef;
## The EntityType is used in :bro:id:`Entity` for defining the entity that a rule ## Type defining the entity that a rule applies to.
## applies to.
type EntityType: enum { type EntityType: enum {
ADDRESS, ##< Activity involving a specific IP address. ADDRESS, ##< Activity involving a specific IP address.
CONNECTION, ##< Activity involving all of a bi-directional connection's activity. CONNECTION, ##< Activity involving all of a bi-directional connection's activity.
FLOW, ##< Actitivy involving a uni-directional flow's activity. Can contain wildcards. FLOW, ##< Activity involving a uni-directional flow's activity. Can contain wildcards.
MAC, ##< Activity involving a MAC address. MAC, ##< Activity involving a MAC address.
}; };
## Flow is used in :bro:id:`Entity` together with :bro:enum:`NetControl::FLOW` to specify ## Flow is used in :bro:type:`NetControl::Entity` together with :bro:enum:`NetControl::FLOW` to specify
## a uni-directional flow that a :bro:id:`Rule` applies to. ## a uni-directional flow that a rule applies to.
## ##
## If optional fields are not set, they are interpreted as wildcarded. ## If optional fields are not set, they are interpreted as wildcarded.
type Flow: record { type Flow: record {
@ -39,7 +38,7 @@ export {
dst_m: string &optional; ##< The destination MAC address. dst_m: string &optional; ##< The destination MAC address.
}; };
## Type defining the entity an :bro:id:`Rule` is operating on. ## Type defining the entity a rule is operating on.
type Entity: record { type Entity: record {
ty: EntityType; ##< Type of entity. ty: EntityType; ##< Type of entity.
conn: conn_id &optional; ##< Used with :bro:enum:`NetControl::CONNECTION`. conn: conn_id &optional; ##< Used with :bro:enum:`NetControl::CONNECTION`.
@ -48,7 +47,7 @@ export {
mac: string &optional; ##< Used with :bro:enum:`NetControl::MAC`. mac: string &optional; ##< Used with :bro:enum:`NetControl::MAC`.
}; };
## The :bro:id`TargetType` defined the target of a :bro:id:`Rule`. ## Type defining the target of a rule.
## ##
## Rules can either be applied to the forward path, affecting all network traffic, or ## Rules can either be applied to the forward path, affecting all network traffic, or
## on the monitor path, only affecting the traffic that is sent to Bro. The second ## on the monitor path, only affecting the traffic that is sent to Bro. The second
@ -60,7 +59,7 @@ export {
}; };
## Type of rules that the framework supports. Each type lists the extra ## Type of rules that the framework supports. Each type lists the extra
## :bro:id:`Rule` argument(s) it uses, if any. ## :bro:type:`NetControl::Rule` fields it uses, if any.
## ##
## Plugins may extend this type to define their own. ## Plugins may extend this type to define their own.
type RuleType: enum { type RuleType: enum {
@ -81,7 +80,7 @@ export {
REDIRECT, REDIRECT,
## Whitelists all packets of an entity, meaning no restrictions will be applied. ## Whitelists all packets of an entity, meaning no restrictions will be applied.
## While whitelisting is the default if no rule matches an this can type can be ## While whitelisting is the default if no rule matches, this type can be
## used to override lower-priority rules that would otherwise take effect for the ## used to override lower-priority rules that would otherwise take effect for the
## entity. ## entity.
WHITELIST, WHITELIST,
@ -92,7 +91,7 @@ export {
src_h: addr &optional; ##< The source IP address. src_h: addr &optional; ##< The source IP address.
src_p: count &optional; ##< The source port number. src_p: count &optional; ##< The source port number.
dst_h: addr &optional; ##< The destination IP address. dst_h: addr &optional; ##< The destination IP address.
dst_p: count &optional; ##< The desintation port number. dst_p: count &optional; ##< The destination port number.
src_m: string &optional; ##< The source MAC address. src_m: string &optional; ##< The source MAC address.
dst_m: string &optional; ##< The destination MAC address. dst_m: string &optional; ##< The destination MAC address.
redirect_port: count &optional; redirect_port: count &optional;
@ -121,8 +120,8 @@ export {
## That being said - their design makes sense and this is probably the data one ## That being said - their design makes sense and this is probably the data one
## can expect to be available. ## can expect to be available.
type FlowInfo: record { type FlowInfo: record {
duration: interval &optional; ##< total duration of the rule duration: interval &optional; ##< Total duration of the rule.
packet_count: count &optional; ##< number of packets exchanged over connections matched by the rule packet_count: count &optional; ##< Number of packets exchanged over connections matched by the rule.
byte_count: count &optional; ##< total bytes exchanged over connections matched by the rule byte_count: count &optional; ##< Total bytes exchanged over connections matched by the rule.
}; };
} }