File Analyzers

Files::Tag
Type

enum

Files::ANALYZER_DATA_EVENT
Files::ANALYZER_ENTROPY
Files::ANALYZER_EXTRACT
Files::ANALYZER_MD5
Files::ANALYZER_SHA1
Files::ANALYZER_SHA256
Files::ANALYZER_PE
Files::ANALYZER_OCSP_REPLY
Files::ANALYZER_OCSP_REQUEST
Files::ANALYZER_X509

Zeek::FileDataEvent

Delivers file content

Components

Files::ANALYZER_DATA_EVENT

Zeek::FileEntropy

Entropy test file content

Components

Files::ANALYZER_ENTROPY

Events

file_entropy
Type

event (f: fa_file, ent: entropy_test_result)

This event is generated each time file analysis performs entropy testing on a file.

Parameters
  • f – The file.

  • ent – The results of the entropy testing.

Zeek::FileExtract

Extract file content

Components

Files::ANALYZER_EXTRACT

Events

file_extraction_limit
Type

event (f: fa_file, args: Files::AnalyzerArgs, limit: count, len: count)

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.

See also: Files::add_analyzer, Files::ANALYZER_EXTRACT

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.

See also: Files::add_analyzer, Files::ANALYZER_MD5, Files::ANALYZER_SHA1, Files::ANALYZER_SHA256

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.

See also: pe_dos_code, pe_file_header, pe_optional_header, pe_section_header

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

See also: pe_dos_header, pe_file_header, pe_optional_header, pe_section_header

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.

See also: pe_dos_header, pe_dos_code, pe_optional_header, pe_section_header

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.

See also: pe_dos_header, pe_dos_code, pe_file_header, pe_section_header

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.

See also: pe_dos_header, pe_dos_code, pe_file_header, pe_optional_header

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.

See also: x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_verify, x509_get_certificate_string, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: x509_certificate, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_verify, x509_get_certificate_string, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: x509_certificate, x509_extension, x509_ext_subject_alternative_name, x509_parse, x509_verify, x509_get_certificate_string, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_parse, x509_verify, x509_ocsp_ext_signed_certificate_timestamp, x509_get_certificate_string

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

See also: ssl_extension_signed_certificate_timestamp, x509_extension, x509_ext_basic_constraints, x509_parse, x509_verify, x509_ext_subject_alternative_name, x509_get_certificate_string ssl_extension_signed_certificate_timestamp, sct_verify, ocsp_request, ocsp_request_certificate, ocsp_response_status, ocsp_response_bytes, ocsp_response_certificate, x509_ocsp_ext_signed_certificate_timestamp

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).

See also: ocsp_request_certificate, ocsp_response_status, ocsp_response_bytes, ocsp_response_certificate, ocsp_extension, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: ocsp_request, ocsp_response_status, ocsp_response_bytes, ocsp_response_certificate, ocsp_extension, x509_ocsp_ext_signed_certificate_timestamp

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).

See also: ocsp_request, ocsp_request_certificate, ocsp_response_bytes, ocsp_response_certificate, ocsp_extension, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: ocsp_request, ocsp_request_certificate, ocsp_response_status, ocsp_response_certificate, ocsp_extension, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: ocsp_request, ocsp_request_certificate, ocsp_response_status, ocsp_response_bytes, ocsp_extension, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: ocsp_request, ocsp_request_certificate, ocsp_response_status, ocsp_response_bytes, ocsp_response_certificate, x509_ocsp_ext_signed_certificate_timestamp

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.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_verify, x509_get_certificate_string

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

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_verify, x509_get_certificate_string, x509_parse

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.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_verify

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.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_get_certificate_string, x509_verify

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.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_get_certificate_string, x509_ocsp_verify, sct_verify

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.

See also: ssl_extension_signed_certificate_timestamp, x509_ocsp_ext_signed_certificate_timestamp, x509_verify

x509_subject_name_hash
Type

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

Get the hash of the subject’s distinguished name.

Parameters
Returns

The hash as a string.

See also: x509_issuer_name_hash, x509_spki_hash, x509_verify, sct_verify

x509_issuer_name_hash
Type

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

Get the hash of the issuer’s distinguished name.

Parameters
Returns

The hash as a string.

See also: x509_subject_name_hash, x509_spki_hash, x509_verify, sct_verify

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
Returns

The hash as a string.

See also: x509_subject_name_hash, x509_issuer_name_hash, x509_verify, sct_verify

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.

See also: x509_set_certificate_cache_hit_callback

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.

See also: x509_set_certificate_cache

x509_check_hostname
Type

function (hostname: string, certname: string) : bool

This function checks a hostname against the name given in a certificate subject/SAN, including our interpretation of RFC6128 wildcard expansions. This specifically means that wildcards are only allowed in the leftmost label, wildcards only span one label, the wildcard has to be the last character before the label-separator, but additional characters are allowed before it, and the wildcard has to be at least at the third level (so *.a.b).

Parameters
  • hostname – Hostname to test

  • certname – Name given in the CN/SAN of a certificate; wildcards will be expanded

Returns

True if the hostname matches.

See also: x509_check_cert_hostname

x509_check_cert_hostname
Type

function (cert_opaque: opaque of x509, hostname: string) : string

This function checks if a hostname matches one of the hostnames given in the certificate.

For our matching we adhere to RFC6128 for the labels (see x509_check_hostname). Furthermore we adhere to RFC2818 and check only the names given in the SAN, if a SAN is present, ignoring CNs in the Subject. If no SAN is present, we will use the last CN in the subject for our tests.

Parameters
  • cert – The X509 certificate opaque handle.

  • hostname – Hostname to check

Returns

empty string if the hostname does not match; matched name (which can contain wildcards) if it did.

See also: x509_check_hostname