Vendor OpenClaw source as Adolf fork baseline
Some checks failed
ClawSweeper Dispatch / dispatch (push) Has been cancelled
CodeQL / Security High (actions) (push) Has been cancelled
CodeQL / Security High (channel-runtime-boundary) (push) Has been cancelled
CodeQL / Security High (core-auth-secrets) (push) Has been cancelled
CodeQL / Security High (mcp-process-tool-boundary) (push) Has been cancelled
CodeQL / Security High (network-ssrf-boundary) (push) Has been cancelled
CodeQL / Security High (plugin-trust-boundary) (push) Has been cancelled
CodeQL / Security High (process-exec-boundary) (push) Has been cancelled
Docs Sync Publish Repo / sync-publish-repo (push) Has been cancelled
Docs / docs (push) Has been cancelled
OpenClaw Stable Main Closeout / Resolve stable release closeout inputs (push) Has been cancelled
OpenClaw Stable Main Closeout / Verify stable main closeout (push) Has been cancelled
Workflow Sanity / no-tabs (push) Has been cancelled
Workflow Sanity / actionlint (push) Has been cancelled
Workflow Sanity / generated-doc-baselines (push) Has been cancelled
CI / runner-admission (push) Has been cancelled
CI / preflight (push) Has been cancelled
CI / security-fast (push) Has been cancelled
CI / pnpm-store-warmup (push) Has been cancelled
CI / build-artifacts (push) Has been cancelled
CI / native-i18n (push) Has been cancelled
CI / ${{ matrix.check_name }} (push) Has been cancelled
CI / ${{ matrix.checkName }} (push) Has been cancelled
CI / checks-node-compat-node22 (push) Has been cancelled
CI / check-bundled-channel-config-metadata (push) Has been cancelled
CI / check-dependencies (push) Has been cancelled
CI / check-guards (push) Has been cancelled
CI / check-lint (push) Has been cancelled
CI / check-prod-types (push) Has been cancelled
CI / check-shrinkwrap (push) Has been cancelled
CI / check-test-types (push) Has been cancelled
CI / check-additional-boundaries-a (push) Has been cancelled
CI / check-additional-boundaries-bcd (push) Has been cancelled
CI / check-additional-extension-bundled (push) Has been cancelled
CI / check-additional-extension-channels (push) Has been cancelled
CI / check-additional-extension-package-boundary (push) Has been cancelled
CI / check-additional-runtime-topology-architecture (push) Has been cancelled
CI / check-session-accessor-boundary (push) Has been cancelled
CI / check-session-transcript-reader-boundary (push) Has been cancelled
CI / check-docs (push) Has been cancelled
CI / skills-python (push) Has been cancelled
CI / macos-swift (push) Has been cancelled
CI / ios-build (push) Has been cancelled
CI / ci-timings-summary (push) Has been cancelled
Native App Locale Refresh / Refresh native fa (push) Has been cancelled
Native App Locale Refresh / Refresh native fr (push) Has been cancelled
Native App Locale Refresh / Refresh native hi (push) Has been cancelled
Native App Locale Refresh / Refresh native id (push) Has been cancelled
Native App Locale Refresh / Refresh native it (push) Has been cancelled
Native App Locale Refresh / Refresh native ja-JP (push) Has been cancelled
Control UI Locale Refresh / plan (push) Has been cancelled
Control UI Locale Refresh / Refresh ${{ matrix.locale }} (push) Has been cancelled
Control UI Locale Refresh / Commit control UI locale refresh (push) Has been cancelled
Live Media Runner Image / Build live media runner image (push) Has been cancelled
Native App Locale Refresh / Refresh native ar (push) Has been cancelled
Native App Locale Refresh / Refresh native de (push) Has been cancelled
Native App Locale Refresh / Refresh native es (push) Has been cancelled
Native App Locale Refresh / Refresh native ko (push) Has been cancelled
Native App Locale Refresh / Refresh native nl (push) Has been cancelled
Native App Locale Refresh / Refresh native pl (push) Has been cancelled
Native App Locale Refresh / Refresh native pt-BR (push) Has been cancelled
Native App Locale Refresh / Refresh native ru (push) Has been cancelled
Native App Locale Refresh / Refresh native sv (push) Has been cancelled
Native App Locale Refresh / Refresh native th (push) Has been cancelled
Native App Locale Refresh / Refresh native tr (push) Has been cancelled
Native App Locale Refresh / Refresh native uk (push) Has been cancelled
Native App Locale Refresh / Refresh native vi (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-CN (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-TW (push) Has been cancelled
Native App Locale Refresh / Commit native locale refresh (push) Has been cancelled
Plugin Init Scaffold Validation / Validate provider scaffold (push) Has been cancelled
Plugin NPM Release / preview_plugins_npm (push) Has been cancelled
Plugin NPM Release / Validate release publish approval (push) Has been cancelled
Plugin NPM Release / preview_plugin_pack (push) Has been cancelled
Plugin NPM Release / publish_plugins_npm (push) Has been cancelled
Sandbox Common Smoke / sandbox-common-smoke (push) Has been cancelled
Website Installer Sync / static (push) Has been cancelled
Website Installer Sync / linux-docker (push) Has been cancelled
Website Installer Sync / macos-installer (push) Has been cancelled
Website Installer Sync / windows-installer (push) Has been cancelled
Website Installer Sync / sync-website (push) Has been cancelled
Some checks failed
ClawSweeper Dispatch / dispatch (push) Has been cancelled
CodeQL / Security High (actions) (push) Has been cancelled
CodeQL / Security High (channel-runtime-boundary) (push) Has been cancelled
CodeQL / Security High (core-auth-secrets) (push) Has been cancelled
CodeQL / Security High (mcp-process-tool-boundary) (push) Has been cancelled
CodeQL / Security High (network-ssrf-boundary) (push) Has been cancelled
CodeQL / Security High (plugin-trust-boundary) (push) Has been cancelled
CodeQL / Security High (process-exec-boundary) (push) Has been cancelled
Docs Sync Publish Repo / sync-publish-repo (push) Has been cancelled
Docs / docs (push) Has been cancelled
OpenClaw Stable Main Closeout / Resolve stable release closeout inputs (push) Has been cancelled
OpenClaw Stable Main Closeout / Verify stable main closeout (push) Has been cancelled
Workflow Sanity / no-tabs (push) Has been cancelled
Workflow Sanity / actionlint (push) Has been cancelled
Workflow Sanity / generated-doc-baselines (push) Has been cancelled
CI / runner-admission (push) Has been cancelled
CI / preflight (push) Has been cancelled
CI / security-fast (push) Has been cancelled
CI / pnpm-store-warmup (push) Has been cancelled
CI / build-artifacts (push) Has been cancelled
CI / native-i18n (push) Has been cancelled
CI / ${{ matrix.check_name }} (push) Has been cancelled
CI / ${{ matrix.checkName }} (push) Has been cancelled
CI / checks-node-compat-node22 (push) Has been cancelled
CI / check-bundled-channel-config-metadata (push) Has been cancelled
CI / check-dependencies (push) Has been cancelled
CI / check-guards (push) Has been cancelled
CI / check-lint (push) Has been cancelled
CI / check-prod-types (push) Has been cancelled
CI / check-shrinkwrap (push) Has been cancelled
CI / check-test-types (push) Has been cancelled
CI / check-additional-boundaries-a (push) Has been cancelled
CI / check-additional-boundaries-bcd (push) Has been cancelled
CI / check-additional-extension-bundled (push) Has been cancelled
CI / check-additional-extension-channels (push) Has been cancelled
CI / check-additional-extension-package-boundary (push) Has been cancelled
CI / check-additional-runtime-topology-architecture (push) Has been cancelled
CI / check-session-accessor-boundary (push) Has been cancelled
CI / check-session-transcript-reader-boundary (push) Has been cancelled
CI / check-docs (push) Has been cancelled
CI / skills-python (push) Has been cancelled
CI / macos-swift (push) Has been cancelled
CI / ios-build (push) Has been cancelled
CI / ci-timings-summary (push) Has been cancelled
Native App Locale Refresh / Refresh native fa (push) Has been cancelled
Native App Locale Refresh / Refresh native fr (push) Has been cancelled
Native App Locale Refresh / Refresh native hi (push) Has been cancelled
Native App Locale Refresh / Refresh native id (push) Has been cancelled
Native App Locale Refresh / Refresh native it (push) Has been cancelled
Native App Locale Refresh / Refresh native ja-JP (push) Has been cancelled
Control UI Locale Refresh / plan (push) Has been cancelled
Control UI Locale Refresh / Refresh ${{ matrix.locale }} (push) Has been cancelled
Control UI Locale Refresh / Commit control UI locale refresh (push) Has been cancelled
Live Media Runner Image / Build live media runner image (push) Has been cancelled
Native App Locale Refresh / Refresh native ar (push) Has been cancelled
Native App Locale Refresh / Refresh native de (push) Has been cancelled
Native App Locale Refresh / Refresh native es (push) Has been cancelled
Native App Locale Refresh / Refresh native ko (push) Has been cancelled
Native App Locale Refresh / Refresh native nl (push) Has been cancelled
Native App Locale Refresh / Refresh native pl (push) Has been cancelled
Native App Locale Refresh / Refresh native pt-BR (push) Has been cancelled
Native App Locale Refresh / Refresh native ru (push) Has been cancelled
Native App Locale Refresh / Refresh native sv (push) Has been cancelled
Native App Locale Refresh / Refresh native th (push) Has been cancelled
Native App Locale Refresh / Refresh native tr (push) Has been cancelled
Native App Locale Refresh / Refresh native uk (push) Has been cancelled
Native App Locale Refresh / Refresh native vi (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-CN (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-TW (push) Has been cancelled
Native App Locale Refresh / Commit native locale refresh (push) Has been cancelled
Plugin Init Scaffold Validation / Validate provider scaffold (push) Has been cancelled
Plugin NPM Release / preview_plugins_npm (push) Has been cancelled
Plugin NPM Release / Validate release publish approval (push) Has been cancelled
Plugin NPM Release / preview_plugin_pack (push) Has been cancelled
Plugin NPM Release / publish_plugins_npm (push) Has been cancelled
Sandbox Common Smoke / sandbox-common-smoke (push) Has been cancelled
Website Installer Sync / static (push) Has been cancelled
Website Installer Sync / linux-docker (push) Has been cancelled
Website Installer Sync / macos-installer (push) Has been cancelled
Website Installer Sync / windows-installer (push) Has been cancelled
Website Installer Sync / sync-website (push) Has been cancelled
Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11), free to diverge. Tree copied sans upstream .git; upstream remote added for future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19. Preserves docs/ARCHITECTURE.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2
This commit is contained in:
85
docs/security/CONTRIBUTING-THREAT-MODEL.md
Normal file
85
docs/security/CONTRIBUTING-THREAT-MODEL.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
summary: "How to contribute to the OpenClaw threat model"
|
||||
title: "Contributing to the threat model"
|
||||
read_when:
|
||||
- You want to contribute security findings or threat scenarios
|
||||
- Reviewing or updating the threat model
|
||||
---
|
||||
|
||||
The [threat model](/security/THREAT-MODEL-ATLAS) is a living document. Contributions are welcome from anyone; you do not need security or MITRE ATLAS background.
|
||||
|
||||
<Note>
|
||||
This is for adding to the threat model, not reporting live vulnerabilities. If you found an exploitable vulnerability, follow the responsible-disclosure instructions on the [Trust page](https://trust.openclaw.ai) instead.
|
||||
</Note>
|
||||
|
||||
## Ways to contribute
|
||||
|
||||
**Add a threat.** Open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues) describing the attack scenario in your own words. Helpful but not required:
|
||||
|
||||
- The attack scenario and how it could be exploited.
|
||||
- Which components are affected (CLI, gateway, channels, ClawHub, MCP servers, etc.).
|
||||
- Your estimate of severity (low / medium / high / critical).
|
||||
- Links to related research, CVEs, or real-world examples.
|
||||
|
||||
Maintainers assign the ATLAS mapping, threat ID, and risk level during review.
|
||||
|
||||
**Suggest a mitigation.** Open an issue or PR referencing the threat. Be specific and actionable: "per-sender rate limiting of 10 messages/minute at the gateway" is more useful than "implement rate limiting."
|
||||
|
||||
**Propose an attack chain.** Attack chains show how multiple threats combine into a realistic scenario. Describe the steps and how an attacker would chain them; a short narrative beats a formal template.
|
||||
|
||||
**Fix or improve existing content.** Typos, clarifications, outdated info, better examples: PRs welcome, no issue needed.
|
||||
|
||||
## Framework reference
|
||||
|
||||
Threats are mapped to [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems), a framework for AI/ML-specific threats like prompt injection, tool misuse, and agent exploitation. You do not need to know ATLAS to contribute; maintainers map submissions during review.
|
||||
|
||||
**Threat IDs.** Each threat gets an ID like `T-EXEC-003`, assigned by maintainers during review.
|
||||
|
||||
| Code | Category |
|
||||
| ------- | ------------------------------------------ |
|
||||
| RECON | Reconnaissance - information gathering |
|
||||
| ACCESS | Initial access - gaining entry |
|
||||
| EXEC | Execution - running malicious actions |
|
||||
| PERSIST | Persistence - maintaining access |
|
||||
| EVADE | Defense evasion - avoiding detection |
|
||||
| DISC | Discovery - learning about the environment |
|
||||
| EXFIL | Exfiltration - stealing data |
|
||||
| IMPACT | Impact - damage or disruption |
|
||||
|
||||
**Risk levels.** If you are unsure about the level, just describe the impact; maintainers assess it.
|
||||
|
||||
| Level | Meaning |
|
||||
| ------------ | ----------------------------------------------------------------- |
|
||||
| **Critical** | Full system compromise, or high likelihood + critical impact |
|
||||
| **High** | Significant damage likely, or medium likelihood + critical impact |
|
||||
| **Medium** | Moderate risk, or low likelihood + high impact |
|
||||
| **Low** | Unlikely and limited impact |
|
||||
|
||||
## Review process
|
||||
|
||||
1. **Triage** - new submissions are reviewed within 48 hours.
|
||||
2. **Assessment** - maintainers verify feasibility, assign ATLAS mapping and threat ID, validate risk level.
|
||||
3. **Documentation** - formatting and completeness pass.
|
||||
4. **Merge** - added to the threat model and visualization.
|
||||
|
||||
## Resources
|
||||
|
||||
- [ATLAS website](https://atlas.mitre.org/)
|
||||
- [ATLAS techniques](https://atlas.mitre.org/techniques/)
|
||||
- [ATLAS case studies](https://atlas.mitre.org/studies/)
|
||||
|
||||
## Contact
|
||||
|
||||
- **Security vulnerabilities:** [Trust page](https://trust.openclaw.ai) for reporting instructions, or `security@openclaw.ai`.
|
||||
- **Threat model questions:** open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues).
|
||||
- **General chat:** Discord `#security` channel.
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors to the threat model are recognized in the threat model acknowledgments, release notes, and the OpenClaw security hall of fame for significant contributions.
|
||||
|
||||
## Related
|
||||
|
||||
- [Threat model](/security/THREAT-MODEL-ATLAS)
|
||||
- [Incident response](/security/incident-response)
|
||||
- [Formal verification](/security/formal-verification)
|
||||
561
docs/security/THREAT-MODEL-ATLAS.md
Normal file
561
docs/security/THREAT-MODEL-ATLAS.md
Normal file
@@ -0,0 +1,561 @@
|
||||
---
|
||||
summary: "OpenClaw threat model mapped to the MITRE ATLAS framework"
|
||||
title: "Threat model (MITRE ATLAS)"
|
||||
read_when:
|
||||
- Reviewing security posture or threat scenarios
|
||||
- Working on security features or audit responses
|
||||
---
|
||||
|
||||
**Version:** 1.0-draft | **Framework:** [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems) + data flow diagrams
|
||||
|
||||
This threat model documents adversarial threats to the OpenClaw AI agent platform and ClawHub skill marketplace. It is a living document maintained by the OpenClaw community. See [Contributing to the threat model](/security/CONTRIBUTING-THREAT-MODEL) for how to report new threats, propose attack chains, or suggest mitigations.
|
||||
|
||||
**Key ATLAS resources:** [Techniques](https://atlas.mitre.org/techniques/) | [Tactics](https://atlas.mitre.org/tactics/) | [Case studies](https://atlas.mitre.org/studies/) | [ATLAS GitHub](https://github.com/mitre-atlas/atlas-data) | [Contributing to ATLAS](https://atlas.mitre.org/resources/contribute)
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope
|
||||
|
||||
| Component | Included | Notes |
|
||||
| ---------------------- | -------- | ------------------------------------------------ |
|
||||
| OpenClaw agent runtime | Yes | Core agent execution, tool calls, sessions |
|
||||
| Gateway | Yes | Authentication, routing, channel integration |
|
||||
| Channel integrations | Yes | WhatsApp, Telegram, Discord, Signal, Slack, etc. |
|
||||
| ClawHub marketplace | Yes | Skill publishing, moderation, distribution |
|
||||
| MCP servers | Yes | External tool providers |
|
||||
| User devices | Partial | Mobile apps, desktop clients |
|
||||
|
||||
Out-of-scope reports and false-positive patterns (public internet exposure, prompt-injection-only chains without a boundary bypass, mutually untrusted operators sharing one gateway host, and others) are enumerated in [`SECURITY.md`](https://github.com/openclaw/openclaw/blob/main/SECURITY.md); that file is the current source of truth for vulnerability-report scope, not this page.
|
||||
|
||||
## 2. System architecture
|
||||
|
||||
### 2.1 Trust boundaries
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ UNTRUSTED ZONE │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ WhatsApp │ │ Telegram │ │ Discord │ ... │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
||||
│ │ │ │ │
|
||||
└─────────┼────────────────┼────────────────┼──────────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TRUST BOUNDARY 1: Channel Access │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ GATEWAY │ │
|
||||
│ │ • Device pairing (1h DM pairing / 5m node pairing TTL) │ │
|
||||
│ │ • AllowFrom / allowlist validation │ │
|
||||
│ │ • Token / password / Tailscale auth │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TRUST BOUNDARY 2: Session Isolation │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ AGENT SESSIONS │ │
|
||||
│ │ • Session key = agent:channel:peer │ │
|
||||
│ │ • Tool policies per agent │ │
|
||||
│ │ • Transcript logging │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TRUST BOUNDARY 3: Tool Execution │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ EXECUTION SANDBOX │ │
|
||||
│ │ • Docker sandbox (default) or host (exec approvals) │ │
|
||||
│ │ • Node remote execution │ │
|
||||
│ │ • SSRF protection (DNS pinning + IP blocking) │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TRUST BOUNDARY 4: External Content │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ FETCHED URLs / EMAILS / WEBHOOKS │ │
|
||||
│ │ • External content wrapping (random-boundary XML tags) │ │
|
||||
│ │ • Security notice injection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TRUST BOUNDARY 5: Supply Chain │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ CLAWHUB │ │
|
||||
│ │ • Skill publishing (semver, SKILL.md required) │ │
|
||||
│ │ • Static pattern + AST-adjacent moderation scanning │ │
|
||||
│ │ • LLM-based agentic risk review + VirusTotal scanning │ │
|
||||
│ │ • GitHub account age verification (14 days) │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 Data flows
|
||||
|
||||
| Flow | Source | Destination | Data | Protection |
|
||||
| ---- | ------- | ----------- | -------------------- | -------------------- |
|
||||
| F1 | Channel | Gateway | User messages | TLS, AllowFrom |
|
||||
| F2 | Gateway | Agent | Routed messages | Session isolation |
|
||||
| F3 | Agent | Tools | Tool invocations | Policy enforcement |
|
||||
| F4 | Agent | External | `web_fetch` requests | SSRF blocking |
|
||||
| F5 | ClawHub | Agent | Skill code | Moderation, scanning |
|
||||
| F6 | Agent | Channel | Responses | Output filtering |
|
||||
|
||||
---
|
||||
|
||||
## 3. Threat analysis by ATLAS tactic
|
||||
|
||||
### 3.1 Reconnaissance (AML.TA0002)
|
||||
|
||||
#### T-RECON-001: Agent endpoint discovery
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | -------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0006 - Active Scanning |
|
||||
| **Description** | Attacker scans for exposed OpenClaw gateway endpoints |
|
||||
| **Attack vector** | Network scanning, Shodan queries, DNS enumeration |
|
||||
| **Affected components** | Gateway, exposed API endpoints |
|
||||
| **Current mitigations** | Tailscale auth option, bind to loopback by default |
|
||||
| **Residual risk** | Medium - public gateways discoverable |
|
||||
| **Recommendations** | Document secure deployment, add rate limiting on discovery endpoints |
|
||||
|
||||
#### T-RECON-002: Channel integration probing
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------ |
|
||||
| **ATLAS ID** | AML.T0006 - Active Scanning |
|
||||
| **Description** | Attacker probes messaging channels to identify AI-managed accounts |
|
||||
| **Attack vector** | Sending test messages, observing response patterns |
|
||||
| **Affected components** | All channel integrations |
|
||||
| **Current mitigations** | None specific |
|
||||
| **Residual risk** | Low - limited value from discovery alone |
|
||||
| **Recommendations** | Consider response timing randomization |
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Initial access (AML.TA0004)
|
||||
|
||||
#### T-ACCESS-001: Pairing code interception
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0040 - AI Model Inference API Access |
|
||||
| **Description** | Attacker intercepts a pairing code during the pairing window (1h DM/generic pairing, 5m node pairing) |
|
||||
| **Attack vector** | Shoulder surfing, network sniffing, social engineering |
|
||||
| **Affected components** | Device pairing system |
|
||||
| **Current mitigations** | 1h TTL (DM/generic pairing), 5m TTL (node pairing); codes sent via the existing channel |
|
||||
| **Residual risk** | Medium - pairing window exploitable |
|
||||
| **Recommendations** | Reduce pairing window, add a confirmation step |
|
||||
|
||||
#### T-ACCESS-002: AllowFrom spoofing
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------------------ |
|
||||
| **ATLAS ID** | AML.T0040 - AI Model Inference API Access |
|
||||
| **Description** | Attacker spoofs an allowed sender identity on a channel |
|
||||
| **Attack vector** | Channel-dependent - phone number spoofing, username impersonation |
|
||||
| **Affected components** | Per-channel AllowFrom validation |
|
||||
| **Current mitigations** | Channel-specific identity verification |
|
||||
| **Residual risk** | Medium - some channels remain vulnerable to spoofing |
|
||||
| **Recommendations** | Document channel-specific risks, add cryptographic verification where possible |
|
||||
|
||||
#### T-ACCESS-003: Token theft
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------ |
|
||||
| **ATLAS ID** | AML.T0040 - AI Model Inference API Access |
|
||||
| **Description** | Attacker steals authentication tokens from config/credential files |
|
||||
| **Attack vector** | Malware, unauthorized device access, config backup exposure |
|
||||
| **Affected components** | Channel/provider credential storage, config storage |
|
||||
| **Current mitigations** | File permissions |
|
||||
| **Residual risk** | High - tokens stored in plaintext on disk |
|
||||
| **Recommendations** | Implement token encryption at rest, add token rotation |
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Execution (AML.TA0005)
|
||||
|
||||
#### T-EXEC-001: Direct prompt injection
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0051.000 - LLM Prompt Injection: Direct |
|
||||
| **Description** | Attacker sends crafted prompts to manipulate agent behavior |
|
||||
| **Attack vector** | Channel messages containing adversarial instructions |
|
||||
| **Affected components** | Agent LLM, all input surfaces |
|
||||
| **Current mitigations** | Pattern detection, external content wrapping; treated as out-of-scope for vulnerability reports absent a boundary bypass (see `SECURITY.md`) |
|
||||
| **Residual risk** | Critical - detection only, no blocking; sophisticated attacks bypass |
|
||||
| **Recommendations** | Output validation and user confirmation for sensitive actions, layered on top of existing detection |
|
||||
|
||||
#### T-EXEC-002: Indirect prompt injection
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0051.001 - LLM Prompt Injection: Indirect |
|
||||
| **Description** | Attacker embeds malicious instructions in fetched content |
|
||||
| **Attack vector** | Malicious URLs, poisoned emails, compromised webhooks |
|
||||
| **Affected components** | `web_fetch`, email ingestion, external data sources |
|
||||
| **Current mitigations** | Content wrapping with random-boundary XML-style markers, homoglyph/special-token normalization, and a security notice |
|
||||
| **Residual risk** | High - LLM may still ignore wrapper instructions |
|
||||
| **Recommendations** | Separate execution contexts for wrapped content |
|
||||
|
||||
#### T-EXEC-003: Tool argument injection
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------ |
|
||||
| **ATLAS ID** | AML.T0051.000 - LLM Prompt Injection: Direct |
|
||||
| **Description** | Attacker manipulates tool arguments through prompt injection |
|
||||
| **Attack vector** | Crafted prompts that influence tool parameter values |
|
||||
| **Affected components** | All tool invocations |
|
||||
| **Current mitigations** | Exec approvals for dangerous commands |
|
||||
| **Residual risk** | High - relies on user judgment |
|
||||
| **Recommendations** | Argument validation, parameterized tool calls |
|
||||
|
||||
#### T-EXEC-004: Exec approval bypass
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0043 - Craft Adversarial Data |
|
||||
| **Description** | Attacker crafts commands that bypass the approval allowlist |
|
||||
| **Attack vector** | Command obfuscation, alias exploitation, path manipulation |
|
||||
| **Affected components** | `src/infra/exec-approvals*.ts`, command allowlist |
|
||||
| **Current mitigations** | Allowlist + ask mode, plus command normalization (dispatch-wrapper unwrapping, inline-eval detection, shell-chain analysis) |
|
||||
| **Residual risk** | High - normalization narrows but does not eliminate obfuscation bypass; parity-only findings between exec paths are treated as hardening, not vulnerabilities (see `SECURITY.md`) |
|
||||
| **Recommendations** | Continue expanding command-normalization coverage against new obfuscation techniques |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Persistence (AML.TA0006)
|
||||
|
||||
#### T-PERSIST-001: Malicious skill installation
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0010.001 - Supply Chain Compromise: AI Software |
|
||||
| **Description** | Attacker publishes a malicious skill to ClawHub |
|
||||
| **Attack vector** | Create account, publish skill with hidden malicious code |
|
||||
| **Affected components** | ClawHub, skill loading, agent execution |
|
||||
| **Current mitigations** | GitHub account age verification, static pattern/AST-adjacent scanning, LLM-based agentic risk review, VirusTotal scanning |
|
||||
| **Residual risk** | High - detection layers exist but skills still run with agent privileges and no execution sandboxing |
|
||||
| **Recommendations** | Skill execution sandboxing, expanded community review |
|
||||
|
||||
#### T-PERSIST-002: Skill update poisoning
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ----------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0010.001 - Supply Chain Compromise: AI Software |
|
||||
| **Description** | Attacker compromises a popular skill and pushes a malicious update |
|
||||
| **Attack vector** | Account compromise, social engineering of skill owner |
|
||||
| **Affected components** | ClawHub versioning, auto-update flows |
|
||||
| **Current mitigations** | Version fingerprinting, moderation/scanning re-run on new versions |
|
||||
| **Residual risk** | High - auto-updates may pull malicious versions before review completes |
|
||||
| **Recommendations** | Update signing, rollback capability, version pinning |
|
||||
|
||||
#### T-PERSIST-003: Agent configuration tampering
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | --------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0010.002 - Supply Chain Compromise: Data |
|
||||
| **Description** | Attacker modifies agent configuration to persist access |
|
||||
| **Attack vector** | Config file modification, settings injection |
|
||||
| **Affected components** | Agent config, tool policies |
|
||||
| **Current mitigations** | File permissions |
|
||||
| **Residual risk** | Medium - requires local access |
|
||||
| **Recommendations** | Config integrity verification, audit logging for config changes |
|
||||
|
||||
---
|
||||
|
||||
### 3.5 Defense evasion (AML.TA0007)
|
||||
|
||||
#### T-EVADE-001: Moderation pattern bypass
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0043 - Craft Adversarial Data |
|
||||
| **Description** | Attacker crafts skill content to evade ClawHub moderation checks |
|
||||
| **Attack vector** | Unicode homoglyphs, encoding tricks, dynamic loading |
|
||||
| **Affected components** | ClawHub moderation/scanning pipeline |
|
||||
| **Current mitigations** | Static pattern rules, AST-adjacent code scanning, LLM agentic-risk review, VirusTotal |
|
||||
| **Residual risk** | Medium - novel obfuscation can still slip past layered heuristics |
|
||||
| **Recommendations** | Continue expanding the pattern/behavioral corpus as new evasions are found |
|
||||
|
||||
#### T-EVADE-002: Content wrapper escape
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0043 - Craft Adversarial Data |
|
||||
| **Description** | Attacker crafts content that escapes the external-content wrapper context |
|
||||
| **Attack vector** | Tag manipulation, context confusion, instruction override |
|
||||
| **Affected components** | External content wrapping |
|
||||
| **Current mitigations** | Random-boundary XML-style markers + security notice, plus homoglyph/whitespace-variant marker-spoof detection |
|
||||
| **Residual risk** | Medium - novel escapes discovered regularly |
|
||||
| **Recommendations** | Output-side validation in addition to input-side wrapping |
|
||||
|
||||
---
|
||||
|
||||
### 3.6 Discovery (AML.TA0008)
|
||||
|
||||
#### T-DISC-001: Tool enumeration
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ----------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0040 - AI Model Inference API Access |
|
||||
| **Description** | Attacker enumerates available tools through prompting |
|
||||
| **Attack vector** | "What tools do you have?" style queries |
|
||||
| **Affected components** | Agent tool registry |
|
||||
| **Current mitigations** | None specific |
|
||||
| **Residual risk** | Low - tools are generally documented |
|
||||
| **Recommendations** | Consider tool visibility controls |
|
||||
|
||||
#### T-DISC-002: Session data extraction
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0040 - AI Model Inference API Access |
|
||||
| **Description** | Attacker extracts sensitive data from session context |
|
||||
| **Attack vector** | "What did we discuss?" queries, context probing |
|
||||
| **Affected components** | Session transcripts, context window |
|
||||
| **Current mitigations** | Session isolation per sender (`agent:channel:peer` key) |
|
||||
| **Residual risk** | Medium - within-session data is accessible by design |
|
||||
| **Recommendations** | Sensitive-data redaction in context |
|
||||
|
||||
---
|
||||
|
||||
### 3.7 Collection and exfiltration (AML.TA0009, AML.TA0010)
|
||||
|
||||
#### T-EXFIL-001: Data theft via web_fetch
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | -------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0009 - Collection |
|
||||
| **Description** | Attacker exfiltrates data by instructing the agent to send it to an external URL |
|
||||
| **Attack vector** | Prompt injection causing the agent to POST data to an attacker server |
|
||||
| **Affected components** | `web_fetch` tool |
|
||||
| **Current mitigations** | SSRF blocking for internal/private networks (DNS pinning + IP blocking) |
|
||||
| **Residual risk** | High - arbitrary external URLs remain permitted |
|
||||
| **Recommendations** | URL allowlisting, data-classification awareness |
|
||||
|
||||
#### T-EXFIL-002: Unauthorized message sending
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | -------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0009 - Collection |
|
||||
| **Description** | Attacker causes the agent to send messages containing sensitive data |
|
||||
| **Attack vector** | Prompt injection causing the agent to message the attacker |
|
||||
| **Affected components** | Message tool, channel integrations |
|
||||
| **Current mitigations** | Outbound messaging gating |
|
||||
| **Residual risk** | Medium - gating may be bypassed |
|
||||
| **Recommendations** | Explicit confirmation for new recipients |
|
||||
|
||||
#### T-EXFIL-003: Credential harvesting
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0009 - Collection |
|
||||
| **Description** | Malicious skill harvests credentials from the agent context |
|
||||
| **Attack vector** | Skill code reads environment variables, config files |
|
||||
| **Affected components** | Skill execution environment |
|
||||
| **Current mitigations** | ClawHub credential-pattern scanning (hardcoded secrets, credential env access paired with network sends); no execution sandboxing for skills at runtime |
|
||||
| **Residual risk** | Critical - skills run with agent privileges |
|
||||
| **Recommendations** | Skill execution sandboxing, credential isolation |
|
||||
|
||||
---
|
||||
|
||||
### 3.8 Impact (AML.TA0011)
|
||||
|
||||
#### T-IMPACT-001: Unauthorized command execution
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0031 - Erode AI Model Integrity |
|
||||
| **Description** | Attacker executes arbitrary commands on the user system |
|
||||
| **Attack vector** | Prompt injection combined with exec approval bypass |
|
||||
| **Affected components** | Bash tool, command execution |
|
||||
| **Current mitigations** | Exec approvals, Docker sandbox option (default runtime backend) |
|
||||
| **Residual risk** | Critical - host execution possible when sandbox is disabled |
|
||||
| **Recommendations** | Improve approval UX; sandbox-off deployments remain a deliberate operator choice, documented as such |
|
||||
|
||||
#### T-IMPACT-002: Resource exhaustion (DoS)
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | -------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0031 - Erode AI Model Integrity |
|
||||
| **Description** | Attacker exhausts API credits or compute resources |
|
||||
| **Attack vector** | Automated message flooding, expensive tool calls |
|
||||
| **Affected components** | Gateway, agent sessions, API provider |
|
||||
| **Current mitigations** | None |
|
||||
| **Residual risk** | High - no per-sender rate limiting |
|
||||
| **Recommendations** | Per-sender rate limits, cost budgets |
|
||||
|
||||
#### T-IMPACT-003: Reputation damage
|
||||
|
||||
| Attribute | Value |
|
||||
| ----------------------- | ----------------------------------------------------------- |
|
||||
| **ATLAS ID** | AML.T0031 - Erode AI Model Integrity |
|
||||
| **Description** | Attacker causes the agent to send harmful/offensive content |
|
||||
| **Attack vector** | Prompt injection causing inappropriate responses |
|
||||
| **Affected components** | Output generation, channel messaging |
|
||||
| **Current mitigations** | LLM provider content policies |
|
||||
| **Residual risk** | Medium - provider filters are imperfect |
|
||||
| **Recommendations** | Output filtering layer, user controls |
|
||||
|
||||
---
|
||||
|
||||
## 4. ClawHub supply chain analysis
|
||||
|
||||
### 4.1 Current security controls
|
||||
|
||||
| Control | Implementation | Effectiveness |
|
||||
| ------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| GitHub account age | `requireGitHubAccountAge()` (14-day minimum) | Medium - raises the bar for new attackers |
|
||||
| Path sanitization | `sanitizePath()` | High - prevents path traversal |
|
||||
| File type validation | `isTextFile()` | Medium - only text files scanned, but still exploitable |
|
||||
| Size limits | 50MB total bundle (`MAX_PUBLISH_TOTAL_BYTES`) | High - prevents resource exhaustion |
|
||||
| Required SKILL.md | Mandatory readme on publish | Low security value - informational only |
|
||||
| Static + AST-adjacent scanning | Pattern engine covering exec, exfiltration, credential-harvest, obfuscation, and more | Medium-High - covers many known abuse patterns, still pattern-based |
|
||||
| LLM-based agentic risk review | Security-prompt-driven verdict on publish | Medium-High - catches behavior static patterns miss |
|
||||
| VirusTotal scanning | Wired to skill and package-release publish/rescan flows, gated on operator API key | High when enabled - static engine detection |
|
||||
| Moderation status | `moderationStatus` field | Medium - manual review possible |
|
||||
|
||||
### 4.2 Moderation limitations
|
||||
|
||||
ClawHub's static scanning inspects skill code content directly (not just slug/metadata/frontmatter), covering dangerous exec calls, dynamic code execution, credential harvesting, exfiltration patterns, obfuscated payloads, and more. Known gaps:
|
||||
|
||||
- Pattern-based detection can still be bypassed by sufficiently novel obfuscation.
|
||||
- LLM-based review and VirusTotal scanning depend on operator-side API keys/config being enabled.
|
||||
- No runtime execution sandbox isolates a skill from the agent's own privileges once installed.
|
||||
|
||||
### 4.3 Badges
|
||||
|
||||
Skills and packages carry moderator-assigned badges: `highlighted`, `official`, `deprecated`, `redactionApproved` (skills only). Community reporting (`skillReports`) and audit logging (`auditLogs`) back moderation workflows.
|
||||
|
||||
---
|
||||
|
||||
## 5. Risk matrix
|
||||
|
||||
### 5.1 Likelihood vs impact
|
||||
|
||||
| Threat ID | Likelihood | Impact | Risk level | Priority |
|
||||
| ------------- | ---------- | -------- | ------------ | -------- |
|
||||
| T-EXEC-001 | High | Critical | **Critical** | P0 |
|
||||
| T-PERSIST-001 | High | Critical | **Critical** | P0 |
|
||||
| T-EXFIL-003 | Medium | Critical | **Critical** | P0 |
|
||||
| T-IMPACT-001 | Medium | Critical | **High** | P1 |
|
||||
| T-EXEC-002 | High | High | **High** | P1 |
|
||||
| T-EXEC-004 | Medium | High | **High** | P1 |
|
||||
| T-ACCESS-003 | Medium | High | **High** | P1 |
|
||||
| T-EXFIL-001 | Medium | High | **High** | P1 |
|
||||
| T-IMPACT-002 | High | Medium | **High** | P1 |
|
||||
| T-EVADE-001 | High | Medium | **Medium** | P2 |
|
||||
| T-ACCESS-001 | Low | High | **Medium** | P2 |
|
||||
| T-ACCESS-002 | Low | High | **Medium** | P2 |
|
||||
| T-PERSIST-002 | Low | High | **Medium** | P2 |
|
||||
|
||||
### 5.2 Critical path attack chains
|
||||
|
||||
**Chain 1: Skill-based data theft**
|
||||
|
||||
```text
|
||||
T-PERSIST-001 → T-EVADE-001 → T-EXFIL-003
|
||||
(Publish malicious skill) → (Evade moderation) → (Harvest credentials)
|
||||
```
|
||||
|
||||
**Chain 2: Prompt injection to RCE**
|
||||
|
||||
```text
|
||||
T-EXEC-001 → T-EXEC-004 → T-IMPACT-001
|
||||
(Inject prompt) → (Bypass exec approval) → (Execute commands)
|
||||
```
|
||||
|
||||
**Chain 3: Indirect injection via fetched content**
|
||||
|
||||
```text
|
||||
T-EXEC-002 → T-EXFIL-001 → External exfiltration
|
||||
(Poison URL content) → (Agent fetches & follows instructions) → (Data sent to attacker)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Recommendations summary
|
||||
|
||||
### 6.1 Immediate (P0)
|
||||
|
||||
| ID | Recommendation | Addresses |
|
||||
| ----- | ------------------------------------------- | -------------------------- |
|
||||
| R-002 | Implement skill execution sandboxing | T-PERSIST-001, T-EXFIL-003 |
|
||||
| R-003 | Add output validation for sensitive actions | T-EXEC-001, T-EXEC-002 |
|
||||
|
||||
### 6.2 Short-term (P1)
|
||||
|
||||
| ID | Recommendation | Addresses |
|
||||
| ----- | --------------------------------------------------------------------- | ------------ |
|
||||
| R-004 | Implement per-sender rate limiting | T-IMPACT-002 |
|
||||
| R-005 | Add token encryption at rest | T-ACCESS-003 |
|
||||
| R-006 | Improve exec approval UX and continue expanding command normalization | T-EXEC-004 |
|
||||
| R-007 | Implement URL allowlisting for `web_fetch` | T-EXFIL-001 |
|
||||
|
||||
### 6.3 Medium-term (P2)
|
||||
|
||||
| ID | Recommendation | Addresses |
|
||||
| ----- | ----------------------------------------------------- | ------------- |
|
||||
| R-008 | Add cryptographic channel verification where possible | T-ACCESS-002 |
|
||||
| R-009 | Implement config integrity verification | T-PERSIST-003 |
|
||||
| R-010 | Add update signing and version pinning | T-PERSIST-002 |
|
||||
|
||||
---
|
||||
|
||||
## 7. Appendices
|
||||
|
||||
### 7.1 ATLAS technique mapping
|
||||
|
||||
| ATLAS ID | Technique name | OpenClaw threats |
|
||||
| ------------- | ------------------------------ | ---------------------------------------------------------------- |
|
||||
| AML.T0006 | Active Scanning | T-RECON-001, T-RECON-002 |
|
||||
| AML.T0009 | Collection | T-EXFIL-001, T-EXFIL-002, T-EXFIL-003 |
|
||||
| AML.T0010.001 | Supply Chain: AI Software | T-PERSIST-001, T-PERSIST-002 |
|
||||
| AML.T0010.002 | Supply Chain: Data | T-PERSIST-003 |
|
||||
| AML.T0031 | Erode AI Model Integrity | T-IMPACT-001, T-IMPACT-002, T-IMPACT-003 |
|
||||
| AML.T0040 | AI Model Inference API Access | T-ACCESS-001, T-ACCESS-002, T-ACCESS-003, T-DISC-001, T-DISC-002 |
|
||||
| AML.T0043 | Craft Adversarial Data | T-EXEC-004, T-EVADE-001, T-EVADE-002 |
|
||||
| AML.T0051.000 | LLM Prompt Injection: Direct | T-EXEC-001, T-EXEC-003 |
|
||||
| AML.T0051.001 | LLM Prompt Injection: Indirect | T-EXEC-002 |
|
||||
|
||||
### 7.2 Key security files
|
||||
|
||||
| Path | Purpose | Risk level |
|
||||
| ----------------------------------- | ------------------------------ | ------------ |
|
||||
| `src/infra/exec-approvals.ts` | Command approval logic | **Critical** |
|
||||
| `src/gateway/auth.ts` | Gateway authentication | **Critical** |
|
||||
| `src/infra/net/ssrf.ts` | SSRF protection | **Critical** |
|
||||
| `src/security/external-content.ts` | Prompt injection mitigation | **Critical** |
|
||||
| `src/agents/sandbox/tool-policy.ts` | Sandbox tool allow/deny policy | **Critical** |
|
||||
| `src/routing/resolve-route.ts` | Session isolation / routing | **Medium** |
|
||||
|
||||
### 7.3 Glossary
|
||||
|
||||
| Term | Definition |
|
||||
| -------------------- | --------------------------------------------------------- |
|
||||
| **ATLAS** | MITRE's Adversarial Threat Landscape for AI Systems |
|
||||
| **ClawHub** | OpenClaw's skill marketplace |
|
||||
| **Gateway** | OpenClaw's message routing and authentication layer |
|
||||
| **MCP** | Model Context Protocol - tool provider interface |
|
||||
| **Prompt injection** | Attack where malicious instructions are embedded in input |
|
||||
| **Skill** | Downloadable extension for OpenClaw agents |
|
||||
| **SSRF** | Server-Side Request Forgery |
|
||||
|
||||
---
|
||||
|
||||
_This threat model is a living document. Report security issues to `security@openclaw.ai` or see the [Trust page](https://trust.openclaw.ai)._
|
||||
|
||||
## Related
|
||||
|
||||
- [Contributing to the threat model](/security/CONTRIBUTING-THREAT-MODEL)
|
||||
- [Incident response](/security/incident-response)
|
||||
- [Network proxy](/security/network-proxy)
|
||||
- [Formal verification](/security/formal-verification)
|
||||
137
docs/security/formal-verification.md
Normal file
137
docs/security/formal-verification.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
summary: Machine-checked security models for OpenClaw's highest-risk paths.
|
||||
title: Formal verification (security models)
|
||||
read_when:
|
||||
- Reviewing formal security model guarantees or limits
|
||||
- Reproducing or updating TLA+/TLC security model checks
|
||||
permalink: /security/formal-verification/
|
||||
---
|
||||
|
||||
OpenClaw's formal security models (TLA+/TLC today) give a machine-checked argument that specific highest-risk paths — authorization, session isolation, tool gating, and misconfiguration safety — enforce their intended policy, under explicit stated assumptions.
|
||||
|
||||
> Note: some older links may refer to the previous project name.
|
||||
|
||||
## What this is
|
||||
|
||||
An executable, attacker-driven security regression suite:
|
||||
|
||||
- Each claim has a runnable model-check over a finite state space.
|
||||
- Many claims have a paired negative model that produces a counterexample trace for a realistic bug class.
|
||||
|
||||
This is **not** a proof that OpenClaw is secure in all respects, and it does not verify the full TypeScript implementation.
|
||||
|
||||
## Where the models live
|
||||
|
||||
Models are maintained in a separate repo: [vignesh07/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models).
|
||||
|
||||
<Note>
|
||||
That repository is currently unreachable (GitHub returns "Repository not found" as of this writing). If it is still broken for you, ask in the OpenClaw maintainer channels for the current location before assuming the models were removed.
|
||||
</Note>
|
||||
|
||||
## Caveats
|
||||
|
||||
- These are models, not the full TypeScript implementation — drift between model and code is possible.
|
||||
- Results are bounded by the state space TLC explores. Green does not imply security beyond the modeled assumptions and bounds.
|
||||
- Some claims rely on explicit environment assumptions (for example, correct deployment and correct configuration inputs).
|
||||
|
||||
## Reproducing results
|
||||
|
||||
Clone the models repo and run TLC:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/vignesh07/openclaw-formal-models
|
||||
cd openclaw-formal-models
|
||||
|
||||
# Java 11+ required (TLC runs on the JVM).
|
||||
# The repo vendors a pinned tla2tools.jar and provides bin/tlc plus Make targets.
|
||||
|
||||
make <target>
|
||||
```
|
||||
|
||||
There is no CI integration back into this repo yet; a future iteration could add CI-run models with public artifacts (counterexample traces, run logs) or a hosted "run this model" workflow for small bounded checks.
|
||||
|
||||
## Claims and targets
|
||||
|
||||
### Gateway exposure and open gateway misconfiguration
|
||||
|
||||
**Claim:** binding beyond loopback without auth can make remote compromise possible and increases exposure; a token/password blocks unauthenticated attackers, per the model's assumptions.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | ---------------------------------------------------------------- |
|
||||
| Green | `make gateway-exposure-v2`, `make gateway-exposure-v2-protected` |
|
||||
| Red (expected) | `make gateway-exposure-v2-negative` |
|
||||
|
||||
See also `docs/gateway-exposure-matrix.md` in the models repo.
|
||||
|
||||
### Node exec pipeline (highest-risk capability)
|
||||
|
||||
**Claim:** `exec host=node` requires (a) a node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay, in the model.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | --------------------------------------------------------------- |
|
||||
| Green | `make nodes-pipeline`, `make approvals-token` |
|
||||
| Red (expected) | `make nodes-pipeline-negative`, `make approvals-token-negative` |
|
||||
|
||||
### Pairing store (DM gating)
|
||||
|
||||
**Claim:** pairing requests respect TTL and pending-request caps.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | ---------------------------------------------------- |
|
||||
| Green | `make pairing`, `make pairing-cap` |
|
||||
| Red (expected) | `make pairing-negative`, `make pairing-cap-negative` |
|
||||
|
||||
### Ingress gating (mentions and control-command bypass)
|
||||
|
||||
**Claim:** in group contexts requiring mention, an unauthorized control command cannot bypass mention gating.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | ------------------------------ |
|
||||
| Green | `make ingress-gating` |
|
||||
| Red (expected) | `make ingress-gating-negative` |
|
||||
|
||||
### Routing and session-key isolation
|
||||
|
||||
**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked or configured.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | --------------------------------- |
|
||||
| Green | `make routing-isolation` |
|
||||
| Red (expected) | `make routing-isolation-negative` |
|
||||
|
||||
## v1++ models: concurrency, retries, trace correctness
|
||||
|
||||
Follow-on models that tighten fidelity around real-world failure modes: non-atomic updates, retries, and message fan-out.
|
||||
|
||||
### Pairing store concurrency and idempotency
|
||||
|
||||
**Claim:** the pairing store enforces `MaxPending` and idempotency even under interleavings — check-then-write must be atomic/locked, and refresh must not create duplicates. Concretely: concurrent requests cannot exceed `MaxPending` for a channel, and repeated requests/refreshes for the same `(channel, sender)` do not create duplicate live pending rows.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Green | `make pairing-race` (atomic/locked cap check), `make pairing-idempotency`, `make pairing-refresh`, `make pairing-refresh-race` |
|
||||
| Red (expected) | `make pairing-race-negative` (non-atomic begin/commit cap race), `make pairing-idempotency-negative`, `make pairing-refresh-negative`, `make pairing-refresh-race-negative` |
|
||||
|
||||
### Ingress trace correlation and idempotency
|
||||
|
||||
**Claim:** ingestion preserves trace correlation across fan-out and is idempotent under provider retries. When one external event becomes multiple internal messages, every part keeps the same trace/event identity; retries do not double-process; if provider event IDs are missing, dedupe falls back to a safe key (for example trace ID) to avoid dropping distinct events.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Green | `make ingress-trace`, `make ingress-trace2`, `make ingress-idempotency`, `make ingress-dedupe-fallback` |
|
||||
| Red (expected) | `make ingress-trace-negative`, `make ingress-trace2-negative`, `make ingress-idempotency-negative`, `make ingress-dedupe-fallback-negative` |
|
||||
|
||||
### Routing dmScope precedence and identityLinks
|
||||
|
||||
**Claim:** routing keeps DM sessions isolated by default and only collapses sessions when explicitly configured, via channel precedence and identity links. Channel-specific `dmScope` overrides win over global defaults; `identityLinks` collapse sessions only within explicit linked groups, not across unrelated peers.
|
||||
|
||||
| Result | Targets |
|
||||
| -------------- | ------------------------------------------------------------------------- |
|
||||
| Green | `make routing-precedence`, `make routing-identitylinks` |
|
||||
| Red (expected) | `make routing-precedence-negative`, `make routing-identitylinks-negative` |
|
||||
|
||||
## Related
|
||||
|
||||
- [Threat model](/security/THREAT-MODEL-ATLAS)
|
||||
- [Contributing to the threat model](/security/CONTRIBUTING-THREAT-MODEL)
|
||||
- [Incident response](/security/incident-response)
|
||||
57
docs/security/incident-response.md
Normal file
57
docs/security/incident-response.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
summary: "How OpenClaw triages, responds to, and follows up on security incidents"
|
||||
title: "Incident response"
|
||||
read_when:
|
||||
- Responding to a security report or suspected security incident
|
||||
- Preparing a coordinated disclosure or patched security release
|
||||
- Reviewing post-incident follow-up expectations
|
||||
---
|
||||
|
||||
## 1. Detection and triage
|
||||
|
||||
Security signals come from:
|
||||
|
||||
- GitHub Security Advisories (GHSA) and private vulnerability reports.
|
||||
- Public GitHub issues/discussions when reports are not sensitive.
|
||||
- Automated signals: Dependabot, CodeQL, npm advisories, secret scanning.
|
||||
|
||||
Initial triage:
|
||||
|
||||
1. Confirm affected component, version, and trust boundary impact.
|
||||
2. Classify as a security issue vs. hardening/no-action, using `SECURITY.md`'s scope and out-of-scope rules.
|
||||
3. An incident owner responds accordingly.
|
||||
|
||||
## 2. Severity
|
||||
|
||||
| Severity | Definition |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Critical | Package/release/repository compromise, active exploitation, or unauthenticated trust-boundary bypass with high-impact control or data exposure. |
|
||||
| High | Verified trust-boundary bypass requiring limited preconditions (for example, authenticated but unauthorized high-impact action), or exposure of OpenClaw-owned sensitive credentials. |
|
||||
| Medium | Significant security weakness with practical impact but constrained exploitability or substantial prerequisites. |
|
||||
| Low | Defense-in-depth findings, narrowly scoped denial-of-service, or hardening/parity gaps without a demonstrated trust-boundary bypass. |
|
||||
|
||||
## 3. Response
|
||||
|
||||
1. Acknowledge receipt to the reporter (privately when sensitive).
|
||||
2. Reproduce on supported releases and latest `main`, then implement and validate a patch with regression coverage.
|
||||
3. Critical/high: prepare patched release(s) as fast as practical.
|
||||
4. Medium/low: patch in the normal release flow and document mitigation guidance.
|
||||
|
||||
## 4. Communication and disclosure
|
||||
|
||||
Communicate through GitHub Security Advisories in the affected repository, release notes/changelog entries for fixed versions, and direct reporter follow-up on status and resolution.
|
||||
|
||||
Critical/high incidents get coordinated disclosure, with CVE issuance when appropriate. Low-risk hardening findings may be documented in release notes or advisories without a CVE, depending on impact and user exposure.
|
||||
|
||||
## 5. Recovery and follow-up
|
||||
|
||||
After shipping the fix:
|
||||
|
||||
1. Verify remediations in CI and release artifacts.
|
||||
2. Run a short post-incident review: timeline, root cause, detection gap, prevention plan.
|
||||
3. Add follow-up hardening/tests/docs tasks and track them to completion.
|
||||
|
||||
## Related
|
||||
|
||||
- [Security policy](https://github.com/openclaw/openclaw/blob/main/SECURITY.md) — report scope and trust model.
|
||||
- [Threat model](/security/THREAT-MODEL-ATLAS)
|
||||
221
docs/security/network-proxy.md
Normal file
221
docs/security/network-proxy.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
summary: "How to route OpenClaw runtime HTTP and WebSocket traffic through an operator-managed filtering proxy"
|
||||
title: "Network proxy"
|
||||
read_when:
|
||||
- You want defense-in-depth against SSRF and DNS rebinding attacks
|
||||
- Configuring an external forward proxy for OpenClaw runtime traffic
|
||||
---
|
||||
|
||||
OpenClaw can route runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This is optional defense in depth: central egress control, stronger SSRF protection, and destination auditability at the network boundary. Because the proxy evaluates the destination at connect time, after DNS resolution and immediately before it opens the upstream connection, it also narrows the gap a DNS-rebinding attack relies on between an earlier application-level DNS check and the actual outbound connection. A single proxy policy also gives operators one place to enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding OpenClaw.
|
||||
|
||||
OpenClaw does not ship, download, start, configure, or certify a proxy. You run the proxy technology that fits your environment; OpenClaw routes its own HTTP and WebSocket clients through it.
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
enabled: true
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
You can also set the URL through the environment while `proxy.enabled: true` stays in config:
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
```
|
||||
|
||||
`proxy.proxyUrl` takes precedence over `OPENCLAW_PROXY_URL`. If `proxy.enabled` is `true` but no valid URL resolves, protected commands fail startup rather than falling back to direct network access.
|
||||
|
||||
| Key | Type | Default | Notes |
|
||||
| -------------------- | ------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `proxy.enabled` | boolean | unset | Must be `true` to activate routing. |
|
||||
| `proxy.proxyUrl` | string | unset | `http://` or `https://` forward proxy URL. Credentials embedded in the URL are treated as sensitive and redacted from snapshots/logs. |
|
||||
| `proxy.tls.caFile` | string | unset | CA bundle for verifying an `https://` proxy endpoint signed by a private CA. |
|
||||
| `proxy.loopbackMode` | `gateway-only` \| `proxy` \| `block` | `gateway-only` | Controls loopback bypass behavior; see below. |
|
||||
|
||||
For managed gateway services, store the URL in config so it survives reinstall, rather than relying on foreground env:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
|
||||
openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
The `OPENCLAW_PROXY_URL` env fallback is best for foreground runs. To use it with an installed service, put it in the service's durable environment (`$OPENCLAW_STATE_DIR/.env`, default `~/.openclaw/.env`), then reinstall so launchd/systemd/Scheduled Tasks picks it up.
|
||||
|
||||
### HTTPS proxy endpoint with a private CA
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
enabled: true
|
||||
proxyUrl: https://proxy.corp.example:8443
|
||||
tls:
|
||||
caFile: /etc/openclaw/proxy-ca.pem
|
||||
```
|
||||
|
||||
`proxy.tls.caFile` verifies the proxy endpoint's own TLS certificate. It is not a destination MITM trust setting, a client certificate, or a substitute for the proxy's destination policy. Use `NODE_EXTRA_CA_CERTS` instead only when the entire Node process must trust an additional CA from startup (for example, an enterprise TLS-inspection system re-signing every HTTPS destination certificate) — that variable is process-global and must be set before Node starts, so OpenClaw cannot apply it mid-run the way it applies `proxy.tls.caFile`. Prefer `proxy.tls.caFile` for HTTPS proxy endpoint trust: it is scoped to managed proxy routing instead of the whole process.
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
openclaw config set proxy.proxyUrl https://proxy.corp.example:8443
|
||||
openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pem
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
## How routing works
|
||||
|
||||
With `proxy.enabled: true` and a valid URL, protected runtime processes (`openclaw gateway run`, `openclaw node run`, `openclaw agent --local`) route normal HTTP and WebSocket egress through the proxy:
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
fetch, node:http, node:https, WebSocket clients -> operator proxy -> destination
|
||||
```
|
||||
|
||||
Internally, OpenClaw installs [Proxyline](https://github.com/openclaw/proxyline) as the process-level routing runtime. It covers `fetch`, undici-backed clients, `node:http`/`node:https`, common WebSocket clients, and helper-created `CONNECT` tunnels, and it replaces caller-provided Node HTTP agents so explicit agents (including `axios`, `got`, `node-fetch`, and similar Node-agent-based clients) cannot silently bypass the proxy.
|
||||
|
||||
The proxy URL scheme describes the hop from OpenClaw to the proxy, not to the final destination:
|
||||
|
||||
- `http://proxy.example:3128` — plain TCP to the proxy; OpenClaw sends HTTP proxy requests, including `CONNECT` for HTTPS destinations.
|
||||
- `https://proxy.example:8443` — OpenClaw opens TLS to the proxy itself (verifying the proxy's certificate), then sends HTTP proxy requests inside that session.
|
||||
|
||||
Destination TLS is independent of proxy-endpoint TLS: for an HTTPS destination, OpenClaw always asks the proxy for a `CONNECT` tunnel and starts destination TLS through that tunnel.
|
||||
|
||||
While the proxy is active, OpenClaw clears `no_proxy`/`NO_PROXY`. Those bypass lists are destination-based; leaving `localhost` or `127.0.0.1` there would let SSRF targets skip the proxy entirely. On shutdown, OpenClaw restores the prior proxy environment and resets cached routing state.
|
||||
|
||||
Some plugins own a custom transport that needs its own proxy wiring even with process-level routing active. Telegram's Bot API client uses its own HTTP/1 undici dispatcher and separately honors process proxy env plus the `OPENCLAW_PROXY_URL` fallback.
|
||||
|
||||
### Gateway loopback mode
|
||||
|
||||
Local Gateway control-plane clients normally connect to a loopback WebSocket such as `ws://127.0.0.1:18789`. `proxy.loopbackMode` controls whether that traffic bypasses the managed proxy:
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
enabled: true
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
loopbackMode: gateway-only # gateway-only, proxy, or block
|
||||
```
|
||||
|
||||
| Mode | Behavior |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `gateway-only` (default) | OpenClaw registers the active Gateway loopback authority as a direct-connect exception, so local Gateway WebSocket traffic connects without the proxy. Custom loopback ports work because the exception targets the exact configured host/port. The bundled browser plugin registers the same kind of exception for the exact local CDP readiness and DevTools WebSocket URLs of OpenClaw-launched managed browsers; the bundled Ollama memory embedding provider has a narrower guarded direct path for its exact configured host-local loopback embedding origin. |
|
||||
| `proxy` | No loopback exceptions are registered; Gateway and Ollama loopback traffic goes through the proxy. A remote proxy must be able to route back to the OpenClaw host's loopback service (for example via a reachable hostname, IP, or tunnel) — a standard remote proxy resolves `127.0.0.1`/`localhost` against itself, not against the OpenClaw host. |
|
||||
| `block` | OpenClaw denies Gateway loopback control-plane connections and guarded Ollama loopback embedding connections before opening a socket. |
|
||||
|
||||
Gateway control-plane bypass is limited to `localhost` and literal loopback IP URLs — use `ws://127.0.0.1:18789`, `ws://[::1]:18789`, or `ws://localhost:18789`. Other hostnames route like ordinary traffic.
|
||||
|
||||
### Containers
|
||||
|
||||
For `openclaw --container ...` commands, OpenClaw forwards `OPENCLAW_PROXY_URL` into the container-targeted child CLI when it is set. The URL must be reachable from inside the container — `127.0.0.1` there refers to the container itself, not the host. OpenClaw rejects loopback proxy URLs for container-targeted commands unless you set `OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1` to explicitly override that check.
|
||||
|
||||
## Related proxy terms
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl` — outbound forward-proxy routing for runtime egress. This page.
|
||||
- `gateway.auth.mode: "trusted-proxy"` — inbound identity-aware reverse-proxy authentication for Gateway access. See [Trusted proxy auth](/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy` — local debug proxy and capture inspector for development and support. See [openclaw proxy](/cli/proxy).
|
||||
- `tools.web.fetch.useTrustedEnvProxy` — opt-in for `web_fetch` to let an operator-controlled HTTP(S) env proxy resolve DNS while keeping strict DNS pinning and hostname policy by default. See [Web fetch](/tools/web-fetch#trusted-env-proxy).
|
||||
- Channel- or provider-specific proxy settings — owner-specific overrides for one transport. Prefer the managed network proxy for central egress control across the runtime.
|
||||
|
||||
## Validating the proxy
|
||||
|
||||
The proxy's destination policy is the actual security boundary; OpenClaw cannot verify that your proxy blocks the right targets. Configure it to:
|
||||
|
||||
- Bind only to loopback or a private trusted interface, reachable only by the OpenClaw process/host/container/service account.
|
||||
- Resolve destinations itself and block by IP after DNS resolution, at connect time, for both plain HTTP and HTTPS `CONNECT` tunnels.
|
||||
- Reject destination-based bypasses for loopback, private, link-local, metadata, multicast, reserved, and documentation ranges.
|
||||
- Avoid hostname allowlists unless you fully trust the DNS resolution path.
|
||||
- Log destination, decision, status, and reason — never request bodies, authorization headers, cookies, or other secrets.
|
||||
- Keep the policy under version control and review changes as security-sensitive.
|
||||
|
||||
Validate from the same host/container/service account that runs OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
With a private-CA HTTPS proxy endpoint:
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
| ------------------------ | -------------------------------------------------------------------- |
|
||||
| `--proxy-url <url>` | Validate this URL instead of resolving config/env. |
|
||||
| `--proxy-ca-file <path>` | CA bundle for an HTTPS proxy endpoint. |
|
||||
| `--allowed-url <url>` | Destination expected to succeed (repeatable). |
|
||||
| `--denied-url <url>` | Destination expected to be blocked (repeatable). |
|
||||
| `--apns-reachable` | Also verify the proxy can tunnel a direct sandbox APNs HTTP/2 probe. |
|
||||
| `--apns-authority <url>` | Override the APNs authority probed with `--apns-reachable`. |
|
||||
| `--timeout-ms <ms>` | Per-request timeout. |
|
||||
| `--json` | Machine-readable output. |
|
||||
|
||||
If `proxy.enabled` is not `true` and no `--proxy-url` is given, the command reports a config problem instead of validating; pass `--proxy-url` for a one-off preflight before changing config.
|
||||
|
||||
With no `--allowed-url`/`--denied-url`, the default checks are: `https://example.com/` must succeed, and a temporary loopback canary server the proxy must not reach must be blocked. The loopback check passes on a transport failure, or on a non-2xx response that lacks the canary's per-run token; it fails on a 2xx response missing the token (an unexpected success from something other than the canary) and, especially, on any response carrying the matching token, since that proves the proxy actually forwarded a loopback destination it should have denied. Custom `--denied-url` targets have no such canary token, so they are fail-closed: any HTTP response counts as reachable (fail), and a transport error is reported as inconclusive rather than proven-blocked, because OpenClaw cannot confirm your proxy denied a reachable origin versus something else going wrong. `--apns-reachable` sends an intentionally invalid provider token, so a `403 InvalidProviderToken` response counts as proof the tunnel reached Apple. The command exits `1` on any validation failure; proxy URL credentials are redacted from both text and JSON output.
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"config": {
|
||||
"enabled": true,
|
||||
"proxyUrl": "http://127.0.0.1:3128/",
|
||||
"source": "override",
|
||||
"errors": []
|
||||
},
|
||||
"checks": [
|
||||
{ "kind": "allowed", "url": "https://example.com/", "ok": true, "status": 200 },
|
||||
{ "kind": "apns", "url": "https://api.sandbox.push.apple.com", "ok": true, "status": 403 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Manual `curl` check (the public request should succeed; the loopback and metadata requests should be blocked by the proxy itself — `curl` alone cannot distinguish a proxy denial from an unreachable origin the way `openclaw proxy validate`'s built-in canary can):
|
||||
|
||||
```bash
|
||||
curl -x http://127.0.0.1:3128 https://example.com/
|
||||
curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
## Recommended blocked destinations
|
||||
|
||||
Starting denylist for any forward proxy, firewall, or egress policy. OpenClaw's own SSRF classifier lives in `src/infra/net/ssrf.ts` and `packages/net-policy/src/ip.ts` (`BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, the RFC 2544 benchmark prefix, and embedded-IPv4 handling for NAT64/6to4/Teredo/ISATAP/IPv4-mapped forms) — useful references, but OpenClaw does not export or enforce these rules in your external proxy.
|
||||
|
||||
| Range or host | Why to block |
|
||||
| ------------------------------------------------------------------------------------ | ------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | Unspecified / this-network addresses |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC 1918 private networks |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Link-local, including common cloud metadata paths |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Cloud metadata services |
|
||||
| `100.64.0.0/10` | Carrier-grade NAT shared address space |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Benchmarking ranges |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-use and documentation ranges |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | Reserved IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | IPv6 local/private ranges |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 discard and ORCHIDv2 ranges |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | NAT64 prefixes with embedded IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 and Teredo with embedded IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4-compatible and IPv4-mapped IPv6 |
|
||||
|
||||
Add any additional metadata hosts or reserved ranges your cloud provider or network platform documents.
|
||||
|
||||
## Limits
|
||||
|
||||
| Surface | Managed proxy status |
|
||||
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `fetch`, `node:http`, `node:https`, common WebSocket clients | Routed through managed proxy hooks when configured. |
|
||||
| APNs direct HTTP/2 | Routed through the APNs managed `CONNECT` helper. |
|
||||
| Gateway control-plane loopback | Direct only for the exact configured local loopback Gateway URL. |
|
||||
| Debug proxy upstream forwarding | Disabled while managed proxy mode is active unless explicitly enabled for local diagnostics. |
|
||||
| IRC | Raw TCP/TLS; not proxied by managed HTTP proxy mode. Set `channels.irc.enabled: false` if your deployment requires all egress through the forward proxy. |
|
||||
| Other raw `net`, `tls`, or `http2` client calls | Must be classified by the raw socket guard before landing. |
|
||||
|
||||
- This is process-level coverage for JavaScript HTTP/WebSocket clients, not an OS-level network sandbox.
|
||||
- Raw `net`, `tls`, `http2` sockets, native addons, and non-OpenClaw child processes may bypass Node-level routing unless they inherit and respect proxy environment variables. Forked OpenClaw child CLIs inherit the managed proxy URL and `proxy.loopbackMode` state.
|
||||
- User local WebUIs and local model servers are not covered by a general local-network bypass — allowlist them in the operator proxy policy if needed. The exception is the bundled Ollama memory embedding provider's guarded direct path, scoped to the exact host-local loopback origin from its configured `baseUrl`; LAN, tailnet, private-network, and public Ollama hosts still use the managed proxy.
|
||||
- The local debug proxy's direct upstream forwarding (for proxy requests and `CONNECT` tunnels) is disabled by default while managed proxy mode is active; enable it only for approved local diagnostics.
|
||||
- OpenClaw does not inspect, test, or certify your proxy policy. Treat proxy policy changes as security-sensitive operational changes.
|
||||
Reference in New Issue
Block a user