Skip to main content
Analysis is deterministic and read-only. It scans persisted evidence, links findings to original event row IDs, and never executes recorded commands. The output schema is syscall-analysis/v1.

Severity

Severity is investigative priority, not probability. --severity is an inclusive minimum.

Confidence

Confidence describes the directness and quality of the recorded evidence. It is not a calibrated probability. Incomplete evidence downgrades confidence: high to medium, medium to low, low remains low.

Rules

ID: SYSCALL-SHELL-CHAIN · Version: 1Conditions
  1. A process instance executed a known shell basename: sh, bash, dash, zsh, ksh, fish, or ash.
  2. At least two descendants are linked by recorded process-instance ancestry.
  3. Maximum observed depth below the shell root is at least two.
Reports: root process, descendant count, maximum depth, a recorded chain, relevant exec and fork events, process references, and timeline.Exclusions: one-child shells and shells whose children do not spawn further processes. Unresolved ancestry is never filled in by name or PID guesswork.False positives: build systems, package managers, service wrappers, scripts, and interactive shells routinely create chains.Severity and confidence: low; high only with resolved ancestry and complete verified evidence.
ID: SYSCALL-TEMP-EXEC · Version: 1Conditions
  1. A persisted process_exec event has a non-empty executable filename.
  2. Its lexically normalized absolute path equals a configured temporary directory or is beneath it at a / component boundary.
Default directories: /tmp, /var/tmp, /dev/shm, /run/shm.Exclusions: /tmpfoo is not treated as /tmp. Relative and empty executable paths are not guessed or resolved. Missing executable paths are reported as a limitation.False positives: installers, builds, tests, and self-updating tools commonly execute from temporary directories.Severity and confidence: medium; high with an observed absolute path and complete evidence.
ID: SYSCALL-SENSITIVE-OPEN · Version: 1ConditionsA file_open event matches a configured sensitive path exactly or beneath it at a component boundary. Successful opens, failed attempts, and unresolved relative paths are grouped separately.Default sensitive paths:
A relative path is reported only when its basename equals a configured sensitive entry basename, and is informational.Exclusions: an open event does not prove that contents were read or written. Relative paths cannot be resolved without the process working directory and dirfd.False positives: authentication, backup, configuration-management, and monitoring software legitimately accesses credential files.Severity and confidence: successful credential-store opens are high; other successful sensitive opens are medium; failed attempts are low; unresolved relative paths are informational. Direct absolute-path findings can be high confidence; failed attempts are medium; unresolved relative paths are low.
ID: SYSCALL-REPEATED-CONNECT · Version: 1Conditions
  1. At least repeated_connection_threshold failed network_connect events (default 3) share process instance, address family, destination address, destination port, and raw result.
  2. All attempts fit within correlation_window_ns (default 60 seconds).
Exclusions: a single failed connection is not reported. Successful connects are not counted as failures.False positives: retry loops, unavailable local services, and scanners can produce repeated refusals.Severity and confidence: medium; high when the session is complete.
ID: SYSCALL-FS-NET-CORRELATION · Version: 1ConditionsA file_open event precedes a network_connect event in persisted chronological order, within correlation_window_ns (default 60 seconds). Same-process and process-tree correlation are separate and labeled.Process-tree correlation requires unambiguous ancestry. Ambiguous PID-reuse links are not invented.Exclusions: the rule never claims that a file was transmitted, that data was exfiltrated, or that the connection carried file contents. Temporal proximity does not prove causation.False positives: applications routinely open configuration or library files before network requests.Severity and confidence: low; medium for direct same-process timing, low for tree-relative timing, further reduced for incomplete evidence.
ID: SYSCALL-SHORT-LIVED-NET · Version: 1Conditions
  1. Recorded process_exec, network_connect, and process_exit events exist for the same process instance.
  2. The connection occurred after exec and before exit.
  3. Exec-to-exit duration is at or below short_lived_window_ns (default 10 seconds).
Exclusions: processes without a recorded exit are not classified; the report records how many were skipped. Short lifetime alone is never suspicious.False positives: CLI tools, health checks, package operations, and one-shot network utilities are naturally short-lived.Severity and confidence: low; medium when all three event types are recorded; lower for incomplete evidence.

Report shape

Each finding includes: The report also contains the session summary, evidence completeness, evaluated rule metadata, report-level limitations, and a truncated flag. Reports are sorted by severity, confidence, start time, rule ID, and finding ID for deterministic output.

Evidence status

evidence.status is complete only when:
  • Session status is completed.
  • Counters show no loss, drops, recovery, or incomplete identity.
  • The event scan was not truncated by max_events.
  • Read-only verification completed with assessment valid.
Otherwise the status is incomplete, and the reasons appear in evidence.notes and report limitations.

Configuration

--config loads strict JSON. Unknown fields are rejected. Paths must be absolute and are lexically normalized. Duplicate normalized paths and duplicate disabled rules are rejected. Empty path lists, zero thresholds, zero windows, root / entries, and unknown rule IDs are errors.
disabled_rules accepts rule IDs. Disabled rules are skipped by default; an explicit --rule RULE_ID overrides the disabled default while still applying bounds.

Bounds

Rule D uses a sliding window rather than unbounded pairwise comparison. Rule F groups events by process instance once rather than rescanning the event list per process.

Known limitations

  • Rules are contextual indicators, not verdicts.
  • An open is not a read; a connect is not an established session.
  • No file contents or network payloads exist in the evidence.
  • Relative paths cannot be resolved.
  • Missing events and losses are never reconstructed.
  • related_findings is reserved; no cross-finding inference is performed.
  • No privileged live validation is claimed for the offline analysis engine.
  • Analysis does not prove database authenticity.
See Analyze behavior for the workflow and Export format for how the report is packaged.