File Analyzers¶
- Files::Tag¶
Zeek::FileDataEvent¶
Delivers file content
Components¶
Zeek::FileEntropy¶
Entropy test file content
Components¶
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¶
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¶
Zeek::FileHash¶
Hash file content
Components¶
Events¶
- file_hash¶
-
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¶
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¶
-
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¶
Types¶
- X509::Certificate¶
- Type
-
- 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.
- version:
- X509::SubjectAlternativeName¶
- Type
-
- 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
- dns:
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¶
-
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¶
-
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. succesful, 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. succesful, 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¶
-
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¶
-
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¶
-
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.
See also:
x509_issuer_name_hash
,x509_spki_hash
,x509_verify
,sct_verify
- x509_issuer_name_hash¶
-
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.
See also:
x509_subject_name_hash
,x509_spki_hash
,x509_verify
,sct_verify
- x509_spki_hash¶
-
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.
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¶
-
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¶
-
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