Detection & custom rules

Beam combines built-in patterns, local custom rules, and sequence detection for captured activity. The same single-event scanning engine is used for offline file scans and collector normalization. Sequence rules need related events in a session; a standalone text scan does not observe a real sequence of tool calls.

Inspect the catalog

beam rule list

Rules are grouped by categories such as execution, exfiltration, impact, integrity, persistence, privilege, reconnaissance, secrets, and source control. The output also lists cross-event sequence rules and any errors loading custom definitions.

A category identifies what a pattern is looking for. It does not establish that the behavior actually occurred or that a matching event is malicious.

Add a custom pattern

Create or carefully merge into ~/.beam/rules.json. The file is a JSON array; preserve existing rules you still need:

[
  {
    "id": "internal_host",
    "pattern": "wiki\\.internal\\.corp",
    "severity": "high",
    "category": "exfil",
    "title": "Internal wiki referenced",
    "explanation": "Review whether this internal hostname is being sent outside the organization."
  }
]

Patterns are regular expressions evaluated case-insensitively. Keep patterns narrow and test both expected matches and benign examples. Detection rules add findings; they do not directly become workspace blocking policies.

Reload and verify

beam rule list
beam rule reload

list reads the catalog and reports malformed entries. reload applies disk changes to the running collector without a restart. Invalid entries are skipped and reported rather than crashing the whole detector. Offline scans load rules from disk for their own run.

Scan a small review fixture containing the intended pattern and inspect the result. Also scan a benign fixture so you understand false positives before rolling the rule into an operational workflow.

Understand sequence findings

For retained events associated with a session, Beam examines a recent window of 50 events when new activity arrives. A credential read followed by network activity can produce a composite finding on the event completing the pattern. Re-ingesting the same history should not duplicate the finding.

Sequence matches still require interpretation. They connect recorded actions, but they do not establish network delivery, data contents, or successful execution. Missing hooks and retention bounds can leave the observed sequence incomplete.