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 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, nine CEL declarations are explicit false placeholders for rules that remain lexical-only in those profiles; strict enables tighter variants of those candidates.

The 184 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.

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

Each bundled profile declares 81 CEL expressions. 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. Twenty-one 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

This benchmarked change added or materially completed 34 exact semantic rule IDs. 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 18 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 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.

YARA MCP-description scanning

The MCP scanner adds five 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 policy_dir until that binding exists. Dynamic paths, malformed keys, missing policy, failed writes, and unresolved homes already fail closed to abstention in its ActionFacts helper.

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

Injection, PII, and tool-injection judges handle ambiguous content. They are optional, non-deterministic secondary detectors and are deliberately outside the benchmarked deterministic block path. Data-exfiltration is a category of the tool-injection judge rather than a separate judge file.

OPA/Rego

OPA/Rego owns admission, firewall, sandbox, audit, skill-action, 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 ./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.