AI Defense key

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_key in the config is refused.
• cisco_ai_defense.api_key_env and .env files 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

Install the deployment first, then store the key. enterprise secret set refuses to run until a deployment is installed (on Windows, secret remove does too):

The MDM wrappers follow the same order for you; see Deliver the key with an MDM.

Where the key is stored

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 set runs 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 -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_KEY

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name ai-defense-api-key --from-file /root/ai-defense-api-key

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_KEY

icacls C:\Admin /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F"
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret set --name ai-defense-api-key --from-file C:\Admin\ai-defense-api-key.txt
Remove-Item C:\Admin\ai-defense-api-key.txt

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 region

Apply 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 status

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise secret status --json

To confirm a key matches the one you hold, compare the digest prefix with the first 12 characters of the key's SHA-256, for example from printf '%s' "$AID_KEY" | sha256sum on Linux or printf '%s' "$AID_KEY" | shasum -a 256 on macOS.

The lifecycle status (enterprise linux status, enterprise macos status or enterprise windows status, with --json) has an inspection.ai_defense field:

On Windows, ok reflects the config and gateway readiness; it does not prove the key was accepted. On Linux and macOS this release reports unknown. To confirm that the gateway loaded the key, check the gateway log for an error from the cisco-inspect subsystem after the restart: a missing or untrusted key is logged there. 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.

Remove the key

sudo /opt/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-key

Set enabled: false in the config as well. Otherwise the gateway keeps logging that the credential is missing, while the local engine decides alone.

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:

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

On Windows a --from-file path that non-administrators can write is also refused with 1639.