Windows standalone deployment

Install the standalone DefenseClaw enterprise services on Windows x64 with the Setup program, check the result, and remove them.

The standalone profile installs DefenseClaw machine-wide on Windows x64 as four Windows services. It does not need Cisco Secure Client. Standard users cannot stop the services or change the config, and the hook guardian restores DefenseClaw's hooks if a user removes them. Terms are in Concepts.

Deploying with an MDM?

This page installs on one computer from an administrator shell. For a fleet, start with Install with an MDM: it uses the same Setup and config.

Requirements

RequirementDetail
WindowsNative Windows x64. ARM64 (including x64 emulation) and 32-bit are refused
PowerShell 7A stable PowerShell 7 x64 from Microsoft's MSI, found through HKLM\SOFTWARE\Microsoft\PowerShellCore\InstalledVersions. PATH is ignored. Without it the run stops with powershell7_required
Language modeFullLanguage. Under WDAC or AppLocker, allow the DefenseClaw signer or the run stops with powershell_constrained_language
Execution policyWith AllSigned set by Group Policy, add DefenseClaw's signing certificate to Trusted Publishers or the run stops with powershell_execution_policy
PrivilegesAn elevated administrator token, or SYSTEM
DiskAbout three copies of the Setup payload plus 256 MB free on the ProgramData volume
Other profilesNo Secure Client DefenseClaw deployment (profile_conflict)
User sessionsUsers enroll while signed in at the console or over Remote Desktop. Accounts that only use SSH, scheduled tasks or runas are never enrolled

Layout

Binaries go under Program Files and state under ProgramData. Standard users cannot change either tree.

ItemPath
BinariesC:\Program Files\Cisco\DefenseClaw\bin: defenseclaw.exe, defenseclaw-gateway.exe, defenseclaw-hook.exe, defenseclaw-hook-guard.exe, defenseclaw-acp.exe, defenseclaw-sensor-helper.exe
Lifecycle scriptsC:\Program Files\Cisco\DefenseClaw\libexec
Managed OpenCode pluginC:\Program Files\Cisco\DefenseClaw\share\opencode\defenseclaw.js. Users hold read, execute and write-attributes on this one file because OpenCode opens every module with that right (Managed OpenCode plugin)
ConfigC:\ProgramData\Cisco\DefenseClaw\etc\config.yaml
SecretsC:\ProgramData\Cisco\DefenseClaw\secrets
Target manifestC:\ProgramData\Cisco\DefenseClaw\hook-guardian\targets.yaml (the enumerator writes it)
Lifecycle stateC:\ProgramData\Cisco\DefenseClaw\install
Gateway dataC:\ProgramData\Cisco\DefenseClaw\runtime
Authorization ledgerC:\ProgramData\Cisco\DefenseClaw\hook-guardian-state
Service logsC:\ProgramData\Cisco\DefenseClaw\logs
Scanner runtimeC:\ProgramData\Cisco\DefenseClaw-ScannerRuntime: defenseclaw-scanners.exe and the Python runtime it unpacks. The gateway can only read and run it
Hook runtimeC:\ProgramData\Cisco\DefenseClaw-HookRuntime, readable by users: the enrollment lists, runtime selectors and machine-policy.json
Lifecycle log%WINDIR%\Logs\DefenseClaw: enterprise-lifecycle.log, last-result.json and mdm-wrapper.log. Only Administrators and Event Log Readers can read them

The lifecycle also registers the deployment with Windows:

Before the gateway launches a scanner, it checks the access list of the bundled Python interpreter and every directory and file under python, including Lib\site-packages. Only SYSTEM and Administrators may create or change code there. A failed check blocks the scan and reports the path; an administrator restores the installed runtime with DefenseClawSetup-Enterprise-Standalone-x64.exe /repair JSON=1.

RegistrationValue
Deployment markerHKLM\SOFTWARE\Cisco\DefenseClaw\Enterprise (Profile, ProductVersion, InstallRoot, StateRoot, TrustMode, UpdatedAt, DisableSelfUpdate). For detection only: verify never trusts it
Add/Remove ProgramsHKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\CiscoDefenseClawEnterprise, "Cisco DefenseClaw Enterprise"
Event logThe DefenseClaw log, source DefenseClaw Lifecycle, writable only by LocalSystem and Administrators
Self-update policyHKLM\SOFTWARE\Policies\Cisco\DefenseClaw\DisableSelfUpdate = 1, written only when absent and removed on uninstall only in that case. Set enterprise.coexistence.disable_self_update: false to opt out

The four services restart after a failure:

ServiceIdentityRole
DefenseClawGatewayLocalSystem, write-restricted by its NT SERVICE\DefenseClawGateway service SID, with only SeChangeNotifyPrivilegePolicy engine and hook API on 127.0.0.1:18970
DefenseClawSensorHelperLocalSystem, SeChangeNotifyPrivilege onlyAnswers the gateway's fixed AI Discovery requests
DefenseClawHookGuardianLocalSystemWrites and repairs each enrolled user's registrations and the configured machine hooks every minute, even with no enrolled users
DefenseClawHookEnumeratorLocalSystemFinds eligible profiles (local, domain and Microsoft Entra ID accounts) every five minutes and writes the target manifest
starts
runs per tool call
asks over loopback TCP
TrustedZ0 · Admin and OS (SYSTEM)
UntrustedZ4 · User session (the user)
RestrictedZ2 · Gateway (restricted LocalSystem)
Service Control Managerknows the gateway's PID
AI agentruns as the user
defenseclaw-hook.exechecks the listener
Gatewayallows or blocks

List view for small screens. Use the expand button to open the drawing.

TrustedZ0 · Admin and OS (SYSTEM)

  1. Service Control Managerknows the gateway's PID
    • startsGatewayZ2

UntrustedZ4 · User session (the user)

  1. AI agentruns as the user
    • runs per tool calldefenseclaw-hook.exe
  2. defenseclaw-hook.exechecks the listener
    • asks over loopback TCPGatewayZ2

RestrictedZ2 · Gateway (restricted LocalSystem)

  1. Gatewayallows or blocks
Windows. The hook calls the gateway on 127.0.0.1:18970. Before it sends any bytes, it checks that the process behind the connection is the one the Service Control Manager reports for DefenseClawGateway. The hook's credential is bound to the user's SID, so the gateway knows who is calling.
writes
reads
repairs, as the user
PrivilegedZ1 · Services (LocalSystem)
ProtectedZ3 · Admin-owned files
UntrustedZ4 · User session (the user)
Enumeratorlists the users
Guardianchecks every minute
Target manifesttargets.yaml
Agent configin the user's profile

List view for small screens. Use the expand button to open the drawing.

PrivilegedZ1 · Services (LocalSystem)

  1. Enumeratorlists the users
    • writesTarget manifestZ3
  2. Guardianchecks every minute
    • readsTarget manifestZ3
    • repairs, as the userAgent configZ4

ProtectedZ3 · Admin-owned files

  1. Target manifesttargets.yaml

UntrustedZ4 · User session (the user)

  1. Agent configin the user's profile
Windows. The enumerator lists the users to protect in hook-guardian\targets.yaml. The guardian puts back DefenseClaw's hooks in each listed user's agent config, writing under that user's own token and only while the user has an active session. It also writes the Claude Code, Cursor, Copilot and OpenCode machine policy; the lifecycle writes Codex's.

The gateway refuses reads and scans inside user profiles. Its install watcher skips profile roots, and defenseclaw-gateway status --json reports a degraded watcher with health.watcher.details.profile_roots_skipped: true; the enterprise status and verify results do not report that field separately. See Scan skills, MCP servers and plugins.

Install

Five steps: check the release, write the config, run Setup, then optionally add the AI Defense key and the LLM judge.

1. Get and check the release

Download DefenseClawSetup-Enterprise-Standalone-x64.exe, checksums.txt and checksums.txt.bundle from one GitHub release. (DefenseClawSetup-Enterprise-x64.exe is the Secure Client Setup. Do not use it.) Verify the signature with cosign, then compare the Setup's hash with its line in the list. Keep the hash: MDM recipes pin it.

cosign verify-blob --bundle checksums.txt.bundle `
  --certificate-identity 'https://github.com/cisco-ai-defense/defenseclaw/.github/workflows/release.yaml@refs/heads/main' `
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' `
  checksums.txt
(Get-FileHash .\DefenseClawSetup-Enterprise-Standalone-x64.exe -Algorithm SHA256).Hash.ToLower()
Select-String -Path .\checksums.txt -Pattern 'DefenseClawSetup-Enterprise-Standalone-x64\.exe$'

2. Write the config

This protects Codex and Claude Code in observe mode:

config.yaml
config_version: 9
deployment_mode: managed_enterprise
enterprise:
  profile: standalone
gateway:
  api_bind: 127.0.0.1
  api_port: 18970
guardrail:
  enabled: true
  mode: observe
  connectors:
    codex: {}
    claudecode: {}

Each key under guardrail.connectors turns on one agent. With none, status warns no_connectors_enabled and verify fails (choose the agents, settings). Pick gateway.api_port before the first install: every user's hooks are bound to it, so changing it later means uninstall and install again. The file may be at most 4 MiB and 65,536 YAML nodes (limits).

Setup takes the config only from an absolute local path that standard users cannot change. Stage it in a folder you own:

$Stage = 'C:\ProgramData\DefenseClaw-Staging'
New-Item -ItemType Directory -Path $Stage -Force | Out-Null
icacls $Stage /setowner '*S-1-5-32-544' /T /C | Out-Null
icacls $Stage /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
Copy-Item .\config.yaml "$Stage\config.yaml"

Setup checks the config with the gateway's own compiler before it changes anything and names the line when it cannot load it. Quote Windows paths with single quotes in YAML. A custom rule pack folder needs its own permissions for the gateway service SID (sc.exe showsid DefenseClawGateway prints it); see Custom rule packs.

Custom rule packs

A pack folder (a guardrail.custom_packs entry) must be writable only by administrators and readable by the gateway service SID and by no standard user, because a pack is one profile's policy. Every parent folder needs Read and execute for that SID too, so give the packs their own folder, not the staging folder. The SID is derived from the service name: sc.exe showsid DefenseClawGateway prints it. Before the first install the service does not exist and icacls cannot grant it (error 1332), so set the permissions with Set-Acl, which writes the SID without a lookup:

$Packs = 'C:\ProgramData\DefenseClaw-RulePacks'
New-Item -ItemType Directory -Path $Packs -Force | Out-Null
# Owner Administrators, no inherited entries, SYSTEM and Administrators Full control,
# NT SERVICE\DefenseClawGateway Read & execute (by SID, so this works before the first install).
$Acl = Get-Acl -LiteralPath $Packs
$Acl.SetSecurityDescriptorSddlForm('O:BAD:PAI(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;0x1200a9;;;S-1-5-80-1858176940-1394861675-2895326486-505287571-2610476274)', 'Owner, Access')
Set-Acl -LiteralPath $Packs -AclObject $Acl
if (Test-Path -LiteralPath "$Packs\my-pack") {
    icacls "$Packs\my-pack" /reset /T /C | Out-Null
    Remove-Item -LiteralPath "$Packs\my-pack" -Recurse -Force -ErrorAction Stop
}
Copy-Item -LiteralPath .\my-pack -Destination $Packs -Recurse -ErrorAction Stop
icacls "$Packs\my-pack" /setowner '*S-1-5-32-544' /T /C | Out-Null

