Environment variables

Supported DefenseClaw and Fleet environment variables, with defaults, accepted values, and source readers.

Every environment variable DefenseClaw reads, with defaults, accepted values and the file that reads it. The catalog is generated from internal/envvars/registry.json; CI checks every DEFENSECLAW_* reference and every direct Fleet and Edge DCLAW_* reader against it.

Observability policy lives in config.yaml

Ambient DEFENSECLAW_OTEL_*, standard OTEL_EXPORTER_OTLP_* and DEFENSECLAW_DISABLE_REDACTION values are not live collection, routing or redaction policy. Destinations name credential variables explicitly through fields such as token_env, bearer_env or {env: NAME}. Rows described as legacy observability inputs are read only by the automatic upgrade converter and are retired after their value is materialized.

On per-user installs, defenseclaw doctor reports active security override flags visible to the CLI process. Inspect the gateway and Edge Connector service environments separately when they run under systemd or another supervisor. A Codex TUI or app server can outlive the shell that launched it, so set its hook posture in guardrail.hook_fail_mode instead of relying on a shell export.

Managed hosts and the environment

Per-user installs and the Secure Client profile read the raw environment for the variables they support. Secure Client profile selection requires its trusted install marker, and its 1.0.4 hooks ignore DEFENSECLAW_FAIL_MODE. A managed standalone host (deployment_mode: managed_enterprise, enterprise.profile: standalone) is different: the administrator owns config.yaml, and every row below has a Managed host policy that stops user-controlled opt-outs from weakening it.

Fleet and Edge DCLAW_* variables marked allow are read by the Go or C service process, and some (TLS verification overrides) can weaken security. Administrators control the service environment; defenseclaw doctor cannot inspect a separate systemd service's environment.

Managed hostWhat a managed standalone host does with the value
allowUses it. This includes runtime paths, credentials, hook-script values, and Fleet service variables. Restrict access to service environments containing Fleet secrets or TLS overrides.
ignoreTreats it as unset. This covers core DEFENSECLAW_* security opt-outs (DEFENSECLAW_FAIL_MODE among them; DEFENSECLAW_STRICT_AVAILABILITY and DEFENSECLAW_MANAGED_TRUST_STRICT_ANCESTORS are tighten_only instead), DEFENSECLAW_HOOK_MAX_BODY (managed hooks keep a fixed 1 MiB cap), the debug switches, most telemetry inputs, discovery probes, the Splunk bridge variables, test fixtures, DEFENSECLAW_REPO, DEFENSECLAW_NO_UPDATE_CHECK, most upgrade-internal variables, and the two deployment pins described below.
tighten_onlyUses it only when it makes the host stricter: DEFENSECLAW_STRICT_AVAILABILITY can only force fail-closed, and DEFENSECLAW_MANAGED_TRUST_STRICT_ANCESTORS can only restore strict ancestor checks. DEFENSECLAW_FAIL_MODE is not one of them: a managed hook uses only the fail mode the administrator installed, so DEFENSECLAW_FAIL_MODE=closed in an agent's environment does not close an outage the administrator set to open.
  • .env follows the same rule. The gateway and the CLI load <data_dir>/.env at start. A variable that is already set in the process environment wins over the file, and on a managed standalone host an entry the registry marks ignore is skipped. Some names are refused from .env on every host, because a file in the data directory must not change how a process starts: PATH, HOME, DEFENSECLAW_HOME, DEFENSECLAW_CONFIG, DEFENSECLAW_FAIL_MODE, DEFENSECLAW_STRICT_AVAILABILITY, every DEFENSECLAW_ALLOW_* switch, and DEFENSECLAW_ENTERPRISE_PROFILE, among others.

  • Python doctor names what it ignored. If the Python CLI reads a managed config, its Security overrides section lists ignored names, never values. Managed packages do not ship this doctor; use Check what is active below.

    [PASS] Ignored environment overrides  —  this device is managed, so these have no effect: DEFENSECLAW_ALLOW_CGNAT, DEFENSECLAW_JUDGE_TRACE
  • The deployment pins cannot be used to change what kind of host this is. DEFENSECLAW_DEPLOYMENT_MODE and DEFENSECLAW_ENTERPRISE_PROFILE are set by the managed service definitions, never by a user. A host is managed when either its config.yaml or the service environment says managed_enterprise, so unsetting or changing the variable in a shell cannot turn a managed host into an unmanaged one. Both pins are refused from .env. The reverse is no escalation either: on a per-user install (a config.yaml in your home folder that does not itself say managed_enterprise), a DEFENSECLAW_DEPLOYMENT_MODE or DEFENSECLAW_ENTERPRISE_PROFILE exported in a shell is dropped when the command starts. The writers keep writing as usual, and defenseclaw doctor lists the variable under Ignored environment overrides. It does not enrol the device or apply an administrator's policy.

  • Settings have a config key where one exists. DEFENSECLAW_REPO is the deprecated alias of update.source, DEFENSECLAW_NO_UPDATE_CHECK has update.check: false, and guardrail.judge.trace replaces DEFENSECLAW_JUDGE_TRACE (which is read only on the Secure Client integration). DEFENSECLAW_CUSTOM_PROVIDERS_PATH names the derived custom-providers.json, not an input. See Source of truth.

Security opt-outs

