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
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.
| OS | Install | Keep applied | Detect |
|---|---|---|---|
| Windows | Win32 app from a ZIP | A script that runs ensure | detect.ps1 as the install-complete script |
| macOS | Internal macOS app (the package) | A script that runs ensure | A sensor with detect.sh |
| Linux | Linux App Management installs the package | Use configuration management | A 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>.zipThe 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:
| Tab | Setting | Value |
|---|---|---|
| Details | Supported Processor Architecture | 64-bit |
| Files | App Dependencies | The PowerShell 7 dependency |
| Files | App Uninstall Process | Use Custom Script, with packaging/mdm/windows/uninstall.ps1 |
| How To Install | Run as, Admin Privileges | System, Yes |
| Install Command | powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\Install-DefenseClawIntune.ps1 | |
| Retry Count, Retry Interval, Install Timeout | 3, 5 minutes, 60 minutes | |
| Installer Success Exit Code, Reboot Exit Code | 0, 3010 | |
| Install Complete | Identify Application By | Using Custom Script, PowerShell |
| Command to Run the Script | powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\detect.ps1 -MinimumVersion <version> | |
| Custom Script File, Success Exit | packaging/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 $LASTEXITCODERun 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
| Where | What |
|---|---|
| Workspace ONE: the device's Scripts and Sensors tabs | Script status and logs, and sensor values |
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.log | Install 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.json | The package's own ensure result |
/Library/Logs/Cisco/DefenseClaw/lifecycle.log, verify.log | The automatic apply and daily verify jobs |
| Code | Meaning | In Workspace ONE |
|---|---|---|
0 | Success, or nothing to do | Executed |
1 | The action failed and rolled back, or the wrapper refused an input | Failed; read errors[].code in the script log |
2 | Invalid 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 |
75 | Another lifecycle run or the package manager holds a lock | Failed 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.
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.
Configuration Manager
Install, configure, detect, repair, upgrade and remove the standalone DefenseClaw enterprise profile on Windows with a Microsoft Configuration Manager application and compliance settings.