The snippet is safe to run again. Then name and pin the pack in the config:

config.yaml (excerpt)
guardrail:
  rule_pack: my-pack
  custom_packs:
    my-pack:
      path: 'C:\ProgramData\DefenseClaw-RulePacks\my-pack'
      digest: 'sha256:<digest>'

Before the first install no defenseclaw-gateway.exe can print the digest. Put a placeholder (sha256: and 64 zeros) in the config and run Setup: it refuses with 1639 and prints the pack's digest. Review the pack, put the digest in the config and run Setup again. Once installed, & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe' rulepack validate --dir "$Packs\my-pack" prints it as custom_packs pin:. Setup also refuses a pack folder with the wrong owner or permissions (1639, with the fix), and warns rule_pack_readable_by_users when Users, Authenticated Users, Everyone, INTERACTIVE or Domain Users can read one. A kind: jsonl destination needs a folder only SYSTEM, Administrators and the gateway SID can write. For Intune, the kit's reference rule-pack app sets these permissions (Custom rule pack app).

Strict and permissive rule packs

The Windows Setup ships only the default rule pack. guardrail.rule_pack: default (or no rule_pack) needs nothing else. strict and permissive have no files on the computer, so Setup refuses them with 1639 and changes nothing until you bring the pack:

config rule pack "strict": policy_dir is not set; the Windows Setup ships only the default rule pack, so strict has no files here. ...

To use strict, take the policies/guardrail/strict folder from the source archive of your DefenseClaw release (the Windows Setup does not contain it; permissive is the folder next to it), put it at guardrail\strict under a folder of your own, and make that folder administrator-owned with read access for the gateway service SID, as for a custom rule pack:

$Policies = 'C:\ProgramData\DefenseClaw-Policies'
New-Item -ItemType Directory -Path "$Policies\guardrail" -Force | Out-Null
$Acl = Get-Acl -LiteralPath $Policies
$Acl.SetSecurityDescriptorSddlForm('O:BAD:PAI(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;0x1200a9;;;S-1-5-80-1858176940-1394861675-2895326486-505287571-2610476274)', 'Owner, Access')
Set-Acl -LiteralPath $Policies -AclObject $Acl
if (Test-Path -LiteralPath "$Policies\guardrail\strict") { Remove-Item -LiteralPath "$Policies\guardrail\strict" -Recurse -Force }
Copy-Item -LiteralPath .\strict -Destination "$Policies\guardrail\strict" -Recurse -ErrorAction Stop
icacls "$Policies" /setowner '*S-1-5-32-544' /T /C | Out-Null

Then set policy_dir in the config:

config.yaml (excerpt)
policy_dir: 'C:\ProgramData\DefenseClaw-Policies'
guardrail:
  rule_pack: strict

Setup refuses a policy_dir without the pack folder with 1639 and names both properties. To keep one pack under your own name and pin its digest instead, use guardrail.custom_packs as described above.

3. Run Setup

From an elevated PowerShell session:

& .\DefenseClawSetup-Enterprise-Standalone-x64.exe /ensure "CONFIG=$Stage\config.yaml" JSON=1
$LASTEXITCODE

/ensure installs, upgrades, re-applies a changed config or repairs, and otherwise does nothing. Exit codes: 0 success or nothing to do, 1603 failed (rolled back), 1618 another run holds the lock (retry), 1639 invalid arguments (retrying does not help). All properties are in Setup actions and properties.

Third-party readers of managed files must open with FILE_SHARE_DELETE or retry a transient open failure during replacement.

An agent reads its hooks when it starts. A session opened before the install runs without DefenseClaw until it restarts; the result names each one with agent_sessions_restart_required.

Setup actions and properties

Setup exits with Windows Installer codes:

CodeMeaning
0Success, or nothing to do
1603Failure. A failed install, upgrade or repair is rolled back, and a refusal before any change leaves the computer as it was. If the rollback cannot finish, the transaction stays pending (Recover a pending transaction). For status and verify, the deployment is unhealthy
1618Retry later: another lifecycle run holds the lock, or Setup stopped before it changed anything (hook_calls_running, hook_in_use, codex_state_held or codex_requirements_held: hook calls still run, or a program holds the installed hook or a Codex file open), or a rollback met such a program after it started, or a Codex writer that keeps its transaction open (codex_state_unsettled): it left that one file or state as it is, restarted the restored services and ended with the transaction still pending (/repair finishes it; the services run)
1639Invalid arguments: a malformed command line (a relative CONFIG= path, an unknown property), or arguments the lifecycle rejected (/ensure without CONFIG= on a computer with no deployment, a config the gateway cannot load, a run enterprise.trust refuses). Retrying does not help
3010Reserved. The lifecycle never requests a restart

Setup properties use NAME=value; names are case-insensitive and ignore dashes.

PropertyMeaning
CONFIG=<path>The administrator config. Required for the first install; later runs reuse the installed config
MANIFEST=<path>A target manifest you publish. Required for /install and for enterprise.enrollment.mode: manifest
BUNDLE=<path>With /ensure: apply this signed policy bundle. With CONFIG= on a computer without DefenseClaw, Setup installs from CONFIG= with every service stopped, then applies the bundle and starts the services on it; if the bundle is not applied it removes that install and exits 1603. On an installed computer CONFIG= is then ignored
TRUSTANCHORS=<path>With /ensure and BUNDLE=: install this administrator-only bundle trust anchor file with the bundle. Not with CONFIG= alone
DEVICEGROUP=<group>With TRUSTANCHORS=: install the anchors pinned to this one device group, which must be one the file lists (or the file lists none). enterprise windows ensure --trust-anchors <file> --device-group <group> does the same
REFUSECAPABILITYLOSS=1With /ensure and BUNDLE=: refuse a bundle that turns off an enforced capability
ATTESTCLAUDEEFFECTIVEPOLICY=1With /repair: record the Claude Code attestation (Verify the install)
ALLOWEDSIGNERS=<sha256>,<sha256>Accept only these Authenticode signer thumbprints
JSON=1Print the result document on standard output
NOSTART=1Install with the services stopped and disabled (not_started warning); a later /repair starts them
PURGE=1With /uninstall: also remove each enrolled account's per-user data (Remove)
FORCE=1With /uninstall: remove the deployment without recovering a pending transaction
TIMEOUTSECONDS=<n>Lifecycle timeout, 60 to 7200, counted from when Setup starts. Default 1800. It also bounds the ensure Setup runs (Setup gives them what is left of the limit less a tenth, taking off at most 2 minutes), so a slow upgrade is no longer cut off at 12 minutes. A direct run of enterprise windows ensure with defenseclaw.exe keeps its 12-minute limit. A run that stops at the limit prints the retry command with the same properties and TIMEOUTSECONDS=7200. A standalone run stopped at the limit then recovers for up to 10 more minutes: allow TIMEOUTSECONDS plus 10 minutes. A run with less than about a minute of it left after the payload checks does not start the lifecycle and changes nothing, so a change (/install, /ensure, /upgrade, /repair, /uninstall) needs at least about 2 minutes (120); a lower value suits only /verify and /status

The other actions are /install, /upgrade, /repair, /reconcile, /status, /verify and /uninstall. Prefer /ensure; /install also needs MANIFEST=. /? lists the actions and properties. A property Setup does not know is refused with a hint that lists every property /? lists. A relative CONFIG= or --config path is invalid_arguments. /repair run from another release than the installed one is refused with invalid_arguments before it changes anything; it names the installed release, Setup /ensure to move to this release and /upgrade to go down. Prerelease versions order as semver does (rc.10 is newer than rc.9), in Setup, /ensure and the Intune detect script.

4. Add the AI Defense key

Without a key the local policy engine decides alone. To add Cisco AI Defense, set enterprise.inspection.ai_defense.enabled: true and credential: ai-defense-api-key in the config, run /ensure, then store the key from an elevated prompt. The deployment must be installed first:

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret set `
  --name ai-defense-api-key --from-file "$Stage\ai-defense.key" --json
Remove-Item "$Stage\ai-defense.key"

Rotation is in AI Defense key.

5. Add the LLM judge

The gateway service has no user environment, so it never reads llm.api_key_env. Name a protected credential in the config, run /ensure, and store the key the same way:

config.yaml (excerpt)
llm:
  model: bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0
  region: us-east-1
guardrail:
  judge:
    enabled: true
    hook_connectors: [claudecode, codex]
enterprise:
  profile: standalone
  inspection:
    llm:
      credential: llm-judge
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret set `
  --name llm-judge --from-file "$Stage\llm.key" --json

Until you store the key, status, verify and the Setup result warn credential_missing. The skill and MCP scanners use the same credential.

Verify the install

From an elevated PowerShell 7 session:

$Cli = 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe'
& $Cli enterprise windows status --profile standalone --json
& $Cli enterprise windows verify --profile standalone --json
Get-Service DefenseClaw* | Format-Table Name, Status, StartType
Output of Get-Service (captured on a standalone install)
Name                      Status  StartType
----                      ------  ---------
DefenseClawGateway        Running Automatic
DefenseClawHookEnumerator Running Automatic
DefenseClawHookGuardian   Running Automatic
DefenseClawSensorHelper   Running Automatic

status reports the state. verify also checks every file, permission, service and hook, and returns a nonzero exit code when anything fails. Healthy values:

FieldHealthy value
ok, errorstrue, empty
installed_versionThe version you deployed
readinessgateway, guardian, enumerator and sensor_helper all true
coverage_completetrue
security_completefalse with Codex or Claude Code enabled: the warning hook_process_fail_open says a stopped, killed or timed-out pre-tool hook can let a tool run (limits). true with only Cursor enabled. It needs Codex, Claude Code or Cursor enabled and, with Claude Code, an attestation
enrollment.targetsOne entry per user and connector. 0 means nobody is protected yet
policyapplied is true; effective_digest identifies the config (digest)

Add/Remove Programs lists Cisco DefenseClaw Enterprise, and the DefenseClaw event log has one entry per lifecycle run (event IDs).

A user's own status

defenseclaw status shows an account's own protection (its agents and Cowork) only in a PowerShell prompt that is not elevated. Setup puts no DefenseClaw command on PATH, so use the full path. Sign in as the standard account and run:

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' status

The & form is PowerShell's. In a Command Prompt (cmd.exe) quote the path with double quotes instead: "C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe" status.

An elevated prompt, and every prompt of the built-in Administrator account, gets the administrator's commands instead. From an elevated PowerShell prompt, check the deployment and one account's agents:

