AI Defense key
Store the Cisco AI Defense API key of a standalone deployment as a protected credential on Windows, Linux and macOS, turn AI Defense on, check and rotate the key, and deliver it with an MDM.
In the standalone profile the local policy engine always decides. You can add Cisco AI Defense to it with an API key. The key is a protected credential: a file in an administrator-only directory that only the gateway service can read. It never appears in the config, on a command line, or in the environment.
- An inline
cisco_ai_defense.api_keyin the config is refused. cisco_ai_defense.api_key_envand.envfiles are ignored in this profile.- If the key is missing or fails its trust check, the gateway logs an error and the local engine keeps deciding alone.
See Concepts for the terms.
Before you start
On Linux and macOS the key can be stored before or after the install. Stored
before the install, it stays readable by root only (enterprise secret set
reports not_installed as a warning and exits 0), and the install gives the
gateway its access, so a config that references the key installs at once.
On Windows, install the deployment first: enterprise secret set and
secret remove refuse with no standalone managed deployment is installed,
exit 1603.
The MDM wrappers follow the same order for you; see Deliver the key with an MDM.
Where the key is stored
| OS | File | Owner and mode | How the gateway reads it |
|---|---|---|---|
| Linux, systemd 247 or later | /etc/defenseclaw/secrets/<name> | root, 0600; directory root, 0700 | systemd passes it with LoadCredential=. The gateway cannot read the secrets directory itself. |
| Linux, older systemd | /etc/defenseclaw/secrets/<name> | root, group defenseclaw, 0640; directory 0750 | Reads the file through its group |
| macOS | /opt/cisco/defenseclaw/etc/secrets/<name> | root, group _defenseclaw, 0640; directory 0750 | Reads the file through its group |
| Windows | C:\ProgramData\Cisco\DefenseClaw\secrets\<name> | Owner Administrators. Protected DACL: full control for SYSTEM and Administrators; read for NT SERVICE\DefenseClawGateway only. On the secrets folder the gateway gets only the rights to traverse it and read its attributes and security descriptor, so it can check the file's parents. | Reads the file as its service identity |
Before the gateway uses a stored key, it checks the file:
- Linux and macOS. A root-owned regular file with one link, that other users cannot read, in directories only administrators can write.
- Windows. Only SYSTEM, Administrators and the gateway service may read
it.
enterprise secret setruns this check right after writing and deletes the file if it fails.
The value must be a single line of at most 16 KiB, without NUL bytes. Linux and macOS remove one trailing line ending; Windows removes all leading and trailing whitespace.
Store the key
Pick a credential name: lowercase letters, digits and dashes, starting with
a letter or digit. The examples use ai-defense-api-key.
Read the key without echoing it, then pipe it in:
read -rs AID_KEY
printf '%s' "$AID_KEY" | sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-stdin
unset AID_KEYOr read it from a root-only file:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-file /root/ai-defense-api-keyThe command stores the key, then runs ensure with reason secret, which
restarts the gateway so it reads the key. The apply path unit would also
pick up the change. The output starts with ✓ secret set: done and
- stored credential ai-defense-api-key, followed by the apply steps. On most
Linux hosts it starts with ! secret set: done with N warnings and the
warning lines instead (for example hook_process_fail_open,
unprivileged_user_namespaces, unprivileged_ptrace), then
- stored credential ai-defense-api-key. The warnings are the host's normal
status, not a failed store.
read -rs AID_KEY
printf '%s' "$AID_KEY" | sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-stdin
unset AID_KEYThe command stores the key, then runs ensure with reason secret, which
restarts the gateway so it reads the key. On a host whose status has
warnings the output starts with ! secret set: done with N warnings and the
warning lines (for example openshell_prerequisite_missing,
hook_process_fail_open, security_incomplete), then
- stored credential ai-defense-api-key; on a host without warnings it starts
with ✓ secret set: done and - stored credential ai-defense-api-key. The
warnings are the host's normal status, not a failed store, and
secret remove prints the same header.
Run from an elevated PowerShell 7 session. --from-file accepts only a
file that non-administrators cannot write. On Windows client editions a new
folder under C:\ inherits write access for authenticated users, so create
an administrator-only folder first, write the key into it from a prompt that
does not echo it, store it, and delete the file:
$Stage = 'C:\ProgramData\DefenseClaw-Staging'
New-Item -ItemType Directory -Path $Stage -Force | Out-Null
icacls $Stage /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
$Key = Read-Host -AsSecureString 'Cisco AI Defense API key'
[System.Net.NetworkCredential]::new('', $Key).Password | Set-Content -NoNewline -Path "$Stage\ai-defense-api-key.txt"
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret set --name ai-defense-api-key --from-file "$Stage\ai-defense-api-key.txt"
Remove-Item "$Stage\ai-defense-api-key.txt"
Remove-Variable KeyThis is the same staging folder the Windows install uses.
The command stores the key and restarts the DefenseClawGateway service
if it is running. A stopped gateway reads the key when it next starts.
Pass exactly one of --from-stdin or --from-file. Add --json for a
machine-readable result.
Turn on AI Defense
Name the credential in the config and set enabled: true:
enterprise:
inspection:
ai_defense:
enabled: true
credential: ai-defense-api-key
cisco_ai_defense:
endpoint: https://us.api.inspect.aidefense.security.cisco.com # the default; change for another regionApply the config as usual: on Linux and macOS the apply job runs ensure
when the file changes; on Windows run ensure again with the new file (see
Change the config).
credential is required when enabled is true. You can turn AI Defense
on before or after you store the key: until the key is present, the
gateway logs an error and the local engine decides alone.
If outbound HTTPS goes through a proxy, set enterprise.network; see
Network proxy. The AI
Defense client uses it on every OS.
Check the key
enterprise secret status lists each stored credential without its value:
name, the first 12 characters of the value's SHA-256, modification time and
(Linux and macOS) file mode.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret statusOn macOS use sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret status.
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret status --jsonThe lifecycle status (enterprise linux status, enterprise macos status
or enterprise windows status, with --json) has an
inspection.ai_defense field:
| Value | Linux and macOS | Windows |
|---|---|---|
disabled | enabled is false | enabled is false |
ok | Cisco AI Defense answered a request with the stored key | enabled is true and the gateway is ready |
unavailable:<code> | AI Defense is enabled but not working. <code> is credential_unavailable (the key is missing or fails its trust check), auth_failed (the key was rejected), proxy_auth_required, proxy_config, unreachable, not_initialized or error. status and verify also warn ai_defense_unavailable | unavailable:gateway_not_ready: enabled is true but the gateway is not ready |
unknown | The gateway has not reported yet, for example right after a restart, before the key has been tried | The gateway did not report its inspection state |
On Linux and macOS the value comes from the gateway's own /health, so ok
means the key works. On Windows, ok reflects the config and gateway
readiness and does not prove the key was accepted: check the gateway log for
an error from the cisco-inspect subsystem after the restart, where a
missing or untrusted key is logged. To prove the key on any OS without waiting for a prompt, run
enterprise secret check --name <credential> --json as root (Linux, macOS) or
from an elevated PowerShell prompt (Windows,
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe' enterprise secret check --name ai-defense-api-key --json):
it makes one request whose only content is a full stop and prints ok when
the key is accepted, rejected when AI Defense answers HTTP 401 or 403, or
unavailable:<code> when the credential or request cannot be checked. It exits
0 when the key is accepted, 1 (Windows 1603) otherwise. See
Logs and events.
Rotate the key
Run enterprise secret set again with the same name and the new value.
The file is replaced atomically and the gateway restarts, as above. Revoke
the old key in AI Defense after secret status shows the new digest.
A device that applies signed policy bundles keeps the key the confirmed
bundle binds: from 1.0.4 each bundle binds the value of every credential it
names, and secret set refuses another value with secret_ref_mismatch. A
bundle signed before 1.0.4 names the key without its value, so secret set
refuses it with secret_ref_unbound. After an upgrade from 1.0.2 or 1.0.3
the confirmed bundle keeps enforcing, but every delivery of it is refused
until a bundle signed for 1.0.4 is in place. To rotate the key on a device
that applies signed policy bundles, contact your administrator: secret set
alone cannot change it.
Remove the key
Removal refuses a key that enabled AI Defense inspection still references
(enterprise.inspection.ai_defense.credential). A reference under disabled inspection does not prevent removal: a disabled AI Defense reference alone never blocks it.
Disable inspection and remove its reference before deleting the stored key:
- In the config you deploy, set
enabled: falseunderenterprise.inspection.ai_defenseand delete itscredentialline. - Apply the config with
ensure. - Remove the key:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret remove --name ai-defense-api-keyOn macOS use sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret remove --name ai-defense-api-key.
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret remove --name ai-defense-api-keyIf enabled AI Defense inspection still names the key, the command exits 1 (1603 on Windows)
with the installed config still references credential ai-defense-api-key, and
nothing is removed. On Linux and macOS a successful removal prints
- removed credential ai-defense-api-key, or
- credential ai-defense-api-key was not stored; nothing to remove.
When the host has status warnings it first prints ! secret remove: done with N warnings
(or ! secret remove: nothing to do (up_to_date), N warnings) and the warning lines.
On Windows, removal reads the installed config to check for references.
If it cannot read that config, it refuses and leaves the credential in place;
restore config access, then run the command again.
Deliver the key with an MDM
Never put the key in an MDM script body or on a command line: neither is secret storage. The MDM wrappers take the key from standard input or from a file only administrators can write, apply the deployment first, then store the key:
| Wrapper | Key options |
|---|---|
defenseclaw-enterprise.sh (Linux and macOS) | --secret-name ai-defense-api-key with --secret-stdin or --secret-file FILE |
Invoke-DefenseClawEnterprise.ps1 (Windows) | -SecretName ai-defense-api-key with -SecretFromStdin or -SecretPath FILE |
The wrapper refuses a key file that a non-administrator can write
(mdm_untrusted_input), and reports mdm_secret_failed when storing the
key fails after the deployment applied. See
Deliver the AI Defense key
for recipes.
Exit codes
| Result | Linux and macOS | Windows |
|---|---|---|
| Stored, listed or removed | 0 | 0 |
Invalid input: an invalid credential name, both or neither of --from-stdin and --from-file, or an empty, multi-line or oversized value | 2 | 1639 |
| Not elevated or not root, not installed (Windows only), the config still references the credential on removal, or the write failed | 1 | 1603 |
The follow-up ensure failed and rolled back | 1 | Not applicable |
| Another lifecycle run holds the lock | 75 | Not applicable |
| The gateway restart failed after the key was stored | Not applicable | 1603 |
A --from-file path that another account could change is also refused
before anything is stored: on Linux and macOS a symlink, a file that group or
others can write or that another account owns, or a file in a folder another
account can write (exit 2); on Windows a path that non-administrators can
write (exit 1639).
Foreign-hook guard
How the standalone profile stops user and project hooks that DefenseClaw has not approved from changing an AI agent's tool call after inspection, which agents and files it covers on each OS, and how to approve or restore a hook.
Account join key
How a standalone device reports a per-tenant key for each account that ran an agent, so a fleet service can match device records to its directory accounts without the device sending names or SIDs.