Secure Client managed deployment

How DefenseClaw runs as a Cisco Secure Client module on Windows and macOS, what it installs, and how to install, reconcile, verify, upgrade and remove it. The standalone profile is documented in the Enterprise section.

This page covers the Secure Client profile: DefenseClaw installed as a module of Cisco Secure Client on Windows or macOS. Cisco AI Defense makes every decision and the local detectors are off (Secure Client profile). For any other MDM, use the standalone profile and start with Deploy to a fleet. The Secure Client profile is not supported on Linux. Services, paths, the config and the production checklist are in the Secure Client deployment reference.

What is the same in both profiles

Both profiles share the design in Enterprise deployment: a gateway, a privileged hook guardian, an enumerator and a sensor helper. What a standard user can and cannot do is the same (Who can change what, threat model). What is specific here:

SettingSecure Client profile
PlatformsWindows (x64) and macOS (Apple silicon)
Who decides on each tool callCisco AI Defense, authenticated with the Secure Client machine identity (CMID). The local detectors are off
Configenterprise.profile is the only enterprise.* key allowed
Default profileWith no profile set, Windows and macOS resolve to secure_client
WindowsFive services, including the CMID credential broker, installed by DefenseClawSetup-Enterprise-x64.exe with Windows PowerShell 5.1
macOSRoot LaunchDaemons under /opt/cisco/secureclient/defenseclaw
One profile per computerThe profiles share the gateway port and, on Windows, the service names. The standalone lifecycle refuses to install over a Secure Client deployment

Enterprise enforcement is opt-in: installing a release does not create a machine service until an administrator runs the lifecycle with a managed config. A per-user install is not affected: normal mode uses the existing per-user repair loop.

runs per tool call
asks over loopback TCP
token, named pipe
inspects, HTTPS
UntrustedZ4 · User session (the user)
RestrictedZ2 · Gateway (restricted LocalSystem)
PrivilegedZ1 · Services (LocalSystem)
ExternalZ5 · Cloud
AI agentruns as the user
defenseclaw-hook.exechecks the listener
Gatewayallows or blocks
CMID brokerholds machine identity
Cisco AI Defensedecides each call

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

UntrustedZ4 · User session (the user)

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

RestrictedZ2 · Gateway (restricted LocalSystem)

  1. Gatewayallows or blocks
    • token, named pipeCMID brokerZ1
    • inspects, HTTPSCisco AI DefenseZ5

PrivilegedZ1 · Services (LocalSystem)

  1. CMID brokerholds machine identity

ExternalZ5 · Cloud

  1. Cisco AI Defensedecides each call
Windows, Secure Client profile. The hook asks the gateway on 127.0.0.1:18970 after it checks that the listener is the DefenseClawGateway service. The gateway asks the CMID broker for a token over a gateway-only named pipe and sends the call to Cisco AI Defense, which decides.

Windows system-service layout

A Secure Client deployment on Windows runs five Service Control Manager (SCM) services. The standalone profile has the same services without the broker, its own roots and a PowerShell 7 lifecycle; see Windows standalone deployment.

ServiceIdentityPurpose
DefenseClawGatewayLocalSystem, write-restricted by its NT SERVICE\DefenseClawGateway service SID, with only SeChangeNotifyPrivilegeInspection, policy, audit, the loopback hook API and health
DefenseClawCMIDBrokerLocalSystem, only SeChangeNotifyPrivilegeHolds access to the Secure Client machine-identity provider behind a gateway-only IPC channel
DefenseClawSensorHelperLocalSystem, only SeChangeNotifyPrivilegeAnswers the gateway's fixed AI Discovery requests (process, connection, host-event and DNS observations). A request carries no path, pid, filter or command
DefenseClawHookGuardianLocalSystemImpersonates each enrolled user to install and repair that user's hooks, then returns to LocalSystem for protected state
DefenseClawHookEnumeratorLocalSystemFinds eligible users in HKLM ProfileList and maintains the protected target manifest