Elevated PowerShell prompt
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --profile standalone
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show --user <account>

Quote an account name that has a space or an apostrophe, as PowerShell does: --user 'John Smith', --user 'O''Brien'.

What Windows shows after an install

The four services run under Automatic start, and Add/Remove Programs lists Cisco DefenseClaw Enterprise. The DefenseClaw event log (Event Viewer > Applications and Services Logs > DefenseClaw) holds one entry per lifecycle run. An agent reads its hooks when it starts, so a session a user opened before Setup activated DefenseClaw runs uninspected until it restarts: the Setup result, status and verify name each one per user with the agent_sessions_restart_required warning. To look from an elevated prompt:

Elevated PowerShell
Get-Service DefenseClaw* | Format-Table Name, Status, StartType
Get-WinEvent -LogName DefenseClaw -MaxEvents 3 | Format-Table TimeCreated, Id, LevelDisplayName, ProviderName

Each message names the action and the result and ends with its record, for example DefenseClaw enterprise repair (standalone) ok=true exit=0 ... record <id>. The matching line of enterprise-lifecycle.log has the same record.

An event lists only the code of each error and warning (for example warning agent_unprotected (x2)), never its text. Any account can read the event logs, and the text can name other accounts, their SIDs, home folders and guardrail profiles. The text is in the lifecycle log line with the same record.

Each elevated lifecycle run appends its result to the lifecycle log. Every run except a healthy status or verify also writes an event to the DefenseClaw log and a copy to the Application log (source DefenseClaw Enterprise). The marker key and the Add/Remove Programs entry change only after a successful run, and they are for detection only. The event IDs are in Operate reference. To check that the entries are genuine, run enterprise windows events (Logs and events).

Claude Code attestation

On Windows, at least one of Codex, Claude Code or Cursor must be enabled, and no agent may be reported as agent_unprotected or hook_contract_unverified. With Claude Code enabled, an administrator must attest that Claude Code runs DefenseClaw's managed hooks:

  1. Install. security_complete is false at this point.

  2. In an enrolled user's own session, start Claude Code and have it make one tool call. From an elevated prompt, check that the gateway recorded it:

    & $Cli audit export --connector claudecode -o "$Stage\audit-claudecode.jsonl"

    $Stage is the administrator-only folder from step 2. The export can hold prompt and tool content. enterprise policy verify --live is not available on Windows.

  3. Record the attestation:

    & $Cli enterprise windows repair --profile standalone --attest-claude-effective-policy --json

    The Setup form is /repair ATTESTCLAUDEEFFECTIVEPOLICY=1 JSON=1.

DefenseClaw records the attestation as you give it; it does not run Claude Code. It is a repair, so it stops the four services and starts them again: for about a minute and a half every user's agents are refused (fail closed, enterprise_managed_gateway_not_running). Plan it in the same maintenance window as the upgrade it follows. The record is bound to the SHA-256 of the installed Claude Code policy file and of the hook binary, so every upgrade makes it stale and that proof becomes stale until you repeat steps 2 and 3. Computers on the same release and Claude Code contract have the same binding, so an MDM can check one reference computer and push the Setup form to the others.

This attestation proves the installed policy path. It cannot prove that the user's hook process will run to completion. With Codex or Claude Code enabled, status and verify continue to report security_complete: false and hook_process_fail_open after attestation: a stopped or timed-out pre-tool hook can still let the tool run without a DefenseClaw decision.

The guardian writes a user's registrations only while that user has an active (connected) session. status and verify also report agents the enumerator found but could not enroll (hook_contract_unverified, agent_unprotected; Enrollment). Each applies to one account: security_complete is false, but verify and MDM detection still pass while the machine policy remains complete. Configured Claude Code, Codex and Cursor machine hooks stay installed before the first enrollment and after the last enrolled user is removed. Even with zero enrolled users, an unenrolled account's hook calls are refused (Machine policy).

Review the audit log

Export the audit database from an elevated prompt, or as LocalSystem from an MDM script. The output file must not exist yet and takes the permissions of its folder, so write it where only administrators can read it. Omit --connector to export every row. Treat it as sensitive: it can hold prompt and tool content.

Elevated Administrator prompt
$Stage = 'C:\ProgramData\DefenseClaw-Staging'   # administrator-only, from step 2
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' audit export --connector claudecode -o "$Stage\audit-claudecode.jsonl"

Standard accounts cannot read the managed audit log. A call refused because the account is excluded or not enrolled yet is in the export too: a hook_decision row and a connector-hook row with action block, the account's SID and name, and reason enterprise_managed_sid_unregistered or enterprise_managed_enrollment_pending. The gateway takes the account from the Windows token of the refused process. Repeated refusals of one account and agent are one row a minute.

A command defenseclaw.exe refuses an account is in the export as well: the setup, upgrade, rollback, config set and config unset answers, the guardrail writers, skill, mcp, plugin and tool block, allow and unblock, and a standard account's enterprise windows lifecycle commands and enterprise secret set or remove. Each is an action row whose target is the command, with outcome=refused, the reason (managed_device, or elevation_required for a command only an administrator runs), the account's SID and name, and the number of attempts. The gateway takes the account from the Windows token of the refusing process, and repeated refusals of one account and command are one row a minute. Arguments are never recorded.

Review AI Discovery

With ai_discovery.enabled: true in the config, the gateway scans each user profile for AI agents, skills, MCP servers, plugins and running AI processes and sends the result to your observability destinations (AI Discovery). Read the inventory on the computer from an elevated prompt:

Elevated Administrator prompt
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows discovery
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows discovery --user <account> --json

--user takes the bare account name, COMPUTER\name, .\name, DOMAIN\name or the SID. The gateway attributes each runtime finding to the account that runs it (process_owner, session or enrolled_profile); a finding none of these names is attribution: unattributed and is host-wide. The destinations get ai_component.discovered, changed and removed records with the user but without the skill or MCP name; read names with discovery --user <account> --json. The ai_discovery.runtime.acquisition key is not available on Windows (config_schema_invalid), and enterprise.tetragon is accepted and ignored.

Scan skills, MCP servers and plugins

The LocalSystem gateway skips enrolled users' profile roots. Install admission applies to skill, plugin and MCP server roots outside profiles that the gateway watches. Assets in profiles are judged at the hook, from their content: set asset_policy.enabled: true, asset_policy.skill.runtime_detection.enabled: true and asset_policy.plugin.runtime_detection.enabled: true (MCP runtime detection already defaults to true) and asset_policy.mode: action. The hook reads the skill folder the request selects (Claude Code, Codex and Copilot CLI, under the skill roots of each, for Copilot CLI including .agents\skills, COPILOT_HOME and COPILOT_SKILLS_DIRS), and the Claude Code plugin it belongs to (including a plugin installed from a local marketplace folder and the tools of its bundled server), as the user, following links as the agent does. The gateway scans that text with the in-process prompt-injection detector and refuses the call when it holds an instruction that overrides the role or instructions of the agent, a fake system or delimiter block, base64-hidden instructions or tag characters, rated HIGH or CRITICAL (profile-asset-verdict), whatever the guardrail mode is, so a skill created while the gateway was stopped is judged the first time it is used. A skill or plugin the hook found but sent no text for, or could not read in full (a file past 64 KiB, more than 64 files, a link that leads nowhere readable, text that is not UTF-8), is refused (profile-asset-unscanned): a verdict on part of an asset is not a verdict on it. So is a skill folder the hook found but could not read, a plugin the registry gives no folder for (missing, unreadable, or larger than the 4 MiB the hook reads), and a tool of a plugin's bundled server whose owner no plugin content names. A tool name that several installed plugins could own (plugins p and p_a for a server p_a_b) is judged on the text of each of them, each up to the per-file (64 KiB) and escaped-text (96 KiB) caps, so up to 23 candidates keep their whole text even when it does not shrink; only a single candidate past those caps is marked truncated and refused. Verdicts are cached by content digest. Ordinary skills and plugins are not refused, and nothing changes while asset_policy.enabled is false or the mode is observe. The text is the hook's claim and the detector is the in-process one: the skill-scanner and CodeGuard are not run on profile assets, and a profile asset still gets no install scan or quarantine. Hooks refuse denied names regardless. Windows status and verify do not warn when a default or registry rule goes unenforced; the gateway log is the only signal. Keep shared skills outside profiles. A profile asset is never admission-blocked or quarantined. Ordinary project skill folders inside profiles are not watched or admission-scanned and do not receive an "is not scanned yet" refusal. At hook time, a project skill folder reached through a link outside the caller's profile, or writable by another user, is reported as unverified. The gateway logs the folder, /health counts it in project_skill_roots_unverified, and enterprise status shows a project_skill_root_unverified warning. A selected skill under an unverified root is refused in every asset policy mode until a fresh caller inspection verifies that the root is ordinary. The same holds for the selected skill itself: when its SKILL.md is a link (symbolic link or junction) to a file outside the caller's profile or below a folder another user can write, or a hard link, the call that selects that skill reports the root with the SKILL.md reason and the Skill call is refused; a link to a file the caller holds privately in the profile is the caller's own skill and loads. A hard link is reported because the hook cannot tell where its other names are. Watcher rows for roots outside profiles carry no per-user attribution. The scan and scan-finding rows of a scan skill or scan plugin run of the installed defenseclaw.exe on an asset in an enrolled user's folder name that user (user.id, defenseclaw.user.name), and the judge model when the judge ran (gen_ai.request.model, judge= in the scan row details).

