docs(security): clarify disclosure policy

vincentkoc · vincentkoc · commit 4429ee7d2e7f · 2026-04-30T13:41:51.000-07:00
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,8 +1,14 @@
 # Security Policy
 
-If you believe you've found a security issue in OpenClaw, please report it privately.
+If you believe you've found a security issue in OpenClaw, report it privately first.
 
-## Reporting
+This policy does two things: it gives researchers a clear disclosure path, and it spells out the trust model maintainers use when triaging reports. OpenClaw is local-first agent infrastructure for trusted operators; it is not designed as a shared multi-tenant boundary between adversarial users on one gateway.
+
+The fastest useful reports show a current, reproducible boundary bypass with demonstrated impact. Scanner output, prompt-injection-only chains, or reports that rely on hostile users sharing one trusted gateway are usually not security vulnerabilities under this model.
+
+Security work is shared across a number of OpenClaw maintainers, including engineers and security researchers from organizations such as NVIDIA. See the [maintainer list](CONTRIBUTING.md#maintainers).
+
+## Report a Security Issue
 
 Report vulnerabilities directly to the repository where the issue lives:
 
@@ -15,22 +21,50 @@ Report vulnerabilities directly to the repository where the issue lives:
 
 For issues that don't fit a specific repo, or if you're unsure, email **[security@openclaw.ai](mailto:security@openclaw.ai)** and we'll route it.
 
+For OpenClaw core issues, submit through a private [GitHub Security Advisory](https://github.com/openclaw/openclaw/security/advisories/new). Do not open a public issue or PR that discloses an unpatched vulnerability, exploit path, secret, or security-sensitive proof of concept.
+
+Maintainers may close, hide, delete, or otherwise take down public issues and PRs that disclose vulnerabilities or active security issues. We will redirect those reports through the private disclosure process so the issue can be triaged and fixed without giving attackers a public playbook.
+
 For full reporting instructions see our [Trust page](https://trust.openclaw.ai).
 
-### Required in Reports
+OpenClaw does not currently run a paid bug bounty program. Please still disclose responsibly so we can fix real issues quickly. The best way to help the project right now is to send high-signal reports and, when practical, focused PRs.
+
+### What We Need
 
-1. **Title**
-2. **Severity Assessment**
-3. **Impact**
-4. **Affected Component**
-5. **Technical Reproduction**
-6. **Demonstrated Impact**
-7. **Environment**
-8. **Remediation Advice**
+Make the report easy to reproduce and easy to route:
 
-Reports without reproduction steps, demonstrated impact, and remediation advice will be deprioritized. Given the volume of AI-generated scanner findings, we must ensure we're receiving vetted reports from researchers who understand the issues.
+- What you found and why you believe it is security-relevant.
+- The affected component, version, and commit SHA when possible.
+- Reproduction steps or a proof of concept against latest `main` or the latest released version.
+- The actual impact, including which OpenClaw trust boundary is crossed.
+- Any remediation advice or focused patch you can provide.
 
-### Report Acceptance Gate (Triage Fast Path)
+Reports without reproduction steps, demonstrated impact, and remediation advice are deprioritized. We receive a high volume of AI-generated scanner findings, so we prioritize vetted reports from researchers who can show how the issue crosses an OpenClaw security boundary.
+
+### What Usually Is Not a Security Bug
+
+These patterns are usually not vulnerabilities by themselves:
+
+- Prompt injection without a policy, auth, approval, sandbox, or tool-boundary bypass.
+- A trusted operator using an intentional local feature, such as local shell access or browser/script execution.
+- A malicious plugin after a trusted operator installs or enables it.
+- Multiple adversarial users sharing one Gateway host/config and expecting per-user isolation.
+- Scanner-only, dependency-only, or stale-path reports without a working repro and demonstrated OpenClaw impact.
+- Public internet exposure or risky deployment choices that the docs already recommend against.
+
+If you are unsure, report privately. We would rather route a careful report than miss a real boundary issue.
+
+### Duplicate Report Handling
+
+- Search existing advisories before filing.
+- Include likely duplicate GHSA IDs in your report when applicable.
+- Maintainers may close lower-quality/later duplicates in favor of the earliest high-quality canonical report.
+
+## Security Posture and Report Rules
+
+The sections below are the normative posture maintainers use for report triage. The headings are editorial; the policy text defines the boundary.
+
+### Detailed Report Acceptance Gate
 
 For fastest triage, include all of the following:
 
@@ -47,7 +81,7 @@ For fastest triage, include all of the following:
 
 Reports that miss these requirements may be closed as `invalid` or `no-action`.
 
-### Common False-Positive Patterns
+### Detailed False-Positive Patterns
 
 These are frequently reported but are typically closed with no code change:
 
@@ -78,26 +112,11 @@ These are frequently reported but are typically closed with no code change:
 - Reports that restate an already-fixed issue against later released versions without showing the vulnerable path still exists in the shipped tag or published artifact for that later version.
 - SSRF reports against the operator-managed HTTP/WebSocket proxy-routing feature whose only claim is that ordinary process-local HTTP clients (`fetch`, `node:http`, `node:https`, WebSocket clients, axios/got/node-fetch-style clients) can reach an internal, metadata, private, or otherwise sensitive destination when proxy routing is disabled, missing, or the operator-managed proxy policy allows it. For this feature, OpenClaw provides fail-closed proxy routing when enabled; the external proxy's destination policy is operator infrastructure, not an OpenClaw-controlled security boundary. See [Network proxy](https://docs.openclaw.ai/security/network-proxy).
 
-### Duplicate Report Handling
-
-- Search existing advisories before filing.
-- Include likely duplicate GHSA IDs in your report when applicable.
-- Maintainers may close lower-quality/later duplicates in favor of the earliest high-quality canonical report.
-
-## Security & Trust
-
-**Jamieson O'Reilly** ([@theonejvo](https://twitter.com/theonejvo)) is Security & Trust at OpenClaw. Jamieson is the founder of [Dvuln](https://dvuln.com) and brings extensive experience in offensive security, penetration testing, and security program development.
-
-## Bug Bounties
-
-OpenClaw is a labor of love. There is no bug bounty program and no budget for paid reports. Please still disclose responsibly so we can fix issues quickly.
-The best way to help the project right now is by sending PRs.
-
-## Maintainers: GHSA Updates via CLI
+### Maintainer GHSA Updates via CLI
 
 When patching a GHSA via `gh api`, include `X-GitHub-Api-Version: 2022-11-28` (or newer). Without it, some fields (notably CVSS) may not persist even if the request returns 200.
 
-## Operator Trust Model (Important)
+### Operator Trust Model
 
 OpenClaw does **not** model one gateway as a multi-tenant, adversarial user boundary.
 
@@ -122,15 +141,15 @@ OpenClaw does **not** model one gateway as a multi-tenant, adversarial user boun
 - Implicit exec calls (no explicit host in the tool call) follow the same behavior.
 - This is expected in OpenClaw's one-user trusted-operator model. If you need isolation, enable sandbox mode (`non-main`/`all`) and keep strict tool policy.
 
-## Trusted Plugin Concept (Core)
+### Trusted Plugins
 
 Plugins/extensions are part of OpenClaw's trusted computing base for a gateway.
 
 - Installing or enabling a plugin grants it the same trust level as local code running on that gateway host.
 - Plugin behavior such as reading env/files or running host commands is expected inside this trust boundary.
 - Security reports must show a boundary bypass (for example unauthenticated plugin load, allowlist/policy bypass, or sandbox/path-safety bypass), not only malicious behavior from a trusted-installed plugin.
 
-## Out of Scope
+### Out of Scope
 
 - Public Internet Exposure
 - Using OpenClaw in ways that the docs recommend not to
@@ -156,7 +175,7 @@ Plugins/extensions are part of OpenClaw's trusted computing base for a gateway.
 - Reports whose only claim is that a platform-provided upload destination URL is untrusted (for example Microsoft Teams `fileConsent/invoke` `uploadInfo.uploadUrl`) without proving attacker control in an authenticated production flow.
 - SSRF reports limited to the operator-managed HTTP/WebSocket proxy-routing feature where the demonstrated mitigation is to enable/configure `proxy.enabled` with a filtering `proxy.proxyUrl`/`OPENCLAW_PROXY_URL`, or where impact depends on a permissive/misconfigured operator proxy. This only covers normal process-local HTTP(S)/WebSocket egress (`fetch`, Node HTTP(S), and similar JavaScript clients); non-HTTP egress and other features are assessed separately. See [Network proxy](https://docs.openclaw.ai/security/network-proxy).
 
-## Deployment Assumptions
+### Deployment Assumptions
 
 OpenClaw security guidance assumes:
 
@@ -166,7 +185,7 @@ OpenClaw security guidance assumes:
 - Authenticated Gateway callers are treated as trusted operators. Session identifiers (for example `sessionKey`) are routing controls, not per-user authorization boundaries.
 - Multiple gateway instances can run on one machine, but the recommended model is clean per-user isolation (prefer one host/VPS per user).
 
-## One-User Trust Model (Personal Assistant)
+### One-User Trust Model
 
 OpenClaw's security model is "personal assistant" (one trusted operator, potentially many agents), not "shared multi-tenant bus."
 
@@ -178,7 +197,7 @@ OpenClaw's security model is "personal assistant" (one trusted operator, potenti
 - For company-shared setups, use a dedicated machine/VM/container and dedicated accounts; avoid mixing personal data on that runtime.
 - If that host/browser profile is logged into personal accounts (for example Apple/Google/personal password manager), you have collapsed the boundary and increased personal-data exposure risk.
 
-## Context Visibility and Allowlists
+### Context Visibility and Allowlists
 
 OpenClaw distinguishes:
 
@@ -196,15 +215,15 @@ Reports that only show supplemental-context visibility differences are typically
 
 Hardening roadmap may add explicit visibility modes (for example `all`, `allowlist`, `allowlist_quote`) so operators can opt into stricter context filtering with predictable tradeoffs.
 
-## Agent and Model Assumptions
+### Agent and Model Assumptions
 
 - The model/agent is **not** a trusted principal. Assume prompt/content injection can manipulate behavior.
 - Security boundaries come from host/config trust, auth, tool policy, sandboxing, and exec approvals.
 - Prompt injection by itself is not a vulnerability report unless it crosses one of those boundaries.
 - Hook/webhook-driven payloads should be treated as untrusted content; keep unsafe bypass flags disabled unless doing tightly scoped debugging (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`).
 - Weak model tiers are generally easier to prompt-inject. For tool-enabled or hook-driven agents, prefer strong modern model tiers and strict tool policy (for example `tools.profile: "messaging"` or stricter), plus sandboxing where possible.
 
-## Gateway and Node trust concept
+### Gateway and Node Trust Concept
 
 OpenClaw separates routing from execution, but both remain inside the same operator trust boundary:
 
@@ -215,7 +234,7 @@ OpenClaw separates routing from execution, but both remain inside the same opera
 - Differences in command-risk warning heuristics between exec surfaces (`gateway`, `node`, `sandbox`) do not, by themselves, constitute a security-boundary bypass.
 - For untrusted-user isolation, split by trust boundary: separate gateways and separate OS users/hosts per boundary.
 
-## Workspace Memory Trust Boundary
+### Workspace Memory Trust Boundary
 
 `MEMORY.md` and `memory/*.md` are plain workspace files and are treated as trusted local operator state.
 
@@ -224,15 +243,15 @@ OpenClaw separates routing from execution, but both remain inside the same opera
 - Example report pattern considered out of scope: "attacker writes malicious content into `memory/*.md`, then `memory_search` returns it."
 - If you need isolation between mutually untrusted users, split by OS user or host and run separate gateways.
 
-## Plugin Trust Boundary
+### Plugin Trust Boundary
 
 Plugins/extensions are loaded **in-process** with the Gateway and are treated as trusted code.
 
 - Plugins can execute with the same OS privileges as the OpenClaw process.
 - Runtime helpers (for example `runtime.system.runCommandWithTimeout`) are convenience APIs, not a sandbox boundary.
 - Only install plugins you trust, and prefer `plugins.allow` to pin explicit trusted plugin ids.
 
-## Temp Folder Boundary (Media/Sandbox)
+### Temp Folder Boundary
 
 OpenClaw uses a dedicated temp root for local media handoff and sandbox-adjacent temp artifacts:
 
@@ -249,27 +268,27 @@ Security boundary notes:
   - SDK temp helpers: `src/plugin-sdk/temp-path.ts`
   - messaging/channel tmp guardrail: `scripts/check-no-random-messaging-tmp.mjs`
 
-## Operational Guidance
+### Operational Guidance
 
 For threat model + hardening guidance (including `openclaw security audit --deep` and `--fix`), see:
 
 - `https://docs.openclaw.ai/gateway/security`
 
-### Tool filesystem hardening
+#### Tool Filesystem Hardening
 
 - `tools.exec.applyPatch.workspaceOnly: true` (recommended): keeps `apply_patch` writes/deletes within the configured workspace directory.
 - `tools.fs.workspaceOnly: true` (optional): restricts `read`/`write`/`edit`/`apply_patch` paths and native prompt image auto-load paths to the workspace directory.
 - Avoid setting `tools.exec.applyPatch.workspaceOnly: false` unless you fully trust who can trigger tool execution.
 
-### Sub-agent delegation hardening
+#### Sub-Agent Delegation Hardening
 
 - Keep `sessions_spawn` denied unless you explicitly need delegated runs.
 - Keep `agents.list[].subagents.allowAgents` narrow, and only include agents with sandbox settings you trust.
 - When delegation must stay sandboxed, call `sessions_spawn` with `sandbox: "require"` (default is `inherit`).
   - `sandbox: "require"` rejects the spawn unless the target child runtime is sandboxed.
   - This prevents a less-restricted session from delegating work into an unsandboxed child by mistake.
 
-### Web Interface Safety
+#### Web Interface Safety
 
 OpenClaw's web interface (Gateway Control UI + HTTP endpoints) is intended for **local use only**.
 
@@ -321,12 +340,39 @@ docker run --read-only --cap-drop=ALL \
 
 ## Security Scanning
 
-This project uses `detect-secrets` for automated secret detection in CI/CD.
-See `.detect-secrets.cfg` for configuration and `.secrets.baseline` for the baseline.
+OpenClaw uses several security and release-validation layers. No single scanner is treated as the boundary.
+
+### Secret Detection
 
-Run locally:
+OpenClaw uses `detect-secrets` with a checked-in baseline and local exclusion notes (`.secrets.baseline`, `.detect-secrets.cfg`). Secret-resolution behavior is also covered by the dedicated secrets test surface.
+
+Run the baseline scan locally:
 
 ```bash
 pip install detect-secrets==1.5.0
 detect-secrets scan --baseline .secrets.baseline
 ```
+
+### Static Analysis
+
+CI runs CodeQL across core TypeScript, GitHub Actions, Android, macOS, and high-risk runtime boundaries using `.github/workflows/codeql*.yml` and `.github/codeql/*.yml`.
+
+OpenGrep provides a high-precision Semgrep-compatible layer. PRs run a changed-path scan; maintainers can run a full repository scan when needed. The rulepack lives under `security/opengrep/`, with `.semgrepignore` as the shared exclusion file.
+
+Run the local OpenGrep wrapper after installing `opengrep`:
+
+```bash
+scripts/run-opengrep.sh --changed --sarif --error
+pnpm check:opengrep-rule-metadata
+```
+
+### E2E and Live Validation
+
+Security-relevant behavior is also covered by runtime validation, not only static scanning:
+
+- `pnpm test:e2e` for repo E2E coverage.
+- `pnpm test:live` for live provider/runtime coverage.
+- `pnpm test:docker:all` for Docker-packaged runtime scenarios.
+- Package acceptance and scheduled live/E2E workflows for release-path validation.
+
+These lanes exercise packaged installs, gateway/runtime behavior, live model/provider paths, Docker scenarios, and platform smoke tests. They complement scanners by proving the security-sensitive flows still behave correctly in real runtime environments.
