mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-01 15:52:26 +03:00
docs: refresh README, contributing guide, and wiki accuracy (#81)
* docs(repo): refresh docs and wiki alignment * fix(feed): align frontend advisory URL with canonical endpoint
This commit is contained in:
davida-ps
GitHub
@@ -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-name>/` (`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/<skill>/test/<name>.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>/skill.json` and `skills/<skill>/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.
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
## Secure Your OpenClaw Bots with a Complete Security Skill Suite
|
||||
## Secure Your OpenClaw and NanoClaw Agents with a Complete Security Skill Suite
|
||||
|
||||
<h4>Brought to you by <a href="https://prompt.security">Prompt Security</a>, the Platform for AI Security</h4>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -188,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:
|
||||
@@ -233,7 +240,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 +255,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** | `<skill>-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 +272,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 +388,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 +412,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 +422,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 +471,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 (`<repo>.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/<page>/llms.txt` is the LLM-ready export for that single wiki page.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
+5
-3
@@ -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';
|
||||
|
||||
|
||||
@@ -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}`);
|
||||
}
|
||||
|
||||
+11
-3
@@ -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}`);
|
||||
}
|
||||
|
||||
@@ -81,6 +81,7 @@ flowchart TD
|
||||
<Route path="/skills/:skillId" element={<SkillDetail />} />
|
||||
<Route path="/feed" element={<FeedSetup />} />
|
||||
<Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
|
||||
<Route path="/wiki/*" element={<WikiBrowser />} />
|
||||
</Routes>
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 `<skill>-v*` | Creates GitHub release assets and signatures. |
|
||||
| Skill release workflow | Metadata PR changes + tag `<skill>-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
|
||||
|
||||
@@ -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>/skill.json`
|
||||
- `/skills/<skill>/checksums.json`
|
||||
- `/advisories/feed.json`
|
||||
- `/wiki/llms.txt`
|
||||
- `/wiki/<page>/llms.txt`
|
||||
- Display contracts:
|
||||
- `SkillMetadata`, `SkillJson`, `SkillChecksums`, `AdvisoryFeed`, `Advisory` from `types.ts`.
|
||||
|
||||
@@ -37,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/<id>/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. |
|
||||
|
||||
@@ -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
|
||||
<Route path="/skills/:skillId" element={<SkillDetail />} />
|
||||
<Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
|
||||
<Route path="/wiki/*" element={<WikiBrowser />} />
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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
|
||||
|
||||
+8
-4
@@ -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
|
||||
|
||||
@@ -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
|
||||
- `<release>/checksums.json`
|
||||
- `<release>/checksums.sig`
|
||||
- `advisories/release-signing-public.pem` (or equivalent repo-pinned location)
|
||||
- `<release>/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
|
||||
|
||||
+2
-1
@@ -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.
|
||||
|
||||
+2
-1
@@ -13,7 +13,8 @@
|
||||
| Skill unit tests | `node skills/<skill>/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 |
|
||||
|
||||
+9
-1
@@ -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 `<skill>-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 `<repo>.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
|
||||
|
||||
Reference in New Issue
Block a user