Verify and monitor
Check the health of a standalone DefenseClaw enterprise deployment on Windows, Linux, and macOS, read the lifecycle result, and find the logs, events, and audit records to alert on.
This page is for administrators who run a standalone deployment day to day. Everything on it is read-only except rotating per-user credentials. To upgrade, change the config, repair or remove a deployment, see Upgrade, repair and remove. For a failed check, look up the code in Troubleshooting. Terms such as guardian, enumerator and machine policy are in Concepts.
Status and verify
Two lifecycle actions report on a deployment. Neither changes the host.
When an account's private agent installs cannot be scanned completely, the warning reads <connector> for user <user> is not protected: the bounded scan of this account's private agent installs was incomplete (<reason>). On macOS the scan does not open the folders macOS privacy protection holds for a background service (Desktop, Documents, Downloads, Movies, Music, the Photos library, and the Mail, Messages, Safari and other personal-data folders under ~/Library); an agent copy kept there is not found. After later records are written, audit_write_failed stays for 16 minutes after the last failed write, then clears without a gateway restart.
| Action | What it does | Use it for |
|---|---|---|
status | Reports the recorded state: installed version, services, readiness, machine policy and enrollment counts. On Linux and macOS it also runs the basic checks (files, services, gateway health); each problem is an error and the command exits non-zero | Inventory and dashboards |
verify | Runs every check. Linux and macOS: file digests, owners and modes, the config and credentials against what was last applied, the runtime descriptor, the service account, required services, gateway health and the guardian's authorization ledger. Windows: files, DACLs, service settings, the mode pin and readiness. Each problem is an error and the command exits non-zero | Compliance and alerting |
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --jsonsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify --json$DefenseClaw = 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe'
& $DefenseClaw enterprise windows status --profile standalone --json
& $DefenseClaw enterprise windows verify --profile standalone --jsonRun these as root on Linux and macOS, and from an elevated prompt on Windows, so every check can read the protected files. On Windows the lifecycle runs on PowerShell 7, which must be installed; you can start the CLI from any shell by its full path.
On managed Linux and macOS, the packaged defenseclaw launcher gives each
account its own connector status and sandbox views. It runs only the commands in
Managed command availability, and refuses doctor,
alerts and tui even when root invokes that launcher. Administrators use
the installed gateway's enterprise linux status or enterprise macos status,
verify, and audit export commands shown here for deployment health and
events.
Result of verify | Linux and macOS | Windows |
|---|---|---|
| Healthy | 0 | 0 |
| A check failed | 1 | 1603 |
| Invalid arguments | 2 | 1639 |
On Windows, a misspelled flag (such as --bogus) on an enterprise windows lifecycle command, for example enterprise windows status or verify, exits 1639, like an argument the lifecycle rejects (--profile bogus). It prints unknown flag and the usage, or with --json one result whose only error is invalid_arguments. 1.0.4 and earlier exit 1 for an unknown flag. Other commands keep their own code: another enterprise command (enterprise policy show --bogus) exits 1, and the rest of defenseclaw.exe (& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' --bogus) exits 2 with the usage line.
On Linux and macOS, verify skips its checks and exits 75 with lifecycle_busy while another lifecycle run is in progress; run it again. On Windows it fails (1603) while another run's transaction is pending. verify also runs on a schedule: daily on Linux (defenseclaw-enterprise-verify.timer) and macOS (com.cisco.defenseclaw.verify), and from your MDM on Windows (for example detect.ps1 -RequireHealthy).
A pending agent install scan is a warning, not a failure: when the enumerator's record of unprotected agents is missing, more than 16 minutes old, or (on Linux and macOS) from a different configuration generation, status and verify show one agent_install_scan_incomplete warning that starts NOT COVERED (scan pending) and set coverage_complete and security_complete to false. This can follow a fresh install, upgrade, or connector change. The warning alone does not fail verify; every other failure, including an agent the old record lists that fails verify, still does. The scan runs every five minutes; to run one now, restart the enumerator (sudo systemctl restart defenseclaw-hook-enumerator.service, sudo launchctl kickstart -k system/com.cisco.defenseclaw.hook-enumerator, or Restart-Service DefenseClawHookEnumerator).
Verify waits and schedules
On Linux and macOS, verify waits up to 5 seconds for another lifecycle run to
finish and holds no lock while it checks. If that run is still going, verify
skips its checks and exits 75 with lifecycle_busy. status run as root waits
the same way, then reports the change as pending apply (ok: true, pending_apply: true,
a lifecycle_busy warning) with the installed version, skips its checks and exits 75.
The Linux verify unit accepts that exit, so a daily run that met an administrator's
change is not left failed. On Windows, verify does not wait: while another run's
transaction is pending it fails (1603); run it again after that run finishes. A
transaction that an interrupted run left pending fails verify (1 with
verify_failed, or 1603) until the next mutating run recovers it.
verify also runs on a schedule, and its result goes to the logs in
Logs and events.
| OS | Scheduled verify |
|---|---|
| Linux | defenseclaw-enterprise-verify.timer: daily, with up to one hour of random delay |
| macOS | com.cisco.defenseclaw.verify: daily at 03:17 local time |
| Windows | None built in. Run verify from your MDM, for example with detect.ps1 -RequireHealthy (see Detection) |
Review activity from the CLI (Linux and macOS)
The lifecycle's status and verify report the deployment. To see the gateway,
who is enrolled and what the gateway decided, run these as root. No extra
environment variables are needed: on a standalone host, status, audit and
enterprise hooks read the managed config, data directory, target manifest and
guardian state instead of ~/.defenseclaw, and audit opens the gateway's audit
database read-only.
sudo /opt/defenseclaw/bin/defenseclaw-gateway status
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise hooks status
sudo /opt/defenseclaw/bin/defenseclaw-gateway audit export --since 2h --connector claudecode --output /root/claudecode-audit.jsonlsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway status
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise hooks status
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway audit export --since 2h --connector claudecode --output /var/root/claudecode-audit.jsonl| Command | What it shows |
|---|---|
status | The gateway's health, its subsystems, and its connectors and their modes |
enterprise hooks status | The guardian's summary, then an Enrollment section: one line per account with each connector's state from the last reconcile (enrolled, pending or failed). --json adds the same list as enrollment. When every connector uses machine policy the section can be absent while eligible users remain protected; check status and verify for coverage |
audit export | The audit records as JSONL, oldest first. --since and --until take an RFC3339 time or a duration ago (30m, 2h). --limit N keeps the first N matching rows, or with --newest the N most recent. --connector keeps one agent's rows, and --output writes a file (it refuses to replace one unless you pass --force). An administrator can use --db <copied-audit.db> to read a retained database copy read-only after decommission; keep its WAL and SHM companions with it. |
audit findings | The distinct current scan findings: skill, MCP, plugin, code, AIBOM and inventory scans. Guardrail decisions are not tracked here; use alerts or audit export |
scan skill, scan plugin and scan mcp also run as root on a managed Linux or macOS host: the
package installs the scanners and the scan runs through the managed gateway. A folder the
service cannot read is refused (exit 3) until you copy it to one it can. On Linux that is
a folder inside a home folder, /root, /tmp, /var/tmp or /run/user; on macOS one
inside /Users or /var/root. On macOS a folder in /tmp is scanned. See
Linux and
macOS.
On managed Windows, run this from an elevated PowerShell prompt (Setup puts no
DefenseClaw command on PATH, so it names the installed CLI by its path). The
enrollment.accounts field lists each account's connectors and their enrolled,
pending or failed state. enterprise hooks status is the Linux and macOS guardian
view.
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --profile standalone --jsonAudit fields on a standalone host
On a standalone host, hook decisions, rejected connector hooks, direct inspect-tool
calls and refused hook-socket requests carry the verified account (user.id,
defenseclaw.user.name); a refused request also names its route and reason. Each
tool call the foreign-hook guard denies adds a connector-hook row with
event: foreign_hook_session that names the file; its trace spans carry
defenseclaw.guardrail.rule_id ENTERPRISE-FOREIGN-HOOK-BLOCKED, so a dashboard
can count foreign-hook blocks apart from rule-pack blocks. Scan-finding and
scan-verdict rows do not carry the account
(#921); join them to
the hook decision on evaluation_id. For the per-user machine-policy view, see
Machine policy status. A standard user who runs
enterprise hooks gets the managed-host message, which names the administrator
command.
Health fields
With --json, every lifecycle action prints one result document, defined by
packaging/mdm/contract/lifecycle-result.schema.json.
The MDM wrapper scripts print the same document.
| Field | Meaning |
|---|---|
ok | true only when errors is empty |
exit_code | The process exit code |
installed, installed_version | Whether a deployment is recorded, and its version |
transaction_pending | An earlier run was interrupted. The next ensure or repair recovers it first by rolling back to the last committed deployment; to apply the config the interrupted run was applying, run ensure --config <file> again. On Linux and macOS, status and verify name the interrupted action, its start time and phase. On Windows, see Recover a pending transaction |
services[] | Each managed service or unit, with its state |
readiness | gateway, guardian, enumerator, sensor_helper: each true when that component is ready |
coverage_complete | The core services are ready (definition per OS below) |
security_complete | Everything coverage_complete needs, plus the extra conditions below |
machine_policy.<connector> | ownership, lock, effective_lock, owned_entries, foreign_entries, and any higher_precedence sources or conflicts |
enrollment | targets, pending, failed, exempt (see the note below the next table); on Windows standalone also accounts: each enrolled account (account, sid) with each connector's state from the guardian's last reconcile |
inspection | local and ai_defense (see the note below the next table) |
policy | The effective policy the host runs. effective_digest and config_generation say which config, applied says whether the running gateway reports it. Omitted when the lifecycle cannot compute it. See Effective policy digest |
errors[], warnings[] | Each has a stable code and a human message. See Troubleshooting |
api_port_holders[] | Windows, with error api_port_held: each process other than the gateway that listens where the gateway API binds, with its address and pid, and its image and account when the caller can identify it |
destinations[] | status only: each observability destination the installed config compiles to, with name, kind, enabled, preset, signals and redaction_profiles (the same compiler as defenseclaw observability plan) |
A healthy status from a Linux host, trimmed to two of its services entries and
two of its machine_policy connectors. With Claude Code enabled, security_complete
is false and the hook_process_fail_open warning names the residual risk of a hook
process the user stops or kills:
{
"schema_version": 2,
"ok": true,
"action": "status",
"profile": "standalone",
"platform": "linux",
"installed_version": "1.0.23",
"installed": true,
"transaction_pending": false,
"services": [
{ "name": "defenseclaw-gateway.service", "kind": "gateway", "state": "active/running", "start_mode": "enabled", "pid": 422027, "required": true },
{ "name": "defenseclaw-hook-guardian.service", "kind": "guardian", "state": "active/running", "start_mode": "enabled", "pid": 422080, "required": true }
],
"readiness": { "gateway": true, "guardian": true, "enumerator": true, "sensor_helper": true },
"inspection": { "local": "active", "ai_defense": "disabled" },
"machine_policy": {
"claudecode": { "ownership": "merge", "lock": "enforce", "effective_lock": "enforce", "owned_entries": 28, "foreign_entries": 0 },
"copilot": { "ownership": "merge", "owned_entries": 14, "foreign_entries": 0 }
},
"enrollment": { "targets": 16, "pending": 0, "failed": 0, "exempt": 0 },
"coverage_complete": true,
"security_complete": false,
"warnings": [
{ "code": "hook_process_fail_open", "message": "claudecode: a killed PreToolUse hook or PreToolUse timeout is non-blocking; ..." }
],
"errors": [],
"policy": {
"effective_digest": "sha256:7b38f1df3862914135b0f9e70f9e679793a35e53018b115784002d9c55b8fce2",
"config_generation": 3,
"applied": true,
"gateway_reported_digest": "sha256:7b38f1df3862914135b0f9e70f9e679793a35e53018b115784002d9c55b8fce2"
},
"exit_code": 0
}A failed run sets ok to false and names each problem in errors[].
Coverage and security complete
A failed run sets ok to false and names each problem in errors[]. This
verify ran without root, so it checked nothing and exited 1. A not_root result
leaves out every field that reports the deployment, because a standard user cannot
read the deployment record and those fields would read as "not installed":
{
"ok": false,
"action": "verify",
"coverage_complete": false,
"security_complete": false,
"errors": [
{ "code": "not_root", "message": "run this command as root (sudo or the MDM agent)" }
],
"exit_code": 1
}The two summary fields are computed differently on each OS:
| Field | Linux and macOS | Windows |
|---|---|---|
coverage_complete | The gateway answers its health check on the hook socket and reports its API listener on 127.0.0.1:18970 up, the guardian is active with a fresh authorization ledger, the enumerator is active, and no agent is reported as hook_contract_unverified or opencode_v1_unprotected | The deployment is installed, the guardian is ready, no transaction is pending, and no agent is reported as hook_contract_unverified or opencode_v1_unprotected |
security_complete | coverage_complete, the sensor helper is active, the run had no errors, no agent is agent_unprotected or hook_contract_unverified, no user target is guardian_target_failed, the config enables at least one agent when there are eligible users (otherwise no_connectors_enabled), and no enabled agent is hook_process_fail_open (Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity) | The deployment is installed and healthy, the target manifest has at least one enabled Codex, Claude Code or Cursor row, no agent is agent_unprotected or hook_contract_unverified, no enabled agent is hook_process_fail_open (Codex, Claude Code), and, when a Claude Code row is enabled, the Claude Code attestation below is recorded |
- Enrollment counts. Linux and macOS read the counts from the guardian's
authorization ledger, and
exemptis always0there: accounts thatexclude_usersorexempt_userskeep out of enrollment have no target, andenterprise policy show --user <name>names the rule for one account. Windows counts the rows of the target manifest:pendingis deferred rows,exemptis disabled rows, andfailedis always0. - Inspection. On Windows,
inspection.ai_defenseisokwhen AI Defense is enabled in the config and the gateway is ready; it does not test the key or the network.inspection.localisactivewhen the gateway is ready,unknownwhile it is not, anddisabledwhen no deployment is installed. On Linux and macOS the lifecycle reads both fields from the gateway's/health:localisactive,disabledorunknown, andai_defenseisdisabled,ok,unavailable:<code>orunknown. The gateway's/healthguardrail detail carriesai_defense_availableand, when it is not available,ai_defense_error. To check AI Defense, see AI Defense is not used. - Users. On Linux and macOS, neither summary field depends on whether any user
is enrolled. Check
enrollmentfor that.
Claude Code attestation
Claude Code attestation (Windows). With Claude Code enabled, Windows reports
security_complete: false until an administrator confirms, with a real Claude Code
session on that host, that Claude Code runs DefenseClaw's managed hooks. After that
check, run repair with --attest-claude-effective-policy. A later change to the
Claude Code policy or the hook binary makes the attestation stale, and
security_complete returns to false.
What to alert on
| Signal | Alert when |
|---|---|
verify exit code | Not 0 |
coverage_complete | false |
security_complete | false for longer than one enumerator cycle for a reason other than hook_process_fail_open. With Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity enabled it stays false and names that warning, so alert on the other warnings and errors. On Windows with Claude Code enabled it also stays false until the Claude Code attestation is recorded, so every such host alerts until then |
warnings[].code | machine_policy_incomplete (Linux, macOS): DefenseClaw's hooks are missing from a vendor policy file. agent_unprotected, hook_contract_unverified: an installed agent runs without DefenseClaw hooks. config_rejected (Linux, macOS): the config you pushed is not the one running. On Linux and macOS, status and changing actions warn with policy_not_applied when the gateway reports another effective policy, or policy_reload_rejected when it rejected a reload. verify reports either as an error and exits nonzero. On Windows also alert on policy_not_buildable and config_edited_outside_lifecycle. |
policy.applied | false on Linux or macOS: security_complete is false; verify fails when the gateway reports a different digest or a rejected reload. |
policy.effective_digest | Differs between hosts of one OS that received the same config |
machine_policy.<connector>.conflicts or .higher_precedence | Not empty |
enrollment.failed | Greater than 0 (Linux, macOS) |
transaction_pending | true on two runs in a row |
| Kernel controls (Linux with Tetragon) | Five Prometheus rules over defenseclaw_kernel_*: DefenseClawKernelDenials, DefenseClawKernelAckStale, DefenseClawKernelPausedLong, DefenseClawTetragonFallback and DefenseClawCustomerPolicyBlocksAgents. The rules ship in the local observability stack; see Tetragon on a Linux fleet |
Claude Code attestation (Windows). With Claude Code enabled, security_complete stays false until an administrator confirms a real session runs the managed hooks and records it with repair --attest-claude-effective-policy.
Effective policy digest and config generation
A host enforces only the administrator config and the policy assets it names. To prove a host runs the config you pushed, compare two numbers: the config generation (counts writes to config.yaml, recorded in config.generation.json) and the effective policy digest (sha256: of the canonical config and its assets). Every lifecycle result carries both in the policy object, and applied: true means the running gateway reports the same digest:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json | jq .policystatus and verify report applied: false but do not fail on it; alert on the field.
Policy digest detail
The administrator config, with the policy assets it names, is the only policy a host enforces. To prove that a host runs the config you pushed, compare digests instead of files. Two numbers identify it:
- The config generation counts the writes to
config.yaml. The single config writer bumps it and records the write inconfig.generation.jsonnext to the config:generation,config_sha256,actor,reasonandwritten_at. On a managed host only the lifecycle (actorlifecycle) and a migration (actormigration) write. - The effective policy digest is
sha256:and the hash of the canonical config and the policy assets it names (rule packs, Rego modules, signature packs, scanner policies). Secret values and theai_discovery.home_dirslist the enumerator fills in are left out, and a path underdata_diris written as${data_dir}. The gateway stamps it on/statusand on the administrator's/health(policy.effective_digest), and on its decision events.
On every OS every lifecycle result carries both in the policy object:
| Field | Meaning |
|---|---|
effective_digest | The digest the installed config computes to, from the installed gateway binary's policy digest run with the service environment |
config_generation | The generation recorded in config.generation.json. 0 means none recorded |
applied | true when the running gateway reports the same digest on /health and has no policy.last_reload_error |
gateway_reported_digest | The digest /health reported. Omitted when the gateway did not answer |
last_reload_error | Why the gateway rejected its last reload. Omitted when there is none |
config_unrecorded | true when config.yaml was changed outside the lifecycle: config.generation.json does not record it and the running gateway may already enforce it. Omitted otherwise |
The human output of status and verify prints the readiness line, the inspection
line and the services, not the digest. Use --json and read the policy object
(for example with jq .policy), as root; a standard account gets not_root and no
policy. The schema is #/$defs/policyState in
lifecycle-result.schema.json.
What the lifecycle does with it:
statusandverifycheck application.applied: falsemeans the gateway runs another policy than the config on disk computes to, or rejected its last reload.statusreports the cause and setssecurity_complete: false.verifyreportspolicy_not_appliedorpolicy_reload_rejectedas an error and exits nonzero until the intended policy applies. The gateway clears a reload error when a later reload succeeds.- Changing actions warn and record. After
install,upgrade,repairorensure, when the gateway is ready, a different gateway digest adds the warningpolicy_not_applied. When the digests match without a reload error, the lifecycle writespolicy-state.json(effective_digest,config_generation,applied_at, root-only) next todeployment.json:/var/lib/defenseclaw-enterpriseon Linux,/opt/cisco/defenseclaw/lifecycleon macOS, andC:\ProgramData\Cisco\DefenseClaw\installon Windows. - Windows. The Windows lifecycle migrates a
config_version: 8config and records the generation as actorlifecycle. You can also read the digest withenterprise policy show, which prints a line such asEffective policy sha256:7b38f1df3862, config generation 3(and addspolicyto--json), as in Machine policy status. - Warnings on every action.
policy_reload_rejectedsays the gateway rejected the last policy change (a rule pack edited away from its pinned digest, for example) and keeps enforcing an earlier one.policy_not_buildablesays the installed config and its assets no longer build into a policy.config_edited_outside_lifecyclesaysconfig.yamlwas changed by hand; runensurewith the intended config to put the managed config back. On Windows thatensurekeeps the edited file asrejected-config.yamlnext toconfig.yaml(administrators only) and warnsconfig_reverted. None of them changesok. - Secure Client. The gateway omits
policyfrom/healthand/status, and the lifecycle result has nopolicyobject.
The gateway reports the same digest, with its own policy generation, on /health
and /status. On a managed standalone computer /health carries the policy
object only for an administrator: root or the gateway's own account on the hook
socket (Linux and macOS), or a request with the gateway token. A plain
curl http://127.0.0.1:18970/health, even under sudo, has no policy key, and
neither has the hook socket's answer to a standard account. As root, read it from
the hook socket:
sudo curl -s --unix-socket /run/defenseclaw-hook/hook.sock http://localhost/healthsudo curl -s --unix-socket /opt/cisco/defenseclaw/run/hook.sock http://localhost/healthor read /status (it needs the gateway token), or the policy: line of
enterprise linux|macos|windows status. See
The policy object.
"policy": {
"effective_digest": "sha256:77ef51dce35bdc753cf9417609695b6e9eee40c83f551274104d0b08e7281f6a",
"generation": 1,
"config_generation": 7,
"config_generation_recorded": true,
"built_at": "2026-10-06T18:32:07Z",
"component_count": 6
}generation counts the policies this gateway process has built, so it restarts at 1
with the process; config_generation is the counter in config.generation.json.
component_count is the number of inputs the digest covers.
config_generation_recorded: false means the file was edited and no writer recorded
it. A change that does not build adds last_reload_error and leaves the previous
generation in force.
The same digest is available without the lifecycle, as root on the host. This output is from a per-user test home; a managed host prints its own digests:
sudo /opt/defenseclaw/bin/defenseclaw-gateway policy digestsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway policy digestEffective policy: sha256:bf9017898a4816b6199c92a10cf289d2559397bfa9f579e150a65f0e91e5d172
Config generation: 2
builtin sha256:31191aec6bcc38a8d63e718a5a6cf9c3bce38229b275f0cf408239901350c6e1
config sha256:9b0c6e11839fec0fcbcc337777ce4c7272e0625431d46e2336b2a1cae60ff77c
guardrail_policy sha256:9586a9559a2578251671e8b3b62b0cffc39d2afacab0a389317b7dd8cebc160b
providers sha256:a23435dc7a50229547fe0cecb4a3c24f5127a2ec8277a498032ef8bff4490dcb
rego sha256:1394e701de498838fa07251f7d5d3c858ed6ce44dcc164536fd13dc58d2a38b3
rule_pack:global sha256:46ece6be297f9c9b221524923b4baf2035c810503ddfa1b83a1024ee3c55c6e0The component lines say which part changed when two digests differ. When
config.yaml was edited and no writer recorded it, the second line reads
Config generation: 3, but config.yaml changed outside the DefenseClaw writer since.
On a managed host a lifecycle run records an administrator's in-place edit as the
next generation, so the line clears once the apply trigger has run.
Compare a fleet by digest. Collect policy.effective_digest from each host's
status --json (or from your MDM wrapper's result) and group by value. Hosts of one
OS on the same release that received the same admin config and assets report the
same digest. A host with another digest has another config or assets, or has not
applied the change yet; its config_generation, applied and
gateway_reported_digest say which, and the component lines of policy digest on
that host and a reference host say which part differs. Do not compare Linux with
macOS: the config names different paths on each OS.
Machine policy status
Machine policy is the vendor policy file (Codex requirements, Claude Code managed
settings, Cursor enterprise hooks, Copilot policy.d, OpenCode's managed config)
where the lifecycle places DefenseClaw's hooks for the connectors that support it;
see Machine policy. The machine_policy block of
the result summarizes it. The enterprise policy commands show each connector's
route, lock and coverage in detail. They never write, and need no environment
variables. Run them as root on Linux and macOS, or from an elevated prompt on
Windows.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy verify --jsonsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show --jsonpolicy show prints the effective policy line and the per-connector route, lock and coverage; policy verify exits 1 when coverage is incomplete, and --connector or --user narrow it. policy verify --live proves a real client loads the hooks.
Machine policy status options
policy showprints the effective policy line after its header, for exampleEffective policy sha256:7b38f1df3862, config generation 3, and adds apolicyobject (effective_digest,config_generation) to--json. The lifecyclestatus --jsonandverify --jsonresults carry the same digest aspolicy.effective_digeston every OS (Health fields);policy verifydoes not print it.policy verifyexits1when coverage is incomplete.- Add
--connector <name>to check one connector, and--user <name>to also check that user's own agent config for hooks DefenseClaw has not approved. policy verify --liveruns the real client as a user and proves that it loads DefenseClaw's hooks. It needs--user, exactly one--connector(codexorclaudecode), and--agent-binarywith the client's absolute path. For Codex, pass the native executable, not the npmcodexlauncher (codex.jsneedsnode, which is not on the probe's minimalPATH): for a global npm install it isnode_modules/@openai/codex/node_modules/@openai/codex-<platform>/vendor/<target>/bin/codex. The default timeout is 90 seconds (--timeout). A managed Windows host refuses--live: use the staticverifyand confirm withaudit export(see Windows: Inspect machine policy).
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy verify \
--live --user alice --connector codex --agent-binary /usr/local/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex --jsonPer-user connector state
Connectors without a machine policy file, such as Devin, Antigravity, Hermes, Amp and Kiro (and OpenCode while its managed plugin is not in force), are wired into each user's own agent config by the guardian. The enumerator decides which users to protect.
- The enumerator runs every 5 minutes on every OS and writes the target manifest
(
targets.yaml), one row per user and connector. A new user or newly enabled connector first appears on its next cycle, so allow up to 5 minutes. - The guardian then installs or repairs the hooks for each row. It reacts to file changes and also reconciles every minute.
- On Linux and macOS, the guardian records each protected user in its authorization ledger. The gateway accepts per-user hook calls only from users in that ledger.
To reconcile now instead of waiting for the next minute, run the reconcile action
(sudo … enterprise linux reconcile --json, or the macOS or Windows equivalent). It
does not wait for the enumerator.
| OS | Target manifest | Notes |
|---|---|---|
| Linux | /etc/defenseclaw/hook-guardian/targets.yaml | A deleted user is removed at the third enumerator cycle in a row that reports "no such user" (10 to 15 minutes), or at once by repair. A directory outage does not remove anyone |
| macOS | /opt/cisco/defenseclaw/etc/hook-guardian/targets.yaml | Same as Linux |
| Windows | C:\ProgramData\Cisco\DefenseClaw\hook-guardian\targets.yaml | The guardian writes a user's hooks only while that user has an active (connected) session. Rows for a signed-out or disconnected user wait |
If a user you expect is missing, see A user is not enrolled and Enrollment.
What the guardian repairs in a user account
A user can break the files DefenseClaw needs in their own account, for example by replacing an agent's config folder with a file or a symbolic link, or leaving an agent config the agent cannot parse. That account is then not protected for the affected per-user agents. Every other account stays protected and the services stay ready. Once the account is fixed, the next reconcile (within a minute) clears the warning.
When the guardian is refused by a path in the user's own home (a link, a file where a
folder belongs, a folder where a file belongs, or a folder the worker cannot read,
other than ~/.defenseclaw and its hooks folder, which the guardian sets back to 0700),
status, verify and reconcile report the warning guardian_target_user_path,
which names the path. It does not fail reconcile, verify,
detect.sh --require-healthy or security_complete, because only that account is
affected and the user could have made the change themselves. Any other reason the
account cannot be protected is guardian_target_failed: it sets
security_complete: false, verify fails, and detect.sh --require-healthy reports
the device as not compliant.
The guardian repairs, as that user and within a minute, what DefenseClaw owns in the
account: DefenseClaw's registration or plugin in the agent's default config; the
modes of a user-owned ~/.defenseclaw and its hooks folder (restored to 0700); a
deleted or edited hook script, and a hook runtime whose fail mode no longer matches
the config; a missing ~/.kiro or ~/.kiro/hooks folder; and group or other write
on the home folder of an enrolled user; a features.hooks key in the user's ~/.codex/config.toml
under Codex machine policy (it conflicts with the pinned setting, and Codex then refuses project
trust writes); and a native OTLP exporter in the user's ~/.codex/config.toml or
~/.claude/settings.json that carries a DefenseClaw credential. It changes nothing else, so these stay
unprotected until the user or an administrator fixes them: a link or non-directory
where an agent's config folder belongs, an agent config the agent cannot parse, a
special file such as a named pipe at a config path, and files another account owns.
A file event starts a guardian pass at once, and the pass watches every protected target for 300 ms, so a program that rewrites an agent's hook block over and over (Hermes was the case tested) is repaired within about 3 seconds of its first damaged write. Faster restores can still undo the repair. On macOS the guardian reads an account's launchd HERMES_HOME (set with launchctl setenv), so a Hermes home outside ~/.hermes is protected.
To find the account, read warnings[] in status --json or verify --json: each
guardian_target_user_path and guardian_target_failed entry names the user, the
connector and the reason. As root, /opt/defenseclaw/bin/defenseclaw-gateway enterprise hooks status --json (/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS)
lists every user and connector with its state.
When a user breaks their own setup (Linux and macOS)
A user can break files DefenseClaw needs in their own account, for example by replacing an agent's config folder with a link. That account is then unprotected for the affected per-user agents; everyone else stays protected. The guardian reports guardian_target_user_path (a path in the user's home refused it; does not fail verify) or guardian_target_failed (sets security_complete: false). Read warnings[] in status --json to find the account.
~/.defenseclaw and ~/.defenseclaw/hooks follow one rule in an account the guardian has a per-user target for: an account enrolled for a per-user agent (Amp, Antigravity, Devin, Hermes, Kiro, or OpenCode on its per-user plugin). While each is a real folder the user owns, the guardian sets its mode back to 0700 within a minute, also after chmod 000, and reports nothing. A link or a file in place of either folder is not changed: it is reported as guardian_target_user_path until the user puts the folder back.
Codex, Claude Code, Cursor, Copilot, and OpenCode through its managed plugin get DefenseClaw's hooks from vendor machine policy (see Machine policy). An account that runs only these agents has no per-user target. The guardian keeps no hook files in its ~/.defenseclaw (only the session cache is there), does not change that folder, and reports no guardian_target_user_path for it: the machine policy keeps the account protected. If the user makes that folder unreadable, the enumerator cannot finish its scan of the account's agent installs, and status and verify report agent_install_scan_incomplete for the account's agents until the folder can be read again. enterprise hooks status lists the accounts that have per-user targets.
Rotate per-user credentials
The guardian gives each enrolled user credentials that it derives from one per-machine key and binds to that user's uid or SID. Native agent telemetry, where enabled, uses them on every OS, as do hooks and in-agent plugins on Windows. On Linux and macOS, hooks and in-agent plugins reach the gateway over the hook socket and hold no credential. Rotate the key when a user's credentials may have been copied, or on your own schedule.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux rotate-credentials --jsonsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos rotate-credentials --jsonIf no enrolled user holds a credential yet, the command exits 0 with
"noop": true and "noop_reason": "no_credentials" and changes nothing. That is the
normal state on Linux and macOS while users run only hook-based agents and the config
enables no agent telemetry.
The rotation checks, stages the new key beside the current one, moves every user, then commits; any failure before the commit rolls every user back and exits 1 with rotation_failed. Ask users to restart their agents afterwards, because running agents lose telemetry once the old key is refused. On Windows rotate-credentials exits 1639; to cut off one user, remove them from enrollment (Contain an incident).
Rotation steps
The rotation moves every user to the new key before the key takes effect:
- Check. Nothing changes until the gateway reports that it serves the current key
alone and a fresh guardian reconcile leaves every user who holds a credential
current. A target the guardian cannot protect but that holds a credential (for
example one whose own home blocks it,
guardian_target_user_path) stops the rotation withrotation_failed; fix that user or remove them from enrollment, then rotate again. A target that holds no credential does not stop it; the rotation lists those inchangesas skipped. - Stage. The rotation writes a root-only record for the guardian, then the new key next to the current one. From then on the gateway accepts the credentials of both keys, and it must prove it accepts each user's new credentials before any user is moved.
- Move. The guardian re-renders every user from the new key. A second reconcile re-reads each user's installed files and must find them unchanged.
- Commit. The new key replaces the current one and the record is removed. The gateway refuses the old key's credentials from then on.
If any step before the commit fails, the guardian moves every user back to the old key
while the gateway still accepts both, then the rotation removes the new key and the
record. The command exits 1 with rotation_failed, which names the step and the
users. rollback_failed beside it means the rollback is not complete yet; its message
says whether the next lifecycle run finishes it or the guardian re-renders the
remaining users within a minute. Ctrl+C (or SIGTERM) rolls the rotation back the same
way unless the new key has already replaced the old one; a second Ctrl+C stops at once
and prints the reconcile command to run. After a stopped or killed rotation, the next
lifecycle action completes a committed rotation or rolls back one that had not, and
reports rotation_recovered. Until then the gateway accepts the new key for at most 30
minutes after the rotation wrote it. The result names keys only by a prefix of their
SHA-256.
What users see: hooks and plugins on Linux and macOS keep working through the rotation. Agents that are already running keep sending telemetry with the credential they loaded at start; it works until the commit, and after that the agent's telemetry is lost until the user restarts it. Ask users to restart their agents after a rotation.
On Windows, enterprise windows rotate-credentials exits 1639 and changes nothing:
the Windows guardian writes a user's credentials only while that user is signed in, so
it cannot move every user before a new key takes effect, and replacing the key would
fail the hooks of every signed-out user closed. To cut off one Windows user, remove
them from enrollment as described in
Contain an incident.
Golden images and VM templates
A host cloned from a template that already runs the deployment shares its device key and per-machine key. Capture the template before you install DefenseClaw, or run uninstall --purge --json on it first.
Golden images and VM templates detail
A host cloned from an image or VM template that already runs the managed deployment
(Linux and macOS) starts with a copy of that host's machine state: the gateway's
device key (/var/lib/defenseclaw/device.key on Linux,
/opt/cisco/defenseclaw/runtime/device.key on macOS), so every clone reports the same
device; the per-machine key the guardian derives each user's credentials from; the
gateway's redaction-correlation.key and sandbox registration store, if an account on
the template kept sandboxes; and the machine ID, unless the imaging tool resets it.
Prefer an image without that state: capture the template before you install DefenseClaw
and install it on each clone at first boot, or run
enterprise linux uninstall --purge --json (macOS: enterprise macos uninstall --purge --json)
on the template before you capture it. A plain uninstall keeps the sandbox store
and redaction-correlation.key when an account kept sandboxes; the key is per-machine
and a clone must not share it. Use --purge for a clean image, and keep --keep-state
off. A purge also deletes each enrolled account's ~/.defenseclaw, its sandboxes and
any sandbox work not pulled yet.
For clones that already run it, on each clone:
- Give it its own machine ID first. On Linux that is the imaging tool's job (for
example
cloud-init clean --machine-id, or an empty/etc/machine-idthat systemd fills at the next boot); on EC2, systemd derives the ID from the instance UUID, so each instance already has its own. Each Mac has its own hardware UUID. - Reinstall: uninstall with
--purge, then install the same package or payload again. On a Linux tarball host with fapolicyd, trust the staged payload and use the two-stage tarball install, adding installed-tree trust if no entry exists or updating an existing entry after staging. That gives the clone a new device key, a new per-machine key and a newredaction-correlation.key. To keep the deployment instead, runenterprise linux rotate-credentials --json(macOS:enterprise macos rotate-credentials --json; see Rotate per-user credentials): the users' credentials then differ per clone, but the device key stays shared.
A new machine ID changes every agent ID: an agt- ID hashes the machine ID
(Agent identity), so each
agent install gets a new agt- ID, and records from before keep the old IDs. status,
verify and the hooks are not affected.
Logs and events
Windows
| What | Where |
|---|---|
| Lifecycle log | %WINDIR%\Logs\DefenseClaw\enterprise-lifecycle.log: one JSON result per line, 5 files of up to 5 MiB each |
| Last result | %WINDIR%\Logs\DefenseClaw\last-result.json |
| MDM wrapper log | %WINDIR%\Logs\DefenseClaw\mdm-wrapper.log |
| Event log | The DefenseClaw event log, source DefenseClaw Lifecycle (table below). Only SYSTEM and Administrators can write it. A copy of each event goes to the Application log, source DefenseClaw Enterprise, where any account can write under any source name; see Windows |
| Gateway log | C:\ProgramData\Cisco\DefenseClaw\logs\gateway\gateway.log |
| Guardian and enumerator log | C:\ProgramData\Cisco\DefenseClaw\logs\guardian\hook-guardian.log. The hook enumerator writes here too, each line prefixed [hook-enumerator]; its warnings about one account name the account's SID |
| Sensor helper log | C:\ProgramData\Cisco\DefenseClaw\logs\sensor-helper\sensor-helper.log |
Administrators and Event Log Readers can read the files in %WINDIR%\Logs\DefenseClaw. The gateway, guardian and sensor helper logs under C:\ProgramData\Cisco\DefenseClaw\logs are for SYSTEM and Administrators only; the gateway service can also read and write logs\gateway.
To check that the event log entries are DefenseClaw's, compare them with the lifecycle log from an elevated PowerShell (as an Administrator or a member of Event Log Readers, the accounts that can read the lifecycle log):
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows events
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows events --application --jsonAn entry is DefenseClaw's only when its message ends with record <id>, the
lifecycle log holds that record with the same event ID and the SHA-256 of the
exact message, it was written within two minutes of that lifecycle line, and no
earlier entry carried the same record. Entries older than the lifecycle log's
first record are listed as unverifiable. The command exits 1 when an entry
was not written by DefenseClaw (a forged entry) or when the newest lifecycle
record written to the checked log has no entry there (a missing record).
--application checks the copies in the Application log instead, --max N
shows the newest N entries (default 20, 0 for all) while every entry is
checked, and --json prints every entry.
Windows event IDs
Only SYSTEM and Administrators can write the files in %WINDIR%\Logs\DefenseClaw,
and only Administrators and members of Event Log Readers can read them, because each
result names the accounts it found, their SIDs and guardrail profiles. Each lifecycle
run sets these permissions again. The events list only the code of each error and
warning; their text is in the lifecycle log. The lifecycle writes these logs and
events only when it runs elevated.
| Event ID | Meaning |
|---|---|
| 100 | Installed (written by /install; /ensure writes 111 or 112 instead) |
| 101 | Upgraded (written by /upgrade; /ensure writes 111 or 112 instead) |
| 102 | Repaired, or a reconcile ran |
| 110 | Uninstalled (Application log only, because uninstall removes the DefenseClaw log) |
| 111 | ensure found nothing to change |
| 112 | ensure applied a change, including the first install and an upgrade that /ensure performed |
| 120 | status or verify found the deployment unhealthy (warning) |
| 130 | An action failed (error) |
| 140 | Another lifecycle run held the lock (warning) |
| 150 | The run was refused: invalid arguments, PowerShell 7 missing or untrusted, a profile conflict, or an unsupported host (error) |
A healthy status or verify writes no event, so frequent polling does not fill the
event log.
Linux
| What | Where |
|---|---|
| Service output | The journal: journalctl -u defenseclaw-gateway.service, and likewise for defenseclaw-hook-guardian.service, defenseclaw-hook-enumerator.service and defenseclaw-sensor-helper.service |
| Config changes applied | journalctl -u defenseclaw-enterprise-apply.service |
| Daily verify | journalctl -u defenseclaw-enterprise-verify.service |
/var/log/defenseclaw | Empty by default: the services write to the journal. The gateway may write only there and in /var/lib/defenseclaw, so it is the place for a jsonl file destination (see Audit records and SIEM forwarding) |
| Package install result | /var/lib/defenseclaw-enterprise/last-package-result.json, and last-package-result.log beside it with the standard error of the same run (often empty, 0 bytes). Every rpm or deb install and upgrade writes both. A later ensure that recovers a host after a failed package run removes both |
| MDM wrapper log | /var/log/defenseclaw-enterprise-mdm.log |
| Kernel sensor records | With Tetragon and Plane C, the sensor helper's records reach your destinations as ai.runtime.plane_health, ai.runtime.kernel_policy, ai.runtime.kernel_event and enforcement.block.applied with the initiator kernel. See Tetragon on a Linux fleet |
journalctl -u defenseclaw-enterprise-verify.service -n 50 --no-pager
systemctl list-timers defenseclaw-enterprise-verify.timermacOS
All logs are in /Library/Logs/Cisco/DefenseClaw.
| What | File |
|---|---|
| Gateway | gateway/gateway.out.log, gateway/gateway.err.log |
| Guardian, enumerator, sensor helper | hook-guardian.*.log, hook-enumerator.*.log, sensor-helper.*.log |
| Config changes applied | lifecycle.log |
| Daily verify | verify.log |
| MDM wrapper | mdm-wrapper.log |
| Package install result | /opt/cisco/defenseclaw/lifecycle/last-package-result.json |
Audit records and SIEM forwarding
The gateway records every hook decision in its local audit store, the SQLite database
set by observability.local.path. By default it is audit.db in the data directory:
/var/lib/defenseclaw on Linux, /opt/cisco/defenseclaw/runtime on macOS, and
C:\ProgramData\Cisco\DefenseClaw\runtime on Windows.
To forward records to a SIEM, add observability.destinations to the managed config
you deploy. Destination kinds include OTLP, Splunk HEC, HTTP JSONL and JSONL files;
see Observability. enterprise <os> status and verify warn
when an optional destination is failing. For the destination name, circuit state, last
failure code and rejected count, run /opt/defenseclaw/bin/defenseclaw-gateway status (/opt/cisco/defenseclaw/bin/defenseclaw-gateway status on macOS, & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe' status on Windows) on the managed host
or read its loopback /health telemetry.details.destinations object. A failed
optional destination does not stop the local audit store or sibling destinations.
no_space means a JSONL file destination's volume is full; free space there and let
its retry resume.
On a managed host, destination credentials come from protected storage (token_credential, bearer_credential, {credential: NAME}), and a jsonl file destination must use a path under /var/lib/defenseclaw or /var/log/defenseclaw on Linux.
Rules for SIEM forwarding on a managed host
Two rules apply on a managed host:
- Credentials come from protected storage, not the environment. The lifecycle
writes each service's environment itself, so a destination's
token_env,bearer_envor{env: NAME}header cannot be resolved, andensurerefuses a config that uses one. Store the credential withenterprise secret setand reference it by name:token_credentialfor Splunk HEC,bearer_credentialfor HTTP JSONL, and{credential: NAME}for a header. See Observability credentials. - The gateway runs in a sandbox. On Linux it can write only inside
/var/lib/defenseclawand/var/log/defenseclaw, so ajsonlfile destination must use a path there. Your log agent can collect the file only if it runs as root or thedefenseclawservice account: the file is0600inside a service-owned0750folder. Use a privileged collector to forward it to a separate destination for other readers.
Run the administrator runbook with an AI agent
Hand this page to your agent
Paste this into your agent:
Read https://cisco-ai-defense.github.io/defenseclaw/docs/enterprise/operations/llms.md and follow it. I am the administrator of this computer. Ask me before running ensure.You are an AI agent working for an administrator, on an admin workstation or a test host the administrator names. Write the standalone config, check it, run ensure and verify the result.
Hard rules
- Never run this on a user's managed computer, or on any computer the administrator did not name. Per-user commands print
This computer is managed(exit2) orThis device is managed(exit3) on a managed computer; that is the product telling you to stop. - Observe first. Write
guardrail.mode: observe. Switching toactionor changing a fail mode needs the administrator's yes to that exact change. - Never print a key or token. The Cisco AI Defense key never goes in the config, a script body or a command line; use
enterprise secret set --from-stdin. - The config file must be owned by root (Windows: SYSTEM or Administrators) and writable by nobody else, or the wrapper refuses it.
Steps
-
Write the config. Start from the Linux example; the macOS and Windows paths are on Enterprise.
config_version: 9 deployment_mode: managed_enterprise data_dir: /var/lib/defenseclaw # must be exactly this path policy_dir: /etc/defenseclaw/policies enterprise: profile: standalone gateway: api_bind: 127.0.0.1 api_port: 18970 guardrail: enabled: true mode: observe connectors: codex: {} claudecode: {}Expected: a root-owned file, mode not writable by group or others, at most 1 MiB. If it differs: fix the owner and mode. Do not proceed.
-
Check the candidate file before anything is installed.
"$PAYLOAD/defenseclaw-gateway" config validate ./config.yamlExpected: no error, and the previous config stays in force either way.
$PAYLOADis the folder of the unpacked release archive. On a host that already has the package, run the installed gateway instead:/opt/defenseclaw/bin/defenseclaw-gatewayon Linux,/opt/cisco/defenseclaw/bin/defenseclaw-gatewayon macOS. It is not on thePATH. If it prints an error: report the setting it names and the profile; do not guess a value (config_invalidin Enterprise troubleshooting). -
Show the administrator the config and the artifact name and SHA-256 you will use. Ask: "Run ensure on this host?" Continue only on yes.
-
Run
ensurewith the kit wrapper (Linux example, pinned by SHA-256).sudo ./defenseclaw-enterprise.sh --source <artifact> --sha256 "$PIN" --config-file /etc/mdm/defenseclaw/config.yamlExpected: one result document and exit code
0. When the host already matches it reports"noop": true. If it differs: read the exit code anderrors[].code.Exit (Windows / Linux, macOS) Meaning You do 0/0Success or nothing to do Continue 1603/1Failed and rolled back Report errors[].code1618/75Busy Retry later, once 1639/2Invalid arguments Fix the assignment -
Verify.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --jsonmacOS:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify --json. Windows (elevated):& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows verify --profile standalone --json. Expected:coverage_completeistrue; on Linux and macOSpolicy.appliedistrue.security_completeistrue, orfalsewith only the warninghook_process_fail_openwhen Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity is enabled: report that warning as the known hook-process limit, not as a failed install. If it differs: report the fields and the error codes. See Enterprise troubleshooting. Do not edit installed files by hand.
Report
Reply with:
- Host, OS and the artifact version and SHA-256 you used.
- The config you wrote (no keys) and its mode.
- The
ensureexit code and result. verifyfieldscoverage_complete,security_completeandpolicy.effective_digest.- What needs the administrator's decision.
Account join key
How a standalone device reports a per-tenant key for each account that ran an agent, so a fleet service can match device records to its directory accounts without the device sending names or SIDs.
Managed command availability
Which defenseclaw commands a standard user can run on a managed Linux, macOS or Windows computer, and which are refused, against a per-user install.