Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 14:48:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Write NetControl framework documentation.

Browse source 
In the process, some of the script documentation of the NetControl
framework was also updated.
This commit is contained in:
Johanna Amann 2016-06-22 16:02:48 -07:00
parent 3b55a917ac
commit f1267b0b94
78 changed files with 1918 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -2,6 +2,7 @@
module NetControl;
@load base/frameworks/cluster
@load ./main
@load ./drop
@ -9,45 +10,67 @@ export {
redef enum Log::ID += { CATCH_RELEASE };
# The record that is used for storing information about current blocks that are
# part of catch and release.
## Thhis record is used 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.
## 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
type CatchReleaseActions: enum {
## 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.
ADDED,
## A drop was requested by catch and release
DROP,
## A address was succesfully blocked by catch and release
DROPPED,
## An address was unblocked after the timeout expired
UNBLOCK,
RESTORED,
## 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
};
## The record type that is used for representing and logging
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.
rule_id: string &log &optional;
## The IP address that this line refers to.
ip: addr &log;
## The action that was taken in this log-line.
action: CatchReleaseActions &log;
## The current block_interaval (for how long the address is blocked).
block_interval: interval &log &optional;
## The current watch_interval (for how long the address will be watched and re-block if it reappears).
watch_interval: interval &log &optional;
## The absolute time until which the address is blocked.
blocked_until: time &log &optional;
## The absolute time until which the address will be monitored.
watched_until: time &log &optional;
## Number of times that this address was blocked in the current cycle.
num_blocked: count &log &optional;
## The user specified location string.
location: string &log &optional;
## Additional informational string by the catch and release framework about this log-line.
message: string &log &optional;
};

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

