From 67f9657e3f96da8d48775f40a41005da0ea99f39 Mon Sep 17 00:00:00 2001 From: David Abutbul Date: Thu, 26 Feb 2026 11:17:07 +0200 Subject: [PATCH 1/2] docs(repo): refresh docs and wiki alignment --- AGENTS.md | 6 +++ CONTRIBUTING.md | 2 +- README.md | 61 ++++++++++++++++++++-------- wiki/architecture.md | 4 +- wiki/data-flow.md | 2 +- wiki/dependencies.md | 4 +- wiki/migration-signed-feed.md | 36 ++++++++-------- wiki/modules/automation-release.md | 8 +++- wiki/modules/frontend-web.md | 9 ++++ wiki/modules/nanoclaw-integration.md | 2 +- wiki/overview.md | 12 ++++-- wiki/security-signing-runbook.md | 56 +++++++++++++------------ wiki/security.md | 3 +- wiki/testing.md | 3 +- wiki/workflow.md | 10 ++++- 15 files changed, 146 insertions(+), 72 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ffd223f..7103a73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,8 @@ ClawSec combines a Vite + React frontend with security skill packages and releas - Frontend entrypoints: `index.tsx`, `App.tsx` - UI and routes: `components/`, `pages/` - Shared types/constants: `types.ts`, `constants.ts` +- Wiki source docs: `wiki/` (synced to GitHub Wiki by `.github/workflows/wiki-sync.yml`) +- Generated wiki exports: `public/wiki/` (`llms.txt` outputs; generated locally/CI and gitignored) - Skills: `skills//` (`skill.json`, `SKILL.md`, optional `scripts/`, `test/`) - Advisory feed: `advisories/feed.json`, `advisories/feed.json.sig` - Automation: `scripts/`, `.github/workflows/` @@ -15,7 +17,9 @@ ClawSec combines a Vite + React frontend with security skill packages and releas - `npm run dev`: run local Vite server. - `npm run build`: create production build (CI gate). - `npm run preview`: preview built app. +- `npm run gen:wiki-llms`: generate wiki `llms.txt` exports from `wiki/` into `public/wiki/`. - `./scripts/prepare-to-push.sh [--fix]`: run lint, types, build, and security checks. +- `./scripts/populate-local-wiki.sh`: regenerate local wiki `llms.txt` exports for preview. - `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0`: lint JS/TS. - `npx tsc --noEmit`: type-check TypeScript. - `node skills/clawsec-suite/test/feed_verification.test.mjs`: run a skill-local Node test. @@ -31,6 +35,7 @@ ClawSec combines a Vite + React frontend with security skill packages and releas There is no root `npm test`; tests are mostly skill-local. - Run changed tests directly: `node skills//test/.test.mjs`. - For frontend/config changes, run ESLint, `npx tsc --noEmit`, and `npm run build`. +- For wiki rendering/export changes, run `npm run gen:wiki-llms` and `npm run build`. - For Python utility updates, run `ruff check utils/` and `bandit -r utils/ -ll`. ## Pull Request Guidelines @@ -39,6 +44,7 @@ There is no root `npm test`; tests are mostly skill-local. - Keep PRs focused and include summary, security benefit, and testing performed. - Keep versions aligned between `skills//skill.json` and `skills//SKILL.md`. - Do not push release tags from PR branches; releases are tagged from `main`. +- Do not commit generated `public/wiki/` artifacts; edit `wiki/` source files instead. ## Agent Collaboration & Git Safety - Delete unused or obsolete files only when your changes make them irrelevant; revert files only when the change is yours or explicitly requested. If a git operation creates uncertainty about another agent’s in-flight work, stop and coordinate instead of deleting. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3a0379..59d6be8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -654,7 +654,7 @@ Wait for a verified patched version. Once your advisory is published: -1. **Agents receive it** - The feed is served from raw GitHub, so agents see it on their next feed check +1. **Agents receive it** - The feed is served at `https://clawsec.prompt.security/advisories/feed.json` (with signature/checksum artifacts), so agents see it on their next feed check 2. **You're credited** - Your issue is linked in the advisory 3. **Community is protected** - Agents using ClawSec Feed will be alerted diff --git a/README.md b/README.md index 28b5341..1245b09 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@
-## Secure Your OpenClaw Bots with a Complete Security Skill Suite +## Secure Your OpenClaw and NanoClaw Agents with a Complete Security Skill Suite

Brought to you by Prompt Security, the Platform for AI Security

