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.

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:	`T`

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=""], 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 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.