VariableWhat it does
DEFENSECLAW_ALLOW_CGNAT
Impact: HIGH
Default: unset (CGNAT blocked)
Values: 1, unset
Managed host: ignore
Allow RFC 6598 carrier-grade NAT addresses (100.64.0.0/10, used by Tailscale and similar overlays) through the SSRF / private-IP guards.
Security: CGNAT egress guard — prevents SSRF into shared carrier-grade NAT / overlay-network address space (e.g. another tenant's Tailscale node).
Read by: internal/netguard/netguard.go, cli/defenseclaw/webhooks/writer.py, cli/defenseclaw/registries/ssrf.py
DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT
Impact: HIGH
Default: unset (fail-closed)
Values: 1, unset
Managed host: ignore
Bypass the fail-closed checks for agent versions with no hook contract (below the tested floor, on the known-broken list, or an unmatched exact build; refused in observe and action mode by setup, init, quickstart and a single-connector gateway start), for unverified versions in action mode, and for incompatible hook-contract lock drift during connector setup.
Security: Hook contract verification — prevents installing an enforcing hook whose request/response contract has drifted from the verified matrix (a silent guardrail bypass).
Read by: internal/gateway/sidecar.go, cli/defenseclaw/commands/cmd_setup.py, cli/defenseclaw/bootstrap.py
DEFENSECLAW_ALLOW_LOCAL_MCP_TARGETS
Impact: HIGH
Default: unset (SSRF guard enforced)
Values: 1, unset
Managed host: ignore
Skip SSRF validation for MCP scan target URLs, permitting loopback, private, link-local, and cloud-metadata destinations.
Security: MCP scan-target SSRF guard — prevents a scan request from reaching IMDS / loopback / private hosts.
Read by: internal/scanner/mcp.go
DEFENSECLAW_ALLOW_PRIVATE_UPSTREAMS
Impact: HIGH
Default: unset (all private IPs blocked)
Values: comma-separated IPs (e.g. 10.50.2.100,172.16.0.5), unset
Managed host: ignore
Comma-separated list of specific IP addresses exempt from the SSRF private-address block for LLM upstream forwarding.
Security: Private-upstream SSRF guard exemption — allows operator-specified on-prem LLM gateways on RFC 1918 addresses to bypass the private-IP block. Each IP must be explicitly listed (no CIDR).
Read by: internal/netguard/allowlist.go, cli/defenseclaw/registries/ssrf.py
DEFENSECLAW_CODEX_LOOPBACK_TRUST
Impact: HIGH
Default: unset (fail-closed)
Values: 1, unset
Managed host: ignore
Restore legacy loopback-trusts-any-bearer behavior for the Codex connector.
Security: Per-bearer Codex authentication on loopback — prevents same-host user-to-user impersonation when multiple users share an OS account.
Read by: internal/gateway/connector/codex.go
DEFENSECLAW_DEV
Impact: low
Default: unset
Values: 1, true, unset
Managed host: ignore
Mark the process as a developer build.
Read by: internal/redaction/credentials.go
DEFENSECLAW_DISABLE_AWS_HTTP1_SHIM
Impact: medium
Default: unset (shim active for Bedrock)
Values: 1, unset
Managed host: ignore
Disable the AWS Bedrock HTTP/1 monkey-patch the OpenClaw plugin installs to make Bedrock traffic visible to the guardrail proxy.
Read by: extensions/defenseclaw/src/aws-sdk-http1-for-guardrail.ts
DEFENSECLAW_DISABLE_REDACTION
Impact: HIGH
Default: unset (ignored by the v8 runtime)
Values: 1, true, unset
Managed host: ignore
Upgrade-only v7 migration input.
Fix: Configure observability.defaults, bucket, or destination redaction_profile in config v8.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_DUMP_RAW_SECRETS
Impact: HIGH
Default: unset
Values: 1, unset
Managed host: ignore
E2E test toggle ONLY.
Read by: scripts/test-e2e-full-stack.sh
DEFENSECLAW_FAIL_MODE
Impact: medium
Default: (value from guardrail.hook_fail_mode in config.yaml)
Values: open, closed, unset
Managed host: ignore
Not read by 1.0.4 hooks in any profile: a hook's fail mode is the guardrail.hook_fail_mode installed with it (the shell hook, the OpenCode plugin, hooks/.hookcfg for the native Windows hook), and status and doctor report that.
Read by: cli/defenseclaw/fail_mode.py
DEFENSECLAW_FORCE_AWS_HTTP1_SHIM
Impact: low
Default: unset (shim only on Bedrock)
Values: 1, unset
Managed host: ignore
Force the AWS HTTP/1 shim to install even on non-Bedrock setups.
Read by: extensions/defenseclaw/src/aws-sdk-http1-for-guardrail.ts
DEFENSECLAW_GATEWAY_AUTOSTART
Impact: low
Default: unset (hooks start a stopped per-user gateway)
Values: 0, false, no, off
Managed host: ignore
Set to 0, false, no or off in the agent's environment to stop the Unix hooks from starting a stopped per-user gateway when their request is refused.
Read by: internal/gateway/connector/hooks/_hardening.sh, internal/gateway/connector/hook_test_env_helpers_test.go
DEFENSECLAW_JSONL_DISABLE
Impact: low
Default: unset (ignored by the v8 runtime)
Values: 1, true, unset
Managed host: ignore
Upgrade-only v7 migration input.
Fix: Add, disable, or remove an explicit kind: jsonl destination in config v8.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_MANAGED_TRUST_STRICT_ANCESTORS
Impact: medium
Default: unset (ancestor verdicts are advisory; CMID broker object drift is repaired or accepted; other managed paths stay strict)
Values: 1, true, yes, on, unset
Managed host: tighten_only
Restore fatal owner/DACL/permission verdicts for the directories ABOVE the managed roots.
Security: Inverted flag: setting it only hardens. The relaxation it disables is the AIFW-34262 default — an untrusted grant on a shared platform-owned parent no longer fails a managed install, which previously aborted after quiesce had disabled every service and left the endpoint unprotected. Set this on hosts where DefenseClaw owns the whole path chain and an untrusted ancestor must be treated as compromise.
Read by: internal/managed/trust_advisory.go, packaging/windows/DefenseClawEnterprise.psm1, packaging/macos/install.sh, internal/gateway/connector/hook_api_token_unix.go, internal/gateway/connector/hook_api_token_windows.go, internal/managed/trust_windows.go, internal/managed/cmidbroker/key_windows.go
DEFENSECLAW_NO_SANDBOX
Impact: medium
Default: unset
Values: 1, unset
Managed host: ignore
Set to 1 to run a harness natively for one command when it has been wrapped for the sandbox in your shell (for example DEFENSECLAW_NO_SANDBOX=1 claude), where your organization allows a host run: on a managed computer whose policy lists the agent in required_for the host run is still refused unless the account is in enterprise.enrollment.exempt_users, or sandboxes are unavailable to the account and the effective when_unavailable setting is alert; a per-user gateway does not read required_for.
Read by: internal/openshell/wrapper/wrapper.go, internal/openshell/sandboxcli/wrappers.go, internal/openshell/sandboxcli/doctor.go
DEFENSECLAW_OTEL_TLS_INSECURE
Impact: HIGH
Default: unset
Values: true, false, 1, 0, unset
Managed host: ignore
Upgrade-only v7 migration input for the former flat OTLP TLS-insecure toggle.
Fix: Configure observability.destinations[].tls in config v8.
Security: Enabling this variable disables OTLP server-certificate verification after legacy configuration is migrated into a named destination.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_POLICY_VALIDATE_ALLOW_NO_OPA
Impact: medium
Default: unset (validation needs opa or defenseclaw-gateway)
Values: 1, unset
Managed host: ignore
Skip the Rego compile check when neither opa nor defenseclaw-gateway is available.
Read by: cli/defenseclaw/commands/cmd_policy.py
DEFENSECLAW_REVEAL_PII
Impact: medium
Default: unset (PII redacted everywhere)
Values: 1, true, unset
Managed host: ignore
Reveal PII in operator-facing logs only (CLI stdout, TUI).
Read by: internal/redaction/redaction.go
DEFENSECLAW_STRICT_AVAILABILITY
Default: unset (no additional force-closed override)
Values: 1, true, TRUE, yes, YES, unset
Managed host: tighten_only
Force transport and missing-token hook failures closed even when the effective fail mode is open, on the hooks that read it (the gateway outage table of the connectors capability matrix lists them), and only when the process running the hook inherits this variable.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_TEST
Impact: low
Default: unset
Values: 1, true, unset
Managed host: ignore
Mark the process as running under tests.
Read by: internal/redaction/credentials.go
DEFENSECLAW_TOOL_INSPECT_FAIL_OPEN
Impact: HIGH
Default: ignored by 1.0.9
Values: 1, true, unset
Managed host: ignore
Legacy OpenClaw tool-inspection outage override through 1.0.8.
Read by: extensions/defenseclaw/src/__tests__/index.test.ts
DEFENSECLAW_TRUSTED_PROXY_CIDRS
Impact: medium
Default: unset (X-Forwarded-For ignored)
Values: comma-separated CIDRs or IPs, unset
Managed host: ignore
Comma-separated CIDRs (or bare IPs) of reverse-proxy peers whose X-Forwarded-For header is trusted for client-IP attribution in logs.
Security: Client-IP attribution — trusting forwarded headers from an untrusted peer lets a caller spoof the source IP recorded in auth-failure and audit logs.
Read by: internal/gateway/requestctx.go
DEFENSECLAW_UNGUARDED_CHATGPT_CODEX_RESPONSES
Impact: HIGH
Default: unset (guardrail proxy enforced)
Values: 1, unset
Managed host: ignore
Allow ChatGPT Codex response-backend requests to bypass the guardrail proxy.
Fix: Leave unset for normal guarded operation; use only while diagnosing proxy incompatibility.
Security: Codex response guardrail enforcement — prevents model prompt/response traffic from silently bypassing observe/action policies unless the operator explicitly opts into an unguarded fallback.
Read by: extensions/defenseclaw/src/fetch-interceptor.ts
DEFENSECLAW_UPGRADE_ALLOW_UNVERIFIED
Default: unset (no effect)
Values: 1, unset
Managed host: ignore
Retired 0.x upgrade override with no effect in 1.x.
Fix: Remove it; 1.x checks every release asset against checksums.txt and has no unverified mode.
Read by: internal/cli/root.go, cli/defenseclaw/file_permissions.py
DEFENSECLAW_WEBHOOK_ALLOW_LOCALHOST
Impact: medium
Default: unset (SSRF guard blocks private IPs)
Values: 1, unset
Managed host: ignore
Relax the webhook SSRF guard to permit localhost and loopback destinations only; private (RFC 1918), link-local and cloud-metadata addresses stay blocked.
Read by: internal/gateway/webhook.go, cli/defenseclaw/webhooks/writer.py
DEFENSECLAW_WINDOWS_ROLLBACK_SIGNED_OUT_ACCOUNTS
Impact: medium
Default: unset (signed-out accounts are restored through an S4U logon)
Values: 0, unset
Managed host: ignore
Skip the S4U logon that the rollback of a failed first Windows standalone install uses to put back a signed-out account's agent configuration.
Security: Cleanup opt-out: with 0, a signed-out account can keep agent hook configuration that points at the rolled-back install until an administrator removes the listed leftovers.
Read by: internal/enterprisehooks/rollback_first_install_windows.go

Credentials & secrets

VariableWhat it does
DEFENSECLAW_CMID_BROKER_AUTH_KEY
Impact: HIGH
Default: unset (legacy in-process provider path)
Values: absolute installer-owned broker-auth.key path, unset
Managed host: allow
Select the protected 32-byte key used by the Windows gateway to authenticate credential broker responses.
Security: Authentication material path — the key bytes never belong in an environment variable, log, event, or diagnostic; the environment contains only its protected path.
Read by: internal/managed/cmidbroker/broker.go
DEFENSECLAW_DECISION_MODEL_KEY
Impact: medium
Default: unset
Values: bearer token string, unset
Managed host: ignore
Canonical env-var name for the decision model bearer token (decision_model.api_key_env when empty).
Read by: internal/config/decision_model.go, cli/defenseclaw/credentials.py
DEFENSECLAW_GATEWAY_TOKEN
Impact: HIGH
Default: unset
Values: bearer-token, unset
Managed host: allow
Bearer token hooks present to the gateway API.
Read by: internal/gateway/connector/hooks/inspect-tool.sh, internal/cli/sidecar.go
DEFENSECLAW_INIT_CISCO_API_KEY
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw init' (--cisco-api-key).
Read by: cli/defenseclaw/commands/cmd_init.py
DEFENSECLAW_INIT_LLM_API_KEY
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw init' (--llm-api-key).
Read by: cli/defenseclaw/commands/cmd_init.py
DEFENSECLAW_LLM_KEY
Impact: HIGH
Default: unset
Values: LLM API key string, unset
Managed host: allow
Canonical env-var name for the unified LLM key.
Read by: cli/defenseclaw/credentials.py
DEFENSECLAW_LLM_KEY_ENV
Impact: low
Default: DEFENSECLAW_LLM_KEY
Values: any env-var name
Managed host: allow
Indirection: name of the env var to read the LLM key from.
Read by: cli/defenseclaw/credentials.py
DEFENSECLAW_LLM_MODEL
Impact: low
Default: (value from llm.model in config.yaml)
Values: provider/model-id, unset
Managed host: allow
Override the configured LLM model id at runtime.
Read by: cli/tests/test_config.py
DEFENSECLAW_LLM_MODEL_ENV
Impact: low
Default: DEFENSECLAW_LLM_MODEL
Values: any env-var name
Managed host: allow
Indirection: name of the env var to read the LLM model from.
Read by: cli/defenseclaw/credentials.py
DEFENSECLAW_LOCAL_PASSWORD
Impact: HIGH
Default: unset
Values: any-string, unset
Managed host: allow
Password for the local Splunk daemon basic-auth surface.
Read by: bundles/splunk_local_bridge/bin/splunk-claw-bridge
DEFENSECLAW_LOCAL_SPLUNK_HEC_TOKEN
Impact: HIGH
Default: unset
Values: cryptographically random HEC token, unset
Managed host: allow
Generated HEC token for the owned bundled Local Splunk sink.
Read by: cli/defenseclaw/observability/local_splunk.py, cli/defenseclaw/commands/cmd_setup.py
DEFENSECLAW_LOCAL_USERNAME
Impact: medium
Default: unset
Values: any-string, unset
Managed host: allow
Username for the local Splunk daemon basic-auth surface.
Read by: bundles/splunk_local_bridge/bin/splunk-claw-bridge
DEFENSECLAW_PD_KEY
Impact: medium
Default: unset
Values: pagerduty-key, unset
Managed host: allow
Alias for DEFENSECLAW_PD_ROUTING_KEY.
Read by: cli/defenseclaw/commands/cmd_setup_webhook.py
DEFENSECLAW_PD_ROUTING_KEY
Impact: medium
Default: unset
Values: pagerduty-routing-key, unset
Managed host: allow
PagerDuty routing key default for webhook entries.
Read by: cli/defenseclaw/commands/cmd_setup_webhook.py
DEFENSECLAW_REGISTRY_TOKEN
Impact: medium
Default: unset
Values: registry-token, unset
Managed host: allow
Default registry auth env var (e.g. SkillsHub).
Read by: cli/defenseclaw/commands/cmd_registry.py
DEFENSECLAW_SANDBOX_TOKEN
Impact: HIGH
Default: (set by DefenseClaw in the sandbox)
Values: OpenShell credential placeholder, binding token (token_delivery: env), unset
Managed host: allow
Per-sandbox binding token the sandbox hooks present to the DefenseClaw hook ingress.
Security: Never log or persist the value. Sandbox hooks must read it from the environment at request time; a placeholder baked into static config does not resolve.
Read by: internal/openshell/sandbox_env.go, internal/gateway/connector/hooks/_sandbox.sh, internal/gateway/connector/hooks/claude-code-hook.sh, internal/gateway/connector/hooks/codex-hook.sh, internal/gateway/connector/claudecode_sandbox.go, internal/gateway/connector/codex_sandbox.go, internal/openshell/harness/codex.go
DEFENSECLAW_SCANNER_AID_API_KEY
Impact: HIGH
Default: unset (set by the gateway for the scanner runtime)
Values: secret-value, unset
Managed host: allow
Secret transport of the Cisco AI Defense API key (cisco_ai_defense.api_key or api_key_env) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan), so the key never appears on its command line.
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_API_KEY
Impact: HIGH
Default: unset (set by the gateway for the scanner runtime)
Values: secret-value, unset
Managed host: allow
Secret transport of the LLM judge API key (llm.api_key or api_key_env) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan), so the key never appears on its command line.
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SETUP_GATEWAY_TOKEN
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw setup gateway' (--token).
Read by: cli/defenseclaw/commands/cmd_setup.py, cli/defenseclaw/tui/panels/setup.py
DEFENSECLAW_SETUP_LLM_API_KEY
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw setup llm' (--api-key).
Read by: cli/defenseclaw/commands/cmd_setup.py, cli/defenseclaw/tui/panels/setup.py
DEFENSECLAW_SETUP_OBSERVABILITY_TOKEN
Impact: HIGH
Default: unset
Values: provider-token, unset
Managed host: allow
Short-lived secret transport for 'defenseclaw setup observability add'.
Read by: cli/defenseclaw/commands/cmd_setup_observability.py, cli/defenseclaw/tui/panels/setup.py
DEFENSECLAW_SETUP_SPLUNK_ACCESS_TOKEN
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw setup splunk' (--access-token).
Read by: cli/defenseclaw/commands/cmd_setup.py, cli/defenseclaw/tui/panels/setup.py
DEFENSECLAW_SETUP_SPLUNK_HEC_TOKEN
Impact: HIGH
Default: unset
Values: secret-value, unset
Managed host: allow
Secret transport for 'defenseclaw setup splunk' (--hec-token).
Read by: cli/defenseclaw/commands/cmd_setup.py, cli/defenseclaw/tui/panels/setup.py
DEFENSECLAW_SIEM_SECRET
Impact: medium
Default: unset
Values: any-string, unset
Managed host: allow
SIEM webhook secret default.
Read by: cli/defenseclaw/commands/cmd_setup_webhook.py
DEFENSECLAW_SKILLSSH_TOKEN
Impact: medium
Default: unset
Values: registry-token, unset
Managed host: allow
Example registry-specific token env var.
Read by: cli/defenseclaw/commands/cmd_registry.py
DEFENSECLAW_SKILL_SCANNER_LLM_KEY
Impact: HIGH
Default: unset
Values: LLM API key string, unset
Managed host: allow
Override the LLM key used by the skill scanner only.
Read by: cli/defenseclaw/credentials.py
DEFENSECLAW_SPLUNK_HEC_TOKEN
Impact: HIGH
Default: unset
Values: HEC token, unset
Managed host: allow
Credential reference of remote Splunk HEC destinations written before 1.0.4.
Read by: cli/defenseclaw/observability/presets.py
DEFENSECLAW_WEBEX_TOKEN
Impact: medium
Default: unset
Values: webex-bot-token, unset
Managed host: allow
Webex bot token default for webhook entries.
Read by: cli/defenseclaw/commands/cmd_setup_webhook.py
DEFENSECLAW_WEBHOOK_SECRET
Impact: medium
Default: unset
Values: any-string, unset
Managed host: allow
Generic webhook HMAC secret default.
Read by: cli/defenseclaw/commands/cmd_setup_webhook.py