The AI agent runs as the interactive standard user. It invokes the hooks but cannot stop, reconfigure or replace any of these services.

The LocalSystem gateway refuses reads and scans inside user profiles, with a message to scan as the signed-in user or move the folder outside the profile. This keeps the former virtual-account boundary around other users' profiles. It still scans readable paths outside profiles. Scanner children inherit its write-restricted LocalSystem token with only SeChangeNotifyPrivilege: the gateway lacks the privileges to start them as another user. The watcher skips profile roots and reports degraded health only when it skips one. Outside profiles, a caller-supplied path readable only by administrators is now readable by the gateway as LocalSystem (the W-05 early-phase limitation).

ItemPath
Binaries (broker, gateway, sensor helper, hook, ACP adapter, lifecycle CLI)C:\Program Files\Cisco\Cisco Secure Client\DefenseClaw\bin
Lifecycle scriptsC:\Program Files\Cisco\Cisco Secure Client\DefenseClaw\libexec\install-enterprise.ps1 and DefenseClawEnterprise.psm1
Managed configC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\etc\config.yaml
Runtime state and service-side scoped credentialsC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime
LogsC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\logs
Target manifestC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\hook-guardian\targets.yaml
Authorization ledgerC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\hook-guardian-state\protected_targets.json
Deployment recordC:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\install\deployment.json
IPC sockets (Secure Client UI, sensor helper)C:\Program Files\Cisco\Cisco Secure Client\DefenseClaw\ipc\
Codex machine policyC:\ProgramData\OpenAI\Codex\requirements.toml
Claude Code machine policyC:\Program Files\ClaudeCode\managed-settings.d\90-defenseclaw.json

The roots are fixed. They come from the protected 64-bit machine registration in HKLM, not from the caller's environment, and the lifecycle refuses roots on network, substituted or aliased drives, reparse points, unsafe owners and unsafe DACLs. Environment poisoning therefore cannot redirect a deployment.

Windows enrollment and discovery

DefenseClawHookEnumerator walks HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList 30 seconds after it starts and then every five minutes, and rewrites targets.yaml only when its content changes. It considers interactive-user SIDs (S-1-5-21-…) with a valid, reparse-free profile path, and only the connector families enabled in the managed config. A new user and connector pair is enrolled once a supported agent and version are found in that profile, so a user who installs a supported agent is enrolled on the next cycle. Rows an administrator already set (enabled, deferred, agent_version) are kept.

The enumerator also grants the gateway service read access to the connector folders it inventories (.claude, .codex, .cursor, .agents, .config), not to the whole profile. A folder that cannot be granted is logged and retried on the next cycle.

Install the Windows services

DefenseClawSetup-Enterprise-x64.exe is one signed Setup. Run it elevated with the config and the first target manifest (examples):

$Stage = 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw-Staging'
.\DefenseClawSetup-Enterprise-x64.exe /install JSON=1 `
  CONFIG="$Stage\config.yaml" `
  MANIFEST="$Stage\targets.yaml"
ActionWhat it does
/installFirst install. Requires CONFIG= and MANIFEST=
/upgradeReplace the payload with this release, transactionally
/repairRestore files, DACLs and services; also applies a new CONFIG= or MANIFEST=
/reconcileRun one guardian reconcile now
/status, /verifyReport state; verify also checks every file, DACL and service
/uninstallRemove the services and binaries. PURGE=1 also removes managed state

NOSTART=1 installs with the services stopped (activate with /repair, never Start-Service). TIMEOUTSECONDS= bounds the run. The Setup exits 0 on success and 1603 on any failure. It has no /ensure action and no ALLOWEDSIGNERS=; those belong to the standalone Setup.

A fresh install reports security_complete=false while a Claude Code target is enabled. Record the proof as in Claude Code proof.

The config and first manifest

A Secure Client config. Quote Windows paths in YAML:

