mirror of
https://github.com/zeek/zeek.git
synced 2025-10-06 08:38:20 +00:00
Fix various typos in the NetControl docs
Also fixed warnings that were seen while building the docs with "make doc".
This commit is contained in:
Daniel Thayer
parent
261c6907d8
commit
3057d2b8fb
12 changed files with 159 additions and 164 deletions
|
|
@ -31,12 +31,12 @@ NetControl Architecture
|
|||
NetControl architecture (click to enlarge).
|
||||
|
||||
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
|
||||
hardware or software device), that is used to implement the commands.
|
||||
|
||||
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
|
||||
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
|
||||
|
|
@ -90,16 +90,12 @@ high-level functions.
|
|||
|
||||
* - :bro:see:`NetControl::drop_address`
|
||||
- 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`
|
||||
- Calling this function stops all packets of a specific connection
|
||||
(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`
|
||||
- Calling this function causes all packets of a specific source IP to be
|
||||
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.
|
||||
|
||||
* - :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.
|
||||
|
||||
* - :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
|
||||
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
|
||||
steps for the user.
|
||||
|
||||
* - :bro:see:`NetControl::whitelist_address`
|
||||
- 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
|
||||
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 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
|
||||
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 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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -254,7 +250,7 @@ drops all connections on the Network:
|
|||
|
||||
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
|
||||
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`.
|
||||
|
||||
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
|
||||
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,
|
||||
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
|
||||
|
|
@ -276,7 +272,7 @@ Rule Policy
|
|||
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
|
||||
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.
|
||||
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
|
||||
|
|
@ -315,7 +311,7 @@ this order:
|
|||
|
||||
* - :bro:see:`NetControl::rule_new`
|
||||
- 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.
|
||||
|
||||
* - :bro:see:`NetControl::rule_added`
|
||||
|
|
@ -328,15 +324,15 @@ this order:
|
|||
* - :bro:see:`NetControl::rule_timeout`
|
||||
- Signals that a rule timeout was reached. If the hardware does not support
|
||||
automatic timeouts, the NetControl framework will automatically call
|
||||
bro:see:`NetControl::remove_rule`.
|
||||
:bro:see:`NetControl::remove_rule`.
|
||||
|
||||
* - :bro:see:`NetControl::rule_removed`
|
||||
- Signals that a new rule has successfully been removed a backend.
|
||||
|
||||
* - :bro:see:`NetControl::rule_destroyed`
|
||||
- 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.
|
||||
This happens, for example, when a rule was removed from all backend.
|
||||
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.
|
||||
|
||||
* - :bro:see:`NetControl::rule_error`
|
||||
- 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
|
||||
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
|
||||
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
|
||||
|
|
@ -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
|
||||
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
|
||||
different specialized functions to NetControl. The documentation for catch and
|
||||
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`.
|
||||
|
||||
* - 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_dst_net_filter`). Since the functionality of the
|
||||
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
|
||||
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`.
|
||||
|
||||
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
|
||||
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
|
||||
create two functions: one that is called when a rule is added, and one that is
|
||||
|
|
|
|||
|
|
@ -10,39 +10,39 @@ export {
|
|||
|
||||
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.
|
||||
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;
|
||||
## 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;
|
||||
## Number of times an IP address was reblocked
|
||||
## Number of times an IP address was reblocked.
|
||||
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;
|
||||
## ID of the inserted block, if any.
|
||||
current_block_id: string;
|
||||
## User specified string
|
||||
## User specified string.
|
||||
location: string &optional;
|
||||
};
|
||||
|
||||
## The enum that contains the different kinds of messages that are logged by
|
||||
## catch and release
|
||||
## catch and release.
|
||||
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,
|
||||
## 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
|
||||
## 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,
|
||||
## A drop was requested by catch and release
|
||||
## A drop was requested by catch and release.
|
||||
DROP,
|
||||
## A address was succesfully blocked by catch and release
|
||||
## An address was successfully blocked by catch and release.
|
||||
DROPPED,
|
||||
## An address was unblocked after the timeout expired
|
||||
## An address was unblocked after the timeout expired.
|
||||
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,
|
||||
## A watched IP address was seen again; catch and release will re-block it.
|
||||
SEEN_AGAIN
|
||||
|
|
@ -52,7 +52,7 @@ export {
|
|||
type CatchReleaseInfo: record {
|
||||
## The absolute time indicating when the action for this log-line occured.
|
||||
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;
|
||||
## The IP address that this line refers to.
|
||||
ip: addr &log;
|
||||
|
|
@ -85,7 +85,7 @@ export {
|
|||
##
|
||||
## 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.
|
||||
##
|
||||
|
|
@ -101,17 +101,17 @@ export {
|
|||
##
|
||||
## 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.
|
||||
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
|
||||
## 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.
|
||||
##
|
||||
## 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);
|
||||
|
||||
## 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.
|
||||
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.
|
||||
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);
|
||||
}
|
||||
|
||||
# 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;
|
||||
|
||||
event bro_init() &priority=5
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ redef Cluster::manager2worker_events += /NetControl::rule_(added|removed|timeout
|
|||
|
||||
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 )
|
||||
return;
|
||||
|
||||
|
|
@ -38,8 +38,8 @@ function add_rule(r: Rule) : string
|
|||
return add_rule_impl(r);
|
||||
else
|
||||
{
|
||||
# we sync rule entities accross the cluster, so we
|
||||
# acually can test if the rule already exists. If yes,
|
||||
# We sync rule entities accross the cluster, so we
|
||||
# actually can test if the rule already exists. If yes,
|
||||
# refuse insertion already at the node.
|
||||
|
||||
if ( [r$entity, r$ty] in rule_entities )
|
||||
|
|
|
|||
|
|
@ -11,34 +11,34 @@ export {
|
|||
##
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
## 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.
|
||||
##
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
type DropInfo: record {
|
||||
## Time at which the recorded activity occurred.
|
||||
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;
|
||||
orig_h: addr &log; ##< The originator's IP address.
|
||||
orig_p: port &log &optional; ##< The originator's port number.
|
||||
resp_h: addr &log &optional; ##< The responder's IP address.
|
||||
resp_p: port &log &optional; ##< The responder's port number.
|
||||
## Expiry time of the shunt
|
||||
## Expiry time of the shunt.
|
||||
expire: interval &log;
|
||||
## Location where the underlying action was triggered.
|
||||
location: string &log &optional;
|
||||
|
|
@ -47,7 +47,7 @@ export {
|
|||
## 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.
|
||||
##
|
||||
## r: The rule to be added
|
||||
## r: The rule to be added.
|
||||
global NetControl::drop_rule_policy: hook(r: Rule);
|
||||
|
||||
## Event that can be handled to access the :bro:type:`NetControl::ShuntInfo`
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
##! 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 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.
|
||||
|
||||
module NetControl;
|
||||
|
|
@ -25,7 +25,7 @@ export {
|
|||
|
||||
## 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
|
||||
## 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.
|
||||
##
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
## Redirects an uni-directional flow to another port.
|
||||
## Redirects a uni-directional flow to another port.
|
||||
##
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
## 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
|
||||
## 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.
|
||||
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.
|
||||
##
|
||||
## 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
|
||||
## string. The ID is also assigned to ``r$id``. Note that
|
||||
## "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.
|
||||
##
|
||||
## 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
|
||||
## 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
|
||||
## wrong at that point.
|
||||
global remove_rule: function(id: string, reason: string &default="") : bool;
|
||||
|
||||
## Deletes a rule without removing in from the backends to which it has been
|
||||
## added before. This mean that no messages will be sent to the switches to which
|
||||
## 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 :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.
|
||||
##
|
||||
|
|
@ -152,9 +152,9 @@ export {
|
|||
## the worker, the internal rule variables (starting with _) will not reflect the
|
||||
## 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;
|
||||
|
||||
## Searches all rules affecting a certain subnet.
|
||||
|
|
@ -171,9 +171,9 @@ export {
|
|||
## the worker, the internal rule variables (starting with _) will not reflect the
|
||||
## 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;
|
||||
|
||||
###### Asynchronous feedback on rules.
|
||||
|
|
@ -201,7 +201,7 @@ export {
|
|||
global rule_exists: event(r: Rule, p: PluginState, msg: string &default="");
|
||||
|
||||
## Reports that a plugin reports a rule was removed due to a
|
||||
## remove: function() vall.
|
||||
## remove_rule function call.
|
||||
##
|
||||
## r: The rule now removed.
|
||||
##
|
||||
|
|
@ -234,9 +234,9 @@ export {
|
|||
|
||||
## 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 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
|
||||
## 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
|
||||
|
|
@ -248,15 +248,15 @@ export {
|
|||
## 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 or a rule remove, hook the rule_removed, rule_timeout and
|
||||
## rule_error calls.
|
||||
## To get the cause of a rule remove, catch the rule_removed, rule_timeout and
|
||||
## rule_error events.
|
||||
global rule_destroyed: event(r: Rule);
|
||||
|
||||
## 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
|
||||
## r: The rule to be added.
|
||||
global NetControl::rule_policy: hook(r: Rule);
|
||||
|
||||
##### Plugin functions
|
||||
|
|
@ -279,19 +279,19 @@ export {
|
|||
|
||||
## State of an entry in the NetControl log.
|
||||
type InfoState: enum {
|
||||
REQUESTED, ##< The request to add/remove a rule was sent to the respective backend
|
||||
SUCCEEDED, ##< A rule was succesfully added by a backend
|
||||
EXISTS, ##< A backend reported that a rule was already existing
|
||||
FAILED, ##< A rule addition failed
|
||||
REMOVED, ##< A rule was succesfully removed by a backend
|
||||
TIMEOUT, ##< A rule timeout was triggered by the NetControl framework or a backend
|
||||
REQUESTED, ##< The request to add/remove a rule was sent to the respective backend.
|
||||
SUCCEEDED, ##< A rule was successfully added by a backend.
|
||||
EXISTS, ##< A backend reported that a rule was already existing.
|
||||
FAILED, ##< A rule addition failed.
|
||||
REMOVED, ##< A rule was successfully removed by 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.
|
||||
type Info: record {
|
||||
## Time at which the recorded activity occurred.
|
||||
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;
|
||||
## Type of the log entry.
|
||||
category: InfoCategory &log &optional;
|
||||
|
|
@ -311,9 +311,9 @@ export {
|
|||
mod: string &log &optional;
|
||||
## String with an additional message.
|
||||
msg: string &log &optional;
|
||||
## Number describing the priority of the log entry
|
||||
## Number describing the priority of the log entry.
|
||||
priority: int &log &optional;
|
||||
## Expiry time of the log entry
|
||||
## Expiry time of the log entry.
|
||||
expire: interval &log &optional;
|
||||
## Location where the underlying action was triggered.
|
||||
location: string &log &optional;
|
||||
|
|
@ -333,7 +333,7 @@ redef record Rule += {
|
|||
_active_plugin_ids: set[count] &default=count_set();
|
||||
## Internally set to plugins where the rule should not be removed upon timeout.
|
||||
_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;
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ export {
|
|||
##
|
||||
## Individual plugins commonly extend this record to suit their needs.
|
||||
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();
|
||||
|
||||
## Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally.
|
||||
|
|
@ -18,14 +18,14 @@ export {
|
|||
## Set internally.
|
||||
_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;
|
||||
};
|
||||
|
||||
## Definition of a plugin.
|
||||
##
|
||||
## 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
|
||||
## that the operation failed. If a function isn't implemented by a plugin,
|
||||
## 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
|
||||
## events ``rule_{added,remove,error}`` to signal if it indeed worked out;
|
||||
## 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.
|
||||
type Plugin: record {
|
||||
## 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;
|
||||
|
||||
## 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,
|
||||
## a plugin that accepts an add_rule() should also accept the
|
||||
## remove_rule().
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
Plugins for the NetControl framework
|
||||
Plugins for the NetControl framework.
|
||||
|
|
|
|||
|
|
@ -17,24 +17,24 @@ export {
|
|||
};
|
||||
|
||||
type AcldConfig: record {
|
||||
## The acld topic used to send events to
|
||||
## The acld topic to send events to.
|
||||
acld_topic: string;
|
||||
## Broker host to connect to
|
||||
## Broker host to connect to.
|
||||
acld_host: addr;
|
||||
## Broker port to connect to
|
||||
## Broker port to connect to.
|
||||
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;
|
||||
## Do we accept rules for the forward path? Default true
|
||||
## Do we accept rules for the forward path? Default true.
|
||||
forward: bool &default=T;
|
||||
|
||||
## 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;
|
||||
};
|
||||
|
||||
|
|
@ -43,27 +43,27 @@ export {
|
|||
|
||||
redef record PluginState += {
|
||||
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;
|
||||
};
|
||||
|
||||
## 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.
|
||||
## 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);
|
||||
|
||||
## 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_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_removed: event(id: count, r: Rule, msg: string);
|
||||
global acld_rule_exists: event(id: count, r: Rule, msg: string);
|
||||
|
|
|
|||
|
|
@ -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
|
||||
##! command-line scripts.
|
||||
|
||||
|
|
@ -13,25 +13,25 @@ module NetControl;
|
|||
export {
|
||||
## This record specifies the configuration that is passed to :bro:see:`NetControl::create_broker`.
|
||||
type BrokerConfig: record {
|
||||
## The broker topic used to send events to
|
||||
## The broker topic to send events to.
|
||||
topic: string &optional;
|
||||
## Broker host to connect to
|
||||
## Broker host to connect to.
|
||||
host: addr &optional;
|
||||
## Broker port to connect to
|
||||
## Broker port to connect to.
|
||||
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;
|
||||
## Do we accept rules for the forward path? Default true
|
||||
## Do we accept rules for the forward path? Default true.
|
||||
forward: bool &default=T;
|
||||
|
||||
## 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;
|
||||
};
|
||||
|
||||
|
|
@ -39,9 +39,9 @@ export {
|
|||
global create_broker: function(config: BrokerConfig, can_expire: bool) : PluginState;
|
||||
|
||||
redef record PluginState += {
|
||||
## OpenFlow controller for NetControl Broker plugin
|
||||
## OpenFlow controller for NetControl Broker plugin.
|
||||
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;
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -9,11 +9,11 @@ module NetControl;
|
|||
export {
|
||||
## This record specifies the configuration that is passed to :bro:see:`NetControl::create_openflow`.
|
||||
type OfConfig: record {
|
||||
monitor: bool &default=T; ##< accept rules that target the monitor path
|
||||
forward: bool &default=T; ##< accept rules that target the forward path
|
||||
idle_timeout: count &default=0; ##< default OpenFlow idle timeout
|
||||
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.
|
||||
monitor: bool &default=T; ##< Accept rules that target the monitor path.
|
||||
forward: bool &default=T; ##< Accept rules that target the forward path.
|
||||
idle_timeout: count &default=0; ##< Default OpenFlow idle timeout.
|
||||
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.
|
||||
|
||||
## Predicate that is called on rule insertion or removal.
|
||||
##
|
||||
|
|
@ -21,7 +21,7 @@ export {
|
|||
##
|
||||
## 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;
|
||||
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
## 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.
|
||||
##
|
||||
## p: Current plugin state.
|
||||
|
|
@ -46,14 +46,14 @@ export {
|
|||
##
|
||||
## 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;
|
||||
};
|
||||
|
||||
redef record PluginState += {
|
||||
## OpenFlow controller for NetControl OpenFlow plugin
|
||||
## OpenFlow controller for NetControl OpenFlow plugin.
|
||||
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;
|
||||
};
|
||||
|
||||
|
|
@ -66,11 +66,11 @@ export {
|
|||
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.
|
||||
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
|
||||
## buildup for quite a while if keeping this around...
|
||||
const openflow_flow_timeout = 24hrs &redef;
|
||||
|
|
|
|||
|
|
@ -11,21 +11,21 @@ export {
|
|||
##
|
||||
## 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.
|
||||
##
|
||||
## 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;
|
||||
|
||||
type ShuntInfo: record {
|
||||
## Time at which the recorded activity occurred.
|
||||
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;
|
||||
## Flow ID of the shunted flow
|
||||
## Flow ID of the shunted flow.
|
||||
f: flow_id &log;
|
||||
## Expiry time of the shunt
|
||||
## Expiry time of the shunt.
|
||||
expire: interval &log;
|
||||
## Location where the underlying action was triggered.
|
||||
location: string &log &optional;
|
||||
|
|
|
|||
|
|
@ -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`,
|
||||
##! 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`.
|
||||
const whitelist_priority: int = +5 &redef;
|
||||
|
||||
## The EntityType is used in :bro:id:`Entity` for defining the entity that a rule
|
||||
## applies to.
|
||||
## Type defining the entity that a rule applies to.
|
||||
type EntityType: enum {
|
||||
ADDRESS, ##< Activity involving a specific IP address.
|
||||
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.
|
||||
};
|
||||
|
||||
## Flow is used in :bro:id:`Entity` together with :bro:enum:`NetControl::FLOW` to specify
|
||||
## a uni-directional flow that a :bro:id:`Rule` applies to.
|
||||
## Flow is used in :bro:type:`NetControl::Entity` together with :bro:enum:`NetControl::FLOW` to specify
|
||||
## a uni-directional flow that a rule applies to.
|
||||
##
|
||||
## If optional fields are not set, they are interpreted as wildcarded.
|
||||
type Flow: record {
|
||||
|
|
@ -39,7 +38,7 @@ export {
|
|||
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 {
|
||||
ty: EntityType; ##< Type of entity.
|
||||
conn: conn_id &optional; ##< Used with :bro:enum:`NetControl::CONNECTION`.
|
||||
|
|
@ -48,7 +47,7 @@ export {
|
|||
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
|
||||
## 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
|
||||
## :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.
|
||||
type RuleType: enum {
|
||||
|
|
@ -81,7 +80,7 @@ export {
|
|||
REDIRECT,
|
||||
|
||||
## 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
|
||||
## entity.
|
||||
WHITELIST,
|
||||
|
|
@ -92,7 +91,7 @@ export {
|
|||
src_h: addr &optional; ##< The source IP address.
|
||||
src_p: count &optional; ##< The source port number.
|
||||
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.
|
||||
dst_m: string &optional; ##< The destination MAC address.
|
||||
redirect_port: count &optional;
|
||||
|
|
@ -121,8 +120,8 @@ export {
|
|||
## That being said - their design makes sense and this is probably the data one
|
||||
## can expect to be available.
|
||||
type FlowInfo: record {
|
||||
duration: interval &optional; ##< total duration of 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
|
||||
duration: interval &optional; ##< Total duration of 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.
|
||||
};
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue