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.

Validation

An Intune-managed Ubuntu device ran the root platform script in the PR #1304 end-to-end pass, and DefenseClaw identity checks ran on it in the test tenant. See Prepare your Intune tenant.

Intune manages Ubuntu and Red Hat Enterprise Linux devices enrolled with the Microsoft Intune app. It deploys Bash platform scripts but no Linux app packages, so one root platform script downloads, verifies, installs and configures DefenseClaw. You upload your copy of packaging/mdm/linux/defenseclaw-enterprise.sh with its settings block and config filled in. Every day it downloads the .deb (Ubuntu), the .rpm (RHEL) or the payload archive from your HTTPS host, installs it when the version differs, and runs ensure. Health is the script's run status plus a second root platform script with detect.sh. Removal is a root platform script with packaging/mdm/linux/uninstall.sh.

On an enforcing fapolicyd host, use the deb or rpm with this script. Its payload-archive path runs one ensure and does not update staged-payload and installed-tree trust before activation. To use a tarball on such a host, follow the two-stage tarball flow outside this wrapper.

This recipe follows the MDM contract; read it first for exit codes, detection and logs.

After the first install or a reinstall, ask users to restart agent sessions that were already open. Those sessions keep running without DefenseClaw until restarted. status and ensure report agent_sessions_restart_required while they remain open.

Before you start

  • Tenant: licences and device groups are in place (Prepare your Intune tenant). Intune has no Linux enrollment setting.
  • Devices: a distribution on Microsoft's list of Intune-supported Linux platforms, enrolled with the Microsoft Intune app, running systemd 239 or later.
  • Release: verify checksums.txt and read the pin of the artifact you deploy (What you deliver). Ubuntu needs the .deb, RHEL the .rpm. On an enforcing fapolicyd host use the package with this script. The payload archive runs its gateway from /var/lib/defenseclaw-mdm, which must allow execution.
  • Config: write the config (Settings), without the AI Defense key.

1. Host the artifact

Put the package on an HTTPS location the devices can reach. The wrapper downloads with curl (or wget) and accepts only https:// URLs that serve the file itself: it does not follow redirects, so a GitHub release link fails. 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/linux/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>-linux-amd64.deb"
DC_SOURCE_SHA256="replace-with-the-64-hex-sha256-from-checksums.txt"
DC_TRUST_MODE=hash_pinned
DC_PRODUCT_VERSION="X.Y.Z"

Ubuntu and RHEL need different packages: create one script per distribution and assign each to a device group that holds only that distribution, or use the payload archive in a single script on hosts without fapolicyd. For GPG trust, set DC_TRUST_MODE=signed, DC_GPG_KEYRING and DC_SIGNATURE_URL (reference).

Then paste the config between the DEFENSECLAW_CONFIG markers in dc_inline_config:

dc_inline_config() {
    cat <<'DEFENSECLAW_CONFIG'
config_version: 9
deployment_mode: managed_enterprise
data_dir: /var/lib/defenseclaw
policy_dir: /etc/defenseclaw/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
}

On Linux, data_dir must be exactly /var/lib/defenseclaw. Never put the AI Defense key in the script: Microsoft states that custom scripts must not carry sensitive information.

3. Add the platform script

In the Intune admin center: Devices > Manage devices > Configuration > Create > New policy > Linux > Settings catalog > Create profile > Custom Configuration (linuxMdm). The review page may show Platform: No Platform.

SettingValue
Execution contextRoot. The Intune daemon still needs authorization for com.microsoft.intune.actions.ConfigureDevice (polkit rule below)
Execution frequencyEvery 1 day. With DC_SOURCE_URL set, every run downloads the artifact before it compares versions
Execution retriesNo retries. The wrapper itself makes up to three attempts on exit 75 (busy): the first run and two retries, 10 seconds apart. Intune may count a cached retry inside its frequency window as successful without rerunning the script
Execution scriptYour edited copy of defenseclaw-enterprise.sh

Assign it to device groups. A busy package manager, for example during unattended upgrades, exits 75 (mdm_package_manager_busy). An older .deb is refused before dpkg -i changes the host.

