policy/protocols/conn/known-services.bro

Known

This script logs and tracks services. In the case of this script, a service is defined as an IP address and port which has responded to and fully completed a TCP handshake with another host. If a protocol is detected during the session, the protocol will also be logged.

Namespace:Known Imports:base/frameworks/cluster, base/utils/directions-and-hosts.bro Source File:/scripts/policy/protocols/conn/known-services.bro

Summary

Runtime Options

Known::service_store_timeout: interval &redef	The timeout interval to use for operations against Known::service_store.
Known::service_tracking: Host &redef	The hosts whose services should be tracked and logged.

Redefinable Options

Known::service_store_expiry: interval &redef	The expiry interval of new entries in Known::service_store.
Known::service_store_name: string &redef	The Broker topic name to use for Known::service_store.
Known::use_service_store: bool &redef	Toggles between different implementations of this script.

State Variables

Known::service_store: Cluster::StoreInfo	Holds the set of all known services.
Known::services: set &create_expire = 1.0 day	Tracks the set of daily-detected services for preventing the logging of duplicates, but can also be inspected by other scripts for different purposes.

Types

Known::AddrPortPair: record
Known::ServicesInfo: record	The record type which contains the column fields of the known-services log.

Redefinitions

Log::ID: enum	The known-services logging stream identifier.
connection: record

Events

Known::log_known_services: event

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

Detailed Interface

Runtime Options

Known::service_store_timeout

Type:interval Attributes:&redef Default:15.0 secs

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

Known::service_tracking

Type:Host Attributes:&redef Default:ALL_HOSTS

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

Redefinable Options

Known::service_store_expiry

Type:interval Attributes:&redef Default:1.0 day

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

Known::service_store_name

Type:string Attributes:&redef Default:"bro/known/services"

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

Known::use_service_store

Type:bool Attributes:&redef Default:T

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

State Variables

Known::service_store

Type:Cluster::StoreInfo Default:

{
   name=<uninitialized>
   store=<uninitialized>
   master_node=""
   master=F
   backend=Broker::MEMORY
   options=[sqlite=[path=""], rocksdb=[path=""]]
   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 services. Keys in the store are Known::AddrPortPair and their associated value is always the boolean value of “true”.

Known::services

Type:set [addr, port] Attributes:&create_expire = 1.0 day Default:{}

Tracks the set of daily-detected services for preventing the logging of duplicates, but can also be inspected by other scripts for different purposes.

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

This set is automatically populated and shouldn’t be directly modified.

Types

Known::AddrPortPair

Type:

record

host: addr

p: port

Known::ServicesInfo

Type:

record

ts: time &log

The time at which the service was detected.

host: addr &log

The host address on which the service is running.

port_num: port &log

The port number on which the service is running.

port_proto: transport_proto &log

The transport-layer protocol which the service uses.

service: set [string] &log

A set of protocols that match the service’s connection payloads.

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

Events

Known::log_known_services

Type:event (rec: Known::ServicesInfo)

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