File Analyzers

This event is generated when a file extraction analyzer is about to exceed the maximum permitted file size allowed by the extract_limit field of Files::AnalyzerArgs. The analyzer is automatically removed from file f.

Parameters:

f – The file.
args – Arguments that identify a particular file extraction analyzer. This is only provided to be able to pass along to FileExtract::set_limit.
limit – The limit, in bytes, the extracted file is about to breach.
len – The length of the file chunk about to be written.

Functions

FileExtract::__set_limit

Type:: function (file_id: string, args: any, n: count) : bool

FileExtract::set_limit.

Zeek::FileHash

Hash file content

Components

Files::ANALYZER_MD5

Files::ANALYZER_SHA1

Files::ANALYZER_SHA256

Events

file_hash

Type:: event (f: fa_file, kind: string, hash: string)

This event is generated each time file analysis generates a digest of the file contents.

Parameters:

f – The file.
kind – The type of digest algorithm.
hash – The result of the hashing.

Zeek::PE

Portable Executable analyzer

Components

Files::ANALYZER_PE

Events

pe_dos_header 

Type:: event (f: fa_file, h: PE::DOSHeader)

A PE file DOS header was parsed. This is the top-level header and contains information like the size of the file, initial value of registers, etc.

Parameters:

f – The file.
h – The parsed DOS header information.

pe_dos_code

Type:: event (f: fa_file, code: string)

A PE file DOS stub was parsed. The stub is a valid application that runs under MS-DOS, by default to inform the user that the program can’t be run in DOS mode.

Parameters:

f – The file.
code – The DOS stub

pe_file_header 

Type:: event (f: fa_file, h: PE::FileHeader)

A PE file file header was parsed. This header contains information like the target machine, the timestamp when the file was created, the number of sections, and pointers to other parts of the file.

Parameters:

f – The file.
h – The parsed file header information.

pe_optional_header 

Type:: event (f: fa_file, h: PE::OptionalHeader)

A PE file optional header was parsed. This header is required for executable files, but not for object files. It contains information like OS requirements to execute the file, the original entry point address, and information needed to load the file into memory.

Parameters:

f – The file.
h – The parsed optional header information.

pe_section_header 

Type:: event (f: fa_file, h: PE::SectionHeader)

A PE file section header was parsed. This header contains information like the section name, size, address, and characteristics.

Parameters:

f – The file.
h – The parsed section header information.

Zeek::X509

X509 and OCSP analyzer

Components

Files::ANALYZER_OCSP_REPLY

Files::ANALYZER_OCSP_REQUEST

Files::ANALYZER_X509

Types

X509::Certificate 

Type:

record

version: count &log: Version number.
serial: string &log: Serial number.
subject: string &log: Subject.
issuer: string &log: Issuer.
cn: string &optional: Last (most specific) common name.
not_valid_before: time &log: Timestamp before when certificate is not valid.
not_valid_after: time &log: Timestamp after when certificate is not valid.
key_alg: string &log: Name of the key algorithm
sig_alg: string &log: Name of the signature algorithm
key_type: string &optional &log: Key type, if key parseable by openssl (either rsa, dsa or ec)
key_length: count &optional &log: Key length in bits
exponent: string &optional &log: Exponent, if RSA-certificate
curve: string &optional &log: Curve, if EC-certificate
tbs_sig_alg: string: Name of the signature algorithm given inside the tbsCertificate. Should be equivalent to sig_alg.

X509::Extension 

Type:

record

name: string: Long name of extension. oid if name not known
short_name: string &optional: Short name of extension if known
oid: string: Oid of extension
critical: bool: True if extension is critical
value: string: Extension content parsed to string for known extensions. Raw data otherwise.

X509::BasicConstraints 

Type:

record

ca: bool &log: CA flag set?
path_len: count &optional &log: Maximum path length

Attributes:

&log

X509::SubjectAlternativeName 

Type:

record

dns: string_vec &optional &log: List of DNS entries in SAN
uri: string_vec &optional &log: List of URI entries in SAN
email: string_vec &optional &log: List of email entries in SAN
ip: addr_vec &optional &log: List of IP entries in SAN
other_fields: bool: True if the certificate contained other, not recognized or parsed name fields

X509::Result 

Type:

record

result: int: OpenSSL result code
result_string: string: Result as string
chain_certs: vector of opaque of x509 &optional: References to the final certificate chain, if verification successful. End-host certificate is first.

Result of an X509 certificate chain verification

Events

x509_certificate

Type:: event (f: fa_file, cert_ref: opaque of x509, cert: X509::Certificate)

Generated for encountered X509 certificates, e.g., in the clear SSL/TLS connection handshake.

See Wikipedia for more information about the X.509 format.

Parameters:

f – The file.
cert_ref – An opaque pointer to the underlying OpenSSL data structure of the certificate.
cert – The parsed certificate information.