For a local-group profile assignment, upload packaging/mdm/intune/linux/sync-local-group.sh as a second root platform script, after editing GROUP_NAME and the complete MEMBERS array. It refuses pre-existing groups unless a root administrator has claimed them (see Identity through Intune). An account removed from MEMBERS whose primary group is the synced group moves to its own group (the one named after it, created when missing) with usermod -g; its open sessions keep the old group until the next sign-in. When that group is not local, is a system group or has other members, the script names the account and exits 1; change its primary group by hand.

For unattended root scripts, authorize only your enrolled Intune users for the daemon's polkit action. Without it, an xrdp or SSH session has no active local seat and the daemon can fail before the script starts. Put enrolled users in a dedicated local group and install this root-owned file as /etc/polkit-1/rules.d/49-intune-scripts.rules:

polkit.addRule(function(action, subject) {
    if (action.id === "com.microsoft.intune.actions.ConfigureDevice" &&
        subject.isInGroup("intune-script-operators")) {
        return polkit.Result.YES;
    }
});

A policy edit reaches a device at its next agent check-in (about one hour plus up to ten minutes), or after the user selects Refresh in the Intune app.

4. Report health

The platform script's own run status is the first signal: it fails whenever ensure fails. For a separate health signal, add a second root platform script: a copy of packaging/mdm/linux/detect.sh with DC_REQUIRE_HEALTHY=1 and, optionally, DC_MIN_VERSION="X.Y.Z". It exits 0 when DefenseClaw is installed, new enough, passes verify, reports coverage_complete: true and has no incomplete-security reason other than hook_process_fail_open, unprivileged_user_namespaces and unprivileged_ptrace, and 1 otherwise. Set DC_REQUIRE_SECURITY_COMPLETE=1 instead to also require security_complete: true. Set its retries to No retries.

Intune's custom compliance cannot run detect.sh (Microsoft runs Linux discovery scripts as the signed-in user, and DefenseClaw's status is readable only by root), and a failed platform script does not make a Linux device noncompliant. Read each script's per-device status instead (open the configuration profile and select Device status). The package database answers inventory:

DefenseClaw leaves Linux kernel settings as found. If the observed values allow unprivileged namespaces or ptrace, status and verify report incomplete security. detect.sh --require-healthy still exits 0 and prints the warnings; --require-security-complete reports unhealthy. An administrator may apply optional host hardening with their own tools. There is no DefenseClaw pending-reboot state.

dpkg-query -W -f='${Status} ${Version}\n' defenseclaw-enterprise
rpm -q defenseclaw-enterprise

Deliver the Cisco AI Defense key

After DefenseClaw is installed, deliver the key once through an administrator channel such as SSH or a secrets agent that runs as root, after the config turns the feature on (Cisco AI Defense key):

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

Delete 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 the script and save. The next run validates and applies it. An invalid config fails the run with config_invalid and leaves the installed config unchanged. In bundle mode (bundle trust anchors installed), a changed config is refused with bundle_required and the installed one stays; deliver a new signed bundle instead.
  • Upgrade: host the new artifact, then update DC_SOURCE_URL, DC_SOURCE_SHA256 and DC_PRODUCT_VERSION. Keep each host on one channel: a host installed from the deb or rpm refuses a payload-archive upgrade. For a tarball host with fapolicyd, use the staged-payload trust and two-stage upgrade outside this wrapper.
  • Roll back: rpm -U refuses an older rpm. See Roll back.

Remove DefenseClaw

If the config names a custom rule pack, run and confirm the pack-delivery script before the package and config script. After an uninstall with purge, /etc/defenseclaw and its pack are gone. Reassign or change the pack script so Intune executes it again, confirm the pack is staged, then reassign the install script. A missing pack causes config_invalid.

First remove the devices from the install script's assignment. Then assign a root platform script with packaging/mdm/linux/uninstall.sh; set DC_PURGE=1 in its settings block for a purge (what it removes). On a host with nothing installed it exits 0. A plain removal keeps your policies in /etc/defenseclaw/policies.

Check it worked

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json

ok: true and installed: true mean the script landed. The wrapper writes /var/log/defenseclaw-enterprise-mdm.log (root, 0600); the package's own ensure result is in /var/lib/defenseclaw-enterprise/last-package-result.json. After the install the lifecycle runs restorecon on /opt/defenseclaw and /etc/defenseclaw where SELinux is enabled.