Workspace ONE UEM

Install, configure, detect, repair, upgrade and remove the standalone DefenseClaw enterprise profile with Omnissa Workspace ONE UEM on Windows and macOS, with Linux install and detection notes.

Template

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

Workspace ONE UEM is an Omnissa product, formerly VMware Workspace ONE UEM. This recipe deploys the standalone profile to Windows and macOS devices with Workspace ONE apps, scripts and sensors, and the MDM kit (packaging/mdm). The contract is in Install with an MDM.

OSInstallKeep appliedDetect
WindowsWin32 app from a ZIPA script that runs ensuredetect.ps1 as the install-complete script
macOSInternal macOS app (the package)A script that runs ensureA sensor with detect.sh
LinuxLinux App Management installs the packageUse configuration managementA sensor with detect.sh

The kit scripts accept only their own flags and stop on any other argument, so put every value in the script's settings block.

Prerequisites

  • Workspace ONE UEM with Intelligent Hub on the devices. macOS scripts need Hub 20.10 and Workflow Engine 20.10 or later. Scripts and sensors cannot be assigned to employee-owned devices.
  • Windows: native x64 (requirements). macOS: Apple silicon on macOS 13 or later.
  • Your administrator config (choose the agents). The default config protects no agent.

Verify every artifact against the release's cosign-signed checksums.txt before you upload it (What you deliver).

Windows

Build the content

On a workstation with PowerShell 7.4 or later, run the kit's packager without -IntuneWinAppUtil. Despite its name, the content does not depend on Intune:

./packaging/mdm/intune/windows/New-DefenseClawIntunePackage.ps1 `
  -SetupPath .\DefenseClawSetup-Enterprise-Standalone-x64.exe `
  -Sha256 '<SHA-256 from the cosign-verified checksums.txt>' `
  -ConfigPath .\config.yaml `
  -OutputDirectory .\ws1-defenseclaw-<version> `
  -ProductVersion X.Y.Z
Compress-Archive -Path .\ws1-defenseclaw-<version>\content\* -DestinationPath .\DefenseClaw-<version>.zip

The content folder holds the Setup, config.yaml, the Install-DefenseClawIntune.ps1 launcher and intune-package.json. The launcher re-checks the pins on the device and starts /ensure JSON=1 with an absolute CONFIG= path. The packager requires a config_version: 9 config. Setup refuses a config file that a non-administrator can change, or that sits in a folder one can replace; if the device's app cache does not meet that, Setup stops with exit 1639 and names the file.

Add PowerShell 7 and the app

The lifecycle needs PowerShell 7 from the x64 MSI. Upload PowerShell-7.x.y-win-x64.msi in Resources > Apps > Native Apps > Internal > ADD > Application File, answering Yes to Is this a dependency file. Then upload the ZIP the same way (answer No) and set:

TabSettingValue
DetailsSupported Processor Architecture64-bit
FilesApp DependenciesThe PowerShell 7 dependency
FilesApp Uninstall ProcessUse Custom Script, with packaging/mdm/windows/uninstall.ps1
How To InstallRun as, Admin PrivilegesSystem, Yes
Install Commandpowershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\Install-DefenseClawIntune.ps1
Retry Count, Retry Interval, Install Timeout3, 5 minutes, 60 minutes
Installer Success Exit Code, Reboot Exit Code0, 3010
Install CompleteIdentify Application ByUsing Custom Script, PowerShell
Command to Run the Scriptpowershell.exe -NoProfile -ExecutionPolicy Bypass -File .\detect.ps1 -MinimumVersion <version>
Custom Script File, Success Exitpackaging/mdm/windows/detect.ps1, 0

detect.ps1 reads the protected marker through the 64-bit registry view. It exits 0 and prints DefenseClaw Enterprise <version> when the deployment is at that version or newer, and 1 otherwise.

Keep it healthy

Add a Windows script (Resources > Scripts > Add > Windows): PowerShell, System, timeout 900 seconds or more, code packaging/mdm/intune/windows/Remediate-Fix.ps1, on a recurring trigger. It runs enterprise windows ensure --profile standalone --json and does nothing on a healthy device.

Deliver the AI Defense key on Windows

Never put the key in the ZIP, config or script body. Add a second System script with the key as variable AIDEFENSE_KEY:

$hklm = [Microsoft.Win32.RegistryKey]::OpenBaseKey(
    [Microsoft.Win32.RegistryHive]::LocalMachine, [Microsoft.Win32.RegistryView]::Registry64)
$marker = $hklm.OpenSubKey('SOFTWARE\Cisco\DefenseClaw\Enterprise')
if ($null -eq $marker) { throw 'DefenseClaw is not installed yet' }
$cli = Join-Path ([string]$marker.GetValue('InstallRoot')) 'bin\defenseclaw.exe'
$null = $env:AIDEFENSE_KEY | & $cli enterprise secret set --name ai-defense-api-key --from-stdin --json 2>&1
exit $LASTEXITCODE

Run it once and again only to rotate. Then turn the feature on in the config (AI Defense key).

Upgrade, roll back and change the config on Windows

Build new content and add it as a new app version; raise -MinimumVersion. /ensure upgrades in place and applies the new config. In bundle mode, leave the config out and deliver a new signed bundle for a config change; a plain config is refused with bundle_required. ensure refuses a downgrade (Roll back).

Uninstall on Windows

uninstall.ps1 finds the installed CLI and runs enterprise windows uninstall; -Purge also removes enrolled accounts' data (what it removes).

Windows logs

Logs: the app's Details View, %WINDIR%\Logs\DefenseClaw\enterprise-lifecycle.log and the DefenseClaw event log.

Windows exit codes

Exit codes: 0 success, 1603 failed (retried up to Retry Count; read errors[].code), 1618 another run holds the lock (the retry usually succeeds), 1639 invalid arguments (fix the content; a retry gives the same result) (Exit codes).

A malformed, non-UTF-8 or invalid Windows candidate config returns invalid_arguments and exit 1639. Fix the content before retrying; the installed config stays in force.

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> (stage-pack script and pin example) and set guardrail.custom_packs.<name> to that path and its sha256:<digest> pin. Stage the pack again before reinstalling after a purge.

macOS

Install the package

Upload the verified defenseclaw-enterprise-<version>-darwin-arm64.pkg in Resources > Apps > Native Apps > Internal > ADD > Application File, with the metadata file from the Admin Assistant. On the app's Scripts settings set Pre-Install Script to the stage script below and Uninstall Method to Uninstall script with packaging/mdm/macos/uninstall.sh (change its first line to #!/bin/bash).

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

#!/bin/bash
# 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. A failed lifecycle fails the install after rolling back; the result is in /opt/cisco/defenseclaw/lifecycle/last-package-result.json.

Keep it applied

Add a macOS script (Resources > Scripting > Scripts): Bash, System, timeout 1800 seconds, code defenseclaw-enterprise.sh with DC_ACTION=ensure, empty source settings and the same YAML between the markers of dc_inline_config. Assign it with Run Periodically (for example every 12 hours). It applies a changed config, repairs drift, or does nothing; where the package is not installed yet it exits 1 with mdm_not_installed.

Detect on macOS

Add a sensor (Resources > Scripting > Sensors), name defenseclaw_status, Bash, System, String, code detect.sh with DC_MIN_VERSION="X.Y.Z", DC_REQUIRE_HEALTHY=1, DC_FORMAT="value". It reports the version, not-installed, outdated, unhealthy or busy.

Deliver the AI Defense key on macOS

Add a second System script with variable AIDEFENSE_KEY: printf '%s' "$AIDEFENSE_KEY" | /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-stdin --json. It fails until the package is installed, and storing the same key again changes nothing. Then enable AI Defense in the config.

Upgrade, roll back and change the config on macOS

Upload the new package as a new app version and raise DC_MIN_VERSION; edit the inline config for a config change (in bundle mode, deliver a new signed bundle instead) (Roll back).

macOS logs and exit codes

WhereWhat
Workspace ONE: the device's Scripts and Sensors tabsScript status and logs, and sensor values
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.logInstall and ensure runs, with their results (root, 0600). Uninstall removes this log with the machine state; use the script log for the uninstall result. detect.sh does not log; it prints one line.
/opt/cisco/defenseclaw/lifecycle/last-package-result.jsonThe package's own ensure result
/Library/Logs/Cisco/DefenseClaw/lifecycle.log, verify.logThe automatic apply and daily verify jobs
CodeMeaningIn Workspace ONE
0Success, or nothing to doExecuted
1The action failed and rolled back, or the wrapper refused an inputFailed; read errors[].code in the script log
2Invalid arguments, such as a missing or malformed setting (mdm_invalid_arguments). A config that does not validate exits 1 (config_invalid).Failed; fix the settings block
75Another lifecycle run or the package manager holds a lockFailed for this run; the next periodic run retries

Linux

Workspace ONE's Linux App Management installs .deb and .rpm files, and Linux sensors run Bash or Python 3. Without a config at /etc/defenseclaw/config.yaml the package installs a default that protects no agent, so stage the config and the key with your configuration-management tool (never in a profile). For detection add a Linux sensor with detect.sh from packaging/mdm/linux, System context, DC_FORMAT="value". The package's postinstall step never fails the package transaction, so check the sensor or /var/lib/defenseclaw-enterprise/last-package-result.json.