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.

Template

Checked by simulating the MDM execution context; not run in a live Configuration Manager site. Pilot it on a small collection first.

This recipe deploys the standalone profile to Windows devices with Microsoft Configuration Manager (formerly SCCM and MECM). An application installs and upgrades DefenseClaw, and an optional configuration item keeps it healthy. The contract is in Install with an MDM.

Prerequisites

  • Native x64 Windows that meets the Windows requirements, with no Cisco Secure Client DefenseClaw deployment.
  • PowerShell 7 from Microsoft's x64 MSI, deployed as its own application. The kit recommends 7.4 or later.
  • Your administrator config.yaml (choose the agents). The default config protects no agent.
  • DefenseClawSetup-Enterprise-Standalone-x64.exe, verified against the release's cosign-signed checksums.txt (What you deliver).

A Script Installer deployment type with Install for system installs once, for all users. Script Installer's default return codes apply (0 Success, 1641 Hard Reboot, 3010 Soft Reboot, 1618 Fast Retry; other codes fail). A detection script that exits non-zero leaves the state Unknown.

How Configuration Manager runs the application

These are Configuration Manager behaviors this recipe depends on. They come from Microsoft's documentation, not from DefenseClaw: check the linked pages if your site version differs.

BehaviorDefaultSource
Return codes0 Success (no reboot), 1641 Hard Reboot, 3010 Soft Reboot, 1618 Fast Retry. Other codes are failures.Create applications
Fast RetryRetries every two hours, 10 times in totalCreate applications
TimeoutMaximum allowed run time is 120 minutesCreate applications
Detection scriptA non-zero exit code means failed, and the state is Unknown. Exit 0 with output on STDOUT is Installed. Exit 0 with no output is Not installed. Exit 0 with output on STDERR only is Unknown.Create applications
Re-evaluationClients re-evaluate deployments every seven daysClient settings
Scripts the client runsThe PowerShell execution policy client setting is All SignedClient settings

Build the content

On a workstation with PowerShell 7.4 or later, run the kit's packager without -IntuneWinAppUtil and use its content folder as the content location. 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 \\server\sources\DefenseClaw\<version> `
  -ProductVersion X.Y.Z

content holds the Setup, your config_version: 9 config (the packager refuses version 8, because migration changes the pinned detection hash), the Install-DefenseClawIntune.ps1 launcher and intune-package.json with the SHA-256 pins. The launcher re-checks the pins and starts /ensure JSON=1 with an absolute CONFIG= path, because Setup refuses relative paths. Setup also refuses a config file that a non-administrator can change, or that sits in a folder one can replace; if the client cache does not meet that, Setup stops with exit 1639 and names the file.

Create the application

Create the PowerShell 7 application first (Windows Installer deployment type for the x64 MSI). Then in Software Library > Application Management > Applications

Create Application, choose Manually specify the application information and add a Script Installer deployment type:

PageSettingValue
ContentContent locationThe content folder, such as \\server\sources\DefenseClaw\<version>\content
Installation programpowershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\Install-DefenseClawIntune.ps1
Uninstall programDefenseClawSetup-Enterprise-Standalone-x64.exe /uninstall JSON=1
Run as 32-bit process on 64-bit clientsCleared
Detection MethodRegistryHKEY_LOCAL_MACHINE, key SOFTWARE\Cisco\DefenseClaw\Enterprise, value ProductVersion, Version, Greater than or equal to <version>, 32-bit association cleared
User ExperienceInstallation behaviorInstall for system, Whether or not a user is logged on, Hidden, run time 120
DependenciesDependency groupThe PowerShell 7 application, Auto Install

Deploy it to a device collection as Required. 1603 and 1639 report as failures: read the error code before you retry, because 1639 always needs a fix. 1618 means another lifecycle run holds the lock; Fast Retry handles it.

Why registry detection

The lifecycle writes ProductVersion in the 64-bit view only after a successful install, upgrade, repair or ensure, and removes the key after a successful uninstall; only SYSTEM and administrators can write it. Do not use packaging/mdm/windows/detect.ps1 here: it exits 1 when DefenseClaw is not installed, which Configuration Manager reports as Unknown, not Not installed. The first install needs the config in the content: /ensure without one exits 1639.

Keep it healthy

The registry value proves what is installed, not that it enforces. To repair drift, create a configuration item (Assets and Compliance > Compliance Settings > Configuration Items, type Windows Desktops and Servers (custom)) with one Script setting, data type String, and a rule that the value Equals Compliant with Remediate noncompliant rules when supported. Discovery script:

$hklm = [Microsoft.Win32.RegistryKey]::OpenBaseKey(
    [Microsoft.Win32.RegistryHive]::LocalMachine, [Microsoft.Win32.RegistryView]::Registry64)