A relative COPILOT_SKILLS_DIRS entry is read below the folder Copilot was started in. The hook reads that folder from the working folder of the Copilot process (Windows and Linux) and then uses it as the only root, whatever the event folder is, so a skill of another folder that the agent does not load never decides the call. When the hook cannot read it, it takes the event folder or the outermost repository (or home) above it, never a folder in between.

  • Verdicts. A level whose admission.<type>.actions is block blocks the asset and leaves its folder in place (file_action=none). quarantine copies the asset to C:\ProgramData\Cisco\DefenseClaw\runtime\quarantine (<type-dir>\<connector>\<name>, or a per-source slot when the name is taken), verifies the copy, then removes the source.

  • Failed scans. A skill or plugin scan that fails blocks and disables the asset. For MCP servers whose scan did not finish, the balanced scanners.mcp_scanner.unverified_server: warn setting keeps the server with a warning and an audit record; unverified_server: block refuses and disables it. A scanner refusal of an unsafe server definition still blocks. A quarantine that cannot finish leaves its asset blocked in place. The gateway retries after 2 minutes, then 4, up to every 30 minutes, and status and verify warn asset_not_scanned or asset_not_quarantined.

  • Signed-out owners. When the source of a quarantine is in the profile of a user who is signed out and Windows gives no S4U logon for the account, the copy is in quarantine and blocked, but the hook guardian removes the original folder only when that user next signs in. Until then status and verify warn asset_removal_deferred, naming the folder and why the guardian waits (a Microsoft Entra ID account, an Active Directory account whose S4U logon was refused, or a local account).

  • take_action: false. A rejected asset is only recorded and stays usable until take_action is on again; then asset_rejected_not_enforced warns.

  • admission.mcp.scan_on_install: false admits new MCP servers without a scan (reason=scan-disabled).

  • Loopback and private MCP URLs are never scanned. The scanner does not connect to loopback, private, link-local or multicast addresses, so an HTTP or SSE server there is blocked (install-scan-error). Stdio servers are unaffected. To admit a server you trust, pin it by name and URL:

    Admin config
    asset_policy:
      mcp:
        allowed:
          - name: notes
            url: http://127.0.0.1:28561/mcp
            reason: reviewed internal server
  • Launchers. A stdio server the gateway starts is scanned only when its npx or uvx is installed for all users in a folder only administrators can change (for example C:\Program Files\nodejs). A launcher in a profile fails the scan (MCPStdioLaunchError ... untrusted Windows path).

  • Claude Code, Kiro and Codex state files. The hook enumerator reads .claude.json, each project's .mcp.json, .kiro\settings\mcp.json, and Codex .codex\config.toml and the config.toml under the user's persistent CODEX_HOME, and publishes their servers to the gateway every 30 seconds and before each MCP tool call. If it cannot read or parse the file, the user's MCP tool calls are refused and status warns claude_state_unreadable, kiro_mcp_unreadable or codex_mcp_unreadable. A project's .mcp.json is opened with the enrolled user's token, from the signed-in session, which can be a disconnected one. A project that user cannot open (access denied) is skipped and its servers are not published; the other projects are unaffected. If the enumerator cannot obtain the token, it reports the state as unreadable and publishes no inventory for that user.

  • Plugins in profiles. A Claude Code plugin from a local marketplace runs from its folder and is not watched. A matching asset_policy.plugin.denied rule still makes the hook refuse it with ASSET-POLICY reason_code=admin-deny source=admin-deny asset_type=plugin asset_name=<plugin>. MCP servers a plugin bundles are admitted with it; asset_policy.mcp rules name them plugin:<plugin>:<server>.

  • A watcher with no folders. When every skill and plugin folder is in a profile, the watcher starts with none: its audit row reads watcher ready: dirs=0 and defenseclaw-gateway status --json reports it degraded with profile_roots_skipped: true. That is expected, not a failure. The watcher does not scan or quarantine a skill or plugin in a profile; the start of this section says what the hook applies to profile assets. For install admission of a shared folder, set gateway.watcher.enabled: true and gateway.watcher.skill.enabled: true (or gateway.watcher.plugin.enabled: true), add take_action: true to enforce the verdict, and list a folder outside profiles in gateway.watcher.skill.dirs (or gateway.watcher.plugin.dirs). Claude Code and Kiro MCP servers in profiles are admitted either way (MCP servers in user profiles).

MCP servers in user profiles

An enrolled user's Claude Code, Kiro and Codex MCP servers (Claude Code user and local scope and a project's .mcp.json, Kiro user scope, Codex user scope) get an install scan and an admission decision like any other server. The scanner runs in the gateway service, so the user cannot change its verdict. Only the server's own process runs as the user:

  • The hook enumerator starts it with the user's session token through the Secondary Logon service (seclogon). The gateway never starts a user's server with its own rights.
  • It starts only the definition it published, and only when the gateway is scanning that one.
  • Only npx or uvx with a package argument and no code-running flag. The launcher must be installed for all users under Program Files; one in the profile, or an earlier same-named file on PATH, is refused.
  • A definition the scan refuses for its own launcher (not npx or uvx, a command path, a code-running flag, no package argument) stays blocked and is not scanned again until the definition, the scanner or the admission settings change, or an allow rule admits it. Its tool calls are refused with that reason. Any other failed scan, including a launcher refusal that comes from the computer's PATH, is retried after 2 minutes, doubling to 30. An administrator unblock of a refused definition stays until the definition changes.
  • The working directory must be on a local fixed drive, inside the project or the user's own profile, in no other user's profile, with no link or junction on the way. Otherwise the scan fails with the reason.
  • It runs hidden in a job that ends every process after at most five minutes, in session 0 on a desktop only that user and LocalSystem can open. A server that needs the interactive desktop or clipboard fails its scan and stays blocked.

A user who is not signed in has no session token: their servers stay blocked until they sign in, and are scanned again within about 30 seconds. If seclogon is disabled, set it back to Manual. MCP servers of other connectors in a profile, and Codex project .codex\config.toml files, are not published and get no install scan (see below for what the gateway does with a Codex project server).

Codex reads one user config.toml: the one under CODEX_HOME when that is set, otherwise .codex\config.toml. The enumerator publishes only that file for the account, so an old definition in the unused file never replaces the one that runs and an unreadable unused file does not block the account. CODEX_HOME counts when it is set for the account (the user environment); one set only for a session is not seen by the enumerator, and the gateway refuses a call to a Codex server defined in that file until the same definition is published (mcp-source-unpublished). The hook sends a digest of the whole definition (URL, command, every argument and the environment), and the gateway compares that digest with the published server, so a definition that differs in an argument past the 32nd, in a long URL or in the environment is not taken for the scanned one. A Codex project .codex\config.toml takes precedence over the user file, but only for a project the user config trusts ([projects."<path>"] trust_level = "trusted"); an untrusted project file is ignored by Codex and by DefenseClaw. A trusted project server is not published: it is refused the same way when it would override a published server of that name, when asset policy is enabled in action mode (the mode of the connector counts) with MCP runtime detection on, or when its definition is too long for the hook to send and an asset_policy.mcp.denied rule that pins an endpoint may match it (the hook sends a digest of each value such a rule compares, so a deny pinned to another URL, command, arguments or transport does not refuse it; the first 2,048 arguments are digested in full and the next 65,536 by an 8-byte digest, so only a deny prefix that reaches past the 67,584th argument cannot be ruled out, and it refuses the call); otherwise it keeps running as before. When the user config marks a folder trusted and a project below it untrusted, the entry nearest the project decides.

Release a blocked or quarantined skill

Standard users cannot release an asset, and skill enable and skill restore are not available. After review, add an allow rule to asset_policy in the admin config, pinned to its watched folder outside profiles or, without source_path_contains, for every matching copy. This example assumes the folder C:\ApprovedSkills\<account> is listed in gateway.watcher.skill.dirs:

Admin config
asset_policy:
  skill:
    allowed:
      - name: reviewed-skill
        reason: reviewed by security
        source_path_contains: ["C:\\ApprovedSkills\\<account>\\reviewed-skill"]

Replace <account> with the folder you list for that user and reviewed-skill with the skill's folder name.

For a Claude Code plugin from a marketplace use asset_policy.plugin; an allow rule needs plugin@marketplace (the name claude plugin list shows), and a deny rule also matches the bare name. To lift a hook refusal of a profile skill denied by name, change its asset_policy.skill.denied rule.

  • A blocked skill still in its folder is released at the next rescan (watch.rescan_interval_min, 60 by default), or at once when it is copied into the watched folder again (install-allowed reason=allow-listed).
  • A quarantined skill keeps its copy under runtime\quarantine\skills. After you add the rule, copy the folder back into the watched folder from an elevated prompt. To purge copies, delete their folders under runtime\quarantine.

An administrator scans a folder or remote MCP server with the same scanners, policy and judge. The gateway reads the folder as LocalSystem and refuses any folder inside a user profile, so copy what you want to scan to a folder outside profiles such as C:\DefenseClawReview. That refusal (HTTP 403) prints the Copy-Item and scan commands for the folder. Standard accounts cannot run managed scans. Variables like SKILL_SCANNER_LLM_MODEL in your shell are ignored.

Elevated Administrator prompt
$Cli = 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe'
& $Cli scan skill 'C:\DefenseClawReview\my-skill'
& $Cli scan mcp https://mcp.example.com/mcp
& $Cli scan plugin 'C:\DefenseClawReview\my-plugin'

Inspect machine policy

Run from an elevated prompt or as LocalSystem. Standard accounts are told to use an elevated prompt.

Elevated Administrator prompt
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy verify

show lists each connector's route, lock and coverage. verify exits 1 while coverage is incomplete. A missing machine policy is a protection failure, even with zero enrolled users: stop the affected agent with application control, fix the reported cause, and from an elevated PowerShell prompt run one of:

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

Then rerun enterprise policy verify as above. A missing hook executable is also a protection failure for Claude Code, Codex, Cursor and Copilot while their machine policy files stay installed. Stop affected agent use, repair the installation, and require the full enterprise windows verify --profile standalone --json check to pass before allowing agent use. With managed_hooks_only: enforce (the default) the Claude Code drop-in C:\Program Files\ClaudeCode\managed-settings.d\90-defenseclaw.json sets allowManagedHooksOnly: true. Claude Code applies drop-ins in name order, so a later file that sets it to false turns the lock off; policy verify and enterprise windows verify report that file. policy verify --live is not available on Windows. To see the hooks run, make a tool call from the user's session and read it with audit export.

On a managed Windows test host, a standard user could create a private DOS device map, but the tested map did not change a fresh read of the installed Codex policy. This does not establish how every agent behaves under every process-local view. status and verify inspect stored policy and cannot by themselves prove that every agent process loaded its hook; compare a native tool call with the gateway audit when validating this boundary (W-63).

Recover a pending transaction

A lifecycle that fails normally rolls back. If the rollback cannot finish, the transaction stays pending: the result reports transaction_pending: true and names the services that stay stopped. status shows it and verify refuses until it is recovered. While the gateway is stopped, users' agents block with enterprise_managed_gateway_not_running, and the block asks them to have an administrator run enterprise windows status. Starting a service by hand does not recover it.

A run that hits TIMEOUTSECONDS (lifecycle_timeout) is stopped, and Setup then runs one recovery of its own, limited to 10 minutes, that replays the pending transaction. The run still fails. When no lifecycle record is left, its result is the recovered deployment's status, with transaction_pending: false. When the recovery cannot prove that, the error names what is left (for example a purge or install-rollback intent), and the run below recovers it.

Every lifecycle stops the DefenseClaw services before it changes anything. A service process that does not answer the stop request within 30 seconds (a hung or suspended process) is ended the way Windows ends a stuck stop, and the lifecycle continues. The result names each such process in a service_process_terminated warning.

An uninstall that is refused or fails after it started, and rolls back, removes the managed-hook teardown journal it wrote (C:\ProgramData\Cisco\DefenseClaw\install\managed-hooks-teardown-journal.json). The next uninstall removes one that an earlier build left and says so in a stale_lifecycle_journal_removed warning. Without that, a later config change could make the uninstall fail with "managed-hook teardown journal does not match the protected deployment".

Recover by running Setup as LocalSystem (Intune install behavior System). /ensure recovers the transaction then installs or upgrades; /uninstall recovers it and removes the deployment:

As LocalSystem
DefenseClawSetup-Enterprise-Standalone-x64.exe /ensure CONFIG=C:\ProgramData\DefenseClaw-Staging\config.yaml JSON=1
DefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall JSON=1

