Overview

February 26, 2026 · View on GitHub

Purpose

ClawSec is a security-focused repository that combines a public web catalog with installable security skills for OpenClaw and NanoClaw environments.
The codebase supports three delivery paths at once: static website publishing, signed advisory distribution, and per-skill GitHub release packaging.
Primary users are agent operators, skill developers, and maintainers running CI-based security automation.

ClawSec Mascot

Path	Role	Notes
`pages/`, `components/`, `App.tsx`, `index.tsx`	Vite + React UI	Skill catalog, advisory feed, and detail pages.
`skills/`	Security skill packages	Each skill has `skill.json`, `SKILL.md`, optional scripts/tests/docs.
`advisories/`	Repository advisory channel	Signed `feed.json` + `feed.json.sig` and key material.
`scripts/`	Local automation	Populate feed/skills, pre-push checks, release helpers.
`.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.
`wiki/`	Documentation hub	Architecture, operations runbooks, compatibility, and verification guides.

Entry	Type	Purpose
`index.tsx`	Frontend bootstrap	Mounts React app into `#root`.
`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.
`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.

Artifact	Produced By	Consumed By
`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/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.

Local web development: npm install then npm run dev.
Local security data preview: run ./scripts/populate-local-skills.sh and ./scripts/populate-local-feed.sh before loading /skills and /feed pages.
Pre-push quality gate: run ./scripts/prepare-to-push.sh (optionally --fix).
Skill lifecycle: edit skills/<name>/, validate with python utils/validate_skill.py, then tag <skill>-vX.Y.Z to trigger release workflow.
Advisory lifecycle: scheduled NVD poll and issue-label-based community ingestion both merge into the same signed feed.

# local UI + locally populated data
npm install
./scripts/populate-local-skills.sh
./scripts/populate-local-feed.sh --days 120
npm run dev

# canonical TypeScript quality checks used by CI
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
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/pages-verify.yml, .github/workflows/skill-release.yml, .github/workflows/deploy-pages.yml, and .github/workflows/wiki-sync.yml for production behavior.

UI behavior is centered in pages/; visual wrappers sit in components/.
Skill-specific logic is isolated by folder under skills/; each folder includes its own scripts/tests/docs.
Feed handling appears in three layers: repository feed files, workflow updates, and runtime consumers (clawsec-suite/clawsec-nanoclaw).
Operational quality gates live in scripts/ and workflow YAML files.
For generation traces and update baselines, start from wiki/GENERATION.md and then branch into module pages.

Using literal home tokens (for example \$HOME) in config path env vars can trigger path validation failures.
Fetching JSON from SPA routes can return HTML with status 200; pages guard for this and treat it as empty-state.
Unsigned feed bypass mode (CLAWSEC_ALLOW_UNSIGNED_FEED=1) exists for migration compatibility and should not be used in steady state.
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.

2026-02-26: Updated repo layout to point operational documentation at wiki/ instead of the removed root docs/ directory.