Paths & runtime layout

VariableWhat it does
DEFENSECLAW_API_ADDR
Impact: low
Default: (templated value from gateway.api_port at hook install time)
Values: host:port, unset
Managed host: allow
Sidecar API address that hooks dial.
Read by: internal/gateway/connector/hooks/inspect-tool.sh
DEFENSECLAW_APP_PATH
Default: /Applications/DefenseClawMac.app when present
Values: any-absolute-path, none
Managed host: allow
macOS app bundle that install.sh replaces with the release's app; none skips the app.
Read by: scripts/install.sh
DEFENSECLAW_ASSEMBLER_PAYLOAD_PATH
Default: unset (set only by DefenseClawAssembler.exe)
Values: <absolute path to Authenticode-signed payload file>, unset
Managed host: allow
Internal IPC channel: the standalone Windows AVC assembler (cmd/windows-avc-assembler) sets this before spawning powershell.exe so the child PS script can locate the payload file to inspect via $env:DEFENSECLAW_ASSEMBLER_PAYLOAD_PATH.
Read by: cmd/windows-avc-assembler/signature.go
DEFENSECLAW_BIN
Impact: low
Default: (discovered via PATH lookup)
Values: any-absolute-path
Managed host: allow
Override path to the defenseclaw CLI binary.
Read by: internal/scanner/plugin_test.go, scripts/setup-llm.sh
DEFENSECLAW_BUILDID
Default: unset
Values: defenseclaw-enterprise-setup-<40-char-lowercase-sha>, unset
Managed host: allow
Reproducible-build id for the Windows managed-enterprise AVC assembly step.
Read by: packaging/scripts/lib/repro-flags.sh, packaging/scripts/lib/repro-flags.ps1, .github/workflows/windows-deterministic-build.yml
DEFENSECLAW_CMID_BROKER_PIPE
Impact: HIGH
Default: unset (legacy in-process provider path)
Values: \\.\pipe\DefenseClawCMIDBroker, installer-owned certification pipe, unset
Managed host: allow
Identify the exact local named pipe used by the restricted Windows gateway to reach the isolated managed credential provider broker.
Security: Local IPC identity boundary — the installer pins this value in the protected gateway service registry environment; partial configuration fails closed.
Read by: internal/managed/cmidbroker/broker.go
DEFENSECLAW_CMID_BROKER_SERVICE_NAME
Impact: HIGH
Default: unset (legacy in-process provider path)
Values: DefenseClawCMIDBroker, installer-owned certification broker service, unset
Managed host: allow
Bind the gateway broker client to the exact installer-owned LocalSystem credential broker service.
Security: SCM identity boundary — changing this value cannot redirect the client because only exact production and certification tuples are accepted.
Read by: internal/managed/cmidbroker/broker.go
DEFENSECLAW_CONFIG
Impact: medium
Default: ${DEFENSECLAW_HOME}/config.yaml
Values: any-absolute-path, unset
Managed host: allow
Override the config.yaml path independently from DEFENSECLAW_HOME.
Security: Managed config path separation — lets system services read admin-owned policy without making the runtime data directory admin-writable.
Read by: internal/config/defaults.go, cli/defenseclaw/config.py, cli/defenseclaw/migrations.py
DEFENSECLAW_CUSTOM_PROVIDERS_PATH
Impact: low
Default: unset
Values: any-absolute-path, unset
Managed host: allow
Path of the derived custom-providers.json overlay, for test and container installs; DefenseClaw writes that file from llm_providers in config.yaml, so change llm_providers, not the file.
Read by: internal/configs/embed.go
DEFENSECLAW_DEPLOYMENT_MODE
Impact: HIGH
Default: unset (use config.yaml deployment_mode)
Values: managed_enterprise, unmanaged_byod, unset
Managed host: ignore
Pin the process deployment mode independently from config.yaml.
Security: Immutable managed-mode boundary — prevents config replacement from disabling administrator-owned path and ownership checks. Deferred-config installs additionally use this pin as the deploy-mode probe BEFORE config.yaml loads, so a mis-set value would incorrectly hard-exit (OSS drift) or spin the wait loop (managed_enterprise drift) — the finite value set in accepted_values guards both cases. Refused from .env files: only the service definition may set it.
Read by: internal/config/config.go, internal/cli/config_v8_wait.go, internal/cli/enterprise_hooks.go, packaging/systemd/defenseclaw-gateway.service, packaging/launchd/com.cisco.secureclient.defenseclaw.plist, packaging/windows/DefenseClawEnterprise.psm1, internal/cli/root.go
DEFENSECLAW_ENTERPRISE_PROFILE
Impact: HIGH
Default: unset (use config.yaml enterprise.profile; then secure_client on Windows/macOS, standalone on Linux)
Values: secure_client, standalone, unset
Managed host: ignore
Pin the managed_enterprise profile (secure_client or standalone) in every managed service environment, next to DEFENSECLAW_DEPLOYMENT_MODE, so a config replacement cannot switch the decision and identity stack.
Security: Immutable profile boundary. Must agree with config.yaml enterprise.profile; a mismatch refuses to start. Only meaningful with DEFENSECLAW_DEPLOYMENT_MODE=managed_enterprise; setting it on an unmanaged process is an error. Refused from .env files: only the service definition may set it.
Read by: internal/config/config.go, internal/managed/profile.go, internal/cli/root.go
DEFENSECLAW_GATEWAY_BIN
Impact: low
Default: (the gateway of this install, then PATH)
Values: any-absolute-path
Managed host: allow
Override path to the defenseclaw-gateway binary, for CI and packagers.
Read by: cli/defenseclaw/gateway.py
DEFENSECLAW_HOME
Default: ~/.defenseclaw
Values: any-absolute-path
Managed host: allow
Override the canonical data dir (default ~/.defenseclaw).
Read by: internal/config/defaults.go, cli/defenseclaw/config.py, cli/defenseclaw/connector_paths.py, scripts/install.sh, internal/gateway/connector/hooks/inspect-tool.sh
DEFENSECLAW_HOOK_GUARDIAN_AUTH_DIR
Impact: HIGH
Default: ${DEFENSECLAW_HOME}-hook-guardian
Values: any-absolute-admin-owned-path, unset
Managed host: allow
Select the administrator-owned directory containing the hook guardian protected-target authorization ledger.
Security: Privileged repair authorization — must remain root/admin-owned and non-writable by the DefenseClaw service account.
Read by: internal/managed/managed.go, internal/cli/enterprise_hooks.go, internal/gateway/sidecar.go
DEFENSECLAW_INSTALL_DIR
Impact: low
Default: $HOME/.local/bin
Values: any-absolute-path
Managed host: allow
Directory where CLI symlinks are placed by install.sh / setup-llm.sh.
Read by: scripts/setup-llm.sh
DEFENSECLAW_INSTALL_ROOT
Impact: medium
Default: unset (no 1.0 installer sets it)
Values: any-absolute-path, unset
Managed host: allow
Internal.
Security: Inherited value, so untrusted: the CLI acts on it only when its own interpreter is the embedded runtime under that root.
Read by: cmd/defenseclaw-launcher/main.go
DEFENSECLAW_IPC_SOCKET
Impact: low
Default: unset (managed_enterprise: Windows Secure Client uses <TrustedProgramFiles>\Cisco\Cisco Secure Client\DefenseClaw\ipc\defenseclaw_ipc.sock and Windows standalone uses <TrustedProgramFiles>\Cisco\DefenseClaw\ipc\defenseclaw_ipc.sock; Linux/macOS use <dirname(data_dir)>/ipc/defenseclaw_ipc.sock. Other modes use <data_dir>/ipc/defenseclaw_ipc.sock)
Values: any-absolute-path, unset
Managed host: allow
Override the local UDS gRPC socket path used by the internal/ipc server in unmanaged and test deployments.
Security: Local-only socket path override — managed_enterprise ignores the environment override, creates the resolved socket with a 0660 ceiling (0600 otherwise), and authenticates peers against the effective code-signing team, signing, and bundle-ID allowlists. Managed Windows also fixes the parent to the trusted Program Files DefenseClaw IPC directory.
Read by: internal/ipc/paths.go, internal/ipc/paths_windows.go
DEFENSECLAW_LIFECYCLE_UNIT
Impact: low
Default: unset (an administrator or MDM run quiesces every DefenseClaw unit)
Values: defenseclaw-enterprise-apply.service, com.cisco.defenseclaw.apply, unset
Managed host: allow
Set by the standalone config-apply unit (systemd) or launchd job to its own name, so the lifecycle it runs never stops or restarts the unit executing the transaction.
Security: Only exempts the config-apply entry point from being stopped; any other value is ignored. The units that set it are root-owned.
Read by: internal/enterpriseunix/env.go
DEFENSECLAW_OBSERVABILITY_BIN
Impact: low
Default: defenseclaw-observability (resolved via PATH)
Values: executable name or absolute path, unset
Managed host: allow
Override the executable used by the backward-compatible POSIX local-observability bridge.
Security: Executable selection — a non-default value changes which local program the compatibility bridge launches.
Read by: bundles/local_observability_stack/bin/openclaw-observability-bridge
DEFENSECLAW_OVERLAY_ROOT
Impact: low
Default: unset
Values: any-absolute-path, unset
Managed host: allow
Extra provider-catalog overlay dir merged on top of the built-in catalog.
Read by: cli/defenseclaw/commands/cmd_setup_provider.py
DEFENSECLAW_PLIST_SRC
Impact: low
Default: unset (installer picks plist alongside install.sh)
Values: any-absolute-path-to-plist, unset
Managed host: allow
Override the LaunchDaemon plist source file the macOS installer copies to /Library/LaunchDaemons.
Security: Installer-only override — treated as untrusted operator input, so the referenced plist must be root-owned and never group/world-writable. The bundled default plist next to install.sh is accepted regardless of extraction owner (content originates from the trusted bundle) but group/world-writable is still refused.
Read by: packaging/macos/install.sh
DEFENSECLAW_SCRUB_BIN
Impact: low
Default: unset (auto-discover in order: /opt/cisco/secureclient/defenseclaw/bin/defenseclaw-gateway, then a defenseclaw or defenseclaw-gateway executable next to uninstall.sh)
Values: any-absolute-path-to-executable, unset
Managed host: allow
Override the DefenseClaw gateway binary used by the macOS uninstaller for the per-user agent-config scrub step (the gateway's enterprise hooks scrub command).
Security: Uninstaller-only executable override — uninstall.sh runs under sudo, so the referenced binary is exec'd as root. _scrub_bin() validates every override before use via the shared _scrub_bin_trusted helper: must be an absolute path, must be a regular file (not a symlink or directory), must be executable, must be root-owned, must not be group/other writable. Any check failing prints a WARN and falls through to auto-discovery. Intended for bundle-fixture and dev-tree tests; production installs should never set this. First shipped in the macOS 26.7.3 Cisco Secure Client bundle (DefenseClaw 0.8.5).
Read by: packaging/macos/uninstall.sh
DEFENSECLAW_SENSOR_HELPER_SOCKET
Impact: low
Default: unset (managed_enterprise: Windows Secure Client uses <TrustedProgramFiles>\Cisco\Cisco Secure Client\DefenseClaw\ipc\sensor-helper.sock and Windows standalone uses <TrustedProgramFiles>\Cisco\DefenseClaw\ipc\sensor-helper.sock; Linux uses /run/defenseclaw-sensor/sensor-helper.sock; macOS standalone uses /var/run/defenseclaw-sensor/sensor-helper.sock; macOS Secure Client keeps /var/run/defenseclaw/sensor-helper.sock. Other modes use <data_dir>/ipc/sensor-helper.sock)
Values: any-absolute-path, unset
Managed host: allow
Override the local UDS path the AI Discovery sensor helper listens on outside managed deployments.
Security: Local-only socket path override, ignored under managed_enterprise. The helper creates the socket at mode 0660 owned by the gateway's group and re-checks the kernel-supplied peer uid at accept on Linux and macOS; Windows anchors the path to the trusted Program Files IPC directory and gates access with the socket DACL. The protocol is closed: a client can ask for the process table, the connection table, the event stream or DNS and cannot describe any of them, so a compromised gateway gains no reach it did not already have.
Read by: internal/sensor/acquire/paths.go, internal/gateway/ai_runtime_helper_socket.go
DEFENSECLAW_SIDECAR_URL
Impact: low
Default: http://127.0.0.1:18790
Values: any-http-url
Managed host: allow
Target URL for the bundled CodeGuard skill (skills/codeguard/main.py) to call into the sidecar.
Read by: skills/codeguard/main.py
DEFENSECLAW_UNIX_SERVICE_ACCOUNT
Impact: HIGH
Default: unset (falls back to "defenseclaw")
Values: <local unix username>, unset
Managed host: allow
Override the unix service-account username the managed runtime trust check accepts as a legitimate leaf-owner alongside root.
Security: Unix managed-runtime writer identity — a misconfigured value silently drops trust for the real service account. Change only in coordinated custom-packaging setups; never expose to per-user shells.
Read by: internal/managed/managed.go, internal/managed/trust_unix.go
DEFENSECLAW_VENV
Impact: medium
Default: ${DEFENSECLAW_HOME}/.venv (or the managed package runtime)
Values: any-absolute-path
Managed host: allow
Absolute Python runtime path selected by the macOS app and passed to its upgrade and gateway actions so each action stays on the selected installation.
Read by: macos/DefenseClawMac/DefenseClawMac/DataLayer/InstallationContext.swift, macos/DefenseClawMac/GatewayAdminHelper/main.swift
DEFENSECLAW_WINDOWS_ENTERPRISE_INSTALLER
Impact: HIGH
Default: unset (resolve the trusted installer adjacent to the native binary)
Values: absolute path to a trusted install-enterprise.ps1, unset
Managed host: allow
Select the signed Windows enterprise PowerShell installer used by the native lifecycle CLI when --installer is omitted.
Security: Privileged code-selection boundary — the resolved installer and adjacent module must pass the native trust checks before elevation.
Read by: internal/cli/windows_enterprise_service.go
DEFENSECLAW_WINDOWS_GATEWAY_SERVICE_NAME
Impact: HIGH
Default: DefenseClawGateway
Values: installer-owned Windows gateway service name
Managed host: allow
Identify the exact enterprise gateway SCM service used for service-SID ACLs and managed hook peer verification.
Security: Service-identity boundary — changing this value changes which virtual service SID is authorized to read managed runtime secrets.
Read by: internal/cli/windows_codex_requirements.go, internal/cli/enterprise_hooks_token_windows.go
DEFENSECLAW_WINDOWS_SERVICE_ACCOUNT
Impact: HIGH
Default: NT SERVICE\${DEFENSECLAW_WINDOWS_GATEWAY_SERVICE_NAME}
Values: NT SERVICE\<installer-owned-service-name>
Managed host: allow
Identify the gateway service SID (as its NT SERVICE account name) permitted to write the managed runtime tree.
Security: Managed-runtime writer identity — only the installer-pinned gateway service SID may receive the corresponding write grants.
Read by: internal/managed/managed.go, internal/managed/trust_windows.go, internal/gateway/connector/hook_api_token_windows.go
DEFENSECLAW_WINDOWS_SERVICE_LOG
Impact: medium
Default: unset (retain the inherited service output handles)
Values: absolute administrator-approved log path, unset
Managed host: allow
Select the absolute append-only log path used when the native binary is hosted by the Windows SCM.
Security: Service output path — the enterprise installer pins this in protected SCM configuration and hardens its parent directory.
Read by: cmd/defenseclaw/service_windows.go, cmd/defenseclaw-sensor-helper/log_windows.go
DEFENSECLAW_WINDOWS_SERVICE_NAME
Impact: HIGH
Default: unset (run as an ordinary CLI process)
Values: installer-owned Windows service name, unset
Managed host: allow
Select the SCM service role hosted by the signed native defenseclaw binary.
Security: Installer-owned service switch — production values belong in the protected per-service registry Environment value, not an interactive user environment.
Read by: cmd/defenseclaw/service_windows.go

Telemetry (OTel)

VariableWhat it does
DEFENSECLAW_OTEL_ENABLED
Default: unset (ignored by the v8 runtime)
Values: true, false, 1, 0, unset
Managed host: ignore
Upgrade-only v7 migration input for the former otel.enabled master toggle.
Fix: Enable or disable named observability.destinations entries in config v8.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_ENDPOINT
Default: unset
Values: any-otlp-endpoint, unset
Managed host: ignore
Upgrade-only v7 migration input for the former flat OTLP exporter endpoint.
Fix: Configure observability.destinations[].endpoint in config v8.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_LOGS_ENDPOINT
Default: unset
Values: any-otlp-endpoint, unset
Managed host: ignore
Upgrade-only v7 migration input for the former log-specific OTLP endpoint.
Fix: Configure a v8 destination endpoint or signal_overrides.logs.endpoint.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_LOGS_PROTOCOL
Default: unset
Values: grpc, grpc/protobuf, http, http/protobuf, http/json, unset
Managed host: ignore
Upgrade-only v7 migration input for the former log-specific OTLP protocol.
Fix: Configure the protocol on the canonical v8 destination.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_METRICS_ENDPOINT
Default: unset
Values: any-otlp-endpoint, unset
Managed host: ignore
Upgrade-only v7 migration input for the former metric-specific OTLP endpoint.
Fix: Configure a v8 destination endpoint or signal_overrides.metrics.endpoint.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_METRICS_PROTOCOL
Default: unset
Values: grpc, grpc/protobuf, http, http/protobuf, http/json, unset
Managed host: ignore
Upgrade-only v7 migration input for the former metric-specific OTLP protocol.
Fix: Configure the protocol on the canonical v8 destination.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_PROTOCOL
Default: unset
Values: grpc, grpc/protobuf, http, http/protobuf, http/json, unset
Managed host: ignore
Upgrade-only v7 migration input for the former flat OTLP exporter protocol.
Fix: Configure observability.destinations[].protocol in config v8.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_TRACES_ENDPOINT
Default: unset
Values: any-otlp-endpoint, unset
Managed host: ignore
Upgrade-only v7 migration input for the former trace-specific OTLP endpoint.
Fix: Configure a v8 destination endpoint or signal_overrides.traces.endpoint.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_OTEL_TRACES_PROTOCOL
Default: unset
Values: grpc, grpc/protobuf, http, http/protobuf, http/json, unset
Managed host: ignore
Upgrade-only v7 migration input for the former trace-specific OTLP protocol.
Fix: Configure the protocol on the canonical v8 destination.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_RUN_ID
Default: auto-generated UUID at gateway boot
Values: any-string, unset
Managed host: allow
Correlation ID stamped on every event for cross-sink joins.
Read by: internal/gatewaylog/runid.go, internal/audit/store.go, internal/gateway/sidecar.go, cli/defenseclaw/logger.py, cli/defenseclaw/db.py, scripts/test-e2e-full-stack.sh
DEFENSECLAW_TELEMETRY_ENABLED
Default: unset
Values: 1, 0, unset
Managed host: ignore
Local-observability-stack-only toggle.
Read by: bundles/local_observability_stack/docker-compose.yml
DEFENSECLAW_TRACEPARENT
Default: unset (no traceparent forwarded)
Values: W3C traceparent string, unset
Managed host: allow
W3C traceparent header value propagated from the agent/hook environment into outbound hook HTTP requests and the Codex telemetry bridge, enabling distributed-trace correlation.
Read by: internal/cli/hook.go, internal/gateway/connector/hooks/_hardening.sh, internal/gateway/connector/codex.go
DEFENSECLAW_TRACESTATE
Default: unset (no tracestate forwarded)
Values: W3C tracestate string, unset
Managed host: allow
W3C tracestate header value propagated alongside traceparent for vendor-specific trace baggage on hook and Codex telemetry outbound requests.
Read by: internal/cli/hook.go, internal/gateway/connector/hooks/_hardening.sh, internal/gateway/connector/codex.go

Debug / verbose logging

VariableWhat it does
DEFENSECLAW_DEBUG
Impact: low
Default: unset
Values: 1, unset
Managed host: ignore
Gateway client logs every request/response frame to stderr.
Read by: internal/gateway/client.go, extensions/defenseclaw/src/log.ts
DEFENSECLAW_JUDGE_TRACE
Impact: medium
Default: unset
Values: 1, true, unset
Managed host: ignore
Secure Client integration only: log every LLM judge prompt + response; on every other install use guardrail.judge.trace in config.yaml, which this variable does not affect.
Read by: internal/gateway/llm_judge.go
DEFENSECLAW_LLM_DEBUG
Impact: medium
Default: unset
Values: 1, true, unset
Managed host: ignore
Python LLM bridge logs per-request prompt + response bodies.
Read by: cli/defenseclaw/llm.py
DEFENSECLAW_LOG_TIMESTAMPS
Default: unset (lines are stamped)
Values: 0, unset
Managed host: ignore
Set to 0 to turn off the RFC 3339 UTC time stamps the gateway and the background watchdog put on each line of their log files.
Read by: internal/daemon/logstamp.go
DEFENSECLAW_NO_UPDATE_CHECK
Default: unset
Values: 1, unset
Managed host: ignore
Turns off the once-a-day 'new release available' notice in the CLI and TUI; the config.yaml equivalent is update.check: false.
Read by: cli/defenseclaw/update_notice.py
DEFENSECLAW_SIDECAR_DIAG
Impact: low
Default: unset
Values: 1, true, unset
Managed host: ignore
Extra sidecar boot-time diagnostics (config dump, env presence).
Read by: internal/cli/sidecar.go
DEFENSECLAW_TUI_SKIP_FIRST_RUN_PROMPT
Default: unset (prompt shown on a TTY)
Values: 1, true, yes, unset
Managed host: ignore
Skip the interactive first-run setup wizard prompt when launching the TUI, proceeding directly without asking whether to run setup.
Read by: cli/defenseclaw/tui/__init__.py
DEFENSECLAW_WEBHOOK_DEBUG
Impact: medium
Default: unset
Values: 1, unset
Managed host: ignore
Webhook dispatcher dumps full request bodies (including secrets) to stderr.
Read by: internal/gateway/webhook.go

Discovery & probes

VariableWhat it does
DEFENSECLAW_ANTHROPIC_PROBE_MODEL
Default: claude-3-5-haiku-latest
Values: any-anthropic-model-id
Managed host: ignore
Override the model used by 'defenseclaw doctor' to probe Anthropic API key validity.
Read by: cli/defenseclaw/commands/cmd_doctor.py
DEFENSECLAW_SENSOR_TETRAGON_BURN_IN
Impact: medium
Default: unset (168h)
Values: 0, whole hours from 24h to 2160h, unset
Managed host: allow
Covered agent time each enrolled user needs, with no would-block hit, before the managed Linux sensor helper lets DefenseClaw's kernel controls deny for that user's agents.
Security: Read from the root-owned drop-in only, so only root or the lifecycle can set it. A malformed value falls back to the default 168h, never to a shorter burn-in. 0 skips the burn-in and enterprise status warns kernel_burn_in_skipped for as long as enforcement runs.
Read by: internal/enterpriseunix/render.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_SENSOR_TETRAGON_CUSTOMER_EVENTS
Impact: medium
Default: unset (agent)
Values: agent, off, unset
Managed host: allow
What the managed Linux sensor helper does with the kprobe and LSM events of the customer's own Tetragon policies (enterprise.tetragon.customer_events): agent forwards those that fall under an AI agent's process lineage, attributed to the agent, the user and the hook decision; off only counts them.
Security: Read from the root-owned drop-in only. It decides only whether typed, redacted records of the customer's own policy events leave the helper; counts and the policy summary stay either way, and no setting lets the helper load, configure or delete a customer policy.
Read by: internal/enterpriseunix/tetragon_cli.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_SENSOR_TETRAGON_ENFORCE_ACK
Impact: medium
Default: unset (no approval: enforce runs in monitor mode)
Values: comma-separated list of 1 to 4 digests, each sha256: and 12 lowercase hex digits, empty, unset
Managed host: allow
The kernel_policy digests the administrator approved (enterprise.tetragon.enforce_ack), as a comma-separated list: one digest, or up to 4 while a ring upgrade runs two builds.
Security: Read from the root-owned drop-in only. It approves control-set digests, never a scope: a build with a changed control set reports a new digest and every user drops to monitor mode (kernel_enforce_ack_stale) until the list includes it.
Read by: internal/enterpriseunix/render.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_SENSOR_TETRAGON_ENFORCE_CONNECTORS
Impact: medium
Default: unset (no connector can be anchored for a deny)
Values: comma-separated connector names, empty, unset
Managed host: allow
Comma-separated enrolled connectors whose effective guardrail mode is action.
Security: Read from the root-owned drop-in only. It can only narrow the enforcing scope: anchors still come from enrolled connectors in the guardian manifest resolved to their real install files.
Read by: internal/enterpriseunix/render.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_SENSOR_TETRAGON_MACHINE_POLICY_CONNECTORS
Impact: medium
Default: unset (only targets.yaml rows are enrolled)
Values: comma-separated connector names, empty, unset
Managed host: allow
Comma-separated enrolled command-line connectors whose DefenseClaw hooks reach every eligible account through vendor machine policy (Claude Code, Codex, Cursor, Copilot CLI and OpenCode on Linux) and that have no per-user rows in targets.yaml because enterprise.enrollment.unenrolled_users is not deny.
Security: Read from the root-owned drop-in only, and the accounts come only from the enumerator's root-owned eligible-accounts record, checked like targets.yaml. A row only anchors an installed command-line agent below that account, and a targets.yaml row for the same user and connector, enabled or not, always wins.
Read by: internal/enterpriseunix/tetragon_cli.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_SENSOR_TETRAGON_MODE
Impact: medium
Default: unset (consume)
Values: off, consume, observe, enforce, unset
Managed host: allow
How the managed Linux sensor helper uses the host's Tetragon (enterprise.tetragon.mode, with the Plane C cap applied): off (cn_proc and fanotify only), consume (read Tetragon's process events), observe (also load DefenseClaw's kernel controls in monitor mode) or enforce (let them deny once enforce_ack matches).
Security: Read from the root-owned drop-in only; the helper never reads config.yaml, so a root process with kernel-policy power acts only on what ensure accepted. A malformed value falls back to consume (read only).
Read by: internal/enterpriseunix/render.go, internal/sensor/kernelpolicy/types.go
DEFENSECLAW_TRUSTED_BIN_PREFIXES
Impact: medium
Default: unset (built-in defaults only)
Values: os.pathsep-separated absolute paths (':' POSIX, ';' Windows), unset
Managed host: ignore
Extra trusted binary prefixes for AI Discovery's binary probing, separated by os.pathsep (':' on POSIX, ';' on Windows).
Security: Tight binary-discovery trust list — prevents PATH-shadow elevation where a malicious binary in a user-writable dir gets probed and treated as a real agent runtime. 'trusted-paths add' refuses world-writable and non-absolute directories unless --force.
Read by: cli/defenseclaw/inventory/agent_discovery.py, cli/defenseclaw/commands/cmd_setup.py, cmd/defenseclaw-sensor-helper/tetragon_linux.go

Hook-internal (do not override)

VariableWhat it does
DEFENSECLAW_AGENT_HOME
Default: (set by hooks)
Values: absolute-path
Managed host: allow
The account's real HOME, saved unexported by the Unix hook hardening before it swaps in the per-hook HOME, so a hook can cold-start the account's stopped per-user gateway with the right HOME.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_AGENT_ID
Default: (set by plugin / hooks)
Values: any-string
Managed host: allow
Agent identity propagated through correlation headers and OTel attributes.
Read by: internal/cli/scan_v7.go, extensions/defenseclaw/src/__tests__/agent_identity.test.ts
DEFENSECLAW_AGENT_INSTANCE_ID
Default: (set by plugin / hooks)
Values: any-string
Managed host: allow
Per-instance agent identifier; used to disambiguate concurrent runs of the same agent.
Read by: internal/cli/scan_v7.go
DEFENSECLAW_AGENT_NAME
Default: (set by plugin / hooks)
Values: any-string
Managed host: allow
Human-readable agent name propagated via correlation headers.
Read by: extensions/defenseclaw/src/index.ts
DEFENSECLAW_BAKED_HOOK_PATH
Impact: medium
Default: empty (default PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin)
Values: colon-separated absolute paths, unset
Managed host: allow
Baked into the installed _hardening.sh helper at hook-generation time.
Security: Hook PATH lockdown — a mis-baked value that widens PATH could re-admit attacker-writable directories to hook execution.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_CLAWHUB_CWD
Default: unset (set by the ClawHub launcher adapter on Windows)
Values: absolute directory path
Managed host: allow
Working directory used by the temporary Windows ClawHub command adapter.
Read by: cli/defenseclaw/commands/cmd_skill.py
DEFENSECLAW_CLAWHUB_LAUNCHER
Default: unset (set by the ClawHub launcher adapter on Windows)
Values: absolute path to a .cmd or .bat launcher
Managed host: allow
Absolute path to the trusted ClawHub .cmd or .bat launcher passed to the temporary Windows command adapter.
Read by: cli/defenseclaw/commands/cmd_skill.py
DEFENSECLAW_CLIENT
Default: (set by plugin)
Values: any-string
Managed host: allow
Client name (e.g. openclaw-plugin) stamped on the X-DefenseClaw-Client correlation header.
Read by: extensions/defenseclaw/src/policy/enforcer.ts
DEFENSECLAW_CODEX_NOTIFY_CHAINED
Impact: low
Default: (unset; set only on the chained notifier's process)
Values: hex SHA-256 of the notify payload
Managed host: allow
Set by defenseclaw-hook notify (the per-user native Codex notifier and the Secure Client Windows notifier) on the notifier it chains, the one setup displaced.
Read by: internal/cli/notify.go
DEFENSECLAW_CONNECTOR
Default: unset
Values: normalized connector identifier, unset
Managed host: allow
Runtime selector for the connector that owns an invocation of the shared hook scripts.
Read by: internal/gateway/connector/hooks/_hardening.sh, internal/gateway/connector/subprocess.go
DEFENSECLAW_CONTAINED_RUN_SUPERVISOR
Default: unset
Values: 1, unset
Managed host: allow
Set to 1, together with the argv[0] defenseclaw-contained-run, only when a DefenseClaw Go binary re-runs itself on Linux as the PID-namespace runner of processutil.RunContained (the Hermes Verify execution probe) or the PID-namespace scanner launcher of processutil.RunTracked.
Read by: internal/processutil/contain_linux.go
DEFENSECLAW_DAEMON
Default: (set by daemon launcher; child only)
Values: 1
Managed host: allow
Sentinel set by the daemon launcher in the child process so it knows it's the daemon.
Read by: internal/daemon/daemon.go
DEFENSECLAW_DATA_DIR
Default: unset (set by the daemon on child processes)
Values: absolute data-directory path
Managed host: allow
Marker injected by the daemon launcher into the spawned gateway child process environment, recording which data directory that child belongs to.
Read by: internal/daemon/daemon.go
DEFENSECLAW_DELEGATED_FROM
Default: unset
Values: defenseclaw, unset
Managed host: allow
Set to 'defenseclaw' by the Python CLI when it runs a gateway command for the user ('defenseclaw audit export' and 'audit findings' run 'defenseclaw-gateway audit ...'), so the gateway's usage errors name the command the user typed.
Read by: cli/defenseclaw/commands/cmd_audit.py, internal/cli/usage_args.go
DEFENSECLAW_EGRESS_BYPASS
Default: (set by DefenseClaw in the sandbox)
Values: comma-separated host list, unset
Managed host: allow
Comma-separated hosts that bypass the DefenseClaw egress proxy inside a sandbox (the hook ingress and credentialed provider hosts, where OpenShell injects credentials).
Read by: internal/openshell/sandbox_env.go, internal/openshell/harness/harness.go
DEFENSECLAW_EGRESS_URL
Impact: low
Default: (set by DefenseClaw in the sandbox)
Values: http:// proxy URL, unset
Managed host: allow
DefenseClaw egress proxy URL (http://<per-sandbox credential>@host.openshell.internal:<egress_port>) set inside every open or balanced sandbox.
Security: Carries the sandbox's egress proxy credential. Never log or persist the value.
Read by: internal/openshell/sandbox_env.go, internal/openshell/harness/harness.go, internal/openshell/harness/shellenv.go
DEFENSECLAW_EXPLICIT_CODEX_SETUP
Default: unset
Values: absolute-path, unset
Managed host: allow
Set by the Python CLI to the absolute Codex home while a Codex setup restarts the gateway, so that gateway binds Codex to the home the user just chose instead of the root recorded in the managed backup (GAP-1106).
Read by: cli/defenseclaw/commands/cmd_setup.py, internal/gateway/connector/config_root_pin.go
DEFENSECLAW_FOREIGN_GUARD
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the administrator-owned defenseclaw-hook path baked in at render time, which the script asks for the foreign-hook decision before each Hermes pre_tool_call and at on_session_start.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GATEWAY_ADDR
Default: 127.0.0.1:<api_port>
Values: loopback host:port, unset
Managed host: allow
Gateway API address for the Windows native Go hook entrypoint.
Security: Loopback-only enforcement — a non-loopback gateway address is rejected so a hook cannot be redirected to an off-box collector.
Read by: internal/cli/hook.go
DEFENSECLAW_GUARD_AGENT_HOME
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the agent's own HOME, captured before the script hardens its environment, so the foreign-hook check reads the Hermes config the agent reads.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hooks/hermes-hook.sh
DEFENSECLAW_GUARD_BODY
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the JSON body of the block it sends to the gateway's foreign-hook session route when the check gave no decision. curl reads it on a descriptor (defenseclaw_gateway_post), never on its command line.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_CAUSE
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: why the foreign-hook check gave no decision (its exit status, no answer, or an answer DefenseClaw could not read), named in the block message.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_EVENT
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the Hermes event name read from the hook payload, which selects whether the foreign-hook check runs.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_OUTPUT
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the Hermes block object printed when the foreign-hook check denies the call.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_REASON
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the reason code of a foreign-hook denial, logged and printed on stderr.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_RESULT
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the JSON answer of defenseclaw-hook --foreign-hook-check; only an explicit allow answer (deny false) continues to the gateway.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_SESSION
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the Hermes session id read from the hook payload, sent with the block to the gateway's foreign-hook session route when the check gave no decision.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_GUARD_STATUS
Default: unset
Values: set by the script
Managed host: allow
Shell variable of the standalone Linux and macOS hermes-hook.sh: the exit status of defenseclaw-hook --foreign-hook-check, named in the block message when the check gave no decision.
Security: Assigned by the script before it is read, so a value in the agent's environment has no effect.
Read by: internal/gateway/connector/hermes_foreign_guard.go
DEFENSECLAW_HOOK_CONNECTOR
Default: (set by hooks)
Values: claudecode, codex, openclaw, zeptoclaw, inspect, ...
Managed host: allow
Internal label identifying which connector's hook is executing.
Read by: internal/gateway/connector/hooks/inspect-tool.sh
DEFENSECLAW_HOOK_CWD
Default: (set by hooks)
Values: absolute-path
Managed host: allow
Resolved CWD exported by hooks; used by sanitizeHookCWD to bound git operations.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_HOOK_HOME
Default: (set by hooks)
Values: absolute-path
Managed host: allow
Hardened HOME exported by hooks to insulate them from operator HOME.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_HOOK_MAX_BODY
Impact: low
Default: 1048576
Values: positive integer
Managed host: ignore
Request-body cap (in bytes) for per-user hooks: a value from 1 to 1048576 lowers it, anything else is ignored; a per-user hook sends at most 921600 bytes (900 KiB) of a call to its own gateway and treats a larger call as oversized input.
Read by: internal/gateway/connector/hooks/_hardening.sh, cmd/defenseclaw-hook-user/main.go, internal/cli/hook.go
DEFENSECLAW_HOOK_NAME
Default: (set by hooks)
Values: inspect-tool, inspect-request, ...
Managed host: allow
Internal label identifying which hook is executing.
Read by: internal/gateway/connector/hooks/inspect-tool.sh
DEFENSECLAW_HOOK_PATH
Default: (set by hooks)
Values: colon-separated paths
Managed host: allow
Hardened PATH exported by hooks (system-only) so a hostile workspace can't shadow git/curl/etc.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_HOOK_PATH_TRUSTED
Default: unset (always stripped before PATH lockdown)
Values: unset
Managed host: allow
Companion name to DEFENSECLAW_HOOK_PATH that an agent process might set.
Security: Hook PATH lockdown — stripped so an agent-supplied 'trusted' flag cannot re-enable an attacker-controlled PATH.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_HOOK_SOCKET
Default: (rendered by setup for standalone Unix installs that name a hook socket; absent everywhere else)
Values: absolute-path
Managed host: allow
Path of the standalone gateway's peer-authorized unix hook socket, assigned inside a rendered standalone Unix hook (connector shell hooks and the Codex notify bridge) before the socket and its directory owners are checked and the request is sent with curl --unix-socket.
Read by: internal/gateway/connector/hook_socket_transport.go
DEFENSECLAW_HOOK_SOCKET_UID
Default: (rendered by setup next to DEFENSECLAW_HOOK_SOCKET)
Values: uid
Managed host: allow
Gateway service account uid that a rendered standalone Unix hook accepts, besides root, as the owner of the hook socket and its directory.
Read by: internal/gateway/connector/hook_socket_transport.go
DEFENSECLAW_HOST_TZ
Default: (set by DefenseClaw in the sandbox)
Values: IANA zone name, unset
Managed host: allow
IANA time zone of the machine a sandbox was created from (America/New_York), set inside every OpenShell sandbox by sandbox run.
Read by: internal/openshell/timezone.go, internal/openshell/harness/shellenv.go
DEFENSECLAW_INTERNAL_HOOK_DELEGATION
Impact: HIGH
Default: unset (set and overwritten by the stable hook launcher on Windows)
Values: v2:<inherited parent handle>:<32-hex transaction id>:<64-hex hook SHA-256>, unset
Managed host: allow
Carries the parent-owned proof for a stable hook launcher to delegate to the exact full-hook generation it already admitted.
Security: Private parent-to-child hook admission proof only. The environment value has no authority without the inherited live-process handle, canonical launcher identity, protected state, and exact transaction and digest match.
Read by: internal/hookruntime/delegation_windows.go
DEFENSECLAW_MANAGED_HOOK
Impact: HIGH
Default: unset (set to 1 only by generated managed hooks)
Values: 1, unset
Managed host: allow
Immutable sentinel baked into managed-enterprise hook scripts so missing authentication material and unavailable enforcement fail closed even when an inherited environment requests permissive availability behavior.
Security: Managed enforcement fail-closed boundary — the value is generated by the privileged hook installer and is not an operator security opt-out.
Read by: internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_OPENCLAW_MAIN
Impact: low
Default: (set by plugin bootstrap)
Values: absolute-path
Managed host: allow
Sentinel read by the OpenClaw plugin bootstrapper to locate its main module.
Read by: extensions/defenseclaw/src/aws-sdk-http1-for-guardrail.ts
DEFENSECLAW_PLUGIN_AGENT_ID
Default: (set by plugin)
Values: any-string
Managed host: allow
Plugin-side agent ID.
Read by: extensions/defenseclaw/src/__tests__/agent_identity.test.ts
DEFENSECLAW_SANDBOX_CA_BASE
Default: unset (set by DefenseClaw in a trusted-CA sandbox)
Values: absolute path to OpenShell's CA bundle, unset
Managed host: allow
Records OpenShell's original CA bundle path in a sandbox process tree so a nested login shell preserves a caller-set SSL_CERT_FILE while refreshing DefenseClaw's combined sandbox CA bundle.
Read by: internal/openshell/trustedca.go, internal/openshell/harness/shellenv.go
DEFENSECLAW_SANDBOX_ID
Impact: medium
Default: (set by DefenseClaw in the sandbox)
Values: opaque DefenseClaw binding id, unset
Managed host: allow
The sandbox's DefenseClaw ingress binding id, which the sandbox manager sets inside every sandbox it launches, through the harness spec's environment.
Fix: Unset it outside a DefenseClaw sandbox.
Security: Sandbox bypass: while set, sandbox run and the shell wrappers run the harness natively on the host, as DEFENSECLAW_NO_SANDBOX does, without a notice. DefenseClaw sets it only inside the sandboxes it launches and refuses it from .env files, so a value on the host was planted or leaked.
Read by: internal/openshell/sandbox_env.go, internal/openshell/harness/harness.go, cli/defenseclaw/main.py, cli/defenseclaw/commands/cmd_doctor.py
DEFENSECLAW_SANDBOX_NAME
Default: (set by DefenseClaw in the sandbox)
Values: sandbox name, unset
Managed host: allow
Human-readable DefenseClaw sandbox name that the sandbox manager sets inside every sandbox it launches, through the harness spec's environment.
Read by: internal/openshell/sandbox_env.go, internal/openshell/harness/harness.go
DEFENSECLAW_SCANNER_AID_ENDPOINT
Impact: low
Default: unset (the default AI Defense endpoint)
Values: https URL, unset
Managed host: allow
Cisco AI Defense endpoint (cisco_ai_defense.endpoint) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan); the runtime uses the default endpoint when it is unset.
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_BASE_URL
Impact: low
Default: unset (set by the gateway for the scanner runtime)
Values: URL, unset
Managed host: allow
LLM judge base URL (llm.base_url) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan).
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_BEDROCK_AUTH_MODE
Default: unset (set by the gateway for a Bedrock judge with a bedrock block)
Values: api_key, iam_credentials, profile, instance_role, unset
Managed host: allow
Bedrock auth mode of the LLM judge (llm.bedrock.auth_mode) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan).
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_MODEL
Default: unset (set by the gateway for the scanner runtime)
Values: LiteLLM model id, unset
Managed host: allow
LiteLLM model id of the LLM judge (llm.provider and llm.model) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan).
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_PROVIDER
Default: unset (set by the gateway for the scanner runtime)
Values: provider name, unset
Managed host: allow
LLM judge provider (llm.provider) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan).
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCANNER_LLM_REGION
Default: unset (set by the gateway for the scanner runtime)
Values: cloud region, unset
Managed host: allow
LLM judge region (llm.region, or llm.bedrock.region when set) for the standalone Windows payload's scanner runtime (defenseclaw-scanners mcp-scan and plugin-scan); the gateway also sets AWS_REGION to it.
Read by: internal/scanner/scanner_runtime.go, cmd/defenseclaw-scanners/main.go
DEFENSECLAW_SCAN_RECORDED_BY_CALLER
Default: unset
Values: 1, unset
Managed host: allow
Set to 1 by the gateway when it runs a defenseclaw plugin scan child whose result it records itself, so the CLI child does not write a second scan row and scan-finding alert (GAP-2482).
Read by: internal/scanner/plugin.go, cli/defenseclaw/commands/_scan_ui.py
DEFENSECLAW_SESSION_FACTS_BIN
Default: (rendered by setup for standalone managed Unix installs; absent everywhere else)
Values: absolute-path
Managed host: allow
Administrator-owned hook binary a rendered standalone managed Unix hook runs as hook session-facts to read the user's Kerberos credential cache, which a shell cannot read.
Read by: internal/gateway/connector/hook_socket_transport.go, internal/gateway/connector/hooks/_hardening.sh
DEFENSECLAW_SIDECAR_INSTANCE_ID
Default: (auto-generated by gateway)
Values: uuid-or-similar
Managed host: allow
Sidecar instance ID; auto-generated by the gateway at boot, propagated via headers.
Read by: internal/cli/scan_v7.go
DEFENSECLAW_SSH_SHIM_PROBE
Default: unset (set only for the probe run)
Values: probe token, unset
Managed host: allow
Set by DefenseClaw only for the one probe run of the ssh shim it puts first on the OpenShell CLI's PATH: the shim prints the value and exits without running ssh, which proves a PATH search finds and executes it.
Read by: internal/openshell/sshshim.go, internal/openshell/sshshim_test.go
DEFENSECLAW_STAMP_LOG
Default: unset
Values: 1, unset
Managed host: allow
Internal marker set by DefenseClaw on a detached helper (the background watchdog) so it stamps its log lines like the gateway; cleared by the helper so its children do not inherit it.
Read by: internal/daemon/logstamp.go
DEFENSECLAW_TRACKED_HOST_STAT_FD
Default: unset
Values: 5, unset
Managed host: allow
Linux scanner custody channel descriptor, set to 5 by the trusted RunTracked launcher.
Read by: internal/processutil/contain_linux.go, internal/managed/trust_owner_linux.go, cli/defenseclaw/file_permissions.py
DEFENSECLAW_TRACKED_RUN_SUPERVISOR
Default: unset
Values: 1, unset
Managed host: allow
Set to 1, together with the argv[0] defenseclaw-tracked-run, only when a DefenseClaw Go binary re-runs itself on macOS as the process-tree supervisor of processutil.RunTracked (gateway scanner runs).
Read by: internal/processutil/track_darwin.go
DEFENSECLAW_WINDOWS_APPROVED_AGENT_CLIENTS_ENFORCED
Impact: HIGH
Default: unset (optional application-control posture is not attested)
Values: 1, unset
Managed host: allow
Carry protected installer evidence that optional application control restricts every enabled enterprise agent client to approved binaries.
Security: Authenticated service evidence — only the signed installer may publish this marker after live WDAC or AppLocker certification. Its absence does not block managed-hook installation or reconciliation.
Read by: internal/cli/windows_codex_requirements.go, packaging/windows/DefenseClawEnterprise.psm1
DEFENSECLAW_WINDOWS_CLAUDE_EFFECTIVE_POLICY_VERIFIED
Impact: HIGH
Default: unset (effective policy is unverified)
Values: 1, unset
Managed host: allow
Carry protected installer evidence that DefenseClaw is Claude Code's effective first-source-wins managed policy.
Security: Authenticated service evidence — protected local policy bytes alone do not establish which Claude managed-policy source is effective.
Read by: internal/cli/windows_codex_requirements.go, packaging/windows/DefenseClawEnterprise.psm1
DEFENSECLAW_WINDOWS_CODEX_APPROVED_CLIENT_ENFORCED
Impact: HIGH
Default: unset
Values: 1, unset
Managed host: allow
Retain the protected Codex-specific compatibility alias for the all-agent application-control attestation.
Security: Compatibility-only service claim — it is not a substitute for DEFENSECLAW_WINDOWS_APPROVED_AGENT_CLIENTS_ENFORCED or live application-control certification.
Read by: packaging/windows/DefenseClawEnterprise.psm1
DEFENSECLAW_WINDOWS_UNINSTALL_PURGE_USER_STATE
Impact: medium
Default: unset (the finalize only names each per-user folder)
Values: 1, unset
Managed host: allow
Tell the standalone Windows managed-hook teardown finalize that the uninstall purges, so it also removes each enrolled account's per-user DefenseClaw folder.
Security: Lifecycle-owned helper switch: the lifecycle sets or clears it for every helper it runs, so a caller's inherited value never reaches the finalize.
Read by: internal/cli/windows_managed_hooks_teardown.go, packaging/windows/DefenseClawEnterprise.psm1

