policy/protocols/conn/known-hosts.zeek

Known

This script logs hosts that Zeek determines have performed complete TCP handshakes and logs the address once per day (by default). The log that is output provides an easy way to determine a count of the IP addresses in use on a network per day.

Namespace

Known

Imports

base/frameworks/cluster, base/utils/directions-and-hosts.zeek

Summary

Runtime Options

Known::host_store_timeout: interval &redef

The timeout interval to use for operations against Known::host_store.

Known::host_tracking: Host &redef

The hosts whose existence should be logged and tracked.

Redefinable Options

Known::host_store_expiry: interval &redef

The expiry interval of new entries in Known::host_store.

Known::host_store_name: string &redef

The Broker topic name to use for Known::host_store.

Known::use_host_store: bool &redef

Toggles between different implementations of this script.

State Variables

Known::host_store: Cluster::StoreInfo

Holds the set of all known hosts.

Known::hosts: set &create_expire = 1.0 day &redef

The set of all known addresses to store for preventing duplicate logging of addresses.

Types

Known::HostsInfo: record

The record type which contains the column fields of the known-hosts log.

Redefinitions

Log::ID: enum

The known-hosts logging stream identifier.

Events

Known::log_known_hosts: event

An event that can be handled to access the Known::HostsInfo record as it is sent on to the logging framework.

Hooks

Known::log_policy_hosts: Log::PolicyHook

A default logging policy hook for the stream.

Detailed Interface

Runtime Options

Known::host_store_timeout
Type

interval

Attributes

&redef

Default

15.0 secs

The timeout interval to use for operations against Known::host_store.

Known::host_tracking
Type

Host

Attributes

&redef

Default

LOCAL_HOSTS

Redefinition

from policy/tuning/track-all-assets.zeek

=:

ALL_HOSTS

The hosts whose existence should be logged and tracked. See Host for possible choices.

Redefinable Options

Known::host_store_expiry
Type

interval

Attributes

&redef

Default

1.0 day

The expiry interval of new entries in Known::host_store. This also changes the interval at which hosts get logged.

Known::host_store_name
Type

string

Attributes

&redef

Default

"zeek/known/hosts"

The Broker topic name to use for Known::host_store.

Known::use_host_store
Type

bool

Attributes

&redef

Default

F

Toggles between different implementations of this script. When true, use a Broker data store, else use a regular Zeek set with keys uniformly distributed over proxy nodes in cluster operation.

State Variables

Known::host_store
Type

Cluster::StoreInfo

Default
{
   name=<uninitialized>
   store=<uninitialized>
   master_node=""
   master=F
   backend=Broker::MEMORY
   options=[sqlite=[path="", synchronous=<uninitialized>, journal_mode=<uninitialized>, failure_mode=Broker::SQLITE_FAILURE_MODE_FAIL, integrity_check=F]]
   clone_resync_interval=10.0 secs
   clone_stale_interval=5.0 mins
   clone_mutation_buffer_interval=2.0 mins
}

Holds the set of all known hosts. Keys in the store are addresses and their associated value will always be the “true” boolean.

Known::hosts
Type

set [addr]

Attributes

&create_expire = 1.0 day &redef

Default

{}

The set of all known addresses to store for preventing duplicate logging of addresses. It can also be used from other scripts to inspect if an address has been seen in use. Maintain the list of known hosts for 24 hours so that the existence of each individual address is logged each day.

In cluster operation, this set is distributed uniformly across proxy nodes.

Types

Known::HostsInfo
Type

record

ts: time &log

The timestamp at which the host was detected.

host: addr &log

The address that was detected originating or responding to a TCP connection.

The record type which contains the column fields of the known-hosts log.

Events

Known::log_known_hosts
Type

event (rec: Known::HostsInfo)

An event that can be handled to access the Known::HostsInfo record as it is sent on to the logging framework.

Hooks

Known::log_policy_hosts
Type

Log::PolicyHook

A default logging policy hook for the stream.