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
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.
cosignon 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 blockDo 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:
| Setting | Value |
|---|---|
| Name | DefenseClaw install |
| Trigger | Recurring Check-in |
| Execution frequency | Once per computer, with Automatically re-run policy on failure |
| Scripts payload | DefenseClaw stage config, priority Before |
| Packages payload | The DefenseClaw package, action Install |
| Maintenance payload | Update inventory |
| Scope | The 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 KEYThen 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
| Task | What to do |
|---|---|
| Upgrade | Upload 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 back | Run a script that creates the root-owned marker (touch /opt/cisco/defenseclaw/lifecycle/allow-downgrade), then deploy the earlier package (Roll back) |
| Change the config | Edit 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| Where | What |
|---|---|
| Computers > Policies > the policy > Logs | Status and script output per computer, truncated after 25 KB |
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.log | Install 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.json | The 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).
Intune on Linux
Deploy the standalone DefenseClaw enterprise profile to Intune-managed Ubuntu and Red Hat Enterprise Linux devices with a root platform script, report its health, deliver the AI Defense key and remove it.
Iru (formerly Kandji)
Install, configure, detect, repair, upgrade and remove the standalone DefenseClaw enterprise profile on Macs with Iru Endpoint Management Custom Scripts and Custom Apps.