/repair also recovers it but then stops with "run Install" after a failed first install, so /ensure is the one-step command. The recovery restores the release that ran before the interrupted change; if the CLI that recovered it is that older release, the result warns recovered_pending_transaction: run the newer Setup /ensure again. If the staged gateway cannot finish the rollback, the lifecycle may retry once with the gateway in the running Setup's payload, and reports recovery_gateway_fallback, recovery_gateway_not_used or recovery_activation_deferred. Do not edit DefenseClaw files by hand.

The installed CLI can also refuse a cut-off upgrade outright, when it stopped between the installer and the module, forward or during its rollback ("module SHA-256 does not match the pinned payload manifest"). Run that release's Setup /ensure; see the troubleshooting entry.

If no recovery finishes, fix what its error names, then as the last resort remove the deployment without recovering the transaction and install again:

As LocalSystem, last resort
DefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall FORCE=1 JSON=1
DefenseClawSetup-Enterprise-Standalone-x64.exe /ensure CONFIG=C:\ProgramData\DefenseClaw-Staging\config.yaml JSON=1

FORCE=1 moves C:\ProgramData\Cisco\DefenseClaw aside, removes the services, C:\Program Files\Cisco\DefenseClaw and the machine-wide hook files, then deletes the moved folder, with forced_uninstall and, if that fails, forced_state_root_kept warnings. If a process holds a file open, Setup fails, moves everything back and restores the services. Per-user registrations are listed in the result. Keep C:\Windows\Logs\DefenseClaw\enterprise-lifecycle.log for support.

