mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
David Abutbul
b37162a33d
* feat(i18n): add multilingual wiki scaffolding, language switcher, and translation QA pipeline * docs(readme): adopt picoclaw-style multilingual link bar * fix(i18n): repair localized index links and tighten partial-pair QA * ci(i18n): fail on broken markdown links in README/wiki * ci(i18n): add changed-files mode for markdown link checks * i18n(de): use local Argos MT to fill untranslated German sections * i18n(es,fr): fill untranslated sections via local Argos workflow * i18n(ja): fill untranslated sections with scoped local Argos pass * i18n(ko): fill untranslated sections with scoped local Argos pass * fix(i18n): address review feedback --------- Co-authored-by: David Abutbul <David.a@prompt.security>
115 lines
6.3 KiB
Markdown
115 lines
6.3 KiB
Markdown
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
|
|
Source: ../overview.md
|
|
Review status: draft
|
|
-->
|
|
|
|
# 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.
|
|
|
|
|
|
|
|
|
|
## 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
|
|
```bash
|
|
# local UI + locally populated data
|
|
npm install
|
|
./scripts/populate-local-skills.sh
|
|
./scripts/populate-local-feed.sh --days 120
|
|
npm run dev
|
|
```
|
|
|
|
```bash
|
|
# 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
|