Defaults

DefenseClaw ships with opinionated defaults that are immediately useful without tuning, and stay out of your way until you opt into stricter behaviour. This page documents what actually ships — grounded in the policy YAMLs in policies/, the schema in internal/config/config.go, and what defenseclaw setup guardrail actually writes.

The two layers you can swap

DefenseClaw separates admission policy from runtime guardrail rules. They ship as matching triples but are independent knobs.

Both layers ship in three named profiles — default, strict, permissive — and you flip them independently:

defenseclaw policy activate default          # OPA layer
defenseclaw guardrail use-pack default        # Guardrail layer

OPA admission policy — what each profile ships

The OPA policy file (policies/<name>.yaml) drives admission decisions: what happens to a finding by severity, whether the allow-list lets first-party assets bypass scanning, and what threshold a Cisco AI Defense verdict has to clear before it blocks.

Severity ranks are the rego convention from policies/rego/guardrail.rego: 1 = LOW, 2 = MEDIUM, 3 = HIGH, 4 = CRITICAL. cisco_trust_level: advisory means even Cisco AI Defense's own verdicts are surfaced but never escalated to a block.

The columns are deliberately conservative. We'd rather you opt into stricter behaviour than have an upgrade silently start blocking your traffic.

Tool-call block and alert levels

The guardrail.block_threshold and alert_threshold rows above apply to LLM traffic through the guardrail proxy. Tool calls that agent hooks send, from Claude Code, Codex and the other hook connectors, take their levels from the first of these that is set:

1. The connector's own level: defenseclaw guardrail block-at LEVEL --connector <name> writes guardrail.connectors.<name>.block_at.
2. The global level: defenseclaw guardrail block-at LEVEL writes guardrail.block_at.
3. The rule pack: strict blocks MEDIUM and above, default and permissive block CRITICAL only.

defenseclaw guardrail alert-at sets the alert level the same way. Without one, strict alerts on LOW and above, default on MEDIUM and above and permissive on HIGH and above. The levels apply in action mode, and defenseclaw guardrail status shows the result for each connector in its block/alert field.

Guardrail rule pack — what each profile ships

The rule pack directory (policies/guardrail/<name>/) holds the regex YAMLs, judge prompts, sensitive-tool definitions, and suppressions the in-flight scanner consumes.

All three packs share the same severity rubric and the same signal_strength output schema — only the per-category thresholds and suppression scope differ between packs. Switching the rule pack does not enable the LLM judge — that's a separate guardrail.judge.enabled toggle in your operator config (default: false). Flipping the rule pack only changes which prompt YAMLs the judge will run if you've enabled it.

What setup guardrail actually writes

After defenseclaw init, this command:

defenseclaw setup guardrail --connector claudecode --mode action \
  --rule-pack default --non-interactive

writes these settings (other generated fields omitted):

claw:
  mode: claudecode

guardrail:
  connector: claudecode
  enabled: true
  scanner_mode: local
  llm_role: judge_only
  mode: action
  rule_pack_dir: /home/<you>/.defenseclaw/policies/guardrail/default

observability: {}   # no optional destinations; local SQLite still records

Settings it doesn't write keep their defaults: guardrail.hook_fail_mode is closed on a new install, guardrail.judge.enabled is false, and guardrail.hilt.enabled is false with min_severity: HIGH.

Things to notice:

• The LLM judge is off by default. It only turns on if you pass --judge-model to setup guardrail or answer "yes" to the interactive judge prompt. The schema default is guardrail.judge.enabled = false in internal/config/config.go. Keeping it off keeps cost predictable; turn it on once you have a DEFENSECLAW_LLM_KEY configured.
• Human approval (HITL) is off by default. The shipped severity floor is HIGH, but with enabled: false it never asks. --human-approval turns it on and --hilt-min-severity changes the floor. The config key and flags are spelled hilt.
• The local store still writes. observability: {} means no optional destination, not no telemetry. Every collected log is stored, unredacted, in the local SQLite database. Add a kind: jsonl destination if you need a file stream, or a remote destination with setup splunk or setup local-observability.
• New destinations get unredacted data. A destination without its own redaction policy receives every capability and bucket under profile none. Configure sensitive, content, strict or a custom profile before you export to a less trusted place.

Tuning by risk tolerance

You usually don't need a custom policy or rule pack — just a few knob changes.

"I'm in pilot, just observe"

defenseclaw policy activate permissive
defenseclaw setup guardrail \
  --connector claudecode \
  --mode observe \
  --rule-pack permissive \
  --restart \
  --non-interactive

Observe mode never blocks; the permissive rule pack only decides what gets logged. Everything still flows to mandatory SQLite and any matching configured destinations so you can review what would have happened. Recommended first week of any rollout.

"Move fast, stop only the obvious harm"

defenseclaw policy activate default
defenseclaw setup guardrail \
  --connector claudecode \
  --mode action \
  --rule-pack default \
  --human-approval \
  --hilt-min-severity high \
  --restart \
  --non-interactive

Default rules: CRITICAL findings block, and HIGH findings pause for your approval inside Claude Code, which supports a native PreToolUse ask. Most engineering teams in the early or middle phase of a rollout land here.

"Regulated workload, lock it down"