config_version: 8
deployment_mode: managed_enterprise
data_dir: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime'
observability:
  local:
    path: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime\audit.db'
    judge_bodies_path: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime\judge_bodies.db'
  defaults:
    redaction_profile: sensitive
plugin_dir: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime\plugins'
policy_dir: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime\policies'
gateway:
  device_key_file: 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\runtime\device.key'
  api_bind: 127.0.0.1
  api_port: 18970
  config_reload:
    mode: restart
guardrail:
  enabled: true
  mode: observe
  scanner_mode: both
application_protection:
  enabled: false

Keep application_protection.enabled: false: in managed mode the guardian, not the gateway, writes user hooks. The first manifest lists the users and connectors to enroll; the enumerator maintains it afterwards. For domain or renamed accounts, add the exact sid:

version: 1
targets:
  - user: alice
    connector: codex
    agent_version: "codex-cli 0.144.3"
  - user: CONTOSO\bob
    sid: S-1-5-21-111111111-222222222-333333333-1001
    connector: claudecode
    agent_version: "2.1.207 (Claude Code)"

Claude Code proof and security_complete

Install is phase one. A fresh install reports claude_effective_policy_verified=false and security_complete=false while a Claude Code target is enabled. Run the approved Claude Code client as an enrolled user with disableAllHooks set in the user and project settings. When you see DefenseClaw's managed hooks run (or the client block the call), record the proof with /repair ATTESTCLAUDEEFFECTIVEPOLICY=1. The proof is bound to the manifest's hash, so a manifest change clears it.

ATTESTAGENTAPPLICATIONCONTROL=1 is optional. Pass it only after WDAC or AppLocker is deployed and tested to allow approved agent builds and block old and unsigned ones. Without it, the managed hooks still run.

The version floors on Windows are Codex 0.131.0 and Claude Code 2.1.152.

Reconcile and verify Windows targets

Only DefenseClawHookGuardian writes user hooks, as the user, and only while the user has an active session. Do not run enterprise hooks install, reconcile or watch from an elevated shell. Run one service-mediated reconcile before you accept an endpoint:

$Gateway = 'C:\Program Files\Cisco\Cisco Secure Client\DefenseClaw\bin\defenseclaw-gateway.exe'
$Manifest = 'C:\ProgramData\Cisco\Cisco Secure Client\DefenseClaw\hook-guardian\targets.yaml'
& $Gateway enterprise windows reconcile --json
& $Gateway enterprise hooks status --manifest $Manifest --json
& $Gateway enterprise hooks verify --manifest $Manifest --json

A partial reconcile makes status and verify return ok: false and a nonzero exit. Service hardening checks: Verify Windows service hardening.

Verify Windows service hardening

From an elevated shell:

$Services = 'DefenseClawGateway', 'DefenseClawCMIDBroker', 'DefenseClawSensorHelper',
  'DefenseClawHookGuardian', 'DefenseClawHookEnumerator'
Get-CimInstance Win32_Service |
  Where-Object { $Services -contains $_.Name } |
  Select-Object Name, State, StartMode, StartName, PathName
foreach ($Service in $Services) { sc.exe qc $Service; sc.exe qfailure $Service; sc.exe sdshow $Service }
.\DefenseClawSetup-Enterprise-x64.exe /verify JSON=1

Expect the identities in the table above, automatic start, the Secure Client image paths, three restart failure actions (5 s, 15 s, then 60 s), protected DACLs with no standard-user write entry, and a passing /verify. The full certification procedure, including live token and tamper checks, is in the repository's Windows enterprise certification runbook. Run it only on disposable validation endpoints.

Windows repair, upgrade, and removal

