types.zeek

NetControl

This file defines the types that are used by the NetControl framework.

The most important type defined in this file is NetControl::Rule, which is used to describe all rules that can be expressed by the NetControl framework.

Namespace:: NetControl

Summary

Runtime Options

NetControl::default_priority: int &redef

The default priority that is used when creating rules.

Redefinable Options

NetControl::whitelist_priority: int &redef

The default priority that is used when using the high-level functions to push whitelist entries to the backends (NetControl::whitelist_address and NetControl::whitelist_subnet).

Types

`NetControl::Entity`: `record`	Type defining the entity a rule is operating on.
`NetControl::EntityType`: `enum`	Type defining the entity that a rule applies to.
`NetControl::Flow`: `record`	Flow is used in `NetControl::Entity` together with `NetControl::FLOW` to specify a uni-directional flow that a rule applies to.
`NetControl::FlowInfo`: `record`	Information of a flow that can be provided by switches when the flow times out.
`NetControl::FlowMod`: `record`	Type for defining a flow modification action.
`NetControl::Rule`: `record`	A rule for the framework to put in place.
`NetControl::RuleType`: `enum`	Type of rules that the framework supports.
`NetControl::TargetType`: `enum`	Type defining the target of a rule.

Detailed Interface

Runtime Options

NetControl::default_priority 

Type:: int
Attributes:: &redef
Default:: 0

The default priority that is used when creating rules.

Redefinable Options

NetControl::whitelist_priority 

Type:: int
Attributes:: &redef
Default:: 5

The default priority that is used when using the high-level functions to push whitelist entries to the backends (NetControl::whitelist_address and NetControl::whitelist_subnet).

Note that this priority is not automatically used when manually creating rules that have a NetControl::RuleType of NetControl::WHITELIST.

Types

NetControl::Entity 

Type:

record

ty: NetControl::EntityType: Type of entity.
conn: conn_id &optional: Used with NetControl::CONNECTION.
flow: NetControl::Flow &optional: Used with NetControl::FLOW.
ip: subnet &optional: Used with NetControl::ADDRESS to specify a CIDR subnet.
mac: string &optional: Used with NetControl::MAC.

Type defining the entity a rule is operating on.

NetControl::EntityType 

Type:

enum

NetControl::ADDRESS: Activity involving a specific IP address.

NetControl::CONNECTION: Activity involving all of a bi-directional connection’s activity.

NetControl::FLOW: Activity involving a uni-directional flow’s activity. Can contain wildcards.

NetControl::MAC: Activity involving a MAC address.

Type defining the entity that a rule applies to.

NetControl::Flow 

Type:

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 destination port number.
src_m: string &optional: The source MAC address.
dst_m: string &optional: The destination MAC address.

Flow is used in NetControl::Entity together with NetControl::FLOW to specify a uni-directional flow that a rule applies to.

If optional fields are not set, they are interpreted as wildcarded.

NetControl::FlowInfo 

Type:

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.

Information of a flow that can be provided by switches when the flow times out. Currently this is heavily influenced by the data that OpenFlow returns by default. That being said - their design makes sense and this is probably the data one can expect to be available.

NetControl::FlowMod 

Type:

record

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 destination port number.
src_m: string &optional: The source MAC address.
dst_m: string &optional: The destination MAC address.

redirect_port: count &optional

Type for defining a flow modification action.

NetControl::Rule 

Type:

record

ty: NetControl::RuleType

Type of rule.

target: NetControl::TargetType

Where to apply rule.

entity: NetControl::Entity

Entity to apply rule to.

expire: interval &optional

Timeout after which to expire the rule.

priority: int &default = NetControl::default_priority &optional

Priority if multiple rules match an entity (larger value is higher priority).

location: string &optional

Optional string describing where/what installed the rule.

out_port: count &optional

Argument for NetControl::REDIRECT rules.

mod: NetControl::FlowMod &optional

Argument for NetControl::MODIFY rules.

id: string &default = "" &optional

Internally determined unique ID for this rule. Will be set when added.

cid: count &default = 0 &optional

Internally determined unique numeric ID for this rule. Set when added.

_plugin_ids: set [count] &default = { } &optional

(present if base/frameworks/netcontrol/main.zeek is loaded)

Internally set to the plugins handling the rule.

_active_plugin_ids: set [count] &default = { } &optional

(present if base/frameworks/netcontrol/main.zeek is loaded)

Internally set to the plugins on which the rule is currently active.

_no_expire_plugins: set [count] &default = { } &optional

(present if base/frameworks/netcontrol/main.zeek is loaded)

Internally set to plugins where the rule should not be removed upon timeout.

_added: bool &default = F &optional

(present if base/frameworks/netcontrol/main.zeek is loaded)

Track if the rule was added successfully by all responsible plugins.

A rule for the framework to put in place. Of all rules currently in place, the first match will be taken, sorted by priority. All further rules will be ignored.

NetControl::RuleType 

Type:

enum

NetControl::DROP

Stop forwarding all packets matching the entity.

No additional arguments.

NetControl::MODIFY: Modify all packets matching entity. The packets will be modified according to the mod entry of the rule.

NetControl::REDIRECT: Redirect all packets matching entity to a different switch port, given in the out_port argument of the rule.

NetControl::WHITELIST: Whitelists all packets of an entity, meaning no restrictions will be applied. 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.

Type of rules that the framework supports. Each type lists the extra NetControl::Rule fields it uses, if any.

Plugins may extend this type to define their own.

NetControl::TargetType 

Type:

enum

NetControl::FORWARD

NetControl::MONITOR

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 Zeek. The second is mostly used for shunting, which allows Zeek to tell the networking hardware that it wants to no longer see traffic that it identified as benign.