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.

Pick your MDM

Find your tool, push the file in the third column, and follow its recipe. New to enterprise deployment? Start with Deploy to a fleet.

MDMOSWhat you push
Intune on WindowsWindows x64A Win32 app with the Setup and your config, plus PowerShell 7
Intune on macOSmacOSA root shell script (the kit wrapper)
Intune on LinuxUbuntu, RHELA root platform script (the kit wrapper)
Jamf PromacOSThe .pkg plus kit scripts
Iru (formerly Kandji)macOSA Custom App and a script, or one script
Workspace ONE UEMWindows, macOS, LinuxAn app, scripts and sensors
Configuration ManagerWindows x64An application with the Setup and your config
Ansible, Puppet, Chef, Salt, apt, dnfLinuxThe .deb or .rpm and your config
Anything else: start at What you deliverWindows, Linux, macOSThe release file and the kit wrapper, run as SYSTEM or root

Validation status. The Intune Windows, macOS script and Linux recipes ran on a test tenant with test builds packaged as 9.9.9 (PR #1304; macOS live script build f9ed814b1). This does not certify later releases. The other recipes, including the macOS PKG app route, are templates checked with Simulate your MDM. Pilot each on a small device group first.

The contract every recipe follows

Any tool that can run a program as SYSTEM (Windows) or root (Linux, macOS) can deploy the standalone profile. The kit in packaging/mdm has a wrapper (Invoke-DefenseClawEnterprise.ps1, defenseclaw-enterprise.sh), a detection script (detect.ps1, detect.sh) and a removal script (uninstall.ps1, uninstall.sh) per OS. Options and codes: MDM kit reference.

makes a private copy
if it matches
then runs ensure
prints
MDM runs the wrapperas SYSTEM or root
Checks the filehash pin or signature
Installs or upgradesSetup, deb, rpm or pkg
Applies your configno-op if unchanged
Reports one resultJSON and exit code

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

  1. 1.MDM runs the wrapperas SYSTEM or root
    • makes a private copyChecks the file
  2. 2.Checks the filehash pin or signature
    • if it matchesInstalls or upgrades
  3. 3.Installs or upgradesSetup, deb, rpm or pkg
    • then runs ensureApplies your config
  4. 4.Applies your configno-op if unchanged
    • printsReports one result
  5. 5.Reports one resultJSON and exit code
One wrapper run. It checks a private copy of the file before anything is installed, and a run that fails after that rolls back. On Windows, Setup /ensure installs and applies in one step. Without a file, the wrapper skips the check and the install and re-applies the installed deployment.

What you deliver

Every deployment needs the release artifact for the OS, the administrator config, and optionally the Cisco AI Defense API key.

OSArtifact (release asset)Trust anchor
Windows x64DefenseClawSetup-Enterprise-Standalone-x64.exeIts SHA-256 from checksums.txt (and, if Authenticode-signed, the signer thumbprint)
Linuxdefenseclaw-enterprise-<version>-linux-<arch>.deb, .rpm or .tar.gzIts SHA-256 from checksums.txt (and, if the release ships them, the .asc signature)
macOS (Apple silicon)defenseclaw-enterprise-<version>-darwin-arm64.pkg or the payload archiveIts SHA-256 from checksums.txt (and, for a signed pkg, the Team ID)

<arch> is amd64 or arm64. On Windows use the -Standalone- Setup: DefenseClawSetup-Enterprise-x64.exe is the Cisco Secure Client build. On an enforcing fapolicyd host, use the deb or rpm with the Linux MDM wrapper. Its tarball path runs one ensure; a tarball requires the staged-payload trust and two-stage flow outside that wrapper.

Hash-pinned trust is the default. The pin is the artifact's SHA-256 from the release's cosign-signed checksums.txt. Verify it once on an administrator workstation, then read the pin:

VERSION=X.Y.Z   # the release you deploy
FILE="defenseclaw-enterprise-$VERSION-linux-amd64.deb"
BASE="https://github.com/cisco-ai-defense/defenseclaw/releases/download/$VERSION"
curl -fsSLO "$BASE/checksums.txt"
curl -fsSLO "$BASE/checksums.txt.bundle"
curl -fsSLO "$BASE/$FILE"
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
sha256sum --check --ignore-missing checksums.txt
PIN=$(awk -v f="$FILE" '$2 == f {print $1}' checksums.txt)
echo "$PIN"

On a Mac use shasum -a 256 -c. If you stage releases on an internal mirror, copy checksums.txt and checksums.txt.bundle unchanged (Where releases come from).

Deliver the config

For signed bundles on Windows, deliver one app that carries the config and the first bundle: Setup installs with the services stopped and starts them on the signed bundle, so nothing runs on the config (the single app in Intune on Windows). Devices installed earlier with a base app and a dependent bundle app take the same single app.

The config decides which agents are protected and how, and it is the only policy a managed host enforces. Content: Settings and Choose the agents to protect. The lifecycle installs it at C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml (Windows), /etc/defenseclaw/config.yaml (Linux) or /opt/cisco/defenseclaw/etc/config.yaml (macOS). A first install on Windows needs a config (ensure without one exits 1639). On Linux and macOS, an install without one gets a default that protects no agents.

MethodLinux and macOS wrapperWindows wrapperWindows Setup
From a file--config-file /abs/path-ConfigPath C:\abs\pathCONFIG=C:\abs\path
From standard input--config-stdin-ConfigFromStdinnone
In the script itselfSettings block DC_CONFIG_FILE, or YAML between the DEFENSECLAW_CONFIG markers in dc_inline_confignonenone
  • Only administrators may change the file, or any parent folder. The wrappers refuse anything else with mdm_untrusted_input; Setup refuses it with exit 1639 and names the account and the icacls fix.
  • Absolute local paths only, at most 1 MiB.
  • No credentials in the config. The standalone profile rejects an inline cisco_ai_defense.api_key.
  • A config_version: 8 file is migrated to 9 when applied. The Intune Win32 packager requires 9.
  • Bundle mode. Once your MDM installs bundle trust anchors, the device takes its config only from signed bundles and refuses a plain config with bundle_required.

On Windows, a new signed bundle that never reaches a gateway reporting its policy before the apply deadline is failed and the lifecycle restores its previous config. If restoration or proof of the restored policy fails during an outage, the gateway is stopped. If the gateway accepted the candidate but became unavailable before receipt confirmation, the receipt stays applied and pending; retry ensure after recovery to settle it. A run interrupted after writing the config can also leave a staged receipt pending until ensure checks the gateway. Repeating an already confirmed bundle during an outage keeps its signed config installed and returns not_confirmed for that retry without creating another receipt.

Deliver the AI Defense key

The key is optional; without it the local policy engine decides alone. The config names the credential and turns the feature on (Cisco AI Defense key). The key never goes on a command line, in a script body or in the config. Pass it in the same wrapper run with --secret-name ai-defense-api-key plus --secret-file or --secret-stdin (Windows: -SecretName, -SecretPath or -SecretFromStdin), or store it directly as root. A failed store is mdm_secret_failed.

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set \
  --name ai-defense-api-key --from-file /root/ai-defense.key
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret status

Run ensure

ensure is the one action an MDM runs. It installs when nothing is installed, upgrades when the version differs, repairs when verify finds drift and applies a changed config. When the host already matches it changes nothing and reports "noop": true, so run it on every check-in.

Linux
sudo ./defenseclaw-enterprise.sh \
  --source /var/cache/mdm/defenseclaw-enterprise-<version>-linux-amd64.deb \
  --sha256 "$PIN" \
  --config-file /etc/mdm/defenseclaw/config.yaml
Windows (PowerShell 7 as SYSTEM)
$pin = '<SHA-256 of the Setup from checksums.txt>'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoProfile -NonInteractive -File .\Invoke-DefenseClawEnterprise.ps1 `
  -SetupPath C:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe `
  -Sha256 $pin `
  -ConfigPath C:\Staging\config.yaml

On macOS use defenseclaw-enterprise.sh with the .pkg as --source. The Windows staging folder must be writable only by SYSTEM and Administrators (how to fix its ACL). If your MDM cannot run PowerShell 7, run Setup directly after checking its SHA-256.

Check it worked

The wrapper prints one result document and exits with a code from the table below. The document's format is lifecycle-result.schema.json. Then ask the host:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json
echo $?

0 and "ok": true mean the deployment is intact. On macOS use the /opt/cisco/defenseclaw/bin path and enterprise macos verify.

Windows staging and Setup-only runs

On Windows, run PowerShell 7 as SYSTEM. The staging folder must be writable only by SYSTEM and Administrators, or the wrapper and Setup refuse the config. On client editions a new folder under C:\ can carry write access for Authenticated Users and read access for Users as entries of their own, which /inheritance:r does not remove. Remove them by name; icacls C:\Staging /T then lists only NT AUTHORITY\SYSTEM and BUILTIN\Administrators:

icacls C:\Staging /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F"
icacls C:\Staging /remove:g "*S-1-5-11" "*S-1-5-32-545" /T /C
$pin = '<SHA-256 of the Setup from checksums.txt>'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoProfile -NonInteractive -File .\Invoke-DefenseClawEnterprise.ps1 `
  -SetupPath C:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe `
  -Sha256 $pin `
  -ConfigPath C:\Staging\config.yaml

If your MDM can run a native executable as SYSTEM but not PowerShell 7, run Setup directly. Setup has no pin of its own, so check its SHA-256 first, in the in-box Windows PowerShell 5.1:

$pin = '<SHA-256 of the Setup from checksums.txt>'
$setup = 'C:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe'
if ((Get-FileHash -LiteralPath $setup -Algorithm SHA256).Hash -ne $pin) { exit 1603 }
& $setup /ensure JSON=1 CONFIG=C:\Staging\config.yaml
exit $LASTEXITCODE

Wrapper options

Linux and macOSWindowsMeaning
--action ensure|status|verify-Action Ensure|Status|VerifyDefault ensure. status and verify are read-only and take no config or key. The Linux and macOS wrapper also refuses a source with them; the Windows wrapper accepts -SetupPath. Use the uninstall script to remove.
--source FILE or --source-url https://...-SetupPath FILEThe artifact. Without it, the wrapper re-applies the installed deployment. A --source-url must serve the file itself: the wrapper downloads with curl and does not follow redirects, so a GitHub release link fails (the wrapper reports HTTP 302). Host the artifact on your own HTTPS server.
--sha256 HEX-Sha256 HEXThe pin. Required with hash-pinned trust.
--trust-mode hash_pinned|signed-TrustMode HashPinned|AuthenticodeDefault hash-pinned.
--allowed-team-id ID (macOS), --gpg-keyring FILE with --signature FILE or --signature-url URL (Linux)-AllowedSigners THUMBPRINT[,...]Signer pins for signed trust.
--config-file, --config-stdin-ConfigPath, -ConfigFromStdinThe config.
--secret-name with --secret-file or --secret-stdin-SecretName with -SecretPath or -SecretFromStdinThe optional key.
--format json|jamf—jamf wraps the result document in <result> for Jamf Pro.
--product-version X.Y.Z-ProductVersion X.Y.ZLinux and macOS: refuse an artifact of any other version (mdm_version_mismatch) before anything is installed. Windows: only without -SetupPath, where it sets the version the installed CLI's ensure records; with -SetupPath it is refused (mdm_invalid_arguments, 1639), because the -Sha256 pin already ties the Setup to one release.
--https-proxy URL—Proxy for the download only. The services' own proxy is set in the config (Network proxy).
--log FILE—Wrapper log path.
--staging-dir DIR—The root-only folder the wrapper stages the artifact and the config in. Default /var/lib/defenseclaw-mdm on Linux (created root, 0700) and /var/tmp on macOS. A payload source runs its defenseclaw-gateway from there, so the folder must allow execution; CIS hosts mount /tmp and /var/tmp noexec. It must be owned by root and not writable by others (mdm_staging_untrusted).

On an enforcing fapolicyd host, the Linux wrapper's payload source does not perform the staged and installed-tree trust updates. Use the deb or rpm with the wrapper, or follow the manual two-stage tarball steps.

Script-only MDMs that cannot pass arguments set the same values in the settings block at the top of defenseclaw-enterprise.sh: DC_ACTION, DC_SOURCE, DC_SOURCE_URL, DC_SOURCE_SHA256, DC_TRUST_MODE, DC_ALLOWED_TEAM_IDS, DC_GPG_KEYRING, DC_SIGNATURE, DC_SIGNATURE_URL, DC_PRODUCT_VERSION, DC_CONFIG_FILE, DC_SECRET_NAME, DC_SECRET_FILE, DC_FORMAT, DC_HTTPS_PROXY, DC_LOG, DC_STAGING_DIR. Flags override the settings block. The wrapper refuses any argument it does not know, including positional arguments, with exit 2 (mdm_invalid_arguments); an MDM that appends its own arguments needs the line its recipe gives.

For Linux signed trust, gpgv needs a binary keyring. Convert the release key once and deploy the result as a root-owned file:

gpg --dearmor < defenseclaw-enterprise-release-key.asc > defenseclaw-enterprise-release-key.gpg

Execution requirements

  • SYSTEM or root. On Windows an elevated administrator session also works. The wrappers refuse anything else (mdm_not_root, mdm_not_elevated), and so does Setup.
  • No terminal and no inherited environment. The Linux and macOS scripts set their own PATH and locale and work under env -i with no TTY. They read standard input only for --config-stdin or --secret-stdin.
  • Windows: native x64 only. The lifecycle refuses ARM64 and 32-bit Windows. The wrapper also refuses a 32-bit or emulated PowerShell, Constrained Language Mode, and .NET loader-injection variables such as DOTNET_STARTUP_HOOKS. A 32-bit agent that starts Windows PowerShell must use %SystemRoot%\Sysnative\WindowsPowerShell\v1.0\powershell.exe.
  • Windows: PowerShell 7, installed from Microsoft's x64 MSI into C:\Program Files\PowerShell\7. The lifecycle refuses a preview build or any PowerShell 7 the MSI did not register. The kit's PowerShell 7 scripts (Invoke-DefenseClawEnterprise.ps1 and New-DefenseClawIntunePackage.ps1) need 7.4 or later. Setup, detect.ps1, uninstall.ps1 and the Intune scripts do not need it to start.
  • Time. Setup gives the lifecycle 30 minutes by default (TIMEOUTSECONDS=60 to 7200), counted from when Setup starts, so its payload checks and unpacking count too; a run with less than about a minute left after them does not start the lifecycle and changes nothing, so a change needs TIMEOUTSECONDS of at least about 2 minutes (120); lower values suit only /verify and /status. 120 only lets a change start: an unloaded upgrade or /ensure takes about 5 to 8 minutes, so keep the default unless you have a reason not to. On Windows, a standalone Setup run stopped at TIMEOUTSECONDS then runs its own recovery for up to 10 more minutes, so allow TIMEOUTSECONDS plus 10 minutes (40 minutes by default). An MDM that ends Setup sooner can stop that recovery and leave verify failing until the next /ensure or /repair.
  • One run at a time. A second run while one holds the lifecycle lock, or while dpkg, rpm or the macOS installer is busy, exits 1618 (Windows) or 75 (Linux, macOS). Retry later. On Windows, a Setup that would upgrade the installed release also exits 1618 (lifecycle_busy) before it changes anything when the processors are less than 25% idle over 6 seconds: the upgrade runs below normal priority so agent hooks keep answering, and could not finish in time on a computer that busy.
  • Leftovers of an unmanaged install (Linux, macOS). If DefenseClaw machine files exist that no committed deployment owns, ensure refuses with unmanaged_layout_present. Take them over once by running enterprise linux ensure or enterprise macos ensure as root with --adopt-existing and --from-package (or --payload <dir>). It backs the old files up first. On a Linux tarball host with fapolicyd, trust the staged payload and use the two-stage install flow, passing --adopt-existing to the staged ensure and adding installed-tree trust before activation. The wrapper does not pass --adopt-existing. See Troubleshooting.

Setup properties

DefenseClawSetup-Enterprise-Standalone-x64.exe takes one action and NAME=value properties. Names are case-insensitive and ignore dashes. /quiet and /norestart are accepted and ignored.

Action or propertyMeaning
/ensureInstall, upgrade, repair or no-op. Use this from an MDM.
/install, /upgrade, /repair, /reconcile, /status, /verify, /uninstallThe individual actions. /install also needs MANIFEST=, so use /ensure instead.
CONFIG=Absolute path of the config. Required for the first install.
MANIFEST=Optional administrator target manifest (targets.yaml). A first install with enterprise.enrollment.mode: manifest needs it.
ALLOWEDSIGNERS=Comma-separated SHA-256 thumbprints of accepted Authenticode signers.
JSON=1Print the result document on standard output. Always set it from an MDM.
NOSTART=1Install with the services stopped (mutating actions only).
PURGE=1With /uninstall, also remove each enrolled account's DefenseClaw data and per-user binaries.
FORCE=1With /uninstall, last resort: remove the deployment without recovering a pending transaction.
TIMEOUTSECONDS=Lifecycle timeout, 60 to 7200 seconds, counted from when Setup starts. Default 1800. A change needs at least about 120; lower values suit only /verify and /status.
ATTESTCLAUDEEFFECTIVEPOLICY=1With /repair: record the administrator's attestation that Claude Code runs DefenseClaw's managed hooks. See Claude Code on Windows.

Exit codes

The wrappers, the removal scripts and every lifecycle action print exactly one result document on standard output and exit with a code from one of two families. The lifecycle prints it with --json or JSON=1; the kit's scripts always ask for it. The detection and Remediations scripts print one line instead. The document's exit_code field matches the process exit code. Its format is packaging/mdm/contract/lifecycle-result.schema.json (schema version 2).

ResultWindowsLinux, macOSMDM action
Success, or nothing to do ("noop": true)00Success
Failed. A mutating action has already rolled back.16031Failure; read errors[].code
Another run holds the lock, the package manager is busy161875Retry later
Invalid arguments, for example a first Windows install without a config. Retrying does not help.16392Failure; fix the assignment
Reboot required (reserved; nothing returns it)3010—Soft reboot

An invalid config is config_invalid and exit 1 on Linux and macOS. On standalone Windows, Setup reports a config that is malformed, not UTF-8 or does not validate as invalid_arguments and exit 1639, because the administrator has to fix the file. The installed config stays as it was.

The Windows codes are Windows Installer codes, so MDMs classify them with their default tables. Intune's default Win32 return codes (0, 1707, 3010, 1641, 1618) already treat 1603 and 1639 as failures and retry 1618.

The standalone Setup can also refuse before the lifecycle starts. It exits 1639 (invalid_arguments) for a malformed command line: an unknown property, a CONFIG= or MANIFEST= path that is missing, relative or environment-expanded, /install without CONFIG= and MANIFEST=, or TIMEOUTSECONDS out of range. It also exits 1639 for a CONFIG= or MANIFEST= file that a non-administrator owns or can change, and names the account and the icacls fix. A token that is not elevated exits 1603. The wrappers' own mdm_untrusted_input stays 1603. With JSON=1, Setup prints the same schema-version-2 document as the lifecycle, with errors[] and exit_code, and the wrappers keep it. Setup scans every argument for JSON=1, so /ensure BOGUS=1 JSON=1 still returns the JSON refusal, whatever the order. The Secure Client Setup returns only 0 and 1603, with a schema-version-1 document (an error field) under JSON=1.

Codes that start with mdm_ come from the kit's scripts. Most mean the wrapper stopped before the lifecycle ran; mdm_not_installed after an apply, and mdm_secret_failed on Windows, come after the lifecycle succeeded. In an mdm_ document, "installed": false means "not evaluated". The Windows wrapper's parameters are checked by PowerShell: an unknown parameter, or starting the wrapper in Windows PowerShell 5.1, stops it with exit 1 before it prints a document. Run the status action to inspect the host. Every other code comes from the lifecycle; see Troubleshooting.

CodeExit (Windows / Linux, macOS)Meaning
mdm_invalid_arguments1639 / 2A flag or setting is missing, malformed, contradictory or unknown.
mdm_wrong_platform— / 2The Linux copy ran on macOS, or the reverse.
mdm_not_root, mdm_not_elevated1603 / 1Not running as root, SYSTEM or an elevated administrator.
mdm_hash_mismatch1603 / 1The staged artifact does not match the pinned SHA-256.
mdm_signature_invalid, mdm_signer_not_allowed, mdm_signature_unsupported1603 / 1The signature is invalid, the signer is not allowed, or signed trust does not apply to this artifact type.
mdm_untrusted_input1603 / 1A config, key or keyring file can be changed by a non-administrator, or (uninstall.sh) the installed gateway is not root-owned.
mdm_untrusted_install1603 / —uninstall.ps1 only: the installed CLI or one of its folders is not administrator-only. The wrapper reports the same condition as mdm_lifecycle_launch_failed, and detect.ps1 as not detected.
mdm_input_too_large1639 / 2Config over 1 MiB or key over 16 KiB.
mdm_staging_full— / 1The staging filesystem filled while extracting a payload. Choose a folder with more space.
mdm_cancelled— / 1The MDM stopped a Unix wrapper and its lifecycle child. Inspect the deployment before a fresh run.
mdm_payload_invalid, mdm_package_invalid, mdm_wrong_package, mdm_wrong_architecture, mdm_version_mismatch— / 1The archive or package is not a DefenseClaw enterprise artifact for this host, or not the version you pinned.
mdm_package_manager_busy— / 75dpkg, rpm or the macOS installer held its lock. Retry.
mdm_package_install_failed, mdm_package_remove_failed, mdm_package_manager_missing— / 1The package manager failed or is absent.
mdm_package_result_empty— / 1macOS: the Installer failed, the postinstall left an empty result, and no lifecycle run holds the lock. When one does, the wrapper reports lifecycle_busy and exits 75.
mdm_disk_full— / 1The volume of the install root has too little free space for the package, or the installer ran out. Nothing was installed.
mdm_download_failed, mdm_download_unavailable— / 1The HTTPS download failed, or neither curl nor wget is installed.
mdm_not_installed1603 / 1A read-only action, or ensure without an artifact, found no installed deployment.
mdm_binaries_damaged— / 1ensure without an artifact found an installed DefenseClaw binary missing, not executable or different from its deployment record. Run the wrapper with the package as the source.
mdm_lifecycle_no_result, mdm_lifecycle_launch_failedSetup's code or 1603 / the lifecycle's code or 1The lifecycle did not start or printed no result document.
mdm_secret_failed1603 / 1, 2 or 75Storing the key failed. On Windows the deployment applied; on Linux and macOS the config was not applied, and the exit code is the one secret set returned.
mdm_staging_untrusted, mdm_package_incomplete1603 / 1The private staging folder, or the Intune Win32 app content (Windows), is not as expected.
mdm_staging_noexec— / 1Linux: the payload's defenseclaw-gateway cannot run from the staging folder because its filesystem is noexec; the message names the mount. Pass --staging-dir with a root-only folder that allows execution, or use the deb or rpm.
unsupported_architecture, powershell_constrained_language, loader_environment_present, powershell7_untrusted1603 / —The PowerShell 7 wrapper refused its host. The lifecycle applies the same checks.

Stage a custom macOS rule pack

If your config selects a custom pack, deliver it before the pkg and config are applied. Add a root MDM script that copies a trusted pack directory from your MDM payload into the administrator policy folder. Replace PACK_SOURCE with the staged payload path:

set -eu
PACK_SOURCE=/path/to/mdm-payload/acme
PACK_DEST=/opt/cisco/defenseclaw/etc/policies/guardrail/acme
test -d "$PACK_SOURCE" || exit 1
PACK_PARENT=$(dirname "$PACK_DEST")
PACK_NAME=$(basename "$PACK_DEST")
install -d -o root -g wheel -m 0755 "$PACK_PARENT"
STAGE=$(mktemp -d "$PACK_PARENT/.$PACK_NAME.stage.XXXXXXXX")
BACKUP=
PUBLISHED=0
cleanup() {
  result=$?
  trap - 0
  if [ "$PUBLISHED" -eq 0 ] && [ -n "$BACKUP" ] &&
     [ -e "$BACKUP/$PACK_NAME" ]; then
    if [ -e "$PACK_DEST" ] || ! mv "$BACKUP/$PACK_NAME" "$PACK_DEST"; then
      echo "Pack publish failed; previous pack is in $BACKUP" >&2
      exit 1
    fi
  fi
  rm -rf "$STAGE"
  [ -z "$BACKUP" ] || rm -rf "$BACKUP"
  exit "$result"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM
cp -R "$PACK_SOURCE/." "$STAGE/"
chown -R root:wheel "$STAGE"
find "$STAGE" -type d -exec chmod 0755 {} +
find "$STAGE" -type f -exec chmod 0644 {} +
BACKUP=$(mktemp -d "$PACK_PARENT/.$PACK_NAME.backup.XXXXXXXX")
if [ -e "$PACK_DEST" ]; then
  mv "$PACK_DEST" "$BACKUP/$PACK_NAME"
fi
mv "$STAGE" "$PACK_DEST"
PUBLISHED=1

Validate the pack on a reference Mac with /opt/cisco/defenseclaw/bin/defenseclaw-gateway rulepack validate --dir "$PACK_DEST" after that binary is installed, and put its custom_packs pin value in the config. For the first installation, validate an identical copy on a reference Mac before assigning the new device. The pin covers the pack's own files.

guardrail:
  rule_pack: acme
  custom_packs:
    acme: {path: /opt/cisco/defenseclaw/etc/policies/guardrail/acme, digest: "sha256:<digest>"}

Re-run the stage script and update the pin before applying an edited pack. The script stages a complete replacement before publishing it; a failed copy leaves the previous pack in place and returns a nonzero exit. An uninstall removes the policy folder, so stage the pack again before a reinstall.

Detection

MDMs ask two questions. Answer each with the mechanism that fits.

  1. Inventory: is the version I assigned installed? Install rules, supersedence and upgrade detection need a cheap, stable answer: the registry marker, the package database or the pkg receipt.
  2. Health: is it installed, intact and enforcing? Compliance scripts and remediations need the lifecycle's own verdict: the detection script with its health option, or the verify action.

The Windows marker is written only after a successful lifecycle run. The Linux package database records the package even when its post-install ensure failed, so use detect.sh or verify for the real state. A macOS pkg whose post-install ensure failed records no receipt, and finishing with ensure --from-package adds none, so install the pkg again after you fix the cause. Standard users cannot write any marker. Only verify proves that the services, protected files, hooks and machine policy are intact.

OSInventoryHealth
WindowsRegistry value HKLM\SOFTWARE\Cisco\DefenseClaw\Enterprise ProductVersion in the 64-bit view, compared as a version, greater than or equal to the assigned version. Or detect.ps1 -MinimumVersion X.Y.Z.detect.ps1 -RequireHealthy, or the installed CLI's enterprise windows verify --profile standalone --json exits 0.
Linuxdpkg-query -W -f='${Status} ${Version}' defenseclaw-enterprise or rpm -q defenseclaw-enterprise (package channel only). Or detect.sh --min-version X.Y.Z, which covers every channel.detect.sh --require-healthy, or the wrapper's --action verify exits 0.
macOSpkgutil --pkg-info com.cisco.defenseclaw.enterprise reports version: X.Y.Z (pkg channel). Or detect.sh --min-version X.Y.Z.detect.sh --require-healthy, or the wrapper's --action verify exits 0.

On Linux, DefenseClaw leaves host kernel settings as found. status and verify report open user namespace and ptrace routes as observed warnings, with incomplete security. detect.sh --require-healthy checks coverage, not host hardening: it reports such a host healthy and prints the warnings on standard error. --require-security-complete reports unhealthy while either route remains open. An administrator may apply optional host hardening with their own tools after testing affected workloads. No DefenseClaw lifecycle step schedules or waits for a reboot.

detect.ps1 [-MinimumVersion X.Y.Z] [-RequireHealthy] [-RequireSessionsProtected] follows Intune's custom-detection rules: "detected" is exit 0 with one line on standard output (DefenseClaw Enterprise <version>) and nothing on standard error; "not detected" is exit 1 with the reason on standard error. It reads the marker through the 64-bit registry view, so it works in 32-bit Windows PowerShell.

detect.sh [--min-version X.Y.Z] [--require-healthy] [--require-security-complete] [--require-tetragon MODE] [--require-sessions-protected] [--format exit|value|jamf] asks the installed, root-owned gateway for its status instead of trusting files, so run it as root. A standard user gets unknown in value and jamf format.

FormatExit codeOutput
exit (default)0 when detected, 1 otherwiseDefenseClaw Enterprise <version> on standard output, or the reason on standard error
valueAlways 0 (except for a failed session check)The installed version, or not-installed, outdated (with --min-version), unhealthy (with --require-healthy), unknown (not run as root) or busy (a lifecycle run holds its lock; transient). For inventory attributes.
jamfAlways 0 (same exception)The same values inside <result>...</result>, for Jamf Pro extension attributes
  • --require-healthy requires verify to pass with coverage_complete: true. When security_complete is false, every reason verify gives for it must be a host-hardening warning: hook_process_fail_open, unprivileged_user_namespaces and unprivileged_ptrace. Those are printed on standard error and the host is healthy. Any other reason (for example agent_sessions_restart_required, guardian_repair_pending, enrolled_home_unavailable or agent_unprotected) reports unhealthy. --require-security-complete (DC_REQUIRE_SECURITY_COMPLETE=1 in the settings block) also requires security_complete: true.
  • --min-version takes a dotted release such as X.Y.Z; a bad value exits 2. A leading v and build metadata (+...) are ignored, and a prerelease sorts before its release.
  • Lock contention is busy (exit 75 in exit format) with or without --require-healthy, and in exit format the verify call can report it too. It is transient: retry after the apply finishes, and keep a device that reports it in the group it was in. On Linux it also reports unhealthy while dpkg lists the package half-configured or rpm lists two versions of it (an install cut short by a power loss), so the MDM runs the deployment again.
  • --require-tetragon consume|observe|enforce (Linux only) also runs enterprise linux tetragon verify --ready-for MODE --json; a failing check is tetragon-not-ready:<first failing check> in value and jamf format. The macOS copy refuses it with "Linux only". See Tetragon on a Linux fleet.
  • --require-sessions-protected (-RequireSessionsProtected) fails while a running agent session predates its managed hooks.
  • An unknown argument or a bad --format exits 2 and prints nothing on standard output.

When an installed agent runs without DefenseClaw hooks for one account (agent_unprotected, hook_contract_unverified), verify reports a warning for that account and passes, with security_complete: false. On Windows, detect.ps1 -RequireHealthy follows the verify exit code, so the device stays healthy. On Linux and macOS, detect.sh --require-healthy reports it unhealthy: hook_contract_unverified makes coverage_complete false, and agent_unprotected is not a host-hardening warning. To collect security_complete across a fleet, read it from the last lifecycle result (%WINDIR%\Logs\DefenseClaw\last-result.json on Windows; the --json output of status on Linux and macOS) with a custom compliance script or inventory attribute.

Windows also keeps an Add/Remove Programs entry, HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\CiscoDefenseClawEnterprise (DisplayName "Cisco DefenseClaw Enterprise", DisplayVersion), and the marker's other values: Profile, InstallRoot, StateRoot, TrustMode, UpdatedAt and DisableSelfUpdate.

Claude Code on Windows

With Claude Code enabled, a Windows host reports security_complete: false until an administrator attests that Claude Code runs DefenseClaw's managed hooks. In an enrolled user's own session, have Claude Code make a tool call, then from an elevated prompt export the gateway's record with defenseclaw audit export --connector claudecode -o <file>. Once the record shows that call, run Setup /repair JSON=1 ATTESTCLAUDEEFFECTIVEPOLICY=1 (see Verify the install). The record is bound to the hashes of the installed Claude Code policy and hook binary, so every upgrade makes it stale. Computers on the same release and Claude Code hook contract share the binding: check one reference computer, then push the /repair command to the others from your MDM after each upgrade.

Logs

OSWhereWhat
Windows%WINDIR%\Logs\DefenseClaw\enterprise-lifecycle.logOne JSON result per lifecycle run, five generations of 5 MiB
Windowslast-result.json, mdm-wrapper.log, same folderThe latest full result; the wrapper's steps
WindowsDefenseClaw event log, source "DefenseClaw Lifecycle"100 installed, 101 upgraded, 102 repaired, 110 uninstalled (Application log only), 111 ensure no-op, 112 ensure applied, 120 unhealthy, 130 failed, 140 busy, 150 refused
WindowsApplication log, source "DefenseClaw Enterprise"A copy of each event
Linux/var/log/defenseclaw-enterprise-mdm.log (root, 0600)Install and ensure results; uninstall removes this log, so use the MDM policy log for its result
Linux/var/lib/defenseclaw-enterprise/last-package-result.json and last-package-result.logThe package's own ensure
Linuxjournalctl -u defenseclaw-enterprise-apply.service and -u defenseclaw-enterprise-verify.serviceConfig-change runs and the daily verify
macOS/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.log (root, 0600)The wrapper's steps and results
macOSlifecycle.log and verify.log, same folderConfig-change runs and the daily verify
macOS/opt/cisco/defenseclaw/lifecycle/last-package-result.jsonThe pkg's own ensure

On Windows, only Administrators and members of Event Log Readers can read the files, because the results name other accounts; users can read both event logs, whose entries carry only codes. Only SYSTEM and Administrators can write the files and the DefenseClaw log. Any account can write Application-log entries under any source name, so detect from the DefenseClaw log. The services' own logs are in Operations.

Upgrades, rollback and config changes

Upgrade. Deliver the new artifact and its pin, and run ensure. It upgrades in place and keeps the config, key and state. In an MDM that models upgrades as supersedence, make the new version supersede the old one without uninstalling it first. On Linux, a package-manager upgrade also works: the package's post-install step runs ensure. Keep each host on one channel: a host installed from the deb or rpm refuses a payload-archive upgrade (package_owned_binaries). The first ensure of a new release migrates a config_version: 8 config to 9 and, on Linux and macOS, reports the applied policy in the result's policy object (Effective policy digest).

On a Linux tarball host with fapolicyd, use the two-stage payload upgrade instead of the wrapper's single ensure.

Roll back. Every lifecycle refuses an older release than the installed one unless you ask for the rollback (downgrade_refused; exit 1603 on Windows). The wrappers do not ask for it: rpm -U refuses an older rpm, and on Linux the lifecycle refuses an older deb after dpkg installs it. On macOS, create the root-owned marker /opt/cisco/defenseclaw/lifecycle/allow-downgrade before you deliver the older pkg; the package consumes it. See Roll back.

Change the config.

OSHow
Linux, macOSRun the wrapper again with the new config and no artifact. The lifecycle validates the new file before it replaces the installed one, then applies it. With a script-only MDM, edit the config in the script and let the MDM run it again. Replacing the installed file directly also works: the apply job (defenseclaw-enterprise-apply.path on Linux, com.cisco.defenseclaw.apply on macOS) runs ensure when the file changes.
WindowsRun Setup again with the new file: /ensure JSON=1 CONFIG=<new file>, or the wrapper with -SetupPath and -ConfigPath. Use a Setup of the installed version or newer. The installed CLI cannot apply a new config on its own: its enterprise windows ensure --config (and the wrapper without -SetupPath) exits 1639, because it has no payload to re-apply.

On a device in bundle mode (bundle trust anchors installed), both routes refuse a config that is not the current bundle's with bundle_required, and on Linux and macOS an edit of the installed file is reverted. Deliver a new signed bundle instead. On a refusal the config is not applied, but on Linux and macOS the wrapper runs its earlier steps first: a deb, rpm or pkg package (--source) is installed and a credential (--secret-name) is stored, and both stay.

When you deliver a credential with a bundle, the script first writes what it replaces to a root-only journal (/var/lib/defenseclaw-mdm/rotation on Linux, /var/db/defenseclaw-mdm/rotation on macOS). If the bundle does not apply, it puts the earlier value back, or removes a credential it added. If the run is stopped before it finishes, the next ensure does that before it changes anything. The new value stays only when the gateway reports that a bundle confirmed since uses it. If the gateway refuses the put-back for another reason, the journal entry stays, the wrapper log says why, and the script rotates no other credential until it is resolved. On Linux and macOS the wrapper journals a credential it rotates with a bundle in that root-only folder. Until the rotation settles, <name>.value there holds a root-only copy of the earlier credential. If an entry cannot be settled, every ensure exits mdm_secret_failed and the wrapper log says why; deliver the package with --source, or fix the logged cause, and run ensure again. Two kit runs do not rotate at once: the wrapper holds a lock on the journal, and a run that waits for it logs that it waits (after 2 seconds, then once a minute, up to 10 minutes). Two first runs that start together both create the state folders without failing.

An MDM that detects the Windows deployment by version does not re-run it for a config-only change. Intune on Windows shows a detection rule that also checks the config. More in Change the config.

Uninstall

The removal scripts are idempotent: on a host with nothing installed they print a no-op result and exit 0.

OSCommandRemoves
Linuxuninstall.sh [--purge] [--keep-package] [--log FILE], or DC_PURGE=1 and DC_KEEP_PACKAGE=1 in its settings blockThe services, DefenseClaw's hooks and machine-policy entries (administrator entries stay), config, credentials, most state and logs, and the defenseclaw service account, then the deb or rpm unless --keep-package. Your policies in /etc/defenseclaw/policies stay; --purge removes them. --purge also removes each enrolled account's ~/.defenseclaw and per-user binaries, the kept sandbox store and key, and the wrapper's state folder (/var/lib/defenseclaw-mdm on Linux, /var/db/defenseclaw-mdm on macOS), including the rotation journal and the staging folders of wrapper runs that were killed. If an enrolled account had its own DefenseClaw install before the enrollment (its ~/.defenseclaw holds config.yaml, .env, audit.db or previous/), --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. Every completed uninstall, through uninstall.sh or `enterprise linux
macOSuninstall.sh [--purge] [--staging-dir DIR] [--log FILE], or DC_PURGE=1 in its settings blockThe same, with the _defenseclaw account; the lifecycle forgets the pkg receipt. --purge also removes the wrapper's empty state folder /var/db/defenseclaw-mdm and the staging folders that killed wrapper runs left in /var/tmp (and in the --staging-dir folder, if your wrapper runs used one).
Windowsuninstall.ps1 [-Purge], or DefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall JSON=1 with optional PURGE=1The services, hooks and machine-policy entries, the machine state (config, key and state), the Add/Remove Programs entry and the marker, and the files the managed runtime wrote in each enrolled account's %USERPROFILE%\.defenseclaw once that account's registrations are removed. Purge also removes each enrolled account's %USERPROFILE%\.defenseclaw and per-user binaries, and the kit's rotation journal C:\ProgramData\Cisco\DefenseClaw-MDM\rotation. A plain uninstall keeps that journal and the JSON result names it (mdm_rotation_journal_kept).

Without --purge, if an account keeps sandboxes, the gateway's sandbox store and redaction-correlation.key stay root-owned until the next ensure adopts them. Use --purge for a clean image, in the first removal: the scripts run the lifecycle only while the DefenseClaw binaries are installed, so a purge after a plain removal finds nothing to run and exits 0 with that state still there. Install the package again and purge, or delete it by hand. To keep the machine state for a reinstall, run the lifecycle's own uninstall --keep-state; see Uninstall.

Simulate your MDM

You can validate a recipe without a tenant by reproducing the context the MDM agent runs in, then checking the exit code, standard output (one result document, or the detection line), standard error, and the result document against the schema.

Linux and macOS. MDM agents run scripts as root with a minimal environment, no terminal and nothing on standard input:

sudo env -i /bin/sh ./defenseclaw-enterprise.sh --action status < /dev/null > result.json 2> stderr.txt
echo "exit=$?"
sudo env -i /bin/sh ./detect.sh --format value < /dev/null

For a script-only MDM, run your edited copy of the wrapper the same way with no arguments.

Windows. Intune and most Windows MDMs run as SYSTEM, often from a 32-bit process. Reproduce that with a scheduled task that runs the 32-bit Windows PowerShell (SysWOW64), then again with the 64-bit one (System32). Run this from an elevated PowerShell; C:\DcSim holds your copy of the script:

$sim = 'C:\DcSim'
$engine = Join-Path $env:WINDIR 'SysWOW64\WindowsPowerShell\v1.0\powershell.exe'
$command = "/c `"`"$engine`" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $sim\detect.ps1 -MinimumVersion X.Y.Z 1>$sim\stdout.txt 2>$sim\stderr.txt`""
$action = New-ScheduledTaskAction -Execute (Join-Path $env:WINDIR 'System32\cmd.exe') -Argument $command
$principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest
Register-ScheduledTask -TaskName 'DefenseClaw MDM simulation' -Action $action -Principal $principal -Force | Out-Null
Start-ScheduledTask -TaskName 'DefenseClaw MDM simulation'
Start-Sleep -Seconds 3
while ((Get-ScheduledTask -TaskName 'DefenseClaw MDM simulation').State -eq 'Running') { Start-Sleep -Seconds 2 }
"exit=$((Get-ScheduledTaskInfo -TaskName 'DefenseClaw MDM simulation').LastTaskResult)"
Get-Content "$sim\stdout.txt", "$sim\stderr.txt"
Unregister-ScheduledTask -TaskName 'DefenseClaw MDM simulation' -Confirm:$false

Also try the failure paths your MDM must handle: a wrong pin, a config that other users can write, two runs at once (expect 1618 or 75 from one), and a run with no user signed in.

The project's CI installs every standalone package this way on each pull request: the .deb on Ubuntu 24.04, the .rpm in RHEL 9 and RHEL 8 containers that boot systemd, the macOS .pkg, and the unsigned Windows Setup. Each lane runs install, a second ensure that must change nothing, verify, status, the detection script and uninstall. The scripts it uses, scripts/test-enterprise-unix-install.sh, scripts/test-enterprise-linux-container.sh, scripts/test-enterprise-windows-install.ps1 and scripts/check_enterprise_lifecycle_result.py, also work on a disposable host of your own; see docs/TESTING.md.