Upgrade-internal (do not override)

VariableWhat it does
DEFENSECLAW_ANTIGRAVITY_CONFIG_HOME
Impact: medium
Default: unset
Values: absolute normalized path from a 0.8.x Setup install state, unset
Managed host: ignore
Internal.
Security: DefenseClaw-only binding. This is not a Antigravity vendor environment variable and must never be used for ordinary Antigravity discovery.
Read by: internal/nativeinstallstate/state.go, internal/nativeinstallstate/state_test.go
DEFENSECLAW_CURSOR_CONFIG_HOME
Impact: medium
Default: unset
Values: absolute normalized path from a 0.8.x Setup install state, unset
Managed host: ignore
Internal.
Security: DefenseClaw-only binding. This is not a Cursor vendor environment variable and must never be used for ordinary Cursor discovery.
Read by: cli/defenseclaw/commands/cmd_setup.py, internal/nativeinstallstate/state.go, internal/nativeinstallstate/state_test.go
DEFENSECLAW_DEVIN_CONFIG_HOME
Impact: medium
Default: unset
Values: absolute normalized path, unset
Managed host: allow
Pins the Devin configuration directory that DefenseClaw discovery and the gateway's Devin connector setup use.
Security: DefenseClaw-only binding. This is not a Devin vendor environment variable; a malformed value fails the lifecycle instead of falling back to a platform default.
Read by: internal/config/claw.go, internal/gateway/sidecar.go, internal/nativeinstallstate/state.go
DEFENSECLAW_DEVIN_EXECUTABLE
Impact: HIGH
Default: unset
Values: absolute normalized Devin executable path from a 0.8.x Setup install state, unset
Managed host: ignore
Internal.
Security: DefenseClaw-only binding, never a general operator path override.
Read by: internal/nativeinstallstate/state.go
DEFENSECLAW_INSTALL_CALLER
Default: unset
Values: app, unset
Managed host: ignore
Set to app by the macOS app so install.sh does not quit or relaunch the running app itself.
Read by: scripts/install.sh
DEFENSECLAW_PERSIST_JUDGE
Impact: medium
Default: unset
Values: 1, true, unset
Managed host: ignore
Read only by the 0.x observability migration, which folds it into config.yaml; nothing reads it at runtime.
Read by: cli/defenseclaw/observability/v8_migration.py
DEFENSECLAW_REPO
Impact: medium
Default: cisco-ai-defense/defenseclaw
Values: owner/name, https mirror base URL
Managed host: ignore
Deprecated alias of update.source in config.yaml: the GitHub owner/name (or https mirror base URL) whose releases defenseclaw upgrade and the installers use, for testing on a fork.
Read by: cli/defenseclaw/upgrade_shim.py, scripts/install.sh, scripts/defenseclaw-upgrade.sh
DEFENSECLAW_STANDALONE_COLLECT_RUNTIME_GENERATIONS
Impact: low
Default: unset
Values: 1, unset
Managed host: ignore
Asks the standalone Windows installer's Verify, run by an elevated ensure that found the deployment compliant, to collect the old managed hook runtime copies a retire left and to name each per-user DefenseClaw folder still untrusted.
Read by: internal/cli/windows_enterprise_standalone.go, packaging/windows/install-enterprise.ps1
DEFENSECLAW_STANDALONE_FORCED_UNINSTALL
Impact: HIGH
Default: unset
Values: 1, unset
Managed host: ignore
Carries Setup /uninstall FORCE=1 (enterprise windows uninstall --force) from the native lifecycle CLI to the standalone Windows installer, which removes the deployment without reading its pending transaction.
Security: Skips recovery of a pending transaction, so it is honoured only in the environment the signed, elevated lifecycle CLI builds for the installer and cleared before any child starts.
Read by: internal/cli/windows_enterprise_standalone.go, packaging/windows/install-enterprise.ps1
DEFENSECLAW_UPGRADE_FRESH_PROCESS
Default: unset
Values: 1, unset
Managed host: ignore
Set by 0.8.x upgrade controllers on the processes they start.
Read by: scripts/defenseclaw-upgrade.sh