x509_extension 

Type:: event (f: fa_file, ext: X509::Extension)

Generated for X509 extensions seen in a certificate.

See Wikipedia for more information about the X.509 format.

Parameters:

f – The file.
ext – The parsed extension.

x509_ext_basic_constraints 

Type:: event (f: fa_file, ext: X509::BasicConstraints)

Generated for the X509 basic constraints extension seen in a certificate. This extension can be used to identify the subject of a certificate as a CA.

Parameters:

f – The file.
ext – The parsed basic constraints extension.

x509_ext_subject_alternative_name

Type:: event (f: fa_file, ext: X509::SubjectAlternativeName)

Generated for the X509 subject alternative name extension seen in a certificate. This extension can be used to allow additional entities to be bound to the subject of the certificate. Usually it is used to specify one or multiple DNS names for which a certificate is valid.

Parameters:

f – The file.
ext – The parsed subject alternative name extension.

x509_ocsp_ext_signed_certificate_timestamp

Type:: event (f: fa_file, version: count, logid: string, timestamp: count, hash_algorithm: count, signature_algorithm: count, signature: string)

Generated for the signed_certificate_timestamp X509 extension as defined in RFC 6962. The extension is used to transmit signed proofs that are used for Certificate Transparency. Raised when the extension is encountered in an X.509 certificate or in an OCSP reply.

Parameters:

f – The file.
version – the version of the protocol to which the SCT conforms. Always should be 0 (representing version 1)
logid – 32 bit key id
timestamp – the NTP Time when the entry was logged measured since the epoch, ignoring leap seconds, in milliseconds.
signature_and_hashalgorithm – signature and hash algorithm used for the digitally_signed struct
signature – signature part of the digitally_signed struct

ocsp_request

Type:: event (f: fa_file, version: count)

Event that is raised when encountering an OCSP request, e.g. in an HTTP connection. See RFC 6960 for more details.

This event is raised exactly once for each OCSP Request.

Parameters:

f – The file.
req – version: the version of the OCSP request. Typically 0 (Version 1).

ocsp_request_certificate

Type:: event (f: fa_file, hashAlgorithm: string, issuerNameHash: string, issuerKeyHash: string, serialNumber: string)

Event that is raised when encountering an OCSP request for a certificate, e.g. in an HTTP connection. See RFC 6960 for more details.

Note that a single OCSP request can contain requests for several certificates. Thus this event can fire several times for one OCSP request, each time requesting information for a different (or in theory even the same) certificate.

Parameters:

f – The file.
hashAlgorithm – The hash algorithm used for the issuerKeyHash.
issuerKeyHash – Hash of the issuers public key.
serialNumber – Serial number of the certificate for which the status is requested.

ocsp_response_status

Type:: event (f: fa_file, status: string)

This event is raised when encountering an OCSP reply, e.g. in an HTTP connection or a TLS extension. See RFC 6960 for more details.

This event is raised exactly once for each OCSP reply.

Parameters:

f – The file.
status – The status of the OCSP response (e.g. successful, malformedRequest, tryLater).

ocsp_response_bytes

Type:: event (f: fa_file, status: string, version: count, responderId: string, producedAt: time, signatureAlgorithm: string, certs: x509_opaque_vector)

This event is raised when encountering an OCSP response that contains response information. An OCSP reply can be encountered, for example, in an HTTP connection or a TLS extension. See RFC 6960 for more details on OCSP.

Parameters:

f – The file.
status – The status of the OCSP response (e.g. successful, malformedRequest, tryLater).
version – Version of the OCSP response (typically - for version 1).
responderId – The id of the OCSP responder; either a public key hash or a distinguished name.
producedAt – Time at which the reply was produced.
signatureAlgorithm – Algorithm used for the OCSP signature.
certs – Optional list of certificates that are sent with the OCSP response; these typically are needed to perform validation of the reply.

ocsp_response_certificate 

Type:: event (f: fa_file, hashAlgorithm: string, issuerNameHash: string, issuerKeyHash: string, serialNumber: string, certStatus: string, revokeTime: time, revokeReason: string, thisUpdate: time, nextUpdate: time)

This event is raised for each SingleResponse contained in an OCSP response. See RFC 6960 for more details on OCSP.

Parameters:

f – The file.
hashAlgorithm – The hash algorithm used for issuerNameHash and issuerKeyHash.
issuerNameHash – Hash of the issuer’s distinguished name.
issuerKeyHash – Hash of the issuer’s public key.
serialNumber – Serial number of the affected certificate.
certStatus – Status of the certificate.
revokeTime – Time the certificate was revoked, 0 if not revoked.
revokeReason – Reason certificate was revoked; empty string if not revoked or not specified.
thisUpdate – Time this response was generated.
nextUpdate – Time next response will be ready; 0 if not supplied.

