known-certs.zeek

Known

Log information about certificates while attempting to avoid duplicate logging.

Namespace:: Known
Imports:: base/files/x509, base/frameworks/cluster, base/frameworks/storage/async.zeek, base/frameworks/storage/sync.zeek, base/protocols/ssl, base/utils/directions-and-hosts.zeek, policy/frameworks/storage/backend/sqlite

Summary

Runtime Options

`Known::cert_store_expiry`: `interval` `&redef`	The expiry interval of new entries in `Known::cert_broker_store` and `Known::cert_store_backend`.
`Known::cert_store_timeout`: `interval` `&redef`	The timeout interval to use for operations against `Known::cert_broker_store` and `Known::cert_store_backend`.
`Known::cert_tracking`: `Host` `&redef`	The certificates whose existence should be logged and tracked.

Redefinable Options

`Known::cert_store_backend_options`: `Storage::BackendOptions` `&redef`	The options for the cert store.
`Known::cert_store_backend_type`: `Storage::Backend` `&redef`	The type of storage backend to open.
`Known::cert_store_name`: `string` `&redef`	The Broker topic name to use for `Known::cert_broker_store`.
`Known::cert_store_prefix`: `string` `&redef`	The name to use for `Known::cert_store_backend`.
`Known::enable_certs_persistence`: `bool` `&redef`	Use the storage framework to enable persistence of the stored certs between runs.
`Known::use_cert_store`: `bool` `&redef` `&deprecated` = …	Toggles between different implementations of this script.

State Variables

`Known::cert_broker_store`: `Cluster::StoreInfo`	Storage configuration for Broker stores Holds the set of all known certs.
`Known::cert_store_backend`: `opaque`	Storage configuration for storage framework stores This requires setting a configuration in local.zeek that sets the Known::enable_certs_persistence boolean to T, and optionally setting different values in the Known::cert_store_backend_options record.
`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

Known::CERTS_LOG

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_broker_store and Known::cert_store_backend. 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_broker_store and Known::cert_store_backend.

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_backend_options 

Type:

Storage::BackendOptions

Attributes:

&redef

Default:

{
   serializer=Storage::STORAGE_SERIALIZER_JSON
   forced_sync=F
   redis=<uninitialized>
   sqlite=[database_path="/known/certs.sqlite", table_name="zeekknowncerts", busy_timeout=5.0 secs, pragma_commands={
      ["quick_check"] = "",
      ["journal_mode"] = "WAL",
      ["synchronous"] = "normal",
      ["temp_store"] = "memory"
   }, pragma_timeout=500.0 msecs, pragma_wait_on_busy=5.0 msecs]
}

The options for the cert store. This should be redef’d in local.zeek to set connection information for the backend. The options default to a central persistent sqlite database.

Known::cert_store_backend_type 

Type:: Storage::Backend
Attributes:: &redef
Default:: Storage::STORAGE_BACKEND_SQLITE

The type of storage backend to open.

Known::cert_store_name 

Type:: string
Attributes:: &redef
Default:: "zeek/known/certs"

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

Known::cert_store_prefix 

Type:: string
Attributes:: &redef
Default:: "zeekknowncerts"

The name to use for Known::cert_store_backend. This will be used by the backends to differentiate tables/keys. This should be alphanumeric so that it can be used as the table name for the storage framework.

Known::enable_certs_persistence 

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

Use the storage framework to enable persistence of the stored certs between runs.

Known::use_cert_store 

Type:: bool
Attributes:: &redef &deprecated = “Remove in v9.1. Store support has been disabled by default since Zeek 6.0 due to performance issues and will be removed.”
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_broker_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
}

Storage configuration for Broker stores Holds the set of all known certs. Keys in the store are Known::AddrPortServTriplet and their associated value is always the boolean value of “true”.

Known::cert_store_backend 

Type:: opaque of Storage::BackendHandle

Storage configuration for storage framework stores This requires setting a configuration in local.zeek that sets the Known::enable_certs_persistence boolean to T, and optionally setting different values in the Known::cert_store_backend_options record. Backend to use for storing known certs data using the storage framework.

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.