Skip to content

overview

Jump to bottom
github-actions[bot] edited this page Feb 26, 2026 · 3 revisions

Overview

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.

Prompt Security Logo ClawSec Mascot

Repo Layout

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 Points

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.

Key Artifacts

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.

Key Workflows

  • 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.

Example Snippets

# 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

Where to Start

  • 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.

How to Navigate

  • 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.

Common Pitfalls

  • 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.

Update Notes

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

Source References

  • README.md
  • package.json
  • App.tsx
  • index.tsx
  • pages/Home.tsx
  • pages/SkillsCatalog.tsx
  • pages/SkillDetail.tsx
  • pages/FeedSetup.tsx
  • scripts/prepare-to-push.sh
  • scripts/populate-local-feed.sh
  • 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

Clone this wiki locally