$marker = $hklm.OpenSubKey('SOFTWARE\Cisco\DefenseClaw\Enterprise')
if ($null -eq $marker) { 'Compliant'; exit 0 }
$cli = Join-Path ([string]$marker.GetValue('InstallRoot')) 'bin\defenseclaw.exe'
$null = & $cli enterprise windows verify --profile standalone --json 2>&1
if ($LASTEXITCODE -eq 0) { 'Compliant' } else { 'NonCompliant' }

Remediation script (throws on failure so Configuration Manager reports it):

$hklm = [Microsoft.Win32.RegistryKey]::OpenBaseKey(
    [Microsoft.Win32.RegistryHive]::LocalMachine, [Microsoft.Win32.RegistryView]::Registry64)
$marker = $hklm.OpenSubKey('SOFTWARE\Cisco\DefenseClaw\Enterprise')
if ($null -eq $marker) { exit 0 }
$cli = Join-Path ([string]$marker.GetValue('InstallRoot')) 'bin\defenseclaw.exe'
$null = & $cli enterprise windows ensure --profile standalone --json 2>&1
if ($LASTEXITCODE -ne 0) { throw "DefenseClaw ensure exited $LASTEXITCODE" }

Add the item to a baseline and deploy it with remediation. The client runs these under the PowerShell execution policy client setting (default All Signed): sign the scripts or change the setting. Scripts time out after 60 seconds unless you raise Script Execution Timeout (seconds), up to 600; if a repair times out, run the application's /ensure again on that device. Health means what verify reports (Health fields).

Deliver the AI Defense key

The key is optional. Do not put it in the content, config, a command line or a script. Store it after the first install, from an elevated session or your secrets tooling:

Get-Content -Raw C:\secure\ai-defense-key.txt | & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret set --name ai-defense-api-key --from-stdin --json

It runs only elevated with a standalone deployment installed, stores the key and restarts the gateway. Then set enterprise.inspection.ai_defense.enabled: true and credential: ai-defense-api-key (AI Defense key).

Upgrade, roll back and change the config

TaskWhat to do
UpgradeBuild content for the new release and create a new application. On its Supersedence tab add the old application and leave Uninstall cleared. Raise the detection rule to the new version
Roll backensure refuses to downgrade on Windows (Roll back)
Change the configSee Change the config. The registry rule checks the version only, so it does not run the application again for a config-only change

Change the config

On a device in bundle mode (bundle trust anchors installed), deliver a new signed bundle instead: Setup refuses a config change with bundle_required. Otherwise:

Build new content with the new config_version: 9 config.yaml and create it as a new application with the same Setup. Replace the registry rule with a Script detection method that also checks the installed config. Take the minimum version and the config_sha256 value from the new content's intune-package.json. A script that exits 0 with output means Installed; no output means Not installed, so devices with the old config run the new application and /ensure validates and applies it.

$minimum = [version]'X.Y.Z'
$configSha256 = 'replace-with-config_sha256-from-intune-package.json'
$base = [Microsoft.Win32.RegistryKey]::OpenBaseKey([Microsoft.Win32.RegistryHive]::LocalMachine, [Microsoft.Win32.RegistryView]::Registry64)
$key = $base.OpenSubKey('SOFTWARE\Cisco\DefenseClaw\Enterprise')
if ($null -eq $key) { exit 0 }
$version = [string]$key.GetValue('ProductVersion')
$stateRoot = [string]$key.GetValue('StateRoot')
$key.Dispose()
$base.Dispose()
$core = ($version -split '[-+]')[0]
if (-not $core -or [version]$core -lt $minimum) { exit 0 }
$config = Join-Path $stateRoot 'etc\config.yaml'
if (-not (Test-Path -LiteralPath $config -PathType Leaf)) { exit 0 }
$actual = (Get-FileHash -LiteralPath $config -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $configSha256.ToLowerInvariant()) { exit 0 }
Write-Output "DefenseClaw Enterprise $version"
exit 0

Do not edit the installed file by hand: changes made outside Setup are not validated.

Uninstall

Remove the baseline deployment first, so remediation does not run against a removed deployment. Then deploy the application with the Uninstall action. The uninstall program removes the machine deployment; add PURGE=1 to also remove each enrolled account's %USERPROFILE%\.defenseclaw and per-user binaries (what it removes).

Check it worked and logs

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --profile standalone --json
WhereWhat
%WINDIR%\CCM\Logs\AppEnforce.log, AppDiscovery.logApplication install and detection
%WINDIR%\CCM\Logs\DcmWmiProvider.logConfiguration item scripts
%WINDIR%\Logs\DefenseClaw\enterprise-lifecycle.logEvery lifecycle result, one JSON line per run

Exit codes in Configuration Manager

Exit codes: 0 success, 1603 failed and rolled back (read errors[].code; lifecycle error codes), 1618 Fast Retry, 1639 invalid arguments (fix the content), 3010 reserved (Exit codes).

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