diff --git a/GENERATION.md b/GENERATION.md index b164c52..fb37ba5 100644 --- a/GENERATION.md +++ b/GENERATION.md @@ -1,9 +1,9 @@ # Wiki Generation Metadata -- Commit hash: `448aed326192d38812cb508820f967cb74e77ae9` -- Branch name: `main` -- Generation timestamp (local): `2026-02-25T20:59:57+0200` -- Generation mode: `initial` +- Commit hash: `d5aadfbee15b48ebb4872dfb838e4df88c611d56` +- Branch name: `codex/wiki-tab-ui` +- Generation timestamp (local): `2026-02-26T09:16:02+0200` +- Generation mode: `update` - Output language: `English` - Assets copied into `wiki/assets/`: - `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`) @@ -11,8 +11,8 @@ - `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`) ## Notes -- This is a first-time generation (`wiki/` did not exist before this run). -- Index sections were generated from repository structure and created wiki pages. +- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages. +- Updated index and cross-links to use `wiki/` as the documentation source of truth. - Future updates should preserve existing headings and append `Update Notes` sections when making deltas. ## Source References @@ -24,3 +24,8 @@ - wiki/dependencies.md - wiki/data-flow.md - wiki/glossary.md +- wiki/security-signing-runbook.md +- wiki/migration-signed-feed.md +- wiki/platform-verification.md +- wiki/remediation-plan.md +- wiki/compatibility-report.md diff --git a/Home.md b/Home.md index 7a59ed7..78be0fa 100644 --- a/Home.md +++ b/Home.md @@ -5,7 +5,7 @@ - Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines. - Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`. - Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing. -- How to navigate: Use Guides for cross-cutting concerns, Modules for implementation boundaries, and Source References at the end of each page to jump into code. +- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code. ## Start Here - [Overview](overview.md) @@ -19,6 +19,13 @@ - [Workflow](workflow.md) - [Security](security.md) +## Operations +- [Security Signing Runbook](security-signing-runbook.md) +- [Signed Feed Migration Plan](migration-signed-feed.md) +- [Platform Verification Checklist](platform-verification.md) +- [Cross-Platform Remediation Plan](remediation-plan.md) +- [Cross-Platform Compatibility Report](compatibility-report.md) + ## Modules - [Frontend Web App](modules/frontend-web.md) - [ClawSec Suite Core](modules/clawsec-suite.md) @@ -32,6 +39,9 @@ ## Generation Metadata - [Generation Metadata](GENERATION.md) +## Update Notes +- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages. + ## Source References - README.md - App.tsx diff --git a/INDEX.md b/INDEX.md index 7a59ed7..78be0fa 100644 --- a/INDEX.md +++ b/INDEX.md @@ -5,7 +5,7 @@ - Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines. - Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`. - Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing. -- How to navigate: Use Guides for cross-cutting concerns, Modules for implementation boundaries, and Source References at the end of each page to jump into code. +- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code. ## Start Here - [Overview](overview.md) @@ -19,6 +19,13 @@ - [Workflow](workflow.md) - [Security](security.md) +## Operations +- [Security Signing Runbook](security-signing-runbook.md) +- [Signed Feed Migration Plan](migration-signed-feed.md) +- [Platform Verification Checklist](platform-verification.md) +- [Cross-Platform Remediation Plan](remediation-plan.md) +- [Cross-Platform Compatibility Report](compatibility-report.md) + ## Modules - [Frontend Web App](modules/frontend-web.md) - [ClawSec Suite Core](modules/clawsec-suite.md) @@ -32,6 +39,9 @@ ## Generation Metadata - [Generation Metadata](GENERATION.md) +## Update Notes +- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages. + ## Source References - README.md - App.tsx diff --git a/compatibility-report.md b/compatibility-report.md new file mode 100644 index 0000000..458ee85 --- /dev/null +++ b/compatibility-report.md @@ -0,0 +1,111 @@ +# Cross-Platform Compatibility Report + +## 1) Executive Summary + +### Overall status by OS +- Linux: **Good**, primary workflows validated; still some POSIX-only scripts/docs. +- macOS: **Good**, with caveats around POSIX tool availability and Homebrew-specific assumptions. +- Windows: **Partial**, Node/Python pieces work, but many shell-first install/release workflows still require WSL/Git Bash. + +### Highest-risk incompatibilities +1. **(Fixed)** Literal `$HOME` path creation risk in audit watchdog cron setup payload generation. +2. **(Fixed)** Path env vars accepted as raw strings in multiple Node entrypoints without expansion/validation. +3. **(Open)** Large portions of manual install/release guidance remain POSIX-only (`bash`, `jq`, `curl`, `unzip`, `chmod`, `find -exec`). + +### SKILLS install path-expansion root cause +Root cause was a combination of: +- shell-side literal env assignment (for example, `PROMPTSEC_INSTALL_DIR='$HOME/...')` +- Node scripts not expanding home tokens +- cron payload construction escaping `$` (`\$HOME`), forcing literal interpretation in downstream shell execution + +This could produce paths like `~/.openclaw/workspace/$HOME/...`. + +--- + +## 2) Findings Table + +| ID | Severity | OS Impact | Component | Description | Proposed Fix | Status | +|---|---|---|---|---|---|---| +| CP-001 | Blocker | Linux/macOS/Windows | `skills/openclaw-audit-watchdog/scripts/setup_cron.mjs` | Literal `$HOME` could be propagated into cron payload, creating wrong runtime paths. | Expand/normalize home tokens and reject unresolved escaped tokens before job creation. | **Fixed** | +| CP-002 | High | Linux/macOS/Windows | `skills/clawsec-suite/hooks/.../handler.ts`, `.../scripts/guarded_skill_install.mjs`, `.../lib/suppression.mjs`, `skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs` | Env path vars treated as opaque strings; `~`, `$HOME` not consistently handled. | Shared/consistent path resolution + fail-fast validation. | **Fixed** | +| CP-003 | Medium | macOS/Windows | `skills/openclaw-audit-watchdog/test/render_report_suppression.test.mjs`, `.../scripts/codex_review.sh` | Hardcoded `/opt/homebrew` and `which` assumptions. | Use `process.execPath` for tests; PATH-first Codex discovery. | **Fixed** | +| CP-004 | Medium | Windows (+ CI) | repo-wide line endings | Missing `.gitattributes` could introduce CRLF script breakage (`env bash^M`). | Add `.gitattributes` with LF enforcement for scripts/config/text. | **Fixed** | +| CP-005 | Medium | macOS/Windows | `.github/workflows/ci.yml` | TS/lint/build checks were Linux-only. | Add OS matrix for Node checks (`ubuntu`, `macos`, `windows`). | **Fixed** | +| CP-006 | High | Windows | Multiple SKILL docs and shell scripts | Install/maintenance flow is still heavily POSIX-shell based. | Add PowerShell equivalents or Node wrappers for critical flows. | Open | +| CP-007 | Medium | Linux/macOS/Windows | `skills/soul-guardian/scripts/soul_guardian.py` | `Path(...).expanduser()` handles `~` but not `$HOME`/`%USERPROFILE%`. | Add explicit env-token expansion + validation for `--state-dir`. | Open | +| CP-008 | Medium | Windows | `scripts/release-skill.sh`, `scripts/populate-local-*.sh` | GNU/BSD shell toolchain assumptions block native Windows usage. | Provide cross-platform Node/Python replacements or PowerShell equivalents. | Open | +| CP-009 | Low | Windows | documentation + scripts using `chmod 600/644` | POSIX permission semantics are partial/non-portable on Windows. | Document best-effort behavior and Windows ACL alternatives. | Open | +| CP-010 | Low | macOS/Windows | CI non-Node jobs | Shell/Python/security scan jobs remain Ubuntu-only. | Add scoped matrix or dedicated non-Linux smoke jobs where practical. | Open | + +--- + +## 3) Detailed Findings + +## Paths +- Fixed: centralized home-token expansion and suspicious token rejection for critical runtime/install path env vars. +- Fixed: path normalization before filesystem access and before cron payload construction. +- Open: `soul_guardian.py` still expands only `~`, not `$HOME`/Windows env tokens. + +## Shell / Command Dependencies +- Confirmed extensive POSIX dependencies (`bash`, `curl`, `jq`, `mktemp`, `chmod`, `find`, `unzip`, `openssl`, `shasum/sha256sum`). +- Fixed minor hardcoded binary path assumptions. +- Open: no full native PowerShell parity for core shell workflows. + +## Permissions / Filesystem Semantics +- Confirmed many scripts rely on POSIX permission commands. +- Existing `state.ts` already handles `chmod` failures on unsupported filesystems. +- Open: documentation still mostly assumes POSIX permissions. + +## Line Endings +- Fixed by adding `.gitattributes` with LF rules for scripts and key text/config files. + +## Runtime Dependencies +- Node scripts generally portable. +- Python utilities are portable. +- OpenSSL usage in documentation/workflows remains shell/toolchain dependent. + +## CI / Automation +- Fixed: TS/lint/build matrix now runs on Linux/macOS/Windows. +- Open: remaining security/shell/python jobs are Linux-only by design. + +--- + +## 4) SKILLS Install Investigation + +### Reproduction (pre-fix) +1. Set install dir with literal token (common quoting mistake): + - `export PROMPTSEC_INSTALL_DIR='$HOME/.config/security-checkup'` +2. Run: + - `node skills/openclaw-audit-watchdog/scripts/setup_cron.mjs` +3. The generated payload command used escaped `$` in `cd` path, resulting in literal token usage at execution time (`cd "\$HOME/..."`), which can resolve under current working directory (for example, `~/.openclaw/workspace/$HOME/...`). + +### Root cause analysis +- POSIX single quotes prevent variable expansion. +- Node does not auto-expand env vars inside strings. +- Existing payload escaping converted `$` to literal in shell command text. + +### Fix implemented +- Added explicit path resolution (supports `~`, `$HOME`, `${HOME}`, `%USERPROFILE%`, `$env:USERPROFILE`) and normalization. +- Added fail-fast validation for unresolved/escaped home tokens. +- Applied to watchdog cron setup, watchdog suppression config loader, suite hook handler, suite advisory suppression loader, and suite guarded installer. +- Added tests covering expansion and escaped-token rejection. + +### Validation targets +- `bash` / `zsh`: expanded env values and reject literal escaped home tokens. +- `sh` (where scripts are invoked through Node entrypoints): same path behavior in Node layer. +- Windows PowerShell: `%USERPROFILE%` / `$env:USERPROFILE` expansion and path normalization validated in Node tests. + +## Source References +- .gitattributes +- .github/workflows/ci.yml +- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts +- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs +- skills/clawsec-suite/scripts/guarded_skill_install.mjs +- skills/openclaw-audit-watchdog/scripts/setup_cron.mjs +- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs +- skills/soul-guardian/scripts/soul_guardian.py +- scripts/release-skill.sh +- scripts/populate-local-feed.sh +- scripts/populate-local-skills.sh +- wiki/remediation-plan.md +- wiki/platform-verification.md diff --git a/migration-signed-feed.md b/migration-signed-feed.md new file mode 100644 index 0000000..26e1455 --- /dev/null +++ b/migration-signed-feed.md @@ -0,0 +1,176 @@ +# Migration Plan: Unsigned Feed → Signed Feed + +## 1) Objective + +Move ClawSec advisory distribution from unsigned `feed.json` delivery to detached-signature verification with minimal disruption. + +This plan is written against the current repository behavior: +- feed is produced by `poll-nvd-cves.yml` and `community-advisory.yml` +- feed is published by `deploy-pages.yml` +- suite consumers currently load unsigned JSON from remote/local fallback paths + +## 2) Baseline (today) + +Current feed paths in active use: +- Source of truth: `advisories/feed.json` +- Skill copy: `skills/clawsec-feed/advisories/feed.json` +- Pages copy: `public/advisories/feed.json` +- Latest mirror copy: `public/releases/latest/download/advisories/feed.json` + +Current consumer defaults: +- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts` +- `skills/clawsec-suite/scripts/guarded_skill_install.mjs` +- default URL: `https://raw.githubusercontent.com/prompt-security/clawsec/main/advisories/feed.json` + +## 3) Migration principles + +- **Dual-publish first**: publish signatures before enforcing verification. +- **Fail-open only during transition**: temporary compatibility period is explicit and time-bounded. +- **Measured rollout**: enforce verification after telemetry confirms stable signed publishing. +- **Fast rollback**: preserve a path back to unsigned behavior while root cause is investigated. + +## 4) Phased timeline + +### Phase 0 — Preparation (Week 0) + +Deliverables: +- signing keys generated and fingerprints recorded +- GitHub secrets created +- public key(s) added in repo +- runbooks approved (`security-signing-runbook.md`, this file) + +Exit criteria: +- key fingerprints verified by reviewer +- protected branch/workflow controls enabled + +### Phase 1 — CI signing enabled, no client enforcement (Week 1) + +Implement: +- add feed signing step/workflow to produce `advisories/feed.json.sig` +- optionally produce `advisories/checksums.json` + `.sig` +- ensure CI verifies signatures before publishing artifacts + +Also update deployment: +- copy `.sig` artifacts to `public/advisories/` +- mirror `.sig` in `public/releases/latest/download/advisories/` + +Exit criteria: +- signatures generated successfully for all feed update paths +- deploy artifacts contain both payload and signature companions + +### Phase 2 — Consumer dual-read/dual-verify support (Week 2) + +Implement in consumers: +- read `feed.json` and `feed.json.sig` +- verify with pinned public key +- keep controlled temporary unsigned fallback during migration window + +Validation: +- test remote signed path +- test local signed fallback path +- test invalid signature rejection + +Exit criteria: +- verification logic released and tested +- no false-positive verification failures in soak period + +### Phase 3 — Enforcement (Week 3) + +Actions: +- disable temporary unsigned fallback behavior in default paths +- add CI/publish gates that fail when `.sig` is missing +- announce enforcement date in release notes and docs + +Exit criteria: +- all production clients verify signatures by default +- no unsigned feed dependency in standard installation flow + +### Phase 4 — Stabilization (Week 4) + +Actions: +- run first key rotation tabletop drill +- run rollback tabletop drill +- close migration with post-implementation review + +## 5) Rollback plan + +### Rollback triggers + +Initiate rollback if any of the following occur: +- sustained signature verification failures across clients +- signing workflow cannot produce valid signatures +- key compromise suspected but replacement key is not yet deployed +- deployment path publishes mismatched payload/signature pairs + +### Rollback levels + +### Level 1 (preferred): Verification bypass window, keep signed publishing + +Use when: signing is healthy, client-side verifier has a defect. + +Actions: +1. Re-enable temporary unsigned-acceptance behavior in client release branch. +2. Ship patch release with explicit expiry date for bypass. +3. Keep signing pipeline active to avoid authenticity gap. + +Recovery target: restore strict verification within 24–48h. + +### Level 2: Signed pipeline paused, unsigned feed temporarily authoritative + +Use when: signing pipeline is unstable or producing inconsistent artifacts. + +Actions: +1. Disable signing workflow or signing step. +2. Continue publishing unsigned `advisories/feed.json` via existing workflows. +3. Revert deploy gates that require `.sig` artifacts. +4. Open incident record and track time in unsigned mode. + +Recovery target: restore signed publishing ASAP, ideally <72h. + +### Level 3: Full release freeze + +Use when: compromise or integrity of repository/workflows is in doubt. + +Actions: +1. Pause feed mutation and deployment workflows. +2. Restore known-good commit for advisory files/workflows. +3. Rotate keys and credentials. +4. Resume pipeline only after security review sign-off. + +### Roll-forward after rollback + +- identify root cause +- add regression tests/gates +- redeploy signed artifacts +- publish incident + remediation summary + +## 6) Communication plan + +For enforcement and rollback events, communicate: +- what changed +- expected operator/client action +- duration of temporary compatibility mode (if any) +- verification commands for users + +Recommended channels: +- GitHub release notes +- repository README/docs updates +- issue/incident report in repository + +## 7) Go/No-Go checklist + +Go only if all are true: +- signing workflow success rate is stable +- signatures are mirrored to all documented feed endpoints +- consumer verification path tested for remote + local fallback +- rollback owner is assigned and reachable +- key rotation procedure has been dry-run at least once + +## Source References +- .github/workflows/poll-nvd-cves.yml +- .github/workflows/community-advisory.yml +- .github/workflows/deploy-pages.yml +- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts +- skills/clawsec-suite/scripts/guarded_skill_install.mjs +- advisories/feed.json +- wiki/security-signing-runbook.md diff --git a/overview.md b/overview.md index 72fbdf3..5393fe2 100644 --- a/overview.md +++ b/overview.md @@ -18,7 +18,7 @@ | `.github/workflows/` | CI/CD pipelines | CI, releases, NVD polling, community advisory ingestion, pages deploy. | | `utils/` | Python utilities | Skill validation and checksum packaging helpers. | | `public/` | Published static assets | Site media, mirrored advisories, and generated skill artifacts. | -| `docs/` | Operational docs | Signing runbooks, migration plans, compatibility and verification guides. | +| `wiki/` | Documentation hub | Architecture, operations runbooks, compatibility, and verification guides. | ## Entry Points | Entry | Type | Purpose | @@ -84,6 +84,9 @@ npm run build - Skill release automation expects version parity between `skill.json` and `SKILL.md` frontmatter. - Some scripts are POSIX shell oriented; Windows users should prefer PowerShell equivalents or WSL. +## Update Notes +- 2026-02-26: Updated repo layout to point operational documentation at `wiki/` instead of the removed root `docs/` directory. + ## Source References - README.md - package.json diff --git a/platform-verification.md b/platform-verification.md new file mode 100644 index 0000000..6e8d14d --- /dev/null +++ b/platform-verification.md @@ -0,0 +1,98 @@ +# Platform Verification Checklist + +Use this checklist to validate portability and path-handling behavior after changes. + +## Linux Verification + +1. Run core Node tests: + ```bash + node skills/clawsec-suite/test/path_resolution.test.mjs + node skills/clawsec-suite/test/guarded_install.test.mjs + node skills/clawsec-suite/test/advisory_suppression.test.mjs + node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs + ``` + Expected: all tests pass. + +2. Verify no literal `$HOME` path acceptance: + ```bash + CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \ + node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run + ``` + Expected: exits non-zero with `Unexpanded home token` error. + +3. Verify `$HOME` expansion works: + ```bash + HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs + ``` + Expected: `$HOME` expansion tests pass. + +## macOS Verification + +1. Run the same Node test suite as Linux. +2. Confirm OpenSSL tooling path assumptions are documented: + - If using LibreSSL/OpenSSL variations, ensure checks use tested command forms from docs. +3. Verify tilde expansion in config path: + ```bash + OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \ + node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions + ``` + Expected: path resolves correctly (or clear file-not-found error at expanded location). + +## Windows Verification (PowerShell) + +1. Run Node tests: + ```powershell + node skills/clawsec-suite/test/path_resolution.test.mjs + node skills/clawsec-suite/test/guarded_install.test.mjs + node skills/clawsec-suite/test/advisory_suppression.test.mjs + ``` + Expected: all pass. + +2. Verify PowerShell env path expansion behavior: + ```powershell + $env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json' + node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run + ``` + Expected: path token is expanded/normalized or fails with a clear error if target files are missing. + +3. Verify escaped literal token rejection: + ```powershell + $env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json' + node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run + ``` + Expected: `Unexpanded home token` error; no directory creation with literal `$HOME`. + +## Line Endings Sanity + +1. Confirm LF policy is present: + ```bash + test -f .gitattributes && grep -n "eol=lf" .gitattributes + ``` + Expected: script/config file patterns enforce LF. + +2. After a CRLF-prone checkout, verify scripts still parse: + ```bash + bash -n scripts/populate-local-feed.sh + bash -n scripts/populate-local-skills.sh + ``` + Expected: no `^M` shebang/parse errors. + +## Explicit Bug Check: No Literal `$HOME` Directory Creation + +1. Configure a path with a literal/escaped token. +2. Run setup/install command. +3. Verify command fails early with token error. +4. Confirm no `$HOME` segment directory was created under working directories. + +Expected outcome: **no directories containing literal `$HOME` are created by supported setup scripts.** + +## Source References +- .gitattributes +- scripts/populate-local-feed.sh +- scripts/populate-local-skills.sh +- skills/clawsec-suite/test/path_resolution.test.mjs +- skills/clawsec-suite/test/guarded_install.test.mjs +- skills/clawsec-suite/test/advisory_suppression.test.mjs +- skills/clawsec-suite/scripts/guarded_skill_install.mjs +- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs +- skills/openclaw-audit-watchdog/test/suppression_config.test.mjs diff --git a/remediation-plan.md b/remediation-plan.md new file mode 100644 index 0000000..8d59b40 --- /dev/null +++ b/remediation-plan.md @@ -0,0 +1,85 @@ +# Cross-Platform Remediation Plan + +## Phase 1: Immediate Risk Closure (Completed) + +### Milestones +- Implement explicit home-path expansion + suspicious token rejection in high-risk runtime/install paths. +- Add regression tests for path expansion and escaped-token rejection. +- Add `.gitattributes` LF policy. +- Expand Node lint/type/build CI coverage to Linux/macOS/Windows. +- Update install docs with shell-specific guidance and literal `$HOME` troubleshooting. + +### Outcomes +- Literal `$HOME` path propagation bug addressed at source. +- Core advisory/install path config now fails fast on invalid path tokens. + +--- + +## Phase 2: Windows Parity for Critical Workflows (Next) + +### Quick wins +- Add PowerShell equivalents for the most-used manual install/check commands in: + - `skills/clawsec-suite/SKILL.md` + - `skills/openclaw-audit-watchdog/SKILL.md` + - `README.md` +- Add a lightweight `scripts/preflight.mjs` to detect missing tools and print OS-specific install hints. + +### Milestones +- Native PowerShell instructions for suite setup and advisory hook. +- WSL/Git Bash fallback documented where shell scripts are unavoidable. + +--- + +## Phase 3: Reduce POSIX Shell Surface (Deeper Refactor) + +### Refactor targets +- `scripts/populate-local-feed.sh` +- `scripts/populate-local-skills.sh` +- `scripts/release-skill.sh` + +### Approach +- Re-implement critical paths in Node/Python to remove dependency on `jq/sed/awk/find/chmod` pipelines. +- Preserve shell wrappers for backward compatibility; route to new cross-platform implementations. + +### Migration notes +- Keep old script entrypoints as wrappers for at least one minor release. +- Emit deprecation warnings with exact migration commands. + +--- + +## Phase 4: CI Hardening and Ongoing Verification + +### Milestones +- Keep Node matrix (Linux/macOS/Windows) as required check. +- Add targeted Windows smoke tests for install path handling. +- Add macOS check for OpenSSL command compatibility notes where relevant. + +### Test strategy +- Local: + - Run Node test suites that cover path expansion/suppression/install behavior. + - Run syntax checks for modified scripts. +- CI: + - Matrix Node checks + guarded installer/suppression/path tests. + - Linux-only security scans remain, but explicitly marked as Linux-scoped. + +--- + +## Rollout / Release Considerations + +- No breaking interface changes introduced in this patch set; behavior is stricter only for invalid/unexpanded path tokens. +- Communicate in release notes: + - path token validation now enforced + - how to correct invalid quoted env values + - where PowerShell examples live + +## Source References +- .gitattributes +- .github/workflows/ci.yml +- scripts/populate-local-feed.sh +- scripts/populate-local-skills.sh +- scripts/release-skill.sh +- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts +- skills/clawsec-suite/scripts/guarded_skill_install.mjs +- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs +- wiki/platform-verification.md +- wiki/compatibility-report.md diff --git a/security-signing-runbook.md b/security-signing-runbook.md new file mode 100644 index 0000000..4ad8f47 --- /dev/null +++ b/security-signing-runbook.md @@ -0,0 +1,228 @@ +# ClawSec Signing Operations Runbook + +## 1) Purpose + +This runbook defines operational procedures for introducing and running cryptographic signing in the ClawSec repository. + +It covers: +- key generation +- GitHub secret management +- signing workflow integration +- key rotation and revocation +- incident response + +## 2) Current branch reality (important) + +As of branch `integration/signing-work`, advisory distribution is **unsigned**: + +- Feed writers: + - `.github/workflows/poll-nvd-cves.yml` writes `advisories/feed.json` and `skills/clawsec-feed/advisories/feed.json` + - `.github/workflows/community-advisory.yml` writes the same files +- Feed publish path: + - `.github/workflows/deploy-pages.yml` copies to `public/advisories/feed.json` + - also mirrors to `public/releases/latest/download/advisories/feed.json` +- Feed consumers: + - `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts` + - `skills/clawsec-suite/scripts/guarded_skill_install.mjs` + - both default to `https://clawsec.prompt.security/advisories/feed.json` + +This document defines the **target operating model** for signed artifacts while preserving compatibility during migration. + +## 3) Target signed artifacts + +### Advisory feed channel +- `advisories/feed.json` (payload) +- `advisories/feed.json.sig` (detached Ed25519 signature; base64) +- `advisories/feed-signing-public.pem` (pinned public key) + +### Release artifact channel (recommended) +- `/checksums.json` +- `/checksums.sig` +- `advisories/release-signing-public.pem` (or equivalent repo-pinned location) + +## 4) Key roles and custody + +- **Security owner**: approves key lifecycle changes and incident actions. +- **Platform owner**: maintains workflows and GitHub secrets. +- **Reviewer**: validates fingerprints in PRs/releases. + +Policy: +- private keys are never committed +- public keys are committed and code-reviewed +- key generation occurs on trusted operator workstation or HSM-backed environment + +## 5) Key generation (Ed25519) + +> Run from a secure workstation. Do not run on shared CI runners. + +```bash +# Feed signing keypair +openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem +openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem + +# Release checksums signing keypair (optional separate key) +openssl genpkey -algorithm Ed25519 -out release-signing-private.pem +openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem +``` + +Generate fingerprints (store in ticket/change record): + +```bash +openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256 +openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256 +``` + +Optional test-sign before publishing: + +```bash +echo '{"probe":"ok"}' > /tmp/probe.json +openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin +openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig +openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin +openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin +``` + +## 6) GitHub secrets setup + +### Required secrets + +- `CLAWSEC_SIGNING_PRIVATE_KEY` — PEM-encoded Ed25519 private key (used for both feed and release signing) +- `CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (optional) passphrase if the private key is encrypted + +### Procedure + +1. Go to **Repo Settings → Secrets and variables → Actions → New repository secret**. +2. Paste full PEM including header/footer. +3. Prefer GitHub **Environment secrets** (with required reviewers) for workflow scoping when possible. +4. Record change ticket with: + - secret name + - creator + - creation time + - key fingerprint + +### Recommended environment protections + +- Require manual approval for workflows that can use signing secrets. +- Restrict who can edit protected workflows. +- Enable branch protection for `main` and require review for workflow changes. + +## 7) Workflow integration points + +This repo already has feed mutation and deployment workflows. Signing should be inserted as a post-mutation, pre-publish control. + +### Feed pipeline + +Current feed mutation points: +- `.github/workflows/poll-nvd-cves.yml` +- `.github/workflows/community-advisory.yml` + +Target addition: +- add signing step/workflow that: + 1. regenerates deterministic feed checksums manifest (optional but recommended) + 2. signs `advisories/feed.json` into `advisories/feed.json.sig` + 3. verifies signature in CI before commit/publish + +### Pages pipeline + +Current publisher: +- `.github/workflows/deploy-pages.yml` + +Target update: +- copy `.sig` files to `public/advisories/` and `public/releases/latest/download/advisories/` +- fail deploy if expected signed companions are missing after migration enforcement date + +### Skill release pipeline (recommended hardening) + +Current release generator: +- `.github/workflows/skill-release.yml` creates `checksums.json` + +Target update: +- sign `checksums.json` before `softprops/action-gh-release` +- attach `checksums.sig` to each release + +## 8) Rotation policy and runbook + +### Rotation cadence +- Routine: every 90 days (or stricter org policy). +- Immediate: on suspected exposure, unauthorized workflow change, or unexplained signature mismatch. + +### Routine rotation steps + +1. Generate new keypair(s). +2. Open PR that updates public key file(s) and fingerprints documentation. +3. Add new private key(s) as GitHub secret(s). +4. Merge workflow changes that use new key(s). +5. Re-sign latest feed/release manifests. +6. Validate verification in CI and in one external client. +7. Remove old private key secret(s). +8. Keep old public key reference only as long as required for historical verification. + +### Revocation steps + +1. Disable workflows using compromised key. +2. Remove compromised GitHub secret(s). +3. Commit revocation note and new public key. +4. Re-sign latest artifacts with replacement key. +5. Publish incident advisory with timestamp and impacted window. + +## 9) Incident response playbook (signing-specific) + +### Triggers +- signature verification fails for newly published feed/release +- unknown commits/workflow edits touching signing paths +- leaked key material, accidental logging, or suspicious secret access + +### Severity guide +- **SEV-1**: key exfiltration confirmed or maliciously signed payload published +- **SEV-2**: verification failures with unknown cause +- **SEV-3**: procedural non-compliance, no active compromise + +### Response phases + +1. **Containment** + - pause signing/publish workflows + - block further feed merges if authenticity is uncertain +2. **Investigation** + - review workflow run logs + - review commits affecting `.github/workflows/`, `advisories/`, and key files + - determine first-bad timestamp and affected artifacts +3. **Eradication** + - rotate/revoke compromised key(s) + - restore trusted artifacts from known-good commit +4. **Recovery** + - re-sign artifacts + - redeploy pages/releases + - verify via independent client check +5. **Post-incident** + - publish timeline and remediation summary + - tighten controls (review gates, protected environments, secret scope) + +## 10) Audit evidence checklist + +For each release cycle or feed-signing run, retain: +- workflow run URL and commit SHA +- signer key fingerprint in use +- verification result logs +- operator/reviewer approvals +- any exception or bypass rationale + +## 11) Minimum acceptance criteria before enforcement + +Before requiring signatures in all clients: +- signed artifacts are produced consistently for at least 2 weeks +- deploy pipeline mirrors signature companions +- one rollback drill and one key rotation drill completed successfully +- incident response on-call owner identified and documented + +## Source References +- advisories/feed.json +- advisories/feed.json.sig +- advisories/feed-signing-public.pem +- clawsec-signing-public.pem +- .github/actions/sign-and-verify/action.yml +- .github/workflows/poll-nvd-cves.yml +- .github/workflows/community-advisory.yml +- .github/workflows/deploy-pages.yml +- .github/workflows/skill-release.yml +- scripts/ci/verify_signing_key_consistency.sh +- wiki/migration-signed-feed.md diff --git a/security.md b/security.md index 5d788ed..36d0f39 100644 --- a/security.md +++ b/security.md @@ -29,8 +29,8 @@ - Release docs include manual verification commands for downstream consumers. ## Incident and Rotation Playbooks -- `docs/SECURITY-SIGNING.md` defines key generation, custody, rotation, and incident phases. -- `docs/MIGRATION-SIGNED-FEED.md` defines staged enforcement and rollback levels. +- `wiki/security-signing-runbook.md` defines key generation, custody, rotation, and incident phases. +- `wiki/migration-signed-feed.md` defines staged enforcement and rollback levels. - Rollback paths prioritize preserving signed publishing where possible and time-boxing any bypass. ## Example Snippets @@ -56,10 +56,13 @@ openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256 - Add explicit tests for workflow-level signature failure scenarios. - Increase runtime telemetry for advisory fetch/verification failures to simplify incident triage. +## Update Notes +- 2026-02-26: Repointed signing and migration references from root `docs/` files to dedicated `wiki/` operations pages. + ## Source References - SECURITY.md -- docs/SECURITY-SIGNING.md -- docs/MIGRATION-SIGNED-FEED.md +- wiki/security-signing-runbook.md +- wiki/migration-signed-feed.md - scripts/ci/verify_signing_key_consistency.sh - .github/actions/sign-and-verify/action.yml - .github/workflows/poll-nvd-cves.yml diff --git a/testing.md b/testing.md index a326463..7833040 100644 --- a/testing.md +++ b/testing.md @@ -57,6 +57,9 @@ node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs 3. For feed/signing changes, run suite verification tests first (`feed_verification`, `guarded_install`). 4. For workflow or release changes, also run `scripts/validate-release-links.sh` and key consistency script. +## Update Notes +- 2026-02-26: Updated source references to the migrated `wiki/platform-verification.md` checklist. + ## Source References - AGENTS.md - scripts/prepare-to-push.sh @@ -70,4 +73,4 @@ node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs - skills/clawsec-suite/test/path_resolution.test.mjs - skills/openclaw-audit-watchdog/test/suppression_config.test.mjs - skills/clawsec-clawhub-checker/test/reputation_check.test.mjs -- docs/PLATFORM_VERIFICATION.md +- wiki/platform-verification.md