vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-04 20:00:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 33
openclaw/docs/cli/security.md
Peter Steinberger 2fffd4e8ba
feat(sessions): enable cross-agent session access by default (#136755) 
* feat(sessions): enable cross-agent session access by default

`tools.sessions.visibility` now defaults to `all` and
`tools.agentToAgent.enabled` to `true`; both widen access.
Narrow access via `tools.sessions.visibility` (agent|tree|self),
`tools.agentToAgent.allow`, or `enabled: false`.

Document that an omitted/empty allow list permits every agent pair.
Denial copy for narrowed visibility no longer instructs enabling the
already-on policy. Regenerate prompt-snapshot fixtures for the visibility
hedge. Maintainer-directed.

* feat(security): audit default cross-agent session access

Add `security.trust_model.cross_agent_session_access_default`: `info`
for plain multi-agent defaults, `warn` with sandbox/tool-restriction/
multi-user ingress signals. No new config keys.

* test(gateway): drain detached a2a flow between agentId send rows

The announce/ping-pong flow outlives the sessions_send tool request; the second agentId row picked up the first row's follow-up agent call for agent:orion:main, so each row now waits for gateway active work to drain before releasing its test state.

* test(security): mock the cross-agent access collector in the non-deep facade

The readonly-setup-fallback test mocks audit.nondeep.runtime with an explicit factory; it now exports collectCrossAgentSessionAccessFindings so the registered collector resolves under the mock (CI run 33699015755, checks-node-compact-large-21).

* fix(security): scope the cross-agent audit to unsandboxed sessions

The audit finding now names which agents can reach other agents
(unsandboxed sessions, or any session when
agents.defaults.sandbox.sessionToolsVisibility is "all"), emits nothing
when every agent is fully sandboxed under the default clamp, and says
sandboxed transcripts stay readable by unsandboxed callers.

Docs qualify the agent-to-agent reference with the requester-owned
native/ACP child exception and correct the security overview's sandbox
wording. Addresses both ClawSweeper rank-up moves on #136755.

* docs(security): qualify the fully sandboxed audit exemption

State in the CLI reference and high-level security audit summary that
fully sandboxed rosters under the default spawn-tree clamp produce no
cross-agent access finding. Disabling that clamp removes the exemption.

Addresses the mechanical ClawSweeper rank-up on #136755 at 3208e19534e.

* fix(security): report per-agent session tool reach in the cross-agent audit

The finding now lists which agents can reach other agents (unclamped sessions that still have a session tool allowed) with their calling context and allowed tools, lists non-reaching agents with the reason, and emits nothing when nobody reaches; help text no longer claims enabled=false isolates agents because requester-owned native/ACP child sessions stay reachable under tree or all visibility; gateway final-effect proof that a disabled policy or restrictive allow list never dispatches to the target. Addresses the ClawSweeper re-review on #136755.

* test(gateway): drain detached a2a flow in an afterEach hook

The in-row drain shared the row's 10s budget and could time out under load, leaking the next row's mock calls; the hook has its own bounded timeout.

* docs: stop describing disabled agent-to-agent access as isolation

enabled: false blocks ordinary cross-agent access, but requester-owned native subagent and ACP child sessions stay reachable under tree or all visibility; every introduced claim now says so and points strict separation to tools.sessions.visibility or separate gateways. Addresses the ClawSweeper P2 on #136755.

* test(qa-lab): prove default cross-agent send and policy denials end to end

Three mock-openai flow scenarios run a two-agent QA Gateway: default config dispatches sessions_send to agent:orion:main (accepted, target run observed, target main session created); enabled=false and a restrictive allow list return forbidden before any target work. Addresses the ClawSweeper P1 merge risk on #136755.

* fix(config): stop listing tree visibility as strict separation

Strict separation is agent or self; tree still admits requester-owned native subagent and ACP child sessions across agents. Addresses a ClawSweeper rank-up move on #136755.
2026-09-02 22:39:03 -07:00

8.9 KiB
Raw Blame History

summary read_when title
CLI reference for `openclaw security` (audit and fix common security footguns)
You want to run a quick security audit on config/state
You want to apply safe "fix" suggestions (permissions, tighten defaults)
Security

openclaw security

Security tools: audit plus optional safe fixes. Related: Security.

openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --auth password --password <password>
openclaw security audit --fix
openclaw security audit --json

Audit modes

Plain security audit stays on the cold config/filesystem/read-only path: it does not discover plugin runtime security collectors, so routine audits do not load every installed plugin runtime. --deep adds best-effort live Gateway probes and plugin-owned security audit collectors (explicit internal callers may also opt into those collectors when they already have an appropriate runtime scope).

If Gateway password auth is supplied only at startup, pass the same value with --auth password --password <password> so the audit can check it against hooks.token.

What it checks

DM/trust model

  • Warns when multiple DM senders share the main session and recommends secure DM mode: session.dmScope="per-channel-peer" (or per-account-channel-peer for multi-account channels) for shared inboxes. This is cooperative/shared-inbox hardening, not isolation for mutually untrusted operators; split trust boundaries with separate gateways (or separate OS users/hosts) for that.
  • Emits security.trust_model.group_scope_main when global session.groupScope="main" or a binding override merges group/channel rooms into the main session. Every member of each matched room shares that context, so reserve this for trusted rooms (see Groups).
  • Emits security.trust_model.multi_user_heuristic when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules) — OpenClaw's default trust model is personal-assistant (one operator), not hostile multi-tenant isolation. For intentional shared-user setups: sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
  • Emits security.trust_model.cross_agent_session_access_default when two or more agents have tools.sessions.visibility resolving to all and agent-to-agent access enabled with an omitted or empty tools.agentToAgent.allow list, provided at least one agent retains a session tool in an unclamped context (unsandboxed sessions or agents.defaults.sandbox.sessionToolsVisibility: "all"). The detail lists each agent's reach and allowed session tools; no finding is emitted if every agent is clamped or has no session tools. This is info for plain multi-agent setups, escalating to warn when an agent is sandboxed, has agent-level tool restrictions, or shared-user ingress signals suggest different trust levels. Narrow session visibility or agent-to-agent access for persona separation.
  • Warns when small models (<=300B parameters) are used without sandboxing and with web/browser tools enabled.

