Defaults
What every fresh DefenseClaw install ships with — three policy presets (permissive / default / strict), three matching guardrail rule packs, the operator-config defaults, and how to pick the combination that fits your team's risk tolerance.
The two layers you can swap
Two independent layers ship in three matching names (default, strict, permissive). Change them separately.
| Layer | What it decides | Lives in | Switch with |
|---|---|---|---|
| Admission preset | What happens to a skill, MCP server or plugin by scan severity, and the block and alert levels | policies/<name>.yaml | defenseclaw policy activate <name> |
| Rule pack | The rules, judge prompts and suppressions that check prompts, replies and tool calls | policies/guardrail/<name>/ | defenseclaw guardrail use-pack <name> |
policy activate strict does not change guardrail.rule_pack, and use-pack does not change admission. For strict everywhere, run both.
Admission policy presets — what each profile ships
Preset-file keys are in the first column. skill_actions, scanner_overrides and the other preset spellings are not valid in config.yaml (config_version: 9); there the same values are admission.defaults.actions, admission.<type>.actions, guardrail.block_at and guardrail.alert_at.
| Knob | permissive | default | strict |
|---|---|---|---|
admission.allow_list_bypass_scan | true | true | false |
skill_actions.critical | quarantine + disable + block | quarantine + disable + block | quarantine + disable + block |
skill_actions.high | none + enable + none | quarantine + disable + block | quarantine + disable + block |
skill_actions.medium | none + enable + none | none + enable + none | quarantine + disable + block |
scanner_overrides.mcp | none | HIGH, MEDIUM and LOW install and run (CRITICAL follows skill_actions.critical) | MEDIUM blocks and quarantines; LOW disables at runtime |
scanner_overrides.plugin | none | HIGH blocks and quarantines; MEDIUM installs and runs | HIGH blocks and quarantines; MEDIUM installs and runs |
guardrail.block_threshold | 4 (CRITICAL) | 4 (CRITICAL) | 2 (MEDIUM) |
guardrail.alert_threshold | 3 (HIGH) | 2 (MEDIUM) | 1 (LOW) |
guardrail.cisco_trust_level | advisory | full | full |
watch.rescan_interval_min | 120 | 60 | 30 |
Preset ranks follow policies/rego/guardrail.rego: 1 = LOW, 2 = MEDIUM, 3 = HIGH, 4 = CRITICAL. HITL is not part of a preset; turn it on with defenseclaw guardrail hilt.
Activate a preset
policy activate copies the preset into config.yaml in one validated write. The gateway never reads the preset file.
| In the preset file | In config.yaml |
|---|---|
admission.scan_on_install, allow_list_bypass_scan | admission.defaults.scan_on_install, allow_list_bypass_scan |
skill_actions | admission.defaults.actions and admission.skill.actions |
scanner_overrides.<type> | admission.<type>.actions |
first_party_allow_list | admission.<type>.first_party_allow_list |
guardrail.block_threshold, alert_threshold | guardrail.block_at, alert_at, only where the preset's level differs from the selected rule pack's default |
guardrail.cisco_trust_level | guardrail.cisco_trust_level (unset for full) |
watch | watch.rescan_enabled, watch.rescan_interval_min |
cisco_ai_defense.endpoint, api_key_env | the same keys, when the preset carries them |
webhooks | added to webhooks; an existing webhook is never removed or rewritten |
The preset's hilt, patterns, severity_mappings, firewall, enforcement and audit sections are not copied. Activation replaces the whole admission: section, so re-apply hand-tuned entries afterwards or use defenseclaw policy edit. It prints each level it changes, old and new, and warns when the new level blocks or alerts on fewer severities. The running gateway applies the change without a restart, except for keys it reads at start (a listener, guardrail.enabled, guardrail.scanner_mode).
Commands for named presets:
defenseclaw policy list
defenseclaw policy show strict
defenseclaw policy create my-policy -d "Production policy"
defenseclaw policy activate my-policy
defenseclaw policy delete my-policy
defenseclaw policy validate
defenseclaw policy test --verbose
defenseclaw policy edit actions --severity high --runtime disable --policy-name my-policyWithout --policy-name, policy edit changes the live policy in config.yaml. With it, it saves a named preset; the first edit of a built-in saves your copy in ~/.defenseclaw/policies/<name>.yaml, and policy delete restores the built-in. policy validate compiles the Rego modules; defenseclaw config validate checks config.yaml.
Available policies:
* default [built-in] [active]
Balanced security policy for standard deployments
permissive [built-in]
Permissive policy for development and testing
strict [built-in]
Maximum security policy for high-risk environments
Activate a policy: defenseclaw policy activate <name>
Show details: defenseclaw policy show <name>* and [active] mark the active preset.
Block and alert levels
A scope that sets neither guardrail.block_at nor alert_at takes its rule pack's default:
| Rule pack | Blocks | Alerts |
|---|---|---|
permissive | CRITICAL | HIGH and above |
default | CRITICAL | MEDIUM and above |
strict | MEDIUM and above | LOW and above |
Scopes and precedence are in thresholds.
Guardrail rule pack — what each profile ships
| Pack | Enabled rules | Judge prompts | suppressions.yaml |
|---|---|---|---|
permissive | 238 of 246 | pii and tool-injection with higher thresholds; injection ships disabled | 12 entries, including all IP findings and selected file-inspection PII |
default | 242 of 246 | injection, pii, tool-injection | 9 entries: private and loopback IPs, platform IDs, expected system metadata |
strict | 258 of 258 | the same three, lower thresholds | 4 entries, minimal; no tool suppressions |
All three have the same eight rule files (c2, cognitive, commands, enterprise-data, local-patterns, secrets, sensitive-paths, trust-exploit) and the same six sensitive-tool definitions. The counts are what defenseclaw guardrail validate-pack reports for the shipped packs. Switching packs does not turn the LLM judge on; that is guardrail.judge.enabled (default false).
Generic curl and wget pipelines into a shell are off in default and
permissive. Both produce a CRITICAL alert without a block in strict.
In default and permissive, a world-writable chmod and a Windows Run-key addition produce HIGH alerts and do not block. Writes to the active user's authorized_keys are blocked in action mode when a direct command, a file tool or a supported literal interpreter form proves the target; in observe mode the same write raises a CRITICAL would-block alert and runs. A plain read of authorized_keys (grep, wc, ssh-keygen -l) is allowed; a redirect, a pipe into a writer or an in-place flag makes the use a write. A write to an instruction file the session loaded is CRITICAL: the default and strict packs block it in action mode and the permissive pack reports it (details). Computed interpreter paths are outside that proof. A symlink in the gateway's local filesystem is resolved for write targets; sandbox filesystems are evaluated without local symlink resolution.
Known limit. The rule reads the text of the command. A write made by a program the command starts (a nested shell, a generated script, a build tool, a tool option that runs another command) is not visible in that text, so it is not caught when it goes through an already existing link to the protected file. Rely on the OpenShell sandbox and file permissions for containment.
Evaluation limit. DefenseClaw judges each command of a shell call on its own, up to 128 commands
in one call (commands joined with ;, &&, || or |, and the commands inside bodies). A call
with more commands, or one the reader cannot analyse (for example a PowerShell statement it cannot
parse before the rest), raises rule ACTION-COMPOUND-LIMIT ("Shell command exceeds policy
evaluation limit"), whatever its length, up to the 1 MiB hook payload cap. Such a call proves no
target. With the default and permissive packs, per-user and managed, the call runs with a visible
alert that names the rule, an audit record with decision=alert, and the LLM judge decides where it
is configured. With the strict pack, managed strict included, action mode blocks it. A finding that
proves a protected target in the same call (a DefenseClaw state write, a file the call names) decides
on its own in every profile; a write the reader resolves into DefenseClaw's own state folder
(~/.defenseclaw) is self-protection and always blocks. A call that only mentions the folder name, next to
a statement the reader cannot analyse, proves no target and is judged like any other limit-only call. Known limit: with default and permissive, a statement the reader
cannot analyse can hide a write to a protected file in the same call; use strict where that
matters. In observe mode the call raises the alert and runs. Split a long command into several
calls, or put it in a script file and run the script.
Operand limit. DefenseClaw also resolves at most 1024 operands and redirection targets of one command,
counted over all its statements, with the file system. A command with more operands is unresolved. Every
word is still matched as text, as the shell decodes it (quotes and backslashes removed): a protected file or
link that the command names, directly or through a value DefenseClaw knows, or among the first 1024
operands, is blocked in every profile, and so is a later name that is a link or a second name of a keys
file. The other plain file names past the bound (a name with no protected part, no variable, glob or
dot-dot, outside the system folders, that is no link) are not resolved further: the default and permissive profiles allow the
call and raise the alert ACTION-OPERAND-BOUND, which names the bound, and the strict profile (and managed
strict) blocks it with ACTION-COMPOUND-LIMIT. Pass such a list through a file (xargs -a list.txt) or split it.
What setup guardrail actually writes
defenseclaw setup guardrail --connector claudecode --mode action \
--rule-pack default --non-interactiveclaw:
mode: claudecode
guardrail:
connector: claudecode
enabled: true
scanner_mode: local
llm_role: judge_only
mode: action
rule_pack: default
observability: {}A built-in pack is a name, not a path. block_at and alert_at stay unset, so the pack's levels apply. observability: {} means no optional destination; the local SQLite history still records every log, unredacted. A destination with no redaction policy receives everything under profile none.
If config.yaml already has an entry for the connector under guardrail.connectors (defenseclaw setup claude-code or an init that picked several agents writes one), the command saves mode and rule_pack in that entry instead of at the top level. The setup summary and defenseclaw guardrail status show the values the connector runs with; defenseclaw config show --section guardrail shows where they are saved.
Tuning by risk tolerance
Block risky plugins at install
The shipped default preset installs a plugin with a MEDIUM finding and lets it run. To block and quarantine those plugins instead, edit the live policy:
defenseclaw policy edit scanner --type plugin --severity medium \
--install block --file quarantine --runtime disable OK Updated admission.plugin.actions.medium: runtime=disable, file=quarantine, install=blockThat writes admission.plugin.actions.medium in config.yaml, and the running gateway applies it. Read it back with defenseclaw config get admission.plugin.actions; before any edit it prints (source: builtin) and the shipped actions. Activating a preset again replaces the whole admission section, so make this change after the last policy activate.
To change a named preset instead, add --policy-name default. The first edit of a built-in saves your own copy in ~/.defenseclaw/policies/default.yaml, policy activate default applies it, and defenseclaw policy delete default removes your copy and restores the built-in. Every admission key is in admission.
Defaults defenseclaw init does not ask about
| Knob | Default | Notes |
|---|---|---|
observability.local SQLite history | always present | Local durability for collected logs |
guardrail.hook_fail_mode | closed on managed installs | A per-user install with no saved mode follows its rule pack when the gateway is down: open with a warning in default and permissive, closed in strict (fail modes) |
guardrail.judge.enabled | false | Turn on with --judge-model or the setup prompt |
guardrail.hilt.enabled | false | min_severity is HIGH; the config key is spelled hilt |
guardrail.judge.timeout | 30s | Judge latency budget |
guardrail.judge.adjudication_timeout | 5s | Per-prompt budget |
guardrail.detection_strategy | regex_judge | Regex first, then the judge for MEDIUM and above. Runs as regex_only while the judge is off |
| Bifrost retry policy | 3 attempts, exponential backoff | LLM routing baseline |
Supported commands: defenseclaw setup llm --max-retries, defenseclaw setup guardrail --detection-strategy, defenseclaw guardrail fail-mode. Run defenseclaw config validate after a direct edit.
Per-connector overrides (guardrail.connectors)
Every field under guardrail.connectors.<name> is optional and inherits the global guardrail.* value when unset:
guardrail:
mode: action
hook_fail_mode: closed
connectors:
codex:
mode: observe
hook_fail_mode: closedManage them with defenseclaw setup <connector> and defenseclaw guardrail ... --connector X. The admission policy is global. Top-level claude_code: and codex: blocks are still parsed, but their fail_mode does nothing at runtime (fail modes).
Inspect the active defaults
defenseclaw config show
defenseclaw config get guardrail.block_at --effective
defenseclaw policy show default
defenseclaw guardrail list-packs
grep -rn "RULE_ID" ~/.defenseclaw/policies/guardrail/default/rules/config show prints every section: the values config.yaml sets plus the defaults for the keys it leaves out, with secrets masked. These options narrow it:
| Option | Shows |
|---|---|
--section NAME | One top-level section, for example guardrail or asset_policy |
--source | config.yaml as written, with no defaults filled in |
--effective | Only the observability section, resolved with its defaults |
--provenance | With --effective, where each observability setting comes from |
--format yaml|json | The output format (default yaml) |
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, 2 for an unknown section. With --effective, guardrail.block_at, guardrail.alert_at, guardrail.connectors.<name>.block_at and alert_at, admission[.<type>] and guardrail.cisco_trust_level print the value the gateway enforces, and the first line says where it comes from:
(source: pack-default:default)
CRITICALpack-default:default means nothing is set in config.yaml and the default rule pack decides. (source: builtin) is a shipped default, and config:<key> is a value you set.
policy show NAME prints a preset's severity actions, scanner overrides, block and alert thresholds and audit retention; --json gives the same as JSON. policy list names the presets. guardrail list-packs shows the rule packs, and (built-in default) in its first line means no pack directory is set, so default applies. To see what the gateway compiled from config.yaml, run defenseclaw-gateway policy show. To dry-run an asset against it, use defenseclaw-gateway policy evaluate.
Reset to defaults
There is no --reset flag. To go back to the defaults:
defenseclaw setup guardrail --rule-pack default --no-human-approval
defenseclaw guardrail hilt off --yes
defenseclaw policy activate default--no-human-approval without --connector turns off only the global guardrail.hilt. A connector set up with --connector <name> --human-approval keeps its own guardrail.connectors.<name>.hilt block, so human approval stays on for it. guardrail hilt off --yes turns it off for every active connector; --yes skips the confirmation prompt.
To reset user state, copy ~/.defenseclaw somewhere first (reset creates no archive), then run defenseclaw reset and defenseclaw quickstart --connector <name> (for example claudecode). Bare defenseclaw quickstart works only when one agent is installed; with several it exits with "Multiple connectors detected" and asks for --connector. The runtime and installed plugin are kept. On Windows copy %USERPROFILE%\.defenseclaw with Copy-Item -Recurse. A managed install resets through its lifecycle commands.
See also
See also: thresholds, rules, configuration.
Policies
How DefenseClaw decides — OPA/Rego policy, structured tool-call rules, regex and judge detection, scanner policy, and noise suppression.
Thresholds: block_at and alert_at
The single threshold model for DefenseClaw guardrails. Where block_at and alert_at can be set, which one wins, what the rule pack supplies when you set nothing, and how to read, change and hot-apply them.