Run every change through the lifecycle, from a fresh copy of the release's Setup.

  • Upgrade. /upgrade with the approved CONFIG= and MANIFEST=. A failed validation leaves the previous deployment running; a failed activation rolls back.
  • Change the config or manifest. /repair CONFIG=... MANIFEST=....
  • Remove. /uninstall revokes the targets, removes the services and binaries, and removes DefenseClaw's Codex and Claude Code machine-policy entries. It keeps runtime state, logs and guardian evidence. PURGE=1 also removes managed state; use it only for an approved decommission. This is the Secure Client profile: the standalone Setup's /uninstall always removes its machine state (see Remove).

Restart Codex and Claude Code sessions after a removal: a running session may still call the removed hook binary. After an upgrade, run /status, /verify, the guardian status and verify, and one allowed and one blocked tool call.

Native Windows Codex managed hooks

Codex is enrolled through machine policy, not by editing <profile>\.codex\config.toml. The lifecycle owns C:\ProgramData\OpenAI\Codex\requirements.toml with allow_managed_hooks_only = true, hooks enabled, and the ten hook events (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, SubagentStart, SubagentStop, PreCompact, PostCompact, Stop). Each hook command runs the protected defenseclaw-hook.exe through the fixed System32 Windows PowerShell, so a user's PATH, config or project hooks cannot change it. Users can read the policy but not write it. The lifecycle creates C:\ProgramData\OpenAI\Codex when it is missing and never takes over an existing folder.

The guardian verifies and repairs the policy bytes, events, owner and DACL. A missing event, a deleted policy or DACL drift makes status and verify fail until it is repaired. Read-only check:

& $Gateway enterprise windows codex-requirements verify --json

For the standalone profile, see Machine policy.

Native Windows Claude Code managed hooks

Claude Code is enrolled without writing ~/.claude/settings.json. Add the claudecode target to the manifest and run the service-mediated reconcile above. The guardian writes the user's scoped runtime under <profile>\.defenseclaw as that user, then publishes the machine policy C:\Program Files\ClaudeCode\managed-settings.d\90-defenseclaw.json with allowManagedHooksOnly: true. Claude Code loads it without a hook trust prompt.

  • The policy applies to every user on the machine, but a hook call from a user whose SID is not enrolled is refused before any credential is read. Test this with a second, unenrolled standard account.
  • The per-user runtime is always <profile>\.defenseclaw. The managed hook ignores DEFENSECLAW_HOME and CLAUDE_CONFIG_DIR.
  • DefenseClaw refuses to overwrite a foreign drop-in, a drop-in an administrator edited, disableAllHooks: true, a file policy superseded by policyHelper, or a higher-precedence HKLM policy. In those environments, add the DefenseClaw hooks to the policy source that wins (server-managed, then HKLM/MDM, then the Program Files file, then HKCU).
  • The policy file existing is not proof that it takes effect. Use the proof step in Claude Code proof and security_complete.

To remove one user's already-owned registration after disabling their row and reconciling, an elevated administrator can run the installed gateway:

& $Gateway enterprise hooks uninstall --user alice --connector claudecode --json

If the account is gone, pass the recorded --sid S-1-5-21-... instead of --user. The per-user runtime files stay behind, inert.

For the standalone profile, see Machine policy.

Install on macOS

The Secure Client module runs as root LaunchDaemons, because the machine-identity provider needs root. There is no dedicated defenseclaw service user on macOS. The gateway bundle (defenseclaw-macos-<version>-darwin-arm64) carries the module's install.sh and uninstall.sh and the three plists. For an administrator-staged config and manifest:

sudo ./packaging/launchd/install-enterprise.sh \
  --binary ./defenseclaw \
  --config /path/to/approved-config.yaml \
  --manifest /path/to/approved-targets.yaml

It is idempotent, checks the root-owned path chain, snapshots the deployment before replacing files, and on a failure restores the previous state. --no-start installs without loading the jobs. Check the daemons:

sudo launchctl print system/com.cisco.secureclient.defenseclaw
sudo lsof -nP -iTCP:18970 -sTCP:LISTEN

Owners, modes and logs are in the macOS LaunchDaemon layout. To change the config, edit it and restart both daemons (restart-required controls).

