policy/protocols/ssl/known-certs.zeek

Known

Log information about certificates while attempting to avoid duplicate logging.

Namespace

Known

Imports

base/files/x509, base/frameworks/cluster, base/protocols/ssl, base/utils/directions-and-hosts.zeek

Summary

Runtime Options

Known::cert_store_expiry: interval &redef

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

Known::cert_store_timeout: interval &redef

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

Known::cert_tracking: Host &redef

The certificates whose existence should be logged and tracked.

Redefinable Options

Known::cert_store_name: string &redef

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

Known::use_cert_store: bool &redef

Toggles between different implementations of this script.

State Variables

Known::cert_store: Cluster::StoreInfo

Holds the set of all known certificates.

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

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

Types

Known::AddrCertHashPair: record

Known::CertsInfo: record

Redefinitions

Log::ID: enum

Events

Known::log_known_certs: event

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

Hooks

Known::log_policy_certs: Log::PolicyHook

Detailed Interface

Runtime Options

Known::cert_store_expiry
Type

interval

Attributes

&redef

Default

1.0 day

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

Known::cert_store_timeout
Type

interval

Attributes

&redef

Default

15.0 secs

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

Known::cert_tracking
Type

Host

Attributes

&redef

Default

LOCAL_HOSTS

Redefinition

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

=:

ALL_HOSTS

The certificates whose existence should be logged and tracked. Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.

Redefinable Options

Known::cert_store_name
Type

string

Attributes

&redef

Default

"zeek/known/certs"

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

Known::use_cert_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::cert_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 certificates. Keys in the store are of type Known::AddrCertHashPair and their associated value is always the boolean value of “true”.

Known::certs
Type

set [addr, string]

Attributes

&create_expire = 1.0 day &redef

Default

{}

The set of all known certificates to store for preventing duplicate logging. It can also be used from other scripts to inspect if a certificate has been seen in use. The string value in the set is for storing the DER formatted certificate’ SHA1 hash.

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

Types

Known::AddrCertHashPair
Type

record

host: addr

hash: string

Known::CertsInfo
Type

record

ts: time &log

The timestamp when the certificate was detected.

host: addr &log

The address that offered the certificate.

port_num: port &log &optional

If the certificate was handed out by a server, this is the port that the server was listening on.

subject: string &log &optional

Certificate subject.

issuer_subject: string &log &optional

Certificate issuer subject.

serial: string &log &optional

Serial number for the certificate.

Events

Known::log_known_certs
Type

event (rec: Known::CertsInfo)

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

Hooks

Known::log_policy_certs
Type

Log::PolicyHook