clawsec/wiki/architecture.md

Architecture

System Context

• This page appears under the Start Here section in INDEX.md.
• ClawSec sits between upstream intelligence sources (NVD + community issues), GitHub automation, and runtime agent environments.
• The repository publishes both static site content and signed artifacts that runtime skills verify before using.
• External actor groups:
  • GitHub Actions runners executing CI, release, and feed workflows.
  • OpenClaw/NanoClaw agents consuming skills, advisories, and verification scripts.
  • Repository maintainers approving advisory issues and merging release/tag changes.

Components

Component	Location	Responsibility
Web UI	App.tsx, pages/, components/	Renders skills catalog and advisory detail experiences.
Advisory Feed Core	advisories/feed.json*, skills/clawsec-suite/.../feed.mjs	Stores, verifies, and parses advisories with detached signatures/checksums.
Skill Packages	skills/*/	Distributes installable security capabilities with SBOM metadata.
Local Automation Scripts	scripts/*.sh	Build local mirrors, pre-push checks, and manual release helpers.
CI/CD Workflows	.github/workflows/*.yml	Linting, tests, NVD polling, release packaging, and Pages deploy.
Python Utility Layer	utils/*.py	Skill metadata validation and checksum generation.

Key Flows

• Skill catalog flow:
  1. Release/tag workflows publish skill assets.
  2. Deploy workflow discovers release assets and builds public/skills/index.json.
  3. UI fetches public/skills/index.json and skill docs for /skills pages.
• Advisory feed flow:
  1. poll-nvd-cves.yml and community-advisory.yml update advisories/feed.json.
  2. Feed is signed and mirrored to public paths.
  3. Runtime hooks/scripts load remote feed and fallback to local signed copies.
• Guarded install flow:
  1. Installer requests target skill + version.
  2. Advisory matcher checks affected specifiers and severity/risk hints.
  3. Exit code 42 enforces second confirmation when advisories match.

Diagrams

flowchart TD
  A["NVD + Community Inputs"] --> B["Feed Workflows\n(poll/community)"]
  B --> C["advisories/feed.json + signatures"]
  C --> D["Deploy Workflow Mirrors to public/"]
  D --> E["React UI (catalog/feed pages)"]
  C --> F["clawsec-suite hook + installers"]
  F --> G["Agent advisory alerts / gated install"]

Interfaces and Contracts

Interface	Contract Form	Validation
Skill metadata	skills/*/skill.json	Validated by Python utility + CI version-parity checks.
Advisory feed	JSON + Ed25519 detached signature	Verified by feed.mjs and NanoClaw signature utilities.
Checksums manifest	checksums.json (+ optional .sig)	Parsed and hash-matched before trusting payloads.
Hook event interface	HookEvent (type, action, messages)	Runtime handler only processes selected event names.
Workflow release naming	Tag pattern <skill>-vX.Y.Z	Parsed in release/deploy workflows to discover skills.

Key Parameters

Parameter	Default	Effect
CLAWSEC_FEED_URL	https://clawsec.prompt.security/advisories/feed.json	Remote advisory source for suite scripts/hooks.
CLAWSEC_ALLOW_UNSIGNED_FEED	0	Enables temporary unsigned fallback compatibility.
CLAWSEC_VERIFY_CHECKSUM_MANIFEST	1	Requires checksum manifest verification where available.
CLAWSEC_HOOK_INTERVAL_SECONDS	300	Scan throttling window for advisory hook.
CLAWSEC_SKILLS_INDEX_TIMEOUT_MS	5000	Remote skill index fetch timeout for catalog discovery.
PROMPTSEC_GIT_PULL	0	Optional auto-pull before watchdog audit runs.

Error Handling and Reliability

• Feed fetching is fail-closed for invalid signatures and malformed manifests.
• Remote fetch failures gracefully fall back to local signed feeds.
• Hook state uses atomic file writes with strict mode where supported.
• UI pages detect HTML fallbacks served as JSON and avoid rendering corrupted data.
• Workflow steps enforce key-fingerprint consistency to avoid split-key drift.

Example Snippets

// Route topology in the web app
<Routes>
  <Route path="/" element={<Home />} />
  <Route path="/skills" element={<SkillsCatalog />} />
  <Route path="/skills/:skillId" element={<SkillDetail />} />
  <Route path="/feed" element={<FeedSetup />} />
  <Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
  <Route path="/wiki/*" element={<WikiBrowser />} />
</Routes>

// Guarded feed loading contract in advisory hook
const remoteFeed = await loadRemoteFeed(feedUrl, {
  signatureUrl: feedSignatureUrl,
  checksumsUrl: feedChecksumsUrl,
  checksumsSignatureUrl: feedChecksumsSignatureUrl,
  publicKeyPem,
  checksumsPublicKeyPem: publicKeyPem,
  allowUnsigned,
  verifyChecksumManifest,
});

Runtime and Deployment

Runtime Surface	Execution Model	Output
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 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.

Scaling Notes

• Advisory volume scales with keyword set in NVD polling; dedupe and post-filtering control noise.
• Deploy workflow processes release lists and keeps newest skill versions in index output.
• Module boundaries by skill folder allow adding new security capabilities without changing frontend structure.
• Signature verification paths remain lightweight because payload sizes (feed/manifests) are small.

Source References

• App.tsx
• 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
• skills/clawsec-suite/scripts/discover_skill_catalog.mjs
• skills/clawsec-nanoclaw/lib/advisories.ts
• skills/clawsec-nanoclaw/lib/signatures.ts
• .github/workflows/poll-nvd-cves.yml
• .github/workflows/community-advisory.yml
• .github/workflows/deploy-pages.yml
• .github/workflows/skill-release.yml