Deterministic detection reference

DefenseClaw separates detection evidence from blocking authority. A regex, CEL expression, YARA signature, or correlated sequence can create a finding, but an authenticated tool call can be denied only when a complete, same-rule deterministic proof reaches an enforcement-capable connector surface and the active profile, or a guardrail.block_at level, maps its severity to block.

This page inventories the detectors currently shipped in the repository and explains which layer owns each decision. Benchmark scores for these layers are published in Deterministic Detection Benchmarks.

Decision architecture

YARA description scanning and the legacy session correlator are parallel detection lanes. They create findings for audit and operator workflows; they do not bypass the same-rule proof gate or retroactively stop an action.

Current rule inventory

The bundled profiles share a common schema but intentionally differ in enabled rules and lexical fallback posture:

a^ is an intentionally impossible RE2 pattern. It is used when a broad raw text fallback would add noise or could not safely prove the same semantic effect. In balanced and permissive, ten CEL declarations are explicit false placeholders for rules that remain lexical-only in those profiles; strict enables tighter variants of those candidates.

The 239 enabled balanced/default rules are generated from policies/guardrail/default/rules/*.yaml:

The generated Go catalog is checked against the YAML in CI. Edit the YAML sources, not internal/gateway/rules_catalog_generated.go.

Download piped into a shell

CMD-PIPE-CURL is off in the default and permissive profiles, so a command such as curl ... | bash is not recorded as a finding there. Many legitimate installers use that pattern. The strict profile enables the rule at CRITICAL. wget ... | sh (CMD-PIPE-WGET) and PowerShell iwr ... | iex (CMD-WIN-IWR-IEX) are still reported in every profile.

To get the finding for curl pipelines, switch to the strict pack with defenseclaw guardrail use-pack strict, or add your own rule in a pack of your own. Authoring CEL rules shows the rule format, and Rules and custom packs shows how to activate it.

ActionFacts

ActionFacts is the typed, bounded representation of one tool action. It parses POSIX shell, PowerShell, Windows CMD, argv-style calls, and closed structured tool schemas without trusting free-form descriptions. Unsupported, dynamic, conditional, truncated, ambiguous, or over-budget input records a parse status and cannot gain blocking authority.

Public CEL projection

The parser caps one command input at 64 KiB and retains at most 128 command facts, 256 path facts, 128 network facts, 256 data-flow facts, and eight issue codes. Exceeding a bound downgrades the projection instead of silently dropping evidence and continuing as authoritative.

Private value-minimized proof facts

Some exact proofs need identities that must not be exposed to operator CEL or persisted as raw values. Code-owned ActionFacts therefore derives only closed operation classes and domain-separated SHA-256 identity digests for:

• structured text replacement deltas and newly added literal IPv4 addresses;
• sensitive-egress artifact writes;
• SQL Server xp_cmdshell operations by connection;
• PostgreSQL COPY ... PROGRAM connection identity;
• command-capable SQL UDF create/invoke operations by engine, connection, and function;
• privileged Kubernetes manifest, pod, and CronJob identities;
• wireless capture/deauthentication BSSID identity;
• cloud IAM user or role identity;
• credential-extraction/remote-execution target and principal identity; and
• staged payload write, mutation, and persistence-install path identity.

Raw SQL, commands, passwords, connection strings, manifests, principal names, packet filters, payload bytes, and persistence content are discarded before these facts reach durable chain state.

Detection and enforcement projections

The full ActionFacts projection is used for detection. A separate monotonic enforcement projection retains only effects statically proven to execute. Previewed commands, unresolved branches, incomplete argv, dynamic identities, and parser-limit failures can still produce a useful alert through a fallback, but cannot be upgraded into a deny.

See CEL authoring for the complete public field and enum reference.

CEL selectors

Balanced/default and permissive each declare 134 CEL expressions; strict declares 147. CEL is deliberately limited to Boolean logic, field access, fixed enum constants, membership, bounded exists comprehensions, and literal RE2 matching. It cannot perform arbitrary history scans, dynamic regex construction, reflection, network access, file access, or unbounded iteration.

A successful CEL match is a candidate, not automatic block authority. The engine evaluates the expression against both full facts and the execute-only projection, then requires a code-owned proof pinned to the same rule ID. CEL errors, budget exhaustion, unsupported connector fields, and partial parsing fall back to that rule's regex lane and remain detection-only unless an exact fallback validator independently proves the same rule.

The admitted syntax, 50 ms dispatch budget, aggregate cost ceiling, and regex limits are documented in CEL engine boundaries.

Regex detection and fallback

All local patterns compile with Go's RE2-based regexp engine. The catalog uses regex in three distinct ways:

On an authenticated tool action, a raw or custom regex match is not trusted blocking proof. The finding remains detection-only unless a complete exact validator for that same rule accepts the action. Sixty-five balanced/default rules intentionally use a^ so there is no lexical fallback at all.

Pattern-writing guidance and counterexamples are in the Regex cookbook.

Exact atomic semantic rules

Thirty-four rule IDs use exact semantic proofs. Twenty-eight combine CEL and regex candidate selection, four use CEL with lexical fallback disabled, and two use a code-owned exact proof selected by a narrow regex. Neither selector alone can authorize a block.

These rules accept closed literal grammars and reject near-miss executables, help/version invocations, dynamic operands, preview modes, conditional or augmented commands, unresolved paths, mismatched identities, and incomplete structured arguments.

Bounded tool-call chains

The fixed chain catalog contains 26 ordered behaviors. A chain examines only the current authenticated event plus at most eight predecessors from the same canonical connector/session, never more than 30 minutes. Required steps must be ordered, successful where specified, and joined by exact value-minimized identity. Failed, denied, cancelled, replayed, cross-session, mismatched, or mutated sequences cannot complete an enforcement proof.

“Enforcement-capable” means the chain can set the enforcement-safe result bit; the connector must still be synchronous and block-capable, the same-rule proof gate must accept it, and the active profile (or the connector's block level) must map the severity to block.

Profile posture

Profiles change the disposition of accepted findings; they do not make an incomplete proof complete.

Strict intentionally accepts more interruption risk. Balanced/default is the recommended general posture, while permissive is useful for observation-heavy deployments. Connector capability still controls whether block can become a native deny; unsupported surfaces retain the finding and audit action without claiming prevention. See Defaults for the complete operator configuration.

To change these levels without switching packs, set the lowest severity that blocks and the lowest that alerts, globally or for one connector:

defenseclaw guardrail block-at HIGH                       # every connector
defenseclaw guardrail block-at CRITICAL --connector codex # except codex
defenseclaw guardrail alert-at MEDIUM --connector codex
defenseclaw guardrail block-at inherit --connector codex  # back to the global level

Levels are CRITICAL, HIGH, MEDIUM or LOW. The commands write guardrail.block_at and guardrail.alert_at, or the same keys under guardrail.connectors.<name>, and the running gateway applies the change without a restart. The most specific value wins: a profile connector, then a profile, then the connector's own value, then the global one, and last the pack's level. The alert level never ends up above the block level, so anything that blocks also alerts, and CRITICAL always blocks. The same settings in config.yaml:

guardrail:
  block_at: HIGH           # every connector blocks HIGH and CRITICAL
  connectors:
    codex:
      block_at: CRITICAL   # except codex, which blocks only CRITICAL
      alert_at: MEDIUM

The levels apply in action mode to every guardrail surface: hook tool calls (including bounded chains, CodeGuard on file writes and sandbox shell commands), hook prompts, and the guardrail proxy's prompts, completions and tool calls. Human approval only ever applies below the block level: anything at or above it blocks without asking. The pack decides everything else, such as which rules run. The gateway picks up an edit to these keys, from a command or by hand in config.yaml, on its next reload; no restart is needed. See Thresholds for the scopes, precedence and the commands that read the effective value.

Low-noise rollout

Start with the balanced/default pack and measure findings separately from blocked actions on representative benign tool traffic. A finding is not necessarily an interruption: detection-only regex, unsupported or partial ActionFacts, and alert-only chains remain observable without gaining deny authority. Move to strict only when the additional alert and interruption risk fits the protected environment.

When extending a pack, prefer the narrowest typed ActionFacts operation and a bounded CEL selector. Keep ambiguous or dynamic inputs detection-only, and add hard negatives for previews, help/version commands, loopback traffic, failed results, mismatched identities, and incomplete chains. Evaluate attack recall on attack-positive data and evaluate finding FPR plus benign block rate on separate benign or mixed data; an attack-only corpus cannot establish FPR.

YARA MCP-description scanning

The MCP scanner adds ten YARA signatures from policies/yara/mcp-tools/description_injection.yara:

These signatures are high-precision description-injection signals, not proof of authorization or tool execution. They remain alert-only. The scanner loads the pack in addition to its existing native rules and preserves the matching YARA rule name in the finding.

Protection packs and policy-provided context

Some actions are dual-use globally but deterministically forbidden inside a customer-declared boundary. High-assurance packs supply that missing policy fact and use closed CEL/ActionFacts proofs instead of resource-name guesses.

The SSH contract intentionally abstains today because the public CEL activation does not expose file content or a trusted fingerprint allowlist parameter. It must not be selected as a rule pack (guardrail.rule_pack) until that binding exists. Dynamic paths, malformed keys, missing policy, failed writes, and unresolved homes already fail closed to abstention in its ActionFacts helper.

“Selectable” means the pack can be turned on for the global rule pack or one connector with defenseclaw guardrail protection enable NAME [--connector X], layered into a custom pack in Policy Creator, or copied into an operator-owned policy directory. guardrail protection enable adds the pack's name to guardrail.rules.protections for the scope (global, one connector, or a profile with --profile). The gateway layers the pack's rules on the scope's rule pack in memory, replacing base rules with the same ID, and writes no directory to disk. guardrail protection disable NAME takes it out of that scope. If a wider scope enables the pack, disable it there; a narrower scope cannot turn it off. guardrail protection list shows which scope has which pack on. The staged SSH contract is refused. None of this adds another value to defenseclaw setup guardrail --rule-pack, which accepts only default, permissive, and strict. For a Policy Creator export, validate the pack, review the declared trust boundary, then switch to it with defenseclaw guardrail use-pack. Either way, assigning a production-protection pack asserts that the selected connector context is actually protected. See Opt-in protection packs, Authoring custom rule packs, and Rules and custom packs for the guardrail.rules scopes.

Other deterministic detection lanes

Post-event correlator

Two bundled patterns operate on persisted findings:

• LETHAL-TRIFECTA: ordered untrusted ingress, sensitive access, then external egress;
• TRIFECTA-WITH-FINGERPRINT-MATCH: the same content fingerprint appears in sensitive access and later external egress.

Both emit a synthetic CRITICAL CORR-* finding. They are post-event detection, not retroactive blocking and not a substitute for exact bounded tool-call chains.

Optional LLM judge

The injection, PII, exfil and tool-injection judges handle ambiguous content. They are optional, non-deterministic secondary detectors and are deliberately outside the benchmarked deterministic block path. The exfil judge reads prompts only and its configuration is compiled in; the tool-injection judge also has a data-exfiltration category. See Layer 3 — LLM judge on the Policies page.

OPA/Rego

OPA/Rego owns admission and final guardrail policy-domain decisions. It does not replace ActionFacts/CEL parsing; instead, it maps accepted findings and deployment context to policy outcomes.

Source of truth and validation

Run the repository checks after changing a detector:

make check-guardrail-catalog
go test -timeout 30m ./internal/actionfacts ./internal/guardrail ./internal/gateway
go test ./benchmarks/...

The catalog check prevents generated Go rules from drifting from YAML. Focused tests exercise parser hard negatives, same-rule proof ownership, bounded chain identity, profile action posture, and connector enforcement eligibility.