Splunk-bridge bundle

VariableWhat it does
DEFENSECLAW_HEC_TOKEN
Impact: HIGH
Default: (set in .env.example)
Values: hec-token
Managed host: ignore
Splunk-bridge HEC token.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_HEC_URL
Default: (set in .env.example)
Values: any-hec-url
Managed host: ignore
Splunk-bridge bundle: HEC endpoint URL.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_INDEX
Default: defenseclaw_local
Values: splunk-index-name
Managed host: ignore
Splunk-bridge target index.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_INTEGRATION_ENABLED
Default: false
Values: true, false
Managed host: ignore
Splunk-bridge integration toggle.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_O11Y_DASHBOARD_NAME_PREFIX
Default: empty (no prefix)
Values: string, unset
Managed host: ignore
Prefix label applied to the Splunk Observability dashboard groups, dashboards, and detectors created by the Terraform setup command.
Read by: cli/defenseclaw/commands/cmd_setup_splunk_o11y_dashboards.py
DEFENSECLAW_REF
Default: unknown
Values: any-string
Managed host: ignore
Splunk-bridge bundle git ref label.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_SOURCE
Default: defenseclaw
Values: any-source-string
Managed host: ignore
Splunk-bridge source label.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_SOURCETYPE
Default: defenseclaw:json
Values: splunk-sourcetype
Managed host: ignore
Splunk-bridge sourcetype.
Read by: bundles/splunk_local_bridge/env/.env.example
DEFENSECLAW_SPLUNK_O11Y_DASHBOARDS_WORK_DIR
Default: <data_dir>/splunk_o11y_dashboards/terraform
Values: absolute directory path, unset
Managed host: ignore
Terraform working directory for Splunk Observability dashboard provisioning.
Read by: cli/defenseclaw/commands/cmd_setup_splunk_o11y_dashboards.py
DEFENSECLAW_TERRAFORM_PLUGIN_DIR
Default: unset (no -plugin-dir passed to terraform init)
Values: absolute directory path, unset
Managed host: ignore
Optional Terraform provider plugin directory for offline / cached provider installs when running 'defenseclaw setup splunk-o11y-dashboards'.
Read by: cli/defenseclaw/commands/cmd_setup_splunk_o11y_dashboards.py

