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.

ActionWhat it doesUse it for
statusReports 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-zeroInventory and dashboards
verifyRuns 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-zeroCompliance and alerting
Linux
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json
macOS
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify --json
Windows (elevated PowerShell)
$DefenseClaw = 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe'
& $DefenseClaw enterprise windows status --profile standalone --json
& $DefenseClaw enterprise windows verify --profile standalone --json

Run 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 verifyLinux and macOSWindows
Healthy00
A check failed11603
Invalid arguments21639

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.

OSScheduled verify
Linuxdefenseclaw-enterprise-verify.timer: daily, with up to one hour of random delay
macOScom.cisco.defenseclaw.verify: daily at 03:17 local time
WindowsNone 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.

Linux
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.jsonl
macOS
sudo /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
CommandWhat it shows
statusThe gateway's health, its subsystems, and its connectors and their modes
enterprise hooks statusThe 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 exportThe 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 findingsThe 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.

Elevated PowerShell prompt
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --profile standalone --json

Audit 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.

FieldMeaning
oktrue only when errors is empty
exit_codeThe process exit code
installed, installed_versionWhether a deployment is recorded, and its version
transaction_pendingAn 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
readinessgateway, guardian, enumerator, sensor_helper: each true when that component is ready
coverage_completeThe core services are ready (definition per OS below)
security_completeEverything 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
enrollmenttargets, 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
inspectionlocal and ai_defense (see the note below the next table)
policyThe 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:

enterprise linux status --json (healthy, trimmed)
{
  "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":

enterprise linux verify --json (failed, trimmed)
{
  "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:

FieldLinux and macOSWindows
coverage_completeThe 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_unprotectedThe 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_completecoverage_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 exempt is always 0 there: accounts that exclude_users or exempt_users keep out of enrollment have no target, and enterprise policy show --user <name> names the rule for one account. Windows counts the rows of the target manifest: pending is deferred rows, exempt is disabled rows, and failed is always 0.
  • Inspection. On Windows, inspection.ai_defense is ok when AI Defense is enabled in the config and the gateway is ready; it does not test the key or the network. inspection.local is active when the gateway is ready, unknown while it is not, and disabled when no deployment is installed. On Linux and macOS the lifecycle reads both fields from the gateway's /health: local is active, disabled or unknown, and ai_defense is disabled, ok, unavailable:<code> or unknown. The gateway's /health guardrail detail carries ai_defense_available and, 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 enrollment for 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

SignalAlert when
verify exit codeNot 0
coverage_completefalse
security_completefalse 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[].codemachine_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.appliedfalse on Linux or macOS: security_complete is false; verify fails when the gateway reports a different digest or a rejected reload.
policy.effective_digestDiffers between hosts of one OS that received the same config
machine_policy.<connector>.conflicts or .higher_precedenceNot empty
enrollment.failedGreater than 0 (Linux, macOS)
transaction_pendingtrue 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 .policy

status 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 in config.generation.json next to the config: generation, config_sha256, actor, reason and written_at. On a managed host only the lifecycle (actor lifecycle) and a migration (actor migration) 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 the ai_discovery.home_dirs list the enumerator fills in are left out, and a path under data_dir is written as ${data_dir}. The gateway stamps it on /status and 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:

FieldMeaning
effective_digestThe digest the installed config computes to, from the installed gateway binary's policy digest run with the service environment
config_generationThe generation recorded in config.generation.json. 0 means none recorded
appliedtrue when the running gateway reports the same digest on /health and has no policy.last_reload_error
gateway_reported_digestThe digest /health reported. Omitted when the gateway did not answer
last_reload_errorWhy the gateway rejected its last reload. Omitted when there is none
config_unrecordedtrue 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:

  • status and verify check application. applied: false means the gateway runs another policy than the config on disk computes to, or rejected its last reload. status reports the cause and sets security_complete: false. verify reports policy_not_applied or policy_reload_rejected as 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, repair or ensure, when the gateway is ready, a different gateway digest adds the warning policy_not_applied. When the digests match without a reload error, the lifecycle writes policy-state.json (effective_digest, config_generation, applied_at, root-only) next to deployment.json: /var/lib/defenseclaw-enterprise on Linux, /opt/cisco/defenseclaw/lifecycle on macOS, and C:\ProgramData\Cisco\DefenseClaw\install on Windows.
  • Windows. The Windows lifecycle migrates a config_version: 8 config and records the generation as actor lifecycle. You can also read the digest with enterprise policy show, which prints a line such as Effective policy sha256:7b38f1df3862, config generation 3 (and adds policy to --json), as in Machine policy status.
  • Warnings on every action. policy_reload_rejected says 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_buildable says the installed config and its assets no longer build into a policy. config_edited_outside_lifecycle says config.yaml was changed by hand; run ensure with the intended config to put the managed config back. On Windows that ensure keeps the edited file as rejected-config.yaml next to config.yaml (administrators only) and warns config_reverted. None of them changes ok.
  • Secure Client. The gateway omits policy from /health and /status, and the lifecycle result has no policy object.

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:

Linux
sudo curl -s --unix-socket /run/defenseclaw-hook/hook.sock http://localhost/health
macOS
sudo curl -s --unix-socket /opt/cisco/defenseclaw/run/hook.sock http://localhost/health

or read /status (it needs the gateway token), or the policy: line of enterprise linux|macos|windows status. See The policy object.

/health (policy)
"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:

Linux
sudo /opt/defenseclaw/bin/defenseclaw-gateway policy digest
macOS
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway policy digest
Effective 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:46ece6be297f9c9b221524923b4baf2035c810503ddfa1b83a1024ee3c55c6e0

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

Linux
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy verify --json
macOS
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
Windows (elevated PowerShell)
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show --json

policy 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 show prints the effective policy line after its header, for example Effective policy sha256:7b38f1df3862, config generation 3, and adds a policy object (effective_digest, config_generation) to --json. The lifecycle status --json and verify --json results carry the same digest as policy.effective_digest on every OS (Health fields); policy verify does not print it.
  • policy verify exits 1 when 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 --live runs the real client as a user and proves that it loads DefenseClaw's hooks. It needs --user, exactly one --connector (codex or claudecode), and --agent-binary with the client's absolute path. For Codex, pass the native executable, not the npm codex launcher (codex.js needs node, which is not on the probe's minimal PATH): for a global npm install it is node_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 static verify and confirm with audit export (see Windows: Inspect machine policy).
Linux: live check for one user
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 --json

Per-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.

  1. 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.
  2. The guardian then installs or repairs the hooks for each row. It reacts to file changes and also reconciles every minute.
  3. 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.

OSTarget manifestNotes
Linux/etc/defenseclaw/hook-guardian/targets.yamlA 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.yamlSame as Linux
WindowsC:\ProgramData\Cisco\DefenseClaw\hook-guardian\targets.yamlThe 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.

Linux
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux rotate-credentials --json
macOS
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos rotate-credentials --json

If 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:

  1. 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 with rotation_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 in changes as skipped.
  2. 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.
  3. 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.
  4. 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:

  1. 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-id that 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.
  2. 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 new redaction-correlation.key. To keep the deployment instead, run enterprise 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

WhatWhere
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 logThe 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 logC:\ProgramData\Cisco\DefenseClaw\logs\gateway\gateway.log
Guardian and enumerator logC:\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 logC:\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 --json

An 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 IDMeaning
100Installed (written by /install; /ensure writes 111 or 112 instead)
101Upgraded (written by /upgrade; /ensure writes 111 or 112 instead)
102Repaired, or a reconcile ran
110Uninstalled (Application log only, because uninstall removes the DefenseClaw log)
111ensure found nothing to change
112ensure applied a change, including the first install and an upgrade that /ensure performed
120status or verify found the deployment unhealthy (warning)
130An action failed (error)
140Another lifecycle run held the lock (warning)
150The 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

WhatWhere
Service outputThe journal: journalctl -u defenseclaw-gateway.service, and likewise for defenseclaw-hook-guardian.service, defenseclaw-hook-enumerator.service and defenseclaw-sensor-helper.service
Config changes appliedjournalctl -u defenseclaw-enterprise-apply.service
Daily verifyjournalctl -u defenseclaw-enterprise-verify.service
/var/log/defenseclawEmpty 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 recordsWith 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.timer

macOS

All logs are in /Library/Logs/Cisco/DefenseClaw.

WhatFile
Gatewaygateway/gateway.out.log, gateway/gateway.err.log
Guardian, enumerator, sensor helperhook-guardian.*.log, hook-enumerator.*.log, sensor-helper.*.log
Config changes appliedlifecycle.log
Daily verifyverify.log
MDM wrappermdm-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_env or {env: NAME} header cannot be resolved, and ensure refuses a config that uses one. Store the credential with enterprise secret set and reference it by name: token_credential for Splunk HEC, bearer_credential for 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/defenseclaw and /var/log/defenseclaw, so a jsonl file destination must use a path there. Your log agent can collect the file only if it runs as root or the defenseclaw service account: the file is 0600 inside a service-owned 0750 folder. 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

  1. 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 (exit 2) or This device is managed (exit 3) on a managed computer; that is the product telling you to stop.
  2. Observe first. Write guardrail.mode: observe. Switching to action or changing a fail mode needs the administrator's yes to that exact change.
  3. 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.
  4. The config file must be owned by root (Windows: SYSTEM or Administrators) and writable by nobody else, or the wrapper refuses it.

Steps

  1. 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.

  2. Check the candidate file before anything is installed.

    "$PAYLOAD/defenseclaw-gateway" config validate ./config.yaml

    Expected: no error, and the previous config stays in force either way. $PAYLOAD is the folder of the unpacked release archive. On a host that already has the package, run the installed gateway instead: /opt/defenseclaw/bin/defenseclaw-gateway on Linux, /opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS. It is not on the PATH. If it prints an error: report the setting it names and the profile; do not guess a value (config_invalid in Enterprise troubleshooting).

  3. 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.

  4. Run ensure with the kit wrapper (Linux example, pinned by SHA-256).

    sudo ./defenseclaw-enterprise.sh --source <artifact> --sha256 "$PIN" --config-file /etc/mdm/defenseclaw/config.yaml

    Expected: one result document and exit code 0. When the host already matches it reports "noop": true. If it differs: read the exit code and errors[].code.

    Exit (Windows / Linux, macOS)MeaningYou do
    0 / 0Success or nothing to doContinue
    1603 / 1Failed and rolled backReport errors[].code
    1618 / 75BusyRetry later, once
    1639 / 2Invalid argumentsFix the assignment
  5. Verify.

    sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json

    macOS: 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_complete is true; on Linux and macOS policy.applied is true. security_complete is true, or false with only the warning hook_process_fail_open when 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 ensure exit code and result.
  • verify fields coverage_complete, security_complete and policy.effective_digest.
  • What needs the administrator's decision.