Jamf Pro

Install, configure, detect, repair, upgrade and remove the standalone DefenseClaw enterprise profile on Macs with Jamf Pro packages, policy scripts and an extension attribute.

Template

Checked by simulating the MDM execution context; not run in a live Jamf Pro tenant. Pilot it on a small group first.

Jamf Pro installs the DefenseClaw package from your distribution point, and two scripts from the MDM kit (packaging/mdm/macos) keep the deployment configured and healthy. The recipe follows the MDM contract for exit codes, detection and how config and keys are delivered.

Prerequisites

  • Macs with Apple silicon on macOS 13 or later, and no Cisco Secure Client DefenseClaw deployment.
  • A cloud distribution point, if you upload the package through the web interface.
  • Your administrator config (choose the agents). The default config protects no agent.
  • cosign on the workstation where you verify the release.

Get and verify the release

VERSION=X.Y.Z   # the release you deploy
BASE=https://github.com/cisco-ai-defense/defenseclaw/releases/download/$VERSION
PKG=defenseclaw-enterprise-$VERSION-darwin-arm64.pkg
curl -fsSL -O "$BASE/checksums.txt" -O "$BASE/checksums.txt.bundle" -O "$BASE/$PKG"
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 "  $PKG\$" checksums.txt | shasum -a 256 -c -

You also need three scripts from packaging/mdm/macos (also in the defenseclaw-enterprise-<version>-darwin-arm64.tar.gz archive): defenseclaw-enterprise.sh (policy script that runs ensure), detect.sh (extension attribute) and uninstall.sh (removal).

How Jamf Pro runs scripts and packages

Add one line to each kit script

Jamf Pro runs scripts as root and always passes positional parameters (your values start at $4). The kit scripts accept only their own flags: any positional argument makes them exit 2 (mdm_invalid_arguments), and detect.sh prints nothing. Add this line at the top of the settings block of every kit script you upload:

set -- # Jamf Pro passes positional values; this script takes its settings from this block

Do not pass settings as Jamf Pro parameters: other processes on the Mac can read command-line arguments. Create each script in Settings > Computer management

Scripts > New.

Prepare the scripts

DefenseClaw stage config

This script writes your config to a root-only staging folder that the ensure script reads. Until the package is installed, it also writes the config to the layout path /opt/cisco/defenseclaw/etc/config.yaml, so the package applies it on the first install. Set its priority to Before.

#!/bin/sh
# DefenseClaw: stage the administrator config (Jamf Pro, priority Before).
set -eu
PATH=/usr/bin:/bin:/usr/sbin:/sbin
stage=/Library/Management/DefenseClaw
layout=/opt/cisco/defenseclaw/etc
umask 022
mkdir -p "$stage"
tmp=$(mktemp "$stage/.config.yaml.XXXXXX")
cat >"$tmp" <<'DEFENSECLAW_CONFIG'
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:
    claudecode: {}
    codex: {}
DEFENSECLAW_CONFIG
chown root:wheel "$tmp"
chmod 0600 "$tmp"
mv -f "$tmp" "$stage/config.yaml"
if [ ! -e "$layout/config.yaml" ] || ! pkgutil --pkg-info com.cisco.defenseclaw.enterprise >/dev/null 2>&1; then
    mkdir -p "$layout"
    tmp=$(mktemp "$layout/.config.yaml.XXXXXX")
    cat "$stage/config.yaml" >"$tmp"
    chown root:wheel "$tmp"
    chmod 0640 "$tmp"
    mv -f "$tmp" "$layout/config.yaml"
fi
echo "DefenseClaw config staged"

Replace the YAML with your config. Never put the AI Defense key in it.

DefenseClaw ensure

Upload defenseclaw-enterprise.sh, leave the source empty (the install policy installs the package) and set its priority to After:

set -- # Jamf Pro passes positional values; this script takes its settings from this block
DC_ACTION=ensure
DC_CONFIG_FILE="/Library/Management/DefenseClaw/config.yaml"

The wrapper refuses a config file that is not owned by root or that another account can write (mdm_untrusted_input). If Jamf cancels the run, it stops the lifecycle child and reports mdm_cancelled.

DefenseClaw uninstall

Upload uninstall.sh with the same set -- line. Set DC_PURGE=1 for a purge (what it removes).

Install

Upload the package in Settings > Computer management > Packages > New, then create a policy in Computers > Policies > New:

SettingValue
NameDefenseClaw install
TriggerRecurring Check-in
Execution frequencyOnce per computer, with Automatically re-run policy on failure
Scripts payloadDefenseClaw stage config, priority Before
Packages payloadThe DefenseClaw package, action Install
Maintenance payloadUpdate inventory
ScopeThe Smart Group DefenseClaw needs install (Detect and report)

The package's postinstall step runs enterprise macos ensure --from-package. If the lifecycle fails it has already rolled back and the install fails, so the policy log shows it. The result is in /opt/cisco/defenseclaw/lifecycle/last-package-result.json.

Keep it applied

A second policy converges the Mac every day, applies config changes and repairs drift: name DefenseClaw ensure, trigger Recurring Check-in, frequency Once every day, scripts DefenseClaw stage config (Before) then DefenseClaw ensure (After), scope the Smart Group DefenseClaw installed. To run it at once on a test Mac, give it a custom trigger and run sudo jamf policy -event <trigger> -verbose.

Deliver the AI Defense key

The key is optional. Jamf Pro parameters reach the script as command-line arguments, so do not put the key in a script, parameter, package or profile. Store it after the first install, on standard input:

read -rs KEY && printf '%s' "$KEY" | sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-stdin --json; unset KEY

Then set enterprise.inspection.ai_defense.enabled: true and credential: ai-defense-api-key in the config (AI Defense key).

Detect and report

Create a computer extension attribute (Settings > Computer management > Extension attributes > New, String, Script) with detect.sh and:

set -- # Jamf Pro passes positional values; this script takes its settings from this block
DC_MIN_VERSION="X.Y.Z"
DC_REQUIRE_HEALTHY=1
DC_FORMAT="jamf"

It always exits 0 and prints the installed version, or not-installed, outdated, unhealthy, busy (a lifecycle run holds its lock; transient) or unknown (not run as root). Build Smart Groups on it: DefenseClaw needs install is not-installed or outdated; DefenseClaw installed is a version, outdated, unhealthy or busy (for example matches regex ^([0-9]\|outdated\|unhealthy\|busy)); DefenseClaw unhealthy is unhealthy. A blank value means the Mac has not reported yet. The value changes only when the Mac submits inventory (Detection).

Upgrade, roll back and change the config

TaskWhat to do
UpgradeUpload the new package and set DC_MIN_VERSION in the extension attribute to the new version. Create a new install policy with the new package, or flush the old policy's logs: a Once per computer policy does not run again on a computer with a log entry
Roll backRun a script that creates the root-owned marker (touch /opt/cisco/defenseclaw/lifecycle/allow-downgrade), then deploy the earlier package (Roll back)
Change the configEdit the YAML in DefenseClaw stage config. The ensure policy applies it at its next run, validated first. In bundle mode, deliver a new signed bundle instead; a plain config is refused with bundle_required

Deliver a custom macOS rule pack

Before the first pkg install, add a root stage-pack script that copies the pack into /opt/cisco/defenseclaw/etc/policies/guardrail/<name> with root:wheel ownership. Use the stage-pack script and pin example, run it before the config and pkg steps, and set guardrail.custom_packs.<name> to that absolute path and its sha256:<digest> pin. Stage the pack again before reinstalling after a purge.

Uninstall

Jamf Pro's own package uninstall works only for packages indexed with Jamf Admin, which Jamf Pro 11.7 removed. Remove the Mac from the install and ensure policies, then run a policy that runs DefenseClaw uninstall. For a clean image set DC_PURGE=1 in the first removal: on a Mac without the deployment the script prints a no-op result and exits 0, so a later purge leaves state behind. Remove /Library/Management/DefenseClaw when you no longer need the staged config.

Check it worked and logs

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
WhereWhat
Computers > Policies > the policy > LogsStatus and script output per computer, truncated after 25 KB
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.logInstall and ensure runs (root, 0600). Uninstall removes this log with the machine state, so use the policy log for the uninstall result
/opt/cisco/defenseclaw/lifecycle/last-package-result.jsonThe package's own ensure result

Exit codes in Jamf Pro

Exit codes follow the Linux and macOS column of Exit codes: 0 success, 1 failed and rolled back (read errors[].code in the policy log; wrapper error codes), 2 invalid settings such as a missing set -- line, 75 another run holds a lock (the next scheduled run retries).