Fleet management (Edge Connector)

VariableWhat it does
DCLAW_AUDIT_KEY
Impact: HIGH
Default: unset
Values: 64-hex-chars
Managed host: allow
Nonzero 32-byte hex HMAC key for signed local audit records.
Read by: edge-connector/src/persist/audit_ring.c
DCLAW_BROKER_URL
Impact: medium
Default: unset
Values: mqtt://host:port, mqtts://host:port
Managed host: allow
Device MQTT broker URL; use mqtts:// and a trusted CA in production.
Read by: edge-connector/src/persist/config_store.c
DCLAW_CA_CERT_PATH
Impact: HIGH
Default: unset
Values: path
Managed host: allow
Path to a PEM CA certificate used to verify the MQTT broker in production.
Read by: edge-connector/src/comms/tls_engine.c
DCLAW_CRL_PATH
Impact: medium
Default: unset
Values: path
Managed host: allow
Optional certificate revocation list for edge MQTT TLS peer validation; an explicit unreadable or invalid CRL aborts TLS initialization.
Read by: edge-connector/src/comms/tls_engine.c
DCLAW_DEVICE_CERT_PATH
Impact: medium
Default: unset
Values: path
Managed host: allow
Path to the edge device client TLS certificate.
Read by: edge-connector/src/comms/tls_engine.c
DCLAW_DEVICE_ID
Impact: low
Default: unset
Values: uint64
Managed host: allow
Numeric edge device identifier assigned by Fleet registration.
Read by: edge-connector/src/main.c
DCLAW_DEVICE_KEY
Impact: HIGH
Default: unset
Values: string
Managed host: allow
Fleet-wide device HMAC key (hex-encoded, 32 bytes).
Read by: internal/fleet/mqtt/bridge.go, edge-connector/src/comms/verdict_protocol.c
DCLAW_DEVICE_KEY_PATH
Impact: HIGH
Default: unset
Values: path
Managed host: allow
Path to the edge device client TLS private key.
Read by: edge-connector/src/comms/tls_engine.c
DCLAW_DEV_MODE
Impact: HIGH
Default: unset
Values: ON, unset
Managed host: ignore
On unmanaged hosts only, ON explicitly enables legacy development Fleet MQTT behavior; unset defaults to production checks.
Read by: internal/fleet/mqtt/bridge.go
DCLAW_EMERGENCY_KEY
Impact: HIGH
Default: unset
Values: string
Managed host: allow
Separate nonzero 32-byte hex HMAC key required for emergency commands and lockdown release; no OTA-key fallback.
Read by: internal/fleet/policy/signer.go, edge-connector/src/comms/ota_receiver.c
DCLAW_FLASH_PATH
Impact: medium
Default: unset
Values: path
Managed host: allow
Override path to edge device emulated flash storage.
Read by: edge-connector/src/platform/hal_linux.c
DCLAW_FLEET_API_TOKEN
Impact: HIGH
Default: unset
Values: string
Managed host: allow
Opaque bearer token for the Fleet management API; the CLI generator uses URL-safe random text.
Read by: internal/fleet/api.go
DCLAW_FLEET_API_URL
Impact: low
Default: unset
Values: URL
Managed host: allow
Fleet API URL used by the remote device installer and Fleet CLI.
Read by: cli/defenseclaw/commands/cmd_edge_install.py, cli/defenseclaw/commands/cmd_edge_connector_cli.py
DCLAW_FLEET_AUTO_REGISTER
Impact: medium
Default: unset
Values: string
Managed host: allow
Allow devices to self-register via MQTT heartbeat.
Read by: internal/gateway/sidecar.go
DCLAW_FLEET_ID
Impact: low
Default: unset
Values: uint32
Managed host: allow
Numeric Fleet identifier assigned to the edge device.
Read by: edge-connector/src/main.c
DCLAW_FLEET_TENANT_TOKENS
Impact: HIGH
Default: unset
Values: string
Managed host: allow
Comma-separated tenant-scoped tokens (token:tid,... format).
Read by: internal/fleet/api.go
DCLAW_IPC_ALLOWED_GID
Impact: HIGH
Default: unset
Values: integer
Managed host: allow
Allowed local group ID for the edge IPC socket.
Read by: edge-connector/src/main.c, edge-connector/src/platform/hal_linux.c
DCLAW_IPC_ALLOWED_UID
Impact: HIGH
Default: unset
Values: integer
Managed host: allow
Allowed local user ID for the edge IPC socket.
Read by: edge-connector/src/main.c, edge-connector/src/platform/hal_linux.c
DCLAW_IPC_SOCKET_PATH
Impact: medium
Default: unset
Values: path
Managed host: allow
Path of the edge connector Unix IPC socket.
Read by: edge-connector/src/main.c
DCLAW_MQTT_BROKER_URL
Impact: medium
Default: unset
Values: string
Managed host: allow
MQTT broker address for fleet bridge (host:port).
Read by: internal/gateway/sidecar.go
DCLAW_MQTT_PASS
Impact: HIGH
Default: unset
Values: string
Managed host: allow
MQTT broker password.
Read by: internal/fleet/mqtt/paho_client.go
DCLAW_MQTT_USER
Impact: HIGH
Default: unset
Values: string
Managed host: allow
MQTT broker username.
Read by: internal/fleet/mqtt/paho_client.go
DCLAW_OTA_HMAC_KEY
Impact: HIGH
Default: unset
Values: 64-hex-chars
Managed host: allow
Explicit nonzero 32-byte hex shared secret for OTA policy HMAC; C production also requires DCLAW_ALLOW_HMAC_OTA=ON at build time.
Read by: internal/fleet/policy/signer.go, edge-connector/src/comms/ota_receiver.c
DCLAW_PRODUCTION
Impact: HIGH
Default: unset
Values: 1, true, unset
Managed host: allow
Force production Fleet MQTT security checks when set to 1 or true; production checks are already the default.
Read by: internal/fleet/mqtt/bridge.go
DCLAW_REQUIRE_TLS
Impact: medium
Default: unset
Values: 1, unset
Managed host: allow
Require TLS for the Go Fleet MQTT client.
Read by: internal/fleet/mqtt/paho_client.go
DCLAW_STRICT_MODE
Impact: medium
Default: unset
Values: 0, 1
Managed host: allow
Require strict edge connector behavior on policy and verdict failures.
Read by: edge-connector/src/dclaw_core.c
DCLAW_TENANT_ID
Impact: low
Default: unset
Values: uint16
Managed host: allow
Numeric Fleet tenant identifier assigned to the edge device.
Read by: edge-connector/src/main.c
DCLAW_TLS_CA_CERT
Impact: medium
Default: unset
Values: path
Managed host: allow
CA certificate path for the active Go Fleet MQTT TLS client.
Read by: internal/fleet/mqtt/tls_config.go
DCLAW_TLS_CLIENT_CERT
Impact: medium
Default: unset
Values: path
Managed host: allow
Client certificate path for the active Go Fleet MQTT TLS client.
Read by: internal/fleet/mqtt/tls_config.go
DCLAW_TLS_CLIENT_KEY
Impact: HIGH
Default: unset
Values: path
Managed host: allow
Client private-key path for the active Go Fleet MQTT TLS client.
Read by: internal/fleet/mqtt/tls_config.go
DCLAW_TLS_INSECURE
Impact: HIGH
Default: unset
Values: 1, unset
Managed host: allow
Development-only switch to allow TLS without a trusted CA; rejected by production C builds.
Read by: edge-connector/src/comms/tls_engine.c
DCLAW_TLS_SKIP_VERIFY
Impact: HIGH
Default: unset
Values: 1, unset
Managed host: ignore
Skip Go Fleet MQTT broker certificate verification only in explicit unmanaged development mode; production and managed hosts enforce verification.
Read by: internal/fleet/mqtt/tls_config.go