@@ -37,7 +37,7 @@ ClawSec is a **complete security skill suite for AI agent platforms**. It provid ### Supported Platforms -- **OpenClaw** (Moltbot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits +- **OpenClaw** (MoltBot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits - **NanoClaw** - Containerized WhatsApp bot security with MCP tools for advisory monitoring, signature verification, and file integrity ### Core Capabilities @@ -74,21 +74,25 @@ Direct link: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4) ### For AI Agents ```bash -# Fetch and install the ClawSec security suite -curl -sL https://clawsec.prompt.security/releases/latest/download/SKILL.md +# Install the ClawSec security suite +npx clawhub@latest install clawsec-suite ``` -The skill file contains deployment instructions. Your agent will: -1. Detect its agent family (OpenClaw/MoltBot/ClawdBot or other) -2. Install appropriate skills from the catalog -3. Verify integrity using checksums -4. Set up cron update checks +After install, the suite can: +1. Discover installable protections from the published skills catalog +2. Verify release integrity using signed checksums +3. Set up advisory monitoring and hook-based protection flows +4. Add optional scheduled checks + +Manual/source-first option: + +> Read https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md and follow the installation instructions. ### For Humans Copy this instruction to your AI agent: -> Read https://clawsec.prompt.security/releases/latest/download/SKILL.md and follow the instructions to install the protection skill suite. +> Install ClawSec with `npx clawhub@latest install clawsec-suite`, then complete the setup steps from the generated instructions. ### Shell and OS Notes @@ -160,13 +164,13 @@ The **clawsec-suite** is a skill-of-skills manager that installs, verifies, and | Skill | Description | Installation | Compatibility | |-------|-------------|--------------|---------------| | πŸ“‘ **clawsec-feed** | Security advisory feed monitoring with live CVE updates | βœ… Included by default | All agents | -| πŸ”­ **openclaw-audit-watchdog** | Automated daily audits with email reporting | βš™οΈ Optional (install separately) | OpenClaw/MoltBot/ClawdBot | +| πŸ”­ **openclaw-audit-watchdog** | Automated daily audits with email reporting | βš™οΈ Optional (install separately) | OpenClaw/MoltBot/Clawdbot | | πŸ‘» **soul-guardian** | Drift detection and file integrity guard with auto-restore | βš™οΈ Optional | All agents | | 🀝 **clawtributor** | Community incident reporting | ❌ Optional (Explicit request) | All agents | > ⚠️ **clawtributor** is not installed by default as it may share anonymized incident data. Install only on explicit user request. -> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/ClawdBot agent family. Other agents receive the universal skill set. +> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/Clawdbot agent family. Other agents receive the universal skill set. ### Suite Features @@ -233,7 +237,7 @@ The feed polls CVEs related to: ``` **Platform values:** -- `"openclaw"` - OpenClaw/ClawdBot/MoltBot only +- `"openclaw"` - OpenClaw/Clawdbot/MoltBot only - `"nanoclaw"` - NanoClaw only - `["openclaw", "nanoclaw"]` - Both platforms - (empty/missing) - All platforms (backward compatible) @@ -248,10 +252,13 @@ ClawSec uses automated pipelines for continuous security updates and skill distr | Workflow | Trigger | Description | |----------|---------|-------------| +| **ci.yml** | PRs to `main`, pushes to `main` | Lint/type/build + skill test suites | +| **pages-verify.yml** | PRs to `main` | Verifies Pages build and signing outputs without publishing | | **poll-nvd-cves.yml** | Daily cron (06:00 UTC) | Polls NVD for new CVEs, updates feed | | **community-advisory.yml** | Issue labeled `advisory-approved` | Processes community reports into advisories | -| **skill-release.yml** | `-v*.*.*` tags | Packages individual skills with checksums to GitHub Releases | -| **deploy-pages.yml** | Push to main | Builds and deploys the web interface to GitHub Pages | +| **skill-release.yml** | Skill tags + metadata PR changes | Validates version parity in PRs and publishes signed skill releases on tags | +| **deploy-pages.yml** | `workflow_run` after successful trusted CI/release or manual dispatch | Builds and deploys the web interface to GitHub Pages | +| **wiki-sync.yml** | Pushes to `main` touching `wiki/**` | Syncs `wiki/` to the GitHub Wiki mirror | ### Skill Release Pipeline @@ -262,7 +269,7 @@ When a skill is tagged (e.g., `soul-guardian-v1.0.0`), the pipeline: 3. **Generates Checksums** - Creates `checksums.json` with SHA256 hashes for all SBOM files 4. **Signs + verifies** - Signs `checksums.json` and validates the generated `signing-public.pem` fingerprint against canonical repo key material 5. **Releases** - Publishes to GitHub Releases with all artifacts -6. **Supersedes Old Releases** - Marks older versions (same major) as pre-releases +6. **Supersedes Old Releases** - Deletes older versions within the same major line (tags remain) 7. **Triggers Pages Update** - Refreshes the skills catalog on the website ### Signing Key Consistency Guardrails @@ -378,8 +385,15 @@ npm run dev # Generate wiki llms exports from wiki/ (for local preview) ./scripts/populate-local-wiki.sh + +# Direct generator entrypoint (used by predev/prebuild) +npm run gen:wiki-llms ``` +Notes: +- `npm run dev` and `npm run build` automatically regenerate wiki `llms.txt` exports (`predev`/`prebuild` hooks). +- `public/wiki/` is generated output (local + CI) and is intentionally gitignored. + ### Build ```bash @@ -395,7 +409,9 @@ npm run build β”‚ └── feed.json # Main advisory feed (auto-updated from NVD) β”œβ”€β”€ components/ # React components β”œβ”€β”€ pages/ # Page components +β”œβ”€β”€ wiki/ # Source-of-truth docs (synced to GitHub Wiki) β”œβ”€β”€ scripts/ +β”‚ β”œβ”€β”€ generate-wiki-llms.mjs # wiki/*.md -> public/wiki/**/llms.txt β”‚ β”œβ”€β”€ populate-local-feed.sh # Local CVE feed populator β”‚ β”œβ”€β”€ populate-local-skills.sh # Local skills catalog populator β”‚ β”œβ”€β”€ populate-local-wiki.sh # Local wiki llms export populator @@ -403,17 +419,24 @@ npm run build β”œβ”€β”€ skills/ β”‚ β”œβ”€β”€ clawsec-suite/ # πŸ“¦ Suite installer (skill-of-skills) β”‚ β”œβ”€β”€ clawsec-feed/ # πŸ“‘ Advisory feed skill +β”‚ β”œβ”€β”€ clawsec-nanoclaw/ # πŸ“± NanoClaw platform security suite +β”‚ β”œβ”€β”€ clawsec-clawhub-checker/ # πŸ§ͺ ClawHub reputation checks β”‚ β”œβ”€β”€ clawtributor/ # 🀝 Community reporting skill β”‚ β”œβ”€β”€ openclaw-audit-watchdog/ # πŸ”­ Automated audit skill +β”‚ β”œβ”€β”€ prompt-agent/ # 🧠 Prompt-focused protection workflows β”‚ └── soul-guardian/ # πŸ‘» File integrity skill β”œβ”€β”€ utils/ β”‚ β”œβ”€β”€ package_skill.py # Skill packager utility β”‚ └── validate_skill.py # Skill validator utility β”œβ”€β”€ .github/workflows/ +β”‚ β”œβ”€β”€ ci.yml # Cross-platform lint/type/build + tests +β”‚ β”œβ”€β”€ pages-verify.yml # PR-only pages build verification β”‚ β”œβ”€β”€ poll-nvd-cves.yml # CVE polling pipeline +β”‚ β”œβ”€β”€ community-advisory.yml # Approved issue -> advisory PR β”‚ β”œβ”€β”€ skill-release.yml # Skill release pipeline +β”‚ β”œβ”€β”€ wiki-sync.yml # Sync repo wiki/ to GitHub Wiki β”‚ └── deploy-pages.yml # Pages deployment -└── public/ # Static assets and published skills +└── public/ # Static assets + generated publish artifacts ``` --- @@ -445,6 +468,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#submitting-security-advisories) for detail For all wiki content, edit files under `wiki/` in this repository. The GitHub Wiki (`.wiki.git`) is synced from `wiki/` by `.github/workflows/wiki-sync.yml` when `wiki/**` changes on `main`. +LLM exports are generated from `wiki/` into `public/wiki/`: +- `/wiki/llms.txt` is the LLM-ready export for `wiki/INDEX.md` (or a generated fallback index if `INDEX.md` is missing). +- `/wiki//llms.txt` is the LLM-ready export for that single wiki page. + --- ## πŸ“„ License diff --git a/wiki/architecture.md b/wiki/architecture.md index 2bf2a05..ad2b1e1 100644 --- a/wiki/architecture.md +++ b/wiki/architecture.md @@ -81,6 +81,7 @@ flowchart TD } /> } /> } /> + } /> ``` @@ -102,7 +103,7 @@ const remoteFeed = await loadRemoteFeed(feedUrl, { | --- | --- | --- | | Vite app (`npm run dev`) | Local frontend server | Interactive web app for feed/skills. | | GitHub CI | Multi-OS matrix + dedicated jobs | Lint/type/build/security and test confidence. | -| Skill release workflow | Tag-driven | Release assets, signed checksums, optional ClawHub publish. | +| Skill release workflow | Tag-driven publish + PR dry-run checks | Release assets, signed checksums, optional ClawHub publish. | | Pages deploy workflow | Triggered by CI/Release success | Static site + mirrored advisories/releases. | | Runtime hooks | OpenClaw event hooks / NanoClaw IPC | Advisory alerts, gating decisions, integrity checks. | @@ -117,6 +118,7 @@ const remoteFeed = await loadRemoteFeed(feedUrl, { - pages/SkillsCatalog.tsx - pages/FeedSetup.tsx - pages/AdvisoryDetail.tsx +- pages/WikiBrowser.tsx - skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts - skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs - skills/clawsec-suite/scripts/guarded_skill_install.mjs diff --git a/wiki/data-flow.md b/wiki/data-flow.md index a459980..7f095aa 100644 --- a/wiki/data-flow.md +++ b/wiki/data-flow.md @@ -11,7 +11,7 @@ 2. JSON transform logic normalizes severity/type/affected fields and deduplicates by advisory ID. 3. Signature/checksum steps generate detached signatures and checksum manifests. 4. Deploy workflow mirrors signed artifacts under `public/` and `public/releases/latest/download/`. -5. UI and runtime consumers fetch feed/index files and validate format/signatures before use. +5. UI consumers validate JSON shape/content; runtime consumers additionally verify signatures/checksums before trusting feed data. 6. Matchers compare `affected` specifiers to skill names/versions and emit alerts or enforce confirmation. ## Inputs and Outputs diff --git a/wiki/dependencies.md b/wiki/dependencies.md index 1b702b8..8bca271 100644 --- a/wiki/dependencies.md +++ b/wiki/dependencies.md @@ -4,7 +4,7 @@ | Layer | Primary Dependencies | Why It Exists | | --- | --- | --- | | Frontend runtime | `react`, `react-dom`, `react-router-dom`, `lucide-react` | UI rendering, routing, iconography. | -| Markdown rendering | `react-markdown`, `remark-gfm` | Render skill docs/readmes in detail pages. | +| Markdown rendering | `react-markdown`, `remark-gfm` | Render skill docs/readmes and in-app wiki markdown pages. | | Build tooling | `vite`, `@vitejs/plugin-react`, `typescript` | Fast TS/TSX bundling and production builds. | | Python utilities | stdlib + `ruff`/`bandit` policy from `pyproject.toml` | Validate/package skills and run static checks. | | Shell automation | `bash`, `jq`, `curl`, `openssl`, `sha256sum`/`shasum` | Feed polling, signing, checksum generation, release checks. | @@ -45,7 +45,7 @@ | Ruff | `ruff check utils/` | Python style and bug pattern checks. | | Bandit | `bandit -r utils/ -ll` | Python security checks. | | Trivy | Workflow + optional local run | FS/config vulnerability scans. | -| Gitleaks | Workflow + optional local run | Secret leak detection. | +| Gitleaks | `scripts/prepare-to-push.sh` optional local run | Secret leak detection before push. | ## Example Snippets ```json diff --git a/wiki/migration-signed-feed.md b/wiki/migration-signed-feed.md index 26e1455..543d9db 100644 --- a/wiki/migration-signed-feed.md +++ b/wiki/migration-signed-feed.md @@ -1,26 +1,30 @@ -# Migration Plan: Unsigned Feed β†’ Signed Feed +# Migration Record: Unsigned Feed β†’ Signed Feed (Completed) -## 1) Objective +## 1) Objective and Status -Move ClawSec advisory distribution from unsigned `feed.json` delivery to detached-signature verification with minimal disruption. +Document how ClawSec advisory distribution moved from unsigned `feed.json` delivery to detached-signature verification, with compatibility preserved for legacy clients. -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 +Current status on `main`: +- Signed feed publishing is active in advisory workflows and deploy workflow. +- Suite and NanoClaw consumers default to signed feed endpoints. +- Unsigned behavior exists only as explicit compatibility bypass (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`). -## 2) Baseline (today) +## 2) Baseline (today, post-migration) Current feed paths in active use: - Source of truth: `advisories/feed.json` +- Source signature: `advisories/feed.json.sig` - Skill copy: `skills/clawsec-feed/advisories/feed.json` +- Skill copy signature: `skills/clawsec-feed/advisories/feed.json.sig` - Pages copy: `public/advisories/feed.json` -- Latest mirror copy: `public/releases/latest/download/advisories/feed.json` +- Pages signature: `public/advisories/feed.json.sig` +- Latest mirror copy: `public/releases/latest/download/advisories/feed.json` (+ `.sig`) 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` +- `skills/clawsec-nanoclaw/lib/advisories.ts` +- default URL: `https://clawsec.prompt.security/advisories/feed.json` ## 3) Migration principles @@ -29,9 +33,9 @@ Current consumer defaults: - **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 +## 4) Phased timeline (historical) -### Phase 0 β€” Preparation (Week 0) +### Phase 0 β€” Preparation (Completed) Deliverables: - signing keys generated and fingerprints recorded @@ -43,7 +47,7 @@ Exit criteria: - key fingerprints verified by reviewer - protected branch/workflow controls enabled -### Phase 1 β€” CI signing enabled, no client enforcement (Week 1) +### Phase 1 β€” CI signing enabled, no client enforcement (Completed) Implement: - add feed signing step/workflow to produce `advisories/feed.json.sig` @@ -58,7 +62,7 @@ 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) +### Phase 2 β€” Consumer dual-read/dual-verify support (Completed) Implement in consumers: - read `feed.json` and `feed.json.sig` @@ -74,7 +78,7 @@ Exit criteria: - verification logic released and tested - no false-positive verification failures in soak period -### Phase 3 β€” Enforcement (Week 3) +### Phase 3 β€” Enforcement (Completed) Actions: - disable temporary unsigned fallback behavior in default paths @@ -85,7 +89,7 @@ Exit criteria: - all production clients verify signatures by default - no unsigned feed dependency in standard installation flow -### Phase 4 β€” Stabilization (Week 4) +### Phase 4 β€” Stabilization (Ongoing) Actions: - run first key rotation tabletop drill diff --git a/wiki/modules/automation-release.md b/wiki/modules/automation-release.md index 0424dbc..4d1e009 100644 --- a/wiki/modules/automation-release.md +++ b/wiki/modules/automation-release.md @@ -8,10 +8,12 @@ ## Key Files - `.github/workflows/ci.yml`: lint/type/build/security/test matrix. +- `.github/workflows/pages-verify.yml`: PR-only Pages build/signing verification (no publish). - `.github/workflows/poll-nvd-cves.yml`: daily NVD advisory ingestion. - `.github/workflows/community-advisory.yml`: issue-label-driven advisory publishing. - `.github/workflows/skill-release.yml`: release validation, packaging, signing, and publishing. - `.github/workflows/deploy-pages.yml`: site build + asset mirroring to GitHub Pages. +- `.github/workflows/wiki-sync.yml`: syncs repository `wiki/` into GitHub Wiki. - `.github/actions/sign-and-verify/action.yml`: shared Ed25519 sign/verify composite action. - `scripts/prepare-to-push.sh`: local CI-like quality gate. - `scripts/release-skill.sh`: manual helper for version bump + tag workflow. @@ -20,10 +22,12 @@ | Interface | Trigger | Outcome | | --- | --- | --- | | CI workflow | Push/PR on `main` | Fails fast on lint/type/build/test/security regressions. | +| Pages Verify workflow | PR on `main` | Validates Pages build/signing artifacts without production deploy. | | NVD poll workflow | Cron + dispatch | Updates advisory feed with deduped, normalized CVEs. | | Community advisory workflow | Issue labeled `advisory-approved` | Opens PR adding signed advisory records. | -| Skill release workflow | Tag `-v*` | Creates GitHub release assets and signatures. | +| Skill release workflow | Metadata PR changes + tag `-v*` | PR dry-run/version checks and tagged release publishing. | | Deploy pages workflow | Successful CI/release run | Publishes site + mirrored artifacts to Pages. | +| Sync wiki workflow | Push `wiki/**` on `main` | Publishes repository wiki content into GitHub Wiki remote. | ## Inputs and Outputs Inputs/outputs are summarized in the table below. @@ -83,6 +87,8 @@ on: - .github/workflows/community-advisory.yml - .github/workflows/skill-release.yml - .github/workflows/deploy-pages.yml +- .github/workflows/pages-verify.yml +- .github/workflows/wiki-sync.yml - .github/workflows/codeql.yml - .github/workflows/scorecard.yml - .github/actions/sign-and-verify/action.yml diff --git a/wiki/modules/frontend-web.md b/wiki/modules/frontend-web.md index fa75a2c..6003cf4 100644 --- a/wiki/modules/frontend-web.md +++ b/wiki/modules/frontend-web.md @@ -2,6 +2,7 @@ ## Responsibilities - Render the ClawSec website for home, skills catalog/detail, and advisory feed/detail experiences. +- Render repository wiki content from `wiki/` markdown and expose per-page `llms.txt` links. - Provide resilient JSON fetch behavior that handles SPA HTML fallback cases. - Display install commands, checksums, and advisory metadata in a browser-focused UX. @@ -13,6 +14,7 @@ - `pages/SkillDetail.tsx`: Loads `skill.json`, checksums, README/SKILL docs with markdown renderer. - `pages/FeedSetup.tsx`: Advisory listing UI with pagination. - `pages/AdvisoryDetail.tsx`: Advisory deep-dive view and source links. +- `pages/WikiBrowser.tsx`: In-app wiki renderer with wiki-page and `llms.txt` links. - `components/Layout.tsx` + `components/Header.tsx`: Shared shell and nav behavior. ## Public Interfaces @@ -22,11 +24,14 @@ - `/skills/:skillId` - `/feed` - `/feed/:advisoryId` + - `/wiki/*` - Static fetch targets: - `/skills/index.json` - `/skills//skill.json` - `/skills//checksums.json` - `/advisories/feed.json` + - `/wiki/llms.txt` + - `/wiki//llms.txt` - Display contracts: - `SkillMetadata`, `SkillJson`, `SkillChecksums`, `AdvisoryFeed`, `Advisory` from `types.ts`. @@ -46,6 +51,7 @@ Inputs/outputs are summarized in the table below. - `vite.config.ts` (port, host, path alias) - `index.html` Tailwind config + custom fonts/colors - `constants.ts` (`ADVISORY_FEED_URL`, `LOCAL_FEED_PATH`) +- Wiki markdown source lives in `wiki/`; `scripts/generate-wiki-llms.mjs` generates `public/wiki/**/llms.txt` (via `predev`/`prebuild`). - Runtime behavior assumptions: - JSON responses may be empty or HTML fallback and must be validated. - Advisory list pagination uses `ITEMS_PER_PAGE = 9`. @@ -66,6 +72,7 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r // Route map defined in App.tsx } /> } /> +} /> ``` ## Edge Cases @@ -89,6 +96,7 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r - pages/SkillDetail.tsx - pages/FeedSetup.tsx - pages/AdvisoryDetail.tsx +- pages/WikiBrowser.tsx - pages/Checksums.tsx - components/Layout.tsx - components/Header.tsx @@ -96,3 +104,4 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r - types.ts - vite.config.ts - index.html +- scripts/generate-wiki-llms.mjs diff --git a/wiki/modules/nanoclaw-integration.md b/wiki/modules/nanoclaw-integration.md index b930ae8..7b887d9 100644 --- a/wiki/modules/nanoclaw-integration.md +++ b/wiki/modules/nanoclaw-integration.md @@ -76,7 +76,7 @@ if (baseline.mode === 'restore' && autoRestore) { | Test Scope | File/Path | Notes | | --- | --- | --- | | Type contracts | `skills/clawsec-nanoclaw/lib/types.ts` | Defines tool/IPC DB payload contracts. | -| Operational docs | `docs/SKILL_SIGNING.md`, `docs/INTEGRITY.md` | Describes verification/integrity usage patterns. | +| Operational docs | `skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md`, `skills/clawsec-nanoclaw/docs/INTEGRITY.md` | Describes verification/integrity usage patterns. | | Cross-module behavior | Reuses suite verification patterns | Signature/checksum primitives ported from suite logic. | ## Source References diff --git a/wiki/overview.md b/wiki/overview.md index 5393fe2..9f5da14 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -24,11 +24,12 @@ | Entry | Type | Purpose | | --- | --- | --- | | `index.tsx` | Frontend bootstrap | Mounts React app into `#root`. | -| `App.tsx` | Frontend router | Defines route map for home, skills, and feed pages. | +| `App.tsx` | Frontend router | Defines route map for home, skills, feed, and wiki pages. | | `scripts/prepare-to-push.sh` | Dev workflow | Runs lint/type/build/security checks before push. | | `scripts/populate-local-feed.sh` | Data bootstrap | Pulls CVEs from NVD and updates local advisory feeds. | | `scripts/populate-local-skills.sh` | Data bootstrap | Builds `public/skills/index.json` and per-skill checksums. | -| `.github/workflows/skill-release.yml` | Release entry | Handles tag-based skill packaging/signing/release. | +| `scripts/generate-wiki-llms.mjs` | Docs export | Generates `public/wiki/llms.txt` and per-page wiki exports. | +| `.github/workflows/skill-release.yml` | Release entry | Handles PR version-parity/dry-run checks and tag-based packaging/signing/release. | | `.github/workflows/poll-nvd-cves.yml` | Scheduled feed updates | Polls NVD and updates advisories. | ## Key Artifacts @@ -37,7 +38,8 @@ | `advisories/feed.json` | NVD poll + community advisory workflows | Web UI, clawsec-suite hook, installers. | | `advisories/feed.json.sig` | Signing workflow steps | Signature verification in suite/nanoclaw tooling. | | `public/skills/index.json` | Deploy workflow / local populate script | `pages/SkillsCatalog.tsx` and `pages/SkillDetail.tsx`. | -| `public/checksums.json` + `public/checksums.sig` | Deploy workflow | Client-side integrity verification flows. | +| `public/wiki/llms.txt` + `public/wiki/**/llms.txt` | Wiki generator script + build hooks | LLM-ready wiki exports linked from the wiki UI. | +| `public/checksums.json` + `public/checksums.sig` | Deploy workflow | Published integrity artifacts for operators and runtime clients. | | `release-assets/checksums.json` | Skill release workflow | Release consumers verifying zip integrity. | | `skills/*/skill.json` | Skill authors | Site catalog generation, validators, and release pipelines. | @@ -68,7 +70,7 @@ npm run build - Read `README.md` for product positioning and install paths. - Open `App.tsx` and `pages/` to understand user-facing behavior. - Open `skills/clawsec-suite/skill.json` to understand the suite contract and embedded components. -- Review `.github/workflows/ci.yml`, `.github/workflows/skill-release.yml`, and `.github/workflows/deploy-pages.yml` for production behavior. +- Review `.github/workflows/ci.yml`, `.github/workflows/pages-verify.yml`, `.github/workflows/skill-release.yml`, `.github/workflows/deploy-pages.yml`, and `.github/workflows/wiki-sync.yml` for production behavior. ## How to Navigate - UI behavior is centered in `pages/`; visual wrappers sit in `components/`. @@ -101,5 +103,7 @@ npm run build - scripts/populate-local-skills.sh - skills/clawsec-suite/skill.json - .github/workflows/ci.yml +- .github/workflows/pages-verify.yml - .github/workflows/skill-release.yml - .github/workflows/deploy-pages.yml +- .github/workflows/wiki-sync.yml diff --git a/wiki/security-signing-runbook.md b/wiki/security-signing-runbook.md index 4ad8f47..74d999a 100644 --- a/wiki/security-signing-runbook.md +++ b/wiki/security-signing-runbook.md @@ -11,22 +11,26 @@ It covers: - key rotation and revocation - incident response -## 2) Current branch reality (important) +## 2) Current operating state (important) -As of branch `integration/signing-work`, advisory distribution is **unsigned**: +On `main`, advisory and release channels are signed and verified by default: - 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 + - `.github/workflows/poll-nvd-cves.yml` updates `advisories/feed.json` and signs `advisories/feed.json.sig` + - `.github/workflows/community-advisory.yml` does the same for approved issue reports + - both sync signed feed artifacts into `skills/clawsec-feed/advisories/` - Feed publish path: - - `.github/workflows/deploy-pages.yml` copies to `public/advisories/feed.json` - - also mirrors to `public/releases/latest/download/advisories/feed.json` + - `.github/workflows/deploy-pages.yml` publishes `public/advisories/feed.json` + `.sig` + - generates and signs `public/checksums.json` + `public/checksums.sig` + - publishes canonical key as `public/signing-public.pem` and `public/advisories/feed-signing-public.pem` + - mirrors compatibility artifacts under `public/releases/latest/download/` (including `feed.json`, `feed.json.sig`, `checksums.json`, `checksums.sig`, `signing-public.pem`) - 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` + - `skills/clawsec-nanoclaw/lib/advisories.ts` + - default feed URL is `https://clawsec.prompt.security/advisories/feed.json` -This document defines the **target operating model** for signed artifacts while preserving compatibility during migration. +Unsigned mode remains an explicit compatibility bypass (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) and is not the steady-state operating model. ## 3) Target signed artifacts @@ -35,10 +39,10 @@ This document defines the **target operating model** for signed artifacts while - `advisories/feed.json.sig` (detached Ed25519 signature; base64) - `advisories/feed-signing-public.pem` (pinned public key) -### Release artifact channel (recommended) +### Release artifact channel - `/checksums.json` - `/checksums.sig` -- `advisories/release-signing-public.pem` (or equivalent repo-pinned location) +- `/signing-public.pem` ## 4) Key roles and custody @@ -108,7 +112,7 @@ openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/pr ## 7) Workflow integration points -This repo already has feed mutation and deployment workflows. Signing should be inserted as a post-mutation, pre-publish control. +This repo enforces signing as a post-mutation, pre-publish control. ### Feed pipeline @@ -116,29 +120,31 @@ 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 +Current behavior: +- workflow step signs `advisories/feed.json` into `advisories/feed.json.sig` +- signing action verifies generated signatures during workflow execution +- signed artifacts are committed via PR automation ### 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 +Current behavior: +- copies payload/signature to `public/advisories/` +- generates + signs `public/checksums.json` and `public/checksums.sig` +- publishes signing key to `public/signing-public.pem` and `public/advisories/feed-signing-public.pem` +- mirrors advisory + signature/checksum/key companions into `public/releases/latest/download/` compatibility paths ### Skill release pipeline (recommended hardening) Current release generator: -- `.github/workflows/skill-release.yml` creates `checksums.json` +- `.github/workflows/skill-release.yml` -Target update: -- sign `checksums.json` before `softprops/action-gh-release` -- attach `checksums.sig` to each release +Current behavior: +- creates `checksums.json`, signs it as `checksums.sig`, and verifies signature before publish +- includes `signing-public.pem` in release assets +- validates generated public-key fingerprint against canonical key material ## 8) Rotation policy and runbook @@ -206,9 +212,9 @@ For each release cycle or feed-signing run, retain: - operator/reviewer approvals - any exception or bypass rationale -## 11) Minimum acceptance criteria before enforcement +## 11) Minimum acceptance criteria before stricter policy changes -Before requiring signatures in all clients: +Before tightening policy further (for example, removing compatibility bypass paths): - 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 diff --git a/wiki/security.md b/wiki/security.md index 36d0f39..7b572fb 100644 --- a/wiki/security.md +++ b/wiki/security.md @@ -23,7 +23,8 @@ | Integrity baseline monitor | `soul-guardian` + NanoClaw integrity monitor | Drift detection, quarantine, restore, auditable history. | ## Supply-Chain and CI Controls -- CI runs Trivy, npm audit, gitleaks, CodeQL, and Scorecard workflows. +- CI runs Trivy, npm audit, CodeQL, and Scorecard workflows. +- Local pre-push checks can run `gitleaks detect` when `gitleaks` is installed. - Release workflows validate SBOM file existence before packaging. - Deploy workflow verifies generated signing key fingerprint against canonical key material. - Release docs include manual verification commands for downstream consumers. diff --git a/wiki/testing.md b/wiki/testing.md index 7833040..61f5332 100644 --- a/wiki/testing.md +++ b/wiki/testing.md @@ -13,7 +13,8 @@ | Skill unit tests | `node skills//test/*.test.mjs` | Signature, matching, suppression, installer contracts. | | Python quality | `ruff check utils/`, `bandit -r utils/ -ll` | Utility correctness and security patterns. | | Shell/script quality | ShellCheck + manual script smoke runs | Script hygiene and command robustness. | -| CI security scans | Trivy, npm audit, gitleaks, CodeQL, Scorecard | Dependency, config, and supply-chain security posture. | +| CI security scans | Trivy, npm audit, CodeQL, Scorecard | Dependency, config, and supply-chain security posture. | +| Local pre-push security scan | optional `gitleaks detect` via `scripts/prepare-to-push.sh` | Secret leak detection before push. | ## Skill Test Matrix | Skill | Test Files | Primary Focus | diff --git a/wiki/workflow.md b/wiki/workflow.md index c61bc01..599cde6 100644 --- a/wiki/workflow.md +++ b/wiki/workflow.md @@ -3,18 +3,22 @@ ## End-to-End Lifecycle - Development starts with local coding + local data population for realistic UI preview. - PR CI validates quality/security and skill test suites. +- PR Pages-verify validates production build/signing behavior without publishing. - Tag-driven release workflow packages and signs skill artifacts. - Pages deploy workflow mirrors release/advisory artifacts and publishes the static site. +- Wiki-sync workflow publishes repo `wiki/` docs to GitHub Wiki on `main`. - Scheduled workflows continuously enrich advisory feed and supply-chain visibility. ## Primary Workflow Map | Workflow | Trigger | Main Steps | | --- | --- | --- | | CI | PR/push to `main` | Lint, typecheck, build, Python checks, security scans, skill tests. | +| Pages Verify | PRs to `main` | Build Pages artifact and validate signing outputs (no publish). | | Poll NVD CVEs | Daily cron + manual dispatch | Fetch CVEs, transform/dedupe, update feed, sign artifacts, PR changes. | | Process Community Advisory | Issue label `advisory-approved` | Parse issue form, create advisory, sign feed, open PR, comment issue. | -| Skill Release | Tag `-v*` | Validate versions, package SBOM files, sign checksums, publish release. | +| Skill Release | Skill tags + metadata PR changes | PR: version-parity + dry-run checks; tags: package/sign/publish release assets. | | Deploy Pages | Successful CI/Release or manual dispatch | Discover releases, mirror assets, sign public advisories/checksums, deploy site. | +| Sync Wiki | Pushes to `main` touching `wiki/**` + manual dispatch | Sync `wiki/` into `.wiki.git` and generate `Home.md` from `INDEX.md`. | ## Local Operator Workflow | Step | Command | Outcome | @@ -22,6 +26,7 @@ | Install deps | `npm install` | Ready local environment. | | Populate local catalog | `./scripts/populate-local-skills.sh` | `public/skills/index.json` and file checksums. | | Populate local feed | `./scripts/populate-local-feed.sh --days 120` | Updated local advisory feed copy. | +| Generate wiki llms exports | `npm run gen:wiki-llms` | Updates `public/wiki/llms.txt` and per-page exports. | | Run local gate | `./scripts/prepare-to-push.sh` | CI-like pass/fail signal. | | Start dev UI | `npm run dev` | Browser preview at local Vite endpoint. | @@ -64,11 +69,14 @@ on: - scripts/prepare-to-push.sh - scripts/populate-local-feed.sh - scripts/populate-local-skills.sh +- scripts/generate-wiki-llms.mjs - .github/workflows/ci.yml - .github/workflows/poll-nvd-cves.yml - .github/workflows/community-advisory.yml - .github/workflows/skill-release.yml - .github/workflows/deploy-pages.yml +- .github/workflows/pages-verify.yml +- .github/workflows/wiki-sync.yml - .github/workflows/codeql.yml - .github/workflows/scorecard.yml - .github/actions/sign-and-verify/action.yml From fe5585b2332c16416d48b5f151a47f3abf0b0996 Mon Sep 17 00:00:00 2001 From: David Abutbul Date: Thu, 26 Feb 2026 11:23:29 +0200 Subject: [PATCH 2/2] fix(feed): align frontend advisory URL with canonical endpoint --- README.md | 3 +++ constants.ts | 8 +++++--- pages/AdvisoryDetail.tsx | 12 ++++++++++-- pages/FeedSetup.tsx | 14 +++++++++++--- wiki/modules/frontend-web.md | 2 +- 5 files changed, 30 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1245b09..96e24fb 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,9 @@ ClawSec maintains a continuously updated security advisory feed, automatically p curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")' ``` +Canonical endpoint: `https://clawsec.prompt.security/advisories/feed.json` +Compatibility mirror (legacy): `https://clawsec.prompt.security/releases/latest/download/feed.json` + ### Monitored Keywords The feed polls CVEs related to: diff --git a/constants.ts b/constants.ts index 0f5c909..8a58d92 100644 --- a/constants.ts +++ b/constants.ts @@ -1,7 +1,9 @@ -// Feed URL for fetching live advisories -export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json'; +// Canonical hosted feed endpoint for fetching live advisories +export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/advisories/feed.json'; + +// Compatibility mirror for legacy clients; keep as last-resort fallback only +export const LEGACY_ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json'; // Local feed path for development export const LOCAL_FEED_PATH = '/advisories/feed.json'; - diff --git a/pages/AdvisoryDetail.tsx b/pages/AdvisoryDetail.tsx index bcef9a0..1c2cfa6 100644 --- a/pages/AdvisoryDetail.tsx +++ b/pages/AdvisoryDetail.tsx @@ -3,7 +3,11 @@ import { useParams, Link } from 'react-router-dom'; import { ArrowLeft, ExternalLink, Shield, AlertTriangle, Github, User, Bot } from 'lucide-react'; import { Footer } from '../components/Footer'; import { Advisory, AdvisoryFeed } from '../types'; -import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants'; +import { + ADVISORY_FEED_URL, + LEGACY_ADVISORY_FEED_URL, + LOCAL_FEED_PATH, +} from '../constants'; export const AdvisoryDetail: React.FC = () => { const { advisoryId } = useParams<{ advisoryId: string }>(); @@ -16,13 +20,17 @@ export const AdvisoryDetail: React.FC = () => { if (!advisoryId) return; try { - // Try local feed first (for development), then fall back to GitHub releases + // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror. let response = await fetch(LOCAL_FEED_PATH); if (!response.ok) { response = await fetch(ADVISORY_FEED_URL); } + if (!response.ok) { + response = await fetch(LEGACY_ADVISORY_FEED_URL); + } + if (!response.ok) { throw new Error(`Failed to fetch feed: ${response.status}`); } diff --git a/pages/FeedSetup.tsx b/pages/FeedSetup.tsx index a86a26c..9c03c76 100644 --- a/pages/FeedSetup.tsx +++ b/pages/FeedSetup.tsx @@ -4,7 +4,11 @@ import { Link } from 'react-router-dom'; import { Footer } from '../components/Footer'; import { AdvisoryCard } from '../components/AdvisoryCard'; import { Advisory, AdvisoryFeed } from '../types'; -import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants'; +import { + ADVISORY_FEED_URL, + LEGACY_ADVISORY_FEED_URL, + LOCAL_FEED_PATH, +} from '../constants'; const ITEMS_PER_PAGE = 9; @@ -21,13 +25,17 @@ export const FeedSetup: React.FC = () => { setError(null); try { - // Try local feed first (for development), then fall back to GitHub releases + // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror. let response = await fetch(LOCAL_FEED_PATH); - + if (!response.ok) { response = await fetch(ADVISORY_FEED_URL); } + if (!response.ok) { + response = await fetch(LEGACY_ADVISORY_FEED_URL); + } + if (!response.ok) { throw new Error(`Failed to fetch feed: ${response.status}`); } diff --git a/wiki/modules/frontend-web.md b/wiki/modules/frontend-web.md index 6003cf4..b8d5ae3 100644 --- a/wiki/modules/frontend-web.md +++ b/wiki/modules/frontend-web.md @@ -42,7 +42,7 @@ Inputs/outputs are summarized in the table below. | --- | --- | --- | --- | | Input | Skills index JSON | `/skills/index.json` | List of published skills and metadata. | | Input | Skill payload files | `/skills//skill.json`, markdown docs, `checksums.json` | Detail-page content and integrity table. | -| Input | Advisory feed JSON | `/advisories/feed.json` or remote URL fallback | Advisory list/detail content. | +| Input | Advisory feed JSON | `/advisories/feed.json`, then `https://clawsec.prompt.security/advisories/feed.json` (legacy mirror fallback to `/releases/latest/download/feed.json`) | Advisory list/detail content. | | Output | Route-specific UI states | Browser view state | Loading, empty, error, and populated experiences. | | Output | Copy-to-clipboard commands | Clipboard API | Install and checksum snippets copied for users. |