base/frameworks/netcontrol/catch-and-release.bro

NetControl

Implementation of catch-and-release functionality for NetControl.

Namespace:NetControl
Imports:base/frameworks/cluster, base/frameworks/netcontrol/drop.bro, base/frameworks/netcontrol/main.bro
Source File:/scripts/base/frameworks/netcontrol/catch-and-release.bro

Summary

Runtime Options

NetControl::catch_release_warn_blocked_ip_encountered: bool &redef If true, catch and release warns if packets of an IP address are still seen after it should have been blocked.

Redefinable Options

NetControl::catch_release_intervals: vector &redef Time intervals for which subsequent drops of the same IP take effect.
NetControl::watch_connections: bool &redef If true, catch_release_seen is called on the connection originator in new_connection, connection_established, partial_connection, connection_attempt, connection_rejected, connection_reset and connection_pending

Types

NetControl::BlockInfo: record This record is used for storing information about current blocks that are part of catch and release.
NetControl::CatchReleaseActions: enum The enum that contains the different kinds of messages that are logged by catch and release.
NetControl::CatchReleaseInfo: record The record type that is used for representing and logging

Redefinitions

Log::ID: enum  

Events

NetControl::catch_release_add: event  
NetControl::catch_release_block_delete: event  
NetControl::catch_release_block_new: event  
NetControl::catch_release_delete: event  
NetControl::catch_release_encountered: event  
NetControl::catch_release_forgotten: event Event is raised when catch and release cases management of an IP address because no activity was seen within the watch_until period.
NetControl::log_netcontrol_catch_release: event Event that can be handled to access the NetControl::CatchReleaseInfo record as it is sent on to the logging framework.

Functions

NetControl::catch_release_seen: function This function can be called to notify the catch and release script that activity by an IP address was seen.
NetControl::drop_address_catch_release: function Stops all packets involving an IP address from being forwarded.
NetControl::get_catch_release_info: function Get the NetControl::BlockInfo record for an address currently blocked by catch and release.
NetControl::unblock_address_catch_release: function Removes an address from being watched with catch and release.

Detailed Interface

Runtime Options

NetControl::catch_release_warn_blocked_ip_encountered
Type:bool
Attributes:&redef
Default:F

If true, catch and release warns if packets of an IP address are still seen after it should have been blocked.

Redefinable Options

NetControl::catch_release_intervals
Type:vector of interval
Attributes:&redef
Default:
[10.0 mins, 1.0 hr, 1.0 day, 7.0 days]

Time intervals for which subsequent drops of the same IP take effect.

NetControl::watch_connections
Type:bool
Attributes:&redef
Default:T

If true, catch_release_seen is called on the connection originator in new_connection, connection_established, partial_connection, connection_attempt, connection_rejected, connection_reset and connection_pending

Types

NetControl::BlockInfo
Type:

record

block_until: time &optional

Absolute time indicating until when a block is inserted using NetControl.

watch_until: time

Absolute time indicating until when an IP address is watched to reblock it.

num_reblocked: count &default = 0 &optional

Number of times an IP address was reblocked.

current_interval: count

Number indicating at which catch and release interval we currently are.

current_block_id: string

ID of the inserted block, if any.

location: string &optional

User specified string.

This record is used for storing information about current blocks that are part of catch and release.

NetControl::CatchReleaseActions
Type:

enum

NetControl::INFO

Log lines marked with info are purely informational; no action was taken.

NetControl::ADDED

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 expires.

NetControl::DROP

(present if base/frameworks/netcontrol/types.bro is loaded)

Stop forwarding all packets matching the entity.

No additional arguments.

NetControl::DROPPED

A drop was requested by catch and release. An address was successfully blocked by catch and release.

NetControl::UNBLOCK

An address was unblocked after the timeout expired.

NetControl::FORGOTTEN

An address was forgotten because it did not reappear within the watch_until interval.

NetControl::SEEN_AGAIN

A watched IP address was seen again; catch and release will re-block it.

The enum that contains the different kinds of messages that are logged by catch and release.

NetControl::CatchReleaseInfo
Type:

record

ts: time &log

The absolute time indicating when the action for this log-line occured.

rule_id: string &log &optional

The rule id that this log line refers to.

ip: addr &log

The IP address that this line refers to.

action: NetControl::CatchReleaseActions &log

The action that was taken in this log-line.

block_interval: interval &log &optional

The current block_interaval (for how long the address is blocked).

watch_interval: interval &log &optional

The current watch_interval (for how long the address will be watched and re-block if it reappears).

blocked_until: time &log &optional

The absolute time until which the address is blocked.

watched_until: time &log &optional

The absolute time until which the address will be monitored.

num_blocked: count &log &optional

Number of times that this address was blocked in the current cycle.

location: string &log &optional

The user specified location string.

message: string &log &optional

Additional informational string by the catch and release framework about this log-line.

The record type that is used for representing and logging

Events

NetControl::catch_release_add
Type:event (a: addr, location: string)
NetControl::catch_release_block_delete
Type:event (a: addr)
NetControl::catch_release_block_new
Type:event (a: addr, b: NetControl::BlockInfo)
NetControl::catch_release_delete
Type:event (a: addr, reason: string)
NetControl::catch_release_encountered
Type:event (a: addr)
NetControl::catch_release_forgotten
Type:event (a: addr, bi: NetControl::BlockInfo)

Event is raised when catch and release cases management of an IP address because no activity was seen within the watch_until period.

A:The address that is no longer being managed.
Bi:The NetControl::BlockInfo record containing information about the block.
NetControl::log_netcontrol_catch_release
Type:event (rec: NetControl::CatchReleaseInfo)

Event that can be handled to access the NetControl::CatchReleaseInfo record as it is sent on to the logging framework.

Functions

NetControl::catch_release_seen
Type:function (a: addr) : void

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 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.
NetControl::drop_address_catch_release
Type:function (a: addr, location: string &default = "" &optional) : NetControl::BlockInfo

Stops all packets involving an IP address from being forwarded. This function uses catch-and-release functionality, where the IP address is only dropped for a short amount of time that is incremented steadily when the IP is encountered again.

In cluster mode, this function works on workers as well as the manager. On managers, the returned NetControl::BlockInfo record will not contain the block ID, which will be assigned on the manager.

A:The address to be dropped.
T:How long to drop it, with 0 being indefinitely.
Location:An optional string describing where the drop was triggered.
Returns:The NetControl::BlockInfo record containing information about the inserted block.
NetControl::get_catch_release_info
Type:function (a: addr) : NetControl::BlockInfo

Get the NetControl::BlockInfo record for an address currently blocked by catch and release. If the address is unknown to catch and release, the watch_until time will be set to 0.

In cluster mode, this function works on the manager and workers. On workers, the data will lag slightly behind the manager; if you add a block, it will not be instantly available via this function.

A:The address to get information about.
Returns:The NetControl::BlockInfo record containing information about the inserted block.
NetControl::unblock_address_catch_release
Type:function (a: addr, reason: string &default = "" &optional) : bool

Removes an address from being watched with catch and release. Returns true if the address was found and removed; returns false if it was unknown to catch and release.

If the address is currently blocked, and the block was inserted by catch and release, the block is removed.

A:The address to be unblocked.
Reason:A reason for the unblock.
Returns:True if the address was unblocked.
Copyright 2016, The Bro Project. Last updated on January 10, 2019. Created using Sphinx 1.7.5.