Webhook/hooks

Startup logs a non-fatal security warning, and audit flags hooks.token reuse of active Gateway shared-secret auth values (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN, gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD). Also warns when:

  • hooks.token is short
  • hooks.path="/"
  • hooks.defaultSessionKey is unset
  • hooks.allowedAgentIds is unrestricted
  • request sessionKey overrides are enabled
  • overrides are enabled without hooks.allowedSessionKeyPrefixes

Run openclaw doctor --fix to rotate a persisted reused hooks.token, then update external hook senders to use the new token.

Sandbox/tools

  • Warns when sandbox Docker settings are configured while sandbox mode is off.
  • Warns when gateway.nodes.commands.deny uses ineffective pattern-like/unknown entries (matching is exact node command-name only, not shell-text filtering).
  • Warns when gateway.nodes.commands.allow explicitly enables dangerous node commands.
  • Warns when global tools.profile="minimal" is overridden by agent tool profiles.
  • Warns when write/edit tools are disabled but exec is still available without a constraining sandbox filesystem boundary.
  • Warns when open DMs or groups expose runtime/filesystem tools without sandbox/workspace guards.
  • Warns when installed plugin tools may be reachable under permissive tool policy.

Sandbox browser

  • Warns when sandbox browser uses Docker bridge network without sandbox.browser.cdpSourceRange.
  • Flags dangerous sandbox Docker network modes, including host and container:* namespace joins.
  • Warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing openclaw.browserConfigEpoch) and recommends openclaw sandbox recreate --browser --all.

Network/discovery

  • Flags gateway.allowRealIpFallback=true (header-spoofing risk if proxies are misconfigured).
  • Flags discovery.mdns.mode="full" (metadata leakage via mDNS TXT records).
  • Warns when gateway.auth.mode="none" leaves Gateway HTTP APIs reachable without a shared secret (/tools/invoke plus any enabled /v1/* endpoint).

Plugins/channels

  • Warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
  • Warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).

Settings prefixed with dangerous/dangerously are explicit break-glass operator overrides; enabling one is not, by itself, a security vulnerability report. For the complete dangerous-parameter inventory, see "Insecure or dangerous flags summary" in Security.

SecretRef behavior

security audit resolves supported SecretRefs in read-only mode for its targeted paths. If a SecretRef is unavailable in the current command path, audit continues and reports secretDiagnostics instead of crashing. --token and --password only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings.

Suppressions

Accept intentional standing findings with security.audit.suppressions. Each suppression matches an exact checkId and can be narrowed with case-insensitive titleIncludes and/or detailIncludes substrings:

{
  "security": {
    "audit": {
      "suppressions": [
        {
          "checkId": "plugins.tools_reachable_permissive_policy",
          "detailIncludes": "Enabled extension plugins: gbrain",
          "reason": "trusted local operator plugin"
        }
      ]
    }
  }
}

Suppressed findings are removed from the active summary and findings list. JSON output keeps them under suppressedFindings for auditability. When suppressions are configured, active output also keeps an unsuppressible security.audit.suppressions.active info finding so readers can tell the audit was filtered. Dangerous config flags are emitted one flag per finding, so accepting one dangerous flag does not hide other enabled flags that share the same config.insecure_or_dangerous_flags checkId.

Because suppressions can hide standing risk, adding or removing them through agent-run shell commands requires exec approval unless exec is already running with security="full" and ask="off" for trusted local automation.

JSON output

openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'

With --fix --json, output includes both fix actions and the final report:

openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'

What --fix changes

Applies safe, deterministic remediations:

  • flips common groupPolicy="open" to groupPolicy="allowlist" (including account variants in supported channels)
  • when WhatsApp group policy flips to allowlist, seeds groupAllowFrom from the stored allowFrom file when that list exists and config does not already define allowFrom
  • tightens permissions for state/config and common sensitive files (credentials/*.json, legacy auth-profiles.json, openclaw-agent.sqlite, and legacy session artifacts)
  • also tightens config include files referenced from openclaw.json
  • uses chmod on POSIX hosts and icacls resets on Windows

--fix does not:

  • rotate tokens/passwords/API keys
  • disable tools (gateway, cron, exec, etc.)
  • change gateway bind/auth/network exposure choices
  • remove or rewrite plugins/skills

Related