Enterprise concepts
A glossary of the terms used in DefenseClaw's enterprise deployment docs, from profiles and the lifecycle to enrollment, machine policy, health fields, and the Windows, Linux, and macOS security terms.
Each entry names the OS it applies to when it is not all of them. Other pages link here the first time they use a term.
Deployment and profiles
managed_enterprise
The deployment_mode value for an administrator-owned deployment. Every service
starts with DEFENSECLAW_DEPLOYMENT_MODE=managed_enterprise, so a user's
environment or config cannot change it. A config without this mode is rejected
if it has an enterprise block.
Profile
Which decision stack a managed deployment uses: secure_client or standalone.
enterprise.profile sets it and DEFENSECLAW_ENTERPRISE_PROFILE pins it in
every service; the two must agree. Changing it means reinstalling. With neither
set, Windows and macOS use secure_client and Linux uses standalone.
Secure Client profile
The profile that Cisco Secure Client installs as one of its modules, on Windows
and macOS. Cisco AI Defense makes every decision and the local detectors are
off. The config allows only enterprise.profile. See
Secure Client managed deployment.
Standalone profile
The profile you install with any MDM, a package or an administrator shell, on Windows, Linux and macOS. The local policy engine decides, and Cisco AI Defense adds its verdict when you store an API key.
Install and update
Lifecycle
The actions that set up and maintain a deployment: install, upgrade,
repair, ensure, reconcile, status, verify and uninstall.
| OS | How you run it |
|---|---|
| Linux | /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux <action>, as root |
| macOS | /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos <action>, as root |
| Windows | & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows <action> --profile standalone from an elevated PowerShell prompt, or the Setup program (/install, /ensure and so on) |
The packages do not put defenseclaw-gateway on the PATH, so a fresh root
login shell answers a bare defenseclaw-gateway with command not found. Use
/opt/defenseclaw/bin/defenseclaw-gateway on Linux or
/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS, or add that folder to
the root shell's PATH. The defenseclaw launcher for users
(/usr/bin/defenseclaw on Linux, /usr/local/bin/defenseclaw on macOS) is on
every PATH.
Ensure
The one action an MDM runs. It installs when nothing is installed and applies any
difference in the payload, config, secrets (Linux and macOS), files or services.
When everything matches, it changes nothing and exits 0. Windows ensure
refuses to replace a newer version with an older one. See
What ensure does with the config.
On a Linux tarball host with fapolicyd, follow the staged-payload trust and two-stage flow before activating an install, upgrade or rollback.
Transaction and rollback
Every action that changes the computer runs as one locked transaction with a
snapshot. If a step fails before the change is committed, it restores the snapshot
(exit 1 on Linux and macOS, 1603 on Windows). If a step fails after the change
committed, for example when cleanup of the journal fails, nothing is rolled back:
the computer is installed (or removed) as asked and the run still exits 1 or
1603. Run Setup or ensure again to finish the cleanup. A run that finds the
lock held exits 75 (Linux, macOS) or 1618 (Windows).
Payload
The DefenseClaw programs a lifecycle action installs: the gateway, the hook and
the sensor helper. On Linux and macOS you pass --payload <directory> or use the
package's files (--from-package). On Windows the Setup program carries the
payload.
Payload manifest
Windows. An administrator-owned JSON file of the SHA-256 of every payload file, the anchor for hash-pinned trust. Setup writes the one it needs from its embedded copy.
Hash-pinned trust
Windows. The payload trust mode hash_pinned: every payload file must match
the SHA-256 in the payload manifest. Use it for unsigned
builds. It does not satisfy WDAC and AppLocker rules that
require a publisher signature. The Linux and macOS MDM wrapper has a mode of the
same name that checks the package against the SHA-256 you pass it.
Authenticode trust
Windows. The payload trust mode authenticode: every program and script must
carry a valid Authenticode signature, optionally from specific signers by
SHA-256 thumbprint. It is the default of defenseclaw.exe enterprise windows.
Policy and config
Admin config
The config.yaml that an administrator or an MDM installs, with the policy
assets it names by digest. It is the only policy a managed host enforces. See
Configure a standalone deployment.
Derived, evidence and runtime state
Files on a host fall into four kinds. See Configuration: one source of truth.
| Kind | Examples | Rule |
|---|---|---|
| Admin intent | config.yaml, the policy assets it names | Written only by the lifecycle on a managed host |
| Derived | Service definitions, the runtime descriptor, machine-policy entries, per-user hook scripts | Regenerated from the config. Never edited by hand |
| Evidence | config.generation.json, migration-v9.json, config.yaml.v8.bak, policy-state.json, committed-config.yaml, rejected-config.yaml, the audit database | Records of what was applied or decided. They never change policy |
| Runtime state | The enforcement journal for quarantine and runtime disable, approvals, discovery results | Reported, never policy |
Config writer
The one code path that writes config.yaml, in Go and in the defenseclaw CLI.
It takes config.yaml.lock, validates, writes atomically and records the write
and its actor in config.generation.json. On a managed standalone host it
refuses every actor but lifecycle and migration, so a per-user defenseclaw config set
exits 3 there (on Linux and macOS the packaged defenseclaw refuses it first, with exit 2; see Managed command availability). See
Policy changes on a managed host.
Config generation
A counter in config.generation.json that the config writer increases on every
write. The file also holds the SHA-256 of the written bytes, the actor, a short
reason and the time. A mismatch means the config was edited outside the writer.
Effective policy digest
sha256: and the hash of the canonical config and the policy assets it names.
The gateway stamps it on /health, /status and decision events. The lifecycle
reports it as policy.effective_digest, with policy.applied saying whether the
running gateway reports the same value. See
Effective policy digest.
Committed config and rejected config
committed-config.yaml is a root-only copy of the last config a lifecycle
transaction applied. When a run rejects an in-place edit, the lifecycle restores
the committed copy and keeps the edit as rejected-config.yaml. See
Edits made on the host.
Managed environment policy
On a managed standalone host, each DEFENSECLAW_* variable's managed setting
(allow, ignore or tighten_only) decides whether the environment can change
it. See Policy changes on a managed host.
Release trust root
The identity that signs every release: the Release workflow of the DefenseClaw
repository on main. A mirror set in update.source changes where bytes come
from, never who must have signed them. See
Where releases come from.
Services
Gateway
The service that checks each agent event against policy and answers allow or
block. On Linux and macOS it runs as a dedicated account, never as root:
defenseclaw on Linux, _defenseclaw on macOS. On Windows it runs as LocalSystem
with a write-restricted service SID (NT SERVICE\DefenseClawGateway), so it can
write only its own runtime and log folders. It listens on 127.0.0.1:18970, and on Linux and
macOS also on the hook socket. It reads the config and policies but cannot
change them.
Hook
defenseclaw-hook (defenseclaw-hook.exe on Windows). An administrator-owned
program that the agent runs, as the user, for each hook event. It verifies the
listener is the real gateway, sends the event and returns the decision. On Linux
and macOS, vendor machine policy registers it as
<bin>/defenseclaw-hook hook --connector <name> --enterprise-managed.
Guardian
The hook guardian service, running as root or LocalSystem. Every minute it writes DefenseClaw's hook into each enrolled user's agent config and repairs it. It never writes a user's files with its own rights: Linux and macOS use a worker that runs as the user, and Windows uses the user's token, so only while the user is signed in. It also keeps the authorization ledger.
Enumerator
The hook enumerator service, running as root or LocalSystem. Every five minutes it lists the users, applies the enrollment settings and publishes the target manifest.
Sensor helper
A small privileged service that answers a fixed set of AI discovery questions for the gateway. The gateway cannot name a path, process or command for it to read.
Service names by OS
| Part | Windows | Linux (systemd) | macOS (launchd) |
|---|---|---|---|
| Gateway | DefenseClawGateway, LocalSystem write-restricted by its NT SERVICE\DefenseClawGateway service SID | defenseclaw-gateway.service, as defenseclaw with no capabilities. systemd holds its sockets | com.cisco.defenseclaw.gateway, as the hidden _defenseclaw user |
| Guardian | DefenseClawHookGuardian, LocalSystem | defenseclaw-hook-guardian.service, root with a bounded capability set | com.cisco.defenseclaw.hook-guardian, root |
| Enumerator | DefenseClawHookEnumerator, LocalSystem | defenseclaw-hook-enumerator.service, root with a bounded capability set | com.cisco.defenseclaw.hook-enumerator, root |
| Sensor helper | DefenseClawSensorHelper, LocalSystem | defenseclaw-sensor-helper.service, root | com.cisco.defenseclaw.sensor-helper, root |
| Applies a config change | Your MDM runs ensure again | defenseclaw-enterprise-apply.path runs ensure when the config, secrets or policies change | com.cisco.defenseclaw.apply does the same |
| Daily check | Your MDM runs detection or verify | defenseclaw-enterprise-verify.timer | com.cisco.defenseclaw.verify, at 03:17 local time |
On Linux and macOS, hooks and DefenseClaw's in-agent plugins reach the gateway only
through the hook socket (/run/defenseclaw-hook/hook.sock on Linux,
/opt/cisco/defenseclaw/run/hook.sock on macOS). The kernel tells the gateway each
caller's uid, and there is no TCP fallback. On Windows they use loopback with
credentials bound to the user's SID.
Users and state
Enrollment
Choosing which users DefenseClaw manages. The enumerator adds a user for an agent
only after it finds a supported install of that agent for that user. On Linux and
macOS enrollment governs per-user connectors, and
machine-policy connectors only with unenrolled_users: deny. On Windows it
governs every connector: a user who is not enrolled has their hook calls refused.
See Enrollment.
Target manifest
targets.yaml: the (user, agent) pairs the guardian manages, with each user's
home and agent version. The enumerator writes it. The exception is
enterprise.enrollment.mode: manifest on Linux, macOS and Windows, where the
administrator supplies it.
Authorization ledger
The guardian's record of which user is enrolled for which agent. Only the guardian writes it, and the gateway reads it. On Linux and macOS the gateway checks each hook call's kernel-reported uid against it. Status and verify count the guardian ready only when its credential attestation matches the current ledger and manifest; an old success never counts.
Runtime descriptor
managed-runtime.json. A public, non-secret file the lifecycle writes with the
profile, version, gateway account, API address, hook socket and machine-policy
agents. Hooks read it to know which listener to trust. The per-user installer,
defenseclaw upgrade and the per-user gateway refuse to run where it exists.
Agents and hooks
Per-user connector
An agent whose hooks live in each user's own config because the vendor has no administrator-owned hook location. The guardian writes and repairs DefenseClaw's entry for every enrolled user. Devin, Antigravity, Hermes, Amp and Kiro are per-user everywhere. OpenCode is per-user only while DefenseClaw's managed OpenCode plugin is not in force.
Machine-policy connector
An agent whose hooks DefenseClaw places in the vendor's administrator-owned policy files, which apply to every user: Codex, Claude Code, Cursor, GitHub Copilot and OpenCode through the managed plugin. DefenseClaw changes only its own entries. See Machine policy.
Managed-hooks-only lock
A vendor setting that makes the agent run only administrator-managed hooks:
allow_managed_hooks_only for Codex and allowManagedHooksOnly for Claude Code.
DefenseClaw sets both when managed_hooks_only is enforce, the default. On
Windows it sets the Codex lock whatever the setting says. See
Machine policy.
Foreign hook
A hook or plugin that DefenseClaw did not install and that is not on the
allowlist (allowed_hooks, a list of SHA-256 digests). One that runs after
DefenseClaw could change a tool call DefenseClaw already allowed.
Foreign-hook guard
The protection against foreign hooks. With the default
foreign_hooks: remove, the guardian removes foreign entries from the user's
config and defenseclaw-hook blocks tool calls while an unapproved one is
present. A session that started with one stays blocked until the agent restarts,
for at most 7 days. See Foreign-hook guard.
Peer verification
The hook's check that it is talking to the real gateway before it sends anything. On Windows it compares the connected process with the gateway process the SCM reports; the Amp and per-user OpenCode plugins instead make the listener prove, with an HMAC over a fresh nonce, that it can derive the user's credential. On Linux and macOS hooks and plugins use only the hook socket and check, through SO_PEERCRED and LOCAL_PEERCRED, that it belongs to root or the gateway account.
Reconcile
One guardian pass: compare each enrolled user's agent config with what it should
be and repair DefenseClaw's entries. It runs every minute, and reconcile runs
one now.
Health and inspection
coverage_complete
A lifecycle result field. On Linux and macOS it is true when the gateway,
guardian and enumerator are ready. On Windows it is true when the deployment is
installed, the guardian is ready and no transaction is pending. It does not check
that any user is enrolled. An installed agent with no verified hook contract
(hook_contract_unverified) makes it false.
security_complete
A stricter result field. On Linux and macOS it adds the sensor helper and requires
no errors. On Windows it needs at least one of Codex, Claude Code or Cursor turned
on, and with Claude Code on, a current administrator attestation. An installed
agent without DefenseClaw hooks (agent_unprotected, hook_contract_unverified)
makes it false, and so does an enabled agent that can run a tool when its hook
process is stopped or times out (hook_process_fail_open: Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity).
See Health fields.
Observe and action modes
guardrail.mode. In observe mode policy verdicts never block and DefenseClaw
records what it would have blocked. The one exception is an agent that changes
DefenseClaw's own files: that is blocked in every mode. In action mode it enforces. The
deployment's own checks apply in both modes. You can also set the mode per agent
under guardrail.connectors.
Cisco AI Defense
Cisco's cloud inspection service. In the Secure Client profile it makes every
decision, authenticated with CMID. In the standalone profile it is
optional: set enterprise.inspection.ai_defense.enabled: true and
enterprise.inspection.ai_defense.credential: <name>, then store the key under
that name. See Cisco AI Defense key.
CMID
Secure Client's cloud machine identity, which the gateway uses to authenticate to
Cisco AI Defense in the Secure Client profile (brokered by DefenseClawCMIDBroker
on Windows). The standalone profile does not use it.
AVC
The Cisco Secure Client packaging and signing pipeline. It ships the Secure Client profile's Windows Setup. The standalone profile does not use it.
Platform terms
SID and service SID
Windows. A SID is the security identifier of a user or group. The standalone
profile accepts local and domain user SIDs (S-1-5-21-…) and Microsoft Entra ID
user SIDs (S-1-12-1-…). A service SID is the identity Windows gives one service,
such as NT SERVICE\DefenseClawGateway.
DACL
Windows. The access list on a file, folder, registry key or service. The lifecycle sets exact DACLs on DefenseClaw's state and services.
SCM
Windows. The Service Control Manager. It runs DefenseClaw's services and restarts them after a failure. Standard users get query-only access.
NSS and SSSD
Linux. NSS is the system's user and group lookup (what getent uses). SSSD
connects Linux to LDAP or Active Directory through NSS. The enumerator lists users
through NSS. UID_MAX in /etc/login.defs (60000 when unset) caps only local
accounts; directory accounts have no upper bound unless you set
enterprise.enrollment.uid_max.
SO_PEERCRED and LOCAL_PEERCRED
Linux and macOS. Kernel features that tell one end of a local socket the user
ID of the process at the other end: SO_PEERCRED on Linux, LOCAL_PEERCRED on
macOS. The hook uses them to check the gateway, and the gateway uses them to learn
who is calling.
PPPC and TCC
macOS. TCC (Transparency, Consent, and Control) is the macOS privacy protection for sensitive folders. A PPPC profile is an MDM profile that grants an app that access in advance. See macOS.
WDAC and AppLocker
Windows. Application-control policies that decide which programs and scripts may run. A rule that requires a publisher signature accepts only signed DefenseClaw builds, not hash-pinned ones.
Zones
Trust zones
The threat model puts every component in one of six zones. An arrow between zones is a boundary DefenseClaw protects.
- Z0 · Admin and OS: the service manager, the MDM agent, the package installer and the lifecycle commands. Trusted.
- Z1 · Services: the guardian, the enumerator and the sensor helper. Privileged and trusted.
- Z2 · Gateway: the gateway, under its own low-privilege account.
- Z3 · Admin-owned files: binaries, config, policies, secrets, the target manifest, the authorization ledger and vendor machine policy.
- Z4 · User session: the user, the AI agent, the hook as it runs for the user, and the user's own files. Untrusted.
- Z5 · Cloud: Cisco AI Defense, used only when an administrator stores an API key. External.
The threat model lists what runs in each zone on each OS.
Plan a rollout
Plan a DefenseClaw enterprise rollout. Choose agents and users, pilot in observe mode, remove per-user installs, and expand in rings.
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.