Windows security model

On Windows, an agent's hook or plugin waits for DefenseClaw's decision and can block. Isolated OpenShell agents may also export native OpenTelemetry (OTLP), which records activity but cannot block it. Host Codex and Claude Code use hooks because their native exporters cannot verify a local TCP listener.

Connector telemetry channels

Each connector page lists that agent's hook events, whether it exports OTLP, its configuration files, and its Windows-only quirks.

The rule on Windows: only a hook or plugin that waits for DefenseClaw's answer can block. OTLP and other telemetry add detail to the audit log and dashboards, but cannot block an action after the fact.

Host setup removes the Codex and Claude Code native OTLP exporters it can prove DefenseClaw wrote and revokes credentials from earlier releases, because those exporters cannot verify who holds a stopped gateway's port. Proof is a value with the scoped credential setup gave that connector (current, or recorded as retired) or a value its setup backup recorded. An exporter you set yourself stays. An exporter left by an earlier install whose credential is gone also stays, even with x-defenseclaw-* headers or an old local port, because setup can no longer prove it is DefenseClaw's. Remove it by hand: the OTEL_* entries in the env block of %USERPROFILE%\.claude\settings.json, or the [otel] table in %USERPROFILE%\.codex\config.toml. Hook and plugin credentials are also connector-scoped and remain distinct from the gateway master token. Connector pages identify which channels exist and where their managed settings live.

Standalone OpenCode and Amp plugins use one TCP connection for the listener challenge and hook request. The gateway checks that the account opening the challenge owns the scoped credential before it returns a proof. Per-user plugins verify the connected listener's account through the native helper.

A scoped credential is accepted only for its connector and route; it cannot authenticate the management API, another connector, or a non-loopback request. Hermes hook-derived audit records retain connector, session, event, and correlation attribution before entering generic alert, webhook, OTLP, or Splunk destinations.

Local audit is always on

The gateway always writes its audit log to %USERPROFILE%\.defenseclaw\audit.db (SQLite). On a managed computer the audit database is C:\ProgramData\Cisco\DefenseClaw\runtime\audit.db, and an administrator checks the deployment from an elevated prompt with defenseclaw.exe enterprise windows status --profile standalone and enterprise windows verify --profile standalone. It keeps writing when no remote destination is configured, and when a remote destination is unreachable.

gateway.jsonl is not a default audit file. It exists only if an optional kind: jsonl destination is configured to write that path. The detached gateway's process log is a different file, %USERPROFILE%\.defenseclaw\gateway.log.

Privacy and redaction boundary

Connectors capture prompt content so that each destination can apply its own redaction. A new install's redaction profile is none. Therefore:

• the local audit database can hold prompts, tool calls, decisions, and telemetry in full;
• adding a remote destination does not make what it receives safe for another audience until you set its redaction; and
• redaction applies to what is sent from now on, not to records already stored or sent.

Treat the data directory and any audit export as sensitive user data. Configure and verify redaction profiles before routing records to another system. defenseclaw config show masks secret values and has no option to reveal them.

The gateway records authentication and delivery failures without putting raw scoped credentials into route names or operational telemetry. That does not make a copied database, log, connector configuration, backup, or crash artifact safe to publish.

Credential model

DefenseClaw uses distinct credentials for distinct jobs:

Rotate safely

Rotation always covers the gateway and every connector together:

defenseclaw setup rotate-token --yes

rotate-token replaces the gateway token and every connector's hook credential, each with its own new value. It stops the gateway, saves the new values, updates each agent's hook or plugin, and starts the gateway again. If a step fails after the gateway stopped, it puts the previous values and gateway back. Rotation always includes the gateway restart, and it does not rewrite a token that you supply through your own environment variable. Hook credentials are private to your account, including those an upgrade from an earlier 1.0 release carried over, so rotate-token works after an upgrade.

Each connector still gets its own credential, separate from the gateway token; rotation never prints them or lets one connector use another's. After a rotation, restart every agent you set up (fully exit and relaunch Amp) so it uses the new settings.

Rotation refuses a hook credential file that is not private to your account, and names the file, the reason and the icacls command that makes it private. The upgrade from 0.8.x seals the credential files 0.8.x left with the permissions they inherited from the folder.

