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
| Requirement | Detail |
|---|---|
| Windows | Native Windows x64. ARM64 (including x64 emulation) and 32-bit are refused |
| PowerShell 7 | A 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 mode | FullLanguage. Under WDAC or AppLocker, allow the DefenseClaw signer or the run stops with powershell_constrained_language |
| Execution policy | With AllSigned set by Group Policy, add DefenseClaw's signing certificate to Trusted Publishers or the run stops with powershell_execution_policy |
| Privileges | An elevated administrator token, or SYSTEM |
| Disk | About three copies of the Setup payload plus 256 MB free on the ProgramData volume |
| Other profiles | No Secure Client DefenseClaw deployment (profile_conflict) |
| User sessions | Users 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.
| Item | Path |
|---|---|
| Binaries | C:\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 scripts | C:\Program Files\Cisco\DefenseClaw\libexec |
| Managed OpenCode plugin | C:\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) |
| Config | C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml |
| Secrets | C:\ProgramData\Cisco\DefenseClaw\secrets |
| Target manifest | C:\ProgramData\Cisco\DefenseClaw\hook-guardian\targets.yaml (the enumerator writes it) |
| Lifecycle state | C:\ProgramData\Cisco\DefenseClaw\install |
| Gateway data | C:\ProgramData\Cisco\DefenseClaw\runtime |
| Authorization ledger | C:\ProgramData\Cisco\DefenseClaw\hook-guardian-state |
| Service logs | C:\ProgramData\Cisco\DefenseClaw\logs |
| Scanner runtime | C:\ProgramData\Cisco\DefenseClaw-ScannerRuntime: defenseclaw-scanners.exe and the Python runtime it unpacks. The gateway can only read and run it |
| Hook runtime | C:\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.
| Registration | Value |
|---|---|
| Deployment marker | HKLM\SOFTWARE\Cisco\DefenseClaw\Enterprise (Profile, ProductVersion, InstallRoot, StateRoot, TrustMode, UpdatedAt, DisableSelfUpdate). For detection only: verify never trusts it |
| Add/Remove Programs | HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\CiscoDefenseClawEnterprise, "Cisco DefenseClaw Enterprise" |
| Event log | The DefenseClaw log, source DefenseClaw Lifecycle, writable only by LocalSystem and Administrators |
| Self-update policy | HKLM\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:
| Service | Identity | Role |
|---|---|---|
DefenseClawGateway | LocalSystem, write-restricted by its NT SERVICE\DefenseClawGateway service SID, with only SeChangeNotifyPrivilege | Policy engine and hook API on 127.0.0.1:18970 |
DefenseClawSensorHelper | LocalSystem, SeChangeNotifyPrivilege only | Answers the gateway's fixed AI Discovery requests |
DefenseClawHookGuardian | LocalSystem | Writes and repairs each enrolled user's registrations and the configured machine hooks every minute, even with no enrolled users |
DefenseClawHookEnumerator | LocalSystem | Finds eligible profiles (local, domain and Microsoft Entra ID accounts) every five minutes and writes the target manifest |
List view for small screens. Use the expand button to open the drawing.
TrustedZ0 · Admin and OS (SYSTEM)
- Service Control Managerknows the gateway's PID
- startsGatewayZ2
UntrustedZ4 · User session (the user)
- AI agentruns as the user
- runs per tool calldefenseclaw-hook.exe
- defenseclaw-hook.exechecks the listener
- asks over loopback TCPGatewayZ2
RestrictedZ2 · Gateway (restricted LocalSystem)
- Gatewayallows or blocks
List view for small screens. Use the expand button to open the drawing.
PrivilegedZ1 · Services (LocalSystem)
- Enumeratorlists the users
- writesTarget manifestZ3
- Guardianchecks every minute
- readsTarget manifestZ3
- repairs, as the userAgent configZ4
ProtectedZ3 · Admin-owned files
- Target manifesttargets.yaml
UntrustedZ4 · User session (the user)
- Agent configin the user's profile
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_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-NullThe snippet is safe to run again. Then name and pin the pack in the config:
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-NullThen set policy_dir in the config:
policy_dir: 'C:\ProgramData\DefenseClaw-Policies'
guardrail:
rule_pack: strictSetup 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:
| Code | Meaning |
|---|---|
0 | Success, or nothing to do |
1603 | Failure. 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 |
1618 | Retry 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) |
1639 | Invalid 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 |
3010 | Reserved. The lifecycle never requests a restart |
Setup properties use NAME=value; names are case-insensitive and ignore dashes.
| Property | Meaning |
|---|---|
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=1 | With /ensure and BUNDLE=: refuse a bundle that turns off an enforced capability |
ATTESTCLAUDEEFFECTIVEPOLICY=1 | With /repair: record the Claude Code attestation (Verify the install) |
ALLOWEDSIGNERS=<sha256>,<sha256> | Accept only these Authenticode signer thumbprints |
JSON=1 | Print the result document on standard output |
NOSTART=1 | Install with the services stopped and disabled (not_started warning); a later /repair starts them |
PURGE=1 | With /uninstall: also remove each enrolled account's per-user data (Remove) |
FORCE=1 | With /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:
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" --jsonUntil 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, StartTypeName Status StartType
---- ------ ---------
DefenseClawGateway Running Automatic
DefenseClawHookEnumerator Running Automatic
DefenseClawHookGuardian Running Automatic
DefenseClawSensorHelper Running Automaticstatus reports the state. verify also checks every file, permission, service and
hook, and returns a nonzero exit code when anything fails. Healthy values:
| Field | Healthy value |
|---|---|
ok, errors | true, empty |
installed_version | The version you deployed |
readiness | gateway, guardian, enumerator and sensor_helper all true |
coverage_complete | true |
security_complete | false 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.targets | One entry per user and connector. 0 means nobody is protected yet |
policy | applied 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' statusThe & 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:
& '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:
Get-Service DefenseClaw* | Format-Table Name, Status, StartType
Get-WinEvent -LogName DefenseClaw -MaxEvents 3 | Format-Table TimeCreated, Id, LevelDisplayName, ProviderNameEach 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:
-
Install.
security_completeisfalseat this point. -
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"$Stageis the administrator-only folder from step 2. The export can hold prompt and tool content.enterprise policy verify --liveis not available on Windows. -
Record the attestation:
& $Cli enterprise windows repair --profile standalone --attest-claude-effective-policy --jsonThe 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.
$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:
& '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>.actionsisblockblocks the asset and leaves its folder in place (file_action=none).quarantinecopies the asset toC:\ProgramData\Cisco\DefenseClaw\runtime\quarantine(<type-dir>\<connector>\<name>, or aper-sourceslot 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: warnsetting keeps the server with a warning and an audit record;unverified_server: blockrefuses 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, andstatusandverifywarnasset_not_scannedorasset_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
statusandverifywarnasset_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 untiltake_actionis on again; thenasset_rejected_not_enforcedwarns. -
admission.mcp.scan_on_install: falseadmits 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
npxoruvxis installed for all users in a folder only administrators can change (for exampleC:\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.tomland theconfig.tomlunder the user's persistentCODEX_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 andstatuswarnsclaude_state_unreadable,kiro_mcp_unreadableorcodex_mcp_unreadable. A project's.mcp.jsonis 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.deniedrule still makes the hook refuse it withASSET-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.mcprules name themplugin:<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=0anddefenseclaw-gateway status --jsonreports it degraded withprofile_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, setgateway.watcher.enabled: trueandgateway.watcher.skill.enabled: true(orgateway.watcher.plugin.enabled: true), addtake_action: trueto enforce the verdict, and list a folder outside profiles ingateway.watcher.skill.dirs(orgateway.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
npxoruvxwith 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 onPATH, is refused. - A definition the scan refuses for its own launcher (not
npxoruvx, 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'sPATH, 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:
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 underruntime\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.
$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.
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy verifyshow 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:
& '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 standaloneThen 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:
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:
DefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall FORCE=1 JSON=1
DefenseClawSetup-Enterprise-Standalone-x64.exe /ensure CONFIG=C:\ProgramData\DefenseClaw-Staging\config.yaml JSON=1FORCE=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\DefenseClawGatewayfromruntimeoretcstops the gateway from starting.repair,/ensure,/uninstalland 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 Codexrequirements.tomland 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,/repairand/ensurerefuse 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/ensureagain. A file that already has the canonical access list is not written, so a holder does not matter for it. For the Codexrequirements.tomland 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.tomlwithout delete sharing, orrequirements.tomlwith write or delete access while its access list has to be written, stops the run after 30 seconds withcodex_requirements_heldorcodex_state_held(exit1618) 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 samecodex_requirements_heldorcodex_state_held(exit1618) naming the program and its process id, and with the failure that started the rollback. The transaction stays pending, and the next/repairas 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 newerrequirements.tomlbeside 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/repairruns; that is fail closed by design. When the held file is therequirements.tomlthe recovery had to republish, the result also says the guardian's coverage was not proven by that rollback. A recovery that restores arequirements.tomlan administrator edited in the managed policy publishes the managed policy again instead of stopping, keeps your file underinstall\recovered-policyand warnscodex_requirements_replaced;/uninstall FORCE=1is 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
/repairrefuses because the running gateway's installed config cannot be validated for rollback, restore an approved, gateway-validconfig.yamland 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. Whendeployment.jsonis 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_skippedwarning. The audit database and the redaction correlation key are never skipped. - The rollback never deletes content in an account's
%USERPROFILE%\.defenseclawit cannot prove DefenseClaw wrote; it renames the folder to.defenseclaw.rollback-<random>. Review and delete that folder. - A signed-out account whose
.defenseclaworhooksfolder has the wrong owner or permissions is skipped with auser_runtime_folder_untrustedwarning 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=0to skip signed-out accounts. No guardian is left to clean an account later, so the result lists each item it could not remove as arollback_leftoverwarning, 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_leftoverwarnings. Setup run from an elevated administrator prompt cannot act as accounts, so run/ensureand/uninstallas 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:
| Reason | Meaning |
|---|---|
no_payload | No gateway ships beside the running Setup |
unsigned_scope | The run is a certification run, not a production one |
not_local_system | The lifecycle does not run as LocalSystem |
inside_install_root | The candidate is the installed payload |
untrusted | The 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_binary | The candidate is the staged gateway that already failed |
version_unknown | The release of the candidate or of the staged gateway cannot be read |
older_release | The 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.
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 $ResultLastTaskResult 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 action | What happens |
|---|---|
install.ps1 | Refuses when the marker key exists, or when DisableSelfUpdate under HKLM\SOFTWARE\Policies\Cisco\DefenseClaw is nonzero |
defenseclaw upgrade, defenseclaw rollback | Refuse when the marker key exists |
| Per-user gateway | Refuses 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 --jsonUninstall 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(andPURGE=1if the original was a purge). - While a program runs a DefenseClaw executable from
bin,/uninstallfails withuninstall_in_usebefore it stops any service, naming the program, process and account. WithPURGE=1, a program holding a file open inC:\ProgramData\Cisco\DefenseClaw(a SIEM forwarder readingruntime\audit.db, for example) blocks it the same way. Close it and run again. The Intune launcher's uninstall retries and then exits1618. privileges_requiredmeans 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 withpsexec -s.- A file or folder under
C:\Program Files\Cisco\DefenseClawthat DefenseClaw did not install stops a standalone uninstall with1603before it changes anything, and the result names that item, also inside thelib\defenseclawfolder that 1.0.2 installed (for examplelib\defenseclaw\operator-note.txt). Move it out ofC:\Program Files\Cisco\DefenseClaw, then run the uninstall again. - A junction or symbolic link inside
C:\ProgramData\Cisco\DefenseClaw(for example atsecrets) 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 atC:\ProgramData\Cisco\DefenseClawitself, or one Setup cannot remove, stops the uninstall with1603(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 usershowsDisc), keep theirs and are named inuser_registrations_pending; failures reportuser_registrations_failed. An older Claude Code per-user hook in%USERPROFILE%\.claude\settings.jsonis removed exactly, and a changed one is kept withclaude_settings_hook_left. - Per-user runtime files. Run as LocalSystem, an uninstall without
PURGE=1also removes, from the%USERPROFILE%\.defenseclawof each enrolled account whose registrations it removed, what the managed runtime wrote there:hooks,logs,hook_contract_lock.jsonand its lock file,inventory.db,foreign-hook-env.json,foreign-hook-sessions,agent_selection.jsonand the connectors' lock files, and the emptiedconnector_backupsfolders. The folder goes when nothing else is in it. The account's own files,foreign-hooks-backup, a backup record that stays andacpstay, and get the owner-private access list a per-user install can manage; the result names the folder inuser_state_remainingwith what stays. A link or junction is left as found, and a folder that holds a per-user install (config.yaml,audit.db,.venvorinstaller) 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 atdefenseclaw init("hook_contract_lock.json rollback source is not protected"); see Per-user installs. PURGE=1also removes each enrolled account's%USERPROFILE%\.defenseclaw(includingforeign-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.defenseclawfor the registrations that stay (user_registrations_pendingandper_user_state_remainingwarnings; the purge exits0). 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. APURGE=1run 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/ensureand then/uninstall PURGE=1as LocalSystem while the accounts have a connected session. If the purge already removed the machine deployment that lists the accounts, a secondPURGE=1finds 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. Themachine_state_remainingwarning names anything it could not remove.- Shared machine folders (
C:\Program Files\ClaudeCode\managed-settings.d, Codex'srequirements.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/ensureadopts it. - If
C:\ProgramData\Cisco\DefenseClawwas deleted by hand, uninstall still removes the services, binaries, Claude Code files and hook runtime, and withPURGE=1names 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,.codexand.claude\settings.json) an explicit access list that does not inherit from the profile. Uninstall andPURGE=1remove 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, runicacls "<folder or file>" /resetas LocalSystem (a SYSTEM scheduled task, for example).(Get-Acl "<path>").AreAccessRulesProtectedisTruefor 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:
| Mode | How a file is trusted |
|---|---|
authenticode | Every binary and script has a valid Authenticode signature. An allowed-signer list narrows the signers |
hash_pinned | Every file that is not validly signed matches a SHA-256 in an administrator-owned payload manifest |
| Entry point | Trust used | How to change it |
|---|---|---|
| Standalone Setup | Chosen by the build: an unsigned Setup uses hash_pinned with a manifest Setup writes from its embedded copy; a signed Setup uses authenticode | ALLOWEDSIGNERS= pins the signer of a signed build |
defenseclaw.exe enterprise windows | authenticode | --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).
| Surface | What DefenseClaw does |
|---|---|
| Claude Desktop WSL sessions | Adds 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 |
wslInheritsWindowsSettings | Detected, 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 extension | Every 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 app | Reported only: the environment is an in-app setting with no documented managed control |
| WSL itself | With 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
falseand0; whether REG_SZtrueforces the gate off is not documented. Check Desktop'smain.logfor[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: disablecloses WSL as a whole. - A Linux standalone install inside the distribution is refused (Linux requirements).
Connectors on Windows
| Connector | Route on Windows | Notes |
|---|---|---|
| Codex | Machine policy | Codex requirements file. DefenseClaw always sets allow_managed_hooks_only = true; an administrator value of false fails the run |
| Claude Code | Machine policy | Managed-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 |
| Cursor | Machine policy | Cursor enterprise hooks |
| GitHub Copilot | Machine policy | %ProgramData%\GitHub\Copilot\policy.d, plus a per-user hook runtime |
| OpenCode | Machine 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, Hermes | Per user | The guardian registers defenseclaw-hook.exe in each user's agent config |
| Amp | Per user | An in-agent plugin that calls the gateway after the listener proves it can derive the user's credential |
| Kiro | Per user | The 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, ZeptoClaw | Not managed | The 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.
| Item | Windows |
|---|---|
| Measured | In 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 folder | claude-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 identified | The Desktop surface is reported surface_unverified. That does not block by default |
| Shell | Runs in the Cowork Linux VM, so the POSIX shell rules apply on Windows |
status and verify | Print 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
closedset tofalseand 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-tamperedaudit 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 andclosedset tofalse, 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 withoutPURGE=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 theantigravity,copilot,devin,hermes,kiroandopencodefolders,enrollment.jsonand.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-*.tmptemp 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 ofmachine-policy.jsonfails 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_NONEopen 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.
Enterprise threat model
Who DefenseClaw trusts, where each trust boundary sits on Windows, Linux and macOS, what a standard user can and cannot do, and which risks remain in the standalone enterprise profile.
Linux standalone deployment
Install the standalone DefenseClaw enterprise services on Linux from the deb or rpm package or the payload tarball, check the result, and remove them.