base/frameworks/netcontrol/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.