From 4de75e70d44da06eb49d1a73c7f8195d78b2d0fb Mon Sep 17 00:00:00 2001 From: rookiestar28 Date: Tue, 28 Apr 2026 20:33:58 +0800 Subject: [PATCH] docs: refresh public runtime and security documentation --- README.md | 38 +++++++++++++------------ docs/SECURITY.md | 23 +++++++++------ docs/connector.md | 1 + docs/release/api_contract.md | 19 +++++++------ docs/release/config_secrets_contract.md | 3 +- docs/release/recent_updates.md | 10 +++++++ docs/release/threat_model.md | 4 +-- 7 files changed, 60 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 342e0c7..bd5d2c0 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ This project is designed to make **ComfyUI a reliable automation target** with a - Secret handling stays server-side: browser storage is not used for secrets, local secret-manager integration is opt-in, and secrets-at-rest / token lifecycle controls are treated as operational boundaries. - Multi-tenant mode is isolation-first: tenant mismatches fail closed across config, secret sources, connector installations, approvals, visibility, and execution budgets. - Connector multi-workspace and multi-account bindings are secret-ref-only and fail-closed by design, so tenant/binding mismatches degrade to explicit rejection paths instead of silently reusing the wrong installation context. -- Operator-facing payloads default to redaction for provider reasoning-like content, while audit trails, diagnostics, and runtime guardrails remain explicit and tamper-evident. +- Operator-facing and audit payloads default to redaction for provider reasoning-like content and explicitly marked internal maintenance/helper prompt material, while diagnostics and runtime guardrails remain explicit and tamper-evident. - Verification is part of the security model: route drift checks, coverage governance, adversarial gates, and doctor/compatibility diagnostics are all wired into CI-parity workflows. Deployment profiles and hardening references: @@ -79,7 +79,7 @@ Deployment profiles and hardening references: - [Security Checklist](docs/security_checklist.md) - [Runtime Hardening and Startup](docs/runtime_hardening_and_startup.md) - [Threat Model](docs/release/threat_model.md) -- [R69 Frontend Migration Decision](docs/r69_ui_framework_migration_decision.md) +- [Frontend Migration Decision](docs/r69_ui_framework_migration_decision.md) @@ -89,6 +89,16 @@ Deployment profiles and hardening references:
+Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime + +- Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability. +- Connector/service launch planning now has a secret-blind env-backed SecretRef boundary that preserves supported connector credential references without expanding raw token values, while rejecting raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens. +- Operator-visible and audit payload sanitization now removes explicitly marked internal maintenance/helper prompt content before normal reasoning redaction, while leaving ordinary user text intact. + +
+ +
+ Host compatibility anchors and inactive-branch preflight diagnostics aligned with current ComfyUI hosts - Refreshed the published compatibility matrix for current ComfyUI, standalone frontend, and desktop reference anchors, keeping desktop embedded-frontend lag explicit instead of assuming standalone-frontend parity. @@ -134,17 +144,6 @@ Deployment profiles and hardening references:
-
- -Output contract, outbound egress handling, Security Doctor structure, and audit verification tooling aligned with the current runtime - -- Kept `/history` + `/view` as the supported runtime output contract for current operator flows, and made asset-service-only refs stay explicit as a bounded fallback state instead of silently guessing a direct `/api/assets` fetch path. -- Consolidated outbound safe HTTP execution behind one shared `safe_io` executor seam so local-provider checks, connector callbacks, and redirect handling now follow the same SSRF-safe validation, pinning, and redirect re-check rules. -- Split Security Doctor internals into focused endpoint, runtime, connector, report, and remediation modules while keeping the operator-facing doctor API and remediation workflow unchanged. -- Added retained audit-chain verification tooling, including a persisted `audit.log.key` sidecar when no environment key is provided, so operators can verify the current audit log plus retained rotations after restart or log rotation. - -
- See full update history: [docs/release/recent_updates.md](docs/release/recent_updates.md) @@ -212,7 +211,7 @@ Notes: - Recommended: set API keys via environment variables. - Optional: for single-user localhost setups, you can store a provider API key from the Settings tab (UI Key Store (Advanced)). - - This writes to the server-side secret store (`{STATE_DIR}/secrets.json`). + - This writes to the encrypted server-side secret store (`{STATE_DIR}/secrets.enc.json`). - Environment variables always take priority over stored keys. - Built-in local-provider defaults use loopback-only OpenAI-compatible URLs: - `Ollama (Local)` -> `http://127.0.0.1:11434/v1` @@ -469,7 +468,7 @@ Main API families: - Observability: health, capabilities, logs, traces, event feeds - Admin diagnostics: preflight inventory snapshot/status, doctor-facing readiness views - Config + LLM: effective config, provider tests, model lists, assist planner/refiner -- Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, and extraction seam metadata +- Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, extraction seam metadata, and static service-env SecretRef propagation policy - Webhooks + events: validate, submit, callback delivery, SSE/polling status - Admin operations: approvals, schedules, presets, rewrite recipes - Model Manager + Packs: search, download/import lifecycle, pack import/export @@ -485,10 +484,10 @@ Primary references: Key operational notes: -- Observability remains token-gated for remote access and redacts provider reasoning-like content by default. +- Observability remains token-gated for remote access and redacts provider reasoning-like content plus marked internal maintenance/helper content by default. - Event/model-download polling and preflight inventory are snapshot/cursor-driven contracts; clients should consume `snapshot_ts`, `scan_state`, `stale`, and cursor metadata instead of assuming full-refresh polling. - Output/history-facing consumers should keep using the bounded `/history` + `/view` contract; refs that only upstream asset services can resolve remain explicit `asset_api_required` compatibility states. -- Connector diagnostics expose redacted token references only, and `/openclaw/connector/extraction-contract` is structural packaging metadata rather than a live installation-health feed. +- Connector diagnostics expose redacted token references only, and `/openclaw/connector/extraction-contract` is structural packaging metadata and static SecretRef policy rather than a live installation-health, environment, or token-status feed. ## Advanced Security and Runtime Setup @@ -676,7 +675,10 @@ The connector currently remains an **optional attached subsystem inside this rep - **Slack multi-workspace and interactive mode**: Workspace installs can be handled through connector-managed OAuth install/callback routes with per-workspace token binding, fail-closed health diagnostics, and signed interactive callback handling for action payloads. - **Feishu/Lark multi-account mode**: Connector-managed account/workspace bindings support tenant-aware installation resolution, interactive approval cards, and signed callback handling without exposing raw app secrets or widening command trust implicitly. - **Bounded connector numeric envs**: Delivery/media/time-budget settings, bind ports, rate limits, and command-length knobs now clamp or fall back to documented defaults with warnings instead of crashing connector startup on malformed values. -- **Packaging diagnostics**: Admin operators/maintainers can inspect `/openclaw/connector/extraction-contract` for the current in-repo recommendation plus the minimum seam families required before any future split. +- **Startup diagnostics**: `/openclaw/health` reports startup readiness, optional warmup degradation, and fatal startup details without making optional warmups block baseline API availability. +- **SecretRef service boundaries**: Connector service-env planning preserves only supported env-backed credential references and rejects raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens. +- **Internal prompt isolation**: Operator-visible and audit payloads remove explicitly marked internal maintenance/helper prompt content before normal reasoning redaction. +- **Packaging diagnostics**: Admin operators/maintainers can inspect `/openclaw/connector/extraction-contract` for the current in-repo recommendation, the static service-env SecretRef propagation policy, and the minimum seam families required before any future split. - [See Setup Guide (`docs/connector.md`)](docs/connector.md) diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 4d129b5..6a5e2ae 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -2,9 +2,9 @@ ## Quick Links -- Deployment profiles and checklists: [Security Deployment Guide](docs/security_deployment_guide.md) -- Runtime startup hardening behavior: [Runtime Hardening and Startup](docs/runtime_hardening_and_startup.md) -- Pre-exposure checklist: [Security Checklist](docs/security_checklist.md) +- Deployment profiles and checklists: [Security Deployment Guide](security_deployment_guide.md) +- Runtime startup hardening behavior: [Runtime Hardening and Startup](runtime_hardening_and_startup.md) +- Pre-exposure checklist: [Security Checklist](security_checklist.md) - Deployment self-check command: - `python scripts/check_deployment_profile.py --profile local|lan|public` @@ -21,7 +21,7 @@ Only the latest version of ComfyUI-OpenClaw is supported for security updates. Please report security vulnerabilities by creating a **private** issue on GitHub if possible, or contact the maintainers directly. Do not open public issues for sensitive security flaws. -### Disclosure Workflow and SLA (S48) +### Disclosure Workflow and SLA Private reporting workflow: 1. Submit a private report with repro steps, affected version, and impact. @@ -103,15 +103,20 @@ export OPENCLAW_ADMIN_TOKEN="your-secure-random-admin-token-here" Then configure your proxy or client to send the header `X-OpenClaw-Obs-Token: your-secure-random-token-here` (legacy: `X-Moltbot-Obs-Token`). -### 1.1 Reasoning Debug Reveal Boundary (Local-only) +### 1.1 Reasoning and Internal Content Redaction Boundary -Operator-facing payloads strip provider reasoning / thinking traces by default across: +Operator-facing payloads strip provider reasoning / thinking traces and explicitly marked internal maintenance/helper prompt content by default across: - assist responses - event / SSE payloads - trace responses - callback payloads - connector trace/debug replies +- audit event payload/meta fields + +Internal maintenance/helper prompt content has no public or debug reveal path. Privileged reasoning reveal is limited to provider reasoning / thinking traces only. + +### 1.2 Reasoning Debug Reveal Boundary (Local-only) There is a privileged local-debug reveal path for troubleshooting, but it is fail-closed unless **all** of the following are true: @@ -142,7 +147,7 @@ export OPENCLAW_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8" # export MOLTBOT_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8" ``` -### 3. Public Profile Boundary Acknowledgement (S69) +### 3. Public Profile Boundary Acknowledgement For public profile deployments, you must explicitly acknowledge that reverse-proxy path controls and network ACL boundaries are already enforced: @@ -220,7 +225,7 @@ Operational note: - this path remains backend-only; frontend surfaces stay secret-blind. -### 5. Startup Gate Behavior (R136 + S56) +### 5. Startup Gate Behavior Startup security gates are fail-closed. Fatal startup gate/bootstrap failures abort route/worker registration and do not continue in a partial state. @@ -283,7 +288,7 @@ OpenClaw enforces internal rate limits: ### 8. Sidecar Bridge -OpenClaw supports a "Sidecar Bridge" (F10) for safe interaction with external bots (Discord/Slack). +OpenClaw supports a "Sidecar Bridge" for safe interaction with external bots (Discord/Slack). * **Default**: **DISABLED**. * **Enable**: Set `OPENCLAW_BRIDGE_ENABLED=1` (legacy `MOLTBOT_BRIDGE_ENABLED=1`). diff --git a/docs/connector.md b/docs/connector.md index ed5c580..b766f2a 100644 --- a/docs/connector.md +++ b/docs/connector.md @@ -45,6 +45,7 @@ Admin diagnostics APIs: Extraction diagnostics note: - `/openclaw/connector/extraction-contract` is an admin-only structural metadata route for maintainers and operators. It returns the current packaging recommendation, candidate extraction options, seam families, and blockers, but it does **not** expose live token or installation-state details beyond the existing diagnostics routes above. +- The extraction contract also includes the static service-env SecretRef propagation policy. It is not a live environment dump and does not expose token values. Slack multi-workspace notes: diff --git a/docs/release/api_contract.md b/docs/release/api_contract.md index 41fe0eb..9cffa28 100644 --- a/docs/release/api_contract.md +++ b/docs/release/api_contract.md @@ -1,12 +1,12 @@ # OpenClaw API Contract (v1) > **Status**: normative -> **Version**: 1.0.8 -> **Date**: 2026-04-26 +> **Version**: 1.0.9 +> **Date**: 2026-04-28 This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies. -## 0. Tenant Boundary Context (S49) +## 0. Tenant Boundary Context Default behavior remains single-tenant compatible (`tenant_id=default`). @@ -51,7 +51,8 @@ All new integrations should use the `/openclaw/` prefix. Use of `/moltbot/` is d Reasoning-content redaction contract: -- operator-visible trace and events payloads strip provider reasoning / thinking-like fields by default +- operator-visible trace and events payloads strip provider reasoning / thinking-like fields and explicitly marked internal maintenance/helper content by default +- audit event payload/meta fields follow the same internal-content and reasoning-like redaction boundary before retention - privileged reveal is opt-in only and requires: - request header `X-OpenClaw-Debug-Reveal-Reasoning: 1` or query `debug_reasoning=1` - server-side enablement via `OPENCLAW_DEBUG_REASONING_REVEAL=1` @@ -60,6 +61,7 @@ Reasoning-content redaction contract: - non-hardened runtime profile - deployment profile `local` or `lan` - clients MUST treat reveal behavior as debug-only and MUST NOT depend on reasoning payload presence in normal operation +- explicitly marked internal maintenance/helper content has no public or debug reveal path Inventory diagnostics contract: @@ -98,8 +100,9 @@ Preflight workflow diagnostics contract: Assist payload redaction contract: -- structured assist responses preserve final operator-visible answer fields but strip provider reasoning / chain-of-thought style fields by default +- structured assist responses preserve final operator-visible answer fields but strip provider reasoning / chain-of-thought style fields and explicitly marked internal maintenance/helper content by default - when the privileged reveal gate is allowed, debug reasoning is exposed only in a separate debug payload and not merged back into the normal structured answer fields +- explicitly marked internal maintenance/helper content is not exposed by the privileged reasoning reveal gate ### 1.3B Connector Installation Diagnostics @@ -112,13 +115,13 @@ Assist payload redaction contract: | `GET` | `/connector/installations/{installation_id}` | `/moltbot/connector/installations/{installation_id}` | Admin | Get one redacted connector installation record. | | `GET` | `/connector/installations/resolve` | `/moltbot/connector/installations/resolve` | Admin | Run fail-closed workspace resolution diagnostics (`platform`, `workspace_id`). | | `GET` | `/connector/installations/audit` | `/moltbot/connector/installations/audit` | Admin | List installation lifecycle audit evidence (redacted). | -| `GET` | `/connector/extraction-contract` | `/moltbot/connector/extraction-contract` | Admin | Get the machine-readable connector extraction recommendation, seam families, and current blockers. | +| `GET` | `/connector/extraction-contract` | `/moltbot/connector/extraction-contract` | Admin | Get the machine-readable connector extraction recommendation, seam families, static service-env SecretRef propagation policy, and current blockers. | Connector diagnostics contract notes: - installation records may expose operator-safe health metadata under `installation.metadata.health` (for example `ok`, `invalid_token`, `revoked`, `degraded`) without exposing token material - `/connector/installations` diagnostics may include aggregate `health_counts` in addition to lifecycle `status_counts` - `/connector/installations/resolve` may expose a stable `health_code` alongside the legacy `reject_reason` so clients can distinguish `workspace_unbound` vs token-health failures without parsing status text -- `/connector/extraction-contract` is structural packaging metadata only; clients MUST NOT treat it as a live installation-health or token-status feed +- `/connector/extraction-contract` is structural packaging metadata and static service-env SecretRef policy only; clients MUST NOT treat it as a live installation-health, live environment dump, or token-status feed ### 1.3C Model Management & Installations @@ -260,7 +263,7 @@ Tenant-boundary error notes: - `error` - `keepalive` - Clients MUST treat `final` as the source of truth for structured assist results. `delta` preview text is best-effort and may be truncated or differ from the final parsed payload. -- Event-stream and polling payloads redact provider reasoning / thinking traces by default; reveal is debug-only and gated by the same privileged local-debug contract used by trace/assist surfaces. +- Event-stream and polling payloads redact provider reasoning / thinking traces and explicitly marked internal maintenance/helper content by default; reasoning reveal is debug-only and gated by the same privileged local-debug contract used by trace/assist surfaces. - Clients SHOULD gracefully fall back to non-streaming assist endpoints when streaming capability is absent or streaming transport fails. ### 2.4 Pagination & Scan Diagnostics (Management Query Contract) diff --git a/docs/release/config_secrets_contract.md b/docs/release/config_secrets_contract.md index 985bd7d..009e27f 100644 --- a/docs/release/config_secrets_contract.md +++ b/docs/release/config_secrets_contract.md @@ -31,7 +31,7 @@ Controls the core LLM client used by nodes (Planner, Refiner, etc.). | `OPENCLAW_LLM_BASE_URL` | No | Provider default | Override base URL (crucial for local/compatible providers). | | `OPENCLAW_LLM_TIMEOUT`| No | `120` | Request timeout in seconds. | -Optional local secret-manager path (S11, disabled by default): +Optional local secret-manager path (disabled by default): | Variable | Required | Default | Description | | :--- | :--- | :--- | :--- | @@ -167,6 +167,7 @@ Connector posture rules: - Public deployment profile check surfaces this as `DP-PUBLIC-009`. - Slack multi-workspace installs persist only encrypted token refs in `connector_installations.json`; raw bot/app tokens remain in encrypted secret storage and must not appear in diagnostics or exported config surfaces. - Feishu/Lark bindings persist normalized installation identity plus secret references only; app secrets and callback signing material must stay in encrypted/local secret storage and must not appear in diagnostics or exported config surfaces. +- Connector service-env propagation preserves only structured env-backed SecretRef metadata for supported connector credential variables. It reports secret-blind status/reason fields and rejects raw secrets, legacy marker strings, unsupported env names, missing envs, and runtime-only auth tokens such as admin, worker, and bridge tokens. Raw token values must not be written into diagnostics or service metadata. - Connector bind-port envs (`OPENCLAW_CONNECTOR_LINE_PORT`, `...WHATSAPP_PORT`, `...WECHAT_PORT`, `...KAKAO_PORT`, `...SLACK_PORT`, `...FEISHU_PORT`) must stay within `1..65535`; invalid or out-of-range values fall back to the documented platform defaults instead of crashing startup. **Delivery & Media:** diff --git a/docs/release/recent_updates.md b/docs/release/recent_updates.md index b00c790..4c1fbb7 100644 --- a/docs/release/recent_updates.md +++ b/docs/release/recent_updates.md @@ -7,6 +7,16 @@ Newest entries appear first.
+Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime + +- Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability. +- Connector/service launch planning now has a secret-blind env-backed SecretRef boundary that preserves supported connector credential references without expanding raw token values, while rejecting raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens. +- Operator-visible and audit payload sanitization now removes explicitly marked internal maintenance/helper prompt content before normal reasoning redaction, while leaving ordinary user text intact. + +
+ +
+ Host compatibility anchors and inactive-branch preflight diagnostics aligned with current ComfyUI hosts - Refreshed the published compatibility matrix for current ComfyUI, standalone frontend, and desktop reference anchors, keeping desktop embedded-frontend lag explicit instead of assuming standalone-frontend parity. diff --git a/docs/release/threat_model.md b/docs/release/threat_model.md index 2918db3..5133545 100644 --- a/docs/release/threat_model.md +++ b/docs/release/threat_model.md @@ -18,7 +18,7 @@ Operators should use this to understand the risks of deployment. * **Access**: Read-only logs (`/openclaw/logs/tail`), config (`/openclaw/config`), health. * **Mechanism**: `OPENCLAW_OBSERVABILITY_TOKEN`. * **Redaction**: Logs/Config are redacted by default to prevent secret leakage. -* **Reasoning-content posture**: provider reasoning / thinking traces are stripped by default from operator-visible assist responses, event streams, trace responses, callback payloads, and connector trace replies; privileged reveal is local-debug only, admin-gated, auditable, and fail-closed outside permissive local posture. +* **Reasoning/internal-content posture**: provider reasoning / thinking traces and explicitly marked internal maintenance/helper prompt content are stripped by default from operator-visible assist responses, event streams, trace responses, callback payloads, connector trace replies, and audit event payload/meta fields. Privileged reasoning reveal is local-debug only, admin-gated, auditable, and fail-closed outside permissive local posture; internal maintenance/helper prompt content has no public or debug reveal path. ### 3. The "Connector" Boundary (ChatOps) @@ -50,7 +50,7 @@ Operators should use this to understand the risks of deployment. * *Mitigation*: Known-host allowlist by default. Custom URLs need explicit opt-in + DNS validation. * **Callback Delivery**: `POST` results to webhook targets. * *Risk*: SSRF / Information Leakage. - * *Mitigation*: DNS-safe validation (no private IPs) + operator-payload redaction, including reasoning-content stripping by default. + * *Mitigation*: DNS-safe validation (no private IPs) + operator-payload redaction, including reasoning/internal-content stripping by default. * **Image Fetching**: `image_url` inputs. * *Mitigation*: SafeIO module (size limits, no file://).