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.

OSHow 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.

KindExamplesRule
Admin intentconfig.yaml, the policy assets it namesWritten only by the lifecycle on a managed host
DerivedService definitions, the runtime descriptor, machine-policy entries, per-user hook scriptsRegenerated from the config. Never edited by hand
Evidenceconfig.generation.json, migration-v9.json, config.yaml.v8.bak, policy-state.json, committed-config.yaml, rejected-config.yaml, the audit databaseRecords of what was applied or decided. They never change policy
Runtime stateThe enforcement journal for quarantine and runtime disable, approvals, discovery resultsReported, 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

PartWindowsLinux (systemd)macOS (launchd)
GatewayDefenseClawGateway, LocalSystem write-restricted by its NT SERVICE\DefenseClawGateway service SIDdefenseclaw-gateway.service, as defenseclaw with no capabilities. systemd holds its socketscom.cisco.defenseclaw.gateway, as the hidden _defenseclaw user
GuardianDefenseClawHookGuardian, LocalSystemdefenseclaw-hook-guardian.service, root with a bounded capability setcom.cisco.defenseclaw.hook-guardian, root
EnumeratorDefenseClawHookEnumerator, LocalSystemdefenseclaw-hook-enumerator.service, root with a bounded capability setcom.cisco.defenseclaw.hook-enumerator, root
Sensor helperDefenseClawSensorHelper, LocalSystemdefenseclaw-sensor-helper.service, rootcom.cisco.defenseclaw.sensor-helper, root
Applies a config changeYour MDM runs ensure againdefenseclaw-enterprise-apply.path runs ensure when the config, secrets or policies changecom.cisco.defenseclaw.apply does the same
Daily checkYour MDM runs detection or verifydefenseclaw-enterprise-verify.timercom.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.