Verify without reading any token:

defenseclaw-gateway status
defenseclaw status
defenseclaw doctor

Loopback and network boundaries

The supported connector topology uses the current user's native agent and gateway on loopback, normally 127.0.0.1:18970. The loopback HTTP receiver is authenticated; it is not a claim that localhost is inherently trusted.

• A connector-scoped token is restricted by connector, route, signal, and loopback origin.
• Management routes require their own authentication.
• An agent on another computer sending hooks to this gateway is not tested on Windows.
• Outbound OTLP, Splunk, Galileo, webhooks, and provider calls are independent client connections. Their availability does not expand hook coverage.
• Native Windows runs no guardrail proxy, so OpenClaw and ZeptoClaw are unsupported.

Do not expose the local API to your network to make a remote agent work. That is not a tested setup, and it needs authentication, TLS, and firewall measures this guide does not cover.

Release and installer trust

install.ps1 checks every file it downloads against the release's checksums.txt. That catches a corrupted or mismatched download, but on its own it does not prove who published the release. The Release workflow signs checksums.txt with Sigstore; when cosign 2.0 or later is installed, the installer and defenseclaw upgrade verify that signature against the release workflow's identity before trusting any file, and stop if it fails. Install cosign first if you want that publisher check.

Windows release executables are not Authenticode-signed, so Windows reports them as NotSigned. Their integrity comes from the checksum set, not from a Cisco Systems, Inc. Digital Signatures entry.

The release workflow installs, upgrades, and rolls back the exact release files on a Windows x64 runner before it publishes them.

Local and pull-request artifacts are not published releases. Passing their tests proves code and lifecycle behavior, not release provenance. See Windows.

Ownership and filesystem boundary

The per-user package runs as the current user and changes only what it created or recorded. Its installer state, credentials, audit database, and process records are owned by the current user. audit.db and .env grant access only to the user (OWNER RIGHTS or the account) and SYSTEM, so an administrator can read them only after taking ownership. The .defenseclaw folder, config.yaml, agent_selection.json, hooks\.hookcfg, the hook tokens and scripts, and OpenCode's managed plugin also grant access only to the user (or OWNER RIGHTS) and SYSTEM. A few files the gateway writes (judge_bodies.db, the audit.db-wal and audit.db-shm journals, redaction-correlation.key and some .lock files) also grant Administrators. That keeps other standard users out, but it does not protect against the user themself or an administrator; defenseclaw doctor detects a changed plugin and setup puts it back. Files that agents own keep their own permissions.

The installer and lifecycle commands:

• refuse an existing folder that has no valid DefenseClaw installer state;
• refuse a protected path, or a recorded agent folder, that goes through a symbolic link or junction;
• stop only the gateway or watchdog they started, checked by executable, process start time, and data folder;
• never replace a sign-in entry, PATH entry, Installed Apps entry, listener, process, or agent file that DefenseClaw does not own; and
• keep recovery files they are unsure about instead of deleting them.

DefenseClaw's own programs support paths longer than the old MAX_PATH limit; third-party agents and plugins may not. Remote network folders are not supported for DefenseClaw's data. Avoid agent folders that differ only by letter case.

Transaction and fail-closed boundaries

What happens when something fails depends on where it fails:

A malformed config.yaml stops the gateway from starting instead of loading part of it. A disabled connector is removed from what the gateway runs. A setting that needs a gateway restart, such as a port or a connector's hook fail mode, shows as a difference between saved and running settings until the gateway restarts. Other changes to config.yaml apply to the running gateway without a restart.

Machine-wide hooks are enterprise only

The per-user install never installs a machine-wide service, guardian, or machine policy. Machine-wide deployment, including Claude Code managed hooks published through Claude Code's managed-settings policy, Codex and Cursor managed hooks, and GitHub Copilot machine policy (standalone profile only), is part of enterprise deployment: the standalone profile or the Secure Client profile.

Security operations links

• Configuration
• Environment variables
• Fail modes
• Redaction
• Observability
• Scan a skill
• Scan an MCP server