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.

Template

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

Kandji is now Iru (Iru and Kandji). This recipe deploys the standalone profile to Macs with Iru Library Items and the MDM kit (packaging/mdm/macos). The contract is in Install with an MDM.

RouteLibrary ItemsPackage source
Iru-hosted package (recommended)A Mac Custom App, and a Mac Custom Script that runs ensureIru hosts the package
Script onlyOne Mac Custom ScriptEach run downloads the package from your own HTTPS server and checks its SHA-256

Prerequisites

  • Macs with Apple silicon on macOS 13 or later, and no Cisco Secure Client DefenseClaw deployment.
  • For the script-only route, an HTTPS server that serves the package file directly. The wrapper does not follow HTTP redirects, and GitHub release links redirect.
  • Your administrator config (choose the agents). The default config protects no agent.

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 -
grep "  $PKG\$" checksums.txt   # the first field is the pin

How Iru runs Library Items

The kit scripts are in packaging/mdm/macos and in the release archive. You paste them into Iru, so each script's settings block holds its values. The Iru Agent runs custom scripts as root. An audit exit 0 is Pass; any other code is Error and raises an alert. The kit scripts accept only their own flags and exit 2 on any other argument, so put every value in the settings block.

Iru-hosted package route

The package

Add a Mac Custom App Library Item named DefenseClaw 1 package, assigned to your Blueprints:

SettingValue
Package TypeInstaller Package, the package you verified
Execution FrequencyAudit and enforce
Audit scriptdetect.sh, with DC_MIN_VERSION="X.Y.Z" and DC_FORMAT="exit"
Pre-install scriptThe stage script below

The audit exits 0 when the Mac has the deployment at that version or newer, so Iru reinstalls the package only when it is missing or older. While a lifecycle run holds its lock it exits 75 (busy), so that audit fails once; the next check-in passes.

The pre-install script puts your config at /opt/cisco/defenseclaw/etc/config.yaml before the package installs, so the package's own ensure --from-package applies it. Once the package is installed (its pkg receipt exists) it never overwrites the config.

#!/bin/sh
# DefenseClaw: put the administrator config in place before a first install.
set -eu
PATH=/usr/bin:/bin:/usr/sbin:/sbin
layout=/opt/cisco/defenseclaw/etc
if [ -e "$layout/config.yaml" ] && pkgutil --pkg-info com.cisco.defenseclaw.enterprise >/dev/null 2>&1; then
    exit 0
fi
umask 022
mkdir -p "$layout"
tmp=$(mktemp "$layout/.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 0640 "$tmp"
mv -f "$tmp" "$layout/config.yaml"

Replace the YAML with your config. Never put the AI Defense key in it. If the lifecycle fails, the postinstall step fails the install and the Custom App shows Error; the result is in /opt/cisco/defenseclaw/lifecycle/last-package-result.json.

The ensure script

Add a Mac Custom Script named DefenseClaw 2 ensure (it sorts after the package), assigned to the same Blueprints, Run daily. Paste defenseclaw-enterprise.sh as the Audit Script, leave the source settings empty so the wrapper re-applies the installed deployment, and put the same YAML between the markers of its inline config:

DC_ACTION=ensure

dc_inline_config() {
    cat <<'DEFENSECLAW_CONFIG'
# the same config YAML as the pre-install script
DEFENSECLAW_CONFIG
}

Leave the Remediation Script empty. Each run, the wrapper stages the inline config in a root-only folder and runs enterprise macos ensure with it: it applies a changed config, repairs drift, or does nothing, and exits with the lifecycle's code. A cancelled run stops its lifecycle child and reports mdm_cancelled; inspect the deployment before retrying. The script is its own audit because detect.sh does not compare configs.

Script-only route

Use one Mac Custom Script named DefenseClaw ensure, Run daily, with defenseclaw-enterprise.sh as the Audit Script and the source in its settings block, together with the inline config above:

DC_ACTION=ensure
DC_SOURCE_URL="https://packages.example.com/defenseclaw/defenseclaw-enterprise-<version>-darwin-arm64.pkg"
DC_SOURCE_SHA256="<the pin from checksums.txt>"
DC_TRUST_MODE=hash_pinned
DC_PRODUCT_VERSION="X.Y.Z"

Each run downloads the package, checks it against the pin (mdm_hash_mismatch otherwise), installs it when its version differs, and runs ensure. Use a direct HTTPS file URL: a GitHub release link may answer HTTP 302, which the wrapper reports instead of treating the empty response as a hash mismatch.

Optional health report

Add a Mac Custom Script DefenseClaw health, Run daily, with detect.sh as its Audit Script and DC_MIN_VERSION="X.Y.Z", DC_REQUIRE_HEALTHY=1, DC_FORMAT="exit". It exits 0 and prints DefenseClaw Enterprise <version> when the Mac is installed, current and passes verify; otherwise it exits 1 and explains on standard error (Iru: Error). See Detection.

Deliver the AI Defense key

The key is optional. Iru's script variables carry device and user details, not secrets, so do not paste the key into a Library Item. 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).

Upgrade, roll back and change the config

TaskIru-hosted package routeScript-only route
UpgradeUpload the new package to the Custom App and raise DC_MIN_VERSION in its audit scriptChange the URL, the pin and DC_PRODUCT_VERSION
Roll backRoll backRoll back
Change the configEdit the inline config in the ensure scriptEdit the inline config in the ensure script

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

Remove the DefenseClaw Library Items from the Blueprints first. Then run uninstall.sh once as a Mac Custom Script (Install once per device, or on demand from Self Service). Set DC_PURGE=1 in its settings block for a purge (what it removes). On a Mac without the deployment it prints a no-op result and exits 0.

Check it worked and logs

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
WhereWhat
The Library Item status in IruAudit and remediation output. Pass when the Mac matches your settings
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.logInstall and ensure runs (root, 0600). Uninstall removes this log with the machine state, so use the audit log for the uninstall result
/opt/cisco/defenseclaw/lifecycle/last-package-result.jsonThe package's own ensure result

Exit codes in Iru

Exit codes: 0 Pass; 1 failed and rolled back or an input was refused (read errors[].code; wrapper error codes); 2 invalid settings (mdm_invalid_arguments; a config that does not validate exits 1, config_invalid); 75 another run or the installer holds a lock, retried on the next run (Exit codes).