Native Windows Claude Code managed hooks

Claude Code is enrolled through machine policy (C:\Program Files\ClaudeCode\managed-settings.d\90-defenseclaw.json), not by editing ~/.claude/settings.json. See Native Windows Claude Code managed hooks.

macOS LaunchDaemon layout

On macOS the Secure Client module runs as root LaunchDaemons, because the machine-identity provider needs root to read its credential store. There is no dedicated defenseclaw service user on macOS. The standalone macOS package is different (it runs the gateway as _defenseclaw under /opt/cisco/defenseclaw); see macOS standalone deployment.

LaunchDaemonRunsPurpose
com.cisco.secureclient.defenseclawThe gateway, as rootInspection, policy, audit, hook API and health
com.cisco.secureclient.defenseclaw.hook-guardianenterprise hooks watch, as root, KeepAliveWatches the enrolled footprints and reconciles every 60 seconds
com.cisco.secureclient.defenseclaw.hook-enumeratorrender-targets.sh, every 300 secondsRewrites the target manifest from the local users
PathOwnerMode
/opt/cisco/secureclient/defenseclawroot:wheel0755
/opt/cisco/secureclient/defenseclaw/bin/defenseclaw-gatewayroot:wheel0755
/opt/cisco/secureclient/defenseclaw/etcroot:wheel0755
/opt/cisco/secureclient/defenseclaw/etc/config.yamlroot:wheel0640
/opt/cisco/secureclient/defenseclaw/runtimeroot:wheel0750
/opt/cisco/secureclient/defenseclaw/hook-guardianroot:wheel0750
/opt/cisco/secureclient/defenseclaw/hook-guardian/targets.yamlroot:wheel0640
/opt/cisco/secureclient/defenseclaw/hook-guardian-stateroot:wheel0750
/Library/Logs/Cisco/SecureClient/DefenseClawroot:wheel0750
/Library/LaunchDaemons/com.cisco.secureclient.defenseclaw*.plistroot:wheel0644

The gateway bundle (defenseclaw-macos-<version>-darwin-arm64) carries the module's install.sh and uninstall.sh and the three plists. For an administrator-staged config and manifest, the release also ships packaging/launchd/install-enterprise.sh, which installs the gateway and guardian daemons:

sudo ./packaging/launchd/install-enterprise.sh \
  --binary ./defenseclaw \
  --config /path/to/approved-config.yaml \
  --manifest /path/to/approved-targets.yaml

It is idempotent, refuses symlinked sources and destinations, checks the root-owned path chain, keeps runtime state across reinstalls, and verifies the owners and modes above before launchd starts a job. The runtime directory is the config's data_dir, and hook-guardian-state holds the authorization ledger. Before replacing files it snapshots the deployment and records which jobs are loaded. A failure after jobs are stopped restores the previous binary, config, manifest, and plists, then re-bootstraps only the jobs that were loaded before. --no-start installs without loading the jobs.

launchd has no equivalent of the Linux systemd sandbox. Protect the module with code-signing and notarization policy, MDM file ownership, Endpoint Security or EDR, and restricted local administrator membership.

Verify:

sudo launchctl print system/com.cisco.secureclient.defenseclaw
sudo launchctl print system/com.cisco.secureclient.defenseclaw.hook-guardian
sudo lsof -nP -iTCP:18970 -sTCP:LISTEN
sudo tail -n 100 /Library/Logs/Cisco/SecureClient/DefenseClaw/gateway.err.log
sudo tail -n 100 /Library/Logs/Cisco/SecureClient/DefenseClaw/hook-guardian.err.log

Endpoint health report

From 1.0.10, about every 30 minutes the gateway sends Cisco AI Defense an endpoint health report and writes the last one to diagnostics/health_report_last.json under its data_dir (runtime). Run elevated (as root on macOS), enterprise windows status --json and enterprise macos status --json summarize it in a health_report object. The object is absent until the first report:

FieldMeaning
statushealthy, degraded, unhealthy or starting
observed_at, built_atWhen the report was built and written (RFC 3339 UTC)
sequence, triggerReport number, and startup, scheduled or config_reload
reason_codesThe report's reason codes, such as HOOKS_PARTIAL
deliveryresult (queued, not_routed or failed), at, failure_class, cloud_state
staleMore than three report intervals passed since observed_at: the gateway stopped reporting
errorunreadable, access_denied or invalid: the file exists but could not be used

The text output adds one line, such as Health report: degraded (HOOKS_PARTIAL) at 2026-11-12T11:30:00Z, delivery queued. The report never changes ok, warnings or the exit code, and verify does not check it. Read status, stale and delivery.result to find a device that needs attention. The gateway sends nothing until the Cisco AI Defense endpoint is configured.

Restart-required controls

In managed mode, config.yaml is the only live configuration source. Hot reload applies only observability, sink, webhook, notification and identity-metadata fields. Connector topology, listeners, scanners, policies and other enforcement settings need a service restart; gateway.config_reload.mode: restart makes that the default. Apply a change through the administrator channel:

  • Windows. /repair CONFIG=... MANIFEST=... with the Setup, then /verify. Do not use the per-user CLI or HTTP PATCH.
  • macOS. Edit the config, then restart both daemons:
sudoedit /opt/cisco/secureclient/defenseclaw/etc/config.yaml
sudo launchctl kickstart -k system/com.cisco.secureclient.defenseclaw
sudo launchctl kickstart -k system/com.cisco.secureclient.defenseclaw.hook-guardian

For the standalone profile, see Change the config.

Sandbox policy pushdown

The openshell.admin block is documented in Sandbox policy pushdown. The keys added for sandboxes on managed computers (required_for, when_unavailable, user_approvals, allowed_credentials, on_silence, process_tree and the other keys of the standalone sandbox policy) are refused in this profile when the config loads, as is a sandbox section in a guardrail profile. Those belong to the standalone profile (see Sandboxes on managed computers); the Secure Client behavior of openshell.admin is unchanged. In the Secure Client profile, apply a change to it as shown in Restart-required controls; on macOS the gateway reloads the openshell block without a restart.

Troubleshooting

SymptomLikely causeWhat to do
security_complete is false on WindowsClaude Code is enabled and its proof is not recorded, or no supported target is enabledRecord the Claude Code proof
One user's target failsNo active session, missing native config, or a foreign-owned file in the footprintRead the error in enterprise hooks status --json; fix the file's provenance
HTTP 401 from one connector's hookIts scoped token is missing or driftedRun /repair or a reconcile
AI Discovery reports sensor helper (not started)DefenseClawSensorHelper is stopped or its socket DACL is unhealthyRun /verify, then /repair
The per-user installer or defenseclaw upgrade refusesA managed deployment existsUpdate through Secure Client (Managed command availability lists the commands a managed computer refuses)

Exit codes and error codes shared with the standalone profile are in Troubleshooting. If an AI agent gained administrator rights, treat the endpoint as compromised (Contain an incident).

Production checklist

  • AI agent users are standard users without administrator rights or passwordless sudo.
  • The Setup and its eight inner files are the signed release; the broker uses the signed Secure Client provider library.
  • The config, manifest and ledger have administrator-only path chains.
  • The enumerator's manifest lists only expected users and approved connectors.
  • The first reconcile succeeds for every enabled target before any connector moves to action mode.
  • On Windows, the Claude Code proof is recorded and security_complete is true.
  • Monitoring alerts on guardian errors, connector errors, repeated repair and enforcement downgrade.
  • Allowed and blocked tool calls, and the measured hook-repair time, are recorded for the deployed version.
  • MDM or EDR locks native agent config where repair-after-tamper is not enough.
  • Upgrades and incident response use an administrator channel the AI agent cannot reach.