Other recovery notes:

  • A hardening script that removes NT SERVICE\DefenseClawGateway from runtime or etc stops the gateway from starting. repair, /ensure, /uninstall and recovery put the deployment's permissions back. A redaction correlation key another account can open is refused before any service stops.
  • A file another program holds open stops the repair of that file. Before Setup puts back the access list of a recorded file (config.yaml, targets.yaml, deployment.json, the Codex requirements.toml and its records), it holds the file so that no other program can write or delete it, checks that it has one link and judges it. If a program already holds it open with write or delete access, or without sharing read access, /repair and /ensure refuse that file by name and change nothing on it, not even its access list. Close the program that holds it (a user's agent, an editor), then run Setup /ensure again. A file that already has the canonical access list is not written, so a holder does not matter for it. For the Codex requirements.toml and the Codex state file of 1.0.8, Setup checks before it stops any service: a program that holds either one without read sharing, requirements.toml without delete sharing, or requirements.toml with write or delete access while its access list has to be written, stops the run after 30 seconds with codex_requirements_held or codex_state_held (exit 1618) and the program's name. Nothing is stopped or changed, and the same command succeeds once the program lets go. A Codex state copy (.defenseclaw-managed-hooks.state.<n>) that a user holds open is neither refused nor changed behind the holder. When it is the current copy and the holder denies read sharing, the next Codex transaction publishes a fresh copy under a new name so that the hook and the guardian can read the state; the held copy stays until it is released. A program that opens one of those two files after that check and does not share delete access cannot be kept out of the rest of the run. If the run then fails and rolls back, Setup waits 30 s for that file to be released, then leaves it as it is, puts the rest back and starts the restored services, and ends with the same codex_requirements_held or codex_state_held (exit 1618) naming the program and its process id, and with the failure that started the rollback. The transaction stays pending, and the next /repair as LocalSystem, after the program lets go, finishes the rollback. The previous hook is handled the same way (hook_in_use). A file left this way can be out of step with the restored release (a newer requirements.toml beside the older state copy, or the replacement hook or the closed hook guard where the previous hook belongs). A Codex agent can then be blocked until /repair runs; that is fail closed by design. When the held file is the requirements.toml the recovery had to republish, the result also says the guardian's coverage was not proven by that rollback. A recovery that restores a requirements.toml an administrator edited in the managed policy publishes the managed policy again instead of stopping, keeps your file under install\recovered-policy and warns codex_requirements_replaced; /uninstall FORCE=1 is not needed for it. Programs that only read the file, such as an antivirus scan, do not stop it. Setup stamps the gateway's own database and log files, which the running services keep open for write, without that hold. The repair the gateway runs on its database files refuses only a program that holds them with delete access or without sharing read access.
  • If Setup /repair refuses because the running gateway's installed config cannot be validated for rollback, restore an approved, gateway-valid config.yaml and retry /repair. If the refusal names an administrator-selected policy, rule-pack or JSONL path that Repair does not restamp, correct its permissions and the gateway service account's access before retrying. Repair restores ACLs on its installed config, runtime root, bundle store and protected credential store; it leaves those administrator-selected paths in place. When deployment.json is readable, Setup /ensure CONFIG=<approved config> can replace the invalid installed config. All paths are checked again after Repair restores its managed permissions.
  • A runtime file the lifecycle cannot open at all keeps its permissions and is named in a runtime_file_skipped warning. The audit database and the redaction correlation key are never skipped.
  • The rollback never deletes content in an account's %USERPROFILE%\.defenseclaw it cannot prove DefenseClaw wrote; it renames the folder to .defenseclaw.rollback-<random>. Review and delete that folder.
  • A signed-out account whose .defenseclaw or hooks folder has the wrong owner or permissions is skipped with a user_runtime_folder_untrusted warning and repaired at its next sign-in.
  • For a signed-out account the rollback of a failed first install uses a service-for-user (S4U) logon: a local account always, a domain account when a domain controller answers. Set DEFENSECLAW_WINDOWS_ROLLBACK_SIGNED_OUT_ACCOUNTS=0 to skip signed-out accounts. No guardian is left to clean an account later, so the result lists each item it could not remove as a rollback_leftover warning, by account and connector, with the command that removes it.
  • The rollback of a failed first install acts as each account, which needs LocalSystem, and lists leftovers as rollback_leftover warnings. Setup run from an elevated administrator prompt cannot act as accounts, so run /ensure and /uninstall as LocalSystem while accounts have a connected session.

Recovery gateway refusal codes

When the staged gateway fails a managed-hook step, recovery may rerun it with the gateway that ships beside the running Setup. If recovery declines, the result has a recovery_gateway_not_used warning with one of these reasons, and the staged gateway's error stands:

ReasonMeaning
no_payloadNo gateway ships beside the running Setup
unsigned_scopeThe run is a certification run, not a production one
not_local_systemThe lifecycle does not run as LocalSystem
inside_install_rootThe candidate is the installed payload
untrustedThe candidate fails the source or trust checks (an administrator-owned source on a local NTFS volume, and a valid signature or the pinned SHA-256)
same_binaryThe candidate is the staged gateway that already failed
version_unknownThe release of the candidate or of the staged gateway cannot be read
older_releaseThe candidate is older than the staged gateway

A failure that concerns file permissions is reported in plain terms. The internal detail is kept in a lifecycle_diagnostic warning for support.

Run Setup as LocalSystem

Without an MDM, a one-time scheduled task gives LocalSystem. Run Setup from the administrator-only staging folder, never from a folder a standard user can write: the task runs whatever file is at that path as SYSTEM.

Elevated PowerShell
if ((Get-Acl $Stage).GetOwner([Security.Principal.SecurityIdentifier]).Value -ne 'S-1-5-32-544') {
    throw "$Stage is not owned by Administrators; create it as in step 2"
}
Copy-Item .\DefenseClawSetup-Enterprise-Standalone-x64.exe $Stage
$Setup  = "$Stage\DefenseClawSetup-Enterprise-Standalone-x64.exe"
$Result = "$Stage\setup-as-system.json"
$Log    = "$Stage\setup-as-system.log"
$Task   = 'DefenseClaw Setup as SYSTEM'
$Action = New-ScheduledTaskAction -Execute "$env:SystemRoot\System32\cmd.exe" `
    -Argument "/d /c `"`"$Setup`" /ensure CONFIG=$Stage\config.yaml JSON=1 > `"$Result`" 2> `"$Log`"`""
Register-ScheduledTask -TaskName $Task -Action $Action -User 'NT AUTHORITY\SYSTEM' -RunLevel Highest -Force | Out-Null
Start-ScheduledTask -TaskName $Task
$Shown = 0
do {
    Start-Sleep -Seconds 5
    $Lines = @(Get-Content $Log -ErrorAction SilentlyContinue)
    $Lines | Select-Object -Skip $Shown
    $Shown = $Lines.Count
} while ((Get-ScheduledTask -TaskName $Task).State -in 'Queued', 'Running')
(Get-ScheduledTaskInfo -TaskName $Task).LastTaskResult
Unregister-ScheduledTask -TaskName $Task -Confirm:$false
Get-Content $Result

LastTaskResult is Setup's exit code. For /uninstall, replace /ensure CONFIG=$Stage\config.yaml with /uninstall. After the services are back, Setup prepares the scanner runtime, which takes seconds to a few minutes and at most 15. On timeout Setup fails with 1603 and scanner_runtime_unavailable ("timed out after 15m0s"): DefenseClaw is installed and running, but watched assets that require a scan stay blocked until a /repair finishes the unpack. The prepare is CPU work, so a burstable cloud VM (Azure B-series, AWS T-series) out of CPU credits can reach the bound; run /repair JSON=1 as LocalSystem again when the computer has CPU to spare.

Per-user installs

On a computer with the standalone deployment the per-user product refuses to run:

Per-user actionWhat happens
install.ps1Refuses when the marker key exists, or when DisableSelfUpdate under HKLM\SOFTWARE\Policies\Cisco\DefenseClaw is nonzero
defenseclaw upgrade, defenseclaw rollbackRefuse when the marker key exists
Per-user gatewayRefuses to start on a managed computer. defenseclaw-gateway stop, start and restart refuse there too; the message names status and the installed CLI's enterprise windows repair --profile standalone, each by its full path, as the way to restart the managed gateway

After the managed deployment is removed, a user can install the per-user product. Its first defenseclaw init moves the files a managed install left in %USERPROFILE%\.defenseclaw (an uninstall before 1.0.8 kept them, with the managed access list) to %USERPROFILE%\.defenseclaw-managed-leftovers-<UTC time> and says so in the Managed leftovers row. It never reads or reuses them. It moves only entries that still carry the managed access list (Administrators full control, the account Modify only), never one with the profile's own access list or one another account can write, and it moves nothing once the folder has a config.yaml, .env or audit.db. Delete that folder when it is no longer needed. If an entry cannot be moved, init names it: move it out of the folder, or have an administrator delete it, and run defenseclaw init again.

Nothing migrates a per-user install. Before you deploy, have each user run defenseclaw uninstall --all --binaries --yes. If a user set up Claude Cowork, they also remove the DefenseClaw plugin in Claude Desktop (Customize > Plugins, then the ... menu on DefenseClaw, Remove); until then Cowork tool calls are blocked. Setup needs --all: it does not adopt a %USERPROFILE%\.defenseclaw folder a per-user install left, and a first install checks every enrolled profile and stops in seconds, naming the folder and this command. A folder the account created itself without a per-user product is taken over. A link or junction the account made at that folder, or at its hooks folder, is moved aside when the account enrolls, without opening what it names, and the folder is created. Until that account signs in it stays pending, not protected: status names it in enrollment_pending_account_link, and Upgrade and Repair leave it pending and finish for the other accounts. A first install still stops before it changes anything, naming the link. Releases before 1.0.6 refuse that account instead, and every later Setup run on the computer stops with lifecycle_error naming the link. A link at that folder that the account does not own, such as one an administrator made, is never followed or moved aside: Setup leaves that one account out, finishes for the others, and status names it in enrollment_skipped_account_link until an administrator removes the link. In every case remove the link (rmdir on a junction removes only the link) and run Setup again. A running per-user gateway holds the API port, and Setup names it in api_port_held. See Uninstall and preserved state.

Remove

With Setup, or with the installed CLI:

& .\DefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall JSON=1
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows uninstall --profile standalone --json

Uninstall removes DefenseClaw's hook registrations and machine-policy entries (for GitHub Copilot, the policy.d drop-in and enabledPlugins["defenseclaw@defenseclaw"] in %ProgramFiles%\GitHubCopilot\managed-settings.json), the four services, the binaries, and the machine state under C:\ProgramData\Cisco\DefenseClaw (config, secrets, data and service logs). From each enrolled account whose registrations it removed it also removes the files the managed runtime wrote in %USERPROFILE%\.defenseclaw (see Per-user runtime files below); the account keeps its other files there and the per-user binaries. Add PURGE=1 to Setup or --purge to the CLI to remove those too. The marker key, the Add/Remove Programs entry and a DisableSelfUpdate value the lifecycle wrote are removed, and the lifecycle log stays. Once nothing of the deployment is left, uninstall also removes the vendor folders DefenseClaw created, such as C:\ProgramData\Cisco, C:\Program Files\Cisco, C:\ProgramData\Cursor, C:\ProgramData\OpenAI\Codex and C:\Program Files\ClaudeCode, if they are empty. A folder that existed before the install, or that holds another program's files, stays, and so does every folder above it. Setup records each folder it creates in C:\ProgramData\Cisco\DefenseClaw-Lifecycle\created-folders. A folder is removed only while it is still administrator-owned and only administrators can change it or its parent; a folder that stays keeps its record, so the next purge tries again. The JSON result names it with the reason (a created_folders_kept warning), and so does the lifecycle log. If a link or junction sits at one of these vendor folders or on the path to one, for example a user made one at C:\ProgramData\Cursor after the folder was removed, or an administrator made C:\ProgramData\OpenAI\Codex a junction to another folder, the uninstall does not follow it, change it or remove it, and does not stop for it. Nothing behind the link is read, opened, locked, written or deleted, even a file that looks like DefenseClaw's own, such as a Codex requirements.toml or a writer lock. The link and what it points to stay as they are, the link is named once in a machine_state_kept warning (and in created_folders_kept when DefenseClaw had recorded the folder), never as a file the uninstall could not remove, and the rest of the uninstall completes. This holds when an account is enrolled for that agent too: the uninstall cannot read the enrollment behind the link, so it leaves that agent out of the checks that compare the enrolled accounts with the machine state, and out of the check that waits for the guardian to reconcile without failure (the guardian does not write through a link). A mismatch that no kept link explains still stops the uninstall. The machine policy folders DefenseClaw writes itself for GitHub Copilot, OpenCode and Devin under C:\ProgramData are the one difference: a link a standard user made there is removed, the link only, and nothing is created in its place (what it points to is untouched), while a link an administrator made stays and is named. Each path is decided on its own: a link at one of Devin's two folders (Devin, or the folder the app used before it was renamed; see Renamed and removed connectors) keeps that folder, and DefenseClaw's entry in the other one is still removed. Only the uninstall keeps a link at the Codex folder, and it reports it as kept and not verified: because nothing behind the link is read, a Codex requirement there may still name the DefenseClaw hook program that the uninstall removes, so check the policy behind a link you made. Install, ensure, repair, the reconcile that turns Codex off and the guardian's Codex removal stop with an error when a link sits at a vendor folder, except that a link a standard user made at the Copilot, OpenCode or Devin policy folder is removed first. A newer Setup that uninstalls a deployment from before 1.0.9 runs that deployment's own gateway, which does not keep a link: there a link at the Codex folder behaves as it did in that release (the uninstall stops with an error). Releases before 1.0.9 kept no record. On a computer installed with one of them, the first 1.0.9 install, upgrade or repair records C:\Program Files\Cisco and C:\ProgramData\Cisco when they still have the permissions Setup gave them and hold only DefenseClaw folders. It records C:\Program Files\ClaudeCode\managed-settings.d, C:\ProgramData\Cursor, C:\ProgramData\OpenAI\Codex and C:\ProgramData\ampcode only when all three hold: the folder was created after C:\ProgramData\Cisco\DefenseClaw, it has exactly the permissions DefenseClaw creates it with, and it holds only DefenseClaw's own files (ampcode must be empty: 1.0.2 through 1.0.6 create it empty, and 1.0.7 and later add an ownership marker when they create it). ClaudeCode and OpenAI follow when their only child is recorded. Setup checks these folders once, on the first install, upgrade or repair after the upgrade; a folder an administrator makes later and Setup adopts is never recorded. The check counts as done when every folder was recorded or failed one of the three conditions; if a record cannot be written, the next install, upgrade or repair checks again. A rollback does not reset the check. A folder that fails any of these stays after a purge, and the purge names it once as "left in place: not provably created by DefenseClaw" when DefenseClaw had written a file or a folder into it. Such a record only lets a purge remove an empty folder; it never makes DefenseClaw treat the folder as its own. A folder that holds anything that looks like Secure Client is never recorded or removed. A standalone Setup uninstall removes the administrator-only C:\ProgramData\Cisco\DefenseClaw-Lifecycle\lifecycle.lock and its directory even without PURGE=1. A plain installed CLI uninstall leaves the lock file and its folder in place (without --purge). They are harmless and the next install reuses them; to remove them, delete C:\ProgramData\Cisco\DefenseClaw-Lifecycle from an elevated prompt once no DefenseClaw run is active. The Secure Client profile keeps the lock unless PURGE=1. The Claude Code settings cleanup keeps a folder in the profile of the account that runs it: C:\Windows\System32\config\systemprofile\AppData\Local\DefenseClaw\claude-settings-teardown for the guardian and a Setup uninstall. Once a cleanup ends, the folder holds one empty lock file. The guardian removes that folder, and the empty DefenseClaw folder above it, after each pass. A standalone uninstall removes the copy of the account that runs it, with or without purge. A folder that still holds an unfinished cleanup stays, and the result names it in a machine_state_kept warning. On a computer without DefenseClaw, uninstall succeeds and changes nothing, so it does not remove a lock an earlier uninstall left.

  • A standalone uninstall first runs a read-only check of the hook teardown (guardian, enrollment and runtime selectors). If the check refuses, DefenseClaw stays fully installed and the result names what to repair. Repair it, then uninstall again.
  • Run the CLI uninstall with defenseclaw.exe; other installed binaries refuse it (1639). If an uninstall committed but could not finish, run Setup again as LocalSystem with /uninstall JSON=1 (and PURGE=1 if the original was a purge).
  • While a program runs a DefenseClaw executable from bin, /uninstall fails with uninstall_in_use before it stops any service, naming the program, process and account. With PURGE=1, a program holding a file open in C:\ProgramData\Cisco\DefenseClaw (a SIEM forwarder reading runtime\audit.db, for example) blocks it the same way. Close it and run again. The Intune launcher's uninstall retries and then exits 1618.
  • privileges_required means the uninstall needs an account that can list and remove a file or folder inside DefenseClaw's own folders that only SYSTEM may open, and the Administrator that ran it cannot. An elevated Administrator holds the backup and restore privileges disabled, and Setup turns them on for one walk at a time, so it normally just works; the error appears when the account's token does not hold them at all (a policy removed them, or the account is not an Administrator). Nothing was changed and the services keep running (or the message says the uninstall can be run again). Run the same uninstall as SYSTEM: an MDM or Intune run already is; by hand, start Setup from a scheduled task that runs as SYSTEM, or with psexec -s.
  • A file or folder under C:\Program Files\Cisco\DefenseClaw that DefenseClaw did not install stops a standalone uninstall with 1603 before it changes anything, and the result names that item, also inside the lib\defenseclaw folder that 1.0.2 installed (for example lib\defenseclaw\operator-note.txt). Move it out of C:\Program Files\Cisco\DefenseClaw, then run the uninstall again.
  • A junction or symbolic link inside C:\ProgramData\Cisco\DefenseClaw (for example at secrets) is removed as a link before the uninstall changes that folder, and never followed: the folder or file it points to keeps its content and permissions, and the log names each link removed. A link at C:\ProgramData\Cisco\DefenseClaw itself, or one Setup cannot remove, stops the uninstall with 1603 (state_invalid) while DefenseClaw is still installed, and the result names the command that removes only the link.
  • Per-user registrations. Uninstall revokes every enrollment, then removes DefenseClaw's own registrations and plugins (Amp, Antigravity, Devin, Hermes, Kiro, OpenCode, a Copilot user hook file) from the agent config of users with an active (connected) session, running as each user. Acting as a user needs LocalSystem, so an uninstall from an elevated prompt or Add/Remove Programs removes none and reports user_registrations_pending. Signed-out users, and signed-in users whose session is disconnected (query user shows Disc), keep theirs and are named in user_registrations_pending; failures report user_registrations_failed. An older Claude Code per-user hook in %USERPROFILE%\.claude\settings.json is removed exactly, and a changed one is kept with claude_settings_hook_left.
  • Per-user runtime files. Run as LocalSystem, an uninstall without PURGE=1 also removes, from the %USERPROFILE%\.defenseclaw of each enrolled account whose registrations it removed, what the managed runtime wrote there: hooks, logs, hook_contract_lock.json and its lock file, inventory.db, foreign-hook-env.json, foreign-hook-sessions, agent_selection.json and the connectors' lock files, and the emptied connector_backups folders. The folder goes when nothing else is in it. The account's own files, foreign-hooks-backup, a backup record that stays and acp stay, and get the owner-private access list a per-user install can manage; the result names the folder in user_state_remaining with what stays. A link or junction is left as found, and a folder that holds a per-user install (config.yaml, audit.db, .venv or installer) is not changed. An account whose registrations stay keeps its folder as it is. Before 1.0.8 the folder stayed whole, with the managed access list, and a later per-user install of that account stopped at defenseclaw init ("hook_contract_lock.json rollback source is not protected"); see Per-user installs.
  • PURGE=1 also removes each enrolled account's %USERPROFILE%\.defenseclaw (including foreign-hooks-backup; copy it first if the account wants those hooks back), its .defenseclaw.rollback-<random> copies, the DefenseClaw launchers and binaries in %USERPROFILE%\.local\bin, the Claude Code drop-ins, machine-policy.json, the runtime selectors and the lifecycle lock. An account without an active (connected) session keeps its .defenseclaw for the registrations that stay (user_registrations_pending and per_user_state_remaining warnings; the purge exits 0). A signed-out account's registry hive is not loaded, so it also keeps its user Path entry for %USERPROFILE%\.local\bin; that is a warning too, and the entry runs nothing. A PURGE=1 run after a plain uninstall already finished removes the accounts' per-user data as well. It needs LocalSystem: otherwise it removes the machine deployment but none of these folders, fails with a nonzero exit and names each account (per_user_state_remaining). Run Setup /ensure and then /uninstall PURGE=1 as LocalSystem while the accounts have a connected session. If the purge already removed the machine deployment that lists the accounts, a second PURGE=1 finds none of them: the error then names the folders to delete by hand. It still removes the marker, so an Intune registry detection rule reports DefenseClaw as not installed. The machine_state_remaining warning names anything it could not remove.
  • Shared machine folders (C:\Program Files\ClaudeCode\managed-settings.d, Codex's requirements.toml) stay while they hold anything else; Setup removes only its own files. Codex's file can hold your own keys, so a purge with no deployment record leaves it, and the next /ensure adopts it.
  • If C:\ProgramData\Cisco\DefenseClaw was deleted by hand, uninstall still removes the services, binaries, Claude Code files and hook runtime, and with PURGE=1 names the per-user folders for you to remove.
  • What stays is inert. The OpenCode and Amp plugins stop enforcing, and the Devin, Hermes, Antigravity, Kiro and Copilot hooks point at the removed defenseclaw-hook.exe, so each call fails to start and none of those agents blocks on it (Hook process control).
  • Folder permissions stay. While an account is enrolled, the guardian gives the agent folders and files that hold DefenseClaw's registrations (for example %USERPROFILE%\.config, .config\amp\plugins, .config\opencode\plugins, .codex and .claude\settings.json) an explicit access list that does not inherit from the profile. Uninstall and PURGE=1 remove DefenseClaw's entries and the gateway's access, but keep that list. The account keeps full access to its files, but cannot change the permissions of those folders, new items in them do not inherit from the profile, and Administrators are not on the list. To return one to the profile's permissions, run icacls "<folder or file>" /reset as LocalSystem (a SYSTEM scheduled task, for example). (Get-Acl "<path>").AreAccessRulesProtected is True for each one that still has the list.

1.0.7 purge limit

On some Windows hosts, new objects are owned by the administrator who created them instead of the Administrators group. After a first install is interrupted, an elevated Setup process that is not LocalSystem can refuse to purge those objects. The refusal preserves ownership checks. Run the recovery or purge as LocalSystem after reviewing the named objects.

Payload trust

The lifecycle refuses any payload file it cannot trust:

ModeHow a file is trusted
authenticodeEvery binary and script has a valid Authenticode signature. An allowed-signer list narrows the signers
hash_pinnedEvery file that is not validly signed matches a SHA-256 in an administrator-owned payload manifest
Entry pointTrust usedHow to change it
Standalone SetupChosen by the build: an unsigned Setup uses hash_pinned with a manifest Setup writes from its embedded copy; a signed Setup uses authenticodeALLOWEDSIGNERS= pins the signer of a signed build
defenseclaw.exe enterprise windowsauthenticode--trust-mode hash_pinned --payload-manifest <file>; --allowed-signer <sha256> (repeatable)
MDM wrapper (Invoke-DefenseClawEnterprise.ps1)HashPinned: it checks the Setup file against -Sha256 first-TrustMode Authenticode -AllowedSigners <sha256> (MDM)

Check a Setup's signature and print the signer thumbprint for ALLOWEDSIGNERS=:

$sig = Get-AuthenticodeSignature -LiteralPath .\DefenseClawSetup-Enterprise-Standalone-x64.exe
$sig.Status
if ($sig.SignerCertificate) {
  $sha = [Security.Cryptography.SHA256]::Create()
  [BitConverter]::ToString($sha.ComputeHash($sig.SignerCertificate.RawData)).Replace('-', '').ToLowerInvariant()
}

Valid means signed; NotSigned means a hash-pinned build, trusted by the hash you checked against checksums.txt. enterprise.trust in the config can only narrow what the entry point accepts: mode: authenticode refuses a hash-pinned run (1639), also over a deployment installed hash-pinned (Payload trust). Hash-pinned files do not satisfy WDAC or AppLocker rules that require a publisher signature.

The lifecycle CLI can also run from a folder with the payload files (defenseclaw.exe, defenseclaw-gateway.exe, defenseclaw-hook.exe, defenseclaw-hook-guard.exe, defenseclaw-acp.exe, defenseclaw-sensor-helper.exe, install-enterprise.ps1, DefenseClawEnterprise.psm1) for your own build or re-signing pipeline, with ensure --profile standalone --config <path> --json. A folder without defenseclaw-hook-guard.exe is refused before anything changes, and so is a direct install or upgrade without --hook-guard-binary. Unsigned files need --trust-mode hash_pinned --payload-manifest <file>, a JSON file of the form {"schema_version":1,"files":{"<file name>":"<sha256>"}} that pins every unsigned file including defenseclaw-scanners.exe. The ...payload-manifest.json release asset has another format. Otherwise use Setup.

Agent sessions in WSL

An agent inside a WSL 2 distribution is outside every policy DefenseClaw publishes on Windows: the distribution has its own /etc/claude-code and ~/.codex, the user can open it as root, and Windows endpoint sensors do not see the WSL VM. The standalone profile turns these off where a vendor documents a control, and enterprise policy show and verify report the rest in a wsl row. Set the behavior under enterprise.machine_policy.windows_wsl (Configuration).

SurfaceWhat DefenseClaw does
Claude Desktop WSL sessionsAdds disableWslSessions (REG_SZ true) to HKLM\SOFTWARE\Policies\Claude only when the key already holds machine policy, and never changes an administrator's value. An administrator false or 0 turns WSL sessions on and fails verify unless agent_sessions: allow is set
wslInheritsWindowsSettingsDetected, never written. While WSL sessions are allowed it fails verify, because a WSL session would load a Windows hook command that cannot start inside Linux
Codex IDE extensionEvery guardian pass, as each enrolled user, resets chatgpt.runCodexInWindowsSubsystemForLinux: true to false in VS Code, VS Code Insiders and Cursor user settings. After 3 repairs for one account in an hour it only reports
Codex appReported only: the environment is an in-app setting with no documented managed control
WSL itselfWith platform: disable, sets HKLM\SOFTWARE\Policies\WSL\AllowWSL=0, turning WSL off for every account. It never replaces an administrator value

Any value directly under HKLM\SOFTWARE\Policies\Claude makes Claude Desktop ignore HKCU policy, so DefenseClaw joins machine policy only when it already exists. With an empty key Claude Desktop's own default applies. The wsl row stays covered with a pending line naming the step that makes the gate explicit: add the output of enterprise policy export --connector wsl (reg, json or intune) to the Claude Desktop policy you deploy, or set claude_desktop_key: create. Uninstall removes only the values DefenseClaw wrote that are unchanged.

If claude_desktop_key: create is later removed from the config (or the organization removes its own values from the key), DefenseClaw keeps the disableWslSessions value it wrote, so WSL sessions stay off. The wsl row stays covered, with a detail line naming the value as DefenseClaw's own, while no account has HKCU Claude Desktop policy or local third-party configuration that the value overrides and the key stays closed to standard accounts; otherwise the row names what the value overrides as a conflict. Uninstall removes the value.

Limits:

  • The vendor documents only false and 0; whether REG_SZ true forces the gate off is not documented. Check Desktop's main.log for [wslPolicyGate] lines.
  • A running Claude Desktop WSL session continues; Desktop checks the value at each session start.
  • A user can turn the Codex extension setting back on until the next guardian pass, and workspace settings are not checked.
  • Agent CLIs a user runs inside the distribution are not covered. Only platform: disable closes WSL as a whole.
  • A Linux standalone install inside the distribution is refused (Linux requirements).

Connectors on Windows

ConnectorRoute on WindowsNotes
CodexMachine policyCodex requirements file. DefenseClaw always sets allow_managed_hooks_only = true; an administrator value of false fails the run
Claude CodeMachine policyManaged-settings drop-in with DefenseClaw's hooks and, under managed_hooks_only: enforce, the allowManagedHooksOnly lock. preserve leaves the lock out and turns the foreign-hook guard on. A non-empty HKLM\SOFTWARE\Policies\ClaudeCode\Settings is refused
CursorMachine policyCursor enterprise hooks
GitHub CopilotMachine policy%ProgramData%\GitHub\Copilot\policy.d, plus a per-user hook runtime
OpenCodeMachine policy%ProgramData%\opencode loads the managed plugin, plus a per-user hook runtime. Falls back to the per-user plugin while the managed plugin is not in force
Antigravity, Devin, HermesPer userThe guardian registers defenseclaw-hook.exe in each user's agent config
AmpPer userAn in-agent plugin that calls the gateway after the listener proves it can derive the user's credential
KiroPer userThe guardian writes defenseclaw-hook.exe into each user's %USERPROFILE%\.kiro\hooks\defenseclaw.json (Kiro IDE 1.0.182 and later, kiro-cli --v3) and the CLI 2.x defenseclaw agent, pinned to a reviewed Windows hook contract (kiro-cli 2.27.1 and later, Kiro IDE 1.0.182 and later). A supported IDE is enrolled beside an older CLI, which is reported separately as unprotected. A user an earlier release enrolled at kiro-cli 2.24.1 to 2.26.x keeps being repaired at that version; status reports that CLI as uncovered and verify fails. A kiro-cli that has never run is not enrolled at an assumed version: status reports it as hook_contract_unverified until its first run names its version (Kiro)
OpenClaw, ZeptoClawNot managedThe enumerator writes no targets for them

See Machine policy and Foreign-hook guard.

Windows platform limit: a held Codex requirements file

Codex reads C:\ProgramData\OpenAI\Codex\requirements.toml as each user, so every user must be able to read it. A user who can read it can also hold it open, and while it is held Windows does not let DefenseClaw replace it, so Codex policy updates wait. The enforced policy already in place stays in effect. Status names the process that holds the file (the warning codex_requirements_held). On a standalone deployment, if the holder lets go within 30 seconds of the failed attempt, the running command applies the update. Otherwise the guardian applies it at its next pass, about a minute later, and a failed Setup run needs the administrator to run it again. Secure Client keeps the earlier behavior and does not wait.

Claude Cowork

Claude Cowork runs its agent loop on the computer, with the Claude Code engine that Claude Desktop bundles. The Claude Code drop-in (C:\Program Files\ClaudeCode\managed-settings.d\90-defenseclaw.json) is meant to cover it. There is nothing to configure for Cowork itself.

ItemWindows
MeasuredIn the 1.0.8 tests with Claude Desktop 4.16336.0 (engine 2.1.317) using third-party inference through Amazon Bedrock, Cowork's hook calls reached the gateway with surface cowork, and an administrator deny rule blocked mcp__workspace__bash. A read of a .env file was not blocked: its contents reached the model, which chose not to repeat the key (DefenseClaw did not withhold it); to prevent such a read, deny the path at PreToolUse (Secrets in tool results). An account that has only Claude Desktop is enrolled. How managed_hooks_only treats Cowork plugin hooks on Windows has not been measured yet
Engine folderclaude-code\<version>\ in the user's Claude Desktop data folder: %APPDATA%\Claude, %LOCALAPPDATA%\Claude-Data\claude_<id> for the Microsoft Store (MSIX) app, or %LOCALAPPDATA%\Claude-3p for third-party inference. DefenseClaw trusts it by an Authenticode signature by Anthropic, PBC (or Anthropic PBC) on claude.exe, whose file version equals the folder
If the engine is not identifiedThe Desktop surface is reported surface_unverified. That does not block by default
ShellRuns in the Cowork Linux VM, so the POSIX shell rules apply on Windows
status and verifyPrint a cowork line (configured, and how many hook calls reported themselves as Cowork since the gateway started), each enrolled account's last Cowork event, and each enrolled account's Claude Desktop data folders with the newest engine build and its Authenticode trust (for example engine 2.1.317 trusted; JSON cowork.claude_desktop). An elevated session is needed for the per-account lines

See Claude Cowork for the tools, managed_hooks_only and the limits.

Sandboxes

Sandboxes do not run on Windows. A guardrail profile can still require one: a person in that group is refused when Claude Code or Codex starts, with reason os_unsupported and the request-access contact. Keep required_for out of the profiles of people who work on Windows if they must keep using these agents (Windows computers).

Upgrades and downgrades

Run /ensure with the newer Setup. It upgrades in place and keeps the config and state. It refuses an older version (downgrade_refused). See Upgrade, Roll back and Lifecycle error codes.

The hook during an upgrade

/repair, /ensure and the hook guardian do not replace a healthy hook: a hook that matches the digest the deployment records keeps its file. An upgrade replaces it once, in one step. The new hook takes the old one's name and the old one stays under a backup name until no program runs it, so a program that starts the hook gets the old one or the new one.

Measured. On Windows Server 2025, 20 upgrades of the 1.0.9 Setup ran with hook starts going the whole time: 10 from 1.0.8 and 10 from an earlier 1.0.9 build, 6 of them with the CPU at 100%. They made 222,039 hook starts and none failed. Before the fix, 1 of 31 upgrades failed 4 starts. The cause was not the swap. It was Setup's own check that nothing holds the hook: the check asked Windows Restart Manager, which opens the file with no sharing for a short time the first time (the length of that hold was not measured in place; the hit rate is the measure). That hit about 3% of upgrades. Setup now tests for a holder first, four times 100 ms apart, and asks Restart Manager only when every test finds a handle that does not share deletion. Before the repeat, Restart Manager still ran in 1 of 7 traced upgrades of the fixed Setup; no start failed in any of them.

Limits. The starts were defenseclaw-hook.exe --version run as SYSTEM, about 65 a second, not real agent calls by a standard user. No start storm ran during /repair or the purge: for repair and ensure, the evidence is that the hook kept the same file in every run and a test of the hold check. The upgrades started from 1.0.8 and one earlier 1.0.9 build, not from 1.0.2 or 1.0.3.

A program that holds the hook open. A program can open the hook so that no one else can open it (a handle that shares nothing, or one that writes without sharing deletion), and while that handle is open no account can start the hook. A swap cannot end that, because Windows refuses to replace a file while a handle on it does not share deletion. On a standalone install the guardian, which runs as SYSTEM, ends such a hold by closing that one handle in the process that owns it. The bounds:

  • It waits for the second or third check. The hook must still refuse a start, and a test open for deletion, on two checks about 5 seconds apart, with a handle of the same program on both: the same process, or the same file object (a duplicated handle keeps it). When the handle on the second check is in a different process of the same user (account and session), it waits for a third check. The hook is free again 5 to 15 seconds after the hold starts, not at once. A single read shorter than about 5 seconds is not closed. Several short reads in a row are closed only when the same program keeps the hook blocked across two checks, or the same user across three.
  • It closes only a handle on the hook's own file (same volume and file ID), with data or execute access, found without reading any name. Windows does not show the sharing mode of one handle, so the guardian tests whether any handle on the file refuses deletion, closes one handle, tests again and stops when the hook can be started. Handles that refer to the same file object are closed together, one file object at a time, the one with the fewest handles first (among objects with as many handles, the one with a handle that can write or append first), and it works on one user at a time, the user whose hold began first. Because Windows does not show one handle's sharing, if that user has other handles on the hook, in the same process or another, on the same file object or another, the guardian can close one that was not the cause (a read handle that shares deletion) before it reaches the one that was; it closes no more than it needs to start the hook, and never in a service, protected or session 0 process. It reaches a second user's handles only if that user also kept a handle on the hook across the same checks and the hook is still refused after the first user's are closed.
  • It never closes a handle in a protected process, in a process that runs as LocalSystem, LocalService, NetworkService or another service account, or in session 0. It closes handles only in the processes of a user who is signed in. Windows does not show whose handle refuses the start, but its sharing rules say which file objects can: a start asks for read and execute and shares read and delete, so a file object can refuse it only if one of its handles can write or append, or if it is the only file object open on the hook. (The guardian service does not get the address of a handle's file object on Windows Server 2025, so it counts every handle as an object of its own; two handles on one file object then look like two objects, and the audit rows and log lines say that the file object count counts handles there.) A program of one of those other kinds that has the hook open on such an object may be what refuses the start, so while it is there the guardian closes no user's handle either: it logs and audits that program, names it and says why, and waits one check for a program of that kind it has only just seen. If that program only has the hook open and a user's handle is what refuses the start, the hook stays unavailable until that program lets go, with one exception: after one user's hold has lasted about 30 seconds the guardian closes that user's handles once per streak, one file object at a time, to rule the program out, and the audit rows say so. A program of that kind that only reads, beside another file object, cannot refuse a start: the guardian names it in a row with closed set to false and still closes the user's blockers. A handle that its owner protected from being closed is named and skipped, and the user's other handles are still closed. If the program is what refuses the start, the hook stays unavailable until it lets go too.
  • Every handle it closes writes a HIGH connector-hook-tampered audit row: the program's full path, process id, account (SID and name), session, the access the handle had, the hook's path, and how many candidate handles, processes and file objects it chose from. A hold it did not end writes a row with the same action and closed set to false, also HIGH, because while that handle lives no hook start is allowed. The file is not changed and the process keeps running. A row waits for the gateway: it is kept in memory and in a file in the guardian's state folder (at most 256 rows) and delivered in order once the gateway answers, so a gateway that is down delays the row, never the close. A row the gateway refuses for good (HTTP 400, 413, 415 or 422, which describe a bad row) is dropped after 5 tries, with a log line, so the rows behind it still go out; a 401, 403, 404 or 405 is about the gateway, not the row, and the row stays queued. A standalone uninstall removes the guardian's whole state folder, with or without PURGE=1, and the file with it.
  • A close that finishes after the guardian stopped waiting for it is audited when it finishes, with a sentence that says so. The guardian waits a quarter of a second for a call, and up to 2 seconds more for a close that has begun; until then its log says the handle "may have been closed", and the next check shows whether the hook is free.
  • A holder that takes the handle again is closed again after 10 seconds, then 20, doubling to 5 minutes, with one audit row per holder until 10 minutes pass without a hold. A user who keeps re-opening the hook this way can keep it from starting for most of that time. That is a known limit of a hook image every user may start.
  • The guardian closes at most 64 handles in one check. If the hook is still refused after 64, the next 64 are closed at a later check, after the wait above, so a user who duplicates the hook handle many times slows the guardian down and keeps the hook unavailable for longer. If the processes that have the hook open hold more than about 2,000 file handles with data access between them, the guardian stops looking and closes none, and the hook stays unavailable until some of them are closed.
  • A call on a handle that does not answer within a quarter of a second is given up on, and that handle is not closed. A user who keeps 24 such calls blocked can stop the guardian from looking for as long as they stay blocked, and the hook stays unavailable.
  • It watches the files a hook start reads, not only the hook: the hook binary and the regular files in C:\ProgramData\Cisco\DefenseClaw-HookRuntime (exactly these names, when they exist as regular files and not as links: machine-policy.json, the machine policy summary; .defenseclaw-hot-config-undo-closed, the closure marker; and in each of the antigravity, copilot, devin, hermes, kiro and opencode folders, enrollment.json and .defenseclaw-managed-runtime-selector.state; 14 files at most). The guardian does not walk the folder. A lock file (.defenseclaw-enrollment.lock, .defenseclaw-managed-runtime-selector.lock), a .defenseclaw-policy-*.tmp temp file, a setup record or any other name is never watched: Setup and the command line hold those locks with no sharing for a whole transaction and the hook never opens them, so closing such a handle would break the lock or write a tamper row for DefenseClaw's own run. In each check the hook binary comes first; the guardian then works on at most 4 held runtime files, and the next check starts where this one stopped, so a user who holds many of them cannot delay the binary; the other held files are handled at most 4 per check, so with N held files a given file can wait up to ceil(N/4) checks for its pass. A hold of machine-policy.json fails every guarded call closed, because the hook cannot read it. Each file has its own two checks, backoff, streak and audit rows, with the same bounds and the same refused-holder rules as the binary. The hook reads these files with read access and every sharing allowed, so a hold is a handle that allows no reading and no deletion. There is no swap for a data file, only the bounded close. The audit row and the log line name the file. A file anywhere else is not watched, even if a program holds it.
  • A standard user cannot make such a hold, as measured on Windows Server 2025. A FILE_SHARE_NONE open by an account with no write access to the file did not keep other programs from opening it: 0 of 12 tries with the file read-only for Users, 12 of 12 with Users allowed to modify it. No file a hook start reads can be written by Users, so the holds this guardian ends come from administrator sessions, SYSTEM and service accounts. This was measured on one Windows Server 2025 host; other Windows builds were not measured, and it holds only while the shipped file permissions are unchanged.
  • Secure Client is unchanged: it never closes another program's handle.

A holder that shares deletion (a handle opened with FileShare.Delete) is swapped around instead: the guardian swaps no more than every 10 seconds, doubling to 5 minutes, and stops while 8 backups are pending.

If Setup refuses to replace the hook. When the installed hook does not match the digest the deployment records, and the guardian's protected copy is missing or does not match either, Setup /ensure and /upgrade of the new release stop before they stop or change anything, exit 1603, with refusing to replace the installed hook: there is no copy to roll back to. The new release's /repair does not help; a Setup repairs only its own release (1639). Recover with the release that is installed, then run the new Setup again. The steps are in Setup refuses to replace the installed hook.