EQL rule reference

How rules are evaluated

After a detonation, the sandbox's raw telemetry is transformed into Elastic Common Schema (ECS) documents and indexed into per-scan event indices. Your EQL rules are then evaluated with Elasticsearch EQL search alongside Bintracer's built-in rules.

• Every rule search is automatically scoped to the scan under review. Rules never need to filter by scan, account, sample hash, or time range.
• Only sample-related telemetry is indexed: events attributable to the sample's process tree, its file and network targets, or files it created. bintracer.relevance.reason records why each document was included (sample_exec, sample_actor, descendant_actor, target, network, xpc, or malware).
• Matches appear on the scan report with the rule's name and MITRE ATT&CK techniques, visible only to your account.
• A rule the scan pipeline cannot load is skipped; it never fails your scan. The EQL query itself is syntax-checked by Elasticsearch at scan time, so a schema-valid rule can still be skipped there if the query is malformed. Every skipped rule is listed with its reason in the scan report's Rule diagnostics section, visible only to your account.
• A rule reports at most one hit per scan: evaluation records match/no-match, so a rule that matches many events still appears once. A scan lists at most 250 matched rules across built-in and custom rules; when the cap is reached the report flags the detection list as truncated and the remaining rules are not evaluated.

Rule file format

An EQL rule is a TOML file in the Elastic detection-rule shape: a [rule] table with the entries below.

• Upload EQL rules as plaintext .toml files up to 1 MiB. Each account can store up to 10,000 custom rules.
• Unused upstream entries (the note triage guide, setup blocks, actions, and other metadata) are ignored, and unicode punctuation in display-only fields such as name and description is normalized rather than rejected.
• Some constructs are rejected at load time with an explanation: eventN.field cross-event references and descendant of (Elasticsearch EQL cannot evaluate them), the Endpoint-only persistence event category (Bintracer emits persistence as file events — match on event.action instead), and non-EQL rule types (new_terms, esql, threshold, query).

Indices

Rules may target three event index patterns. Every event document lands in exactly one of them, keyed by its ECS event category.

• The Elastic Endpoint spellings logs-endpoint.events.* (including the process, file, network, library, api, authentication, and session forms) are accepted as aliases over the same indices, so upstream Elastic rules keep their index arrays verbatim.
• event.dataset and data_stream.dataset name the physical index (bintracer.events.process|file|network): api, library, authentication, and session documents carry bintracer.events.process, and configuration and malware documents carry bintracer.events.file. Filter on event.category for semantics.
• The per-scan run summary lives in a separate index that rules cannot query.

Fields on every event

Every event document carries this envelope in addition to its per-event fields.

Process context

The acting process (for exec documents the exec target, for network documents the flow's source process) is rendered under process.* on every event document.

Event catalog: process index

Events in logs-bintracer.events.process-*, grouped by event.category.

process

api (cross-process / IPC)

library

authentication

session

Event catalog: file index

Events in logs-bintracer.events.file-*. File documents carry file.{path,name,extension,directory} plus, when known, file.size, file.uid/file.gid, file.mode (octal string), file.attributes (decoded flags such as hidden), file.mtime/file.created (compare for timestomp evidence), file.Ext.header_bytes (first bytes, lowercase hex), and file.hash.*.

file

configuration

malware

Event catalog: network index

Events in logs-bintracer.events.network-*. All network documents carry the source-process process.* block, and related.ip collects every IP on the document.

• dns.answers items carry name, type, type_code, class_code, ttl, and data, plus preference/exchange for MX, strings for TXT, and rdata_base64 for TXT and undecoded types.
• bintracer.dns.* context includes flow_id, upstream_resolver, source_app_signing_identifier, packet_length, tcp_framed, and parse_error.
• DNS documents carry event.category: network, so write network where … (or an unqualified any where …) — a dns where … category clause never matches.

Field types and search behavior

Fields are mapped for the query patterns rule authors need most.

• String fields are keyword by default — exact match, in, and case-insensitive like~ patterns all work.
• High-cardinality text is wildcard-mapped with a full-text subfield for fast like~/regex~ and no length cap: process.command_line (also the parent's), url.full, url.path, http.request.body.content, user_agent.original, bintracer.library.dlopen.requested_path (also .requested_path_base64), bintracer.file.extended_attribute_value, and bintracer.file.where_froms.
• destination.ip, source.ip, dns.resolved_ip, host.ip, and related.ip are ip-typed, so CIDR queries such as destination.ip == "10.0.0.0/8" work.
• Booleans include the code-signature exists/trusted flags, bintracer.persistence.{run_at_load,keep_alive}, and the truncation flags under bintracer.process.* and bintracer.file.*.
• Dates: @timestamp, event.created, event.ingested, process.start, file.accessed, file.created, file.mtime, bintracer.file.quarantine.timestamp.

Example: sequence rule

Sequences join events with sequence by, typically on process.entity_id or the parent's. This rule flags a process that launches curl and then executes a file from a download location within 30 seconds, joined on the shared parent.

[rule]
name = "Download and Execute via curl"
type = "eql"
language = "eql"
index = ["logs-bintracer.events.process-*"]
query = '''
sequence by process.parent.entity_id with maxspan=30s
  [process where event.action == "exec" and process.name == "curl"]
  [process where event.action == "exec" and
     process.executable like~ ("/tmp/*", "/private/tmp/*", "/Users/*/Downloads/*")]
'''