mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
feat(wiki): add full in-app wiki browser and llms index (#80)
* feat(wiki): add full in-app wiki browser and llms index * feat(wiki): auto-generate per-page llms exports * vuln package * fix(wiki): guard malformed route decoding * fix(wiki): preserve markdown anchor fragments across page links * refactor(markdown): share default render components * fix(wiki): block unsafe markdown link schemes * fix(wiki): block unsafe markdown image schemes * docs(wiki): migrate root docs into wiki pages * chore(wiki): de-track generated llms exports * chore(wiki): ignore generated public wiki artifacts * fix(wiki): align llms urls with per-page endpoint pattern * fix(wiki): derive llms index from wiki index page * refactor(markdown): share frontmatter and title helpers * refactor(wiki): share route and llms path mapping * ci(pages): add pr verify workflow and tighten deploy triggers
This commit is contained in:
davida-ps
GitHub
+11
-6
@@ -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
|
||||
|
||||
+11
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
+4
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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)
|
||||
- `<release>/checksums.json`
|
||||
- `<release>/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
|
||||
+7
-4
@@ -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
|
||||
|
||||
+4
-1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user