Test fixtures (test-only)

These variables exist for DefenseClaw's own test suites. Do not set them on a real install.

Managed enterprise deployments

On an enterprise deployment, the lifecycle writes each service's environment itself. Do not set these variables in a user's shell or in the services by hand.

VariableRole on a managed host
DEFENSECLAW_DEPLOYMENT_MODESet to managed_enterprise by the managed service definitions, so a replaced config cannot turn managed mode off
DEFENSECLAW_ENTERPRISE_PROFILEPins the profile (secure_client or standalone). The standalone service definitions set it to standalone. It must agree with enterprise.profile in the config. Unset, the profile comes from the config, then the per-OS default: secure_client on Windows and macOS, standalone on Linux
DEFENSECLAW_CONFIGPoints the services at the administrator-owned config, for example /etc/defenseclaw/config.yaml on Linux
DEFENSECLAW_HOOK_GUARDIAN_AUTH_DIRThe guardian's authorization ledger directory: /var/lib/defenseclaw-hook-guardian on Linux, /opt/cisco/defenseclaw/hook-guardian-state on macOS
DEFENSECLAW_UNIX_SERVICE_ACCOUNTThe macOS service definitions, and the gateway commands the macOS lifecycle runs, set it to _defenseclaw. Linux uses the default, defenseclaw. Set it yourself only for custom packaging that runs the gateway under another account; a wrong value makes the runtime trust check reject the real service account
DEFENSECLAW_INSTALL_MANAGED_DESCRIPTORTest-only. Points install.sh at a temporary runtime descriptor. The per-user gateway still refuses to start on a managed host

