macOS standalone deployment
Install the standalone DefenseClaw enterprise LaunchDaemons on Apple silicon Macs from the pkg or the payload tarball, check the result, and remove them.
The standalone macOS profile installs DefenseClaw machine-wide under
/opt/cisco/defenseclaw, with LaunchDaemons labeled com.cisco.defenseclaw.* and
a hidden service account, _defenseclaw. It is separate from the Cisco Secure
Client module and refuses to install beside it. Standard users cannot stop the
daemons 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 Mac from an administrator shell. For Jamf Pro, Iru, Intune, Workspace ONE or another MDM, start with Install with an MDM. It uses the same pkg and config.
Requirements
| Requirement | Detail |
|---|---|
| macOS | 13.0 or later. The pkg refuses older versions |
| Hardware | Apple silicon only. Releases build no Intel macOS binaries |
| Privileges | root, through sudo or an MDM agent. Every enterprise macos action, status included, needs root |
| Other profiles | No Secure Client DefenseClaw module. The pkg's pre-install script refuses when /opt/cisco/secureclient/defenseclaw or a com.cisco.secureclient.defenseclaw* LaunchDaemon exists |
| Gatekeeper | Releases currently ship the pkg unsigned, pinned by checksums.txt (details) |
Gatekeeper
Only the pkg can be Developer ID-signed and notarized, and it is signed only when the release pipeline has Apple signing credentials. Releases currently ship it unsigned, pinned by checksums.txt. The tarball's binaries are never Developer ID-signed. On Macs that require notarized software, check the pkg first with spctl --assess --type install --verbose=2 <pkg>. Releases currently ship the pkg unsigned, so pkgutil --check-signature reports "no signature"; its SHA-256 in checksums.txt, whose cosign signature you check, protects it.
Layout
Paths are under /opt/cisco/defenseclaw unless shown in full.
| Item | Path | Owner and mode |
|---|---|---|
| Binaries | bin: defenseclaw-gateway, defenseclaw-hook, defenseclaw-sensor-helper, and defenseclaw-acp when present | root, 0755 |
| Managed OpenCode plugin | share/opencode/index.js | root, 0644 |
| Config | etc/config.yaml | root:_defenseclaw, 0640 |
| Policies | etc/policies | root:_defenseclaw, 0750 |
| Secrets | etc/secrets | Directory root:_defenseclaw 0750, files 0640 |
| Target manifest | etc/hook-guardian/targets.yaml (the enumerator writes it) | Directory root:_defenseclaw, 0750 |
| Runtime descriptor | etc/managed-runtime.json | root, 0644 |
| Machine-policy summary | etc/machine-policy.json | Readable by users |
| Lifecycle state | lifecycle: last-package-result.json, last-activation-failure.log, the last applied and a rejected config | root, 0700 |
| Gateway data | runtime | _defenseclaw, 0700 |
| Authorization ledger | hook-guardian-state, with each user's latest AI Discovery scan in ai-discovery/ | root:_defenseclaw, 0750 |
| Hook socket | run/hook.sock | Directory _defenseclaw, 0755 |
| Logs | /Library/Logs/Cisco/DefenseClaw, gateway logs in gateway/ | root, 0755; gateway/ is _defenseclaw, 0750 |
| LaunchDaemons | /Library/LaunchDaemons/com.cisco.defenseclaw.*.plist | root, 0644 |
| Sandbox launcher | /usr/local/bin/defenseclaw, a link to defenseclaw-gateway that offers users only the commands in Managed command availability | root, 0755 |
| Sandbox LaunchAgents | /Library/LaunchAgents/com.cisco.defenseclaw.sandbox.<tag>.plist and com.cisco.defenseclaw.openshell-gateway.<tag>.plist, run as each signed-in user. <tag> is the first 12 digits of the gateway binary's SHA-256, so each upgrade installs both agents under new labels and removes the plists of the earlier labels; releases before 1.0.4 used the labels without a tag (Sandboxes) | root, 0644 |
| Sandbox state | runtime/sandbox/, and etc/openshell/gateway.toml when enterprise.openshell is set | _defenseclaw, 0600 files; root |
The gateway runs as _defenseclaw, a hidden account and group the lifecycle
creates with dscl (the highest free id from 300 to 499, shell /usr/bin/false,
home /var/empty). Everything else runs as root.
| Label | Runs as | What it does |
|---|---|---|
com.cisco.defenseclaw.gateway | _defenseclaw | Policy engine and hook API. Serves 127.0.0.1:18970, which launchd holds for it, and binds run/hook.sock |
com.cisco.defenseclaw.hook-guardian | root | Always running. Reconciles each user's hooks every minute through a worker that runs as that user, which also runs the user's AI Discovery scan. Every 5 seconds it checks the hook binary and Claude Code's 90-defenseclaw.json drop-in; if either is gone or changed it logs tamper: and starts com.cisco.defenseclaw.apply, whose ensure puts them back |
com.cisco.defenseclaw.hook-enumerator | root | Rewrites the target manifest every five minutes (in auto enrollment mode) |
com.cisco.defenseclaw.sensor-helper | root | Answers the gateway's fixed AI Discovery requests |
com.cisco.defenseclaw.apply | root | Runs ensure --reason path when etc/config.yaml, etc/secrets or etc/policies changes |
com.cisco.defenseclaw.verify | root | Runs verify daily at 03:17 local time |
List view for small screens. Use the expand button to open the drawing.
TrustedZ0 · Admin and OS (root)
- launchdstarts the daemons
- starts as _defenseclawGatewayZ2
UntrustedZ4 · User session (the user)
- AI agentruns as the user
- runs per tool calldefenseclaw-hook
- defenseclaw-hookchecks the socket owner
- asks over hook.sockGatewayZ2
RestrictedZ2 · Gateway (_defenseclaw)
- Gatewayallows or blocks
Unlike systemd on Linux, launchd does not hold the sockets for the gateway:
launchd hands sockets over only through launch_activate_socket(3), which needs
cgo, and release builds are built without cgo. The protected socket directory and
the hook's owner check do the same job.
List view for small screens. Use the expand button to open the drawing.
PrivilegedZ1 · Services (root)
- Enumeratorlists the users
- writesTarget manifestZ3
- Guardianchecks every minute
- readsTarget manifestZ3
- starts, as the userPer-user workerZ4
ProtectedZ3 · Admin-owned files
- Target manifesttargets.yaml
UntrustedZ4 · User session (the user)
- Per-user workerruns as the user
- repairs hooksAgent config
- Agent configin the user's home
Install
Stage the config first, then install the pkg or the tarball.
1. Get and check the release
Download defenseclaw-enterprise-<version>-darwin-arm64.pkg (or the .tar.gz),
checksums.txt and checksums.txt.bundle from one GitHub release. Check the
signature on checksums.txt with cosign,
then the file against it:
VERSION=1.0.4 # the release you deploy
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
grep " defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg\$" checksums.txt | shasum -a 256 -cPin that SHA-256 in your MDM. pkgutil --check-signature reports "no signature"
on the unsigned pkg; the checks above are what protect it.
2. Stage the config
Write the config as config_version: 9. ensure also takes a config_version: 8
file: it migrates it to 9, keeps config.yaml.v8.bak and migration-v9.json, and
warns config_version_8. It refuses any other version with config_invalid.
The lifecycle requires deployment_mode: managed_enterprise,
enterprise.profile: standalone and data_dir: /opt/cisco/defenseclaw/runtime. If
you set gateway.api_bind or gateway.api_port, they must be 127.0.0.1 and
18970.
config_version: 9
deployment_mode: managed_enterprise
data_dir: /opt/cisco/defenseclaw/runtime
policy_dir: /opt/cisco/defenseclaw/etc/policies
enterprise:
profile: standalone
gateway:
api_bind: 127.0.0.1
api_port: 18970
guardrail:
enabled: true
mode: observe
connectors:
codex: {}
claudecode: {}
ai_discovery:
enabled: trueAI Discovery is off unless the config sets ai_discovery.enabled: true, as above. Each key under guardrail.connectors turns on one agent
(choose the agents).
Without a config the pkg installs a default that protects nothing.
sudo install -d -o root -g wheel -m 0755 /opt/cisco/defenseclaw/etc
sudo install -o root -g wheel -m 0640 config.yaml /opt/cisco/defenseclaw/etc/config.yaml3a. Install the pkg
sudo installer -pkg "defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg" -target /
sudo cat /opt/cisco/defenseclaw/lifecycle/last-package-result.jsonThe post-install script runs enterprise macos ensure --from-package: it creates
_defenseclaw, validates the config, writes and starts the LaunchDaemons, verifies,
and rolls back on any failure. A failed apply fails the pkg install, and
/var/log/install.log names the first error. No pkg? Use the
tarball. Exit codes of the
lifecycle: 0 success or nothing to do, 1 failed (rolled back), 2 invalid
arguments, 75 another run holds the lock.
How the pkg install works
The pkg installs the binaries and its post-install script runs
enterprise macos ensure --from-package --reason package --json: it creates
_defenseclaw, validates the config, lays out the files, writes the LaunchDaemons,
starts them in order, verifies, and rolls back on any failure. A failed apply fails
the pkg install, so installer and your MDM report it. The result is in
last-package-result.json, and /var/log/install.log names its first error. Fix
it, then install the pkg again. The pkg receipt is
com.cisco.defenseclaw.enterprise; a failed install records none, and
ensure --from-package records none either, so receipt-based inventory reports the
Mac as not installed until the pkg installs successfully.
If you did not stage a config, the pkg installs the default, which protects
nothing. Copy your config to /opt/cisco/defenseclaw/etc/config.yaml and the apply
daemon runs ensure, or run it yourself:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ensure \
--from-package --config "$PWD/config.yaml" --json3b. Or install from the tarball
The payload folder and its binaries must be owned by root and not writable by group or others:
VERSION=1.0.4 # the release you deploy
PAYLOAD="/var/root/defenseclaw-enterprise-${VERSION}"
sudo install -d -o root -g wheel -m 0700 "$PAYLOAD"
sudo tar -xzf "defenseclaw-enterprise-${VERSION}-darwin-arm64.tar.gz" \
-C "$PAYLOAD" --no-same-owner --no-same-permissions
sudo chmod -R go-w "$PAYLOAD"
sudo "$PAYLOAD/defenseclaw-gateway" enterprise macos ensure --payload "$PAYLOAD" --jsonensure installs when nothing is installed, applies a different payload,
re-applies a changed config, repairs a deployment that fails verification, and
otherwise does nothing. Add --config <absolute path> for a config elsewhere and
--no-start to stage with the daemons stopped. A hand-built layout stops the
install with unmanaged_layout_present; --adopt-existing backs it up and takes it
over.
| Code | Meaning |
|---|---|
0 | Success, or nothing to do |
1 | Failure. A failed install, upgrade or repair is rolled back, and a refusal before any change leaves the computer as it was. For status and verify, the deployment is unhealthy |
2 | Invalid arguments |
75 | Another lifecycle run holds the lock. Retry later |
4. Add the AI Defense key
Optional. Set enterprise.inspection.ai_defense.enabled: true and
credential: ai-defense-api-key in the config, then store the key:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set \
--name ai-defense-api-key --from-file /var/root/ai-defense.key --json
sudo rm /var/root/ai-defense.keyRotation: AI Defense key.
Verify the install
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify --json
pkgutil --pkg-info com.cisco.defenseclaw.enterprise # pkg installs onlystatus reports the state. verify also checks every file, permission (including
macOS ACL entries), LaunchDaemon and readiness check, and exits 1 when anything
fails. repair removes only the ACL entries that are wrong: one that lets another
account change a DefenseClaw file or reach a private one, or that keeps the
_defenseclaw service account from reading etc/policies and the packs in it. Other entries
stay. The JSON has the same shape as the Linux sample.
| 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 when the enabled hooks are installed |
security_complete | false with Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity enabled; hook_process_fail_open warns that a stopped, killed or timed-out hook can let a tool run |
policy | applied is true (digest) |
enrollment.targets | Per-user targets. 0 is normal when you enable only machine-policy connectors |
With no agent enabled, status warns no_connectors_enabled and verify fails.
The enumerator enrolls accounts with uid 501 or higher by default
(Enrollment). To reconcile at once:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json.
The gateway log is /Library/Logs/Cisco/DefenseClaw/gateway/gateway.err.log.
Status details
When the config enables no agent while there are users to enroll, status warns
no_connectors_enabled, verify fails and security_complete is false. Neither
field checks that the expected users are enrolled, so check enrollment too. The
enumerator enrolls accounts with a uid of 501 or higher by default
(Enrollment). To reconcile at once:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json.
agent_settings_not_restored warns when the guardian puts back a missing Hermes
config.yaml or Devin config.json from a last good copy or recreates it with
hooks only; it does not make security_complete false or fail verify, the exit
code or MDM detection (see Warnings).
A guardrail.profile_assignments group this Mac does not know selects nobody, so
its members get the default profile; status and verify warn
profile_assignment_unmatched, with the same list enterprise macos profile-explain --user <account> --connector <connector> shows. The gateway log is
/Library/Logs/Cisco/DefenseClaw/gateway/gateway.err.log. The managed launcher offers only
defenseclaw guardrail profile explain (Managed command availability). Monitoring is in
Status and verify.
Claude Cowork
Claude Cowork runs its agent loop on the Mac, as the user, with the Claude Code engine that Claude Desktop bundles. The Claude Code drop-in (/Library/Application Support/ClaudeCode/managed-settings.d/90-defenseclaw.json) is meant to cover it. There is nothing to configure for Cowork itself.
| Item | macOS |
|---|---|
| Measured | Test hooks in managed settings and in a managed-settings.d drop-in ran in Cowork turns on Claude Desktop 4.4212.0, and a deny held. In the 1.0.8 tests on a managed Mac 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), and DefenseClaw recorded the secret after the read; to prevent such a read, deny the path at PreToolUse (Secrets in tool results). With managed_hooks_only: enforce an organization plugin's hooks did not run, with preserve they did, and DefenseClaw's hooks ran under both. With the gateway service stopped, Cowork prompts were blocked with enterprise_managed_gateway_not_running |
| Organization plugins | Claude Desktop 4.16336.0 installs a plugin in /Library/Application Support/Claude/org-plugins/ only when its .claude-plugin/plugin.json sets "installationPreference": "required"; otherwise it is only listed as available |
| Engine folder | ~/Library/Application Support/Claude/claude-code/<version>/, or Claude-3p instead of Claude for third-party inference. DefenseClaw trusts it by Anthropic's Developer ID signature, checked as the user with codesign, and by an Info.plist version equal to the folder |
| Shell | Runs in the Cowork Linux VM on the Mac |
See Claude Cowork for the tools, managed_hooks_only and the limits.
Sandboxes
A macOS standalone install can run coding agents in OpenShell MicroVM sandboxes on
Apple silicon, under the sandbox policy of each person's directory group. They are
off until openshell.enabled is on. The pkg packages the defenseclaw launcher
and the LaunchAgents, which stay in place while sandboxes are off and leave with
uninstall; you provide OpenShell or let each person's daemon download it
(install: setup). The pkg supplies a MicroVM e2fsprogs fallback; set the
root-owned enterprise.openshell.e2fsprogs_dir to use your own tools. Docker
Desktop must run for the person, because the agent images are built there. An
Intel Mac is refused with os_unsupported. Write directory groups in the spelling
macOS reports (DOMAIN\group) and check them with profile-explain. Keys and
recipes are in Sandboxes on managed computers.
Per-user installs
On a Mac with /opt/cisco/defenseclaw/etc/managed-runtime.json the per-user
product refuses to run: the current install.sh (the one-line installer) refuses
and changes nothing, even when the managed launcher is on the user's
PATH; defenseclaw upgrade refuses (Managed command availability); and the per-user gateway refuses to start.
Installers from 0.8.x predate the managed marker and do not check for it, so a
user can still run one after you deploy. It installs a per-user copy, but the
managed gateway keeps enforcing: the per-user copy cannot start its own gateway,
because the managed gateway holds the port. Ask the user to run
defenseclaw uninstall --binaries --yes.
A 0.8.x installer can also stop with "existing installation detected" and tell
the user to run defenseclaw-upgrade.sh. That text is not meant for managed Macs;
do not follow it. On a managed Mac, upgrades come from your deployment, not from
the upgrade resolver.
Nothing migrates a per-user install. Before you deploy, have each user run
defenseclaw uninstall --binaries --yes (add --all to delete ~/.defenseclaw;
Uninstall). 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.
A config.yaml a per-user install left in ~/.defenseclaw is not the policy the
device enforces. The installed managed defenseclaw launcher shows the account's
own connectors with status, and offers sandbox and guardrail profile views; the full list is in Managed command availability.
It refuses doctor, alerts, tui and per-user configuration commands with exit
2, naming the installed administrator status, verify and audit export commands.
A separate per-user CLI, if present, exits 3 for per-user commands and its
doctor reports the device as managed.
A per-user gateway still running holds the managed port 127.0.0.1:18970 unless
its user moved it. The pkg install then stages the package files, but the
postinstall refuses the managed deployment before applying it, with
api_port_held. installer -pkg prints a generic postinstall failure and records
no package receipt, so detection reports the computer as not installed. The process
and kill command appear in /var/log/install.log, the error is in
last-package-result.json, and enterprise macos status --json also reports the
holder. Stop that gateway or move it, then run installer -pkg again (or
/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ensure --from-package, which records no
receipt). A per-user gateway on another port keeps running; the install, status
and verify name each such account with per_user_gateway_running.
Scan skills, MCP servers and plugins
The package installs the skill, MCP and plugin scanners. An administrator scans with the gateway's scanners, policy and judge:
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway scan skill /opt/defenseclaw-scan/my-skill
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway scan plugin /opt/defenseclaw-scan/my-plugin
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway scan mcp https://mcp.example.com/mcpThe scan runs through the managed gateway, and only an administrator can read its token, so run
it with sudo. The gateway service cannot read user folders (/Users, /var/root); a folder in /tmp is scanned. Copy the folder to one that every account can read, such as
/opt/defenseclaw-scan, and scan the copy. A refused scan exits 3 and says Nothing was scanned. A deployment installed from the payload archive has no scanner runtime: install the
package to scan.
Remove
Run these as root from /opt/cisco/defenseclaw/bin.
| Goal | Command |
|---|---|
Stop and remove the deployment, its binaries, config, secrets and logs, most of its data and lifecycle state, and the _defenseclaw account. Each user keeps ~/.defenseclaw. When an account keeps sandboxes, /opt/cisco/defenseclaw/runtime/sandbox and /opt/cisco/defenseclaw/runtime/redaction-correlation.key stay with the root-only records /opt/cisco/defenseclaw/lifecycle/openshell-state.kept.json and /opt/cisco/defenseclaw/lifecycle/retained-state.json and the marker /opt/cisco/defenseclaw/runtime/.defenseclaw-retained. They are root-owned while the service account is gone; the next ensure adopts them | /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --json |
Also remove each enrolled user's ~/.defenseclaw and per-user binaries | /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --purge --json |
| Keep the config, secrets, data and logs (and the account) for a reinstall | /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --keep-state --json |
Keep only the _defenseclaw account | Add --keep-service-account |
Uninstall removes each user's DefenseClaw hook registrations and DefenseClaw's own
machine-policy entries first; administrator entries stay. Use --purge for a clean
image. With --purge it also stops each enrolled user's per-user gateway and
removes ~/.defenseclaw, the empty agent folders DefenseClaw created, the
per-user binaries in ~/.local/bin and DefenseClaw's wheels in ~/.cache/uv. If an enrolled account had its own DefenseClaw install before the enrollment (its ~/.defenseclaw holds config.yaml, .env, audit.db, previous/, or the program the per-user installer puts there, .venv/ or installer/, also when the account never ran defenseclaw init), --purge leaves that folder and the install's binaries exactly as they are and names the account in the result (kept the DefenseClaw per-user data of user <name> ... and a per_user_state_remaining warning). A machine uninstall never deletes or moves an account's own data. The purge first moves the backups an earlier release saved for a connector it removed (connector_backups/openhands and connector_backups/omnigent) to ~/.defenseclaw-removed-connector-backups, and stops without deleting anything if it cannot. Accounts the deployment never enrolled keep their DefenseClaw files (an earlier per-user install, or hooks a former enrollment left). The purge result lists each such account on a kept: warning; delete those files with the account's owner. An account the machine policy covered without a per-user enrollment (not named in the enrollment manifest) is purged the same way when its ~/.defenseclaw holds only what DefenseClaw wrote there (hook scripts, hook tokens and settings, connector backups, also those an earlier failed install left); when it holds the account's own install, the account is named as above. The managed deployment shares ~/.defenseclaw with such an own install. The uninstall, with or without --purge, puts back what the enrollment changed there: the install's hook scripts and hook settings, connector backups, hook contract lock and session cache, byte for byte, and each agent config those backups name when the uninstall left that file as it was before the own install. An agent config that changed while the computer was managed stays as it is and is named in a per_user_state_remaining warning; that user runs defenseclaw setup again if its hooks are missing. The result's kept: line names accounts that
keep data. Pass --purge in the same run as the uninstall: uninstall deletes the
list of enrolled accounts, so a later --purge is a no-op (not_installed). To
clean up afterward, delete ~/.defenseclaw by hand, or install again and run
uninstall --purge. macOS lets only a process with Full Disk Access delete the
_defenseclaw account. Run from an ssh session or an MDM agent without it, the
delete is refused (eDSPermissionError) and the uninstall still completes with a
service_account warning carrying the two dscl commands; run them from a
Terminal or MDM script that has Full Disk Access (or grant it with a PPPC profile).
A pkg has no uninstaller, so the lifecycle removes the binaries itself. The
root-owned lifecycle/lifecycle.lock remains so waiting runs share one lock. For a
pkg install it also runs pkgutil --forget com.cisco.defenseclaw.enterprise.
Uninstall also removes the shared folders the deployment created, such as /opt,
/opt/cisco, /usr/local/bin and /Library/Logs/Cisco, once they are empty. A
folder that existed before the install stays, empty or not. A deployment installed
before 1.0.9 did not record /opt, /opt/cisco, /usr/local and /usr/local/bin,
so those stay until you remove them.
launchd keeps a record for each removed label, so launchctl print system lists
the labels as enabled while no job stays loaded. macOS also keeps any privacy
(TCC) decision about the gateway binary, such as Full Disk Access; remove it in
System Settings > Privacy & Security > Full Disk Access, or remove the MDM PPPC
profile that granted it.
Upgrades and changes
- Upgrade. Install the newer pkg, or run
ensurewith the newer tarball. An older pkg is refused unless the root-owned marker/opt/cisco/defenseclaw/lifecycle/allow-downgradeexists; the lifecycle refuses an older tarball unless you pass--allow-downgrade(Upgrade, Roll back). The firstensureof a new release migrates an olderconfig_versionand keepsconfig.yaml.v8.bakandmigration-v9.json. - Change the config. Replace
/opt/cisco/defenseclaw/etc/config.yaml. The apply daemon runsensure, which validates and applies it or rolls back (Change the config). In bundle mode the edit is reverted; deliver a new signed bundle. - Failures. See Lifecycle error codes.
Privacy prompts
The packaging ships no PPPC (Privacy Preferences Policy Control) profile. The
guardian works only in hidden dot-directories inside each user's home (~/.claude,
~/.codex, ~/.config), which macOS privacy controls (TCC) do not protect.
The per-user AI Discovery scan also walks the home for package manifests and model
files, and its inventory includes CLI binaries in /usr/local/bin,
/opt/homebrew/bin, /opt/local/bin, /opt/dc-agents/bin, ~/.local/bin and
~/bin (it checks executability without running them). Without Full Disk Access it
never opens the folders that make macOS ask the employee for permission: Desktop,
Documents, Downloads, Movies, Music, Pictures, iCloud Drive, other apps' data in
~/Library/Containers and ~/Library/Group Containers, and Contacts. No employee
sees a prompt attributed to defenseclaw-gateway. The scan summary is partial:
detector_errors.macos_privacy reports "protected folders were not scanned". Other
TCC-protected folders answer "operation not permitted" and are skipped the same way.
If your organization moves agent configuration into a TCC-protected folder, deploy
a PPPC profile that grants Full Disk Access (SystemPolicyAllFiles) to
/opt/cisco/defenseclaw/bin/defenseclaw-gateway, the one binary that runs the
gateway, the guardian and the enumerator. Identify it by its Developer ID code
requirement, which needs a signed build. With the grant the scan also reads those
folders; the gateway checks the grant every ten minutes.
AI Discovery Plane C (Endpoint Security)
AI Discovery runtime detection has three planes: A watches inference compute, B
attributes network traffic and C records agent actions from kernel events
(Runtime planes). Plane C
(ai_discovery.runtime.enable_host_plane: true with c in
ai_discovery.runtime.planes) reads process and file events through Apple's
eslogger, which the root sensor helper
(/opt/cisco/defenseclaw/bin/defenseclaw-sensor-helper) runs. launchd starts the
helper directly, so macOS treats it as the responsible process and it is the binary
that needs Full Disk Access. Without it, Endpoint Security refuses the client
(ES_NEW_CLIENT_RESULT_ERR_NOT_PERMITTED), Plane C reports running: false with
that reason, and the snapshot stays degraded; Planes A and B keep working. A
detached child of a terminal-launched agent can stay unattributed after it is
reparented to PID 1.
Grant the access with a PPPC payload (com.apple.TCC.configuration-profile-policy):
<key>Services</key>
<dict>
<key>SystemPolicyAllFiles</key>
<array>
<dict>
<key>Identifier</key>
<string>/opt/cisco/defenseclaw/bin/defenseclaw-sensor-helper</string>
<key>IdentifierType</key>
<string>path</string>
<key>CodeRequirement</key>
<string>(the designated requirement printed by codesign -dr - on that path)</string>
<key>Allowed</key>
<true/>
</dict>
</array>
</dict>The code requirement needs a signed build. On an unsigned test build, grant Full
Disk Access to that path by hand in System Settings, then restart the helper with
sudo launchctl kickstart -k system/com.cisco.defenseclaw.sensor-helper. A config
that carries enterprise.tetragon is accepted and ignored on macOS;
enterprise macos status --json and enterprise macos verify report tetragon_not_applicable; plain status does not print it.
Machine policy
For Codex, Claude Code, Cursor, GitHub Copilot and OpenCode, DefenseClaw adds its
hooks to the vendor's machine policy files under /etc and
/Library/Application Support (files).
An MDM configuration profile for com.openai.codex or com.anthropic.claudecode
outranks those files; export DefenseClaw's entries in plist form and add them to
your profile (Higher-precedence sources,
Inspect, export and verify).
After changing a vendor policy file or MDM preference, run
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json
(or ensure). Until the new policy view is verified and pinned, managed hooks
keep sending every call for inspection under the managed policy and the gateway
raises a HIGH runtime alert, enterprise_managed_policy_view_unverified. This includes
a per-user managed preference that appears when an account signs in. An MDM
agent that delivers the same preference bytes again changes nothing: pins
compare content only.
On a managed 1.0.2 macOS 15.8 test host, a standard user started Claude Code inside
a sandbox-exec profile that hid its machine policy directory. Claude ran a
Bash tool call, while the gateway recorded no matching call and administrator
status and verify still reported complete security. A hook cannot refuse
an agent that never loads it. Until agent launch and policy registration are
enforced outside that process-local view, a healthy result does not prove that
all Claude tool calls are inspected (M-34).
Tetragon on a Linux fleet
Roll DefenseClaw out to Linux computers that already run Tetragon - harden Tetragon, turn on Plane C, see your own policies' events from AI agents, observe, approve and enforce ring by ring, check the fleet, and troubleshoot - with tested Ansible and shell examples.
Install with an MDM
The contract every MDM recipe follows to deliver, run, detect, upgrade, reconfigure and remove the standalone DefenseClaw enterprise deployment on Windows, Linux and macOS.