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 host | What a managed standalone host does with the value |
|---|---|
allow | Uses it. This includes runtime paths, credentials, hook-script values, and Fleet service variables. Restrict access to service environments containing Fleet secrets or TLS overrides. |
ignore | Treats 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_only | Uses 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. |
-
.envfollows the same rule. The gateway and the CLI load<data_dir>/.envat 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 marksignoreis skipped. Some names are refused from.envon 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, everyDEFENSECLAW_ALLOW_*switch, andDEFENSECLAW_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_MODEandDEFENSECLAW_ENTERPRISE_PROFILEare set by the managed service definitions, never by a user. A host is managed when either itsconfig.yamlor the service environment saysmanaged_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 (aconfig.yamlin your home folder that does not itself saymanaged_enterprise), aDEFENSECLAW_DEPLOYMENT_MODEorDEFENSECLAW_ENTERPRISE_PROFILEexported in a shell is dropped when the command starts. The writers keep writing as usual, anddefenseclaw doctorlists the variable underIgnored environment overrides. It does not enrol the device or apply an administrator's policy. -
Settings have a config key where one exists.
DEFENSECLAW_REPOis the deprecated alias ofupdate.source,DEFENSECLAW_NO_UPDATE_CHECKhasupdate.check: false, andguardrail.judge.tracereplacesDEFENSECLAW_JUDGE_TRACE(which is read only on the Secure Client integration).DEFENSECLAW_CUSTOM_PROVIDERS_PATHnames the derivedcustom-providers.json, not an input. See Source of truth.
Security opt-outs
| Variable | What it does |
|---|---|
DEFENSECLAW_ALLOW_CGNATImpact: HIGH Default: unset (CGNAT blocked)Values: 1, unsetManaged 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_DRIFTImpact: HIGH Default: unset (fail-closed)Values: 1, unsetManaged 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_TARGETSImpact: HIGH Default: unset (SSRF guard enforced)Values: 1, unsetManaged 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_UPSTREAMSImpact: HIGH Default: unset (all private IPs blocked)Values: comma-separated IPs (e.g. 10.50.2.100,172.16.0.5), unsetManaged 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_TRUSTImpact: HIGH Default: unset (fail-closed)Values: 1, unsetManaged 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_DEVImpact: low Default: unsetValues: 1, true, unsetManaged host: ignore | Mark the process as a developer build. Read by: internal/redaction/credentials.go |
DEFENSECLAW_DISABLE_AWS_HTTP1_SHIMImpact: medium Default: unset (shim active for Bedrock)Values: 1, unsetManaged 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_REDACTIONImpact: HIGH Default: unset (ignored by the v8 runtime)Values: 1, true, unsetManaged 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_SECRETSImpact: HIGH Default: unsetValues: 1, unsetManaged host: ignore | E2E test toggle ONLY. Read by: scripts/test-e2e-full-stack.sh |
DEFENSECLAW_FAIL_MODEImpact: medium Default: (value from guardrail.hook_fail_mode in config.yaml) Values: open, closed, unsetManaged 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_SHIMImpact: low Default: unset (shim only on Bedrock)Values: 1, unsetManaged 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_AUTOSTARTImpact: low Default: unset (hooks start a stopped per-user gateway)Values: 0, false, no, offManaged 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_DISABLEImpact: low Default: unset (ignored by the v8 runtime)Values: 1, true, unsetManaged 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_ANCESTORSImpact: 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, unsetManaged 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_SANDBOXImpact: medium Default: unsetValues: 1, unsetManaged 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_INSECUREImpact: HIGH Default: unsetValues: true, false, 1, 0, unsetManaged 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_OPAImpact: medium Default: unset (validation needs opa or defenseclaw-gateway)Values: 1, unsetManaged 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_PIIImpact: medium Default: unset (PII redacted everywhere)Values: 1, true, unsetManaged host: ignore | Reveal PII in operator-facing logs only (CLI stdout, TUI). Read by: internal/redaction/redaction.go |
DEFENSECLAW_STRICT_AVAILABILITYDefault: unset (no additional force-closed override)Values: 1, true, TRUE, yes, YES, unsetManaged 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_TESTImpact: low Default: unsetValues: 1, true, unsetManaged host: ignore | Mark the process as running under tests. Read by: internal/redaction/credentials.go |
DEFENSECLAW_TOOL_INSPECT_FAIL_OPENImpact: HIGH Default: ignored by 1.0.9 Values: 1, true, unsetManaged host: ignore | Legacy OpenClaw tool-inspection outage override through 1.0.8. Read by: extensions/defenseclaw/src/__tests__/index.test.ts |
DEFENSECLAW_TRUSTED_PROXY_CIDRSImpact: medium Default: unset (X-Forwarded-For ignored)Values: comma-separated CIDRs or IPs, unsetManaged 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_RESPONSESImpact: HIGH Default: unset (guardrail proxy enforced)Values: 1, unsetManaged 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_UNVERIFIEDDefault: unset (no effect)Values: 1, unsetManaged 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_LOCALHOSTImpact: medium Default: unset (SSRF guard blocks private IPs)Values: 1, unsetManaged 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_ACCOUNTSImpact: medium Default: unset (signed-out accounts are restored through an S4U logon)Values: 0, unsetManaged 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
| Variable | What it does |
|---|---|
DEFENSECLAW_CMID_BROKER_AUTH_KEYImpact: HIGH Default: unset (legacy in-process provider path)Values: absolute installer-owned broker-auth.key path, unsetManaged 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_KEYImpact: medium Default: unsetValues: bearer token string, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: bearer-token, unsetManaged 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_KEYImpact: HIGH Default: unsetValues: secret-value, unsetManaged host: allow | Secret transport for 'defenseclaw init' (--cisco-api-key). Read by: cli/defenseclaw/commands/cmd_init.py |
DEFENSECLAW_INIT_LLM_API_KEYImpact: HIGH Default: unsetValues: secret-value, unsetManaged host: allow | Secret transport for 'defenseclaw init' (--llm-api-key). Read by: cli/defenseclaw/commands/cmd_init.py |
DEFENSECLAW_LLM_KEYImpact: HIGH Default: unsetValues: LLM API key string, unsetManaged host: allow | Canonical env-var name for the unified LLM key. Read by: cli/defenseclaw/credentials.py |
DEFENSECLAW_LLM_KEY_ENVImpact: low Default: DEFENSECLAW_LLM_KEY Values: any env-var nameManaged host: allow | Indirection: name of the env var to read the LLM key from. Read by: cli/defenseclaw/credentials.py |
DEFENSECLAW_LLM_MODELImpact: low Default: (value from llm.model in config.yaml) Values: provider/model-id, unsetManaged host: allow | Override the configured LLM model id at runtime. Read by: cli/tests/test_config.py |
DEFENSECLAW_LLM_MODEL_ENVImpact: low Default: DEFENSECLAW_LLM_MODEL Values: any env-var nameManaged host: allow | Indirection: name of the env var to read the LLM model from. Read by: cli/defenseclaw/credentials.py |
DEFENSECLAW_LOCAL_PASSWORDImpact: HIGH Default: unsetValues: any-string, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: cryptographically random HEC token, unsetManaged 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_USERNAMEImpact: medium Default: unsetValues: any-string, unsetManaged host: allow | Username for the local Splunk daemon basic-auth surface. Read by: bundles/splunk_local_bridge/bin/splunk-claw-bridge |
DEFENSECLAW_PD_KEYImpact: medium Default: unsetValues: pagerduty-key, unsetManaged host: allow | Alias for DEFENSECLAW_PD_ROUTING_KEY. Read by: cli/defenseclaw/commands/cmd_setup_webhook.py |
DEFENSECLAW_PD_ROUTING_KEYImpact: medium Default: unsetValues: pagerduty-routing-key, unsetManaged host: allow | PagerDuty routing key default for webhook entries. Read by: cli/defenseclaw/commands/cmd_setup_webhook.py |
DEFENSECLAW_REGISTRY_TOKENImpact: medium Default: unsetValues: registry-token, unsetManaged host: allow | Default registry auth env var (e.g. SkillsHub). Read by: cli/defenseclaw/commands/cmd_registry.py |
DEFENSECLAW_SANDBOX_TOKENImpact: HIGH Default: (set by DefenseClaw in the sandbox) Values: OpenShell credential placeholder, binding token (token_delivery: env), unsetManaged 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_KEYImpact: HIGH Default: unset (set by the gateway for the scanner runtime)Values: secret-value, unsetManaged 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_KEYImpact: HIGH Default: unset (set by the gateway for the scanner runtime)Values: secret-value, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: secret-value, unsetManaged 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_KEYImpact: HIGH Default: unsetValues: secret-value, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: provider-token, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: secret-value, unsetManaged 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_TOKENImpact: HIGH Default: unsetValues: secret-value, unsetManaged 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_SECRETImpact: medium Default: unsetValues: any-string, unsetManaged host: allow | SIEM webhook secret default. Read by: cli/defenseclaw/commands/cmd_setup_webhook.py |
DEFENSECLAW_SKILLSSH_TOKENImpact: medium Default: unsetValues: registry-token, unsetManaged host: allow | Example registry-specific token env var. Read by: cli/defenseclaw/commands/cmd_registry.py |
DEFENSECLAW_SKILL_SCANNER_LLM_KEYImpact: HIGH Default: unsetValues: LLM API key string, unsetManaged host: allow | Override the LLM key used by the skill scanner only. Read by: cli/defenseclaw/credentials.py |
DEFENSECLAW_SPLUNK_HEC_TOKENImpact: HIGH Default: unsetValues: HEC token, unsetManaged host: allow | Credential reference of remote Splunk HEC destinations written before 1.0.4. Read by: cli/defenseclaw/observability/presets.py |
DEFENSECLAW_WEBEX_TOKENImpact: medium Default: unsetValues: webex-bot-token, unsetManaged host: allow | Webex bot token default for webhook entries. Read by: cli/defenseclaw/commands/cmd_setup_webhook.py |
DEFENSECLAW_WEBHOOK_SECRETImpact: medium Default: unsetValues: any-string, unsetManaged host: allow | Generic webhook HMAC secret default. Read by: cli/defenseclaw/commands/cmd_setup_webhook.py |
Paths & runtime layout
| Variable | What it does |
|---|---|
DEFENSECLAW_API_ADDRImpact: low Default: (templated value from gateway.api_port at hook install time) Values: host:port, unsetManaged host: allow | Sidecar API address that hooks dial. Read by: internal/gateway/connector/hooks/inspect-tool.sh |
DEFENSECLAW_APP_PATHDefault: /Applications/DefenseClawMac.app when present Values: any-absolute-path, noneManaged 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_PATHDefault: unset (set only by DefenseClawAssembler.exe)Values: <absolute path to Authenticode-signed payload file>, unsetManaged 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_BINImpact: low Default: (discovered via PATH lookup) Values: any-absolute-pathManaged host: allow | Override path to the defenseclaw CLI binary. Read by: internal/scanner/plugin_test.go, scripts/setup-llm.sh |
DEFENSECLAW_BUILDIDDefault: unsetValues: defenseclaw-enterprise-setup-<40-char-lowercase-sha>, unsetManaged 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_PIPEImpact: HIGH Default: unset (legacy in-process provider path)Values: \\.\pipe\DefenseClawCMIDBroker, installer-owned certification pipe, unsetManaged 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_NAMEImpact: HIGH Default: unset (legacy in-process provider path)Values: DefenseClawCMIDBroker, installer-owned certification broker service, unsetManaged 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_CONFIGImpact: medium Default: ${DEFENSECLAW_HOME}/config.yamlValues: any-absolute-path, unsetManaged 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_PATHImpact: low Default: unsetValues: any-absolute-path, unsetManaged 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_MODEImpact: HIGH Default: unset (use config.yaml deployment_mode)Values: managed_enterprise, unmanaged_byod, unsetManaged 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_PROFILEImpact: HIGH Default: unset (use config.yaml enterprise.profile; then secure_client on Windows/macOS, standalone on Linux)Values: secure_client, standalone, unsetManaged 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_BINImpact: low Default: (the gateway of this install, then PATH) Values: any-absolute-pathManaged host: allow | Override path to the defenseclaw-gateway binary, for CI and packagers. Read by: cli/defenseclaw/gateway.py |
DEFENSECLAW_HOMEDefault: ~/.defenseclaw Values: any-absolute-pathManaged 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_DIRImpact: HIGH Default: ${DEFENSECLAW_HOME}-hook-guardianValues: any-absolute-admin-owned-path, unsetManaged 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_DIRImpact: low Default: $HOME/.local/binValues: any-absolute-pathManaged host: allow | Directory where CLI symlinks are placed by install.sh / setup-llm.sh. Read by: scripts/setup-llm.sh |
DEFENSECLAW_INSTALL_ROOTImpact: medium Default: unset (no 1.0 installer sets it)Values: any-absolute-path, unsetManaged 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_SOCKETImpact: 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, unsetManaged 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_UNITImpact: low Default: unset (an administrator or MDM run quiesces every DefenseClaw unit)Values: defenseclaw-enterprise-apply.service, com.cisco.defenseclaw.apply, unsetManaged 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_BINImpact: low Default: defenseclaw-observability (resolved via PATH) Values: executable name or absolute path, unsetManaged 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_ROOTImpact: low Default: unsetValues: any-absolute-path, unsetManaged 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_SRCImpact: low Default: unset (installer picks plist alongside install.sh)Values: any-absolute-path-to-plist, unsetManaged 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_BINImpact: 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, unsetManaged 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_SOCKETImpact: 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, unsetManaged 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_URLImpact: low Default: http://127.0.0.1:18790Values: any-http-urlManaged 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_ACCOUNTImpact: HIGH Default: unset (falls back to "defenseclaw")Values: <local unix username>, unsetManaged 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_VENVImpact: medium Default: ${DEFENSECLAW_HOME}/.venv (or the managed package runtime)Values: any-absolute-pathManaged 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_INSTALLERImpact: HIGH Default: unset (resolve the trusted installer adjacent to the native binary)Values: absolute path to a trusted install-enterprise.ps1, unsetManaged 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_NAMEImpact: HIGH Default: DefenseClawGateway Values: installer-owned Windows gateway service nameManaged 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_ACCOUNTImpact: 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_LOGImpact: medium Default: unset (retain the inherited service output handles)Values: absolute administrator-approved log path, unsetManaged 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_NAMEImpact: HIGH Default: unset (run as an ordinary CLI process)Values: installer-owned Windows service name, unsetManaged 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)
| Variable | What it does |
|---|---|
DEFENSECLAW_OTEL_ENABLEDDefault: unset (ignored by the v8 runtime)Values: true, false, 1, 0, unsetManaged 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_ENDPOINTDefault: unsetValues: any-otlp-endpoint, unsetManaged 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_ENDPOINTDefault: unsetValues: any-otlp-endpoint, unsetManaged 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_PROTOCOLDefault: unsetValues: grpc, grpc/protobuf, http, http/protobuf, http/json, unsetManaged 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_ENDPOINTDefault: unsetValues: any-otlp-endpoint, unsetManaged 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_PROTOCOLDefault: unsetValues: grpc, grpc/protobuf, http, http/protobuf, http/json, unsetManaged 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_PROTOCOLDefault: unsetValues: grpc, grpc/protobuf, http, http/protobuf, http/json, unsetManaged 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_ENDPOINTDefault: unsetValues: any-otlp-endpoint, unsetManaged 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_PROTOCOLDefault: unsetValues: grpc, grpc/protobuf, http, http/protobuf, http/json, unsetManaged 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_IDDefault: auto-generated UUID at gateway boot Values: any-string, unsetManaged 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_ENABLEDDefault: unsetValues: 1, 0, unsetManaged host: ignore | Local-observability-stack-only toggle. Read by: bundles/local_observability_stack/docker-compose.yml |
DEFENSECLAW_TRACEPARENTDefault: unset (no traceparent forwarded)Values: W3C traceparent string, unsetManaged 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_TRACESTATEDefault: unset (no tracestate forwarded)Values: W3C tracestate string, unsetManaged 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
| Variable | What it does |
|---|---|
DEFENSECLAW_DEBUGImpact: low Default: unsetValues: 1, unsetManaged host: ignore | Gateway client logs every request/response frame to stderr. Read by: internal/gateway/client.go, extensions/defenseclaw/src/log.ts |
DEFENSECLAW_JUDGE_TRACEImpact: medium Default: unsetValues: 1, true, unsetManaged 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_DEBUGImpact: medium Default: unsetValues: 1, true, unsetManaged host: ignore | Python LLM bridge logs per-request prompt + response bodies. Read by: cli/defenseclaw/llm.py |
DEFENSECLAW_LOG_TIMESTAMPSDefault: unset (lines are stamped)Values: 0, unsetManaged 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_CHECKDefault: unsetValues: 1, unsetManaged 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_DIAGImpact: low Default: unsetValues: 1, true, unsetManaged host: ignore | Extra sidecar boot-time diagnostics (config dump, env presence). Read by: internal/cli/sidecar.go |
DEFENSECLAW_TUI_SKIP_FIRST_RUN_PROMPTDefault: unset (prompt shown on a TTY)Values: 1, true, yes, unsetManaged 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_DEBUGImpact: medium Default: unsetValues: 1, unsetManaged host: ignore | Webhook dispatcher dumps full request bodies (including secrets) to stderr. Read by: internal/gateway/webhook.go |
Discovery & probes
| Variable | What it does |
|---|---|
DEFENSECLAW_ANTHROPIC_PROBE_MODELDefault: claude-3-5-haiku-latest Values: any-anthropic-model-idManaged 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_INImpact: medium Default: unset (168h)Values: 0, whole hours from 24h to 2160h, unsetManaged 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_EVENTSImpact: medium Default: unset (agent)Values: agent, off, unsetManaged 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_ACKImpact: 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, unsetManaged 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_CONNECTORSImpact: medium Default: unset (no connector can be anchored for a deny)Values: comma-separated connector names, empty, unsetManaged 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_CONNECTORSImpact: medium Default: unset (only targets.yaml rows are enrolled)Values: comma-separated connector names, empty, unsetManaged 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_MODEImpact: medium Default: unset (consume)Values: off, consume, observe, enforce, unsetManaged 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_PREFIXESImpact: medium Default: unset (built-in defaults only)Values: os.pathsep-separated absolute paths (':' POSIX, ';' Windows), unsetManaged 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)
| Variable | What it does |
|---|---|
DEFENSECLAW_AGENT_HOMEDefault: (set by hooks) Values: absolute-pathManaged 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_IDDefault: (set by plugin / hooks) Values: any-stringManaged 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_IDDefault: (set by plugin / hooks) Values: any-stringManaged host: allow | Per-instance agent identifier; used to disambiguate concurrent runs of the same agent. Read by: internal/cli/scan_v7.go |
DEFENSECLAW_AGENT_NAMEDefault: (set by plugin / hooks) Values: any-stringManaged host: allow | Human-readable agent name propagated via correlation headers. Read by: extensions/defenseclaw/src/index.ts |
DEFENSECLAW_BAKED_HOOK_PATHImpact: medium Default: empty (default PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) Values: colon-separated absolute paths, unsetManaged 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_CWDDefault: unset (set by the ClawHub launcher adapter on Windows)Values: absolute directory pathManaged host: allow | Working directory used by the temporary Windows ClawHub command adapter. Read by: cli/defenseclaw/commands/cmd_skill.py |
DEFENSECLAW_CLAWHUB_LAUNCHERDefault: unset (set by the ClawHub launcher adapter on Windows)Values: absolute path to a .cmd or .bat launcherManaged 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_CLIENTDefault: (set by plugin) Values: any-stringManaged 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_CHAINEDImpact: low Default: (unset; set only on the chained notifier's process) Values: hex SHA-256 of the notify payloadManaged 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_CONNECTORDefault: unsetValues: normalized connector identifier, unsetManaged 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_SUPERVISORDefault: unsetValues: 1, unsetManaged 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_DAEMONDefault: (set by daemon launcher; child only) Values: 1Managed 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_DIRDefault: unset (set by the daemon on child processes)Values: absolute data-directory pathManaged 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_FROMDefault: unsetValues: defenseclaw, unsetManaged 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_BYPASSDefault: (set by DefenseClaw in the sandbox) Values: comma-separated host list, unsetManaged 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_URLImpact: low Default: (set by DefenseClaw in the sandbox) Values: http:// proxy URL, unsetManaged 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_SETUPDefault: unsetValues: absolute-path, unsetManaged 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_GUARDDefault: unsetValues: set by the scriptManaged 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_ADDRDefault: 127.0.0.1:<api_port>Values: loopback host:port, unsetManaged 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_HOMEDefault: unsetValues: set by the scriptManaged 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_BODYDefault: unsetValues: set by the scriptManaged 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_CAUSEDefault: unsetValues: set by the scriptManaged 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_EVENTDefault: unsetValues: set by the scriptManaged 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_OUTPUTDefault: unsetValues: set by the scriptManaged 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_REASONDefault: unsetValues: set by the scriptManaged 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_RESULTDefault: unsetValues: set by the scriptManaged 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_SESSIONDefault: unsetValues: set by the scriptManaged 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_STATUSDefault: unsetValues: set by the scriptManaged 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_CONNECTORDefault: (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_CWDDefault: (set by hooks) Values: absolute-pathManaged host: allow | Resolved CWD exported by hooks; used by sanitizeHookCWD to bound git operations. Read by: internal/gateway/connector/hooks/_hardening.sh |
DEFENSECLAW_HOOK_HOMEDefault: (set by hooks) Values: absolute-pathManaged host: allow | Hardened HOME exported by hooks to insulate them from operator HOME. Read by: internal/gateway/connector/hooks/_hardening.sh |
DEFENSECLAW_HOOK_MAX_BODYImpact: low Default: 1048576 Values: positive integerManaged 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_NAMEDefault: (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_PATHDefault: (set by hooks) Values: colon-separated pathsManaged 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_TRUSTEDDefault: unset (always stripped before PATH lockdown)Values: unsetManaged 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_SOCKETDefault: (rendered by setup for standalone Unix installs that name a hook socket; absent everywhere else) Values: absolute-pathManaged 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_UIDDefault: (rendered by setup next to DEFENSECLAW_HOOK_SOCKET) Values: uidManaged 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_TZDefault: (set by DefenseClaw in the sandbox) Values: IANA zone name, unsetManaged 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_DELEGATIONImpact: 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>, unsetManaged 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_HOOKImpact: HIGH Default: unset (set to 1 only by generated managed hooks)Values: 1, unsetManaged 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_MAINImpact: low Default: (set by plugin bootstrap) Values: absolute-pathManaged 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_IDDefault: (set by plugin) Values: any-stringManaged host: allow | Plugin-side agent ID. Read by: extensions/defenseclaw/src/__tests__/agent_identity.test.ts |
DEFENSECLAW_SANDBOX_CA_BASEDefault: unset (set by DefenseClaw in a trusted-CA sandbox)Values: absolute path to OpenShell's CA bundle, unsetManaged 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_IDImpact: medium Default: (set by DefenseClaw in the sandbox) Values: opaque DefenseClaw binding id, unsetManaged 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_NAMEDefault: (set by DefenseClaw in the sandbox) Values: sandbox name, unsetManaged 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_ENDPOINTImpact: low Default: unset (the default AI Defense endpoint)Values: https URL, unsetManaged 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_URLImpact: low Default: unset (set by the gateway for the scanner runtime)Values: URL, unsetManaged 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_MODEDefault: unset (set by the gateway for a Bedrock judge with a bedrock block)Values: api_key, iam_credentials, profile, instance_role, unsetManaged 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_MODELDefault: unset (set by the gateway for the scanner runtime)Values: LiteLLM model id, unsetManaged 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_PROVIDERDefault: unset (set by the gateway for the scanner runtime)Values: provider name, unsetManaged 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_REGIONDefault: unset (set by the gateway for the scanner runtime)Values: cloud region, unsetManaged 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_CALLERDefault: unsetValues: 1, unsetManaged 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_BINDefault: (rendered by setup for standalone managed Unix installs; absent everywhere else) Values: absolute-pathManaged 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_IDDefault: (auto-generated by gateway) Values: uuid-or-similarManaged 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_PROBEDefault: unset (set only for the probe run)Values: probe token, unsetManaged 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_LOGDefault: unsetValues: 1, unsetManaged 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_FDDefault: unsetValues: 5, unsetManaged 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_SUPERVISORDefault: unsetValues: 1, unsetManaged 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_ENFORCEDImpact: HIGH Default: unset (optional application-control posture is not attested)Values: 1, unsetManaged 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_VERIFIEDImpact: HIGH Default: unset (effective policy is unverified)Values: 1, unsetManaged 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_ENFORCEDImpact: HIGH Default: unsetValues: 1, unsetManaged 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_STATEImpact: medium Default: unset (the finalize only names each per-user folder)Values: 1, unsetManaged 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)
| Variable | What it does |
|---|---|
DEFENSECLAW_ANTIGRAVITY_CONFIG_HOMEImpact: medium Default: unsetValues: absolute normalized path from a 0.8.x Setup install state, unsetManaged 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_HOMEImpact: medium Default: unsetValues: absolute normalized path from a 0.8.x Setup install state, unsetManaged 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_HOMEImpact: medium Default: unsetValues: absolute normalized path, unsetManaged 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_EXECUTABLEImpact: HIGH Default: unsetValues: absolute normalized Devin executable path from a 0.8.x Setup install state, unsetManaged host: ignore | Internal. Security: DefenseClaw-only binding, never a general operator path override. Read by: internal/nativeinstallstate/state.go |
DEFENSECLAW_INSTALL_CALLERDefault: unsetValues: app, unsetManaged 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_JUDGEImpact: medium Default: unsetValues: 1, true, unsetManaged 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_REPOImpact: medium Default: cisco-ai-defense/defenseclaw Values: owner/name, https mirror base URLManaged 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_GENERATIONSImpact: low Default: unsetValues: 1, unsetManaged 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_UNINSTALLImpact: HIGH Default: unsetValues: 1, unsetManaged 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_PROCESSDefault: unsetValues: 1, unsetManaged host: ignore | Set by 0.8.x upgrade controllers on the processes they start. Read by: scripts/defenseclaw-upgrade.sh |
Splunk-bridge bundle
| Variable | What it does |
|---|---|
DEFENSECLAW_HEC_TOKENImpact: HIGH Default: (set in .env.example) Values: hec-tokenManaged host: ignore | Splunk-bridge HEC token. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_HEC_URLDefault: (set in .env.example) Values: any-hec-urlManaged host: ignore | Splunk-bridge bundle: HEC endpoint URL. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_INDEXDefault: defenseclaw_local Values: splunk-index-nameManaged host: ignore | Splunk-bridge target index. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_INTEGRATION_ENABLEDDefault: false Values: true, falseManaged host: ignore | Splunk-bridge integration toggle. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_O11Y_DASHBOARD_NAME_PREFIXDefault: empty (no prefix) Values: string, unsetManaged 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_REFDefault: unknown Values: any-stringManaged host: ignore | Splunk-bridge bundle git ref label. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_SOURCEDefault: defenseclaw Values: any-source-stringManaged host: ignore | Splunk-bridge source label. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_SOURCETYPEDefault: defenseclaw:json Values: splunk-sourcetypeManaged host: ignore | Splunk-bridge sourcetype. Read by: bundles/splunk_local_bridge/env/.env.example |
DEFENSECLAW_SPLUNK_O11Y_DASHBOARDS_WORK_DIRDefault: <data_dir>/splunk_o11y_dashboards/terraformValues: absolute directory path, unsetManaged host: ignore | Terraform working directory for Splunk Observability dashboard provisioning. Read by: cli/defenseclaw/commands/cmd_setup_splunk_o11y_dashboards.py |
DEFENSECLAW_TERRAFORM_PLUGIN_DIRDefault: unset (no -plugin-dir passed to terraform init)Values: absolute directory path, unsetManaged 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)
| Variable | What it does |
|---|---|
DCLAW_AUDIT_KEYImpact: HIGH Default: unsetValues: 64-hex-charsManaged host: allow | Nonzero 32-byte hex HMAC key for signed local audit records. Read by: edge-connector/src/persist/audit_ring.c |
DCLAW_BROKER_URLImpact: medium Default: unsetValues: mqtt://host:port, mqtts://host:portManaged 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_PATHImpact: HIGH Default: unsetValues: pathManaged 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_PATHImpact: medium Default: unsetValues: pathManaged 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_PATHImpact: medium Default: unsetValues: pathManaged host: allow | Path to the edge device client TLS certificate. Read by: edge-connector/src/comms/tls_engine.c |
DCLAW_DEVICE_IDImpact: low Default: unsetValues: uint64Managed host: allow | Numeric edge device identifier assigned by Fleet registration. Read by: edge-connector/src/main.c |
DCLAW_DEVICE_KEYImpact: HIGH Default: unsetValues: stringManaged 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_PATHImpact: HIGH Default: unsetValues: pathManaged host: allow | Path to the edge device client TLS private key. Read by: edge-connector/src/comms/tls_engine.c |
DCLAW_DEV_MODEImpact: HIGH Default: unsetValues: ON, unsetManaged 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_KEYImpact: HIGH Default: unsetValues: stringManaged 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_PATHImpact: medium Default: unsetValues: pathManaged host: allow | Override path to edge device emulated flash storage. Read by: edge-connector/src/platform/hal_linux.c |
DCLAW_FLEET_API_TOKENImpact: HIGH Default: unsetValues: stringManaged 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_URLImpact: low Default: unsetValues: URLManaged 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_REGISTERImpact: medium Default: unsetValues: stringManaged host: allow | Allow devices to self-register via MQTT heartbeat. Read by: internal/gateway/sidecar.go |
DCLAW_FLEET_IDImpact: low Default: unsetValues: uint32Managed host: allow | Numeric Fleet identifier assigned to the edge device. Read by: edge-connector/src/main.c |
DCLAW_FLEET_TENANT_TOKENSImpact: HIGH Default: unsetValues: stringManaged host: allow | Comma-separated tenant-scoped tokens (token:tid,... format). Read by: internal/fleet/api.go |
DCLAW_IPC_ALLOWED_GIDImpact: HIGH Default: unsetValues: integerManaged 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_UIDImpact: HIGH Default: unsetValues: integerManaged 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_PATHImpact: medium Default: unsetValues: pathManaged host: allow | Path of the edge connector Unix IPC socket. Read by: edge-connector/src/main.c |
DCLAW_MQTT_BROKER_URLImpact: medium Default: unsetValues: stringManaged host: allow | MQTT broker address for fleet bridge (host:port). Read by: internal/gateway/sidecar.go |
DCLAW_MQTT_PASSImpact: HIGH Default: unsetValues: stringManaged host: allow | MQTT broker password. Read by: internal/fleet/mqtt/paho_client.go |
DCLAW_MQTT_USERImpact: HIGH Default: unsetValues: stringManaged host: allow | MQTT broker username. Read by: internal/fleet/mqtt/paho_client.go |
DCLAW_OTA_HMAC_KEYImpact: HIGH Default: unsetValues: 64-hex-charsManaged 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_PRODUCTIONImpact: HIGH Default: unsetValues: 1, true, unsetManaged 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_TLSImpact: medium Default: unsetValues: 1, unsetManaged host: allow | Require TLS for the Go Fleet MQTT client. Read by: internal/fleet/mqtt/paho_client.go |
DCLAW_STRICT_MODEImpact: medium Default: unsetValues: 0, 1Managed host: allow | Require strict edge connector behavior on policy and verdict failures. Read by: edge-connector/src/dclaw_core.c |
DCLAW_TENANT_IDImpact: low Default: unsetValues: uint16Managed host: allow | Numeric Fleet tenant identifier assigned to the edge device. Read by: edge-connector/src/main.c |
DCLAW_TLS_CA_CERTImpact: medium Default: unsetValues: pathManaged host: allow | CA certificate path for the active Go Fleet MQTT TLS client. Read by: internal/fleet/mqtt/tls_config.go |
DCLAW_TLS_CLIENT_CERTImpact: medium Default: unsetValues: pathManaged host: allow | Client certificate path for the active Go Fleet MQTT TLS client. Read by: internal/fleet/mqtt/tls_config.go |
DCLAW_TLS_CLIENT_KEYImpact: HIGH Default: unsetValues: pathManaged host: allow | Client private-key path for the active Go Fleet MQTT TLS client. Read by: internal/fleet/mqtt/tls_config.go |
DCLAW_TLS_INSECUREImpact: HIGH Default: unsetValues: 1, unsetManaged 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_VERIFYImpact: HIGH Default: unsetValues: 1, unsetManaged 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.
| Variable | Role on a managed host |
|---|---|
DEFENSECLAW_DEPLOYMENT_MODE | Set to managed_enterprise by the managed service definitions, so a replaced config cannot turn managed mode off |
DEFENSECLAW_ENTERPRISE_PROFILE | Pins 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_CONFIG | Points the services at the administrator-owned config, for example /etc/defenseclaw/config.yaml on Linux |
DEFENSECLAW_HOOK_GUARDIAN_AUTH_DIR | The guardian's authorization ledger directory: /var/lib/defenseclaw-hook-guardian on Linux, /opt/cisco/defenseclaw/hook-guardian-state on macOS |
DEFENSECLAW_UNIX_SERVICE_ACCOUNT | The 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_DESCRIPTOR | Test-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 --jsonThe 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 --jsonThe 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 listOn 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 --jsonThese 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.
Migrate config.yaml from v8 to v9
What the config_version 8 to 9 migration moves into config.yaml, which commands run it, before and after examples for every moved key, how conflicts are recorded in migration-v9.json, and how to go back to DefenseClaw 0.8.x.
Keys
The defenseclaw keys registry, credential resolution order, dynamically discovered credential references, and separately managed gateway tokens.