On standalone managed Linux and macOS, run the installed enterprise policy commands as root without setting DEFENSECLAW_CONFIG. The commands use the trusted runtime descriptor to pin the installed config, data directory and deployment mode together instead of reading root's per-user config:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json

The first command is for Linux; the second is for macOS. On managed Windows with the standalone profile, use an elevated PowerShell prompt to run enterprise policy show --json without setting DEFENSECLAW_CONFIG:

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

The Windows CLI pins the installed config, data directory and service identity together. On every OS, setting only DEFENSECLAW_CONFIG skips automatic pinning and can make the command read the caller's runtime directory. See Machine policy status.

When in doubt

On a per-user install, run defenseclaw doctor to inspect the CLI process environment and defenseclaw keys list to check credential sources.

defenseclaw doctor
defenseclaw keys list

On managed Linux and macOS, the user's defenseclaw launcher offers only the commands in Managed command availability; it refuses doctor and keys list. An administrator runs the packaged binary as root:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json

These status commands report deployment health. To check ignored overrides, compare the administrator-owned service environment's variable names with this catalog's ignore and tighten_only rows. On managed Windows, run & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --json from an elevated PowerShell prompt; its doctor command only prints administrator guidance. For Fleet and Edge services, inspect their supervisor's environment and resolved config.yaml.

See also Keys, Redaction, and Fail modes for DEFENSECLAW_FAIL_MODE and DEFENSECLAW_STRICT_AVAILABILITY.