ocsp_extension

Type:: event (f: fa_file, ext: X509::Extension, global_resp: bool)

This event is raised when an OCSP extension is encountered in an OCSP response. See RFC 6960 for more details on OCSP.

Parameters:

f – The file.
ext – The parsed extension (same format as X.509 extensions).
global_resp – T if extension encountered in the global response (in ResponseData), F when encountered in a SingleResponse.

Functions

x509_parse

Type:: function (cert: opaque of x509) : X509::Certificate

Parses a certificate into an X509::Certificate structure.

Parameters:: cert – The X509 certificate opaque handle.
Returns:: A X509::Certificate structure.

x509_from_der

Type:: function (der: string) : opaque of x509

Constructs an opaque of X509 from a der-formatted string.

Parameters:: Note – this function is mostly meant for testing purposes

x509_get_certificate_string

Type:: function (cert: opaque of x509, pem: bool &default = F &optional) : string

Returns the string form of a certificate.

Parameters:

cert – The X509 certificate opaque handle.
pem – A boolean that specifies if the certificate is returned in pem-form (true), or as the raw ASN1 encoded binary (false).

Returns:

X509 certificate as a string.

x509_ocsp_verify

Type:: function (certs: x509_opaque_vector, ocsp_reply: string, root_certs: table_string_of_string, verify_time: time &default = 0.0 &optional) : X509::Result

Verifies an OCSP reply.

Parameters:

certs – Specifies the certificate chain to use. Server certificate first.
ocsp_reply – the ocsp reply to validate.
root_certs – A list of root certificates to validate the certificate chain.
verify_time – Time for the validity check of the certificates.

Returns:

A record of type X509::Result containing the result code of the verify operation.

x509_verify

Type:: function (certs: x509_opaque_vector, root_certs: table_string_of_string, verify_time: time &default = 0.0 &optional) : X509::Result

Verifies a certificate.

Parameters:

certs – Specifies a certificate chain that is being used to validate the given certificate against the root store given in root_certs. The host certificate has to be at index 0.
root_certs – A list of root certificates to validate the certificate chain.
verify_time – Time for the validity check of the certificates.

Returns:

A record of type X509::Result containing the result code of the verify operation. In case of success also returns the full certificate chain.

sct_verify

Type:: function (cert: opaque of x509, logid: string, log_key: string, signature: string, timestamp: count, hash_algorithm: count, issuer_key_hash: string &default = "" &optional) : bool

Verifies a Signed Certificate Timestamp as used for Certificate Transparency. See RFC6962 for more details.

Parameters:

cert – Certificate against which the SCT should be validated.
logid – Log id of the SCT.
log_key – Public key of the Log that issued the SCT proof.
timestamp – Timestamp at which the proof was generated.
hash_algorithm – Hash algorithm that was used for the SCT proof.
issuer_key_hash – The SHA-256 hash of the certificate issuer’s public key. This only has to be provided if the SCT was encountered in an X.509 certificate extension; in that case, it is necessary for validation.

Returns:

T if the validation could be performed successfully, F otherwise.

x509_subject_name_hash

Type:: function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the subject’s distinguished name.

Parameters:

cert – The X509 certificate opaque handle.
hash_alg –
the hash algorithm to use, according to the IANA mapping at

:param https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns:

The hash as a string.

x509_issuer_name_hash

Type:: function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the issuer’s distinguished name.

Parameters:

cert – The X509 certificate opaque handle.
hash_alg –
the hash algorithm to use, according to the IANA mapping at

:param https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns:

The hash as a string.

x509_spki_hash

Type:: function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the Subject Public Key Information of the certificate.

Parameters:

cert – The X509 certificate opaque handle.
hash_alg –
the hash algorithm to use, according to the IANA mapping at

:param https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns:

The hash as a string.

x509_set_certificate_cache

Type:: function (tbl: string_any_table) : bool

This function can be used to set up certificate caching. It has to be passed a table[string] which can contain any type.

After this is set up, for each certificate encountered, the X509 analyzer will check if the entry tbl[sha256 of certificate] is set. If this is the case, the X509 analyzer will skip all further processing, and instead just call the callback that is set with

:param zeek:id:x509_set_certificate_cache_hit_callback.

Parameters:: tbl – Table to use as the certificate cache.
Returns:: Always returns true.

Note

The base scripts use this function to set up certificate caching. You should only change the cache table if you are sure you will not conflict with the base scripts.

x509_set_certificate_cache_hit_callback

Type:: function (f: string_any_file_hook) : bool

This function sets up the callback that is called when an entry is matched against the table set by x509_set_certificate_cache.

Parameters:: f – The callback that will be called when encountering a certificate in the cache table.
Returns:: Always returns true.

Note

The base scripts use this function to set up certificate caching. You should only change the callback function if you are sure you will not conflict with the base scripts.