File Analyzers

Contents

• File Analyzers
  • Bro::FileDataEvent
  • Bro::FileEntropy
  • Bro::FileExtract
  • Bro::FileHash
  • Bro::PE
  • Bro::Unified2
  • Bro::X509

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_UNIFIED2

Files::ANALYZER_X509

Bro::FileDataEvent

Delivers file content

Components

Files::ANALYZER_DATA_EVENT

Bro::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.

F:The file. Ent:The results of the entropy testing.

Bro::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.

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.

Bro::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.

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

Bro::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.

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.

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.

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.

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.

F:The file. H:The parsed section header information.

See also: pe_dos_header, pe_dos_code, pe_file_header, pe_optional_header

Bro::Unified2

Analyze Unified2 alert files.

Components

Files::ANALYZER_UNIFIED2

Types

Unified2::IDSEvent

Type:

record

sensor_id: count

event_id: count

ts: time

signature_id: count

generator_id: count

signature_revision: count

classification_id: count

priority_id: count

src_ip: addr

dst_ip: addr

src_p: port

dst_p: port

impact_flag: count

impact: count

blocked: count

mpls_label: count &optional

Not available in “legacy” IDS events.

vlan_id: count &optional

Not available in “legacy” IDS events.

packet_action: count &optional

Only available in “legacy” IDS events.

Unified2::Packet

Type:

record

sensor_id: count

event_id: count

event_second: count

packet_ts: time

link_type: count

data: string

Events

unified2_event

Type:event (f: fa_file, ev: Unified2::IDSEvent)

Abstract all of the various Unified2 event formats into a single event.

F:The file. Ev:TODO.

unified2_packet

Type:event (f: fa_file, pkt: Unified2::Packet)

The Unified2 packet format event.

F:The file. Pkt:TODO.

Bro::X509

X509 analyzer

Components

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

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.

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

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

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

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_get_certificate_string

Functions

x509_parse

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

Parses a certificate into an X509::Certificate structure.

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_get_certificate_string

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

Returns the string form of a certificate.

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.

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.

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