defenseclaw policy activate strict
defenseclaw setup guardrail \
  --connector claudecode \
  --mode action \
  --rule-pack strict \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-haiku-4-5 \
  --restart \
  --non-interactive

Strict policy (block ≥ MEDIUM, no allow-list bypass), strict rule pack (stricter profile variants and minimal suppressions), and the LLM judge enabled. Because the strict block threshold runs before HITL, MEDIUM-and-higher findings block rather than prompt. Combine this with a reviewed first-party allow-list.

"Block risky plugins at install"

How DefenseClaw treats skills, MCP servers and plugins with findings is set in the admission policy, independent of the rule pack. The shipped default policy installs a plugin with a MEDIUM finding and lets it run. To block and quarantine those plugins instead:

defenseclaw policy edit scanner --type plugin --severity medium \
  --install block --file quarantine --runtime disable

The first edit of a built-in policy saves your own copy in ~/.defenseclaw/policies/default.yaml, and the command asks the running gateway to reload it. defenseclaw policy show default lists the result under Scanner Overrides, and defenseclaw policy delete default restores the built-in policy.

Defaults defenseclaw init does not ask about

init does not prompt for the following lower-level defaults. Use the documented setup/guardrail command when it exposes the knob; otherwise edit ~/.defenseclaw/config.yaml and validate the result.

defenseclaw setup llm --max-retries, defenseclaw setup guardrail --detection-strategy, and defenseclaw guardrail fail-mode provide supported CLI paths for three of these controls. Run defenseclaw config validate after any direct edit.

Per-connector overrides (guardrail.connectors)

When you run more than one hook connector from a single gateway, override guardrail policy per connector under guardrail.connectors.<name> in ~/.defenseclaw/config.yaml. Every field is optional and inherits the global guardrail.* value when unset, so a connector block only carries what differs:

guardrail:
  mode: action                   # global default
  hook_fail_mode: closed

  connectors:
    claudecode:
      mode: action               # enforce for Claude Code
    codex:
      mode: observe              # softer for Codex than for Claude Code
      hook_fail_mode: open         # explicit softer override for Codex

With more than one connector active, claw.mode keeps naming the primary connector, and the gateway leaves the defenseclaw.claw.mode telemetry attribute off. Manage these blocks with defenseclaw setup <connector> (choosing Add) and the defenseclaw guardrail ... --connector X command group, for example defenseclaw guardrail block-at HIGH --connector codex — see Setup → Multi-connector and Reference → Configuration. The OPA admission policy is still global — there's no per-connector policy override surface yet.

claude_code:
  enabled: true
  mode: action
  fail_mode: open                # LEGACY hint, NOT consumed by hooks; see Reference → Fail modes

Inspect the active defaults

defenseclaw config show                  # every setting, with defaults (secrets masked)
defenseclaw config get asset_policy.enabled   # one value of that view
defenseclaw policy list                  # all policies on disk + which is active
defenseclaw policy show default          # normalized summary of one named policy

For configuration v8, config show prints every section: the values config.yaml sets plus the defaults that apply to the keys it leaves out, with the observability section resolved the way the gateway runs it. A fresh install's config.yaml sets only a few sections, so this is how you read asset_policy and the rest before you change them. --section NAME keeps one section (for example asset_policy), and config get KEY prints one dotted key such as asset_policy.mcp.registry_required. A default value prints with a note on stderr; the exit code is 1 when the key has no value and no default, and 2 for an unknown section. Use --source for the masked source document as written, --effective for the resolved observability section alone, or --effective --provenance for explicit compiler annotations. V8 rejects --reveal; neither source nor effective output resolves secret values.

policy show <name> prints a normalized summary of the named file (default, strict, permissive, or any custom policies/<name>.yaml you've added). It does not dump the source YAML or individual guardrail rules. To find a rule by ID, look up the directory a connector enforces with list-packs, then search it:

defenseclaw guardrail list-packs
grep -rn "RULE_ID" ~/.defenseclaw/policies/guardrail/default/rules/

(built-in default) in the list-packs output means no pack has been selected yet, so the default pack applies.

Reset to defaults

There's no --reset flag. Two real paths exist:

Soft reset (most common) — just re-run setup with the defaults you want. setup guardrail overwrites the relevant guardrail.* keys idempotently:

defenseclaw setup guardrail --rule-pack default --no-human-approval
defenseclaw policy activate default

Reset user state — first make your own private backup if you need one, then use the destructive reset command. It deletes resettable state; it does not create a rollback archive. The managed runtime and installed plugin are retained so quickstart can reinstall. The example is for macOS and Linux. On Windows, back up %USERPROFILE%\.defenseclaw with Copy-Item -Recurse, then run the same defenseclaw reset and defenseclaw quickstart. A managed (enterprise) install is reset through its lifecycle commands instead.

umask 077
cp -a "$HOME/.defenseclaw" "$HOME/.defenseclaw.before-reset"
defenseclaw reset
defenseclaw quickstart

See also

• Policies — the layered architecture (regex → judge → suppressions → OPA admission)
• Setup Guardrail — the CLI that consumes these defaults
• HITL — what guardrail.hilt.enabled and min_severity actually change for the operator
• Reference → Fail modes — the three "fail open vs closed" knobs disambiguated
• Reference → Configuration — every key surfaced here, with type and default