Intune on macOS
Deploy the standalone DefenseClaw enterprise profile to Apple silicon Macs with a Microsoft Intune shell script, report its version with a custom attribute, deliver the AI Defense key and remove it.
Validation
9.9.9 (build f9ed814b1, PR #1304): install, an offline period and repeated uninstall. A cached install can still reinstall after removal; see Remove DefenseClaw. The earlier removal check used test package 1.0.902. These test builds do not certify later releases or the PKG app route.You upload one root shell script: your copy of
packaging/mdm/macos/defenseclaw-enterprise.sh with its settings block and config
filled in. Every day it downloads defenseclaw-enterprise-<version>-darwin-arm64.pkg
from your HTTPS host, installs it when the version differs, and runs ensure. A
custom attribute from detect.sh reports the installed version, not-installed,
outdated, unhealthy, or busy while a lifecycle run holds its lock. Removal is a
root shell script with packaging/mdm/macos/uninstall.sh.
This recipe follows the MDM contract; read it first for exit codes, detection and logs.
Before you start
- Tenant: the Apple push certificate, device groups and licences are in place and the Macs are enrolled (Prepare your Intune tenant).
- Macs: Apple silicon on macOS 13.0 or later.
- Intune: Intune runs macOS shell scripts only over a direct internet connection, not through a proxy, and stops a script after 60 minutes.
- Release: verify
checksums.txtand read the pkg's SHA-256 pin (What you deliver). - Config: write the config (Settings), without the AI Defense key.
Choose a route
Use Route A, the shell script, unless you must use app assignments. Intune's
macOS app (PKG) type reports success from the app bundles listed under Included
apps. This package installs command-line binaries and no .app bundle, so Intune
can report a working install as failed. Route B is at the end of this page.
Route A: one root shell script
1. Host the package
Put the pkg on an HTTPS location the Macs reach without a proxy. Use a
direct HTTPS file URL: the wrapper does not follow redirects, so a GitHub release link fails with
HTTP 302. If the download needs a proxy, set DC_HTTPS_PROXY; only the download uses it.
2. Fill in the wrapper's settings block
Copy packaging/mdm/macos/defenseclaw-enterprise.sh and edit the settings block at
the top. Intune runs the script with no arguments, so every value goes here:
DC_ACTION=ensure
DC_SOURCE_URL="https://downloads.example.com/defenseclaw/defenseclaw-enterprise-<version>-darwin-arm64.pkg"
DC_SOURCE_SHA256="replace-with-the-64-hex-sha256-from-checksums.txt"
DC_TRUST_MODE=hash_pinned
DC_PRODUCT_VERSION="X.Y.Z"Paste your config between the DEFENSECLAW_CONFIG markers in dc_inline_config.
This minimal one protects Claude Code and Codex in observe mode
(choose the agents):
dc_inline_config() {
cat <<'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: {}
ai_discovery:
enabled: true
DEFENSECLAW_CONFIG
}An inline data_dir must be exactly /opt/cisco/defenseclaw/runtime. Never put the
AI Defense key in the script: Intune scripts are not secret storage. For Developer ID
trust on a signed and notarized pkg, set DC_TRUST_MODE=signed and
DC_ALLOWED_TEAM_IDS.
3. Add the script in Intune
Devices > By platform > macOS > Manage devices > Scripts > Add:
| Setting | Value |
|---|---|
| Upload script | Your edited copy of defenseclaw-enterprise.sh, with the config added |
| Run script as signed-in user | No (runs as root) |
| Hide script notifications on devices | Yes |
| Script frequency | Every 1 day. With DC_SOURCE_URL set, every run downloads the pkg before it compares versions |
| Max number of times to retry if script fails | 3. Exit 75 means another run or the installer was busy; a later run succeeds |
Assign it to device groups. The script's run status in Intune is Success for exit 0
and Failed otherwise.
4. Report the version with a custom attribute
Copy packaging/mdm/macos/detect.sh and set DC_FORMAT="value" in its settings
block (optionally DC_MIN_VERSION="X.Y.Z" and DC_REQUIRE_HEALTHY=1). In
Devices > By platform > macOS > Organize devices > Custom attributes
for macOS > Add, set Data type to String and upload your copy. Intune
runs it about every 8 hours, and it must run as root: without root it reports
unknown. The pkg receipt is the other inventory signal:
pkgutil --pkg-info com.cisco.defenseclaw.enterprise.
Route B: macOS app (PKG)
Add the pkg in Apps > All Apps > Create > macOS app (PKG). Its
post-install step runs enterprise macos ensure --from-package and uses the config
already at /opt/cisco/defenseclaw/etc/config.yaml, or the built-in default, which
protects no agents. So set Ignore app version to No, deliver the config with
the Route A script (with DC_SOURCE_URL empty), and track the result with the Route A
custom attribute, not the app's install status.
Deliver the Cisco AI Defense key
Intune scripts and custom attributes are not secret storage. After DefenseClaw is installed, deliver the key once through an administrator channel that runs as root, after the config turns the feature on (Cisco AI Defense key):
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set \
--name ai-defense-api-key --from-file /var/root/ai-defense.key
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret statusDelete the source file afterwards. Storing the key re-runs ensure, which applies it.
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.
Change the config, upgrade and roll back
- Change the config: edit it in your script and save. Intune runs the new version
and
ensurevalidates and applies it. An invalid config fails the run withconfig_invalidand leaves the installed config unchanged. In bundle mode (bundle trust anchors installed), a changed config is refused withbundle_requiredand the installed one stays; deliver a new signed bundle instead. - Upgrade: host the new pkg, then update
DC_SOURCE_URL,DC_SOURCE_SHA256andDC_PRODUCT_VERSION. - Roll back: Roll back.
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.
Remove DefenseClaw
First remove the Macs from the install script's assignment. The Intune agent for macOS keeps running a cached recurring install script after its assignment is removed: in the test tenant, Graph confirmed the script had no assignments, yet the Mac ran it again 4 seconds and 16 minutes later. A cached install run after the uninstall reinstalls the pkg. Before you assign uninstall:
- Check the Intune agent log on each Mac (
/Library/Logs/Microsoft/Intune) and wait until each Mac has checked in and the install script's policy ID has stopped appearing. - Assign the uninstall script as a new script object. A run-once script that already ran on a Mac does not run again when you reassign it.
- After the uninstall, check at the next check-ins that
pkgutil --pkg-info com.cisco.defenseclaw.enterprisefinds no package. If a cached install run reinstalled DefenseClaw, run the uninstall again with another new script object.
The uninstall is a root shell script set to run once, with
packaging/mdm/macos/uninstall.sh; set DC_PURGE=1 in its settings block for a
purge (what it removes).
Troubleshoot
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --jsonok: true and installed: true mean the script landed. Where to look otherwise:
| Where | What |
|---|---|
| Scripts > your script > Device status | Intune's run status per Mac |
/Library/Logs/Microsoft/Intune | The Intune agent's logs |
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.log | Install and ensure results (root, 0600); uninstall removes this log, so use the Intune script output for its result |
/opt/cisco/defenseclaw/lifecycle/last-package-result.json | The pkg's own ensure result |
For Entra users and groups on a Mac see Identity through Intune; for privacy prompts see the macOS reference.
Intune on Windows
Deploy the standalone DefenseClaw enterprise profile to Windows x64 with a Microsoft Intune Win32 app, keep it healthy with Remediations, deliver the AI Defense key, change the config and remove it.
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.