@ -81,9 +81,11 @@ export {
## Returns: The id of the inserted rule on succes and zero on failure.
global redirect_flow: function(f: flow_id, out_port: count, t: interval, location: string &default="") : string;
## Quarantines a host by redirecting rewriting DNS queries to the network dns server dns
## to the host. Host has to answer to all queries with its own address. Only http communication
## from infected to quarantinehost is allowed.
## Quarantines a host. This requires a special quarantine server, which runs a HTTP server explaining
## the quarantine and a DNS server which resolves all requests to the quarantine server. DNS queries
## from the host to the network dns server will be rewritten and will be sent to the quarantine server
## instead. Only http communication infected to quarantinehost is allowed. All other network communication
## is blocked.
##
## infected: the host to quarantine
##
@ -96,7 +98,7 @@ export {
## 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;
## Flushes all state.
## Flushes all state by calling :bro:see:`NetControl::remove_rule` on all currently active rules.
global clear: function();
# ###
@ -120,7 +122,7 @@ export {
## Removes a rule.
##
## id: The rule to remove, specified as the ID returned by :bro:id:`NetControl::add_rule`.
## id: The rule to remove, specified as the ID returned by :bro:see:`NetControl::add_rule`.
##
## Returns: True if succesful, the relevant plugin indicated that it knew
## how to handle the removal. Note that again "success" means the
@ -134,10 +136,10 @@ export {
## 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:id:`add_rule` .
## id: The rule to delete, specified as the ID returned by :bro:see:`add_rule` .
##
## Returns: True if removal is successful, or sent to manager.
## False if the rule could not be found.
## False if the rule could not be found.
global delete_rule: function(id: string) : bool;
## Searches all rules affecting a certain IP address.
@ -152,6 +154,14 @@ export {
global find_rules_addr: function(ip: addr) : vector of Rule;
## Searches all rules affecting a certain subnet.
##
## A rule affects a subnet, if it covers the whole subnet. Note especially that
## this function will not reveal all rules that are covered by a subnet.
##
## For example, a search for 192.168.17.0/8 will reveal a rule that exists for
## 192.168.0.0/16, since this rule affects the subnet. However, it will not reveal
## a more specific rule for 192.168.17.1/32, which does not directy affect the whole
## subnet.
##
## This function works on both the manager and workers of a cluster. Note that on
## the worker, the internal rule variables (starting with _) will not reflect the
@ -263,14 +273,14 @@ export {
RULE
};
## State of an entry in the NetControl log.
## State of an entry in the NetControl log.
type InfoState: enum {
REQUESTED,
SUCCEEDED,
EXISTS,
FAILED,
REMOVED,
TIMEOUT,
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
};
## The record type defining the column fields of the NetControl log.
@ -313,13 +323,13 @@ export {
}
redef record Rule += {
##< Internally set to the plugins handling the rule.
## Internally set to the plugins handling the rule.
_plugin_ids: set[count] &default=count_set();
##< Internally set to the plugins on which the rule is currently active.
## Internally set to the plugins on which the rule is currently active.
_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();
##< Track if the rule was added succesfully by all responsible plugins.
## Track if the rule was added succesfully by all responsible plugins.
_added: bool &default=F;
};

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

@ -1,11 +1,13 @@
##! Plugin interface for NetControl backends.
##! This file defines the plugin interface for NetControl.
module NetControl;
@load ./types
export {
## State for a plugin instance.
## This record keeps the per instance state of a plugin.
##
## Individual plugins commonly extend this record to suit their needs.
type PluginState: record {
## Table for a plugin to store custom, instance-specfific state.
config: table[string] of string &default=table();
@ -20,69 +22,69 @@ export {
_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
# 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.
#
# 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
# something it thought it could handle.
## 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
## 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.
##
## 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
## something it thought it could handle.
type Plugin: record {
# Returns a descriptive name of the plugin instance, suitable for use in logging
# messages. Note that this function is not optional.
## Returns a descriptive name of the plugin instance, suitable for use in logging
## messages. Note that this function is not optional.
name: function(state: PluginState) : string;
## If true, plugin can expire rules itself. If false,
## If true, plugin can expire rules itself. If false, the NetControl
## framework will manage rule expiration.
can_expire: bool;
# One-time initialization function called when plugin gets registered, and
# before any other methods are called.
#
# If this function is provided, NetControl assumes that the plugin has to
# perform, potentially lengthy, initialization before the plugin will become
# active. In this case, the plugin has to call ``NetControl::plugin_activated``,
# once initialization finishes.
## One-time initialization function called when plugin gets registered, and
## before any other methods are called.
##
## If this function is provided, NetControl assumes that the plugin has to
## perform, potentially lengthy, initialization before the plugin will become
## active. In this case, the plugin has to call ``NetControl::plugin_activated``,
## once initialization finishes.
init: function(state: PluginState) &optional;
# One-time finalization function called when a plugin is shutdown; no further
# functions will be called afterwords.
## One-time finalization function called when a plugin is shutdown; no further
## functions will be called afterwords.
done: function(state: PluginState) &optional;
# Implements the add_rule() operation. If the plugin accepts the rule,
# it returns true, false otherwise. The rule will already have its
# ``id`` field set, which the plugin may use for identification
# purposes.
## Implements the add_rule() operation. If the plugin accepts the rule,
## it returns true, false otherwise. The rule will already have its
## ``id`` field set, which the plugin may use for identification
## purposes.
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
# ``id`` field will match that of the add_rule() call. Generally,
# a plugin that accepts an add_rule() should also accept the
# remove_rule().
## Implements the remove_rule() operation. This will only be called for
## rules that the plugins 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().
remove_rule: function(state: PluginState, r: Rule) : bool &optional;
# A transaction groups a number of operations. The plugin can add them internally
# and postpone putting them into effect until committed. This allows to build a
# configuration of multiple rules at once, including replaying a previous state.
## A transaction groups a number of operations. The plugin can add them internally
## and postpone putting them into effect until committed. This allows to build a
## configuration of multiple rules at once, including replaying a previous state.
transaction_begin: function(state: PluginState) &optional;
transaction_end: function(state: PluginState) &optional;
};
# Table for a plugin to store instance-specific configuration information.
#
# Note, it would be nicer to pass the Plugin instance to all the below, instead
# of this state table. However Bro's type resolver has trouble with refering to a
# record type from inside itself.
## Table for a plugin to store instance-specific configuration information.
##
## Note, it would be nicer to pass the Plugin instance to all the below, instead
## of this state table. However Bro's type resolver has trouble with refering to a
## record type from inside itself.
redef record PluginState += {
## The plugin that the state belongs to. (Defined separately
## because of cyclic type dependency.)
## because of cyclic type dependency.)
plugin: Plugin &optional;
};

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

@ -11,6 +11,7 @@ module NetControl;
@ifdef ( Broker::__enable )
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
topic: string &optional;
@ -38,6 +39,7 @@ export {
global create_broker: function(config: BrokerConfig, can_expire: bool) : PluginState;
redef record PluginState += {
## OpenFlow controller for NetControl Broker plugin
broker_config: BrokerConfig &optional;
## The ID of this broker instance - for the mapping to PluginStates
broker_id: count &optional;

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

@ -7,22 +7,46 @@
module NetControl;
export {
## This record specifies the configuration that is passed to :bro:see:`NetControl::create_openflow`.
type OfConfig: record {
monitor: bool &default=T;
forward: bool &default=T;
idle_timeout: count &default=0;
table_id: count &optional;
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.
##
## 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 otherwhise.
check_pred: function(p: PluginState, r: Rule): bool &optional;
## This predicate is called each time an OpenFlow match record is created.
## The predicate can modify the match structure before it is sent on to the
## device.
##
## p: Current plugin state.
##
## r: The rule to be inserted or removed.
##
## 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.
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
## device. It can modify the FlowMod message before it is passed on.
##
## p: Current plugin state.
##
## r: The rule to be inserted or removed.
##
## m: The OpenFlow FlowMod message.
##
## Returns: The modified FloMod 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;
};

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

@ -1,30 +1,45 @@
##! Types used by the NetControl framework.
##! This file defines the 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.
module NetControl;
export {
## The default priority that is used when creating rules.
const default_priority: int = +0 &redef;
## The default priority that is used when using the high-level functions to
## push whitelist entries to the backends (:bro:see:`NetControl::whitelist_address` and
## :bro:see:`NetControl::whitelist_subnet`).
##
## Note that this priority is not automatically used when manually creating rules
## that have a :bro:see:`NetControl::RuleType` of :bro:enum:`NetControl::WHITELIST`.
const whitelist_priority: int = +5 &redef;
## Type of a :bro:id:`Entity` for defining an action.
## The EntityType is used in :bro:id:`Entity` for defining the entity that a rule
## applies to.
type EntityType: enum {
ADDRESS, ##< Activity involving a specific IP address.
CONNECTION, ##< All of a bi-directional connection's activity.
FLOW, ##< All of a uni-directional flow's activity. Can contain wildcards.
CONNECTION, ##< Activity involving all of a bi-directional connection's activity.
FLOW, ##< Actitivy involving a uni-directional flow's activity. Can contain wildcards.
MAC, ##< Activity involving a MAC address.
};
## Type for defining a flow.
## 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.
##
## If optional fields are not set, they are interpreted as wildcarded.
type Flow: record {
src_h: subnet &optional; ##< The source IP address/subnet.
src_p: port &optional; ##< The source port number.
dst_h: subnet &optional; ##< The destination IP address/subnet.
dst_p: port &optional; ##< The desintation port number.
dst_p: port &optional; ##< The destination port number.
src_m: string &optional; ##< The source MAC address.
dst_m: string &optional; ##< The destination MAC address.
};
## Type defining the enity an :bro:id:`Rule` is operating on.
## Type defining the entity an :bro:id:`Rule` is operating on.
type Entity: record {
ty: EntityType; ##< Type of entity.
conn: conn_id &optional; ##< Used with :bro:enum:`NetControl::CONNECTION`.
@ -33,32 +48,36 @@ export {
mac: string &optional; ##< Used with :bro:enum:`NetControl::MAC`.
};
## Target of :bro:id:`Rule` action.
## The :bro:id`TargetType` defined the target of a :bro:id:`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
## is mostly used for shunting, which allows Bro to tell the networking hardware that
## it wants to no longer see traffic that it identified as benign.
type TargetType: enum {
FORWARD, #< Apply rule actively to traffic on forwarding path.
MONITOR, #< Apply rule passively to traffic sent to Bro for monitoring.
};
## Type of rules that the framework supports. Each type lists the
## Type of rules that the framework supports. Each type lists the extra
## :bro:id:`Rule` argument(s) it uses, if any.
##
## Plugins may extend this type to define their own.
type RuleType: enum {
## Stop forwarding all packets matching entity.
## Stop forwarding all packets matching the entity.
##
## No arguments.
## No additional arguments.
DROP,
## Begin modifying all packets matching entity.
## Modify all packets matching entity. The packets
## will be modified according to the `mod` entry of
## the rule.
##
## .. todo::
## Define arguments.
MODIFY,
## Begin redirecting all packets matching entity.
## Redirect all packets matching entity to a different switch port,
## given in the `out_port` argument of the rule.
##
## .. todo::
## c: output port to redirect traffic to.
REDIRECT,
## Whitelists all packets of an entity, meaning no restrictions will be applied.