gnezim/clawsec
1
0
Fork 0
mirror of https://github.com/prompt-security/clawsec.git synced 2026-06-01 15:52:26 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(i18n): add multilingual wiki scaffolding, language switcher, and… (#212)

Browse Source 
* 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>
This commit is contained in:
David Abutbul
2026-04-29 09:00:31 +03:00
committed by GitHub
parent 627d20b7e1
commit b37162a33d
105 changed files with 13084 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/i18n-qa.yml
+35
View File
@@ -0,0 +1,35 @@
name: i18n QA
on:
pull_request:
branches: [main]
paths:
- 'README*.md'
- 'wiki/**/*.md'
- 'scripts/i18n/**'
- '.github/workflows/i18n-qa.yml'
workflow_dispatch:
permissions: read-all
jobs:
i18n-qa:
name: Translation Integrity Checks
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
python-version: '3.12'
- name: Run i18n QA
run: python scripts/i18n/qa_check.py
- name: Check markdown links (README/wiki)
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
python scripts/i18n/link_check.py --changed-only --base-ref "origin/${{ github.base_ref }}"
else
python scripts/i18n/link_check.py
fi
README.de.md
+434
View File
@@ -0,0 +1,434 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: README.md
Review status: draft
-->
# Deutsch Translation Scaffold
This file is currently a draft scaffold. Use README.md as the canonical source.
<h1 align="center">
<img src="/img/prompt-icon.svg" alt="prompt-icon" breit="40">
ClawSec: Security Skill Suite für KI-Agenten
<img src="/img/prompt-icon.svg" alt="prompt-icon" breit="40">
</h1>
<div align="center">
Sichern Sie Ihre OpenClaw, NanoClaw und Hermes Agents mit einer kompletten Sicherheits-Fähigkeits-Suite
<h4>Brought to you von <a href="https://prompt.security">Prompt Security</a>, the Platform of AI Security</h4>
</div>
<div align="center">
![Prompt Security Logo](./img/Black+Color.png)
<img src="/public/img/mascot.png" alt="clawsec mascot" breit="200" />
</div>
<div align="center">
🌐 **Live at: [https://clawsec.prompt.security](https://clawsec.prompt.security)[https://prompt.security/clawsec](https://prompt.security/clawsec)**
[![CI](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml)
[![Deploy Pages](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml)
[![Poll NVD CVEs](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml)
</div>
--
Übersetzungen
- Español: [README.es.md](README.es.md)
- 한국어: [README.ko.md](README.ko.md)
Was ist ClawSec?
ClawSec ist eine ** umfassende Sicherheits-Fähigkeits-Suite für AI-Agent-Plattformen*. Es bietet eine einheitliche Sicherheitsüberwachung, Integritätsprüfung und Bedrohung Intelligenz-Schutz der kognitiven Architektur Ihres Agenten gegen schnelle Injektion, Drift und schädliche Anweisungen.
### Unterstützte Plattformen
- **OpenClaw** (MoltBot, Clawdbot und Klone) - Komplette Suite mit Skill-Installer, Dateiintegritätsschutz und Sicherheitsaudits
- **NanoKlaue** - Gebindet App-Bot-Sicherheit mit MCP-Tools für die Überwachung, Unterschriftsprüfung und Dateiintegrität
- **Hermes** - Hermes-native Sicherheitskompetenzen für eine unterzeichnete Beratungs-Feed-Verifikation, beratungssichere Verifikation, deterministische Attestations-Generierung, fehlgeschlossene Verifikation und grundlegende Drifterkennung
- **Picoclaw** - Leichte AI-Gateway-Sicherheitsüberprüfungen mit Beratendem Bewusstsein, config Drift-Erkennung, Release-artifact-Verifikation und einem optionalen separaten Selbst-Pen-Testpaket
### Skill Feature Matrix
| Skill name | unterstützte Plattform| Sicherheits-Feed-Verifikation- config Drift | Agent Self Pen-Tests- Supply-Chain-Verifikation |
...
| claw-release | OpenClaw | Nein | Nein | Nein | Nein | Ja |
| clawsec-clawhub-checker | OpenClaw + clawsec-suite Integration | Nein | Nein | Nein | Ja |
| clawsec-feed | OpenClaw | Ja | Nein | Nein | Ja |
Ja | Ja | Ja | Ja | Ja | Ja |
| clawsec-scanner | OpenClaw | Ja | Nein | Ja | Ja | Ja |
| clawsec-suite | OpenClaw | Ja | Ja | Nein | Ja |
| Clawtributor | OpenClaw | Ja | Nein | Nein
| hermes-attestation-guardian | Hermes | Ja (signierte beratende Feed-Verifikation) | Ja | Nein | Limited (nur Vorabbeleuchtung; keine Artefaktsignatur/provenance install-Verifikation) |
| Openclaw-audit-watchdog | OpenClaw | Nein | Nein | Ja | Nein
| Picoclaw-security-guardian | Picoclaw | Ja | Ja | Nein
| Picoclaw-self-pen-testing
| Seelenhüter | OpenClaw | Nein | Nein | Nein
### Core Caps
- **📦 Suite Installer** - One-Command-Installation aller Sicherheitsfertigkeiten mit Integritätsprüfung
- **🛡️ Datei-Integrity-Schutz* - Drift-Erkennung und Auto-Restore für kritische Agent-Dateien (SOUL.md, IDENTITY.md, etc.)
- **📡 Live Security Advisories* - Automatisierte NVD CVE Umfragen und Community-Drohung Intelligenz
- **🔍 Security Audits** - Self-Check-Skripte, um schnelle Injektionsmarker und Schwachstellen zu erkennen
- **🔐 Prüfsummenverifikation** - SHA256 Prüfsummen für alle Fähigkeiten Artefakte
- **Health Checks* - Automatisierte Updates und Integritätsprüfung für alle installierten Fähigkeiten
--
Produktdemonstrationen
Animierte Vorschauen unten sind GIFs (keine Audio). Klicken Sie auf jede Vorschau, um das volle MP4 mit Audio zu öffnen.
### Demo installieren (`clawsec-suite`)
[![Install demo animated preview](public/video/install-demo-preview.gif)(öffentlich/video/install-demo.mp4)
Direkter Link: [install-demo.mp4](public/video/install-demo.mp4)
### Drift Detection Demo (`soul-guardian`)
[![Drift detection animated preview](public/video/soul-guardian-demo-preview.gif)(öffentlich/video/soul-guardian-demo.mp4)
Direkter Link: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4)
--
🚀 Schneller Start
### For AI Agents
```bash
# Install the ClawSec security suite
npx clawhub@latest install clawsec-suite
```
Nach der Installation kann die Suite:
ANHANG Entdecken Sie installierbare Schutze aus dem veröffentlichten Kompetenzkatalog
2. Verifizieren Sie die Freigabeintegrität mit unterzeichneten Prüfsummen
3. Einrichtung von Beratungs- und hakenbasierten Schutzströmen
4. Optionale geplante Überprüfungen hinzufügen
Manual/source-first option:
> Weiterlesen https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md und folgen den Installationsanweisungen.
### For Humans
Kopieren Sie diese Anleitung zu Ihrem KI-Agent:
> Installieren Sie ClawSec mit `npx clawhub@latest install clawsec-suite`, füllen Sie dann die Setup-Schritte aus den generierten Anweisungen aus.
### Shell and OS Notes
ClawSec-Skripte werden aufgeteilt zwischen:
- Cross-Plattform Node/Python-Tooling (`npm run build`, Haken/Setup `.mjs`_ `utils/*.py`_
- POSIX Shell Workflows (`*.sh`, die meisten manuellen Installationsschnipsel)
Für Linux/macOS (`bash`/`zsh`):
- Verwenden Sie nicht zitiertes oder doppelt zitiertes Zuhause vars: `export INSTALL_ROOT="$HOME/.openclaw/skills"`
- Do **not** Einquoten-Expandierbare Vars (zum Beispiel `'$HOME/.openclaw/skills'`)
Für Windows (PowerShell):
- Präferen Sie explizite Pfadaufbau:
- Was?
- Was?
- POSIX `.sh` Skripte benötigen WSL oder Git Bash.
Fehlerbehebung: Wenn Sie Verzeichnisse wie `~/.openclaw/workspace/$HOME/...` sehen, wurde eine Heimvariable buchstäblich übergeben. Re-run mit einem absoluten Pfad oder einem nicht zitierten Heimausdruck.
--
Plattform & Suite Dokumentation
Detaillierte Plattform und Suiten docs live in den Wiki-Modulen:
- NanoClaw: [wiki/modules/nanoclaw-integration.md](wiki/modules/nanoclaw-integration.md)
- Hermes: [wiki/modules/hermes-attestation-guardian.md](wiki/modules/hermes-attestation-guardian.md)
- Picoclaw: [wiki/modules/picoclaw-security-guardian.md](wiki/modules/picoclaw-security-guardian.md)
- Picoclaw Selbstprüfung: [wiki/modules/picoclaw-self-pen-testing.md](wiki/modules/picoclaw-self-pen-testing.md)
- ClawSec Suite (OpenClaw): [wiki/modules/clawsec-suite.md](wiki/modules/clawsec-suite.md)
- CI/CD-Pipelines: [wiki/modules/automation-release.md](wiki/modules/automation-release.md)
Schnelle Installation von Links:
- NanoClaw installiert: [skills/clawsec-nanoclaw/INSTALL.md](skills/clawsec-nanoclaw/INSTALL.md)
- Hermes Geschick Paket: `skills/hermes-attestation-guardian/`
- Picoclaw Schutzpaket: `skills/picoclaw-security-guardian/`
- Picoclaw Selbstprüfungspaket: `skills/picoclaw-self-pen-testing/`
- Suite-Paket: `skills/clawsec-suite/`
--
📡 Sicherheitsberatung Fütterung
ClawSec unterhält einen kontinuierlich aktualisierten Sicherheitsberatungsfeed, der automatisch aus der NIST National Vulnerability Database (NVD) besiedelt wird.
### Feed URL
```bash
# Fetch latest advisories
curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
```
Kanonischer Endpunkt: `https://clawsec.prompt.security/advisories/feed.json`
Kompatibilitätsspiegel (Legalacy): `https://clawsec.prompt.security/releases/latest/download/feed.json`
### Überwachte Keywords
Die Feed-Quoten CVEs bezogen auf:
**OpenClaw Platform**: `OpenClaw`, `clawdbot`__, `Moltbot`
**NanoClaw Platform**: `NanoClaw`____________________________________________________
- **Picoclaw Platform*: `Picoclaw`, `picoclaw`, leichte AI Gateways, MCP Gateway Belichtung
- Prompt Injektionsmuster
- Sicherheitslücken von Agenten
### Exploitability Context
ClawSec bereichert CVE-Advisories mit **-Exploitability-Kontext**, um Agenten dabei zu helfen, das reale Risiko über die rohen CVSS-Score hinaus zu bewerten. Neu analysierte Berater können:
- **Exploit Evidence**: Ob öffentliche Ausbeutungen in der Wildnis existieren
- **Beantwortungsstatus**: Wenn Exploits in gemeinsame Angriffsrahmen integriert werden
- **Anforderungen**: Voraussetzungen für eine erfolgreiche Nutzung (Netzwerkzugriff, Authentifizierung, Benutzerinteraktion)
- **Risikobewertung**: Kontextualisiertes Risikoniveau, das technische Schwere mit Ausbeutbarkeit kombiniert
Diese Funktion hilft Agenten, Schwachstellen zu priorisieren, die unmittelbare Bedrohungen gegenüber theoretischen Risiken darstellen und intelligentere Sicherheitsentscheidungen ermöglichen.
### Advisory Schema
**NVD CVE Beratung:**
```json
{
"id": "CVE-2026-XXXXX",
"severity": "critical|high|medium|low",
"type": "vulnerable_skill",
"platforms": ["openclaw", "nanoclaw"],
"title": "Short description",
"description": "Full CVE description from NVD",
"published": "2026-02-01T00:00:00Z",
"cvss_score": 8.8,
"nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX",
"exploitability_score": "high|medium|low|unknown",
"exploitability_rationale": "Why this CVE is or is not likely exploitable in agent deployments",
"references": ["..."],
"action": "Recommended remediation"
}
```
**Gemeinschaftsbeirat:**
```json
{
"id": "CLAW-2026-0042",
"severity": "high",
"type": "prompt_injection|vulnerable_skill|tampering_attempt",
"platforms": ["nanoclaw"],
"title": "Short description",
"description": "Detailed description from issue",
"published": "2026-02-01T00:00:00Z",
"affected": ["skill-name@1.0.0"],
"source": "Community Report",
"github_issue_url": "https://github.com/.../issues/42",
"action": "Recommended remediation"
}
```
**Platformwerte:**
- `"openclaw"` - OpenClaw/Clawdbot/Molt Nur
- `"nanoclaw"` - NanoClaw nur
- Nur Hermes
- Nur Picoclaw
- `["openclaw", "nanoclaw", "hermes", "picoclaw"]` - Alle Kernplattformen
- (leer/missing) - Alle Plattformen (backward kompatibel)
--
🔄 CI/CD Pipelines
CI/CD Pipelinedetails wurden auf die Wiki-Modulseite verschoben:
- Was?
Ähnliche Arbeitspunkte:
- Was?
- Was?
--
🛠️ Offline Tools
ClawSec umfasst Python utilities für lokale Fähigkeiten Entwicklung und Validierung.
### Skill Validator
Validiert einen Geschicksordner gegen das erforderliche Schema:
```bash
python utils/validate_skill.py skills/clawsec-feed
```
Kontrollen:
- `skill.json` existiert und ist gültig JSON
- Erforderliche Felder vorhanden (Name, Version, Beschreibung, Autor, Lizenz)
- SBOM-Dateien existieren und sind lesbar
- OpenClaw Metadaten sind richtig strukturiert
### Skill Checksums Generator
Erzeugt `checksums.json` mit SHA256 Hashes für ein Geschick:
```bash
python utils/package_skill.py skills/clawsec-feed ./dist
```
Ausgänge:
- `checksums.json` - SHA256 hathes zur Überprüfung
--
Lokale Entwicklung
### Voraussetzungen
- Node.js 20+
- Python 3.10+ (für Offline-Tools)
- npm
### Setup
```bash
# Install dependencies
npm install
# Start development server
npm run dev
```
### Lokale Daten ausfüllen
```bash
# Populate skills catalog from local skills/ directory
./scripts/populate-local-skills.sh
# Populate advisory feed with real NVD CVE data
./scripts/populate-local-feed.sh --days 120
# 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
```
Anmerkungen:
- `npm run dev` und `npm run build` regenerieren automatisch wiki `llms.txt` Exporte (`predev`_`prebuild` Haken).
- `public/wiki/` wird ausgegeben (lokal + CI) und ist absichtlich gitignored.
### Build
```bash
npm run build
```
--
Projektstruktur
```
├── advisories/
│ ├── feed.json # Main advisory feed
│ ├── feed.json.sig # Detached signature for feed.json
│ └── feed-signing-public.pem # Public key for feed verification
├── components/ # React components
├── pages/ # Route/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
│ ├── prepare-to-push.sh # Local CI-style quality gate
│ ├── validate-release-links.sh # Release link checks
│ └── release-skill.sh # Manual skill release helper
├── skills/
│ ├── claw-release/ # 🚀 Release automation workflow skill
│ ├── clawsec-suite/ # 📦 Suite installer (skill-of-skills)
│ ├── clawsec-feed/ # 📡 Advisory feed skill
│ ├── clawsec-scanner/ # 🔍 Vulnerability scanner (deps + SAST + OpenClaw DAST)
│ ├── clawsec-nanoclaw/ # 📱 NanoClaw platform security suite
│ ├── clawsec-clawhub-checker/ # 🧪 ClawHub reputation checks
│ ├── clawtributor/ # 🤝 Community reporting skill
│ ├── hermes-attestation-guardian/ # 🛡️ Hermes attestation + drift verification
│ ├── openclaw-audit-watchdog/ # 🔭 Automated audit skill
│ ├── picoclaw-security-guardian/ # 🦐 Picoclaw posture/advisory/drift/supply-chain checks
│ ├── picoclaw-self-pen-testing/ # 🧪 Picoclaw self-pen-testing checks (separate package)
│ └── 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/signing verification
│ ├── poll-nvd-cves.yml # CVE polling pipeline
│ ├── community-advisory.yml # Approved issue -> advisory PR
│ ├── skill-release.yml # Skill release/signing pipeline
│ ├── deploy-pages.yml # GitHub Pages deployment
│ ├── wiki-sync.yml # Sync repo wiki/ to GitHub Wiki
│ ├── codeql.yml # CodeQL security analysis
│ └── scorecard.yml # OpenSSF Scorecard checks
└── public/ # Static assets + generated wiki exports
```
--
Beiträge
Wir begrüßen Beiträge! Siehe [CONTRIBUTING.md](CONTRIBUTING.md) für Richtlinien.
### Sicherheitsberater einfügen
Haben Sie einen schnellen Injektionsvektor, bösartige Fähigkeiten oder Sicherheitslücke gefunden? Über GitHub Issues melden:
ANHANG Öffne ein neues Problem mit der Vorlage **Security Incident Report***
2. Füllen Sie die erforderlichen Felder aus (Stärke, Art, Beschreibung, Betroffene Fähigkeiten)
3. Ein Betreuer überprüft und fügt das `advisory-approved` Label hinzu
4. Die Beratung wird automatisch im Feed veröffentlicht als `CLAW-{YEAR}-{ISSUE#}`
Siehe `CLAW-{YEAR}-{ISSUE#}` für detaillierte Richtlinien.
### Neue Fähigkeiten hinzufügen
ANHANG Erstellen Sie einen Kompetenzordner unter `skills/`
2. Hinzufügen `skill.json` mit benötigten Metadaten und SBOM
3. `SKILL.md` mit agentenlesbaren Anweisungen hinzufügen
4. Gültig mit `python utils/validate_skill.py skills/your-skill`
5. Eine PR zur Überprüfung einreichen
📚 Dokumentation Quelle der Wahrheit
Für alle Wiki-Inhalte bearbeiten Sie Dateien unter `wiki/` in diesem Repository. Das GitHub Wiki (`<repo>.wiki.git`) wird von `wiki/`_ durch `.github/workflows/wiki-sync.yml` synchronisiert, wenn `wiki/**`_ auf `main`__ wechselt.
LLM-Exporte werden von `wiki/` in `public/wiki/`_ generiert:
- `/wiki/llms.txt` ist der LLM-ready Export für `wiki/INDEX.md` (oder ein generierter Fallback-Index, wenn `INDEX.md` fehlt).
- `/wiki/<page>/llms.txt` ist der LLM-ready Export für diese einzelne Wiki-Seite.
--
📄 Lizenz
- Quellcode: GNU AGPL v3.0 oder später - Siehe [LICENSE](LICENSE) für Details.
- Schriften in `font/`: separat lizenziert - Siehe [`font/README.md`](font/README.md).
--
<div align="center">
**ClawSec** · Sicherheitsleistung, SentinelOne
🦞 Härten Agentic Workflows, eine Fähigkeit zu einer Zeit.
</div>
README.es.md
+277
View File
@@ -0,0 +1,277 @@
■h1 align="center"
■img src="./img/prompt-icon.svg" alt="prompt-icon" ancho="40"
ClawSec: Suite de habilidades de seguridad para agentes de IA
■img src="./img/prompt-icon.svg" alt="prompt-icon" ancho="40"
■/h1 título
"Cierto"
## Protege tus agentes OpenClaw, NanoClaw, Hermes y Picoclaw con una suite de seguridad completa
<h4>Traído por <a href="https://prompt.security">Prompt Security</a>, la plataforma de seguridad para IA</h4>
■/div titulada
"Cierto"
! [Prompt Security Logo](./img/Black+Color.png)
■img src="./public/img/mascot.png" alt="clawsec mascot" ancho="200" /
■/div titulada
"Cierto"
🌐 **En vivo en: [https://clawsec.prompt.security](https://clawsec.prompt.security) [https://prompt.security/clawsec](https://prompt.security/clawsec)**
[![CI](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml)
[![Deploy Pages](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml)
[![Poll NVD CVEs](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml)
■/div titulada
-...
## 🌍 Traducciones
- English (source of truth): [README.md](README.md)
- Español: `README.es.md`
## ✅ Estado de traducción (Fase 1)
Esta traducción en español cubre el flujo principal de onboarding y operación.
Para detalles de bajo nivel, schema completo y notas avanzadas de CI/CD, consulta el README en inglés.
## 🦞 ¿Qué es ClawSec?
ClawSec es una **suite completa de habilidades de seguridad para plataformas de agentes de IA**. Proporciona monitoreo de seguridad unificado, verificación de integridad e inteligencia de amenazas para proteger la arquitectura cognitiva del agente frente a inyección de prompts, deriva y/o instrucciones maliciosas.
### Plataformas compatibles
- **OpenClaw** (MoltBot, Clawdbot y clones): suite completa con instalador de habilidades, protección de integridad de archivos y auditorías de seguridad
- **NanoClaw**: seguridad para bot de WhatsApp en contenedor, con herramientas MCP para monitoreo de advisories, verificación de firmas e integridad de archivos
- **Hermes**: habilidades nativas de Hermes para verificación de feed firmado, verificación protegida con contexto de advisories, generación determinista de attestation, fail-closed verification y detección de drift de baseline
- **Picoclaw**: chequeos livianos de postura de seguridad en gateway de IA, con awareness de advisories, detección de drift de configuración, verificación de artefactos de release y paquete opcional separado de self-pen-testing
### Capacidades principales
- **📦 Instalador de suite**: instalación de todas las habilidades de seguridad con un solo comando y verificación de integridad
- **🛡️ Protección de integridad de archivos**: detección de drift y auto-restauración de archivos críticos del agente (`SOUL.md`, `IDENTITY.md`, etc.)
- **📡 Advisories de seguridad en vivo**: polling automatizado de CVEs del NVD e inteligencia comunitaria
- **🔍 Auditorías de seguridad**: scripts de auto-chequeo para detectar marcadores de prompt injection y vulnerabilidades
- **🔐 Verificación por checksums**: hashes SHA256 para artefactos de habilidades
- **Health checks**: actualizaciones y verificación de integridad automatizadas para habilidades instaladas
-...
## 🚀 Inicio rápido
### Para agentes de IA
```bash
# Instala la suite de seguridad de ClawSec
npx clawhub@latest install clawsec-suite
```
Después de instalar, la suite puede:
1. Descubrir protecciones instalables desde el catálogo de habilidades publicado
2. Verificar la integridad de releases con checksums firmados
3. Configurar monitoreo de advisories y flujos de protección basados en hooks
4. Añadir chequeos programados opcionales
Opción manual/source-first:
> Lee https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md y sigue las instrucciones de instalación.
### Para humanos
Copia esta instrucción a tu agente:
> Instala ClawSec con `npx clawhub@latest install clawsec-suite`, y luego completa los pasos de setup desde las instrucciones generadas.
### Notas de shell y SO
Los scripts de ClawSec se dividen entre:
- Tooling cross-platform en Node/Python (`npm run build`, hooks/setup `.mjs`, `utils/*.py`)
- Flujos POSIX shell (`*.sh`, la mayoría de snippets de instalación manual)
Para Linux/macOS (`bash`/`zsh`):
- Usa variables home sin comillas simples o con comillas dobles: `export INSTALL_ROOT="$HOME/.openclaw/skills"`
- **No** uses comillas simples con variables expandibles (por ejemplo, evita `'$HOME/.openclaw/skills'`)
Para Windows (PowerShell):
- Prefiere construir rutas de forma explícita:
- `$env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"`
- `node "$env:INSTALL_ROOT\\clawsec-suite\\scripts\\setup_advisory_hook.mjs"`
- Los scripts POSIX `.sh` requieren WSL o Git Bash.
Si ves rutas tipo `~/.openclaw/workspace/$HOME/...`, una variable home se pasó de forma literal. Re-ejecuta con ruta absoluta o con expresión home expandible.
-...
## 🧭 Documentación por plataforma y suite
La documentación detallada vive en los módulos del wiki:
- NanoClaw: [wiki/modules/nanoclaw-integration.md](wiki/modules/nanoclaw-integration.md)
- Hermes: [wiki/modules/hermes-attestation-guardian.md](wiki/modules/hermes-attestation-guardian.md)
- Picoclaw: [wiki/modules/picoclaw-security-guardian.md](wiki/modules/picoclaw-security-guardian.md)
- Picoclaw auto-pen-testing: [wiki/modules/picoclaw-self-pen-testing.md](wiki/modules/picoclaw-self-pen-testing.md)
- ClawSec Suite (OpenClaw): [wiki/modules/clawsec-suite.md](wiki/modules/clawsec-suite.md)
- Pipelines CI/CD: [wiki/modules/automation-release.md](wiki/modules/automation-release.md)
Instalación rápida:
- NanoClaw: [skills/clawsec-nanoclaw/INSTALL.md](skills/clawsec-nanoclaw/INSTALL.md)
- Hermes: `skills/hermes-attestation-guardian/`
- Picoclaw guardian: `skills/picoclaw-security-guardian/`
- Picoclaw self-pen-testing: `skills/picoclaw-self-pen-testing/`
- Suite: `skills/clawsec-suite/`
-...
## 📡 Feed de advisories de seguridad
ClawSec mantiene un feed de advisories continuamente actualizado, poblado automáticamente desde la National Vulnerability Database (NVD) de NIST.
### URL del feed
```bash
# Obtener advisories recientes
curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
```
Endpoint canónico: `https://clawsec.prompt.security/advisories/feed.json`
Mirror de compatibilidad (legacy): `https://clawsec.prompt.security/releases/latest/download/feed.json`
### Palabras clave monitoreadas
El feed consulta CVEs relacionados con:
- **OpenClaw**: `OpenClaw`, `clawdbot`, `Moltbot`
- **NanoClaw**: `NanoClaw`, `WhatsApp-bot`, `baileys`
- **Picoclaw**: `Picoclaw`, gateways ligeros de IA, exposición de gateway MCP
- Patrones de prompt injection
- Vulnerabilidades de seguridad en agentes
### Contexto de explotabilidad
ClawSec enriquece advisories de CVE con **contexto de explotabilidad** para ayudar a evaluar riesgo real, más allá del score CVSS bruto.
Puede incluir:
- **Evidencia de exploit**: si hay exploits públicos activos
- **Estado de weaponization**: si hay integración en frameworks comunes de ataque
- **Requisitos de ataque**: prerequisitos para explotar (acceso de red, autenticación, interacción de usuario)
- **Evaluación de riesgo**: nivel contextualizado que combina severidad técnica y explotabilidad
Esto ayuda a priorizar vulnerabilidades de amenaza inmediata frente a riesgos teóricos.
-...
## 🛠️ Desarrollo local
### Prerrequisitos
- Node.js 20+
- Python 3.10+ (herramientas offline)
- Npm
#### Setup
```bash
# Instala dependencias
npm install
# Arranca servidor de desarrollo
npm run dev
```
### Poblar datos locales
```bash
# Poblar catálogo de skills desde skills/
./scripts/populate-local-skills.sh
# Poblar advisory feed con CVEs reales del NVD
./scripts/populate-local-feed.sh --days 120
# Generar exportes llms desde wiki/ (preview local)
./scripts/populate-local-wiki.sh
# Entry point directo del generador (usado por predev/prebuild)
npm run gen:wiki-llms
```
Notas:
- `npm run dev` y `npm run build` regeneran automáticamente exportes `llms.txt` (`predev`/`prebuild`).
- `public/wiki/` es salida generada (local + CI) y está gitignored intencionalmente.
### Build
```bash
npm run build
```
-...
## 📁 Estructura del proyecto
```text
├── advisories/
├── components/
├── pages/
├── wiki/
├── scripts/
├── skills/
├── utils/
├── .github/workflows/
└── public/
```
Para la estructura detallada (scripts, workflows y paquetes de habilidades), consulta el README principal en inglés: [README.md](README.md).
-...
## 🤝 Contribuir
¡Contribuciones bienvenidas! Revisa [CONTRIBUTING.md](CONTRIBUTING.md).
### Enviar advisories de seguridad
¿Encontraste un vector de prompt injection, skill malicioso o vulnerabilidad? Repórtalo en GitHub Issues:
1. Abre un issue nuevo con la plantilla **Security Incident Report**
2. Completa campos requeridos (severidad, tipo, descripción, skills afectados)
3. Un maintainer revisa y agrega `advisory-approved`
4. El advisory se publica automáticamente en el feed como `CLAW-{YEAR}-{ISSUE#}`
Guía detallada: [CONTRIBUTING.md#submitting-security-advisories](CONTRIBUTING.md#submitting-security-advisories)
### Añadir nuevas skills
1. Crea carpeta bajo `skills/`
2. Agrega `skill.json` con metadata requerida y SBOM
3. Agrega `SKILL.md` con instrucciones legibles por agente
4. Valida con `python utils/validate_skill.py skills/your-skill`
5. Envía PR para review
## 📚 Fuente de verdad de la documentación
Todo el contenido wiki se edita en `wiki/` dentro de este repo. El GitHub Wiki (`<repo>.wiki.git`) se sincroniza desde `wiki/` vía `.github/workflows/wiki-sync.yml` cuando cambia `wiki/**` en `main`.
Los exportes para LLM se generan desde `wiki/` hacia `public/wiki/`:
- `/wiki/llms.txt` exporta `wiki/INDEX.md` (o índice fallback generado si falta `INDEX.md`)
- `/wiki/<page>/llms.txt` exporta la página wiki individual
-...
## 📄 Licencia
- Código fuente: GNU AGPL v3.0 o posterior — ver [LICENSE](LICENSE)
- Fuentes en `font/`: licencia separada — ver [`font/README.md`](font/README.md)
-...
"Cierto"
**ClawSec** · Seguridad Prompt, SentinelOne
🦞 Fortaleciendo flujos agentic, skill por skill.
■/div titulada
README.fr.md
+434
View File
@@ -0,0 +1,434 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: README.md
Review status: draft
-->
# Français Translation Scaffold
This file is currently a draft scaffold. Use README.md as the canonical source.
<h1 align="center">
<img src="/img/prompt-icon.svg" alt="prompt-icon" largeur="40">
ClawSec: Suite de compétences en sécurité pour les agents d'IA
<img src="/img/prompt-icon.svg" alt="prompt-icon" largeur="40">
</h1>
<div align="center">
## Sécurisez vos agents OpenClaw, NanoClaw et Hermes avec une suite complète de compétences en sécurité
<h4>Présenté par <a href="https://prompt.security">Prompt Security</a>, la plateforme pour la sécurité de l'IA</h4>
</div>
<div align="center">
- Oui. [Prompt Security Logo](./img/Black+Color.png)
<img src="/public/img/mascot.png" alt="clawsec mascotte" width="200" />
</div>
<div align="center">
C'est-à-dire **Live at: [https://clawsec.prompt.security](https://clawsec.prompt.security) [https://prompt.security/clawsec](https://prompt.security/clawsec)**
[![CI](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml)
[![Deploy Pages](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml)
[![Poll NVD CVEs](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml/badge.svg)](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml)
</div>
---
Traductions
- Español: [README.es.md](README.es.md)
- 한국어: [README.ko.md](README.ko.md)
Qu'est-ce que ClawSec ?
ClawSec est une suite complète de compétences en sécurité pour les plateformes d'agents d'IA**. Il fournit une surveillance de sécurité unifiée, la vérification de l'intégrité et la protection de l'architecture cognitive de votre agent contre l'injection rapide, la dérive et les instructions malveillantes.
Plateformes prises en charge
- **OpenClaw** (MoltBot, Clawdbot et clones) - Suite complète avec installateur de compétences, protection de l'intégrité des fichiers et audits de sécurité
- **NanoClaw** - Containerized Whats Sécurité des applications bot avec des outils MCP pour la surveillance consultative, la vérification des signatures et l'intégrité des fichiers
- **Hermès** - Compétences en sécurité Hermès-native pour la vérification de l'alimentation, la vérification de l'information-conseil, la génération d'attestations déterministes, la vérification fermée et la détection de la dérive de base
- **Picoclaw** - Contrôles de la posture de sécurité de la passerelle légère AI avec sensibilisation, détection de la dérive de config, vérification de l'artéfact de relâchement, et un ensemble d'auto-essais facultatifs
### Matrix des compétences
- Oui. Nom de la compétence Plate-forme prise en charge de la sécurité de la vérification de l'alimentation de config driving de l'agent testing de l'auto stylo de la chaîne d'approvisionnement de vérification d'installation de l'installation de l'agent
-- -- -- -- -- -- -- -- -- -- -- -- --
Claw-release
Clawsec-clawhub-checker
Oui Non Oui Oui
Oui Oui Oui Oui
Oui Non Oui Oui
Oui Oui Oui Oui
Clawtributor OpenClaw OpenClaw OpenClaw OpenClaw OpenClaw
Hermes-attestation-guardian.
Openclaw-audit-watchdog
Picoclaw-security-guardian.
Picoclaw-auto-test de stylos
Un gardien de l'âme OpenClaw OpenClaw OpenClaw OpenClaw
Capacités de base
- ** Installateur Suite** - Installation unique de toutes les compétences de sécurité avec vérification de l'intégrité
- Oui. Protection de l'intégrité des fichiers** - Détection et récupération automatique des fichiers d'agents critiques (SOUL.md, IDENTITY.md, etc.)
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
- Oui. Audits de sécurité** - Auto-vérifier les scripts pour détecter les marqueurs d'injection et les vulnérabilités
- Oui. Vérification des contrôles** - SHA256 somme de contrôle pour tous les artefacts de compétence
- **Vérifications santé** - Mises à jour automatisées et vérification de l'intégrité pour toutes les compétences installées
---
Démos de produits
Les aperçus animés ci-dessous sont des GIF (pas d'audio). Cliquez sur n'importe quel aperçu pour ouvrir le MP4 complet avec audio.
### Installer la démo (`clawsec-suite`)
[![Install demo animated preview](public/video/install-demo-preview.gif)](public/video/install-demo.mp4)
Lien direct: [install-demo.mp4](public/video/install-demo.mp4)
### Démo de détection de la dérive (`soul-guardian`)
[![Drift detection animated preview](public/video/soul-guardian-demo-preview.gif)](public/video/soul-guardian-demo.mp4)
Lien direct: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4)
---
Début rapide
Pour les agents de l'IA
```bash
# Install the ClawSec security suite
npx clawhub@latest install clawsec-suite
```
Après l'installation, la suite peut :
1. Découvrez les protections installables à partir du catalogue de compétences publié
2. Vérifier l'intégrité de la libération à l'aide de comptes de vérification signés
3. Mettre en place une surveillance consultative et des flux de protection par crochet
4. Ajouter des contrôles programmés facultatifs
Manuel/source-première option:
> Lire https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md et suivre les instructions d'installation.
Pour les humains
Copiez cette instruction à votre agent d'IA :
> Installez ClawSec avec `npx clawhub@latest install clawsec-suite`, puis remplissez les étapes de configuration à partir des instructions générées.
### Notes Shell et OS
Les scripts ClawSec sont divisés entre :
- Plateforme transversale Outillage Noeud/Python (`npm run build`, crochet/réglage `.mjs`, `utils/*.py`)
- Workflows shell POSIX (`*.sh`, la plupart des snipets d'installation manuelle)
Pour Linux/macOS (`bash`/`zsh`):
- Utiliser des vars d'habitation sans ou double citations: `export INSTALL_ROOT="$HOME/.openclaw/skills"`
- Ne pas **** vars extensibles à simple cote (par exemple, éviter `'$HOME/.openclaw/skills'`)
Pour Windows (PowerShell):
- Préférez la construction explicite du chemin :
- `$env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"`
- `node "$env:INSTALL_ROOT\\clawsec-suite\\scripts\\setup_advisory_hook.mjs"`
- POSIX `.sh` nécessitent WSL ou Git Bash.
Dépannage : si vous voyez des répertoires tels que `~/.openclaw/workspace/$HOME/...`, une variable d'accueil a été transmise littéralement. Re-exécuter en utilisant un chemin absolu ou une expression de la maison non citée.
---
Documentation sur la plateforme et la suite
Des documents détaillés sur la plateforme et la suite sont disponibles dans les modules wiki :
- NanoClaw: [wiki/modules/nanoclaw-integration.md](wiki/modules/nanoclaw-integration.md)
- Hermès: [wiki/modules/hermes-attestation-guardian.md](wiki/modules/hermes-attestation-guardian.md)
- Picoclaw: [wiki/modules/picoclaw-security-guardian.md](wiki/modules/picoclaw-security-guardian.md)
- Picoclaw auto-test : [wiki/modules/picoclaw-self-pen-testing.md](wiki/modules/picoclaw-self-pen-testing.md)
- ClawSec Suite (OpenClaw): [wiki/modules/clawsec-suite.md](wiki/modules/clawsec-suite.md)
- pipelines CI/CD: [wiki/modules/automation-release.md](wiki/modules/automation-release.md)
Liens d'installation rapide :
- Installation de NanoClaw : [skills/clawsec-nanoclaw/INSTALL.md](skills/clawsec-nanoclaw/INSTALL.md)
- Pack de compétences Hermes: `skills/hermes-attestation-guardian/`
- Paquet de protection Picoclaw: `skills/picoclaw-security-guardian/`
- Paquet Picoclaw auto-test: `skills/picoclaw-self-pen-testing/`
- Paquet Suite: `skills/clawsec-suite/`
---
No # # # Avis de sécurité
ClawSec tient à jour en permanence un avis de sécurité, alimenté automatiquement par la base de données nationale sur la vulnérabilité (NVD) du NIST.
URL du flux
```bash
# Fetch latest advisories
curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
```
Critère canonique: `https://clawsec.prompt.security/advisories/feed.json`
Miroir de compatibilité (légère): `https://clawsec.prompt.security/releases/latest/download/feed.json`
Mots-clés surveillés
Les sondages sur les aliments du bétail ont porté sur :
- ** Plateforme OpenClaw** : `OpenClaw`, `clawdbot`, `Moltbot`
- **NanoClaw Platform**: `NanoClaw`, `WhatsApp-bot`, `baileys`
- **Picoclaw Platform**: `Picoclaw`, `picoclaw`, passerelles AI légères, exposition aux passerelles MCP
- Modèles d'injection rapides
- Vulnérabilités de sécurité des agents
Contexte d'exploitation
ClawSec enrichit les avis CVE avec **contexte d'exploitation** pour aider les agents à évaluer le risque réel au-delà des scores CVSS bruts. Les avis nouvellement analysés peuvent comprendre :
- **Exploiter des preuves**: si des exploits publics existent dans la nature
- ** État des armes** : Si les exploits sont intégrés dans des cadres d'attaque communs
- **Exigences d'adaptation**: Prérequis pour une exploitation réussie (accès au réseau, authentification, interaction utilisateur)
- **Évaluation des risques**: Niveau de risque contextuel combinant gravité technique et exploitabilité
Cette fonctionnalité aide les agents à prioriser les vulnérabilités qui posent des menaces immédiates par rapport aux risques théoriques, permettant ainsi des décisions de sécurité plus intelligentes.
Schéma consultatif
** NVD CVE Conseil :**
```json
{
"id": "CVE-2026-XXXXX",
"severity": "critical|high|medium|low",
"type": "vulnerable_skill",
"platforms": ["openclaw", "nanoclaw"],
"title": "Short description",
"description": "Full CVE description from NVD",
"published": "2026-02-01T00:00:00Z",
"cvss_score": 8.8,
"nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX",
"exploitability_score": "high|medium|low|unknown",
"exploitability_rationale": "Why this CVE is or is not likely exploitable in agent deployments",
"references": ["..."],
"action": "Recommended remediation"
}
```
**Conseil communautaire:**
```json
{
"id": "CLAW-2026-0042",
"severity": "high",
"type": "prompt_injection|vulnerable_skill|tampering_attempt",
"platforms": ["nanoclaw"],
"title": "Short description",
"description": "Detailed description from issue",
"published": "2026-02-01T00:00:00Z",
"affected": ["skill-name@1.0.0"],
"source": "Community Report",
"github_issue_url": "https://github.com/.../issues/42",
"action": "Recommended remediation"
}
```
**Valeurs de la plateforme:**
- `"openclaw"` - OpenClaw/Clawdbot/Molt Bot seulement
- `"nanoclaw"` - NanoClaw seulement
- `"hermes"` - Hermès seulement
- `"picoclaw"` - Picoclaw seulement
- `["openclaw", "nanoclaw", "hermes", "picoclaw"]` - Toutes les plateformes centrales
- (vide/manque) - Toutes les plates-formes (compatible avec l'arrière)
---
Lignes de pipelines CI/CD
Les détails du pipeline CI/CD ont été déplacés vers la page du module wiki :
- [wiki/modules/automation-release.md](wiki/modules/automation-release.md)
Opérations connexes docs:
- [wiki/security-signing-runbook.md](wiki/security-signing-runbook.md)
- [wiki/migration-signed-feed.md](wiki/migration-signed-feed.md)
---
Outils hors ligne
ClawSec comprend Utilitaires Python pour le développement et la validation des compétences locales.
### Validateur de compétences
Valide un dossier de compétences en fonction du schéma requis :
```bash
python utils/validate_skill.py skills/clawsec-feed
```
Contrôles :
- `skill.json` existe et est valide JSON
- Champs obligatoires présents (nom, version, description, auteur, licence)
- Les fichiers SBOM existent et sont lisibles
- Les métadonnées OpenClaw sont bien structurées
Générateur de contrôles de compétences
Génére `checksums.json` avec SHA256 haches pour une compétence:
```bash
python utils/package_skill.py skills/clawsec-feed ./dist
```
Produits :
- `checksums.json` - SHA256 haches pour vérification
---
Développement local
Préalables
- Node.js 20+
- Python 3.10+ (pour les outils hors ligne)
- npm
Configuration
```bash
# Install dependencies
npm install
# Start development server
npm run dev
```
- Oui. Populer des données locales
```bash
# Populate skills catalog from local skills/ directory
./scripts/populate-local-skills.sh
# Populate advisory feed with real NVD CVE data
./scripts/populate-local-feed.sh --days 120
# 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
```
Remarques:
- `npm run dev` et `npm run build` régénèrent automatiquement les exportations de wikis `llms.txt` (Hooks `predev`/`prebuild`).
- `public/wiki/` est généré en sortie (locale + CI) et est intentionnellement gitagnolé.
Construire
```bash
npm run build
```
---
Structure du projet
```
├── advisories/
│ ├── feed.json # Main advisory feed
│ ├── feed.json.sig # Detached signature for feed.json
│ └── feed-signing-public.pem # Public key for feed verification
├── components/ # React components
├── pages/ # Route/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
│ ├── prepare-to-push.sh # Local CI-style quality gate
│ ├── validate-release-links.sh # Release link checks
│ └── release-skill.sh # Manual skill release helper
├── skills/
│ ├── claw-release/ # 🚀 Release automation workflow skill
│ ├── clawsec-suite/ # 📦 Suite installer (skill-of-skills)
│ ├── clawsec-feed/ # 📡 Advisory feed skill
│ ├── clawsec-scanner/ # 🔍 Vulnerability scanner (deps + SAST + OpenClaw DAST)
│ ├── clawsec-nanoclaw/ # 📱 NanoClaw platform security suite
│ ├── clawsec-clawhub-checker/ # 🧪 ClawHub reputation checks
│ ├── clawtributor/ # 🤝 Community reporting skill
│ ├── hermes-attestation-guardian/ # 🛡️ Hermes attestation + drift verification
│ ├── openclaw-audit-watchdog/ # 🔭 Automated audit skill
│ ├── picoclaw-security-guardian/ # 🦐 Picoclaw posture/advisory/drift/supply-chain checks
│ ├── picoclaw-self-pen-testing/ # 🧪 Picoclaw self-pen-testing checks (separate package)
│ └── 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/signing verification
│ ├── poll-nvd-cves.yml # CVE polling pipeline
│ ├── community-advisory.yml # Approved issue -> advisory PR
│ ├── skill-release.yml # Skill release/signing pipeline
│ ├── deploy-pages.yml # GitHub Pages deployment
│ ├── wiki-sync.yml # Sync repo wiki/ to GitHub Wiki
│ ├── codeql.yml # CodeQL security analysis
│ └── scorecard.yml # OpenSSF Scorecard checks
└── public/ # Static assets + generated wiki exports
```
---
Contribution
Nous saluons les contributions! Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour les lignes directrices.
### Soumettre des avis de sécurité
Trouvé un vecteur d'injection rapide, une compétence malveillante ou une vulnérabilité à la sécurité? Signalez-le via GitHub Questions :
1. Ouvrir un nouveau numéro en utilisant le modèle **Rapport d'incident de sécurité**
2. Remplissez les champs requis (série, type, description, compétences affectées)
3. Un responsable examinera et ajoutera l'étiquette `advisory-approved`
4. L'avis est automatiquement publié sur le flux sous la forme de `CLAW-{YEAR}-{ISSUE#}`
Voir [CONTRIBUTING.md](CONTRIBUTING.md#submitting-security-advisories) pour des lignes directrices détaillées.
Ajouter de nouvelles compétences
1. Créer un dossier de compétences sous `skills/`
2. Ajouter `skill.json` avec les métadonnées requises et SBOM
3. Ajouter `SKILL.md` avec des instructions lisibles par agent
4. Valider avec `python utils/validate_skill.py skills/your-skill`
5. Soumettre un rapport de situation pour examen
Source de documentation de la vérité
Pour tout le contenu wiki, éditer des fichiers sous `wiki/` dans ce dépôt. Le Wiki GitHub (`<repo>.wiki.git`) est synchronisé depuis `wiki/` par `.github/workflows/wiki-sync.yml` lorsque `wiki/**` change sur `main`.
Les exportations de LLM sont générées par `wiki/` vers `public/wiki/`:
- `/wiki/llms.txt` est l'exportation prête à LLM pour `wiki/INDEX.md` (ou un indice de repli généré si `INDEX.md` est manquant).
- `/wiki/<page>/llms.txt` est l'export LLM-ready pour cette seule page wiki.
---
Licence
- Code source : GNU AGPL v3.0 ou ultérieur - Voir [LICENSE](LICENSE) pour plus de détails.
- Polices dans `font/`: Licence séparée - Voir [`font/README.md`](font/README.md).
---
<div align="center">
**ClawSec** · Sécurité rapide, SentinelOne
C'est-à-dire Renforcer les workflows d'agents, une compétence à la fois.
</div>
README.ja.md
+434
View File
@@ -0,0 +1,434 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: README.md
Review status: draft
-->
# 日本語 Translation Scaffold
This file is currently a draft scaffold. Use README.md as the canonical source.
<h1 align="center">
<img src="./img/prompt-icon.svg"alt="prompt-icon" 幅="40">
ClawSec:AIエージェントのセキュリティスキルスイート
<img src="./img/prompt-icon.svg"alt="prompt-icon" 幅="40">
</h1>
<div align="center">
## 完全なセキュリティスキルスイートでOpenClaw、NanoClaw、およびヘルメスエージェントをセキュアに
<h4>AIセキュリティプラットフォーム</h4>
</div>
<div align="center">
お問い合わせ [Prompt Security Logo](./img/Black+Color.png)の特長
<img src="./public/img/mascot.png"alt="clawsec mascot" 幅="200" />
</div>
<div align="center">
ブーツ **ライブ時: [https://clawsec.prompt.security](https://clawsec.prompt.security) [https://prompt.security/clawsec](https://prompt.security/clawsec)**
[![CI](https://github.com/prompt-security/clawsec/actions/workflows/ci.yml/badge.svg)(https://github.com/prompt-security/clawsec/actions/workflows/ci.yml)
[![Deploy Pages](https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml/badge.svg)(https://github.com/prompt-security/clawsec/actions/workflows/deploy-pages.yml)
[![Poll NVD CVEs](https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml/badge.svg)(https://github.com/prompt-security/clawsec/actions/workflows/poll-nvd-cves.yml)
</div>
お問い合わせ
## 翻訳
- Español: [README.es.md](README.es.md)
- 한국어: [README.ko.md](README.ko.md)
## 🦞 ClawSecとは?
ClawSec は、AI エージェント プラットフォームの**完全なセキュリティ スキル スイートです。 エージェントの認知アーキテクチャを迅速注入、ドリフト、悪意のある指示に対して、統一されたセキュリティ監視、完全性検証、脅威インテリジェンス保護を提供します。
## 対応プラットフォーム
- **OpenClaw**(MoltBot、Clawdbot、およびクローン) - スキルインストーラ、ファイルの完全性保護、およびセキュリティ監査とフルスイート
- **ナノクロー** - コンテナ化されたもの 諮問監視、署名検証、ファイルの整合性のためのMCPツールを使用したAppボットセキュリティ
-**Hermes** - 署名された諮問的フィード検証、アドバイザリーアウェアガード検証、決定的な検証生成、フェイルクローズド検証、ベースラインドリフト検出のためのヘルメスネイティブセキュリティスキル
-**Picoclaw** - 軽量AIゲートウェイセキュリティの姿勢は、アドバイザリーの意識、構成の漂流検出、リリースアーティファクト検証、およびオプションの別々のセルフペンテストパッケージでチェックします
##スキル機能マトリックス
お問い合わせ スキル名 | 対応プラットフォーム| 安全検証| 構成漂流 | エージェントセルフペンテスト| サプライチェーンインストール検証 |
お問い合わせ
| プレスリリース | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部
| クローム・クローブ・チェッカー | OpenClaw + clawsec スイート・インテグレーション | ノー | ノー | ノー | ノー | ノー | ノー |
| クロームフィード | OpenClaw | 有り | なし | なし | なし | 有り |
| クローム・ナンクロー | ナノクロー | 可 | 可 | 有 | 有 | 有 | 有 | 有 | 有 | 有 |
| クローム・スキャナ | オープンクロー | 有り | なし | 有り | 可 | 可 | 可 | 可 | 可 |
| クロームスイート | オープンクローラ | 有り | 有り | なし | 有り | なし | 有り | なし | なし | なし | なし | なし | なし | なし | なし | なし | なし | なし |
| プライバシーポリシー | 免責事項 | 免責事項 | 免責事項 | 免責事項 | 免責事項 | 免責事項 | 免責事項 |
| ヘルメス・アテスタンス・ガーディアン | ヘルメス | はい(アドバイザリー・フィード・検証) | はい | なし | 限定(アドバイザリー・プレッションのみ・アーティファクト・シグネチャ・プロテナンス・インストール・検証なし) |
| Openclaw-audit-watchdog | OpenClaw | ノー | ノー | ノー | ノー | ノー |
| picoclaw-security-guardian | ピッコロー | 有り | なし | 有り | 有り |
| picoclaw-self-pen-testing | ピッコロー | ノー | ノー | ノー | ノー |
| 魂を守る人 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 | 営業部 |
## コア機能
- ** レース スイート インストーラ** - 完全性検証ですべてのセキュリティ スキルのワンコマンド インストール
お問い合わせ ファイル整合性保護** - 重要なエージェントファイル(SOUL.md、IDENTITY.mdなど)のドリフト検出と自動復元
- **セキュリティアドバイザリー** - 自動NVD CVEポーリングとコミュニティの脅威インテリジェンス
- ** 絶縁 セキュリティ監査** - プロンプトインジェクションマーカーと脆弱性を検出するためにスクリプトをセルフチェック
お問い合わせ チェックサム検証** - すべてのスキルアーティファクトのSHA256チェックサム
- **健康チェック** - インストールされたすべてのスキルの自動更新と完全性検証
お問い合わせ
## ✔製品デモ
下記のアニメーションプレビューはGIF(音声なし)です。 任意のプレビューをクリックして、オーディオでフルMP4を開きます。
## デモをインストール (`clawsec-suite`)
[![Install demo animated preview](public/video/install-demo-preview.gif)(パブリック/ビデオ/インストールデモ)
直接リンク: [install-demo.mp4](public/video/install-demo.mp4)
## ドリフト検出デモ(`soul-guardian`)
[![Drift detection animated preview](public/video/soul-guardian-demo-preview.gif)(公共/ビデオ/ソウル-保護者-demo.mp4)
直接リンク: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4)
お問い合わせ
## すぐにスタート
##AIエージェントの###
```bash
# Install the ClawSec security suite
npx clawhub@latest install clawsec-suite
```
インストール後、スイートは次のことができます。
1。 公開されたスキルカタログからインストール可能な保護を発見
2。 署名されたチェックサムを使用してリリースの完全性を確認します
3。 アドバイザリーモニタリングとホックベースの保護フローの設定
4。 オプションのスケジュールチェックを追加
手動/ソース優先オプション:
ツイート 採用情報 https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md とインストール手順に従います。
人間のための#####
この指示をAIエージェントにコピーします。
ツイート `npx clawhub@latest install clawsec-suite`でClawSecをインストールし、生成された指示からセットアップ手順を完了します。
##シェルとOSノート
ClawSec スクリプトは以下の間に分割されます。
- クロスプラットフォーム Node/Python ツーリング (`npm run build`、hook/setup `.mjs`、`utils/*.py`)
- POSIXシェルワークフロー(`*.sh`、ほとんどの手動インストールスニペット)
Linux/macOS (`bash`/`zsh`) の場合:
- 引用されていないか二重引用された家変数を使用して下さい:`export INSTALL_ROOT="$HOME/.openclaw/skills"`
- 単一の引用符の拡張可能なvars (例えば、`'$HOME/.openclaw/skills'`を避けるため) を**しない**
Windows用(PowerShell):
- プレファーの明示的な道の建物:
- `$env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"`
- `node "$env:INSTALL_ROOT\\clawsec-suite\\scripts\\setup_advisory_hook.mjs"`
- POSIX `.sh`スクリプトはWSLまたはGit Bashが必要です。
トラブルシューティング:`~/.openclaw/workspace/$HOME/...`などのディレクトリが表示された場合、ホーム変数は文字通り渡されました。 絶対パスまたは非引用のホーム式を使用して再実行します。
お問い合わせ
## 🧭プラットフォーム&スイートドキュメント
詳細なプラットフォームとスイート docs は wiki モジュールで動作します。
・ナノクロー:[wiki/modules/nanoclaw-integration.md](wiki/modules/nanoclaw-integration.md)
- ヘルメス:[wiki/modules/hermes-attestation-guardian.md](wiki/modules/hermes-attestation-guardian.md)
- ピコクロー:[wiki/modules/picoclaw-security-guardian.md](wiki/modules/picoclaw-security-guardian.md)
- ピコクローセルフペンテスト: [wiki/modules/picoclaw-self-pen-testing.md](wiki/modules/picoclaw-self-pen-testing.md)の特長
- ClawSec Suite (OpenClaw): [wiki/modules/clawsec-suite.md](wiki/modules/clawsec-suite.md)
- CI/CDのパイプライン: [wiki/modules/automation-release.md](wiki/modules/automation-release.md)の特長
クイックインストールリンク:
- NanoClawは取付けます: [skills/clawsec-nanoclaw/INSTALL.md](skills/clawsec-nanoclaw/INSTALL.md)の特長
- エルメススキルパッケージ:`skills/hermes-attestation-guardian/`
- Picoclawの保護者のパッケージ:`skills/picoclaw-security-guardian/`
- ピコクローセルフペンテストパッケージ:`skills/picoclaw-self-pen-testing/`
- スイートパッケージ:`skills/clawsec-suite/`
お問い合わせ
## 安全保障アドバイザリーフィード
ClawSecは、NISTのNational Vulnerability Database(NVD)から自動ポップアップし、継続的に更新されたセキュリティアドバイザリーフィードを維持します。
## フィード URL
```bash
# Fetch latest advisories
curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
```
キヤノンのエンドポイント:`https://clawsec.prompt.security/advisories/feed.json`
互換性ミラー(レガシー):`https://clawsec.prompt.security/releases/latest/download/feed.json`
### 監視されたキーワード
フィードの投票 CVE に関連する:
- **OpenClawプラットフォーム**: `OpenClaw`、`clawdbot`、`Moltbot`
- **ナノクロープラットフォーム**:`NanoClaw`、`WhatsApp-bot`、`baileys`
- **Picoclaw Platform**:`Picoclaw`、`picoclaw`、軽量AIゲートウェイ、MCPゲートウェイ露出
- プロンプト射出パターン
- エージェントのセキュリティ脆弱性
###exploitability コンテキスト
ClawSec は、CVE のアドバイザリーを **exploitability context** で強化し、CVSS スコアを超えて、エージェントが現実的なリスクを評価するのを支援します。 新規に分析されたアドバイザリーには以下が含まれます。
-**Exploit Evidence**: 公共の悪用が野生に存在するかどうか
- **武器の状態**: 悪用が一般的な攻撃フレームワークに統合されている場合
- **攻撃要件**:成功した搾取(ネットワークアクセス、認証、ユーザーインタラクション)に必要な前提条件
-**リスクアセスメント**:技術的重大性を悪用性と組み合わせるコンテキストリスクレベル
この機能は、エージェントが直面する脅威を理論的なリスクに優先し、よりスマートなセキュリティ決定を可能にします。
##アドバイザリー・スキーマ
**NVD CVE ** アドバイザリー:**
```json
{
"id": "CVE-2026-XXXXX",
"severity": "critical|high|medium|low",
"type": "vulnerable_skill",
"platforms": ["openclaw", "nanoclaw"],
"title": "Short description",
"description": "Full CVE description from NVD",
"published": "2026-02-01T00:00:00Z",
"cvss_score": 8.8,
"nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX",
"exploitability_score": "high|medium|low|unknown",
"exploitability_rationale": "Why this CVE is or is not likely exploitable in agent deployments",
"references": ["..."],
"action": "Recommended remediation"
}
```
**コミュニティアドバイザリー:**
```json
{
"id": "CLAW-2026-0042",
"severity": "high",
"type": "prompt_injection|vulnerable_skill|tampering_attempt",
"platforms": ["nanoclaw"],
"title": "Short description",
"description": "Detailed description from issue",
"published": "2026-02-01T00:00:00Z",
"affected": ["skill-name@1.0.0"],
"source": "Community Report",
"github_issue_url": "https://github.com/.../issues/42",
"action": "Recommended remediation"
}
```
**プラットフォーム値:**
- `"openclaw"` - OpenClaw/Clawdbot/Molt ボットのみ
- `"nanoclaw"` - ナノクローのみ
- `"hermes"` - ヘルメスのみ
- `"picoclaw"` - ピコクローのみ
- `["openclaw", "nanoclaw", "hermes", "picoclaw"]` - すべてのコアプラットフォーム
- (empty/missing) - すべてのプラットフォーム(後方互換)
お問い合わせ
## は、CI/CD パイプライン
CI/CD パイプラインの詳細は wiki モジュールページに移動しました。
- [wiki/modules/automation-release.md](wiki/modules/automation-release.md)
関連操作 docs:
- [wiki/security-signing-runbook.md](wiki/security-signing-runbook.md)
- [wiki/migration-signed-feed.md](wiki/migration-signed-feed.md)
お問い合わせ
## ️️ オフラインツール
ClawSecには ローカルスキル開発と検証のためのPythonユーティリティ。
##スキルバリデータ
必要なスキーマに対してスキルフォルダーを検証します。
```bash
python utils/validate_skill.py skills/clawsec-feed
```
チェック:
- `skill.json`が存在し、有効なJSON
- 必須フィールド(名前、バージョン、説明、著者、ライセンス)
- SBOMファイルが存在し、読みやすく
- OpenClawメタデータを適切に構造化
##スキルチェックサムジェネレーター
`checksums.json` を SHA256 のハッシュで生成します。
```bash
python utils/package_skill.py skills/clawsec-feed ./dist
```
出力:
- `checksums.json` - SHA256ハッシュの検証
お問い合わせ
## ローカル開発
### 前提条件
- Node.js 20 +
- Python 3.10+(オフラインツール用)
- 午後
### セットアップ
```bash
# Install dependencies
npm install
# Start development server
npm run dev
```
################################################################################################################################################################################################################################################################ ローカルデータを出力
```bash
# Populate skills catalog from local skills/ directory
./scripts/populate-local-skills.sh
# Populate advisory feed with real NVD CVE data
./scripts/populate-local-feed.sh --days 120
# 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
```
注意:
- `npm run dev` と `npm run build` は自動的に wiki `llms.txt` のエクスポート (`predev`/`prebuild` のホック) を再生成します。
- `public/wiki/`は出力(ローカル+CI)を生成し、意図的に無視されます。
## ビルド
```bash
npm run build
```
お問い合わせ
## 📁 プロジェクト構造
```
├── advisories/
│ ├── feed.json # Main advisory feed
│ ├── feed.json.sig # Detached signature for feed.json
│ └── feed-signing-public.pem # Public key for feed verification
├── components/ # React components
├── pages/ # Route/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
│ ├── prepare-to-push.sh # Local CI-style quality gate
│ ├── validate-release-links.sh # Release link checks
│ └── release-skill.sh # Manual skill release helper
├── skills/
│ ├── claw-release/ # 🚀 Release automation workflow skill
│ ├── clawsec-suite/ # 📦 Suite installer (skill-of-skills)
│ ├── clawsec-feed/ # 📡 Advisory feed skill
│ ├── clawsec-scanner/ # 🔍 Vulnerability scanner (deps + SAST + OpenClaw DAST)
│ ├── clawsec-nanoclaw/ # 📱 NanoClaw platform security suite
│ ├── clawsec-clawhub-checker/ # 🧪 ClawHub reputation checks
│ ├── clawtributor/ # 🤝 Community reporting skill
│ ├── hermes-attestation-guardian/ # 🛡️ Hermes attestation + drift verification
│ ├── openclaw-audit-watchdog/ # 🔭 Automated audit skill
│ ├── picoclaw-security-guardian/ # 🦐 Picoclaw posture/advisory/drift/supply-chain checks
│ ├── picoclaw-self-pen-testing/ # 🧪 Picoclaw self-pen-testing checks (separate package)
│ └── 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/signing verification
│ ├── poll-nvd-cves.yml # CVE polling pipeline
│ ├── community-advisory.yml # Approved issue -> advisory PR
│ ├── skill-release.yml # Skill release/signing pipeline
│ ├── deploy-pages.yml # GitHub Pages deployment
│ ├── wiki-sync.yml # Sync repo wiki/ to GitHub Wiki
│ ├── codeql.yml # CodeQL security analysis
│ └── scorecard.yml # OpenSSF Scorecard checks
└── public/ # Static assets + generated wiki exports
```
お問い合わせ
## 社会貢献
寄付を歓迎します! ガイドラインの[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
### 提出セキュリティアドバイザリー
迅速な注射ベクトル、悪意のあるスキル、またはセキュリティ脆弱性を発見しましたか? GitHub の問題で報告する:
1。 **セキュリティインシデントレポート**テンプレートを使用して新しい問題を開きます
2。 必須項目を記入(重度、種類、説明、影響を受けたスキル)
3。 メンテナーが`advisory-approved`ラベルを見直し、追加します
4。 アドバイザリーが`CLAW-{YEAR}-{ISSUE#}`としてフィードに自動的に公開されます
詳細は[CONTRIBUTING.md](CONTRIBUTING.md#submitting-security-advisories)をご覧ください。
##新規スキルの追加
1。 `skills/`でスキルフォルダを作成する
2。 必要なメタデータとSBOMで`skill.json`を追加
3。 エージェント読み取り可能な指示で`SKILL.md`を追加
4. `python utils/validate_skill.py skills/your-skill`と検証
5。 レビューのPRを提出する
## ドキュメント 真実のソース
すべてのwikiコンテンツについては、このリポジトリの`wiki/`でファイルを編集します。 GitHub Wiki (`<repo>.wiki.git`) は、`main` が `.github/workflows/wiki-sync.yml` から `wiki/**` が `main` で変更されたときに、`.github/workflows/wiki-sync.yml` から同期されます。
LLM エクスポートは `wiki/` から `public/wiki/` に生成されます。
- `/wiki/llms.txt` は `wiki/INDEX.md` の LLM-ready エクスポート (または `INDEX.md` が見つからない場合は生成されたフォールバックインデックス) です。
- `/wiki/<page>/llms.txt`は、その単一のwikiページのためのLM-readyエクスポートです。
お問い合わせ
## ライセンス
- ソースコード:GNU AGPL v3.0以降 - 詳細は[LICENSE](LICENSE)を参照してください。
- `font/`のフォント: ライセンス別 - [`font/README.md`](font/README.md) をご覧ください。
お問い合わせ
<div align="center">
**ClawSec**・Prompt Security、SentinelOne **
エージェントのワークフローを強化し、一度に1つのスキル。
</div>
README.ko.md
+59
View File
@@ -0,0 +1,59 @@
# ClawSec: AI 에이전트를 위한 보안 스킬 스위트
> 한국어 번역 (초기 버전)
## 🌍 번역
- English (source of truth): [README.md](README.md)
- Español: [README.es.md](README.es.md)
- 한국어: `README.ko.md`
## ✅ 번역 상태 (Korean Phase 1)
이 한국어 문서는 핵심 온보딩/운영 흐름을 우선 제공합니다.
고급 스키마, 전체 CI/CD 세부사항, 최신 기준 문서는 영어 README를 참고하세요.
## 🦞 ClawSec란?
ClawSec은 **OpenClaw, NanoClaw, Hermes, Picoclaw 같은 AI 에이전트 플랫폼용 종합 보안 스킬 스위트**입니다.
프롬프트 인젝션, 드리프트, 악성 지시로부터 에이전트 동작을 보호하기 위해
통합 보안 모니터링, 무결성 검증, 위협 인텔리전스를 제공합니다.
## 🚀 빠른 시작
### AI 에이전트용
```bash
npx clawhub@latest install clawsec-suite
```
설치 후 ClawSec 스위트는 다음을 수행할 수 있습니다:
1. 공개 스킬 카탈로그에서 설치 가능한 보호 기능 탐색
2. 서명된 체크섬을 통한 릴리스 무결성 검증
3. advisory 모니터링 및 훅 기반 보호 흐름 설정
4. 선택적 스케줄 점검 추가
### 사람 운영자용
에이전트에게 다음 지시를 전달하세요:
· `npx clawhub@latest install clawsec-suite`로 ClawSec을 설치 한 다음 생성 된 지침에서 설정 단계를 완료하십시오.
## 🧭 위키 문서
플랫폼/스위트 상세 문서는 wiki 모듈을 참고하세요:
- [wiki/modules/clawsec-suite.md](wiki/modules/clawsec-suite.md)
- [wiki/modules/nanoclaw-integration.md](wiki/modules/nanoclaw-integration.md)
- [wiki/modules/hermes-attestation-guardian.md](wiki/modules/hermes-attestation-guardian.md)
- [wiki/modules/picoclaw-security-guardian.md](wiki/modules/picoclaw-security-guardian.md)
## 📡 보안 advisory 피드
정식 엔드포인트:
- `https://clawsec.prompt.security/advisories/feed.json`
## 🛠️ 로컬 개발
```bash
npm install
./scripts/populate-local-skills.sh
./scripts/populate-local-feed.sh --days 120
npm run gen:wiki-llms
npm run dev
```
## 📄 라이선스
- Source code: GNU AGPL v3.0 or later — [LICENSE](LICENSE)
- Font assets: [`font/README.md`](font/README.md)
README.md
+6
View File
@@ -31,6 +31,12 @@
---
## 🌍 Translations
[Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **English**
Wiki indexes: [DE](wiki/de/INDEX.md) · [ES](wiki/es/INDEX.md) · [FR](wiki/fr/INDEX.md) · [JA](wiki/ja/INDEX.md) · [KO](wiki/ko/INDEX.md) · [EN](wiki/INDEX.md)
## 🦞 What is ClawSec?
ClawSec is a **complete security skill suite for AI agent platforms**. It provides unified security monitoring, integrity verification, and threat intelligence-protecting your agent's cognitive architecture against prompt injection, drift, and malicious instructions.
package.json
+5
View File
@@ -10,6 +10,11 @@
"predev": "npm run gen:wiki-llms",
"dev": "vite",
"prebuild": "npm run gen:wiki-llms",
"i18n:qa": "python scripts/i18n/qa_check.py",
"i18n:bootstrap:ko": "python scripts/i18n/bootstrap_language_from_en.py --lang ko",
"i18n:bootstrap:fr": "python scripts/i18n/bootstrap_language_from_en.py --lang fr",
"i18n:bootstrap:de": "python scripts/i18n/bootstrap_language_from_en.py --lang de",
"i18n:bootstrap:ja": "python scripts/i18n/bootstrap_language_from_en.py --lang ja",
"build": "vite build",
"preview": "vite preview"
},
pages/WikiBrowser.tsx
+84 -2
View File
@@ -139,6 +139,26 @@ const wikiAssetByPath = new Map<string, string>(
const defaultDoc = wikiDocBySlug.get('index') ?? wikiDocs[0] ?? null;
const languageLabelByCode: Record<string, string> = {
en: 'English',
es: 'Español',
ko: '한국어',
fr: 'Français',
de: 'Deutsch',
ja: '日本語',
};
const languageIndexByCode = new Map<string, WikiDoc>(
wikiDocs
.map((doc) => {
const match = doc.slug.match(/^([^/]+)\/index$/i);
if (!match) return null;
const code = match[1].toLowerCase();
return [code, doc] as const;
})
.filter((entry): entry is readonly [string, WikiDoc] => entry !== null),
);
const toGroupName = (filePath: string): string => {
if (!filePath.includes('/')) return 'Core';
if (filePath.startsWith('modules/')) return 'Modules';
@@ -160,11 +180,16 @@ export const WikiBrowser: React.FC = () => {
requested = '';
}
const requestedSlug = requested || 'INDEX';
const requestedSlugLower = requestedSlug.toLowerCase();
const languageIndexFallback = languageIndexByCode.get(requestedSlugLower);
const selectedDoc = wikiDocBySlug.get(requestedSlug.toLowerCase()) ?? defaultDoc;
const selectedDoc =
wikiDocBySlug.get(requestedSlugLower) ??
languageIndexFallback ??
defaultDoc;
const notFound =
(decodeFailed && normalizedWildcard.length > 0) ||
(requested.length > 0 && !wikiDocBySlug.has(requestedSlug.toLowerCase()));
(requested.length > 0 && !wikiDocBySlug.has(requestedSlugLower) && !languageIndexFallback);
const groupedDocs = useMemo(() => {
const map = new Map<string, WikiDoc[]>();
@@ -209,6 +234,34 @@ export const WikiBrowser: React.FC = () => {
const pageLlmsPath = toWikiLlmsPath(activeSlug);
const showWikiLlmsIndexLink = !isWikiIndexSlug(activeSlug);
const localizedPrefix = Array.from(languageIndexByCode.keys()).find((code) =>
activeSlug.startsWith(`${code}/`),
);
const currentLanguageCode = localizedPrefix ?? 'en';
const activeBaseSlug = localizedPrefix
? activeSlug.slice(localizedPrefix.length + 1)
: activeSlug;
const languageOptions = [
{ code: 'en', label: languageLabelByCode.en ?? 'English' },
...Array.from(languageIndexByCode.keys())
.sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }))
.map((code) => ({
code,
label: languageLabelByCode[code] ?? code.toUpperCase(),
})),
].map((option) => {
const targetSlug = option.code === 'en' ? activeBaseSlug : `${option.code}/${activeBaseSlug}`;
const fallbackSlug = option.code === 'en' ? 'index' : `${option.code}/index`;
const resolvedSlug = wikiDocBySlug.has(targetSlug) ? targetSlug : fallbackSlug;
const translated = wikiDocBySlug.has(targetSlug);
return {
...option,
route: toWikiRoute(resolvedSlug),
translated,
};
});
const resolveWikiRouteFromHref = (href: string): string | null => {
if (!href || isExternalHref(href) || href.startsWith('mailto:') || href.startsWith('tel:')) {
return null;
@@ -291,6 +344,35 @@ export const WikiBrowser: React.FC = () => {
Full repository wiki rendered from markdown in <code className="text-gray-300">wiki/</code>.
This is the same source synced to GitHub Wiki.
</p>
<div className="flex flex-wrap items-center gap-2 text-sm text-gray-300">
<span className="text-gray-400">Language:</span>
{languageOptions.map((option) => {
const isActiveLanguage = option.code === currentLanguageCode;
return isActiveLanguage ? (
<span
key={option.code}
className="px-2 py-1 rounded bg-clawd-700 text-white border border-clawd-600"
>
{option.label}
</span>
) : (
<Link
key={option.code}
to={option.route}
className="px-2 py-1 rounded border border-clawd-700 hover:border-clawd-accent hover:text-white transition-colors"
title={option.translated ? `Open ${option.label} translation` : `Open ${option.label} index fallback`}
>
{option.label}
{option.translated ? (
<span className="text-gray-500"> · translated</span>
) : (
<span className="text-gray-500"> · index fallback</span>
)}
</Link>
);
})}
</div>
<div className="flex flex-wrap gap-3">
<a
href={pageLlmsPath}
scripts/i18n/bootstrap_language_from_en.py
+90
View File
@@ -0,0 +1,90 @@
#!/usr/bin/env python3
"""Create missing translated wiki pages from English source.
Usage:
python scripts/i18n/bootstrap_language_from_en.py --lang ko
python scripts/i18n/bootstrap_language_from_en.py --lang ko --dry-run
python scripts/i18n/bootstrap_language_from_en.py --lang ko --overwrite
"""
from __future__ import annotations
import argparse
from pathlib import Path
SKIP_TOP_LEVEL_DIRS = {"assets", "i18n", "modules"}
def build_header(lang: str, rel_path: str) -> str:
return (
f"<!-- AUTO-GENERATED TRANSLATION SCAFFOLD ({lang})\n"
f"Source: ../{rel_path}\n"
"Review status: draft\n"
"-->\n\n"
)
def discover_source_pages(wiki_root: Path, lang_dirs: set[str]) -> list[Path]:
pages: list[Path] = []
for page in wiki_root.rglob("*.md"):
rel = page.relative_to(wiki_root)
if not rel.parts:
continue
first = rel.parts[0]
if first in SKIP_TOP_LEVEL_DIRS or first in lang_dirs:
continue
pages.append(page)
return sorted(pages)
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--lang", required=True, help="language code, e.g. ko, es, fr")
parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--overwrite", action="store_true")
args = parser.parse_args()
repo_root = Path(__file__).resolve().parents[2]
wiki_root = repo_root / "wiki"
target_root = wiki_root / args.lang
lang_dirs = {
p.name
for p in wiki_root.iterdir()
if p.is_dir() and (p / "INDEX.md").exists() and p.name not in SKIP_TOP_LEVEL_DIRS
}
source_pages = discover_source_pages(wiki_root, lang_dirs)
created = 0
skipped = 0
overwritten = 0
for src in source_pages:
rel = src.relative_to(wiki_root)
dst = target_root / rel
existed_before = dst.exists()
if existed_before and not args.overwrite:
skipped += 1
continue
src_text = src.read_text(encoding="utf-8")
header = build_header(args.lang, rel.as_posix())
out = header + src_text
if not args.dry_run:
dst.parent.mkdir(parents=True, exist_ok=True)
dst.write_text(out, encoding="utf-8")
if existed_before:
overwritten += 1
else:
created += 1
mode = "DRY-RUN" if args.dry_run else "WRITE"
print(f"[{mode}] lang={args.lang} source_pages={len(source_pages)} created={created} overwritten={overwritten} skipped={skipped}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
scripts/i18n/fill_missing_translations_argos.py
+207
View File
@@ -0,0 +1,207 @@
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import re
from collections.abc import Iterable
from pathlib import Path
from argostranslate import translate
RE_INLINE_CODE = re.compile(r"`[^`]*`")
RE_MD_LINK = re.compile(r"\[[^\]]*\]\([^\)]*\)")
ENGLISH_HINTS = {
"a",
"an",
"and",
"are",
"as",
"at",
"be",
"before",
"by",
"for",
"from",
"if",
"in",
"is",
"of",
"on",
"or",
"the",
"this",
"to",
"use",
"using",
"when",
"with",
"you",
"your",
}
def _protect_tokens(line: str) -> tuple[str, dict[str, str]]:
mapping: dict[str, str] = {}
idx = 0
def repl(pattern: re.Pattern[str], text: str) -> str:
nonlocal idx
def _r(m: re.Match[str]) -> str:
nonlocal idx
key = f"ZXQTOKEN{idx}QXZ"
idx += 1
mapping[key] = m.group(0)
return key
return pattern.sub(_r, text)
out = line
out = repl(RE_MD_LINK, out)
out = repl(RE_INLINE_CODE, out)
return out, mapping
def _restore_tokens(line: str, mapping: dict[str, str]) -> str:
out = line
for key, value in mapping.items():
out = out.replace(key, value)
old_style = re.fullmatch(r"__TOK_(\d+)__", key)
if old_style:
idx = old_style.group(1)
out = re.sub(rf"_{{1,2}}TOK_{idx}_{{1,2}}", value, out)
continue
new_style = re.fullmatch(r"ZXQTOKEN(\d+)QXZ", key)
if new_style:
idx = new_style.group(1)
out = re.sub(rf"ZXQTOKEN{idx}\s+QXZ", value, out)
return out
def _should_translate(line: str) -> bool:
s = line.strip()
if not s:
return False
if s.startswith("<!--") or s.endswith("-->"):
return False
return True
def _translate_line(tr, line: str) -> str:
protected, mapping = _protect_tokens(line)
translated = tr.translate(protected)
restored = _restore_tokens(translated, mapping)
return restored
def _normalize_line(line: str) -> str:
return re.sub(r"\s+", " ", line.strip())
def _looks_like_english(line: str) -> bool:
words = re.findall(r"[A-Za-z]+", line.lower())
if not words:
return False
hint_count = sum(1 for word in words if word in ENGLISH_HINTS)
return hint_count >= 2
def _should_process_target_line(target_line: str, source_lines: set[str]) -> bool:
normalized = _normalize_line(target_line)
return normalized in source_lines or _looks_like_english(target_line)
def _process_pair(source: Path, target: Path, tr) -> int:
src_lines = source.read_text(encoding="utf-8").splitlines()
src_set = {_normalize_line(line) for line in src_lines if line.strip()}
tgt_lines = target.read_text(encoding="utf-8").splitlines()
changed = 0
in_code = False
for i, tgt in enumerate(tgt_lines):
if tgt.strip().startswith("```"):
in_code = not in_code
continue
if in_code:
continue
# Only fill lines that are still unchanged or visibly retain English fragments.
if not _should_process_target_line(tgt, src_set):
continue
if not _should_translate(tgt):
continue
new = _translate_line(tr, tgt)
if new and new != tgt:
tgt_lines[i] = new
changed += 1
if changed:
target.write_text("\n".join(tgt_lines) + "\n", encoding="utf-8")
return changed
def _normalize_only(values: Iterable[str] | None) -> set[str]:
normalized: set[str] = set()
for value in values or []:
item = value.strip().replace("\\", "/")
if not item:
continue
normalized.add(item)
normalized.add(Path(item).name)
return normalized
def _matches_only(path: Path, repo: Path, only: set[str]) -> bool:
if not only:
return True
rel = path.relative_to(repo).as_posix()
candidates = {path.name, rel}
return bool(candidates & only)
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--lang", required=True, choices=["de", "es", "fr", "ja", "ko"])
parser.add_argument(
"--only",
nargs="*",
default=None,
help="Optional list of target markdown filenames to process (e.g. README.ja.md overview.md security.md)",
)
args = parser.parse_args()
repo = Path(__file__).resolve().parents[2]
tr = translate.get_translation_from_codes("en", args.lang)
if tr is None:
raise SystemExit(f"Missing Argos en->{args.lang} model. Install first.")
total = 0
only = _normalize_only(args.only)
# README
readme_target = repo / f"README.{args.lang}.md"
if _matches_only(readme_target, repo, only):
total += _process_pair(repo / "README.md", readme_target, tr)
# wiki/<lang>
lang_root = repo / "wiki" / args.lang
for lang_file in sorted(lang_root.glob("*.md")):
if not _matches_only(lang_file, repo, only):
continue
if lang_file.name in {"INDEX.md", "GENERATION.md"}:
continue
src = repo / "wiki" / lang_file.name
if src.exists():
total += _process_pair(src, lang_file, tr)
print(f"Updated translated lines for {args.lang}: {total}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
scripts/i18n/link_check.py
+98
View File
@@ -0,0 +1,98 @@
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import re
import subprocess
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
MARKDOWN_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
def _all_docs() -> set[Path]:
files = set(ROOT.glob("README*.md"))
files.update(ROOT.glob("wiki/**/*.md"))
return {p for p in files if p.is_file()}
def _changed_docs(base_ref: str) -> set[Path]:
cmd = ["git", "diff", "--name-only", f"{base_ref}...HEAD"]
output = subprocess.check_output(cmd, cwd=ROOT, text=True)
docs: set[Path] = set()
for rel in output.splitlines():
if not rel.endswith(".md"):
continue
p = (ROOT / rel).resolve()
if p in _all_docs() and p.exists():
docs.add(p)
return docs
def _should_skip(link: str) -> bool:
return (
not link
or link.startswith("#")
or "://" in link
or link.startswith("mailto:")
or link.startswith("tel:")
)
def _resolve_target(doc: Path, link: str) -> Path:
clean = link.split("#", 1)[0].strip()
return (doc.parent / clean).resolve()
def _select_docs(changed_only: bool, base_ref: str) -> list[Path]:
all_docs = _all_docs()
if not changed_only:
return sorted(all_docs)
try:
changed = _changed_docs(base_ref)
except Exception as exc: # noqa: BLE001
print(f"[link-check] WARN: changed-only mode failed ({exc}); falling back to full scan")
return sorted(all_docs)
if not changed:
print("[link-check] No changed markdown docs detected; nothing to check.")
return []
return sorted(changed)
def main() -> int:
parser = argparse.ArgumentParser(description="Check local markdown links in README/wiki docs")
parser.add_argument("--changed-only", action="store_true", help="Check only changed markdown docs against a base ref")
parser.add_argument("--base-ref", default="origin/main", help="Base ref for --changed-only (default: origin/main)")
args = parser.parse_args()
docs = _select_docs(args.changed_only, args.base_ref)
failures: list[str] = []
for doc in docs:
rel_doc = doc.relative_to(ROOT)
content = doc.read_text(encoding="utf-8")
for match in MARKDOWN_LINK_RE.finditer(content):
raw_link = match.group(1).strip()
if _should_skip(raw_link):
continue
target = _resolve_target(doc, raw_link)
if not target.exists():
failures.append(f"{rel_doc}: broken link -> {raw_link}")
if failures:
print(f"[link-check] FAILED: {len(failures)} broken link(s) found.")
for item in failures:
print(f" - {item}")
return 1
scope = "changed docs" if args.changed_only else "all docs"
print(f"[link-check] PASS: no broken local markdown links found ({scope}).")
return 0
if __name__ == "__main__":
raise SystemExit(main())
scripts/i18n/qa_check.py
+208
View File
@@ -0,0 +1,208 @@
#!/usr/bin/env python3
"""Translation QA checks for ClawSec docs.
Validates markdown translation pairs with a focus on technical integrity:
- fenced code blocks are preserved exactly
- key inline technical tokens are preserved
- absolute URLs from source are preserved
- non-translatable product/skill terms are preserved
This script checks only pairs that already exist (partial translation is allowed).
"""
from __future__ import annotations
import re
import sys
from dataclasses import dataclass
from pathlib import Path
@dataclass(frozen=True)
class Pair:
source: Path
target: Path
NON_TRANSLATABLE_TERMS = (
"ClawSec",
"OpenClaw",
"NanoClaw",
"Hermes",
"Picoclaw",
"clawsec-suite",
)
def _extract_fenced_blocks(text: str) -> list[str]:
return re.findall(r"```[^\n]*\n.*?```", text, flags=re.DOTALL)
def _extract_inline_code(text: str) -> list[str]:
return re.findall(r"`([^`\n]+)`", text)
def _extract_absolute_urls(text: str) -> set[str]:
return set(re.findall(r"https?://[^\s)>'\"]+", text))
def _is_technical_inline_token(token: str) -> bool:
checks = (
"/" in token,
token.startswith("./"),
token.startswith("../"),
token.endswith(".md"),
token.endswith(".yml"),
token.endswith(".json"),
token.startswith("npx "),
token.startswith("npm "),
token.startswith("python "),
token.startswith("node "),
"--" in token,
bool(re.search(r"\$[A-Z_][A-Z0-9_]*", token)),
)
return any(checks)
def _collect_pairs(repo_root: Path) -> list[Pair]:
pairs: list[Pair] = []
readme_en = repo_root / "README.md"
for translated_readme in sorted(repo_root.glob("README.*.md")):
if translated_readme.name == "README.md":
continue
if readme_en.exists():
pairs.append(Pair(readme_en, translated_readme))
wiki_root = repo_root / "wiki"
language_dirs = {
p.name
for p in wiki_root.iterdir()
if p.is_dir() and (p / "INDEX.md").exists() and p.name not in {"modules", "i18n", "assets"}
}
for source in wiki_root.rglob("*.md"):
rel = source.relative_to(wiki_root)
rel_parts = rel.parts
if not rel_parts:
continue
# Skip language roots and i18n metadata as source files.
if rel_parts[0] in language_dirs or rel_parts[0] == "i18n":
continue
for lang in sorted(language_dirs):
target = wiki_root / lang / rel
if target.exists():
pairs.append(Pair(source, target))
return sorted(pairs, key=lambda p: str(p.source))
def _extract_command_lines_from_fence(block: str) -> list[str]:
lines = block.splitlines()[1:-1]
cleaned: list[str] = []
for line in lines:
candidate = line.strip()
if not candidate or candidate.startswith("#"):
continue
cleaned.append(candidate)
return cleaned
def _check_pair(pair: Pair) -> tuple[list[str], list[str]]:
errors: list[str] = []
warnings: list[str] = []
source_text = pair.source.read_text(encoding="utf-8")
target_text = pair.target.read_text(encoding="utf-8")
source_blocks = _extract_fenced_blocks(source_text)
target_blocks = _extract_fenced_blocks(target_text)
partial_pair = len(source_blocks) != len(target_blocks)
if partial_pair:
# Allow partial translations, but preserve command lines in translated fences.
for idx, target_block in enumerate(target_blocks, start=1):
for command_line in _extract_command_lines_from_fence(target_block):
if command_line not in source_text:
errors.append(
f"translated code fence #{idx} contains command line not found in source: {command_line}"
)
warnings.append(
f"partial translation detected (code fences source={len(source_blocks)} target={len(target_blocks)})"
)
else:
for idx, (src_block, tgt_block) in enumerate(zip(source_blocks, target_blocks), start=1):
src_commands = _extract_command_lines_from_fence(src_block)
tgt_commands = _extract_command_lines_from_fence(tgt_block)
if src_commands != tgt_commands:
errors.append(f"code fence #{idx} command lines differ from source")
source_inline = {tok for tok in _extract_inline_code(source_text) if _is_technical_inline_token(tok)}
missing_inline = sorted(tok for tok in source_inline if tok not in target_text)
if missing_inline:
preview = ", ".join(missing_inline[:8])
extra = "" if len(missing_inline) <= 8 else f" (+{len(missing_inline) - 8} more)"
msg = f"missing inline technical tokens: {preview}{extra}"
if partial_pair:
warnings.append(f"{msg} (partial pair)")
else:
warnings.append(msg)
source_urls = _extract_absolute_urls(source_text)
missing_urls = sorted(url for url in source_urls if url not in target_text)
if missing_urls:
preview = ", ".join(missing_urls[:5])
extra = "" if len(missing_urls) <= 5 else f" (+{len(missing_urls) - 5} more)"
msg = f"missing absolute URLs: {preview}{extra}"
if partial_pair:
warnings.append(f"{msg} (partial pair)")
else:
warnings.append(msg)
for term in NON_TRANSLATABLE_TERMS:
if term in source_text and term not in target_text:
errors.append(f"non-translatable term missing: {term}")
return errors, warnings
def main() -> int:
repo_root = Path(__file__).resolve().parents[2]
pairs = _collect_pairs(repo_root)
if not pairs:
print("[i18n-qa] No translation pairs found. Nothing to check.")
return 0
print(f"[i18n-qa] Checking {len(pairs)} translation pairs...")
total_errors = 0
total_warnings = 0
for pair in pairs:
rel_source = pair.source.relative_to(repo_root)
rel_target = pair.target.relative_to(repo_root)
errors, warnings = _check_pair(pair)
for warn in warnings:
total_warnings += 1
print(f"WARN {rel_source} -> {rel_target} :: {warn}")
if errors:
total_errors += len(errors)
print(f"\nFAIL {rel_source} -> {rel_target}")
for err in errors:
print(f" - {err}")
else:
print(f"PASS {rel_source} -> {rel_target}")
if total_errors:
print(f"\n[i18n-qa] FAILED with {total_errors} issue(s) and {total_warnings} warning(s).")
return 1
print(f"\n[i18n-qa] All checks passed with {total_warnings} warning(s).")
return 0
if __name__ == "__main__":
raise SystemExit(main())
scripts/i18n/test_fill_missing_translations_argos.py
+88
View File
@@ -0,0 +1,88 @@
from __future__ import annotations
import importlib.util
import sys
import tempfile
import types
import unittest
from pathlib import Path
def _load_module():
translate_stub = types.SimpleNamespace(get_translation_from_codes=lambda *_args: None)
sys.modules.setdefault("argostranslate", types.SimpleNamespace(translate=translate_stub))
module_path = Path(__file__).with_name("fill_missing_translations_argos.py")
spec = importlib.util.spec_from_file_location("fill_missing_translations_argos", module_path)
if spec is None or spec.loader is None:
raise RuntimeError(f"Unable to load {module_path}")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
class FakeTranslator:
def translate(self, line: str) -> str:
return (
line.replace("Brought to you von", "Bereitgestellt von")
.replace("the Platform of AI Security", "die Plattform fuer KI-Sicherheit")
.replace("requires WSL or Git Bash", "erfordern WSL oder Git Bash")
)
class FillMissingTranslationsArgosTests(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
cls.module = _load_module()
def test_restore_tokens_handles_placeholder_variants(self) -> None:
mapping = {
"__TOK_0__": "`bash`",
"__TOK_1__": "[Prompt Security](https://prompt.security)",
"ZXQTOKEN2QXZ": "`node`",
}
restored = self.module._restore_tokens(
"Use __TOK_0_, _TOK_1__, and ZXQTOKEN2 QXZ before running.",
mapping,
)
self.assertEqual(
restored,
"Use `bash`, [Prompt Security](https://prompt.security), and `node` before running.",
)
def test_process_pair_translates_lines_that_still_contain_english_fragments(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir:
root = Path(tmpdir)
source = root / "source.md"
target = root / "target.md"
source.write_text(
'<h4>Brought to you by <a href="https://prompt.security">Prompt Security</a>, '
"the Platform of AI Security</h4>\n",
encoding="utf-8",
)
target.write_text(
'<h4>Brought to you von <a href="https://prompt.security">Prompt Security</a>, '
"the Platform of AI Security>/h4>\n",
encoding="utf-8",
)
changed = self.module._process_pair(source, target, FakeTranslator())
self.assertEqual(changed, 1)
self.assertIn("Bereitgestellt von", target.read_text(encoding="utf-8"))
self.assertIn("die Plattform fuer KI-Sicherheit", target.read_text(encoding="utf-8"))
def test_only_matching_accepts_repo_relative_wiki_targets(self) -> None:
repo = Path("/repo")
target = repo / "wiki" / "ja" / "overview.md"
matches_only = getattr(self.module, "_matches_only", lambda *_args: False)
self.assertTrue(matches_only(target, repo, {"wiki/ja/overview.md"}))
self.assertTrue(matches_only(target, repo, {"overview.md"}))
self.assertFalse(matches_only(target, repo, {"wiki/ja/security.md"}))
if __name__ == "__main__":
unittest.main()
scripts/i18n/test_qa_check.py
+41
View File
@@ -0,0 +1,41 @@
from __future__ import annotations
import importlib.util
import sys
import tempfile
import unittest
from pathlib import Path
def _load_module():
module_path = Path(__file__).with_name("qa_check.py")
spec = importlib.util.spec_from_file_location("qa_check", module_path)
if spec is None or spec.loader is None:
raise RuntimeError(f"Unable to load {module_path}")
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module
spec.loader.exec_module(module)
return module
class QaCheckTests(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
cls.module = _load_module()
def test_partial_pairs_still_fail_when_non_translatable_terms_are_missing(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir:
root = Path(tmpdir)
source = root / "source.md"
target = root / "target.md"
source.write_text("ClawSec keeps this term.\n```sh\nnpm run build\n```\n", encoding="utf-8")
target.write_text("Translated text without the product term.\n", encoding="utf-8")
errors, warnings = self.module._check_pair(self.module.Pair(source, target))
self.assertIn("non-translatable term missing: ClawSec", errors)
self.assertTrue(any("partial translation detected" in warning for warning in warnings))
if __name__ == "__main__":
unittest.main()
wiki/INDEX.md
+8
View File
@@ -11,7 +11,15 @@
- [Overview](overview.md)
- [Architecture](architecture.md)
## Translations
- [Español](es/INDEX.md)
- [한국어](ko/INDEX.md)
- [Français (draft scaffold)](fr/INDEX.md)
- [Deutsch (draft scaffold)](de/INDEX.md)
- [日本語 (draft scaffold)](ja/INDEX.md)
## Guides
- [Localization Workflow](localization.md)
- [Dependencies](dependencies.md)
- [Data Flow](data-flow.md)
- [Configuration](configuration.md)
wiki/de/GENERATION.md
+42
View File
@@ -0,0 +1,42 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../GENERATION.md
Review status: draft
-->
# Wiki Generation Metadata
- Commit hash: `c3983a100581a9f27eb8cc3b5baa4f585e6c45e4`
- Branch name: `codex/clawsec-scanner-0.0.2-dast-harness`
- Generation timestamp (local): `2026-03-10T19:06:29+0200`
- Generation mode: `update`
- Output language: `English`
- Assets copied into `wiki/assets/`:
- `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
- `overview_img_02_clawsec-mascot.png` (from `public/img/mascot.png`)
- `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)
## Notes
- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
- Updated index and cross-links to use `wiki/` as the documentation source of truth.
- Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
- Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.
- 2026-04-26: Split Picoclaw self-pen-testing into dedicated `wiki/modules/picoclaw-self-pen-testing.md`, and updated `wiki/modules/picoclaw-security-guardian.md` to cover advisory/drift/supply-chain scope only.
- 2026-04-25: Added DeepWiki-friendly `wiki/modules/picoclaw-security-guardian.md` with support-matrix claims, threat model, default safety posture, frontend/advisory-board wiring, verification commands, and source references. Regenerated `public/wiki/**/llms.txt` exports with `npm run gen:wiki-llms`.
## Source References
- README.md
- package.json
- AGENTS.md
- wiki/overview.md
- wiki/architecture.md
- wiki/modules/clawsec-scanner.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- wiki/dependencies.md
- wiki/data-flow.md
- wiki/glossary.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
wiki/de/INDEX.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../INDEX.md
Review status: draft
-->
# Wiki Index
## Summary
- Purpose: Document ClawSec as a combined web catalog, signed advisory channel, and multi-skill security distribution system.
- Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines.
- Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`.
- Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing.
- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code.
## Start Here
- [Overview](overview.md)
- [Architecture](architecture.md)
## Translations
- [Español](../es/INDEX.md)
- [한국어](../ko/INDEX.md)
## Guides
- [Localization Workflow](localization.md)
- [Dependencies](dependencies.md)
- [Data Flow](data-flow.md)
- [Configuration](configuration.md)
- [Testing](testing.md)
- [Workflow](workflow.md)
- [Security](security.md)
## Operations
- [Security Signing Runbook](security-signing-runbook.md)
- [Signed Feed Migration Plan](migration-signed-feed.md)
- [Platform Verification Checklist](platform-verification.md)
- [Cross-Platform Remediation Plan](remediation-plan.md)
## Modules
- [Frontend Web App](../modules/frontend-web.md)
- [ClawSec Suite Core](../modules/clawsec-suite.md)
- [ClawSec Scanner](../modules/clawsec-scanner.md)
- [Hermes Attestation Guardian](../modules/hermes-attestation-guardian.md)
- [Hermes Attestation Guardian Draft History (Archived)](../modules/hermes-attestation-guardian-draft-history.md)
- [NanoClaw Integration](../modules/nanoclaw-integration.md)
- [Picoclaw Security Guardian](../modules/picoclaw-security-guardian.md)
- [Picoclaw Self Pen Testing](../modules/picoclaw-self-pen-testing.md)
- [Automation and Release Pipelines](../modules/automation-release.md)
- [Local Validation and Packaging Tools](../modules/local-tooling.md)
## Glossary
- [Glossary](glossary.md)
## Generation Metadata
- [Generation Metadata](GENERATION.md)
## Update Notes
- 2026-04-26: Split Picoclaw self-pen-testing into standalone `picoclaw-self-pen-testing`; updated Picoclaw module docs and references.
- 2026-04-25: Added Picoclaw Security Guardian module for advisory awareness, config drift detection, and chain-of-supply verification.
- 2026-04-19: Moved NanoClaw platform-support and CI/CD pipeline detail sections out of `README.md` into module pages (`modules/nanoclaw-integration.md`, `modules/automation-release.md`) and left README pointers.
- 2026-04-16: Added install-guard compatibility note for Hermes Attestation Guardian (community-source install now SAFE without `--force`; behavior unchanged).
- 2026-04-15: Expanded Hermes Attestation Guardian module page into full narrative, claim-by-claim operator guidance (no claim tables), and added archived draft-history module page.
- 2026-03-10: Added ClawSec Scanner module documentation and linked it under Modules.
- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.
## Source References
- README.md
- App.tsx
- package.json
- scripts/prepare-to-push.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- skills/clawsec-suite/skill.json
- skills/clawsec-scanner/skill.json
- skills/hermes-attestation-guardian/skill.json
- skills/picoclaw-security-guardian/skill.json
- skills/picoclaw-self-pen-testing/skill.json
- wiki/modules/clawsec-scanner.md
- wiki/modules/hermes-attestation-guardian.md
- wiki/modules/hermes-attestation-guardian-draft-history.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- .github/workflows/ci.yml
wiki/de/architecture.md
+136
View File
@@ -0,0 +1,136 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../architecture.md
Review status: draft
-->
# Architektur
• Systemkontext
- Ja. Diese Seite erscheint unter dem `Start Here` Abschnitt in `INDEX.md`.
- ClawSec sitzt zwischen vorgelagerten Nachrichtenquellen (NVD + Community-Probleme), GitHub Automation und Laufzeit Agent-Umgebungen.
- Ja. Das Repository veröffentlicht sowohl statische Website-Inhalte als auch unterzeichnete Artefakte, die Laufzeitfähigkeiten vor der Verwendung überprüfen.
- Externe Schauspielergruppen:
- GitHub Actions Läufer, die CI-, Release- und Feed-Workflows ausführen.
- OpenClaw/NanoClaw Agenten verbrauchen Fähigkeiten, Berater und Verifikationsskripte.
- Repository-Betreuer, die beratende Fragen und die Verschmelzung von Release/Tag-Änderungen anerkennen.
Komponenten
| Komponente | Standort | Verantwortung |
--- | --- | ---
| Web UI | `App.tsx`, `pages/`, `components/` | Renders-Katalog und Beratungs-Detail-Erfahrungen. |
| Advisory Feed Core | `advisories/feed.json*`, `skills/clawsec-suite/.../feed.mjs` | Stores, überprüft und parses Advisories mit abgelösten Signaturen/Checksums. |
| Skill Packages | `skills/*/` | Verteilt installierbare Sicherheitsfunktionen mit SBOM-Metadaten. |
| Local Automation Scripts | `scripts/*.sh` | Lokale Spiegel, Pre-Push-Checks und manuelle Release-Helfer erstellen. |
| CI/CD Workflows | `.github/workflows/*.yml` | Linting, Tests, NVD-Verschmutzung, Release-Verpackung und Pages bereitstellen. |
| Python Utility Layer | `utils/*.py` | Skill Metadatenvalidierung und Prüfsummengenerierung. |
oder Schlüsselflüsse
- Skill Katalogfluss:
1. Release/tag Workflows veröffentlichen Fähigkeiten Assets.
2. Deploy Workflow entdeckt Freigabevermögen und baut `public/skills/index.json`.
3. UI fetches `public/skills/index.json` und Skill-Docs für `/skills` Seiten.
- Beratender Förderstrom:
1. `poll-nvd-cves.yml` und `community-advisory.yml` update `advisories/feed.json`.
2. Fütterung wird unterschrieben und auf öffentliche Wege gespiegelt.
3. Runtime Haken / Schriften laden Remote Feed und Rückfall auf lokale signierte Kopien.
- Bewachter Installationsfluss:
1. Installer fordert Zielfähigkeit + Version.
2. Beitragsüberprüfungen betroffener Spektifizierer und Schwere-/Risikohinweise.
3. Exit-Code 42 erzwingt die zweite Bestätigung, wenn Berater übereinstimmen.
(Diagramme)
```mermaid
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"]
```
![Prompt Line Motif](../assets/architecture_img_01_prompt-line.svg)
Schnittstellen und Verträge
| Schnittstelle | Vertragsformular | Validierung |
--- | --- | ---
| Skill metadata | `skills/*/skill.json` | Gültig durch Python Dienstprogramm + CI-Versionsparitätsprüfungen. |
| Beratender Feed | JSON + Ed25519 abgelöste Signatur | Verifiziert durch `feed.mjs` und NanoClaw Signaturenprogramme. |
| Checksums manifest | `checksums.json` (+ optional `.sig`) | Parsed and hash-matched before trusting payloads. |
| Hook event interface | `HookEvent` (`type`, `action`, `messages`) | Runtime-Handler verarbeitet nur ausgewählte Ereignisnamen. |
| Workflow Release Benennung | Tag-Muster `<skill>-vX.Y.Z` | Parsed in Release/Deploy Workflows, um Fähigkeiten zu entdecken. |
oder Schlüsselparameter
| Parameter | Default | Effekt |
--- | --- | ---
| `CLAWSEC_FEED_URL` | `https://clawsec.prompt.security/advisories/feed.json` | Remote Advisory source for suite scripts/hooks. |
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | Ermöglicht temporäre unsignierte Fallback-Kompatibilität. |
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | Erfordert die Überprüfung der Prüfsumme, wo verfügbar. |
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | Das Drosselfenster für den Beratenden Haken scannen. |
| `CLAWSEC_SKILLS_INDEX_TIMEOUT_MS` | `5000` | Remote Skill Index fetch timeout for Catalog Discovery. |
| `PROMPTSEC_GIT_PULL` | `0` | Optionales Autopull, bevor das Watchdog Audit läuft. |
Fehlerbehandlung und Zuverlässigkeit
- Fütterung wird für ungültige Unterschriften und fehlerhafte Manifeste nicht geschlossen.
- Remote-Fetch-Ausfälle fallen anmutig zurück zu lokalen signierten Feeds.
- Hook state verwendet Atomdatei schreibt mit strengem Modus, wo unterstützt.
- UI-Seiten erkennen HTML-Rückschläge als JSON und vermeiden, beschädigte Daten zu machen.
- Workflow-Schritte durchsetzen Key-Fingerprint-Konsistenz, um Split-key Drift zu vermeiden.
Beispiel Snippets
```tsx
// 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>
```
```ts
// Guarded feed loading contract in advisory hook
const remoteFeed = await loadRemoteFeed(feedUrl, {
signatureUrl: feedSignatureUrl,
checksumsUrl: feedChecksumsUrl,
checksumsSignatureUrl: feedChecksumsSignatureUrl,
publicKeyPem,
checksumsPublicKeyPem: publicKeyPem,
allowUnsigned,
verifyChecksumManifest,
});
```
Laufzeit und Bereitstellung
| Laufzeit Oberfläche | Ausführungsmodell | Ausgabe |
--- | --- | ---
| Vite App (`npm run dev`) | Lokaler Frontendserver | Interaktive Web-App für Feed/Skills. |
| GitHub CI | Multi-OS-Matrix + dedizierte Jobs | Lint/Typ/Bau/Sicherheit und Testvertrauen. |
| Skill release workflow | Tag-getriebene veröffentlichen + PR-Trocken-run-Checks | Freigabevermögen, unterzeichnete Prüfsummen, optional ClawHub veröffentlichen. |
| Seiten bereitstellen Workflow | Ausgelöst von CI/Release Erfolg | Statische Website + gespiegelte Berater/Releases. |
| Runtime Haken | OpenClaw Event Haken / NanoClaw IPC | Beratende Alarme, Gating Entscheidungen, Integritätskontrollen. |
Skalierungshinweise
- Beratende Volumenwaagen mit Schlüsselwort in NVD-Abfrage; Dedupe und Nachfilterung Steuergeräusche.
- Bereitstellung von Workflow-Prozessen Release-Listen und hält neueste Qualifikationsversionen in Indexausgabe.
- Modulgrenzen nach Fachordner ermöglichen es, neue Sicherheitsfunktionen hinzuzufügen, ohne Frontendstruktur zu ändern.
- Unterschriftsverifikationspfade bleiben leicht, da die Nutzlastgrößen (Feed/Manifests) klein sind.
Quellenangaben
- App.tsx
- Seiten/SkillsCatalog.tsx
- Seiten/FeedSetup.tsx
- Seiten/AdvisoryDetail.tsx
- Seiten/WikiBrowser.tsx
- Fertigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- Fertigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- Fertigkeiten/Clawsec-suite/scripts/guarded_skill_install.mjs
- Fertigkeiten/Clawsec-suite/scripts/discover_skill_catalog.mjs
- Fertigkeiten/Clawsec-nanoclaw/lib/advisories.ts
- Fertigkeiten/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
wiki/de/configuration.md
+93
View File
@@ -0,0 +1,93 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../configuration.md
Review status: draft
-->
# Konfiguration
Anwendungsbereich
- Konfiguration erstreckt sich über Frontend Build-Einstellungen, Laufzeit-Feed-Pfade, Workflow-Trigger und Kompetenz-Metadaten-Verträge.
- Die meisten Runtime-sensitiven Steuerungen sind Umgebungsvariablen, die mit `CLAWSEC_` oder `OPENCLAW_` vorgegeben sind.
- Die Path-Normalisierung ist sicherheitsempfindlich und lehnt absichtlich ungelöste Heim-Token-Literaturen ab.
Variablen Core Runtime
| Variable | Default | Wird von | verwendet
--- | --- | ---
| `CLAWSEC_FEED_URL` | Hosted Advisory URL | Suite Haken und bewachte Installations-Feed-Ladung. |
| `CLAWSEC_FEED_SIG_URL` | `<feed>.sig` | Gelöschte Signaturquelle. |
| `CLAWSEC_FEED_CHECKSUMS_URL` | `checksums.json` in der Nähe der Feed-URL | Optionale Prüfsumme-manifest-Quelle. |
| `CLAWSEC_FEED_PUBLIC_KEY` | Suite-local PEM-Datei | Signaturverifikation füttern. |
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | Temporäre Migrationsbypass-Flagge. |
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | Ermöglicht die Überprüfung von Prüfsummen-Manifest. |
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | Beratende Haken-Scandrossel. |
/ Wegeauflösungsregeln
| Regel | Verhalten | Durchsetzung Standort |
--- | --- | ---
| `~` Erweiterung | Aufgelöst auf erkanntes Home-Verzeichnis | Geteilte Pfad-Dienstfunktionen in Suite/watchdog-Skripten. |
| `$HOME` / `${HOME}` Erweiterung | Aufgelöst, wenn nicht | Gleiche Dienstprogramme. |
| Windows home tokens | `%USERPROFILE%`, `$env:USERPROFILE` normalisiert | Gleiche Dienstprogramme. |
| Escaped tokens (`\$HOME`) | Ausgestoßen mit explizitem Fehler | Verhindert die zufällige buchstäbliche Verzeichnis-Erstellung. |
| Ungültiger expliziter Pfad | Kann mit Warnung auf Standardpfad zurückfallen . `resolveConfiguredPath` Helfer. |
Frontend und Build Konfiguration
- `vite.config.ts` definiert Port (`3000`), Host (`0.0.0.0`) und Pfad-Alias (`@`_).
- `index.html` bietet Tailwind Runtime config, benutzerdefinierte Schriften, und Grundfarbe Tokens.
- `tsconfig.json` verwendet die Paketermodulauflösung `noEmit` und die JSX Laufzeitkonfiguration.
- `eslint.config.js` TS, React, Haken und Script-spezifische Lint Regeln.
Metadaten der Fähigkeiten Konfiguration
| Feldgruppe | Standort | Funktion |
--- | --- | ---
| Kernkompetenzidentität | `skills/*/skill.json` | Name/Version/Autor/Lizenz/Beschreibung Metadaten. |
| SBOM-Dateiliste | `skill.json -> sbom.files` | Erklärt Release-erforderliche Artefakte. |
| Platform metadata | `openclaw` oder `nanoclaw` Blöcke | CLI Anforderungen, Trigger, Plattformfähigkeitshinweise. |
| Suite Katalog Metadaten | `skills/clawsec-suite/skill.json -> catalog` | Integriertes/Standard/consent Verhalten für Suite-Mitglieder. |
 Workflow Konfiguration
- Die Schedule-Konfiguration existiert im Workflow `cron` Einträge (`poll-nvd-cves`, `codeql`, `scorecard`.
- Release Workflow erwartet Tag Benming-Muster `<skill>-v<semver>`.
- Der Arbeitsablauf wird durch erfolgreiche CI/Release `workflow_run` Ereignisse und manuelle Versendung ausgelöst.
- Composite Signing Aktion erfordert private Schlüsseleingänge und überprüft Signaturen unmittelbar nach der Unterzeichnung.
Beispiel Snippets
```bash
# run guarded install with explicit local signed feed paths
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```
```json
{
"name": "example-skill",
"version": "1.2.3",
"sbom": {
"files": [
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
]
}
}
```
Betriebshinweise
- Halten Sie die Zeichentasten vor dem Repository und injizieren Sie nur über GitHub Secrets.
- Bestimmen Sie absolute Pfade oder unescaped Home Expressions in lokalen Umgebungsvariablen übergeordnet.
- Behandeln Sie den nicht zugewiesenen Feed-Modus als temporäre Migrationsunterstützung, nicht normaler Betrieb.
- Re-run release-link Validierung bei der Bearbeitung `SKILL.md`_ URLs, um gebrochene Artefakte Referenzen zu vermeiden.
Quellenangaben
- vite.config.ts
- index.html
- tsconfig.json
- eslint.config.js
- Fähigkeiten/Clawsec-suite/skill.json
- Fertigkeiten/Klausel-Nanoclaw/skill.json
- Fertigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs
- Fertigkeiten/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- Fertigkeiten/Clawsec-suite/scripts/guarded_skill_install.mjs
- Skripte/validate-release-links.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/skill-release.yml
- .github/actions/sign-and-verify/action.yml
wiki/de/data-flow.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../data-flow.md
Review status: draft
-->
# Datenfluss
Primäre Ströme
- `Advisory ingestion`: NVD/Gemeinde-Eingänge werden in einen normalisierten Beratungsfeed umgewandelt, signiert, dann für Kunden gespiegelt.
- `Skill catalog publication`: Freigabevermögen werden entdeckt und in `public/skills/index.json` plus per-skill docs/checksums umgewandelt.
- `Runtime enforcement`: Suite- und Nanoclaw-Verbraucher laden beratende Daten, passen gegen Fähigkeiten und senden Alarme oder Bestätigungs-Gate aus.
- Ja. Diese Seite erscheint unter dem `Guides` Abschnitt in `INDEX.md`.
Schritt für Schritt
ANHANG Feed-Produzent Workflow/script holt Quelldaten (`NVD API` oder Ausgabe Payload) ab.
2. JSON-Transformationslogik normalisiert Schwere/Typ/beeinflusste Felder und dedupliziert durch Beratungs-ID.
3. Signatur/Checksum-Schritte erzeugen abgelöste Signaturen und Prüfsummen manifestiert.
4. Bereitstellung von Workflow-Spiegeln signiert Artefakte unter `public/` und `public/releases/latest/download/`.
5. UI-Verbraucher validieren JSON Shape/Content; Laufzeit-Verbraucher überprüfen zusätzlich Signaturen/Checksums vor vertrauensvollen Feed-Daten.
6. Die Matcher vergleichen `affected`-Spezifikatoren mit Geschicksnamen/Versionen und senden Alarme aus oder setzen die Bestätigung durch.
Eingänge und Ausgänge
Inputs/Outputs sind in der folgenden Tabelle zusammengefasst.
| Typ | Name | Standort | Beschreibung |
| --- | --- | ---
| Input | CVE Payloads | `services.nvd.nist.gov/rest/json/cves/2.0` | Source Schwachstellen gefiltert durch ClawSec Keywords. |
| Input | Community Advisory Issue | `.github/workflows/community-advisory.yml` Event Payload | Maintainer-genehmigte Ausgabe verwandelt in Advisory Record. |
| Input | Skill release Assets | GitHub veröffentlicht API + Assets | Wird verwendet, um Webkatalog und Spiegel-Downloads zu erstellen. |
| Input | Local config/env | `OPENCLAW_AUDIT_CONFIG`, `CLAWSEC_*` vars | Controls Feed-Tracking, Unterdrückung und Verifikationsverhalten. |
| Ausgabe | Beratender Feed | `advisories/feed.json` | Canonical Repository Feed. |
| Ausgabe | Beratende Signatur | `advisories/feed.json.sig` | Entschlossene Signatur für Feed-Authentizität. |
| Ausgabe | Skill Katalogindex | `public/skills/index.json` | Runtime Webkatalog verwendet von `/skills` Seiten. |
| Ausgabe | Release Schecksums/signatures | `release-assets/checksums.json(.sig)` | Integrity manifest for release Konsumenten. |
| Ausgabe | Hook state | `~/.openclaw/clawsec-suite-feed-state.json` | Verfolgen Sie Scan-Terminal und angezeigte Spiele. |
oder Datenstrukturen
| Struktur | Schlüsselfelder | Zweck |
--- | --- | ---
| Beratender Feed-Record | `id`, `severity`, `type`, `affected[]`, `published`_ | Einheit der von UI und Installern verwendeten Risikodaten. |
| Skill Metadatensatz | `id`, `name`, `version`, `emoji`, `tag` | Katalogzeile für Web-Browsing und Installationsbefehle. |
| Checksums manifest | `schema_version`, `algorithm`, `files` | Kartendateinamen, die erwartete Verdauungen aufweisen. |
| Beratender Zustand | `known_advisories`, `last_hook_scan`, `notified_matches` | Verhindert wiederholte Warnungen und Drosseln Scans. |
| Suppression config | `enabledFor[]`, `suppressions[]` | Gezielte Liste der Skipisten von `checkId` + `skill`.
(Diagramme)
```mermaid
flowchart LR
A["NVD + Issue Inputs"] --> B["Transform + Deduplicate"]
B --> C["advisories/feed.json"]
C --> D["Sign + checksums"]
D --> E["public/advisories + releases/latest"]
E --> F["Web UI fetch"]
E --> G["Suite/NanoClaw verification"]
G --> H["Match skills + emit alerts/gates"]
```
Zustand und Lagerung
| Pfad/Scope | Pfad schreiben |
--- | --- | ---
| Canonical Advisories | `advisories/` | NVD + Community Workflows und lokales Populärskript. |
| Embedded-Beratungskopien | `skills/clawsec-feed/advisories/` und `skills/clawsec-suite/advisories/` | Sync/Packaging-Prozesse und Release-Workflow. |
| Öffentliche Spiegel | `public/advisories/`, `public/releases/` | Workflow bereitstellen. |
| Laufzeit Zustand | `~/.openclaw/clawsec-suite-feed-state.json` | Beratender Haken Zustand Beharrlichkeit. |
| NanoClaw cache | `/workspace/project/data/clawsec-advisory-cache.json` | Host-side Advisory cache manager. |
| Integritätszustand | `/workspace/project/data/soul-guardian/` (NanoClaw) | Integritätsmonitor Basis-/Auditspeicher. |
Beispiel Snippets
```bash
# Local feed flow (NVD fetch -> transform -> sync)
./scripts/populate-local-feed.sh --days 120
jq '.updated, (.advisories | length)' advisories/feed.json
```
```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Nicht verfügbar
- NVD-Ratenlimits (`403/429`) können die Feed-Erfrischung verzögern und Retries/Backoff benötigen.
- Fehlende oder ungültige abgelöste Signaturen verursachen die Ablehnung von Futtermitteln im fehlgeschlagenen Modus.
- HTML Fallback-Antworten für JSON Endpunkte können falsche Positive erzeugen, es sei denn, explizit gefiltert.
- Die Path-token-Fehlerkonfiguration (`\$HOME`) kann die lokale Fallbackpfadauflösung brechen.
- Unübertroffene öffentliche Schlüssel Fingerabdrücke in Workflows lösen harte CI-Versagen aus.
Quellenangaben
- Berater/feed.json
- Berater/feed.json.sig
- Skripte/Popula-lokal-feed.sh
- Skripte/Popula-lokal-skills.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- Fertigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- Fertigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/lib/state.ts
- Fähigkeiten/Clawsec-suite/hooks/clawsec-advisory-guardian/lib/matching.ts
- Fertigkeiten/Clawsec-suite/scripts/guarded_skill_install.mjs
- Fertigkeiten/Clawsec-nanoclaw/lib/advisories.ts
- Fähigkeiten/Clawsec-nanoclaw/host-services/advisory-cache.ts
wiki/de/dependencies.md
+106
View File
@@ -0,0 +1,106 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../dependencies.md
Review status: draft
-->
# Abhängigkeiten
Aufbau und Laufzeit
| Ebene | Primärabhängigkeiten | Warum es existiert |
--- | --- | ---
| Frontend Laufzeit | `react`, `react-dom`, `react-router-dom`, `lucide-react` | UI Rendering, Routing, Iconographie. |
| Markdown Rendering | `react-markdown`, `remark-gfm` | Render Skill-Docs/readmes und in-app Wiki-Markdown-Seiten. |
| Werkzeugbau | `vite`, `@vitejs/plugin-react`, `typescript` | Fast TS/TSX Bündelung und Produktion baut. |
| Python utilities | stdlib + `ruff`/`bandit` Policy from `pyproject.toml` | Gültige/Paketfähigkeiten und führen statische Überprüfungen durch. |
| Shell Automation | `bash`, `jq`, `curl`, `openssl`, `sha256sum`_`shasum` | Fütterung, Signierung, Prüfsummenerzeugung, Freigabeprüfungen. |
Abhängige Details
| Paket | Version Constraint | Scope |
--- | --- | ---
| `react` / `react-dom` | `^19.2.4` | Vorneige Laufzeit |
| `react-router-dom` | `^7.13.1` | Frontend Routing |
| `lucide-react`_ | `^0.575.0` | UI Symbolsatz |
| `vite` | `^7.3.1` | Dev Server + build |
| `typescript` | `~5.8.2` | Typkontrolle |
|
| `@typescript-eslint/*` | `^8.55.0` / `^8.56.0` | TS lint parser/rules |
| `fast-check` | `^4.5.3` | Immobilien/Fuss-Style-Tests |
| Override | Pinned Version | Rationale |
--- | --- | ---
| `ajv` | `6.14.0` | Sicherheit und Kompatibilitätsstabilisierung. |
| `balanced-match` | `4.0.3` | Transitive Sicherheitskontrolle. |
| `brace-expansion` | `5.0.2` | Übergangsabhängigkeitsverfestigung. |
| `minimatch` | `10.2.1` | Deterministische Abhängigkeitsverhalten. |
Externe Dienste
| Service | Gebraucht von | Funktion |
--- | --- | ---
| NVD API (`services.nvd.nist.gov`) | `poll-nvd-cves` Workflow + lokales Feed-Skript | Pull CVEs nach Schlüsselwort/Datumsfenster. |
| GitHub API | Workflows bereitstellen/erleichtern | Releases entdecken, Assets herunterladen, Outputs veröffentlichen. |
| GitHub Pages | Workflow bereitstellen | statische Seite und gespiegelte Artefakte bedienen. |
| ClawHub CLI/Registry | Installieren Sie Skripte + optionale Jobs | Installieren und veröffentlichen Sie Fähigkeiten. |
| Optional lokale SMTP/sendmail | `openclaw-audit-watchdog` Scripts | Auditberichte per E-Mail liefern. |
/ Entwicklungswerkzeuge
| Tool | Invocation | Coverage |
--- | --- | ---
| ESLint | `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0` | Frontend und Skriptlinting. |
| TypeScript | `npx tsc --noEmit` | Laufzeit TS Vertragsüberprüfungen. |
| Ruff | `ruff check utils/` | Python-Stil und Bug-Muster überprüfen. |
| Bandit | `bandit -r utils/ -ll` | Python Sicherheitskontrollen. |
| Trivy | Workflow + optionaler lokaler Run | FS/config Sicherheitsscans. |
| Gitleaks | `scripts/prepare-to-push.sh` optionaler lokaler Run | Secret Leck Erkennung vor dem Push. |
Beispiel Snippets
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.4",
"react-router-dom": "^7.13.1"
}
}
```
```toml
[tool.ruff]
target-version = "py310"
line-length = 120
[tool.bandit]
exclude_dirs = ["__pycache__", ".venv"]
skips = ["B101"]
```
In den Warenkorb
- Lokale Skripte Konto für macOS vs Linux Unterschiede in `date` und `stat` Nutzung.
- Einige Workflows/scripts erfordern OpenSSL-Funktionen, die mit Ed25519 und `pkeyutl -rawin` verwendet werden.
- Windows-Unterstützung ist am stärksten für Node-basierte Tooling; POSIX Shell-Pfade kann WSL / Git Bash benötigen.
- Zu den Futtermittelverbrauchern gehören Kompatibilitätsbypasses für Migrationsphasen, aber der unterzeichnete Modus ist der beabsichtigte stationäre Zustand.
In den Warenkorb
- Skill Release-Tags folgen `<skill>-v<semver>` und werden von CI/Deploy Automation parsed.
- Die PR-Validierung erzwingt die Versionsparität zwischen `skill.json` und `SKILL.md` Frontmatter für sprunghafte Fähigkeiten.
- Ja. Der Public Skill Index hält die neueste entdeckte Version pro Geschick für UI-Display.
- Signierte Artefakte Manifeste (`checksums.json`) werden pro Veröffentlichung veröffentlicht und beinhalten File Hashes und URLs.
Quellenangaben
- Paket.json
- Paket-lock.json
- pyproject.toml
- eslint.config.js
- tsconfig.json
- Skripte/Präpare-to-push.sh
- Skripte/Popula-lokal-feed.sh
- Skripte/Popula-lokal-skills.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
wiki/de/exploitability-scoring.md
+425
View File
@@ -0,0 +1,425 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../exploitability-scoring.md
Review status: draft
-->
# Exploitability Scoring Methodology
## Overview
ClawSec's exploitability scoring system provides context-aware vulnerability assessment specifically designed for AI agent deployments (OpenClaw/NanoClaw). Unlike generic CVSS scores that treat all environments equally, our scoring considers the unique attack surface and usage patterns of AI agents to reduce alert fatigue and prioritize actionable threats.
## Scoring Levels
| Level | Severity | Meaning |
|---|---|---|
| `high` | Critical/High | Exploitable in typical agent deployments, immediate attention required |
| `medium` | Medium | May be exploitable depending on configuration, warrants investigation |
| `low` | Low | Limited exploitability in agent context, low priority |
| `unknown` | Unknown | Insufficient data to assess exploitability |
## Scoring Factors
### 1. CVSS Base Score (Baseline)
The analysis starts with the CVSS base score as a foundation:
- **CVSS ≥ 9.0**: Critical severity → initial score `high`
- **CVSS 7.0-8.9**: High severity → initial score `high`
- **CVSS 4.0-6.9**: Medium severity → initial score `medium`
- **CVSS 1.0-3.9**: Low severity → initial score `low`
- **No CVSS**: → initial score `unknown`
### 2. Attack Vector Analysis (CVSS Metrics)
The analyzer parses CVSS v2, v3.0, and v3.1 vectors to assess:
#### Network Accessibility
- **AV:N** (Network): Remotely exploitable over network
- **AV:A** (Adjacent): Requires local network access
- **AV:L** (Local): Requires local system access
- **AV:P** (Physical): Requires physical access
**Impact on agents**: Network-accessible vulnerabilities are elevated because agents typically run as network services or make external API calls.
#### Authentication Requirements
- **PR:N / Au:NONE**: No authentication required → elevates score
- **PR:L / Au:SINGLE**: Low privileges required
- **PR:H / Au:MULTIPLE**: High privileges required → reduces score
**Impact on agents**: Unauthenticated exploits are critical for publicly exposed agent APIs.
#### User Interaction
- **UI:N**: No user interaction required → elevates score
- **UI:R**: Requires user interaction → reduces score
**Impact on agents**: Agents often operate autonomously, so vulnerabilities requiring user interaction are less critical.
#### Attack Complexity
- **AC:L**: Low complexity → elevates score
- **AC:M / AC:H**: Medium/High complexity → neutral or reduces score
**Impact on agents**: Low-complexity exploits are more likely to be automated and used in mass attacks.
### 3. Vulnerability Type (Deployment Context)
ClawSec adjusts scores based on how vulnerability types affect AI agent deployments:
#### High-Risk Types in Agent Context
**Remote Code Execution (RCE)**
```
Score: Always HIGH
Rationale: RCE is critical in agent deployments
```
AI agents execute arbitrary code as part of their function. RCE vulnerabilities allow attackers to hijack agent execution flow, exfiltrate credentials, or pivot to other systems.
**Server-Side Request Forgery (SSRF)**
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: SSRF affects agents making external requests
```
Agents frequently call external APIs, access internal services, and fetch remote resources. SSRF allows attackers to:
- Access internal cloud metadata services (AWS IMDSv1, GCP metadata)
- Pivot to internal networks
- Exfiltrate data through DNS tunneling
**Path Traversal / Directory Traversal**
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: Path traversal affects agents with file access
```
Agents read files, execute scripts, and manage codebases. Path traversal enables:
- Reading sensitive configuration files (.env, credentials)
- Accessing SSH keys, API tokens
- Overwriting critical system files
**Command Injection**
```
Score: Always HIGH
Rationale: Command injection is critical in agent deployments
```
Similar to RCE, agents often execute shell commands to interact with systems. Command injection allows full system compromise.
#### Medium-Risk Types
**Prototype Pollution (Node.js)**
```
Score: Elevated from LOW to MEDIUM
Rationale: Prototype pollution can escalate in Node.js agents
```
Many agent frameworks run on Node.js. Prototype pollution can lead to:
- Bypass of authentication checks
- Privilege escalation
- Denial of service
**SQL Injection / NoSQL Injection**
```
Score: Elevated to HIGH if network-accessible and unauthenticated
Rationale: Injection affects agents with database access
```
Agents that store conversation history, user data, or tool results in databases are vulnerable to injection attacks.
#### Lower-Risk Types
**Cross-Site Scripting (XSS)**
```
Score: Reduced to MEDIUM if not network-accessible
Rationale: XSS has limited impact in headless agents
```
Agents typically don't render HTML in browsers, reducing XSS impact. However, XSS in agent management UIs or chat interfaces remains a concern.
### 4. Exploit Availability
When `--check-exploits` is enabled, the analyzer checks reference URLs for public exploits:
**Exploit Indicators:**
- exploit-db.com / exploit-database.com
- packetstormsecurity.com
- github.com/exploit, github.com/poc
- metasploit framework modules
- URLs containing "/exploit", "/poc", "/proof-of-concept"
**Score Elevation:**
- `low` → `medium` (exploit available)
- `medium` → `high` (exploit available)
- `unknown` → `medium` (exploit available + CVSS > 0)
**Rationale**: Public exploits lower the skill barrier for attackers and increase the likelihood of automated exploitation.
## Scoring Algorithm
The analyzer follows this decision tree:
```
1. Parse CVSS score → set baseline (high/medium/low/unknown)
2. Parse CVSS vector → analyze attack characteristics
3. Adjust for attack vector:
- Network-accessible + no auth + no UI → elevate to HIGH
- Local-only access → reduce HIGH to MEDIUM
4. Adjust for vulnerability type:
- Check against agent-specific risk categories
- Elevate or reduce score based on deployment context
5. Check for public exploits (if enabled):
- Elevate score if exploits detected
6. Generate rationale explaining the final score
```
## Examples
### Example 1: Critical RCE (High Exploitability)
```json
{
"cve_id": "CVE-2024-12345",
"cvss_score": 9.8,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"type": "remote_code_execution",
"description": "Unauthenticated RCE in Express.js framework"
}
```
**Analysis Output:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments"
}
```
**Why HIGH**: Critical CVSS + network accessible + no auth + RCE type.
### Example 2: SSRF in Agent API (High Exploitability)
```json
{
"cve_id": "CVE-2024-23456",
"cvss_score": 7.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:L",
"type": "server_side_request_forgery",
"description": "SSRF in webhook handler allows internal network access"
}
```
**Analysis Output:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "High CVSS score (7.3); remotely exploitable without authentication; SSRF affects agents making external requests"
}
```
**Why HIGH**: SSRF is critical for agents that make API calls (most do). Network-accessible without authentication elevates risk.
### Example 3: Path Traversal with Public Exploit (High Exploitability)
```json
{
"cve_id": "CVE-2024-34567",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"type": "path_traversal",
"references": [
"https://exploit-db.com/exploits/51234",
"https://nvd.nist.gov/vuln/detail/CVE-2024-34567"
]
}
```
**Analysis Output (with --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (6.5); network accessible; path traversal affects agents with file access; public exploit available (1 source)"
}
```
**Why HIGH**: Path traversal + agent file access + public exploit elevates medium CVSS to high exploitability.
### Example 4: XSS in Agent UI (Medium Exploitability)
```json
{
"cve_id": "CVE-2024-45678",
"cvss_score": 7.1,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:L",
"type": "cross_site_scripting",
"description": "Stored XSS in agent management dashboard"
}
```
**Analysis Output:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (7.1); network accessible; XSS has limited impact in headless agents"
}
```
**Why MEDIUM**: Despite high CVSS, XSS is less critical in agent deployments (headless operation). Requires user interaction.
### Example 5: Local Privilege Escalation (Medium Exploitability)
```json
{
"cve_id": "CVE-2024-56789",
"cvss_score": 8.8,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
"type": "privilege_escalation",
"description": "Local privilege escalation via symbolic link attack"
}
```
**Analysis Output:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (8.8); requires local access"
}
```
**Why MEDIUM**: Despite high CVSS, requires local access. Agents typically run in containerized/sandboxed environments where local escalation has limited impact.
### Example 6: Prototype Pollution with Exploit (High Exploitability)
```json
{
"cve_id": "CVE-2024-67890",
"cvss_score": 5.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N",
"type": "prototype_pollution",
"description": "Prototype pollution in lodash merge function",
"references": [
"https://github.com/exploit/prototype-pollution-poc",
"https://snyk.io/vuln/SNYK-JS-LODASH-1234567"
]
}
```
**Analysis Output (with --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (5.3); remotely exploitable without authentication; prototype pollution can escalate in Node.js agents; public exploit available (1 source)"
}
```
**Why HIGH**: Prototype pollution in Node.js agents + public exploit + network-accessible without auth = high risk despite moderate CVSS.
## Usage in ClawSec Workflows
### Automated Scoring (NVD Feed)
The `poll-nvd-cves.yml` workflow automatically scores new CVEs:
```bash
# Workflow step
python utils/analyze_exploitability.py --json --check-exploits < cve-data.json
```
Advisories in `advisories/feed.json` can include:
```json
{
"id": "CVE-2024-12345",
"severity": "high",
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments",
"attack_vector_analysis": {
"is_network_accessible": true,
"requires_authentication": false,
"requires_user_interaction": false,
"complexity": "low"
}
}
```
### Manual Analysis
Security researchers can analyze CVEs manually:
```bash
# Basic analysis
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"type":"ssrf"}' | \
python utils/analyze_exploitability.py --json
# With exploit detection
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"references":["https://exploit-db.com/exploits/51234"]}' | \
python utils/analyze_exploitability.py --json --check-exploits
```
### Filtering by Exploitability
Users can filter advisories by exploitability score:
```bash
# Get only high-exploitability advisories
curl -s https://clawsec.prompt.security/feed.json | \
jq '.advisories[] | select(.exploitability_score == "high")'
# Prioritize by exploitability and severity
curl -s https://clawsec.prompt.security/feed.json | \
jq '[.advisories[] | select(.exploitability_score == "high" and .severity == "critical")] | sort_by(.cvss_score) | reverse'
```
## Backfilling Existing Advisories (Historical Maintenance)
`scripts/backfill-exploitability.sh` is retained as a historical maintainer utility for one-off repository maintenance.
It is not the primary path for normal advisory generation.
Preferred paths:
1. CI canonical path: run the NVD workflow with init/reset to rebuild advisories from NVD and sign artifacts in pipeline.
2. Local developer path: run `./scripts/populate-local-feed.sh --force` to repopulate local feeds with exploitability context.
Use backfill only when explicitly repairing legacy feed content that already exists in-repo.
## Community Contributions
Community members can submit exploitability assessments:
1. **Report via GitHub Issue**: Use the advisory template to report CVEs with exploitability context
2. **Automated Analysis**: The `community-advisory.yml` workflow automatically scores community-reported CVEs
3. **Manual Review**: Maintainers review and approve exploitability assessments
4. **Feed Update**: Approved advisories are added to the feed with exploitability scores
## Limitations and Future Work
### Current Limitations
1. **Static Analysis**: Scoring is based on CVE metadata, not dynamic runtime analysis
2. **No Version Detection**: Doesn't check if specific versions are vulnerable
3. **Binary Classification**: Doesn't consider partial mitigations or defense-in-depth
4. **Limited Context**: Doesn't know exact agent configuration or deployed tools
### Future Enhancements
1. **EPSS Integration**: Incorporate EPSS (Exploit Prediction Scoring System) probability scores
2. **KEV Matching**: Cross-reference with CISA KEV (Known Exploited Vulnerabilities) catalog
3. **Agent Profiling**: Consider deployed agent capabilities and exposed APIs
4. **Mitigation Detection**: Check for WAF rules, sandboxing, or other compensating controls
5. **ML-Based Scoring**: Use machine learning to predict exploitability based on historical data
## References
- **CVSS v3.1 Specification**: [https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document)
- **CVSS v2 Guide**: [https://www.first.org/cvss/v2/guide](https://www.first.org/cvss/v2/guide)
- **EPSS**: [https://www.first.org/epss/](https://www.first.org/epss/)
- **CISA KEV**: [https://www.cisa.gov/known-exploited-vulnerabilities-catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- **NVD API**: [https://nvd.nist.gov/developers/vulnerabilities](https://nvd.nist.gov/developers/vulnerabilities)
## Contributing
To improve the exploitability scoring methodology:
1. **Submit Test Cases**: Add test cases to `utils/analyze_exploitability.py`
2. **Report False Positives/Negatives**: Open GitHub issues with CVE examples
3. **Propose Scoring Adjustments**: Submit PRs with rationale and examples
4. **Share Agent Context**: Contribute agent-specific vulnerability patterns
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
---
**Maintained by**: [Prompt Security](https://prompt.security)
**License**: AGPL-3.0-or-later
**Last Updated**: 2026-03-01
wiki/de/glossary.md
+62
View File
@@ -0,0 +1,62 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../glossary.md
Review status: draft
-->
# Glossary
## Terms
| Term | Definition |
| --- | --- |
| Advisory Feed | JSON document (`feed.json`) containing security advisories for skills/platforms. |
| Affected Specifier | Skill selector such as `skill@1.2.3`, wildcard, or range used in matching logic. |
| Guarded Install | Two-step installer behavior that requires explicit confirmation when advisories match. |
| SBOM Files | Skill-declared artifact list in `skill.json` used for packaging and validation. |
| Detached Signature | Base64 signature file (`.sig`) stored separately from signed payload. |
| Checksum Manifest | File hash map (`checksums.json`) used to verify payload integrity. |
## Skill Packaging Terms
| Term | Definition |
| --- | --- |
| Skill Tag | Git tag formatted as `<skill>-v<semver>` used by release automation. |
| Release Assets | Files attached to GitHub release (zip, `skill.json`, checksums, signatures). |
| Catalog Index | `public/skills/index.json`, generated list consumed by web catalog. |
| Embedded Components | Capability bundle from one skill included in another (for example feed embedded in suite). |
## Advisory and Security Terms
| Term | Definition |
| --- | --- |
| Fail-Closed Verification | Reject payload if signature or checksum validation fails. |
| Unsigned Compatibility Mode | Temporary bypass path enabled via `CLAWSEC_ALLOW_UNSIGNED_FEED=1`. |
| Suppression Rule | Config entry matching `checkId` and `skill` to suppress known/accepted findings. |
| Key Fingerprint | SHA-256 digest of DER-encoded public key used for key consistency checks. |
## Runtime and Platform Terms
| Term | Definition |
| --- | --- |
| OpenClaw Hook | Runtime event handler (`clawsec-advisory-guardian`) that checks advisories. |
| NanoClaw IPC | Host/container task exchange for advisory refresh, signature verification, integrity checks. |
| Integrity Baseline | Stored approved hashes/snapshots for protected files. |
| Hash-Chained Audit Log | Append-only audit log where each entry depends on prior hash. |
## CI/CD Terms
| Term | Definition |
| --- | --- |
| Poll NVD CVEs Workflow | Scheduled workflow that fetches and transforms NVD CVEs into advisories. |
| Community Advisory Workflow | Issue-label-triggered workflow that publishes approved community advisories. |
| Skill Release Workflow | Tag-triggered packaging/signing/publishing pipeline for skills. |
| Deploy Pages Workflow | Workflow that builds site assets and mirrors release/advisory artifacts. |
## Source References
- types.ts
- skills/clawsec-suite/skill.json
- skills/clawsec-nanoclaw/skill.json
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
- skills/clawsec-nanoclaw/guardian/integrity-monitor.ts
- scripts/populate-local-feed.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
wiki/de/localization.md
+71
View File
@@ -0,0 +1,71 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../localization.md
Review status: draft
-->
# Localization Workflow
## Purpose
Define a repeatable docs localization pipeline for ClawSec README and wiki pages.
## Scope
- Source language: English (`README.md`, `wiki/*.md`)
- Current translated language: Spanish (`README.es.md`, `wiki/es/*.md`)
- Korean pilot language: Korean (`README.ko.md`, `wiki/ko/*.md`)
- Future languages: `wiki/<lang>/...` and `README.<lang>.md`
## Source of Truth Rules
1. English files are canonical.
2. Translations must preserve commands, file paths, code blocks, and identifiers exactly.
3. Product names and skill names stay untranslated (`ClawSec`, `OpenClaw`, `NanoClaw`, `Hermes`, `Picoclaw`, skill package names).
4. When translation coverage is partial, translated files must state scope explicitly.
## Folder Conventions
- README translations:
- `README.es.md`
- Future: `README.fr.md`, `README.de.md`, `README.ja.md`, etc.
- Wiki translations:
- `wiki/es/INDEX.md`
- `wiki/es/<page>.md`
- Future: `wiki/fr/<page>.md`, `wiki/de/<page>.md`, etc.
- Localization assets:
- `wiki/i18n/terminology-en-es.md`
- `wiki/i18n/translation-tracker.md`
## Update Workflow
1. **Normalize source docs first**
- Update English source docs for clarity and structure before translation.
2. **Record delta**
- Note changed English pages in `wiki/i18n/translation-tracker.md`.
3. **Translate changed pages**
- Präservieren Sie die Struktur und die Rubriken.
- Halten Sie Befehlsblöcke unberührt.
4. **QA pass**
- Verifizieren Sie die Links.
- Überprüfen Sie Codeblöcke und Inline-Befehle sind unverändert.
- Verifizieren Sie die Terminologiekonsistenz mit `terminology-en-es.md`.
5. **Regenerate exports**
- Laufen `npm run gen:wiki-llms`.
6. **Review and PR**
- Inklusive Zusammenfassung der übersetzten Seiten und Restlücken.
Übersetzung QA Checkliste
- [ ] Die Rubrik Hierarchie erhalten.
- Kommandoschnipsel unverändert und lauffähig.
- [ ] Dateipfade und URLs unverändert.
- [ ] Geschicklichkeit und Plattformnamen unverändert.
- Sicherheitsterminologie konsistent.
- [ ] `wiki/INDEX.md` hat Übersetzungslinkeinträge.
- [ ] `wiki/<lang>/INDEX.md` verlinkt zurück zu den wichtigsten englischen Seiten, wenn nicht übersetzt.
Sprache Rollout vorschlagen
1. Spanisch (`es`) – in Phase 1 Basislinie.
2. Französisch (`fr`) und Deutsch (`de`) für breites technisches Publikum.
3. Japanisch (`ja`) für High-Fidelity-Plattformen.
Quellenangaben
- README.md
- README.es.md
- wiki/INDEX.md
- wiki/es/INDEX.md
- wiki/es/overview.md
wiki/de/migration-signed-feed.md
+185
View File
@@ -0,0 +1,185 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../migration-signed-feed.md
Review status: draft
-->
# Migration Record: Unsigned Feed → Signed Feed (Completed)
## 1) Objective and Status
Document how ClawSec advisory distribution moved from unsigned `feed.json` delivery to detached-signature verification, with compatibility preserved for legacy clients.
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, 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`
- 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`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- default URL: `https://clawsec.prompt.security/advisories/feed.json`
## 3) Migration principles
- **Dual-publish first**: publish signatures before enforcing verification.
- **Fail-open only during transition**: temporary compatibility period is explicit and time-bounded.
- **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 (historical)
### Phase 0 — Preparation (Completed)
Deliverables:
- signing keys generated and fingerprints recorded
- GitHub secrets created
- public key(s) added in repo
- runbooks approved (`security-signing-runbook.md`, this file)
Exit criteria:
- key fingerprints verified by reviewer
- protected branch/workflow controls enabled
### Phase 1 — CI signing enabled, no client enforcement (Completed)
Implement:
- add feed signing step/workflow to produce `advisories/feed.json.sig`
- optionally produce `advisories/checksums.json` + `.sig`
- ensure CI verifies signatures before publishing artifacts
Also update deployment:
- copy `.sig` artifacts to `public/advisories/`
- mirror `.sig` in `public/releases/latest/download/advisories/`
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 (Completed)
Implement in consumers:
- read `feed.json` and `feed.json.sig`
- verify with pinned public key
- keep controlled temporary unsigned fallback during migration window
Validation:
- test remote signed path
- test local signed fallback path
- test invalid signature rejection
Exit criteria:
- verification logic released and tested
- no false-positive verification failures in soak period
### Phase 3 — Enforcement (Completed)
Actions:
- disable temporary unsigned fallback behavior in default paths
- add CI/publish gates that fail when `.sig` is missing
- announce enforcement date in release notes and docs
Exit criteria:
- all production clients verify signatures by default
- no unsigned feed dependency in standard installation flow
### Phase 4 — Stabilization (Ongoing)
Actions:
- run first key rotation tabletop drill
- run rollback tabletop drill
- close migration with post-implementation review
## 5) Rollback plan
### Rollback triggers
Initiate rollback if any of the following occur:
- sustained signature verification failures across clients
- signing workflow cannot produce valid signatures
- key compromise suspected but replacement key is not yet deployed
- deployment path publishes mismatched payload/signature pairs
### Rollback levels
### Level 1 (preferred): Verification bypass window, keep signed publishing
Use when: signing is healthy, client-side verifier has a defect.
Actions:
1. Re-enable temporary unsigned-acceptance behavior in client release branch.
2. Ship patch release with explicit expiry date for bypass.
3. Keep signing pipeline active to avoid authenticity gap.
Recovery target: restore strict verification within 24–48h.
### Level 2: Signed pipeline paused, unsigned feed temporarily authoritative
Use when: signing pipeline is unstable or producing inconsistent artifacts.
Actions:
1. Disable signing workflow or signing step.
2. Continue publishing unsigned `advisories/feed.json` via existing workflows.
3. Revert deploy gates that require `.sig` artifacts.
4. Open incident record and track time in unsigned mode.
Recovery target: restore signed publishing ASAP, ideally <72h.
### Level 3: Full release freeze
Use when: compromise or integrity of repository/workflows is in doubt.
Actions:
1. Pause feed mutation and deployment workflows.
2. Restore known-good commit for advisory files/workflows.
3. Rotate keys and credentials.
4. Resume pipeline only after security review sign-off.
### Roll-forward after rollback
- identify root cause
- add regression tests/gates
- redeploy signed artifacts
- publish incident + remediation summary
## 6) Communication plan
For enforcement and rollback events, communicate:
- what changed
- expected operator/client action
- duration of temporary compatibility mode (if any)
- verification commands for users
Recommended channels:
- GitHub release notes
- repository README/docs updates
- issue/incident report in repository
## 7) Go/No-Go checklist
Go only if all are true:
- signing workflow success rate is stable
- signatures are mirrored to all documented feed endpoints
- consumer verification path tested for remote + local fallback
- rollback owner is assigned and reachable
- key rotation procedure has been dry-run at least once
## Source References
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- advisories/feed.json
- wiki/security-signing-runbook.md
wiki/de/overview.md
+114
View File
@@ -0,0 +1,114 @@
<!-- 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.
![Prompt Security Logo](../assets/overview_img_01_prompt-security-logo.png)
![ClawSec Mascot](../assets/overview_img_02_clawsec-mascot.png)
## 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
wiki/de/platform-verification.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../platform-verification.md
Review status: draft
-->
# Platform Verification Checklist
Use this checklist to validate portability and path-handling behavior after changes.
## Linux Verification
1. Run core Node tests:
```bash
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
Expected: all tests pass.
2. Verify no literal `$HOME` path acceptance:
```bash
CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Expected: exits non-zero with `Unexpanded home token` error.
3. Verify `$HOME` expansion works:
```bash
HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
```
Expected: `$HOME` expansion tests pass.
## macOS Verification
1. Run the same Node test suite as Linux.
2. Confirm OpenSSL tooling path assumptions are documented:
- If using LibreSSL/OpenSSL variations, ensure checks use tested command forms from docs.
3. Verify tilde expansion in config path:
```bash
OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
```
Expected: path resolves correctly (or clear file-not-found error at expanded location).
## Windows Verification (PowerShell)
1. Run Node tests:
```powershell
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
```
Expected: all pass.
2. Verify PowerShell env path expansion behavior:
```powershell
$env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Expected: path token is expanded/normalized or fails with a clear error if target files are missing.
3. Verify escaped literal token rejection:
```powershell
$env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Expected: `Unexpanded home token` error; no directory creation with literal `$HOME`.
## Line Endings Sanity
1. Confirm LF policy is present:
```bash
test -f .gitattributes && grep -n "eol=lf" .gitattributes
```
Expected: script/config file patterns enforce LF.
2. After a CRLF-prone checkout, verify scripts still parse:
```bash
bash -n scripts/populate-local-feed.sh
bash -n scripts/populate-local-skills.sh
```
Expected: no `^M` shebang/parse errors.
## Explicit Bug Check: No Literal `$HOME` Directory Creation
1. Configure a path with a literal/escaped token.
2. Run setup/install command.
3. Verify command fails early with token error.
4. Confirm no `$HOME` segment directory was created under working directories.
Expected outcome: **no directories containing literal `$HOME` are created by supported setup scripts.**
## Source References
- .gitattributes
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- skills/clawsec-suite/test/path_resolution.test.mjs
- skills/clawsec-suite/test/guarded_install.test.mjs
- skills/clawsec-suite/test/advisory_suppression.test.mjs
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
wiki/de/remediation-plan.md
+89
View File
@@ -0,0 +1,89 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../remediation-plan.md
Review status: draft
-->
# Cross-Platform Remediation Plan
## Phase 1: Immediate Risk Closure (Completed)
### Milestones
- Implement explicit home-path expansion + suspicious token rejection in high-risk runtime/install paths.
- Add regression tests for path expansion and escaped-token rejection.
- Add `.gitattributes` LF policy.
- Expand Node lint/type/build CI coverage to Linux/macOS/Windows.
- Update install docs with shell-specific guidance and literal `$HOME` troubleshooting.
### Outcomes
- Literal `$HOME` path propagation bug addressed at source.
- Core advisory/install path config now fails fast on invalid path tokens.
---
## Phase 2: Windows Parity for Critical Workflows (Next)
### Quick wins
- Add PowerShell equivalents for the most-used manual install/check commands in:
- `skills/clawsec-suite/SKILL.md`
- `skills/openclaw-audit-watchdog/SKILL.md`
- `README.md`
- Add a lightweight `scripts/preflight.mjs` to detect missing tools and print OS-specific install hints.
### Milestones
- Native PowerShell instructions for suite setup and advisory hook.
- WSL/Git Bash fallback documented where shell scripts are unavoidable.
---
## Phase 3: Reduce POSIX Shell Surface (Deeper Refactor)
### Refactor targets
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `scripts/release-skill.sh`
### Approach
- Re-implement critical paths in Node/Python to remove dependency on `jq/sed/awk/find/chmod` pipelines.
- Preserve shell wrappers for backward compatibility; route to new cross-platform implementations.
### Migration notes
- Keep old script entrypoints as wrappers for at least one minor release.
- Emit deprecation warnings with exact migration commands.
---
## Phase 4: CI Hardening and Ongoing Verification
### Milestones
- Keep Node matrix (Linux/macOS/Windows) as required check.
- Add targeted Windows smoke tests for install path handling.
- Add macOS check for OpenSSL command compatibility notes where relevant.
### Test strategy
- Local:
- Run Node test suites that cover path expansion/suppression/install behavior.
- Run syntax checks for modified scripts.
- CI:
- Matrix Node checks + guarded installer/suppression/path tests.
- Linux-only security scans remain, but explicitly marked as Linux-scoped.
---
## Rollout / Release Considerations
- No breaking interface changes introduced in this patch set; behavior is stricter only for invalid/unexpanded path tokens.
- Communicate in release notes:
- path token validation now enforced
- how to correct invalid quoted env values
- where PowerShell examples live
## Source References
- .gitattributes
- .github/workflows/ci.yml
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- scripts/release-skill.sh
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- wiki/platform-verification.md
wiki/de/security-signing-runbook.md
+239
View File
@@ -0,0 +1,239 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../security-signing-runbook.md
Review status: draft
-->
# ClawSec Signing Operations Runbook
## 1) Purpose
This runbook defines operational procedures for introducing and running cryptographic signing in the ClawSec repository.
It covers:
- key generation
- GitHub secret management
- signing workflow integration
- key rotation and revocation
- incident response
## 2) Current operating state (important)
On `main`, advisory and release channels are signed and verified by default:
- Feed writers:
- `.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` 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`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- default feed URL is `https://clawsec.prompt.security/advisories/feed.json`
Unsigned mode remains an explicit compatibility bypass (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) and is not the steady-state operating model.
## 3) Target signed artifacts
### Advisory feed channel
- `advisories/feed.json` (payload)
- `advisories/feed.json.sig` (detached Ed25519 signature; base64)
- `advisories/feed-signing-public.pem` (pinned public key)
### Release artifact channel
- `<release>/checksums.json`
- `<release>/checksums.sig`
- `<release>/signing-public.pem`
## 4) Key roles and custody
- **Security owner**: approves key lifecycle changes and incident actions.
- **Platform owner**: maintains workflows and GitHub secrets.
- **Reviewer**: validates fingerprints in PRs/releases.
Policy:
- private keys are never committed
- public keys are committed and code-reviewed
- key generation occurs on trusted operator workstation or HSM-backed environment
## 5) Key generation (Ed25519)
> Run from a secure workstation. Do not run on shared CI runners.
```bash
# Feed signing keypair
openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem
openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem
# Release checksums signing keypair (optional separate key)
openssl genpkey -algorithm Ed25519 -out release-signing-private.pem
openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem
```
Generate fingerprints (store in ticket/change record):
```bash
openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256
openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256
```
Optional test-sign before publishing:
```bash
echo '{"probe":"ok"}' > /tmp/probe.json
openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
```
## 6) GitHub secrets setup
### Required secrets
- `CLAWSEC_SIGNING_PRIVATE_KEY` — PEM-encoded Ed25519 private key (used for both feed and release signing)
- `CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (optional) passphrase if the private key is encrypted
### Procedure
1. Go to **Repo Settings → Secrets and variables → Actions → New repository secret**.
2. Paste full PEM including header/footer.
3. Prefer GitHub **Environment secrets** (with required reviewers) for workflow scoping when possible.
4. Record change ticket with:
- secret name
- creator
- creation time
- key fingerprint
### Recommended environment protections
- Require manual approval for workflows that can use signing secrets.
- Restrict who can edit protected workflows.
- Enable branch protection for `main` and require review for workflow changes.
## 7) Workflow integration points
This repo enforces signing as a post-mutation, pre-publish control.
### Feed pipeline
Current feed mutation points:
- `.github/workflows/poll-nvd-cves.yml`
- `.github/workflows/community-advisory.yml`
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`
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`
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
### Rotation cadence
- Routine: every 90 days (or stricter org policy).
- Immediate: on suspected exposure, unauthorized workflow change, or unexplained signature mismatch.
### Routine rotation steps
1. Generate new keypair(s).
2. Open PR that updates public key file(s) and fingerprints documentation.
3. Add new private key(s) as GitHub secret(s).
4. Merge workflow changes that use new key(s).
5. Re-sign latest feed/release manifests.
6. Validate verification in CI and in one external client.
7. Remove old private key secret(s).
8. Keep old public key reference only as long as required for historical verification.
### Revocation steps
1. Disable workflows using compromised key.
2. Remove compromised GitHub secret(s).
3. Commit revocation note and new public key.
4. Re-sign latest artifacts with replacement key.
5. Publish incident advisory with timestamp and impacted window.
## 9) Incident response playbook (signing-specific)
### Triggers
- signature verification fails for newly published feed/release
- unknown commits/workflow edits touching signing paths
- leaked key material, accidental logging, or suspicious secret access
### Severity guide
- **SEV-1**: key exfiltration confirmed or maliciously signed payload published
- **SEV-2**: verification failures with unknown cause
- **SEV-3**: procedural non-compliance, no active compromise
### Response phases
1. **Containment**
- pause signing/publish workflows
- block further feed merges if authenticity is uncertain
2. **Investigation**
- review workflow run logs
- review commits affecting `.github/workflows/`, `advisories/`, and key files
- determine first-bad timestamp and affected artifacts
3. **Eradication**
- rotate/revoke compromised key(s)
- restore trusted artifacts from known-good commit
4. **Recovery**
- re-sign artifacts
- redeploy pages/releases
- verify via independent client check
5. **Post-incident**
- publish timeline and remediation summary
- tighten controls (review gates, protected environments, secret scope)
## 10) Audit evidence checklist
For each release cycle or feed-signing run, retain:
- workflow run URL and commit SHA
- signer key fingerprint in use
- verification result logs
- operator/reviewer approvals
- any exception or bypass rationale
## 11) Minimum acceptance criteria before stricter policy changes
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
- incident response on-call owner identified and documented
## Source References
- advisories/feed.json
- advisories/feed.json.sig
- advisories/feed-signing-public.pem
- clawsec-signing-public.pem
- .github/actions/sign-and-verify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- scripts/ci/verify_signing_key_consistency.sh
- wiki/migration-signed-feed.md
wiki/de/security.md
+83
View File
@@ -0,0 +1,83 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../security.md
Review status: draft
-->
# Security
## Security Model Overview
- ClawSec secures both content distribution (signed artifacts) and runtime behavior (advisory gating, integrity monitoring).
- Trust anchors are pinned public keys committed in repo and verified against workflow-generated outputs.
- Runtime consumers default to verification-first behavior with explicit migration bypass flags.
## Cryptographic Controls
| Control | Mechanism | Location |
| --- | --- | --- |
| Feed authenticity | Ed25519 detached signatures (`feed.json.sig`) | Advisory workflows + consumer verification libs. |
| Artifact integrity | SHA-256 checksum manifests (`checksums.json`) | Skill release and pages deploy workflows. |
| Key consistency | Fingerprint comparison across docs + canonical PEMs | `scripts/ci/verify_signing_key_consistency.sh`. |
| Signature verification action | Composite sign+verify action in CI | `.github/actions/sign-and-verify/action.yml`. |
## Runtime Enforcement Controls
| Control | Component | Effect |
| --- | --- | --- |
| Advisory hook gating | `clawsec-advisory-guardian` | Alerts and cautious guidance based on matched advisories. |
| Double-confirmation installer | `guarded_skill_install.mjs` | Exit `42` until explicit confirmation for matched advisories. |
| Reputation extension | `clawsec-clawhub-checker` | Additional risk scoring before install. |
| NanoClaw signature gate | `skill-signature-handler.ts` + MCP tool | Blocks tampered/unsigned package installs by policy. |
| Integrity baseline monitor | `soul-guardian` + NanoClaw integrity monitor | Drift detection, quarantine, restore, auditable history. |
## Supply-Chain and CI Controls
- 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.
## Incident and Rotation Playbooks
- `wiki/security-signing-runbook.md` defines key generation, custody, rotation, and incident phases.
- `wiki/migration-signed-feed.md` defines staged enforcement and rollback levels.
- Rollback paths prioritize preserving signed publishing where possible and time-boxing any bypass.
## Example Snippets
```bash
# verify canonical public key fingerprint
openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256
```
```bash
# run repo key-consistency guardrail used in CI
./scripts/ci/verify_signing_key_consistency.sh
```
## Known Security Tradeoffs
- Unsigned compatibility mode can reduce assurance and should be disabled once migration completes.
- Some deploy paths tolerate unsigned legacy checksum assets for backward compatibility.
- Reputation checks rely on external tooling output and may include heuristic false positives/negatives.
- Local scripts inherit environment trust; compromised local shells can still subvert operator workflows.
## Hardening Opportunities
- Remove unsigned compatibility flags after migration stabilization.
- Expand deterministic checksum/signature verification for all mirrored release files.
- Add explicit tests for workflow-level signature failure scenarios.
- Increase runtime telemetry for advisory fetch/verification failures to simplify incident triage.
## Update Notes
- 2026-02-26: Repointed signing and migration references from root `docs/` files to dedicated `wiki/` operations pages.
## Source References
- SECURITY.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- scripts/ci/verify_signing_key_consistency.sh
- .github/actions/sign-and-verify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/clawsec-clawhub-checker/scripts/enhanced_guarded_install.mjs
- skills/soul-guardian/scripts/soul_guardian.py
- skills/clawsec-nanoclaw/host-services/skill-signature-handler.ts
- skills/clawsec-nanoclaw/guardian/integrity-monitor.ts
wiki/de/testing.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../testing.md
Review status: draft
-->
# Testing
## Testing Strategy
- The repository uses layered verification rather than a single root `npm test` command.
- Core confidence comes from lint/type/build gates plus skill-local Node test suites.
- Python and shell tooling are validated through dedicated lint/security checks.
- Workflow pipelines run the same command classes used in local pre-push automation.
## Verification Layers
| Layer | Commands | Scope |
| --- | --- | --- |
| Frontend/static checks | ESLint + `tsc --noEmit` + `npm run build` | TS/TSX correctness and build viability. |
| 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, 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 |
| --- | --- | --- |
| `clawsec-suite` | `feed_verification`, `guarded_install`, `path_resolution`, fuzz tests | Signature checks, advisory gating, path safety, matching robustness. |
| `openclaw-audit-watchdog` | suppression config and render tests | Config parsing, suppression behavior, report formatting. |
| `clawsec-clawhub-checker` | `reputation_check.test.mjs` | Input validation and reputation gating behavior. |
## CI Workflow Coverage
| Workflow | Trigger | Key Assertions |
| --- | --- | --- |
| `ci.yml` | PR/push to `main` | Lint/type/build, Python checks, security scans, skill tests. |
| `codeql.yml` | PR/push/schedule | JS/TS static security analysis. |
| `scorecard.yml` | schedule/push | Supply-chain posture reporting and SARIF upload. |
| `skill-release.yml` | tags + PRs | Version parity and release artifact verification. |
## Local Testing Commands
```bash
# baseline frontend + config checks
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
npm run build
```
```bash
# representative skill tests
node skills/clawsec-suite/test/feed_verification.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
## Failure Patterns to Watch
- Signature/test fixtures can fail from key/payload mismatch when expected files are regenerated inconsistently.
- Path-resolution tests intentionally fail on escaped home tokens; this behavior is expected and security-relevant.
- Local scripts relying on `openclaw` or `clawhub` binaries may fail in environments where those CLIs are absent.
- Deploy/release logic can pass locally while failing in CI if signing secrets or workflow permissions differ.
## Suggested Test Order
1. Run `./scripts/prepare-to-push.sh` for a full local gate.
2. Run directly impacted skill-local tests.
3. For feed/signing changes, run suite verification tests first (`feed_verification`, `guarded_install`).
4. For workflow or release changes, also run `scripts/validate-release-links.sh` and key consistency script.
## Update Notes
- 2026-02-26: Updated source references to the migrated `wiki/platform-verification.md` checklist.
## Source References
- AGENTS.md
- scripts/prepare-to-push.sh
- scripts/validate-release-links.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/skill-release.yml
- skills/clawsec-suite/test/feed_verification.test.mjs
- skills/clawsec-suite/test/guarded_install.test.mjs
- skills/clawsec-suite/test/path_resolution.test.mjs
- skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
- skills/clawsec-clawhub-checker/test/reputation_check.test.mjs
- wiki/platform-verification.md
wiki/de/workflow.md
+87
View File
@@ -0,0 +1,87 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (de)
Source: ../workflow.md
Review status: draft
-->
# Workflow
## 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 | 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 |
| --- | --- | --- |
| 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. |
## Release Workflow Details
- Version bump and docs parity are enforced for PR/tag paths.
- Skill packaging includes SBOM-declared files and integrity manifests.
- `checksums.json` is signed and immediately verified in workflow execution.
- Optional publish-to-ClawHub job runs after successful GitHub release when configured.
- Older releases within same major line can be superseded/deleted by automation.
## Advisory Workflow Details
- NVD workflow determines incremental window from previous feed `updated` timestamp.
- Transform phase maps CVE metrics to severity/type and normalizes affected targets.
- Community advisory workflow creates deterministic IDs (`CLAW-YYYY-NNNN`) from issue metadata.
- Both advisory workflows update skill feed copies and signature companions.
## Example Snippets
```bash
# manual release prep for a skill
./scripts/release-skill.sh clawsec-feed 0.0.5
# then push tag if running in release branch mode
```
```yaml
# pages deploy depends on successful upstream workflow run
on:
workflow_run:
workflows: ["CI", "Skill Release"]
types: [completed]
```
## Operational Risks
- Workflow permissions and secret scope misconfiguration can block signing/publishing.
- NVD/API transient failures may delay advisory freshness.
- Invalid tag naming or version mismatches halt release automation.
- Local scripts and CI can diverge if operator machine lacks expected binaries (`jq`, `openssl`, `clawhub`).
## Source References
- scripts/release-skill.sh
- 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
wiki/es/GENERATION.md
+42
View File
@@ -0,0 +1,42 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../GENERATION.md
Review status: draft
-->
# Wiki Generation Metadata
- Commit hash: `c3983a100581a9f27eb8cc3b5baa4f585e6c45e4`
- Branch name: `codex/clawsec-scanner-0.0.2-dast-harness`
- Generation timestamp (local): `2026-03-10T19:06:29+0200`
- Generation mode: `update`
- Output language: `English`
- Assets copied into `wiki/assets/`:
- `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
- `overview_img_02_clawsec-mascot.png` (from `public/img/mascot.png`)
- `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)
## Notes
- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
- Updated index and cross-links to use `wiki/` as the documentation source of truth.
- Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
- Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.
- 2026-04-26: Split Picoclaw self-pen-testing into dedicated `wiki/modules/picoclaw-self-pen-testing.md`, and updated `wiki/modules/picoclaw-security-guardian.md` to cover advisory/drift/supply-chain scope only.
- 2026-04-25: Added DeepWiki-friendly `wiki/modules/picoclaw-security-guardian.md` with support-matrix claims, threat model, default safety posture, frontend/advisory-board wiring, verification commands, and source references. Regenerated `public/wiki/**/llms.txt` exports with `npm run gen:wiki-llms`.
## Source References
- README.md
- package.json
- AGENTS.md
- wiki/overview.md
- wiki/architecture.md
- wiki/modules/clawsec-scanner.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- wiki/dependencies.md
- wiki/data-flow.md
- wiki/glossary.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
wiki/es/INDEX.md
+65
View File
@@ -0,0 +1,65 @@
# Índice del Wiki
## Resumen
- Propósito: documentar ClawSec como catálogo web, canal de advisories firmados y sistema de distribución de múltiples skills de seguridad.
- Stack tecnológico: frontend React 19 + Vite + TypeScript, scripts Node/ESM, utilidades Python, automatización Bash y pipelines de GitHub Actions.
- Puntos de entrada: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, y workflows en `.github/workflows/`.
- Dónde empezar: lee [Overview (ES)](overview.md), luego [Architecture (EN)](../architecture.md), y después los módulos según el área que vas a editar.
- Cómo navegar: usa Guides para temas transversales, Operations para runbooks y planes de migración, Modules para límites de implementación, y Source References al final de cada página para saltar al código.
## Empieza aquí
- [Overview (ES)](overview.md)
- [Architecture (EN)](../architecture.md)
## Guías
- [Flujo de localización](localization.md)
- [Dependencies](../dependencies.md)
- [Data Flow](../data-flow.md)
- [Configuration](../configuration.md)
- [Testing](../testing.md)
- [Workflow](../workflow.md)
- [Security](security.md)
## Operaciones
- [Security Signing Runbook](../security-signing-runbook.md)
- [Signed Feed Migration Plan](../migration-signed-feed.md)
- [Platform Verification Checklist](../platform-verification.md)
- [Cross-Platform Remediation Plan](../remediation-plan.md)
## Módulos
- [Frontend Web App](../modules/frontend-web.md)
- [ClawSec Suite Core](../modules/clawsec-suite.md)
- [ClawSec Scanner](../modules/clawsec-scanner.md)
- [Hermes Attestation Guardian](../modules/hermes-attestation-guardian.md)
- [Hermes Attestation Guardian Draft History (Archived)](../modules/hermes-attestation-guardian-draft-history.md)
- [NanoClaw Integration](../modules/nanoclaw-integration.md)
- [Picoclaw Security Guardian](../modules/picoclaw-security-guardian.md)
- [Picoclaw Self Pen Testing](../modules/picoclaw-self-pen-testing.md)
- [Automation and Release Pipelines](../modules/automation-release.md)
- [Local Validation and Packaging Tools](../modules/local-tooling.md)
## Glosario
- [Glossary](../glossary.md)
## Metadata de generación
- [Generation Metadata](../GENERATION.md)
## Notas de actualización
- 2026-04-27: Añadida traducción inicial al español (`wiki/es/INDEX.md`, `wiki/es/overview.md`) como fase 1.
- 2026-04-26: Separado Picoclaw self-pen-testing en `picoclaw-self-pen-testing`; actualizados docs y referencias de módulo Picoclaw.
- 2026-04-25: Añadido módulo Picoclaw Security Guardian para awareness de advisories, detección de drift de configuración y verificación de cadena de suministro.
## Referencias de código
- `README.md`
- `README.es.md`
- `App.tsx`
- `package.json`
- `scripts/prepare-to-push.sh`
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `skills/clawsec-suite/skill.json`
- `skills/clawsec-scanner/skill.json`
- `skills/hermes-attestation-guardian/skill.json`
- `skills/picoclaw-security-guardian/skill.json`
- `skills/picoclaw-self-pen-testing/skill.json`
- `.github/workflows/ci.yml`
wiki/es/architecture.md
+136
View File
@@ -0,0 +1,136 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../architecture.md
Review status: draft
-->
# Architecture
## System Context
- Esta página aparece en la sección `Start Here` en `INDEX.md`.
- ClawSec se encuentra entre fuentes de inteligencia aguas arriba (NVD + problemas comunitarios), automatización GitHub y entornos de agente de tiempo de ejecución.
- El repositorio publica tanto el contenido del sitio estático como los artefactos firmados que las habilidades de ejecución verifican antes de usar.
- Grupos de actores externos:
- GitHub Acciones corredores ejecutando CI, liberando y alimentando flujos de trabajo.
- Agentes OpenClaw/NanoClaw que consumen habilidades, asesorías y scripts de verificación.
- Mantenedores de depósitos que aprueban cuestiones de asesoramiento y fusionan cambios de liberación/tag.
## Componentes
Silencio Componente Silencio Ubicación Silencioso
Silencio.
TEN Web UI TENIDO `App.tsx`, `pages/`, `components/` ANTE Renders skills catalog and advisory detail experiences. Silencio
Silencioso asesor Feed Core Silencio `advisories/feed.json*`, `skills/clawsec-suite/.../feed.mjs` TENIDO Tiendas, verifica y analiza asesorías con firmas/consultos desprendidos. Silencio
← Paquetes de Habilidad Silencio `skills/*/` ← Distribuye capacidades de seguridad instalables con metadatos SBOM. Silencio
Scripts de Automatización Local ← `scripts/*.sh` ← Construir espejos locales, cheques pre-push y ayudantes manuales de liberación. Silencio
TEN CI/CD Workflows ANTE `.github/workflows/*.yml` ANTE Linting, tests, encuestas NVD, embalaje de lanzamiento y páginas implementadas. Silencio
TEN Python Utility Layer ANTE `utils/*.py` ← validación de metadatos de habilidad y generación de checksum. Silencio
## Flujos clave
- Flujo de catálogo de habilidad:
1. Los flujos de trabajo de lanzamiento/tag publican activos de habilidad.
2. Deploy workflow discovers release assets and builds `public/skills/index.json`.
3. UI fetches `public/skills/index.json` y docs de habilidad para las páginas `/skills`.
- Flujo de alimentación:
1. `poll-nvd-cves.yml` y `community-advisory.yml` actualizan `advisories/feed.json`.
2. La alimentación está firmada y reflejada en caminos públicos.
3. Ganchos/scriptos de tiempo de ejecución cargan alimentación remota y retroceso a copias firmadas locales.
- Flujo de instalación vigilado:
1. Installer solicita habilidad objetivo + versión.
2. Consultas del matcher afectan a los especificadores e indicaciones de gravedad/riesgo.
3. Código de salida 42 hace cumplir la segunda confirmación cuando las advertencias coinciden.
## Diagramas
```mermaid
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"]
```
![Prompt Line Motif](../assets/architecture_img_01_prompt-line.svg)
## Interfaces and Contracts
Silencioso Interfaz Silencioso Formulario de Contrato
Silencio.
← Metadatos de Habilidad Silencio `skills/*/skill.json` Silencio Validado por utilidad Python + cheques de paridad de la versión CI. Silencio
← Alimentación de asesoramiento Silencio JSON + Ed25519 firma despreocupada Silencio Verificada por `feed.mjs` y NanoClaw utilidades de firma. Silencio
Silenciosos Checksums manifiesto ← `checksums.json` (+ opcional `.sig`) Silencio Parsed and hash-matched antes de confiar en las cargas de pago. Silencio
Silencio Interfaz de evento de gancho ¦ `HookEvent` (`type`, `action`, `messages`) Silencio El controlador Runtime solo procesa nombres de eventos seleccionados. Silencio
etiqueta: patrón `<skill>-vX.Y.Z` Silencio Parsed in release/deploy workflows to discover skills. Silencio
## Parámetros clave
Silencio parametro Silencioso prefecto Silencioso
Silencio.
Silencio `CLAWSEC_FEED_URL` Silencio `https://clawsec.prompt.security/advisories/feed.json` Silencio Fuente de asesoramiento remota para scripts/hooks de suite. Silencio
Silencio `CLAWSEC_ALLOW_UNSIGNED_FEED` Silencio `0` Silencio Permite una compatibilidad temporal sin firmar. Silencio
Silencio `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` Silencio `1` Silencio Requiere verificación de manifiesto de checksum cuando esté disponible. Silencio
Silencio `CLAWSEC_HOOK_INTERVAL_SECONDS` Silencio `300` Silencioso ventana de escaneo para gancho asesor. Silencio
Silencio `CLAWSEC_SKILLS_INDEX_TIMEOUT_MS` Silencio `5000` Silencio Índice de habilidad remota buscar tiempo libre para el descubrimiento del catálogo. Silencio
Silencio `PROMPTSEC_GIT_PULL` Silencio `0` ← Auto-pull opcional antes de ejecutar la auditoría de relojes. Silencio
## Manejo de errores y fiabilidad
- Feed fetching está bloqueado para firmas inválidas y manifiestos malformados.
- Las fallas remotas de la embrague caen con gracia a los alimentos firmados localmente.
- El estado de gancho utiliza el archivo atómico escribe con el modo estricto donde se apoya.
- Las páginas UI detectan retrocesos HTML servidos como JSON y evitan renderizar datos corruptos.
- Los pasos de flujo de trabajo refuerzan la consistencia de la marca clave para evitar la deriva de la llave dividida.
## Ejemplos Snippets
```tsx
// 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>
```
```ts
// 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 Silencioso Modelo de Ejecución
Silencio.
← Aplicación Vite (`npm run dev`) Silencio Servidor de frontend local Silencio Aplicación interactiva web para feed/skills. Silencio
Silencio GitHub CI tención Matriz multi-OS + trabajos dedicados ← Lint/type/build/security and test confidence. Silencio
Silencio Flujo de trabajo de liberación de la piel ← Publicación de la etiqueta + cheques de funcionamiento seco de PR tención Activo de lanzamiento, cheques firmados, publicación opcional ClawHub. Silencio
Silencio Páginas desplegando flujo de trabajo Silencio Triggered by CI/Release success tención Static site + retrovisored advisories/releases. Silencio
← Ganchos de Runtime ← Ganchos de eventos OpenClaw / NanoClaw IPC Silencio Alertas de asesoramiento, decisiones de juego, controles de integridad. Silencio
## Scaling Notes
- Escalas de volumen de asesoramiento con palabras clave establecidas en encuestas NVD; ruido de control de dedupe y post-filtering.
- Implementar listas de lanzamiento de procesos de flujo de trabajo y mantiene nuevas versiones de habilidad en la salida de índice.
- Los límites del módulo por carpeta de habilidad permiten añadir nuevas capacidades de seguridad sin cambiar la estructura de frontend.
- Los caminos de verificación de firmas siguen siendo ligeros porque los tamaños de la carga útil (feed/manifests) son pequeños.
## Referencias Fuente
- App.tsx
- páginas/SkillsCatalog.tsx
- páginas/FeedSetup.tsx
- páginas/AdvisoryDetail.tsx
- páginas/WikiBrowser.tsx
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- habilidades/clawsec-suite/scripts/discover_skill_catalog.mjs
- habilidades/clawsec-nanoclaw/lib/advisories.ts
- habilidades/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
wiki/es/configuration.md
+93
View File
@@ -0,0 +1,93 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../configuration.md
Review status: draft
-->
# Configuración
## Scope
- La configuración abarca los ajustes de construcción de frontend, las rutas de alimentación de tiempo de ejecución, los desencadenantes de flujo de trabajo y los contratos de metadatos de habilidad.
- La mayoría de controles sensibles a tiempo de ejecución son variables ambientales prefijadas con `CLAWSEC_` o `OPENCLAW_`.
- La normalización del camino es sensible a la seguridad y rechaza intencionalmente literales sin resolver.
## Core Runtime Variables
Silencio Variable ← Default Silencio Usado por
Silencio.
TEN `CLAWSEC_FEED_URL` ANTE Hosted advisory URL TEN Suite hook and guarded installer feed loading. Silencio
Silencio `CLAWSEC_FEED_SIG_URL` Silencio `<feed>.sig` Silencio Fuente de firma independiente. Silencio
Silencio `CLAWSEC_FEED_CHECKSUMS_URL` Silencio `checksums.json` cerca de la URL de alimentación TEN Opcional checksum-manifest source. Silencio
Silencio `CLAWSEC_FEED_PUBLIC_KEY` Silencio Suite-local PEM file ← Verificación de la firma Feed. Silencio
TENIDO `CLAWSEC_ALLOW_UNSIGNED_FEED` TENIDO `0` TENIDO Bandera de circunvalación migratoria temporal. Silencio
Silencio `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` Silencio `1` Silencio Permite verificación de suma-manifiesto. Silencio
Silencio `CLAWSEC_HOOK_INTERVAL_SECONDS` Silencio `300` Silencioso de la exploración de ganchos. Silencio
## Path Resolution Rules
Silencio Silencio Silencio Silencio Silencioso
Silencio.
Silencio `~` expansion ← Resolvado para detectar directorio de inicio ← Funciones de utilidad de ruta compartida en scripts de suite/watchdog. Silencio
Silencio `$HOME` / `${HOME}` expansion tención Resolvido cuando no escaped durable Las mismas utilidades. Silencio
Silencio Windows case tokens ← `%USERPROFILE%`, `$env:USERPROFILE` normalizado TENIDOS Mismo utilities. Silencio
Silencio Tokens Escaped (`\$HOME`) Silencio Rechazado con error explícito ← Impide la creación accidental del directorio literal. Silencio
tención Sendero explícito inválido Silencio Puede retroceder a la ruta predeterminada con la advertencia de los ayudantes `resolveConfiguredPath`. Silencio
## Frontend and Build Configuration
- `vite.config.ts` define el puerto (`3000`), host (`0.0.0.0`), y el alias de ruta (`@`).
- `index.html` proporciona Tailwind runtime config, fuentes personalizadas y tokens de color base.
- `tsconfig.json` utiliza la resolución del módulo del paqueter, `noEmit` y la configuración del tiempo de ejecución JSX.
- `eslint.config.js` aplica TS, React, ganchos y reglas de forro específicas para scripts.
## Skill Metadata Configuración
Silencioso Grupo de Campo Silencioso Ubicación
Silencio.
Silencio Identidad de la habilidad básica Ø `skills/*/skill.json` TENIDO Nombre/versión/autor/license/descripción metadatos. Silencio
Silencio SBOM lista de archivos Silencio `skill.json -> sbom.files` Silencio Declara artefactos que requieren liberación. Silencio
Metadatos de plataformas ← `openclaw` o `nanoclaw` bloquean los requisitos de CLI, disparadores, consejos de capacidad de plataforma. Silencio
Metadatos del catálogo Silenciosos `skills/clawsec-suite/skill.json -> catalog` TENIDO Comportamiento integrado/default/consentimiento para miembros de la suite. Silencio
Configuración del flujo de trabajo
- La configuración de programación existe en las entradas `cron` (`poll-nvd-cves`, `codeql`, `scorecard`).
- El flujo de trabajo de lanzamiento espera el patrón de nombres de etiquetas `<skill>-v<semver>`.
- El flujo de trabajo de despliegue se activa con eventos exitosos de CI/release `workflow_run` y envío manual.
- La acción de firma compuesta requiere entradas clave privadas y verifica firmas inmediatamente después de la firma.
## Ejemplos Snippets
```bash
# run guarded install with explicit local signed feed paths
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```
```json
{
"name": "example-skill",
"version": "1.2.3",
"sbom": {
"files": [
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
]
}
}
```
## Operational Notes
- Mantenga la firma de llaves fuera del repositorio e inyecte solo a través de GitHub Secrets.
- Preferir caminos absolutos o expresiones hogareñas sin escatimar en entornos locales cambian las variables.
- Tratar el modo de alimentación sin firmar como soporte de migración temporal, no operación normal.
- Re-run release-link validation al editar URLs `SKILL.md` para evitar referencias de artefacto roto.
## Referencias Fuente
- vite.config.ts
- index.html
- tsconfig.json
- eslint.config.js
- habilidades/clawsec-suite/skill.json
- habilidades/clawsec-nanoclaw/skill.json
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs
- habilidades/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- scripts/validate-release-links.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/skill-release.yml
- .github/actions/sign-and-verify/action.yml
wiki/es/data-flow.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../data-flow.md
Review status: draft
-->
# Flujo de datos
## Primary Flows
- `Advisory ingestion`: Las entradas de NVD/community se transforman en una alimentación de asesoramiento normalizada, firmada, luego reflejada para clientes.
- `Skill catalog publication`: activos de liberación son descubiertos y convertidos en `public/skills/index.json` más docs/checksums per-skill.
- `Runtime enforcement`: Los consumidores de suite y nanoclaw cargan datos de asesoramiento, coinciden con las habilidades y emiten alertas o puertas de confirmación.
- Esta página aparece en la sección `Guides` en `INDEX.md`.
Paso a paso
1. Datos fuente de flujo de trabajo/script fetches (`NVD API` o payload de emisión).
2. JSON transforma lógica normaliza la severidad/tipo/ campos afectados y deduplica por ID de asesoramiento.
3. Signature/checksum steps generate detached signatures and checksum manifests.
4. Deploy workflow mirrors signed artifacts under `public/` and `public/releases/latest/download/`.
5. Los consumidores de UI validan la forma/contenido de JSON; los consumidores de tiempo de ejecución verifican adicionalmente firmas/consultos antes de confiar en datos de alimentación.
6. Los Matchers comparan los especificadores `affected` con nombres de habilidad/versiones y emiten alertas o imponen confirmación.
## Inputs and Outputs
En el cuadro que figura a continuación se resumen los insumos y los productos.
Silencio Tipo TENIDO Nombre TENIDO Ubicación Silencio Descripción
Silencio --- Silencio ---
← Input Silencio CVE payloads TEN `services.nvd.nist.gov/rest/json/cves/2.0` TEN Fuente vulnerabilidades filtradas por ClawSec keywords. Silencio
Silencio Input Silencio Community advisory issue Silencio `.github/workflows/community-advisory.yml` event payload Silencio Tema aprobado por Maintainer transformado en registro consultivo. Silencio
← Input ← activos de liberación de Habilidad Silencio GitHub Releases API + activos TEN Utilizado para construir catálogo web y descargas de espejo. Silencio
← Input Silencio Local config/env Silencio `OPENCLAW_AUDIT_CONFIG`, `CLAWSEC_*` vars Silencio Controls alimentan caminos, supresión y comportamiento de verificación. Silencio
TENCIÓN TENIDO ANTERIENDA ALIMENTAR TENIDO `advisories/feed.json` TENIDO Alimento de repositorio canónico. Silencio
TENCIÓN ANTERIENTE Firma asesora ANTERI `advisories/feed.json.sig` TENIDO Firma adjunta para la autenticidad del alimento. Silencio
Índice de catálogo de Habilidad Silencioso `public/skills/index.json` Silencioso Catálogo web usado por páginas de `/skills`. Silencio
TENCIÓN ANTERIOR ANTERIENDIENTE Compruebas/signaturas ANTE `release-assets/checksums.json(.sig)` ANTE Integrity manifest for release consumers. Silencio
TENCIÓN ANTERIENTE Hook state ANTE `~/.openclaw/clawsec-suite-feed-state.json` TENIDO Pistas de escaneo y coincidencias notificadas. Silencio
## Estructuras de datos
tención Estructura TENIDO Key Fields
Silencio.
tención Registro de alimentación de mantenimiento de `id`, `severity`, `type`, `affected[]`, `published` TENIDO Unidad de datos de riesgo usados por UI e instaladores. Silencio
← Metadatos de Habilidad Silencio `id`, `name`, `version`, `emoji`, `tag` Silencioso Catálogo fila para navegar por la web e instalar comandos. Silencio
tención Checksums manifiesto Silencioso `schema_version`, `algorithm`, `files` Silencio Mapas nombres de archivos a los digestos esperados. Silencio
tención Estado asesor Silencioso `known_advisories`, `last_hook_scan`, `notified_matches` Silencio Impide las alertas repetidas y los escaneos de aceleradores. Silencio
confidencialidad de la supresión permanente `enabledFor[]`, `suppressions[]` TENIDO Lista de saltos apuntado por `checkId` + `skill`. Silencio
## Diagramas
```mermaid
flowchart LR
A["NVD + Issue Inputs"] --> B["Transform + Deduplicate"]
B --> C["advisories/feed.json"]
C --> D["Sign + checksums"]
D --> E["public/advisories + releases/latest"]
E --> F["Web UI fetch"]
E --> G["Suite/NanoClaw verification"]
G --> H["Match skills + emit alerts/gates"]
```
## State and Storage
← Tienda Silenciosos Sendero/Escopo Silencioso
Silencio.
← Asesorías canónicas Silencio `advisories/` TENIDO NVD + flujos de trabajo comunitarios y script populate local. Silencio
Silencio Copias de asesoramiento incrustadas Silencio `skills/clawsec-feed/advisories/` y `skills/clawsec-suite/advisories/` Silencio Procesos de sincronización/envasado y flujo de trabajo de liberación. Silencio
tención Espejos públicos Silenciosos `public/advisories/`, `public/releases/` ANTE Deploy workflow. Silencio
tención Runtime state ← `~/.openclaw/clawsec-suite-feed-state.json` tención Asesoramiento estado persistencia. Silencio
Silencio NanoClaw cache Silencio `/workspace/project/data/clawsec-advisory-cache.json` Silencio Director de caché de asesoramiento lado anfitrión. Silencio
Silencio Integrity state ← `/workspace/project/data/soul-guardian/` (NanoClaw) TEN Integrity monitor baseline/audit storage. Silencio
## Ejemplos Snippets
```bash
# Local feed flow (NVD fetch -> transform -> sync)
./scripts/populate-local-feed.sh --days 120
jq '.updated, (.advisories | length)' advisories/feed.json
```
```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
## Failure Modes
- Los límites de la tasa NVD (`403/429`) pueden retrasar el refresco de alimentación y requerir retries/backoff.
- Las firmas desvinculadas o inválidas causan rechazo de la alimentación en modo cerrado.
- Las respuestas de retroceso HTML para los puntos finales de JSON pueden producir falsos positivos a menos que se filtra explícitamente.
- La malconfiguración token (`\$HOME`) puede romper la resolución de la ruta de retroceso local.
- Las huellas dactilares de clave pública en los flujos de trabajo provocan un duro fallo de la CI.
## Referencias Fuente
- asesorías/feed.json
- asesorías/feed.json.sig
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/state.ts
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/matching.ts
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- habilidades/clawsec-nanoclaw/lib/advisories.ts
- habilidades/clawsec-nanoclaw/host-services/advisory-cache.ts
wiki/es/dependencies.md
+106
View File
@@ -0,0 +1,106 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../dependencies.md
Review status: draft
-->
# Dependencias
## Build and Runtime
Layer ← Dependencias Primarias
Silencio.
Silencio Frontend runtime Silencio `react`, `react-dom`, `react-router-dom`, `lucide-react` ANTE UI rendering, routing, iconography. Silencio
Silencio Markdown rendering ← `react-markdown`, `remark-gfm` ANTE Render habilidad docs/readmes y wiki in-app paginas de marcado. Silencio
Silencio Construir herramientas Silenciosos `vite`, `@vitejs/plugin-react`, `typescript` TEN Fast TS/TSX bundling and production builds. Silencio
Las utilidades de Python ← stdlib + `ruff`/`bandit` policy from `pyproject.toml` TEN Validate/package skills and run static checks. Silencio
Silencio Automatización de cascos TEN `bash`, `jq`, `curl`, `openssl`, `sha256sum`/`shasum` ANTES Feed polling, signing, checksum generation, release checks. Silencio
## Dependency Details
Silencioso paquete ← Versión anterior
Silencio.
Silencio `react` / `react-dom` Silencio `^19.2.4` Silencio Frontend runtime Silencio
Silencio `react-router-dom` Silencio `^7.13.1` Silencio Frontend routing ←
Silencio `lucide-react` Silencio `^0.575.0` Silencioso icono UI conjunto
Silencio `vite` Silencio `^7.3.1` Silencio Servidor Dev + construya
Silencio `typescript` Silencioso `~5.8.2` Silencio Tipo de comprobación
Silencio `eslint` Silencio `^9.39.2` Silencio JS/TS linting Silencio
Silencio `@typescript-eslint/*` Silencio `^8.55.0` / `^8.56.0` Silencio TS lint parser/rules ←
Silencio `fast-check` Silencio `^4.5.3` Silencio Pruebas de estilo de propiedad/fuzz
← Sobrevivir Silencioso Versión grabada
Silencio.
Silencio `ajv` Silencio `6.14.0` Silencio Seguridad y estabilización de compatibilidad. Silencio
Silencio `balanced-match` Silencio `4.0.3` Silencio Transitive vulnerability control. Silencio
TENIDO `brace-expansion` TENIDO `5.0.2` TENIDO Durmiendo la dependencia transitiva. Silencio
Silencio `minimatch` Silencio `10.2.1` Silencio Comportamiento de dependencia determinista. Silencio
## External Services
← Servicio Silencioso usado por Silencioso
Silencio.
TEN NVD API (`services.nvd.nist.gov`) TENIDO `poll-nvd-cves` flujo de trabajo + script de alimentación local ¦ Pull CVEs por palabra clave/fecha ventana. Silencio
Silencio GitHub API tención Desploy/release workflows TEN Discover releases, download assets, publish outputs. Silencio
← Páginas de GitHub ← Deploy workflow ← Servir el sitio estático y los artefactos espejo. Silencio
← ClawHub CLI/registry tención Install scripts + trabajos opcionales publicitarios tención Instalar y publicar habilidades. Silencio
tención Opcional SMTP/sendmail local Silencio `openclaw-audit-watchdog` scripts Silencio Entrega informes de auditoría por correo electrónico. Silencio
## Development Tools
← Herramienta Silencioso Silencioso
Silencio.
TEN ESLint TENIDO `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0` TENIDO Frontend y forro de script. Silencio
Silencio TipoScript Silencio `npx tsc --noEmit` tención Compile-time TS checks contract. Silencio
TENIDO Ruff TENIDO `ruff check utils/` TENIDO Estilo Python y cheques de patrón de errores. Silencio
Silencio Bandit Silencio `bandit -r utils/ -ll` Silencio Controles de seguridad Python. Silencio
Silencio Trivy Silencio flujo de trabajo + funcionamiento local opcional Silencio FS/config vulnerabilidad escaneos. Silencio
Silencio Gitleaks Silencio `scripts/prepare-to-push.sh` Funcionamiento local opcional tención detección de fugas secretas antes de empujar. Silencio
## Ejemplos Snippets
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.4",
"react-router-dom": "^7.13.1"
}
}
```
```toml
[tool.ruff]
target-version = "py310"
line-length = 120
[tool.bandit]
exclude_dirs = ["__pycache__", ".venv"]
skips = ["B101"]
```
## Compatibilidad Notes
- Cuenta de scripts locales para las diferencias de macOS vs Linux en `date` y `stat`.
- Algunos flujos de trabajo/scripts requieren funciones OpenSSL utilizadas con Ed25519 y `pkeyutl -rawin`.
- El soporte de Windows es más fuerte para herramientas basadas en Nodo; los caminos de shell POSIX pueden requerir WSL/Git Bash.
- Los consumidores alimentados incluyen bypasses de compatibilidad para las fases migratorias, pero el modo firmado es el estado fijo previsto.
## Versioning Notes
- Las etiquetas de liberación de habilidad siguen `<skill>-v<semver>` y son analizadas por la automatización CI/deploy.
- La validación de PR impone la paridad de la versión entre `skill.json` y el frontmatter `SKILL.md` para habilidades contuídas.
- El índice de habilidades públicas mantiene la última versión descubierta por habilidad para la visualización UI.
- Los manifiestos de artefactos firmados (`checksums.json`) se versionan por versión e incluyen hashes de archivos y URLs.
## Referencias Fuente
- paquete.json
- paquete-lock.json
- pyproject.toml
- eslint.config.js
- tsconfig.json
- scripts/prepare-to-push.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
wiki/es/exploitability-scoring.md
+425
View File
@@ -0,0 +1,425 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../exploitability-scoring.md
Review status: draft
-->
# Exploitability Scoring Methodology
## Overview
El sistema de puntuación de la optimización de ClawSec proporciona una evaluación de vulnerabilidad consciente de contexto diseñada específicamente para implementaciones de agentes de IA (OpenClaw/NanoClaw). A diferencia de las puntuaciones genéricas de CVSS que tratan a todos los ambientes por igual, nuestra puntuación considera los patrones únicos de superficie de ataque y uso de los agentes de AI para reducir la fatiga de alerta y priorizar amenazas accionables.
## Scoring Levels
TENIDO Nivel ANTE Severity TENIDO Significado
Silencio...
Silencio `high` ANTE Critical/High ANTE Exploitable en despliegues típicos de agentes, atención inmediata requerida
Silencio `medium` Silencio Medium Silencio Puede ser explotable dependiendo de la configuración, justifica la investigación
Silencio `low` Silencio Bajo Silencio Explotación limitada en contexto de agente, baja prioridad
Silencio `unknown` Silencio Desconocido Silencio Datos insuficientes para evaluar la explotación
## Scoring Factors
### 1. CVSS Base Score (Baseline)
El análisis comienza con la puntuación base CVSS como base:
**CVSS ≥ 9.0**: Severidad crítica → puntuación inicial `high`
- **CVSS 7.0-8.9**: Alta gravedad → puntuación inicial `high`
**CVSS 4.0-6.9**: Severidad media → puntuación inicial `medium`
**CVSS 1.0-3.9**: Baja gravedad → puntuación inicial `low`
- **No CVSS**: → puntuación inicial `unknown`
### 2. Análisis de vectores de ataque (Métricas CVSS)
El analizador analiza los vectores CVSS v2, v3.0 y v3.1 para evaluar:
#### Network Accessibility
**AV:N** (Network): Remotamente explotable sobre la red
- **AV:A** (Adjacent): Requiere acceso a la red local
- **AV:L** (Local): Requiere el acceso del sistema local
- **AV:P** (Physical): Requiere acceso físico
**Impact on agents**: Las vulnerabilidades accesibles a la red son elevadas porque los agentes normalmente funcionan como servicios de red o hacen llamadas externas de API.
##### Requisitos de autenticación
- **PR:N / Au:NONE**: No se requiere autenticación → eleva la puntuación
- **PR:L / Au:SINGLE**: Bajo privilegios requeridos
- **PR:H / Au:MULTIPLE**: Se requieren altos privilegios → reduce la puntuación
**Impact on agents**: Los exploits no autenticados son críticos para las API de agente expuesto públicamente.
###### User Interaction
- **UI:N**: No se requiere interacción de usuario → eleva la puntuación
- **UI:R**: Requiere la interacción del usuario → reduce la puntuación
**Impact on agents**: Los agentes suelen funcionar de forma autónoma, por lo que las vulnerabilidades que requieren interacción con el usuario son menos críticas.
#### Attack Complexity
- **AC:L**: Baja complejidad → eleva la puntuación
- **AC:M / AC:H**: Media / Alta complejidad → neutral o reduce la puntuación
**Impact on agents**: Las explotaciones de baja complejidad tienen más probabilidades de ser automatizadas y utilizadas en ataques masivos.
### 3. Tipo de vulnerabilidad (Contexto de despliegue)
ClawSec ajusta las puntuaciones basándose en cómo los tipos de vulnerabilidad afectan las implementaciones de agentes AI:
#### High-Risk Types in Agent Context
** Ejecución del Código de Revocación (RCE)* *
```
Score: Always HIGH
Rationale: RCE is critical in agent deployments
```
Los agentes de AI ejecutan código arbitrario como parte de su función. Las vulnerabilidades RCE permiten a los atacantes secuestrar flujo de ejecución de agentes, exfiltrate credenciales o pivotar a otros sistemas.
**Server-Side Request Forgery (SSRF)* *
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: SSRF affects agents making external requests
```
Los agentes suelen llamar a API externas, acceder a servicios internos y buscar recursos remotos. SSRF permite a los atacantes:
- Acceso a los servicios de metadatos de nube interna (AWS IMDSv1, metadatos GCP)
- Pivot a redes internas
- Exfiltrate data through DNS túneling
**Path Traversal / Directorio Traversal* *
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: Path traversal affects agents with file access
```
Los agentes leen archivos, ejecutan scripts y administran codebases. Traversal permite:
- Leyendo archivos de configuración sensibles (.env, credenciales)
- Acceso a las teclas SSH, fichas API
- Sobreescribir archivos de sistema crítico
Inyección colectiva**
```
Score: Always HIGH
Rationale: Command injection is critical in agent deployments
```
Similar a RCE, los agentes a menudo ejecutan comandos de shell para interactuar con sistemas. La inyección de comandos permite un compromiso completo del sistema.
#### Medium-Risk Types
**Contaminación de prototipos (Node.js)* *
```
Score: Elevated from LOW to MEDIUM
Rationale: Prototype pollution can escalate in Node.js agents
```
Muchos marcos de agentes funcionan en Node.js. La contaminación prototipo puede conducir a:
- Pasaje de cheques de autenticación
- Escalada de privilegios
- Denegación del servicio
**SQL Injection / NoSQL Injection**
```
Score: Elevated to HIGH if network-accessible and unauthenticated
Rationale: Injection affects agents with database access
```
Los agentes que almacenan historia de conversación, datos de usuario o resultados de herramientas en bases de datos son vulnerables a ataques de inyección.
#### Tipos de tinta inferior
**Cross-Site Scripting (XSS)* *
```
Score: Reduced to MEDIUM if not network-accessible
Rationale: XSS has limited impact in headless agents
```
Los agentes normalmente no renderizan HTML en los navegadores, reduciendo el impacto XSS. Sin embargo, XSS en la gestión de agentes UIs o interfaces de chat sigue siendo una preocupación.
### 4. Disponibilidad de explotación
Cuando `--check-exploits` está habilitado, el analizador comprueba URLs de referencia para exploits públicos:
** Indicadores de despliegue:**
- exploit-db.com / exploit-database.com
- packetstormsecurity.com
- github.com/exploit, github.com/poc
- módulos marco metásploit
- URL que contienen "/exploit", "/poc", "/proof-of-concept"
**Score Elevation:**
- `low` → `medium` (exploit available)
- `medium` → `high` (exploit available)
- `unknown` → `medium` (exploit available + CVSS ⇩ 0)
**Rationale**: Las explotaciones públicas reducen la barrera de habilidad para los atacantes y aumentan la probabilidad de explotación automatizada.
## Scoring Algorithm
El analizador sigue este árbol de decisión:
```
1. Parse CVSS score → set baseline (high/medium/low/unknown)
2. Parse CVSS vector → analyze attack characteristics
3. Adjust for attack vector:
- Network-accessible + no auth + no UI → elevate to HIGH
- Local-only access → reduce HIGH to MEDIUM
4. Adjust for vulnerability type:
- Check against agent-specific risk categories
- Elevate or reduce score based on deployment context
5. Check for public exploits (if enabled):
- Elevate score if exploits detected
6. Generate rationale explaining the final score
```
## Ejemplos
### Ejemplo 1: Critical RCE (High Exploitability)
```json
{
"cve_id": "CVE-2024-12345",
"cvss_score": 9.8,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"type": "remote_code_execution",
"description": "Unauthenticated RCE in Express.js framework"
}
```
** Producto de Análisis**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments"
}
```
**Por qué ALTO**: CVSS crítico + red accesible + no auth + RCE tipo.
### Ejemplo 2: SSRF en la API de agente (Explotabilidad alta)
```json
{
"cve_id": "CVE-2024-23456",
"cvss_score": 7.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:L",
"type": "server_side_request_forgery",
"description": "SSRF in webhook handler allows internal network access"
}
```
** Producto de Análisis**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "High CVSS score (7.3); remotely exploitable without authentication; SSRF affects agents making external requests"
}
```
**Por qué ALTO**: SSRF es crítico para los agentes que hacen llamadas de API (la mayoría lo hace). El acceso a la red sin autenticación eleva el riesgo.
### Ejemplo 3: Path Traversal with Public Exploit (High Exploitability)
```json
{
"cve_id": "CVE-2024-34567",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"type": "path_traversal",
"references": [
"https://exploit-db.com/exploits/51234",
"https://nvd.nist.gov/vuln/detail/CVE-2024-34567"
]
}
```
** Producto de análisis (con --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (6.5); network accessible; path traversal affects agents with file access; public exploit available (1 source)"
}
```
**Por qué ALTO**: Acceso a ficheros Path traversal + agente + exploit público eleva el CVSS medio a alta explotabilidad.
### Ejemplo 4: XSS in Agent UI (Medium Exploitability)
```json
{
"cve_id": "CVE-2024-45678",
"cvss_score": 7.1,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:L",
"type": "cross_site_scripting",
"description": "Stored XSS in agent management dashboard"
}
```
** Producto de Análisis**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (7.1); network accessible; XSS has limited impact in headless agents"
}
```
**Por qué MEDIUM**: A pesar de la alta CVSS, XSS es menos crítico en implementaciones de agentes (operación sin cabeza). Requiere la interacción del usuario.
### Ejemplo 5: Escalada Local de Privilege (Explotabilidad de Medios)
```json
{
"cve_id": "CVE-2024-56789",
"cvss_score": 8.8,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
"type": "privilege_escalation",
"description": "Local privilege escalation via symbolic link attack"
}
```
** Producto de Análisis**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (8.8); requires local access"
}
```
**Por qué MEDIUM**: A pesar de la alta CVSS, requiere acceso local. Los agentes normalmente se ejecutan en entornos containerizzatos y en caja donde la escalada local tiene un impacto limitado.
### Ejemplo 6: Contaminación Prototipo con Exploit (High Exploitability)
```json
{
"cve_id": "CVE-2024-67890",
"cvss_score": 5.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N",
"type": "prototype_pollution",
"description": "Prototype pollution in lodash merge function",
"references": [
"https://github.com/exploit/prototype-pollution-poc",
"https://snyk.io/vuln/SNYK-JS-LODASH-1234567"
]
}
```
** Producto de análisis (con --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (5.3); remotely exploitable without authentication; prototype pollution can escalate in Node.js agents; public exploit available (1 source)"
}
```
**Por qué ALTO**: contaminación prototipo en agentes Node.js + explotación pública + acceso a la red sin auth = alto riesgo a pesar de CVSS moderado.
## Usage in ClawSec Workflows
### Automated Scoring (NVD Feed)
El flujo de trabajo `poll-nvd-cves.yml` marca automáticamente nuevos CVEs:
```bash
# Workflow step
python utils/analyze_exploitability.py --json --check-exploits < cve-data.json
```
Los asesores en `advisories/feed.json` pueden incluir:
```json
{
"id": "CVE-2024-12345",
"severity": "high",
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments",
"attack_vector_analysis": {
"is_network_accessible": true,
"requires_authentication": false,
"requires_user_interaction": false,
"complexity": "low"
}
}
```
### Manual Analysis
Los investigadores de seguridad pueden analizar CVEs manualmente:
```bash
# Basic analysis
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"type":"ssrf"}' | \
python utils/analyze_exploitability.py --json
# With exploit detection
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"references":["https://exploit-db.com/exploits/51234"]}' | \
python utils/analyze_exploitability.py --json --check-exploits
```
## Filtración por Exploitability
Los usuarios pueden filtrar las asesorías mediante la puntuación de explotación:
```bash
# Get only high-exploitability advisories
curl -s https://clawsec.prompt.security/feed.json | \
jq '.advisories[] | select(.exploitability_score == "high")'
# Prioritize by exploitability and severity
curl -s https://clawsec.prompt.security/feed.json | \
jq '[.advisories[] | select(.exploitability_score == "high" and .severity == "critical")] | sort_by(.cvss_score) | reverse'
```
## Backfilling Existing Advisories (Mantenimiento histórico)
`scripts/backfill-exploitability.sh` se mantiene como una utilidad de mantenimiento histórico para el mantenimiento de un repositorio.
No es el camino principal para la generación de asesoramiento normal.
Rutas preferidas:
1. Ruta canónica de la CI: ejecutar el flujo de trabajo NVD con init/reset para reconstruir asesorías de NVD y firmar artefactos en tubería.
2. Ruta del desarrollador local: ejecute `./scripts/populate-local-feed.sh --force` para repoblar los piensos locales con contexto de explotación.
Use backfill sólo cuando repara explícitamente el contenido de alimentación heredado que ya existe en-repo.
## Community Contributions
Los miembros de la comunidad pueden presentar evaluaciones de la explotación:
1. **Informe a través de GitHub Edición**: Use la plantilla de asesoramiento para informar a CVEs con contexto de explotación
2. **Análisis automatizado**: El flujo de trabajo `community-advisory.yml` marca automáticamente CVEs reportado por la comunidad
3. **Revisión manual**: Los usuarios examinan y aprueban evaluaciones de la explotación
4. **Feed Update**: Los asesores aprobados se añaden al pienso con puntuaciones de explotación
## Limitaciones y trabajo futuro
Limitaciones actuales
1. **Análisis estadístico**: El cableado se basa en metadatos CVE, no en el análisis dinámico del tiempo de ejecución
2. **No hay detección de versiones**: No comprueba si las versiones específicas son vulnerables
3. ** Clasificación interna**: No considera atenuaciones parciales o defensa en profundidad
4. **Contexto enviado**: No conoce la configuración exacta del agente ni las herramientas desplegadas
### Future Enhancements
1. **Incorporar las puntuaciones de probabilidad EPSS (Exploit Prediction Scoring System)**
2. **KEV Matching**: Cross-reference with CISA KEV (Known Exploited Vulnerabilities) catalog
3. **Agent Profiling**: Considerar las capacidades de los agentes desplegados y las API expuestas
4. **Detección de Mitigación**: Comprobar reglas de WAF, sandboxing u otros controles compensatorios
5. **Escobimiento basado en MLS**: Usar el aprendizaje automático para predecir la explotación basada en datos históricos
## Referencias
**CVSS v3.1 Especificación**: [https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document)
- Guía CVSS v2**: [https://www.first.org/cvss/v2/guide](https://www.first.org/cvss/v2/guide)
- [https://www.first.org/epss/](https://www.first.org/epss/)
- **CISA KEV**: [https://www.cisa.gov/known-exploited-vulnerabilities-catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
**NVD API**: [https://nvd.nist.gov/developers/vulnerabilities](https://nvd.nist.gov/developers/vulnerabilities)
## Contribución
Mejorar la metodología de puntuación de explotabilidad:
1. **Enviar casos de prueba**: Agregar casos de prueba a `utils/analyze_exploitability.py`
2. **Informe Positivos/Negativos falsos**: Open GitHub números con ejemplos de CVE
3. **Ajustes para la preparación de proyectos**: Presentar relaciones públicas con racionalidad y ejemplos
4. **Compartir el contexto del agente**: Contribuir patrones de vulnerabilidad específicos del agente
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
-...
**Maintained by**: [Prompt Security](https://prompt.security)
**Licencia**: AGPL-3.0 o later
** Última actualización**: 2026-03-01
wiki/es/glossary.md
+62
View File
@@ -0,0 +1,62 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../glossary.md
Review status: draft
-->
# Glosario
## Terms
TENIDO TÉPTIMO TENIDO Definición ANTE
Silencio.
← Asesoramiento Feed Silencio documento JSON (`feed.json`) que contiene asesorías de seguridad para habilidades/platformas. Silencio
Silencio Especificador Afectado Silencio Selector de Habilidad como `skill@1.2.3`, comodín, o rango utilizado en la lógica de juego. Silencio
TEN Guarded Install Silencio Comportamiento del instalador de dos pasos que requiere confirmación explícita cuando los avisos coinciden. Silencio
← Archivos SBOM ← Lista de artefactos declarados por Habilidad en `skill.json` utilizada para embalaje y validación. Silencio
Archivo de firmas TEN Base64 (`.sig`) almacenado por separado de la carga útil firmada. Silencio
Silencio Checksum Manifest Silencio File hash map (`checksums.json`) utilizado para verificar la integridad de la carga útil. Silencio
## Skill Packaging Terms
TENIDO TÉPTIMO TENIDO Definición ANTE
Silencio.
Tag tóxico etiqueta Git formateado como `<skill>-v<semver>` utilizado por la automatización de liberación. Silencio
tención de lanzamiento de activos Silenciosos archivos adjuntos a la liberación de GitHub (zip, `skill.json`, checksums, signatures). Silencio
tención Catálogo Índice Silencioso `public/skills/index.json`, lista generada consumida por el catálogo web. Silencio
← Componentes embedded Silencio Capability paquete de una habilidad incluida en otra (por ejemplo, la alimentación incrustada en suite). Silencio
## Condiciones de asesoramiento y seguridad
TENIDO TÉPTIMO TENIDO Definición ANTE
Silencio.
← Verificación perdida de Fail TEN Rechazar la carga útil si la validación de la firma o el chequesum falla. Silencio
← Modo de Compatibilidad Insigned tención Sendero de bypass temporal habilitado a través de `CLAWSEC_ALLOW_UNSIGNED_FEED=1`. Silencio
tención permanente Regla tención Config entrada que coincida con `checkId` y `skill` para suprimir hallazgos conocidos/aceptados. Silencio
TEN Key Fingerprint TEN SHA-256 digest of DER-encoded public key used for key consistency checks. Silencio
## Runtime and Platform Terms
TENIDO TÉPTIMO TENIDO Definición ANTE
Silencio.
← OpenClaw Hook Silencio Runtime event handler (`clawsec-advisory-guardian`) que comprueba las advertencias. Silencio
Silencio NanoClaw IPC Silencio Host/container task exchange for advisory ref, signature verification, integrity checks. Silencio
← Integrity Baseline tención Guardado hahes/snapshots aprobado para archivos protegidos. Silencio
Hash-Chained Audit Log Registro de auditorías sólo de apéndice donde cada entrada depende del hash anterior. Silencio
## CI/CD Terms
TENIDO TÉPTIMO TENIDO Definición ANTE
Silencio.
Contaminación del NVD CVEs Workflow ← Corriente de trabajo programada que fetches y transforma CVEs NVD en asesorías. Silencio
TEN Comunidad Asesoramiento flujo de trabajo Silencioso flujo de trabajo desencadenado por la etiqueta de edición que publica asesorías comunitarias aprobadas. Silencio
Flujo de trabajo de liberación de Habilidades TENIDO Embalaje/envase/envase/envase publicado por etiqueta para habilidades. Silencio
Silencio Páginas de Implementación Flujo de trabajo Silencioso que construye activos del sitio y espejos liberación / artefactos advisorios. Silencio
## Referencias Fuente
- tipos.
- habilidades/clawsec-suite/skill.json
- habilidades/clawsec-nanoclaw/skill.json
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
- habilidades/clawsec-nanoclaw/guardian/integrity-monitor.ts
- scripts/populate-local-feed.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
wiki/es/localization.md
+42
View File
@@ -0,0 +1,42 @@
# Flujo de localización
## Objetivo
Definir un pipeline repetible para localización de documentación (README y wiki) en ClawSec.
## Alcance
- Idioma fuente: inglés (`README.md`, `wiki/*.md`)
- Idioma traducido actual: español (`README.es.md`, `wiki/es/*.md`)
- Idiomas futuros: `wiki/<lang>/...` y `README.<lang>.md`
## Reglas de fuente de verdad
1. Los archivos en inglés son canónicos.
2. Las traducciones deben preservar exactamente comandos, rutas, bloques de código e identificadores.
3. Nombres de producto y skills no se traducen (`ClawSec`, `OpenClaw`, `NanoClaw`, `Hermes`, `Picoclaw`).
4. Si la cobertura de traducción es parcial, el archivo traducido debe declararlo.
## Convenciones de carpetas
- Traducciones README:
- `README.es.md`
- Futuro: `README.fr.md`, `README.de.md`, `README.ja.md`
- Traducciones wiki:
- `wiki/es/INDEX.md`
- `wiki/es/<page>.md`
- Assets de localización:
- `wiki/i18n/terminology-en-es.md`
- `wiki/i18n/translation-tracker.md`
## Flujo de actualización
1. Normalizar docs fuente en inglés.
2. Registrar cambios en `wiki/i18n/translation-tracker.md`.
3. Traducir páginas modificadas preservando estructura Markdown.
4. Ejecutar QA (enlaces, comandos, terminología).
5. Ejecutar `npm run gen:wiki-llms`.
6. Abrir PR con páginas traducidas y gaps pendientes.
## Checklist QA
- [ ] Jerarquía de títulos preservada.
- [ ] Snippets de comandos sin cambios.
- [ ] Rutas y URLs sin cambios.
- [ ] Nombres de skills/plataformas sin cambios.
- [ ] Terminología de seguridad consistente.
- [ ] Enlaces de traducción visibles desde índices.
wiki/es/migration-signed-feed.md
+185
View File
@@ -0,0 +1,185 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../migration-signed-feed.md
Review status: draft
-->
# Migration Record: Unsigned Feed → Signed Feed (Completed)
## 1) Objetivo y situación
Document how ClawSec advisory distribution moved from unsigned `feed.json` delivery to detached-signature verification, with compatibility kept for legacy clients.
Situación actual en `main`:
- La publicación de alimentos firmados está activa en los flujos de trabajo consultivos y el flujo de trabajo.
- Los consumidores de Suite y NanoClaw predeterminan firmar puntos finales de alimentación.
- La conducta no firmada sólo existe como bypass de compatibilidad explícita (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`).
## 2) Base de referencia (hoy, después de la migración)
Vías de alimentación actuales en uso activo:
- Fuente de la verdad: `advisories/feed.json`
- Firma de origen: `advisories/feed.json.sig`
- Copia de habilidad: `skills/clawsec-feed/advisories/feed.json`
- Firma de copia de la piel: `skills/clawsec-feed/advisories/feed.json.sig`
- Copia de las páginas: `public/advisories/feed.json`
- Firma de páginas: `public/advisories/feed.json.sig`
- Última copia del espejo: `public/releases/latest/download/advisories/feed.json` (+ `.sig`)
Por defecto del consumidor actual:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- URL predeterminada: `https://clawsec.prompt.security/advisories/feed.json`
## 3) Principios de migración
- ** Publicación final**: publicar firmas antes de ejecutar la verificación.
**Apenado rápido sólo durante la transición**: el período de compatibilidad temporal es explícito y con plazos.
- **Enrollo asegurado**: hacer cumplir la verificación después de la telemetría confirma la publicación firmada estable.
- **Regreso rápido**: preservar un camino de regreso a un comportamiento sin firmar mientras la causa raíz es investigada.
## 4) Línea temporal gradual (histórica)
### Fase 0 — Preparación (Completa)
Entregas:
- claves de firma generadas y huellas digitales grabadas
- Secretos GitHub creados
- clave(s) públicas añadidos en repo
- gobooks aprobados (`security-signing-runbook.md`, este archivo)
Criterios de salida:
- huellas digitales clave verificadas por el revisor
- Controles de rama/flujo de trabajo protegidos
### Fase 1 - Firma de la CI activada, sin cumplimiento del cliente (Completed)
Aplicar:
- añadir paso de firma de alimentos/flujo de trabajo para producir `advisories/feed.json.sig`
- Producción opcional `advisories/checksums.json` + `.sig`
- asegurar que CI verifica firmas antes de publicar artefactos
Actualizar también el despliegue:
- copiar artefactos `.sig` a `public/advisories/`
- espejo `.sig` en `public/releases/latest/download/advisories/`
Criterios de salida:
- firmas generadas con éxito para todas las rutas de actualización de alimentación
- desplegar artefactos contienen tanto carga útil como compañeros de firma
### Fase 2 - Apoyo dual-read/dual-verify al consumidor (completo)
Aplicar en consumidores:
- leer `feed.json` y `feed.json.sig`
- verificar con llave pública
- mantener bajo control temporal sin señalización durante la ventana de migración
Validación:
- prueba remoto camino firmado
- probar el camino de regreso firmado local
- test invalid signature rejection
Criterios de salida:
- lógica de verificación liberada y probada
- no fallas de verificación falsos positivos en el período de empapado
### Fase 3 - Ejecución (completa)
Acciones:
- deshabilitar el comportamiento temporal sin firmar en los caminos predeterminados
- añadir las puertas CI/publish que fallan cuando `.sig` falta
- anunciar fecha de ejecución en notas de liberación y documentos
Criterios de salida:
- todos los clientes de producción verifican firmas por defecto
- ninguna dependencia de alimentación no firmada en el flujo de instalación estándar
### Fase 4 - Estabilización (en curso)
Acciones:
- ejecutar el primer simulacro de rotación clave
- perforación de mesa redondeada
- migración estrecha con revisión posterior a la ejecución
## 5) Plan de retroceso
### Rollback triggers
Inicie la devolución si se produce alguno de los siguientes:
- fallas sostenidas de verificación de firmas entre clientes
- El flujo de trabajo de firma no puede producir firmas válidas
- compromiso clave sospechoso, pero aún no se ha desplegado la llave de reemplazo
- ruta de despliegue publica pares de carga/signatura desajustados
## Rollback levels
## Nivel 1 (preferido): Ventana de bypass de verificación, mantenga la publicación firmada
Usar cuando: firmar es saludable, el verificador del lado cliente tiene un defecto.
Acciones:
1. Re-enable comportamiento temporal de aceptación no firmada en la rama de liberación del cliente.
2. Entrega de parche con fecha de vencimiento explícita para bypass.
3. Mantenga activo el oleoducto para evitar la brecha de autenticidad.
Objetivo de recuperación: restaurar la verificación estricta dentro de 24 a 48h.
### Level 2: Signed pipeline paused, unsigned feed temporary authoritative
Utilizar cuando: firmar el oleoducto es inestable o producir artefactos inconsistentes.
Acciones:
1. Desactivar el flujo de trabajo de firma o paso de firma.
2. Seguir publicando `advisories/feed.json` sin firmar a través de los flujos de trabajo existentes.
3. Revertir las puertas de despliegue que requieren artefactos `.sig`.
4. Abrir registro de incidentes y tiempo de seguimiento en modo no firmado.
Objetivo de recuperación: restaurar la publicación firmada ASAP, idealmente.
### Level 3: Full release freeze
Use cuando: compromiso o integridad del repositorio/flujos de trabajo está en duda.
Acciones:
1. Pause feed mutation and deployment workflows.
2. Restaurar archivos de asesoramiento/flujos de trabajo conocidos.
3. Rotar claves y credenciales.
4. Reanuda el oleoducto sólo después del inicio de la revisión de seguridad.
## Roll-forward after rollback
- identificar la causa raíz
- añadir pruebas de regresión / puertas
- redistribuir artefactos firmados
- publicar incidente + resumen de remediación
## 6) Plan de comunicación
For enforcement and rollback events, communicate:
- ¿Qué cambió?
- acción esperada del operador/cliente
- duración del modo de compatibilidad temporal (si existe)
- comandos de verificación para usuarios
Canales recomendados:
- Notas de liberación GitHub
- actualizaciones del repositorio README/docs
- informe de emisión/incidente en el repositorio
## 7) Lista de verificación de go/no go
Sólo si todos son verdaderos:
- La tasa de éxito del flujo de trabajo de firma es estable
- las firmas se reflejan en todos los puntos finales de alimentación documentados
- ruta de verificación del consumidor probada para retroceso remoto + local
- el propietario de la devolución es asignado y accesible
- el procedimiento de rotación clave ha sido seco al menos una vez
## Referencias Fuente
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- asesorías/feed.json
- wiki/security-signing-runbook.md
wiki/es/overview.md
+111
View File
@@ -0,0 +1,111 @@
# Sinopsis
## Propósito
- ClawSec es un repositorio orientado a seguridad que combina un catálogo web público con habilidades de seguridad instalables para entornos OpenClaw, NanoClaw, Hermes y Picoclaw.
- El codebase soporta tres rutas de entrega en paralelo: publicación de sitio estático, distribución de advisories firmados y empaquetado de releases por skill en GitHub.
- Los usuarios principales son operadores de agentes, desarrolladores de skills y maintainers que ejecutan automatización de seguridad basada en CI.
![Prompt Security Logo](../assets/overview_img_01_prompt-security-logo.png)
![ClawSec Mascot](../assets/overview_img_02_clawsec-mascot.png)
## Layout del repositorio
| Ruta | Rol | Notas |
Silencio.
| `pages/`, `components/`, `App.tsx`, `index.tsx` | UI Vite + React | Catálogo de skills, feed de advisories y páginas de detalle. |
| `skills/` | Paquetes de skills de seguridad | Cada skill contiene `skill.json`, `SKILL.md` y opcionalmente scripts/tests/docs. |
| `advisories/` | Canal de advisories del repositorio | `feed.json` firmado + `feed.json.sig` y material de claves. |
| `scripts/` | Automatización local | Poblar feed/skills, checks pre-push y helpers de release. |
| `.github/workflows/` | Pipelines CI/CD | CI, releases, polling NVD, ingesta de advisory comunitario y deploy de pages. |
| `utils/` | Utilidades Python | Validación de skills y helpers de empaquetado/checksums. |
| `public/` | Assets estáticos publicados | Media del sitio, advisories espejados y artefactos generados de skills. |
| `wiki/` | Hub de documentación | Arquitectura, runbooks operativos, compatibilidad y guías de verificación. |
## Puntos de entrada
| Entrada | Tipo | Propósito |
Silencio.
| `index.tsx` | Bootstrap frontend | Monta la app React en `#root`. |
| `App.tsx` | Router frontend | Define rutas para home, skills, feed y wiki. |
| `scripts/prepare-to-push.sh` | Flujo dev | Ejecuta checks de lint/type/build/security antes de push. |
| `scripts/populate-local-feed.sh` | Bootstrap de datos | Obtiene CVEs del NVD y actualiza feeds locales de advisories. |
| `scripts/populate-local-skills.sh` | Bootstrap de datos | Construye `public/skills/index.json` y checksums por skill. |
| `scripts/generate-wiki-llms.mjs` | Export de docs | Genera `public/wiki/llms.txt` y exportes wiki por página. |
| `.github/workflows/skill-release.yml` | Entrada de release | Maneja checks PR (paridad de versión/dry-run) y empaquetado/firmado/release basado en tags. |
| `.github/workflows/poll-nvd-cves.yml` | Feed programado | Consulta NVD y actualiza advisories. |
## Artefactos clave
| Artefacto | Producido por | Consumido por |
Silencio.
| `advisories/feed.json` | Poll NVD + workflows comunitarios | UI web, hook de clawsec-suite, instaladores. |
| `advisories/feed.json.sig` | Pasos de firmado en workflow | Verificación de firma en tooling de suite/nanoclaw. |
| `public/skills/index.json` | Workflow de deploy / script local | `pages/SkillsCatalog.tsx` y `pages/SkillDetail.tsx`. |
| `public/wiki/llms.txt` + `public/wiki/**/llms.txt` | Script generador wiki + hooks de build | Exportes wiki para LLM enlazados desde la UI del wiki. |
| `public/checksums.json` + `public/checksums.sig` | Workflow de deploy | Artefactos de integridad publicados para operadores y clientes runtime. |
| `release-assets/checksums.json` | Workflow de release de skill | Consumidores de release que verifican integridad de zips. |
| `skills/*/skill.json` | Autores de skills | Generación de catálogo del sitio, validadores y pipelines de release. |
## Flujos clave
- Desarrollo web local: `npm install` y luego `npm run dev`.
- Preview local de datos de seguridad: ejecuta `./scripts/populate-local-skills.sh` y `./scripts/populate-local-feed.sh` antes de abrir `/skills` y `/feed`.
- Quality gate pre-push: ejecuta `./scripts/prepare-to-push.sh` (opcional `--fix`).
- Ciclo de vida de skill: edita `skills/<name>/`, valida con `python utils/validate_skill.py`, y etiqueta `<skill>-vX.Y.Z` para disparar workflow de release.
- Ciclo de advisories: el polling programado de NVD y la ingesta comunitaria por labels convergen en el mismo feed firmado.
## Snippets de ejemplo
```bash
# UI local + datos locales poblados
npm install
./scripts/populate-local-skills.sh
./scripts/populate-local-feed.sh --days 120
npm run dev
```
```bash
# checks canónicos de TypeScript usados por CI
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
npm run build
```
## Dónde empezar
- Lee `README.md` para posicionamiento del producto y rutas de instalación.
- Abre `App.tsx` y `pages/` para entender el comportamiento de cara al usuario.
- Abre `skills/clawsec-suite/skill.json` para entender el contrato de la suite y sus componentes embebidos.
- Revisa `.github/workflows/ci.yml`, `.github/workflows/pages-verify.yml`, `.github/workflows/skill-release.yml`, `.github/workflows/deploy-pages.yml` y `.github/workflows/wiki-sync.yml` para el comportamiento productivo.
## Cómo navegar
- El comportamiento de UI está centrado en `pages/`; los wrappers visuales están en `components/`.
- La lógica específica de cada skill está aislada por carpeta bajo `skills/`; cada carpeta incluye sus propios scripts/tests/docs.
- El manejo de feeds aparece en tres capas: archivos feed del repositorio, updates de workflows y consumidores runtime (`clawsec-suite`/`clawsec-nanoclaw`).
- Los quality gates operativos viven en `scripts/` y en YAMLs de workflows.
- Para trazas de generación y baseline de actualizaciones, empieza por `wiki/GENERATION.md` y luego ramifica hacia páginas de módulo.
## Errores comunes
- Usar tokens home literales (por ejemplo `\$HOME`) en variables de ruta puede disparar fallas de validación.
- Solicitar JSON desde rutas SPA puede devolver HTML con status 200; las páginas lo tratan como estado vacío.
- El modo bypass de feed no firmado (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) existe solo por compatibilidad de migración y no debe usarse en estado estable.
- La automatización de release espera paridad de versión entre `skill.json` y frontmatter de `SKILL.md`.
- Algunos scripts son POSIX-oriented; en Windows conviene PowerShell o WSL.
## Notas de actualización
- 2026-04-27: Traducción inicial al español en `wiki/es/` como fase 1.
- 2026-02-26: Layout actualizado para apuntar documentación operativa a `wiki/` en lugar del directorio raíz `docs/` (eliminado).
## Referencias de código
- `README.md`
- `README.es.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`
wiki/es/platform-verification.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../platform-verification.md
Review status: draft
-->
Lista de verificación de la plataforma
Utilice esta lista de verificación para validar la portabilidad y el comportamiento de manejo de caminos después de cambios.
## Linux Verification
1. Ejecutar las pruebas del núcleo del nodo:
```bash
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
Se espera: todas las pruebas pasan.
2. No verifique ninguna aceptación literal del camino `$HOME`:
```bash
CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Se espera: salidas no cero con error `Unexpanded home token`.
3. Verificar las obras de expansión `$HOME`:
```bash
HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
```
Se espera: las pruebas de expansión `$HOME` pasan.
## MacOS Verification
1. Ejecute la misma suite de pruebas Node que Linux.
2. Confirme que se documentan los supuestos de la ruta de la herramienta OpenSSL:
- Si utilizas las variaciones LibreSSL/OpenSSL, asegúrate de utilizar formularios de comando probados de los docs.
3. Verificar la expansión de inclinación en el camino de config:
```bash
OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
```
Se espera: la ruta resuelve correctamente (o el error de archivo claro no encontrado en la ubicación ampliada).
## Verificación de Windows (PowerShell)
1. Ejecutar pruebas de Nodo:
```powershell
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
```
Se espera: pasen todos.
2. Verificar el poder Shell env ruta comportamiento de expansión:
```powershell
$env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Se espera: el token de ruta se expande/normaliza o falla con un error claro si faltan los archivos de destino.
3. Verify escape literal token rejection:
```powershell
$env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Se espera: error `Unexpanded home token`; no creación de directorio con literal `$HOME`.
## Line Endings Sanity
1. La política de confirmación está presente:
```bash
test -f .gitattributes && grep -n "eol=lf" .gitattributes
```
Se espera: script/config patrones de archivo ejecuten LF.
2. Después de un checkout prono CRLF, verifique los scripts todavía parse:
```bash
bash -n scripts/populate-local-feed.sh
bash -n scripts/populate-local-skills.sh
```
Se espera: ningún error `^M` shebang/parse.
## Explicit Bug Check: No Literal `$HOME` Creación del directorio
1. Configure un camino con un token literal/escaped.
2. Ejecute el comando setup/install.
3. Verify command fails early with token error.
4. Confirmar no `$HOME` directorio de segmento fue creado bajo directorios de trabajo.
Resultado esperado: ** ningún directorio que contenga `$HOME` literal son creados por scripts de configuración compatibles. #
## Referencias Fuente
- .gitattributes
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- habilidades/clawsec-suite/test/path_ resolution.test.mjs
- habilidades/clawsec-suite/test/guarded_install.test.mjs
- habilidades/clawsec-suite/test/advisory_suppression.test.mjs
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- habilidades/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- habilidades/openclaw-audit-watchdog/test/suppression_config.test.mjs
wiki/es/remediation-plan.md
+89
View File
@@ -0,0 +1,89 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../remediation-plan.md
Review status: draft
-->
# Cross-Platform Remediation Plan
## Fase 1: Cierre de riesgo inmediato (completo)
### Milestones
- Implementar la expansión explícita del home-path + rechazo de token sospechoso en las rutas de funcionamiento/instalación de alto riesgo.
- Agregue pruebas de regresión para la expansión del camino y el rechazo de token.
- Agregue la política de `.gitattributes` LF.
- Ampliar la cobertura de Node lint/type/build CI a Linux/macOS/Windows.
- Actualizar los docs de instalación con guía específica de shell y solución de problemas literal `$HOME`.
### Outcomes
- Literal `$HOME` path propagation bug addressed at source.
- La guía central/instalación de configuración ahora falla rápidamente en las fichas de ruta inválidas.
-...
## Fase 2: Paridad de Windows para los flujos de trabajo críticos (Siguiente)
### Quick wins
- Add Power Sumas equivalentes para los comandos de instalación/control manual más usados en:
- `skills/clawsec-suite/SKILL.md`
- `skills/openclaw-audit-watchdog/SKILL.md`
- `README.md`
- Agregue un `scripts/preflight.mjs` ligero para detectar herramientas faltantes e imprimir consejos de instalación específicos del sistema operativo.
### Milestones
- Poder nativo Instrucciones de Shell para la configuración de suite y gancho de asesoramiento.
- WSL/Git Bash recuento documentado donde los scripts de shell son inevitables.
-...
## Fase 3: Reducir POSIX Superficie de Shell (Refactor Deeper)
### Refactor targets
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `scripts/release-skill.sh`
### Approach
- Recopilar caminos críticos en Node/Python para eliminar la dependencia de los oleoductos `jq/sed/awk/find/chmod`.
- Envoltorios de conchas preseleccionados para compatibilidad atrasada; ruta a nuevas implementaciones multiplataforma.
### Migration notes
- Mantenga los viejos puntos de entrada de script como envoltorios para al menos una liberación menor.
- Emitir advertencias de deprecación con órdenes de migración exactas.
-...
## Fase 4: endurecimiento del CI y verificación continua
### Milestones
- Mantenga la matriz de Nodo (Linux/macOS/Windows) según sea necesario.
- Agregue pruebas de humo de Windows específicas para el manejo de la ruta de instalación.
- Agregue el cheque macOS para notas de compatibilidad de comandos OpenSSL cuando sea relevante.
### Estrategia de ensayo
- Local:
- Ejecutar suites de ensayo Node que cubren la expansión del camino / supresión / comportamiento de instalación.
- Ejecute cheques de sintaxis para scripts modificados.
- CI:
- Controles Matrix Node + pruebas de instalador/supresión/pata vigiladas.
- Se mantienen solo escáneres de seguridad Linux, pero explícitamente marcados como Linux-scopio.
-...
## Rollout / Release Considerations
- No hay cambios de interfaz de ruptura introducidos en este conjunto de parches; el comportamiento es más estricto sólo para los tokens de ruta inválidos/desgastados.
- Comunicar en notas de liberación:
- la validación de tokens ahora aplicada
- cómo corregir los valores inválidos citados env
- Donde Poder Ejemplos de Shell viven
## Referencias Fuente
- .gitattributes
- .github/workflows/ci.yml
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- scripts/release-skill.sh
- habilidades/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- habilidades/clawsec-suite/scripts/guarded_skill_install.mjs
- habilidades/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- wiki/platform-verification.md
wiki/es/security-signing-runbook.md
+239
View File
@@ -0,0 +1,239 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../security-signing-runbook.md
Review status: draft
-->
# ClawSec Signing Operations Runbook
## 1) Propósito
Este manual define los procedimientos operativos para introducir y ejecutar la firma criptográfica en el repositorio ClawSec.
Cubre:
- generación clave
- Gestion secreta GitHub
- Integración del flujo de trabajo de firma
- rotación y revocación clave
- respuesta a incidentes
## 2) Estado operativo actual (importante)
En `main`, los canales de asesoramiento y liberación se firman y verifican por defecto:
- Escritores de comida:
- Actualizaciones `.github/workflows/poll-nvd-cves.yml` `advisories/feed.json` y signos `advisories/feed.json.sig`
- `.github/workflows/community-advisory.yml` hace lo mismo para los informes de emisión aprobados
- ambos artefactos de alimentación firmados en `skills/clawsec-feed/advisories/`
- Carril de publicación Feed:
- `.github/workflows/deploy-pages.yml` publica `public/advisories/feed.json` + `.sig`
- genera y firma `public/checksums.json` + `public/checksums.sig`
- publica clave canónica como `public/signing-public.pem` y `public/advisories/feed-signing-public.pem`
- objetos de compatibilidad con espejos bajo `public/releases/latest/download/` (incluyendo `feed.json`, `feed.json.sig`, `checksums.json`, `checksums.sig`, `signing-public.pem`)
- Alimentar a los consumidores:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- URL de alimentación predeterminada es `https://clawsec.prompt.security/advisories/feed.json`
El modo no firmado sigue siendo un bypass de compatibilidad explícita (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) y no es el modelo operativo estable.
## 3) artefactos firmados por objetivos
### Advisory feed channel
- `advisories/feed.json` (carga)
- `advisories/feed.json.sig` (firma independiente Ed25519; base64)
- `advisories/feed-signing-public.pem` (clave público)
### Canal de artefactos de liberación
- `<release>/checksums.json`
- `<release>/checksums.sig`
- `<release>/signing-public.pem`
## 4) Funciones clave y custodia
**Propietario de seguridad**: aprueba cambios clave en el ciclo de vida y acciones de incidentes.
- **Propietario de Platform**: mantiene flujos de trabajo y secretos GitHub.
- **Revisor**: valida las huellas dactilares en PRs/releases.
Política:
- Las llaves privadas nunca se comprometen
- las claves públicas están comprometidas y revisión de código
- generación clave se produce en la estación de trabajo del operador de confianza o en el entorno respaldado por HSM
## 5) Generación clave (Ed25519)
■ Huye de una estación de trabajo segura. No corras con corredores compartidos de CI.
```bash
# Feed signing keypair
openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem
openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem
# Release checksums signing keypair (optional separate key)
openssl genpkey -algorithm Ed25519 -out release-signing-private.pem
openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem
```
Generar huellas dactilares (store in ticket/change record):
```bash
openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256
openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256
```
Opcional test-sign antes de publicar:
```bash
echo '{"probe":"ok"}' > /tmp/probe.json
openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
```
## 6) GitHub secrets setup
### Secretos obligatorios
- `CLAWSEC_SIGNING_PRIVATE_KEY` — Llave privada con código PEM Ed25519 (utilizada para la firma de alimentación y liberación)
- `CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (opcional) contraseña si la clave privada está encriptada
#### Procedure
1. Ir a **Repo Settings → Secretos y variables → Acciones → Nuevo secreto del repositorio**.
2. Paste completo PEM incluyendo cabecera/pieza.
3. Preferencia GitHub ** Secretos del medio ambiente** (con revisores requeridos) para el análisis del flujo de trabajo cuando sea posible.
4. Billete de cambio con:
- nombre secreto
- Creador
- tiempo de creación
- huella clave
### Protección del medio ambiente recomendada
- Solicitar aprobación manual para flujos de trabajo que puedan usar secretos de firma.
- Restringir quién puede editar flujos de trabajo protegidos.
- Permitir la protección de ramas para `main` y requerir revisión para cambios de flujo de trabajo.
## 7) Puntos de integración del flujo de trabajo
Este repo impone la firma como un control post-mutación, pre-publicado.
### Feed pipeline
Puntos de mutación de alimentación actuales:
- `.github/workflows/poll-nvd-cves.yml`
- `.github/workflows/community-advisory.yml`
Comportamiento actual:
- signos de flujo de trabajo `advisories/feed.json` en `advisories/feed.json.sig`
- firma de acciones verifica firmas generadas durante la ejecución del flujo de trabajo
- los artefactos firmados se cometen a través de la automatización PR
### Pautas de tuberías
actual fabricante:
- `.github/workflows/deploy-pages.yml`
Comportamiento actual:
- copias de pago/transmisión a `public/advisories/`
- genera + signos `public/checksums.json` y `public/checksums.sig`
- publica la clave de firma de `public/signing-public.pem` y `public/advisories/feed-signing-public.pem`
- Espejos de asesoramiento + firma / checksum/key compañeros en `public/releases/latest/download/` caminos de compatibilidad
### Gasoducto de liberación de habilidades (recomendado endurecimiento)
Generador de liberación actual:
- `.github/workflows/skill-release.yml`
Comportamiento actual:
- crea `checksums.json`, lo firma como `checksums.sig`, y verifica la firma antes de publicar
- incluye `signing-public.pem` en activos de liberación
- valida la huella generada en clave pública contra el material clave canónico
## 8) Política de rotación y guía
## Rotation cadence
- Rutina: cada 90 días (o política de org más estricta).
- Inmediatamente: sobre sospecha de exposición, cambio de flujo de trabajo no autorizado o desajuste de firma no explicada.
### Rotación de rutina
1. Generar nuevo teclado(s).
2. Open PR que actualiza archivos de clave pública y documentación de huellas dactilares.
3. Agregue nuevas teclas privadas como GitHub secret(s).
4. Combina cambios de flujo de trabajo que utilizan nuevas teclas.
5. Reasignar los últimos manifiestos de alimentación/liberación.
6. Validar la verificación en CI y en un cliente externo.
7. Quitar viejos secretos de llave privada.
8. Mantenga la vieja referencia pública clave sólo siempre que sea necesaria para la verificación histórica.
### Pasos de revocación
1. Desactivar los flujos de trabajo utilizando clave comprometida.
2. Retire los secretos de GitHub comprometidos.
3. Presentar nota de revocación y nueva clave pública.
4. Reasignar los últimos artefactos con llave de reemplazo.
5. Publish incident advisory with timestamp and impacted window.
## 9) Libro de juegos de respuesta de incidentes (consignación específica)
## Triggers
- la verificación de firmas falla para la nueva publicación de feed/release
- compromisos desconocidos / ediciones de flujo de trabajo tocando caminos de firma
- filtrado material clave, registro accidental o acceso secreto sospechoso
#### Severity guide
**SEV-1**: la exfiltración clave confirmada o firmada malintencionadamente carga útil publicada
**SEV-2**: fallas de verificación con causa desconocida
**SEV-3**: incumplimiento de procedimiento, no compromiso activo
### Fases de respuesta
1. **Contenimiento* *
- pausa para firmar y publicar flujos de trabajo
- bloque de alimentación se fusiona si la autenticidad es incierta
2. **Investigación**
- revisar registros de flujo de trabajo
- review commits affecting `.github/workflows/`, `advisories/`, and key files
- determinar los tiempos y artefactos afectados
3. *Erradicación*
- rotar/revocar claves comprometidas
- restaurar objetos de confianza de un compromiso conocido-bueno
4. *Recuperación*
- artefactos de re-signación
- Redistribuir páginas/liberaciones
- verificar a través de la comprobación del cliente independiente
5. **Post-incident* *
- publicar cronograma y resumen de remediación
- endurecer los controles (revisar las puertas, entornos protegidos, alcance secreto)
## 10) Lista de comprobación de pruebas de auditoría
Para cada ciclo de liberación o carrera de señalización de alimentación, retén:
- workflow run URL y compromete SHA
- señalización de huellas digitales en uso
- Registros de resultados de verificación
- Aprobaciones del operador/revisor
- cualquier excepción o racional de bypass
## 11) Criterios de aceptación mínima antes de cambios de política más estrictos
Antes de reforzar aún más la política (por ejemplo, eliminar las vías de bypass de compatibilidad):
- los artefactos firmados se producen consistentemente durante al menos 2 semanas
- desplegar espejos de tuberías compañeros de firma
- un taladro de retroceso y un taladro de rotación clave completado con éxito
- respuesta a incidentes identificados y documentados por el propietario
## Referencias Fuente
- asesorías/feed.json
- asesorías/feed.json.sig
- consejeros/feed-signing-public.pem
- Clawsec-signing-public.pem
- .github/actions/sign-and-verify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- scripts/ci/verify_signing_key_consistency.sh
- wiki/migration-signed-feed.md
wiki/es/security.md
+79
View File
@@ -0,0 +1,79 @@
# Seguridad
## Resumen del modelo de seguridad
- ClawSec protege tanto la distribución de contenido (artefactos firmados) como el comportamiento en runtime (advisory gating, monitoreo de integridad).
- Las anclas de confianza son claves públicas fijadas en el repo y verificadas contra outputs generados por workflows.
- Los consumidores runtime usan por defecto un modelo verification-first, con flags de bypass explícitos solo para migración.
## Controles criptográficos
| Control | Mecanismo | Ubicación |
Silencio.
| Autenticidad del feed | Firmas detached Ed25519 (`feed.json.sig`) | Workflows de advisories + librerías de verificación del consumidor. |
| Integridad de artefactos | Manifiestos de checksum SHA-256 (`checksums.json`) | Workflows de release de skill y deploy de pages. |
| Consistencia de claves | Comparación de fingerprint entre docs + PEM canónicos | `scripts/ci/verify_signing_key_consistency.sh`. |
| Acción de verificación de firma | Acción compuesta de sign+verify en CI | `.github/actions/sign-and-verify/action.yml`. |
## Controles de enforcement en runtime
| Control | Componente | Efecto |
Silencio.
| Advisory hook gating | `clawsec-advisory-guardian` | Alertas y guía cautelosa según advisories coincidentes. |
| Instalador con doble confirmación | `guarded_skill_install.mjs` | Sale con código `42` hasta recibir confirmación explícita en advisories coincidentes. |
| Extensión de reputación | `clawsec-clawhub-checker` | Scoring de riesgo adicional antes de instalar. |
| Signature gate en NanoClaw | `skill-signature-handler.ts` + herramienta MCP | Bloquea instalaciones de paquetes manipulados/no firmados por política. |
| Monitor de baseline de integridad | `soul-guardian` + monitor de integridad NanoClaw | Detección de drift, cuarentena, restauración e historial auditable. |
## Controles de cadena de suministro y CI
- CI ejecuta Trivy, npm audit, CodeQL y Scorecard.
- Los checks locales pre-push pueden ejecutar `gitleaks detect` si `gitleaks` está instalado.
- Los workflows de release validan existencia de SBOM antes de empaquetar.
- El workflow de deploy verifica el fingerprint de la signing key generada contra material de clave canónico.
- La documentación de release incluye comandos de verificación manual para consumidores downstream.
## Playbooks de incidentes y rotación
- `wiki/security-signing-runbook.md` define generación de claves, custodia, rotación y fases de incidentes.
- `wiki/migration-signed-feed.md` define enforcement por etapas y niveles de rollback.
- Los paths de rollback priorizan preservar publicación firmada cuando sea posible y limitar temporalmente cualquier bypass.
## Snippets de ejemplo
```bash
# verificar fingerprint de la clave pública canónica
openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256
```
```bash
# ejecutar guardrail de consistencia de claves usado en CI
./scripts/ci/verify_signing_key_consistency.sh
```
## Tradeoffs de seguridad conocidos
- El modo de compatibilidad sin firma reduce garantía y debe deshabilitarse cuando termine la migración.
- Algunos paths de deploy toleran assets de checksums legacy sin firma por compatibilidad retroactiva.
- Los checks de reputación dependen de output de tooling externo y pueden incluir falsos positivos/negativos heurísticos.
- Los scripts locales heredan confianza del entorno; un shell local comprometido aún puede subvertir flujos del operador.
## Oportunidades de hardening
- Eliminar flags de compatibilidad unsigned tras estabilizar migración.
- Expandir verificación determinista de checksum/firma para todos los archivos release espejados.
- Añadir tests explícitos para escenarios de falla de firma a nivel workflow.
- Aumentar telemetría runtime para fallas en fetch/verify de advisories y simplificar triage de incidentes.
## Notas de actualización
- 2026-04-27: Traducción inicial al español de `wiki/security.md`.
- 2026-02-26: Referencias de signing y migración movidas desde `docs/` raíz a páginas operativas en `wiki/`.
## Referencias de código
- `SECURITY.md`
- `wiki/security-signing-runbook.md`
- `wiki/migration-signed-feed.md`
- `scripts/ci/verify_signing_key_consistency.sh`
- `.github/actions/sign-and-verify/action.yml`
- `.github/workflows/poll-nvd-cves.yml`
- `.github/workflows/community-advisory.yml`
- `.github/workflows/skill-release.yml`
- `.github/workflows/deploy-pages.yml`
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-clawhub-checker/scripts/enhanced_guarded_install.mjs`
- `skills/soul-guardian/scripts/soul_guardian.py`
- `skills/clawsec-nanoclaw/host-services/skill-signature-handler.ts`
- `skills/clawsec-nanoclaw/guardian/integrity-monitor.ts`
wiki/es/testing.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../testing.md
Review status: draft
-->
# Testing
## Testing Strategy
- El repositorio utiliza verificación en capas en lugar de un comando `npm test` raíz.
- La confianza básica proviene de las puertas de forro/tipo/construcción más la habilidad local suites de pruebas de nodos.
- Python y shell tooling se validan mediante controles de seguridad y forro dedicados.
- Las tuberías de flujo de trabajo ejecutan las mismas clases de comandos utilizadas en la automatización local pre-push.
## Verification Layers
← Layer ← Comandos
Silencio.
Controles de Frontend/static TEN ESLint + `tsc --noEmit` + `npm run build` ANTE TS/TSX corrección y construcción de viabilidad. Silencio
Exámenes de la unidad de Habilidad Silencio `node skills/<skill>/test/*.test.mjs` ANTE Signature, matching, suppression, installer contracts. Silencio
← Calidad de Python TENIDO `ruff check utils/`, `bandit -r utils/ -ll` ANTE Utility correctness and security patterns. Silencio
TEN Shell/script quality TEN ShellCheck + manual script smoke runs ← Higiene del script y robustez del comando. Silencio
tención CI escáneres de seguridad Silencio Trivy, auditoría npm, CodeQL, Scorecard tención Dependencia, configuración y postura de seguridad de cadena de suministro. Silencio
tención Local pre-push security scan TEN Opcional `gitleaks detect` vía `scripts/prepare-to-push.sh` ANTE La detección de fugas secretas antes de empujar. Silencio
## Skill Test Matrix
← Habilidad tóxica Archivos de prueba
Silencio.
TENIDO `clawsec-suite` ANTE `feed_verification`, `guarded_install`, `path_resolution`, pruebas de fuzz ANTES Controles de firmas, gatitas de asesoramiento, seguridad de ruta, solidez de combinación. Silencio
tención `openclaw-audit-watchdog` Silencioso de supresión config y hacer pruebas TEN Config parsing, comportamiento de supresión, reportar formato. Silencio
Silencio `clawsec-clawhub-checker` Silencio `reputation_check.test.mjs` Silencio Validación de entrada y comportamiento de determinación de reputación. Silencio
## CI Workflow Coverage
Silencioso de trabajo Silencioso Silencio
Silencio.
Silencio `ci.yml` Silencio PR/push a `main` Silencio Lint/type/build, cheques de Python, escaneos de seguridad, pruebas de habilidad. Silencio
TEN `codeql.yml` TENER PR/push/schedule TEN JS/TS static security analysis. Silencio
Silencio `scorecard.yml` Silencio agenda/push Silencio Presentación de informes de posturas de cadena de suministro y carga SARIF. Silencio
confidencialidad `skill-release.yml` Etiquetas de la vida + PRs TEN Version parity and release artifact verification. Silencio
## Comandos locales de prueba
```bash
# baseline frontend + config checks
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
npm run build
```
```bash
# representative skill tests
node skills/clawsec-suite/test/feed_verification.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
## Patrones de fracaso para ver
- Los accesorios de firma/pruebas pueden fallar en el desajuste clave/pago cuando los archivos esperados se regeneran incoherentemente.
- Las pruebas de la resolución del camino fallan intencionadamente en los tokens del hogar escapados; este comportamiento es esperado y relevante para la seguridad.
- Los scripts locales que confían en los binarios `openclaw` o `clawhub` pueden fallar en entornos donde estos CLI están ausentes.
- La lógica de deplorar/renunciar puede pasar localmente mientras que falla en el CI si la firma de secretos o permisos de flujo de trabajo difieren.
## Orden de prueba sugerida
1. Ejecute `./scripts/prepare-to-push.sh` para una puerta local completa.
2. Ejecutar directamente las pruebas de habilidad local impactadas.
3. Para los cambios de alimentación/signación, ejecute primero las pruebas de verificación de suite (`feed_verification`, `guarded_install`).
4. Para cambios de flujo de trabajo o liberación, también ejecute `scripts/validate-release-links.sh` y script de consistencia clave.
## Update Notes
- 2026-02-26: Referencias de origen actualizadas a la lista de verificación `wiki/platform-verification.md` migrada.
## Referencias Fuente
- AGENTS.md
- scripts/prepare-to-push.sh
- scripts/validate-release-links.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/skill-release.yml
- habilidades/clawsec-suite/test/feed_verification.test.mjs
- habilidades/clawsec-suite/test/guarded_install.test.mjs
- habilidades/clawsec-suite/test/path_ resolution.test.mjs
- habilidades/openclaw-audit-watchdog/test/suppression_config.test.mjs
- habilidades/clawsec-clawhub-checker/test/reputation_check.test.mjs
- wiki/platform-verification.md
wiki/es/workflow.md
+87
View File
@@ -0,0 +1,87 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (es)
Source: ../workflow.md
Review status: draft
-->
# Workflow
## End-to-End Lifecycle
- El desarrollo comienza con la codificación local + la población de datos locales para una presentación realista de la interfaz de usuario.
- PR CI valida suites de calidad/seguridad y pruebas de habilidad.
- PR Pages-verify validates production build/signing behaviour without publishing.
- Paquetes de flujo de trabajo de liberación impulsados por la etiqueta y signos artifactos de habilidad.
- Páginas desplegando espejos de flujo de trabajo liberación / artefactos advisorios y publica el sitio estático.
- Wiki-sync workflow publica repo `wiki/` docs to GitHub Wiki on `main`.
- Los flujos de trabajo programados enriquecen continuamente la visibilidad de la fuente de asesoramiento y la cadena de suministro.
Mapa de flujo de trabajo primario
Silencioso de trabajo Silencioso de la lucha
Silencio.
← CI Silencio PR/push to `main` tención Lint, tipocheck, build, Python checks, security scans, skill tests. Silencio
Silencio Pages Verify TENIDO PRs a `main` ANTE Build Pages artefacto y validar salidas de firma (no publicar). Silencio
← Encuesta NVD CVEs Silencio Cron diario + despacho manual ← Fetch CVEs, transform/dedupe, feed de actualización, artefactos de firma, cambios de PR. Silencio
← Procesamiento Comunidad Asesoramiento TENIDO Etiqueta `advisory-approved` Silencio Forma de emisión Parse, crear asesoría, feed de firma, PR abierto, cuestión de comentarios. Silencio
← Skill Release Silencio Etiquetas de la habilidad + metadatos PR cambios Silencio PR: versión-paridad + cheques de funcionamiento seco; etiquetas: paquete/sign/publicar activos de liberación. Silencio
Silencio Páginas de Despliegue Silencio Exitosa CI/Libertad o envío manual Silencio Discover releases, mirror assets, sign public advisories/checksums, deployment site. Silencio
← Sincronización Wiki tención Empuja a `main` tocando `wiki/**` + despacho manual  Sync `wiki/` en `<repo>.wiki.git` y generar `Home.md` de `INDEX.md`. Silencio
## Local Operator Workflow
TEN TERRITORIO TERRITORIO ANTERIOR ANTERIOR
Silencio.
Silencio Install deps Silencio `npm install` ← Entorno local listo. Silencio
tención Populate local catalog Silencio `./scripts/populate-local-skills.sh` Silencioso `public/skills/index.json` y checksums de archivos. Silencio
Silencio Populate local feed Silencio `./scripts/populate-local-feed.sh --days 120` tención Actualizado local advisory feed copy. Silencio
¦ Generate wiki llms exports Silencio `npm run gen:wiki-llms` Silencio Actualizaciones `public/wiki/llms.txt` y exportaciones por página. Silencio
Silencio Ejecute la puerta local Silencio `./scripts/prepare-to-push.sh` TENIENDO CI-como la señal de paso/fail. Silencio
Silencio Inicio dev UI Silencio `npm run dev` Silencio Vista previa del navegador en el punto final local Vite. Silencio
## Detalles del flujo de trabajo de liberación
- La paridad de versiones y docs se aplican para las vías PR/tag.
- Embalaje de habilidad incluye archivos declarados por SBOM y manifiestos de integridad.
- `checksums.json` está firmado e inmediatamente verificado en ejecución de flujo de trabajo.
- El trabajo opcional public-to-ClawHub funciona después de la exitosa publicación GitHub cuando está configurado.
- Las versiones más antiguas dentro de la misma línea principal pueden ser superadas o eliminadas por la automatización.
## Advisory Workflow Details
- El flujo de trabajo NVD determina la ventana incremental de la alimentación anterior `updated` timetamp.
- Transformar mapas de fase CVE métricas a la gravedad/tipo y normalizar objetivos afectados.
- El flujo de trabajo de asesoramiento comunitario crea identificaciones deterministas (`CLAW-YYYY-NNNN`) de metadatos de emisión.
- Ambos flujos de trabajo de asesoramiento actualizan copias de alimentación y compañeros de firma.
## Ejemplos Snippets
```bash
# manual release prep for a skill
./scripts/release-skill.sh clawsec-feed 0.0.5
# then push tag if running in release branch mode
```
```yaml
# pages deploy depends on successful upstream workflow run
on:
workflow_run:
workflows: ["CI", "Skill Release"]
types: [completed]
```
## Operational Risks
- Los permisos de flujo de trabajo y la inconfiguración de alcance secreto pueden bloquear la firma / publicación.
- Los fallos transitorios NVD/API pueden retrasar la frescura asesora.
- Nombramiento de etiquetas inválidos o desajustes de versiones detienen la automatización de liberación.
- Los scripts locales y el CI pueden divergir si la máquina del operador carece de binarios esperados (`jq`, `openssl`, `clawhub`).
## Referencias Fuente
- scripts/release-skill.sh
- 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
wiki/fr/GENERATION.md
+42
View File
@@ -0,0 +1,42 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../GENERATION.md
Review status: draft
-->
# Wiki Generation Metadata
- Commit hash: `c3983a100581a9f27eb8cc3b5baa4f585e6c45e4`
- Branch name: `codex/clawsec-scanner-0.0.2-dast-harness`
- Generation timestamp (local): `2026-03-10T19:06:29+0200`
- Generation mode: `update`
- Output language: `English`
- Assets copied into `wiki/assets/`:
- `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
- `overview_img_02_clawsec-mascot.png` (from `public/img/mascot.png`)
- `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)
## Notes
- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
- Updated index and cross-links to use `wiki/` as the documentation source of truth.
- Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
- Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.
- 2026-04-26: Split Picoclaw self-pen-testing into dedicated `wiki/modules/picoclaw-self-pen-testing.md`, and updated `wiki/modules/picoclaw-security-guardian.md` to cover advisory/drift/supply-chain scope only.
- 2026-04-25: Added DeepWiki-friendly `wiki/modules/picoclaw-security-guardian.md` with support-matrix claims, threat model, default safety posture, frontend/advisory-board wiring, verification commands, and source references. Regenerated `public/wiki/**/llms.txt` exports with `npm run gen:wiki-llms`.
## Source References
- README.md
- package.json
- AGENTS.md
- wiki/overview.md
- wiki/architecture.md
- wiki/modules/clawsec-scanner.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- wiki/dependencies.md
- wiki/data-flow.md
- wiki/glossary.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
wiki/fr/INDEX.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../INDEX.md
Review status: draft
-->
# Wiki Index
## Summary
- Purpose: Document ClawSec as a combined web catalog, signed advisory channel, and multi-skill security distribution system.
- Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines.
- Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`.
- Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing.
- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code.
## Start Here
- [Overview](overview.md)
- [Architecture](architecture.md)
## Translations
- [Español](../es/INDEX.md)
- [한국어](../ko/INDEX.md)
## Guides
- [Localization Workflow](localization.md)
- [Dependencies](dependencies.md)
- [Data Flow](data-flow.md)
- [Configuration](configuration.md)
- [Testing](testing.md)
- [Workflow](workflow.md)
- [Security](security.md)
## Operations
- [Security Signing Runbook](security-signing-runbook.md)
- [Signed Feed Migration Plan](migration-signed-feed.md)
- [Platform Verification Checklist](platform-verification.md)
- [Cross-Platform Remediation Plan](remediation-plan.md)
## Modules
- [Frontend Web App](../modules/frontend-web.md)
- [ClawSec Suite Core](../modules/clawsec-suite.md)
- [ClawSec Scanner](../modules/clawsec-scanner.md)
- [Hermes Attestation Guardian](../modules/hermes-attestation-guardian.md)
- [Hermes Attestation Guardian Draft History (Archived)](../modules/hermes-attestation-guardian-draft-history.md)
- [NanoClaw Integration](../modules/nanoclaw-integration.md)
- [Picoclaw Security Guardian](../modules/picoclaw-security-guardian.md)
- [Picoclaw Self Pen Testing](../modules/picoclaw-self-pen-testing.md)
- [Automation and Release Pipelines](../modules/automation-release.md)
- [Local Validation and Packaging Tools](../modules/local-tooling.md)
## Glossary
- [Glossary](glossary.md)
## Generation Metadata
- [Generation Metadata](GENERATION.md)
## Update Notes
- 2026-04-26: Split Picoclaw self-pen-testing into standalone `picoclaw-self-pen-testing`; updated Picoclaw module docs and references.
- 2026-04-25: Added Picoclaw Security Guardian module for advisory awareness, config drift detection, and chain-of-supply verification.
- 2026-04-19: Moved NanoClaw platform-support and CI/CD pipeline detail sections out of `README.md` into module pages (`modules/nanoclaw-integration.md`, `modules/automation-release.md`) and left README pointers.
- 2026-04-16: Added install-guard compatibility note for Hermes Attestation Guardian (community-source install now SAFE without `--force`; behavior unchanged).
- 2026-04-15: Expanded Hermes Attestation Guardian module page into full narrative, claim-by-claim operator guidance (no claim tables), and added archived draft-history module page.
- 2026-03-10: Added ClawSec Scanner module documentation and linked it under Modules.
- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.
## Source References
- README.md
- App.tsx
- package.json
- scripts/prepare-to-push.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- skills/clawsec-suite/skill.json
- skills/clawsec-scanner/skill.json
- skills/hermes-attestation-guardian/skill.json
- skills/picoclaw-security-guardian/skill.json
- skills/picoclaw-self-pen-testing/skill.json
- wiki/modules/clawsec-scanner.md
- wiki/modules/hermes-attestation-guardian.md
- wiki/modules/hermes-attestation-guardian-draft-history.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- .github/workflows/ci.yml
wiki/fr/architecture.md
+136
View File
@@ -0,0 +1,136 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../architecture.md
Review status: draft
-->
Architecture
## Contexte du système
- Oui. Cette page apparaît dans la section `Start Here` dans `INDEX.md`.
- ClawSec se situe entre les sources d'intelligence amont (NVD + problèmes communautaires), l'automatisation GitHub, et les environnements d'agents d'exécution.
- Oui. Le dépôt publie à la fois le contenu statique du site et les artefacts signés que les compétences d'exécution vérifient avant d'utiliser.
- Groupes d'acteurs extérieurs :
- Les coureurs GitHub Actions exécutent des flux de travail de CI, release et feed.
- Les agents OpenClaw/NanoClaw consomment des compétences, des avis et des scripts de vérification.
- Les responsables du dépôt approuvent les questions d'avis et fusionnent les modifications de diffusion/d'étiquette.
Composantes
Composante Lieu Responsabilité
- Oui.
USI Web de `App.tsx`, `pages/`, `components/`. - Oui.
Voir la fiche d'information. - Oui.
Des packs de compétences `skills/*/`?Distribue des capacités de sécurité installables avec des métadonnées SBOM. - Oui.
Scripts d'automatisation locale `scripts/*.sh`=Construisez des miroirs locaux, des vérifications pré-poussières et des aides à la libération manuelle. - Oui.
IC/CD Workflows (en anglais seulement) `.github/workflows/*.yml` (en anglais seulement) Doublure, tests, sondage NVD, emballage de libération et déploiement des pages. - Oui.
Python Utility Layer (Python Utility Layer) `utils/*.py` (Python Utility Layer) Validation des métadonnées des compétences et génération de bilans. - Oui.
Oui. Flux clés
- Flux de catalogue des compétences :
1. Les workflows de publication/d'étiquetage publient les compétences.
2. Déployer workflow découvre les actifs de libération et construit `public/skills/index.json`.
3. L'interface utilisateur récupère `public/skills/index.json` et les documents de compétences pour les pages `/skills`.
- Débit d'alimentation consultatif :
1. Mise à jour `poll-nvd-cves.yml` et `community-advisory.yml` `advisories/feed.json`.
2. Les aliments pour animaux sont signés et reproduits sur les voies publiques.
3. Les hameçons/scripts d'exécution chargent le flux à distance et le retour aux copies signées locales.
- Débit d'installation surveillé:
1. Installer demande compétence cible + version.
2. Les contrôles de l'appariement consultatif ont affecté les spécifications et les indices de gravité/risque.
3. Le code de sortie 42 impose une seconde confirmation lorsque les avis correspondent.
Schémas
```mermaid
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"]
```
![Prompt Line Motif](../assets/architecture_img_01_prompt-line.svg)
## Interfaces et contrats
Formulaire de contrat de validation
- Oui.
Validé par l'utilitaire Python + vérification de la parité des versions CI. - Oui.
JSON + Ed25519 signature détachée. - Oui.
Voir le manifeste des contrôles. - Oui.
- Oui. Interface d'événement hook : `HookEvent` (`type`, `action`, `messages`) ► Le gestionnaire d'événements ne traite que les noms d'événement sélectionnés. - Oui.
Motif d'étiquettes `<skill>-vX.Y.Z`.Parsed in release/deploy workflows to discover competences. - Oui.
Oui. Paramètres clés
Paramètre par défaut Effet
- Oui.
`CLAWSEC_FEED_URL`= `https://clawsec.prompt.security/advisories/feed.json`= Source d'avis à distance pour les scripts/hooks de suite. - Oui.
`CLAWSEC_ALLOW_UNSIGNED_FEED`=2 `0`=2 Permet une compatibilité temporaire non signée. - Oui.
`CLAWSEC_VERIFY_CHECKSUM_MANIFEST`.`1`.U. Nécessite une vérification de manifeste de somme de contrôle lorsque disponible. - Oui.
`CLAWSEC_HOOK_INTERVAL_SECONDS`.`300`.Scanner la fenêtre de griffage pour le crochet de conseil. - Oui.
`CLAWSEC_SKILLS_INDEX_TIMEOUT_MS`.`5000`= Indice de compétence à distance récupérer le temps de sortie pour la découverte du catalogue. - Oui.
`PROMPTSEC_GIT_PULL`.`0` en option avant les audits de chien de garde. - Oui.
## Gestion des erreurs et fiabilité
- La récupération du flux est fermée par défaut pour les signatures invalides et les manifestes malformés.
- Remote récupérer les échecs gracieusement revenir aux flux signés locaux.
- Hook state utilise le fichier atomique écrit en mode strict où supporté.
- Les pages d'interface utilisateur détectent les replis HTML utilisés comme JSON et évitent de rendre les données corrompues.
- Les étapes de flux de travail font en sorte que l'empreinte des clés soit cohérente pour éviter la dérive des clés fractionnées.
## Exemples d'extraits
```tsx
// 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>
```
```ts
// Guarded feed loading contract in advisory hook
const remoteFeed = await loadRemoteFeed(feedUrl, {
signatureUrl: feedSignatureUrl,
checksumsUrl: feedChecksumsUrl,
checksumsSignatureUrl: feedChecksumsSignatureUrl,
publicKeyPem,
checksumsPublicKeyPem: publicKeyPem,
allowUnsigned,
verifyChecksumManifest,
});
```
Temps d'exécution et déploiement
Modèle d'exécution
- Oui.
Variez l'application (`npm run dev`) - Oui.
Matrice multi-OS + emplois dédiés. - Oui.
- Oui. Workflow de sortie de compétences ► Publication guidée par l'étiquette + Vérifications de sortie à sec de la RP. - Oui.
- Oui. Déploiement des pages Déclenchement par CI/Succcès de la libération. - Oui.
IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IPC IG IPC IPC IPC IPC IPC IPC IPC IPC IPC , IPC IPC , IPC STAT STAT STAT STAT STAT STAT STAT - Oui.
Remarques supplémentaires
- Échelles de volume de consultation avec mot-clé fixé dans le sondage NVD; bruit de dédoublement et de contrôle post-filtrage.
- Déployer les processus de flux de travail publie des listes et conserve les nouvelles versions de compétences dans la sortie index.
- Les limites des modules par dossier de compétences permettent d'ajouter de nouvelles capacités de sécurité sans changer la structure de frontend.
- Les voies de vérification des signatures restent légères car les tailles de charge utile (feed/manifestes) sont petites.
Références sources
- App.tsx
- pages / SkillsCatalog.tsx
- pages/FeedSetup.tsx
- pages/conseilDétail.tsx
- pages/WikiBrowser.tsx
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/clawsec-suite/scripts/discover_skill_catalog.mjs
- compétences/clawsec-nanoclaw/lib/advisories.ts
- compétences/clawsec-nanoclaw/lib/signatures.ts
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/kill-release.yml
wiki/fr/configuration.md
+93
View File
@@ -0,0 +1,93 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../configuration.md
Review status: draft
-->
Configuration #
Portée
- La configuration couvre les paramètres de construction frontend, les chemins de flux d'exécution, les déclencheurs de workflow et les contrats de métadonnées de compétences.
- La plupart des commandes sensibles à l'exécution sont des variables d'environnement préfixées avec `CLAWSEC_` ou `OPENCLAW_`.
- La normalisation du chemin est sensible à la sécurité et rejette intentionnellement les littérales non résolues.
## Variables d'exécution du noyau
Variable par défaut
- Oui.
`CLAWSEC_FEED_URL`.Hosted advisory URL.Hosted Suite hook and garded installator feed loading. - Oui.
`CLAWSEC_FEED_SIG_URL`= `<feed>.sig`= Source de signature séparée. - Oui.
`CLAWSEC_FEED_CHECKSUMS_URL`= `checksums.json` près de l'URL du flux. - Oui.
`CLAWSEC_FEED_PUBLIC_KEY`. - Oui.
`CLAWSEC_ALLOW_UNSIGNED_FEED`= `0`=Flag de contournement de migration temporaire. - Oui.
`CLAWSEC_VERIFY_CHECKSUM_MANIFEST`= `1`=Active la vérification du manifeste de contrôle. - Oui.
`CLAWSEC_HOOK_INTERVAL_SECONDS`= `300`=L'accélérateur de balayage du crochet. - Oui.
Règles de résolution du chemin
Règle du comportement Lieu d'exécution
- Oui.
Expansion `~` Résolue au répertoire d'origine détecté. - Oui.
`$HOME` / `${HOME}` expansion Resolved when unscaped. - Oui.
- Oui. Jetons d'accueil de Windows: `%USERPROFILE%`, `$env:USERPROFILE` normalisé. - Oui.
Les jetons échappés (`\$HOME`) sont rejetés par erreur explicite. - Oui.
Un chemin explicite non valide peut revenir au chemin par défaut avec un avertissement. - Oui.
Configuration de frontend et de build
- `vite.config.ts` définit le port (`3000`), l'hôte (`0.0.0.0`) et l'alias de chemin (`@`).
- `index.html` fournit Tailwind runtime config, polices personnalisées et jetons de couleur de base.
- `tsconfig.json` utilise la résolution de module de groupeur, `noEmit` et la configuration d'exécution JSX.
- `eslint.config.js` applique les règles TS, React, Hooks et les règles de linte spécifiques au script.
## Métadonnées sur les compétences Configuration
Groupe de champ Lieu Fonction
- Oui.
- Oui. Identité de la compétence de base: `skills/*/skill.json`. - Oui.
La liste des fichiers SBOM de `skill.json -> sbom.files` declare les artefacts requis pour la libération. - Oui.
Les métadonnées de la plate-forme sont des blocs `openclaw` ou `nanoclaw`. - Oui.
Suite catalog metatalogs. - Oui.
Configuration du flux de travail
- La configuration du programme existe dans les entrées `cron` (`poll-nvd-cves`, `codeql`, `scorecard`).
- Release workflow s'attend à la désignation de tag pattern `<skill>-v<semver>`.
- Le flux de travail de déploiement est déclenché par les événements CI/release `workflow_run` et l'expédition manuelle.
- La signature composite nécessite des entrées de clé privée et vérifie les signatures immédiatement après la signature.
## Exemples d'extraits
```bash
# run guarded install with explicit local signed feed paths
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```
```json
{
"name": "example-skill",
"version": "1.2.3",
"sbom": {
"files": [
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
]
}
}
```
Notes opérationnelles
- Continuez à signer les clés en dehors du dépôt et injectez uniquement via GitHub Secrets.
- Préférez les chemins absolus ou les expressions de la maison non-sacrées dans les variables d'environnement local.
- Traiter le mode d'alimentation non signé comme un support temporaire de migration, et non comme un fonctionnement normal.
- Relancer la validation des liens de sortie lors de l'édition des URL `SKILL.md` pour éviter les références d'artefact cassées.
Références sources
- rite.config.ts
- index.html
- tsconfig.json
- eslint.config.js
- compétences/clawsec-suite/skill.json
- compétences/clawsec-nanoclaw/skill.json
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs
- compétences/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- scripts/validate-release-links.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/kill-release.yml
- .github/actions/sign-and-vérify/action.yml
wiki/fr/data-flow.md
+105
View File
@@ -0,0 +1,105 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../data-flow.md
Review status: draft
-->
# Flux de données
> Contexte produit: ClawSec
Flux primaires
- `Advisory ingestion`: Les entrées NVD/community sont transformées en un flux de consultation normalisé, signé, puis miroir pour les clients.
- `Skill catalog publication`: les actifs de libération sont découverts et convertis en `public/skills/index.json` plus les documents/chèques par compétence.
- `Runtime enforcement`: les consommateurs de suites et nanoclaw chargent des données consultatives, se joignent aux compétences et émettent des alertes ou des portes de confirmation.
- Oui. Cette page apparaît dans la section `Guides` dans `INDEX.md`.
Pas à pas
1. Le workflow/script du producteur d'alimentation récupère les données sources (`NVD API` ou charge utile d'émission).
2. La logique de transformation de JSON normalise les champs de gravité/type/affectés et les doublons par ID-conseil.
3. Les étapes Signature/Checksum génèrent des signatures séparées et des manifestes de checksum.
4. Déployer des miroirs de flux de travail signés artefacts sous `public/` et `public/releases/latest/download/`.
5. Les consommateurs d'interface utilisateur valident la forme/le contenu de JSON; les consommateurs d'exécution vérifient en outre les signatures/chèques avant de faire confiance aux données d'alimentation.
6. Les correspondants comparent les spécifications `affected` aux noms de compétences/versions et émettent des alertes ou forcent la confirmation.
## Entrées et sorties
Les entrées/sorties sont résumées dans le tableau ci-dessous.
Type de type Nom Lieu Description
* * * * * * * * * *
En entrée CVE charge utile. - Oui.
Contribution Question de consultation communautaire Question de consultation `.github/workflows/community-advisory.yml` charge utile événementaire Question approuvée par le mainteneur transformée en dossier de consultation. - Oui.
Entraits de compétences Release actifs de compétences de GitHub Releases API + actifs de compétences Utilisé pour construire le catalogue Web et les téléchargements miroirs. - Oui.
Introduire Config./env. Local `OPENCLAW_AUDIT_CONFIG`, `CLAWSEC_*` vars. - Oui.
SortieSupport consultatifSupport de dépôt canonique. - Oui.
SortieSignature consultativeSignature indépendante pour l'authenticité des aliments. - Oui.
Output (en anglais seulement) Index du catalogue des compétences (en anglais seulement) `public/skills/index.json` (en anglais seulement) Catalogue Web d'exécution utilisé par les pages `/skills`. - Oui.
Sortie Release checksums/signatures Release manifeste for release consumers. - Oui.
Sortie de la commande État de crochet de la commande `~/.openclaw/clawsec-suite-feed-state.json`. - Oui.
Oui. Structures de données
Structure des champs clés
- Oui.
Uniquement pour les données de risque utilisées par l'UI et les installateurs. - Oui.
Enregistrez vos métadonnées de compétences. - Oui.
Voir le manifeste des contrôles. - Oui.
L'état consultatif (`known_advisories`, `last_hook_scan`, `notified_matches`) prévient les alertes répétées et les balayages des gaz. - Oui.
Suppression de la confiscation de `enabledFor[]`, `suppressions[]`. - Oui.
Schémas
```mermaid
flowchart LR
A["NVD + Issue Inputs"] --> B["Transform + Deduplicate"]
B --> C["advisories/feed.json"]
C --> D["Sign + checksums"]
D --> E["public/advisories + releases/latest"]
E --> F["Web UI fetch"]
E --> G["Suite/NanoClaw verification"]
G --> H["Match skills + emit alerts/gates"]
```
État et stockage
Magasin d'écriture
- Oui.
Remarques canoniques: `advisories/` , NVD + workflows communautaires et script popularisé local. - Oui.
- Oui. Copies-conseils intégrées : `skills/clawsec-feed/advisories/` et `skills/clawsec-suite/advisories/`. - Oui.
Rétroviseurs publics (`public/advisories/`, `public/releases/`) Déployer le workflow. - Oui.
L'état d'exécution `~/.openclaw/clawsec-suite-feed-state.json`=La persistance de l'état d'hameçon consultatif. - Oui.
NanoClaw cache. - Oui.
L'état d'intégrité de `/workspace/project/data/soul-guardian/` (NanoClaw) - Oui.
## Exemples d'extraits
```bash
# Local feed flow (NVD fetch -> transform -> sync)
./scripts/populate-local-feed.sh --days 120
jq '.updated, (.advisories | length)' advisories/feed.json
```
```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Modes d'échec
- Les limites de débit NVD (`403/429`) peuvent retarder le rafraîchissement de l'alimentation et nécessiter des retraits/retraits.
- Les signatures détachées manquantes ou non valides provoquent le rejet du flux en mode fermé.
- Les réponses HTML pour les paramètres JSON peuvent produire de faux positifs sauf si elles sont filtrées explicitement.
- L'erreur de configuration (`\$HOME`) peut briser la résolution locale du chemin de repli.
- Les empreintes de clés publiques décomposées dans les flux de travail déclenchent une défaillance de l'IC.
Références sources
- avis/feed.json
- avis/feed.json.sig
- scripts/popular-local-feed.sh
- scripts/popular-local-skills.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/kill-release.yml
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/state.ts
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/matching.ts
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/clawsec-nanoclaw/lib/advisories.ts
- compétences/clawsec-nanoclaw/host-services/advisory-cache.ts
wiki/fr/dependencies.md
+106
View File
@@ -0,0 +1,106 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../dependencies.md
Review status: draft
-->
Dépendances
## Construire et exécuter
Pourquoi il existe des dépendances primaires
- Oui.
Frontend runtime. - Oui.
Le rendu de Markdown est rendu par `react-markdown`, `remark-gfm`. - Oui.
Construisez l'outillage d'outillage d'outillage d'outillage d'outillage d'outillages `vite`, `@vitejs/plugin-react`, `typescript`. - Oui.
Utilitaires Python : stdlib + `ruff`/`bandit` politique de `pyproject.toml`. - Oui.
- Oui. Automatisation de la coquille: - Oui.
Détails de la dépendance
Version Contraintes Portée
- Oui.
`react` / `react-dom`
`react-router-dom`
Jeu d'icônes de l'interface utilisateur `lucide-react`
`vite`
`typescript`
`eslint`
`@typescript-eslint/*`= `^8.55.0` / `^8.56.0`= TS analyseur de lint/règles=
`fast-check`
Dépassement Version épinglée Justification
- Oui.
`ajv`.`6.14.0`.Sécurité et stabilisation de la compatibilité. - Oui.
`balanced-match`.`4.0.3`. - Oui.
`brace-expansion`.`5.0.2`. - Oui.
`minimatch`.`10.2.1`. - Oui.
Services externes
Service utilisé par fonction
- Oui.
API NVD (`services.nvd.nist.gov`) (`poll-nvd-cves` workflow + script de flux local) Tirez les CVE par la fenêtre mot-clé/date. - Oui.
API GitHub Déployer/release workflows Découvrez les versions, les actifs de téléchargement, les sorties de publication. - Oui.
GitHub Pages Déploiement Déploiement Service statique et artefacts miroirs. - Oui.
Installer des scripts + des emplois de publication optionnels Installer et publier des compétences. - Oui.
En option, SMTP/sendmail local. - Oui.
## Outils de développement
Couverture de l'Invocation
- Oui.
ESLint: `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0`. - Oui.
TypeScript (en anglais seulement) `npx tsc --noEmit` (en anglais seulement). - Oui.
Le style Python et les contrôles de patrons de bugs. - Oui.
Bandit: `bandit -r utils/ -ll` , Vérifications de sécurité Python. - Oui.
Trivy: flux de travail + exécution locale optionnelle. - Oui.
Gitleaks (en option) `scripts/prepare-to-push.sh` (en option) - Oui.
## Exemples d'extraits
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.4",
"react-router-dom": "^7.13.1"
}
}
```
```toml
[tool.ruff]
target-version = "py310"
line-length = 120
[tool.bandit]
exclude_dirs = ["__pycache__", ".venv"]
skips = ["B101"]
```
## Notes de compatibilité
- Les scripts locaux rendent compte des différences entre macOS et Linux dans l'utilisation de `date` et `stat`.
- Certains workflows/scripts nécessitent des fonctionnalités OpenSSL utilisées avec Ed25519 et `pkeyutl -rawin`.
- La prise en charge de Windows est la plus forte pour l'outillage basé sur les nœuds; les chemins shell POSIX peuvent nécessiter WSL/Git Bash.
- Les consommateurs d'aliments pour animaux incluent les contournements de compatibilité pour les phases de migration, mais le mode signé est l'état stable prévu.
Remarques de version
- Les étiquettes de sortie des compétences suivent `<skill>-v<semver>` et sont analysées par l'automatisation CI/déploiement.
- La validation PR impose la parité de version entre `skill.json` et `SKILL.md` pour les compétences en bosse.
- Oui. L'indice des compétences publiques conserve la dernière version découverte par compétence pour l'affichage de l'interface utilisateur.
- Les manifestes d'artefacts signés (`checksums.json`) sont mis en version par version et comprennent des hashes de fichiers et des URL.
Références sources
- paquet.json
- paquet-lock.json
- pyproject.toml
- eslint.config.js
- tsconfig.json
- scripts/prepare-to-poush.sh
- scripts/popular-local-feed.sh
- scripts/popular-local-skills.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/kill-release.yml
wiki/fr/exploitability-scoring.md
+425
View File
@@ -0,0 +1,425 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../exploitability-scoring.md
Review status: draft
-->
# Méthode de notation de l'exploitation
## Aperçu
Le système de notation d'exploitabilité de ClawSec fournit une évaluation de vulnérabilité contextuelle spécialement conçue pour les déploiements d'agents d'IA (OpenClaw/NanoClaw). Contrairement aux scores CVSS génériques qui traitent tous les environnements de façon égale, notre notation tient compte de la surface d'attaque unique et des modèles d'utilisation des agents d'IA pour réduire la fatigue alerte et prioriser les menaces actionnables.
Niveau de notation
Niveau de gravité Signification
- Oui.
`high`=Critical/High=Exploitable dans les déploiements d'agents typiques, attention immédiate requise=
`medium`= Moyenne Peut être exploitable selon la configuration, justifie enquête
`low`L'exploitation limitée dans le contexte des agents, faible priorité
`unknown` Inconnu Données insuffisantes pour évaluer l'exploitabilité
Facteurs de cotation
- Oui. 1. Score de base du CVSS (base)
L'analyse commence par le score de base du CVSS comme fondement :
- **CVSS ≥ 9.0**: Gravité critique → score initial `high`
- **CVSS 7.0-8,9**: Haute sévérité → score initial `high`
- **CVSS 4.0-6.9**: sévérité moyenne → score initial `medium`
- **CVSS 1.0-3.9**: Faible sévérité → score initial `low`
- **Pas de CVSS**: → score initial `unknown`
- Oui. 2. Analyse vectorielle d ' attaque (Métrique CVSS)
L'analyseur analyse les vecteurs CVSS v2, v3.0 et v3.1 pour évaluer:
Accessibilité du réseau
- **AV:N** (Réseau): Téléexploitable sur réseau
- **AV:A** (Adjoint): Nécessite un accès au réseau local
- **AV:L** (local): Nécessite un accès au système local
- **AV:P** (Physique): Nécessite un accès physique
**Impact sur les agents**: Les vulnérabilités accessibles au réseau sont élevées parce que les agents fonctionnent généralement comme des services de réseau ou font des appels d'API externes.
Exigences en matière d'authentification
- **PR:N / Au:NONE**: Aucune authentification requise → élève le score
- **PR:L / Au:SINGLE**: Faibles privilèges requis
- **PR:H / Au:MULTIPLE**: Les privilèges élevés requis → réduit le score
**Impact sur les agents**: Les exploits non authentifiés sont essentiels pour les API d'agents publics.
L'interaction utilisateur
- **UI:N**: Aucune interaction utilisateur requise → élève le score
- **UI:R**: Nécessite une interaction utilisateur → réduit le score
**Impact sur les agents**: Les agents fonctionnent souvent de manière autonome, de sorte que les vulnérabilités nécessitant une interaction utilisateur sont moins critiques.
Complexe d'attaque
- **AC:L**: Faible complexité → élève le score
- **AC:M / AC:H**: complexité moyenne/haute → neutre ou réduit le score
**Impact sur les agents**: Les exploits à faible complexité sont plus susceptibles d'être automatisés et utilisés dans les attaques de masse.
- Oui. 3. Type de vulnérabilité (contexte du détachement)
ClawSec ajuste les scores en fonction de la façon dont les types de vulnérabilité affectent les déploiements d'agents d'IA :
Types à risque élevé dans le contexte de l'agent
**Exécution de code à distance (RCE)* *
```
Score: Always HIGH
Rationale: RCE is critical in agent deployments
```
Les agents d'IA exécutent le code arbitraire dans le cadre de leur fonction. Les vulnérabilités RCE permettent aux attaquants de détourner le flux d'exécution des agents, d'exfiltrer les identifiants ou de pivoter vers d'autres systèmes.
**Forgerie de demande à l'aide d'un serveur* *
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: SSRF affects agents making external requests
```
Les agents appellent souvent des API externes, accèdent aux services internes et récupèrent des ressources à distance. SSRF permet aux attaquants :
- Accès aux services de métadonnées cloud internes (AWS IMDSv1, métadonnées GCP)
- Pivot vers les réseaux internes
- Exfiltrer les données par tunnel DNS
**Path Traversal / Directory Traversal* *
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: Path traversal affects agents with file access
```
Les agents lisent les fichiers, exécutent des scripts et gèrent les bases de code. Le parcours permet :
- Lecture de fichiers de configuration sensibles (.env, identifiants)
- Accès aux clés SSH, jetons API
- Suppression des fichiers système critiques
**Injection de commande**
```
Score: Always HIGH
Rationale: Command injection is critical in agent deployments
```
Comme RCE, les agents exécutent souvent des commandes shell pour interagir avec les systèmes. L'injection de commande permet un compromis complet du système.
Types à risque moyen
**Prototype Pollution (Node.js)* *
```
Score: Elevated from LOW to MEDIUM
Rationale: Prototype pollution can escalate in Node.js agents
```
De nombreux cadres d'agents fonctionnent sur Node.js. La pollution par prototype peut conduire à:
- Dépassement des contrôles d'authentification
- L'escalade des privilèges
- Refus de service
**Injection SQL / Injection NoSQL**
```
Score: Elevated to HIGH if network-accessible and unauthenticated
Rationale: Injection affects agents with database access
```
Les agents qui stockent l'historique de conversation, les données utilisateur ou les résultats d'outils dans les bases de données sont vulnérables aux attaques par injection.
Types de risques inférieurs
** Scénario du site (XSS)* *
```
Score: Reduced to MEDIUM if not network-accessible
Rationale: XSS has limited impact in headless agents
```
Les agents ne rendent généralement pas HTML dans les navigateurs, réduisant l'impact XSS. Cependant, XSS dans les interfaces de gestion d'agents ou de chat reste une préoccupation.
- Oui. 4. Exploiter la disponibilité
Lorsque `--check-exploits` est activé, l'analyseur vérifie les URL de référence pour les exploits publics:
** Indicateurs d'exploitation :**
- exploit-db.com / exploit-database.com
- packetstormsecurity.com
- github.com/exploitation, github.com/poc
- modules-cadres métasploit
- URL contenant "/exploiter", "/poc", "/proof-of-concept"
** Augmentation de la note :**
- `low` → `medium` (exploitation disponible)
- `medium` → `high` (exploitation disponible)
- `unknown` → `medium` (exploitation disponible + CVSS > 0)
**Rationale**: Le public exploite moins la barrière des compétences pour les attaquants et augmente la probabilité d'exploitation automatisée.
L'algorithme de notation
L ' analyseur suit cet arbre de décision:
```
1. Parse CVSS score → set baseline (high/medium/low/unknown)
2. Parse CVSS vector → analyze attack characteristics
3. Adjust for attack vector:
- Network-accessible + no auth + no UI → elevate to HIGH
- Local-only access → reduce HIGH to MEDIUM
4. Adjust for vulnerability type:
- Check against agent-specific risk categories
- Elevate or reduce score based on deployment context
5. Check for public exploits (if enabled):
- Elevate score if exploits detected
6. Generate rationale explaining the final score
```
## Exemples
Exemple 1 : risque critique (haute exploitation)
```json
{
"cve_id": "CVE-2024-12345",
"cvss_score": 9.8,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"type": "remote_code_execution",
"description": "Unauthenticated RCE in Express.js framework"
}
```
**Produit d'analyse:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments"
}
```
**Pourquoi HAUT**: CVSS critique + accès réseau + pas d'auth + type RCE.
### Exemple 2 : SSRF dans l'API d'agent (haute exploitation)
```json
{
"cve_id": "CVE-2024-23456",
"cvss_score": 7.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:L",
"type": "server_side_request_forgery",
"description": "SSRF in webhook handler allows internal network access"
}
```
**Produit d'analyse:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "High CVSS score (7.3); remotely exploitable without authentication; SSRF affects agents making external requests"
}
```
**Pourquoi HAUT**: SSRF est critique pour les agents qui font des appels API (la plupart font). Accès réseau sans authentification élève le risque.
### Exemple 3 : Chemin transversal avec exploitation publique (haute exploitation)
```json
{
"cve_id": "CVE-2024-34567",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"type": "path_traversal",
"references": [
"https://exploit-db.com/exploits/51234",
"https://nvd.nist.gov/vuln/detail/CVE-2024-34567"
]
}
```
**Produit d'analyse (avec --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (6.5); network accessible; path traversal affects agents with file access; public exploit available (1 source)"
}
```
**Pourquoi HIGH**: L'accès au fichier de transit + agent + l'exploitation publique élève le CVSS moyen à une grande exploitabilité.
Exemple 4 : XSS dans l'assurance-chômage des agents (Exploitation moyenne)
```json
{
"cve_id": "CVE-2024-45678",
"cvss_score": 7.1,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:L",
"type": "cross_site_scripting",
"description": "Stored XSS in agent management dashboard"
}
```
**Produit d'analyse:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (7.1); network accessible; XSS has limited impact in headless agents"
}
```
**Pourquoi MEDIUM** : Malgré un CVSS élevé, XSS est moins critique dans les déploiements d'agents (opération sans tête). Nécessite une interaction utilisateur.
Exemple 5 : Escalation des privilèges locaux (Exploitation moyenne)
```json
{
"cve_id": "CVE-2024-56789",
"cvss_score": 8.8,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
"type": "privilege_escalation",
"description": "Local privilege escalation via symbolic link attack"
}
```
**Produit d'analyse:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (8.8); requires local access"
}
```
**Pourquoi MEDIUM**: Malgré un CVSS élevé, nécessite un accès local. Les agents fonctionnent généralement dans des environnements containerizzato/sandbox où l'escalade locale a un impact limité.
Exemple 6 : Prototype de pollution par exploitation (haute exploitation)
```json
{
"cve_id": "CVE-2024-67890",
"cvss_score": 5.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N",
"type": "prototype_pollution",
"description": "Prototype pollution in lodash merge function",
"references": [
"https://github.com/exploit/prototype-pollution-poc",
"https://snyk.io/vuln/SNYK-JS-LODASH-1234567"
]
}
```
**Produit d'analyse (avec --check-exploits):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (5.3); remotely exploitable without authentication; prototype pollution can escalate in Node.js agents; public exploit available (1 source)"
}
```
**Pourquoi HAUT** : Prototype pollution dans les agents Node.js + exploitation publique + accès réseau sans auth = risque élevé malgré un CVSS modéré.
## Utilisation dans les flux de travail ClawSec
### Note automatique (Feed NVD)
Le workflow `poll-nvd-cves.yml` marque automatiquement de nouveaux CVE :
```bash
# Workflow step
python utils/analyze_exploitability.py --json --check-exploits < cve-data.json
```
Les avis en `advisories/feed.json` peuvent inclure:
```json
{
"id": "CVE-2024-12345",
"severity": "high",
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments",
"attack_vector_analysis": {
"is_network_accessible": true,
"requires_authentication": false,
"requires_user_interaction": false,
"complexity": "low"
}
}
```
Analyse manuelle
Les chercheurs en sécurité peuvent analyser manuellement les CVE :
```bash
# Basic analysis
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"type":"ssrf"}' | \
python utils/analyze_exploitability.py --json
# With exploit detection
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"references":["https://exploit-db.com/exploits/51234"]}' | \
python utils/analyze_exploitability.py --json --check-exploits
```
Filtrage par Exploitation
Les utilisateurs peuvent filtrer les avis par un score d'exploitation :
```bash
# Get only high-exploitability advisories
curl -s https://clawsec.prompt.security/feed.json | \
jq '.advisories[] | select(.exploitability_score == "high")'
# Prioritize by exploitability and severity
curl -s https://clawsec.prompt.security/feed.json | \
jq '[.advisories[] | select(.exploitability_score == "high" and .severity == "critical")] | sort_by(.cvss_score) | reverse'
```
## Remplissage des avis existants (entretien historique)
`scripts/backfill-exploitability.sh` est conservé comme utilitaire de maintenance historique pour la maintenance unique du dépôt.
Ce n'est pas la voie principale pour la génération de conseils normaux.
Voies préférées:
1. Chemin canonique IC : exécutez le workflow NVD avec init/reset pour reconstruire les avis de NVD et signez les artefacts en pipeline.
2. Chemin du développeur local : exécutez `./scripts/populate-local-feed.sh --force` pour repeupler les flux locaux avec un contexte d'exploitation.
N'utilisez le remblayage que lorsqu'il répare explicitement le contenu de flux qui existe déjà en repo.
Contributions communautaires
Les membres de la communauté peuvent soumettre des évaluations de l'exploitabilité:
1. **Rapport via GitHub Question**: Utilisez le modèle de conseil pour signaler les CVE avec contexte d'exploitation
2. **Analyse automatisée**: Le workflow `community-advisory.yml` obtient automatiquement des CVE déclarés par la communauté
3. **Examen manuel**: Les responsables examinent et approuvent les évaluations de l'exploitabilité
4. **Mise à jour**: Les avis approuvés sont ajoutés au flux avec des scores d'exploitation
## Limites et travaux futurs
Limites actuelles
1. **Analyse statique**: La notation est basée sur les métadonnées CVE et non sur l'analyse dynamique de l'exécution
2. **Pas de détection de version**: Ne vérifie pas si des versions spécifiques sont vulnérables
3. **Classification des prix**: Ne considère pas les atténuations partielles ou la défense en profondeur
4. **Contexte limité**: Ne connaît pas la configuration exacte de l'agent ou les outils déployés
Améliorations futures
1. ** Intégration EPSS**: Incorporer les cotes de probabilité EPSS (Exploit Prediction Score System)
2. ** Correspondance de KEV** : référence croisée avec le catalogue CISA KEV (Vulnérabilités exploitées)
3. **Profilage d'agents**: Considérer les capacités d'agents déployés et les API exposées
4. **Détection d'atténuation**: Vérifiez les règles WAF, le bac à sable ou d'autres contrôles compensateurs
5. **Score basé sur le LM**: Utiliser l'apprentissage automatique pour prédire l'exploitation à partir de données historiques
Références
- **CVSS v3.1 Spécification**: [https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document)
- **CVSS v2 Guide**: [https://www.first.org/cvss/v2/guide](https://www.first.org/cvss/v2/guide)
- **EPSS**: [https://www.first.org/epss/](https://www.first.org/epss/)
- **CISA KEV**: [https://www.cisa.gov/known-exploited-vulnerabilities-catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- ** API NVD**: [https://nvd.nist.gov/developers/vulnerabilities](https://nvd.nist.gov/developers/vulnerabilities)
Oui. Contribution
Pour améliorer la méthodologie de notation de l'exploitation :
1. **Soumettre les cas d'essai**: Ajouter les cas d'essai à `utils/analyze_exploitability.py`
2. **Reporter de faux positifs/négatifs**: Ouvrir les problèmes GitHub avec des exemples CVE
3. **Proposition d'ajustements de notation**: Soumettre des PR avec justification et exemples
4. **Contexte de l'agent de partage**: Contribuer les profils de vulnérabilité propres à l'agent
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
---
**Entretenu par**: [Prompt Security](https://prompt.security)
**License**: AGPL-3,0-ou plus tard
**Dernière mise à jour**: 2026-03-01
wiki/fr/glossary.md
+62
View File
@@ -0,0 +1,62 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../glossary.md
Review status: draft
-->
♪ Glossaire
Termes
Définition
- Oui.
Le document JSON (`feed.json`) contenant des avis de sécurité pour les compétences/plateformes. - Oui.
Specificateur affecté Obtenir un sélecteur de compétences tel que `skill@1.2.3`, wildcard ou gamme utilisé dans la logique correspondante. - Oui.
Installation surveillée Installation en deux étapes qui nécessite une confirmation explicite lorsque les avis correspondent. - Oui.
Dossiers SBOM Liste des artefacts déclarés dans `skill.json` utilisés pour l'emballage et la validation. - Oui.
Signature détachée (`.sig`) stockée séparément de la charge utile signée. - Oui.
Voir la carte de hachage du fichier (`checksums.json`) utilisée pour vérifier l'intégrité de la charge utile. - Oui.
## Conditions d'emballage des compétences
Définition
- Oui.
Catégorie de compétences Git tag formaté en `<skill>-v<semver>` utilisé par l'automatisation de la libération. - Oui.
Release Assets (en anglais seulement) Fichiers attachés à la version GitHub (zip, `skill.json`, checksums, signatures). - Oui.
Index du catalogue , liste générée consommée par le catalogue web. - Oui.
Composantes embarquées Ensemble de capacités d'une compétence incluse dans une autre (par exemple, alimentation intégrée dans la suite). - Oui.
## Avis et conditions de sécurité
Définition
- Oui.
Vérification clôturée par échec. - Oui.
Mode de compatibilité non signé. - Oui.
Règle de répression ─ Entrée config correspondant à `checkId` et `skill` pour supprimer les constatations connues/acceptées. - Oui.
Digest SHA-256 de clé publique encodée DER utilisée pour les contrôles de cohérence des clés. - Oui.
## Termes d'exécution et de plate-forme
Définition
- Oui.
OpenClaw Hook (`clawsec-advisory-guardian`) qui vérifie les avis. - Oui.
NanoClaw IPC= Échange de tâches d'hôte/conteneur pour la mise à jour des conseils, la vérification de la signature, les vérifications d'intégrité. - Oui.
L'intégrité Base de données L'enregistrement des hashes/snapshots approuvés pour les fichiers protégés. - Oui.
Registre de vérification à la suite d'une enquête Ajouter seulement le journal de vérification où chaque entrée dépend du hash antérieur. - Oui.
## Conditions CI/CD
Définition
- Oui.
Poll NVD CVEs Workflow (en anglais seulement) Workflow programmé qui récupère et transforme les CVE NVD en avis. - Oui.
Déroulement du travail d'avis de la collectivité Obtenir un document d'information qui publie les avis approuvés de la collectivité. - Oui.
Release Workflow (en anglais seulement) Emballage/signation/publishing pipeline pour les compétences. - Oui.
Déploiement des pages Flux de travail Flux de travail qui construit les actifs du site et les miroirs rejets/artefacts consultatifs. - Oui.
Références sources
- types.ts
- compétences/clawsec-suite/skill.json
- compétences/clawsec-nanoclaw/skill.json
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- compétences/clawec-suite/hooks/clawec-advisory-guardian/lib/suppression.mjs
- compétences/clawsec-nanoclaw/guardian/integrity-monitor.ts
- scripts/popular-local-feed.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/kill-release.yml
- .github/workflows/deploy-pages.yml
wiki/fr/localization.md
+71
View File
@@ -0,0 +1,71 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../localization.md
Review status: draft
-->
# Flux de travail de localisation
Objet
Définir un pipeline de localisation des docs répétables pour les pages de ClawSec README et wiki.
Portée
- Langue source: anglais (`README.md`, `wiki/*.md`)
- Langue traduite actuelle: espagnol (`README.es.md`, `wiki/es/*.md`)
- Langue pilote coréenne: coréen (`README.ko.md`, `wiki/ko/*.md`)
- Langues futures: `wiki/<lang>/...` et `README.<lang>.md`
Source des règles de vérité
1. Les fichiers anglais sont canoniques.
2. Les traductions doivent préserver les commandes, les chemins de fichiers, les blocs de code et les identifiants exactement.
3. Les noms de produits et les noms de compétences restent non traduits (`ClawSec`, `OpenClaw`, `NanoClaw`, `Hermes`, `Picoclaw`, noms de paquets de compétences).
4. Lorsque la couverture de traduction est partielle, les fichiers traduits doivent indiquer explicitement la portée.
## Dossier Conventions
- Traductions README :
- `README.es.md`
- Futur: `README.fr.md`, `README.de.md`, `README.ja.md`, etc.
- Traductions Wiki :
- `wiki/es/INDEX.md`
- `wiki/es/<page>.md`
- Avenir: `wiki/fr/<page>.md`, `wiki/de/<page>.md`, etc.
- Actifs de localisation :
- `wiki/i18n/terminology-en-es.md`
- `wiki/i18n/translation-tracker.md`
## Mettre à jour le flux de travail
1. **Normaliser les documents sources d'abord* *
- Mettre à jour les documents source en anglais pour plus de clarté et de structure avant la traduction.
2. **Enregistrement delta**
- Note modifiée pages en anglais dans `wiki/i18n/translation-tracker.md`.
3. **Translate changed pages**
- Préserver la structure de balisage et les niveaux de cap.
- Gardez les blocs de commande intacts.
4. **QA pass**
- Vérifier si les liens sont résolus.
- Vérifier que les blocs de code et les commandes en ligne sont inchangés.
- Vérifier la cohérence terminologique en utilisant `terminology-en-es.md`.
5. **Regenerate exports**
- Exécutez `npm run gen:wiki-llms`.
6. **Review and PR**
- Inclure un résumé des pages traduites et des lacunes restantes.
## Liste de contrôle de l'AQ pour la traduction
- [ ] Hiérarchie de cap conservée.
- Le commandement n'a pas changé.
- [ ] Chemins de fichiers et URLs inchangés.
- [ ] Compétence et noms de plate-forme inchangés.
- La terminologie de la sécurité est cohérente.
- [ ] `wiki/INDEX.md` a des entrées de lien de traduction.
- [ ] `wiki/<lang>/INDEX.md` renvoie à des pages anglaises clés lorsqu'elles ne sont pas traduites.
## Suggestion de déploiement du langage
1. Espagnol (`es`) – effectué au niveau de la phase 1.
2. Français (`fr`) et allemand (`de`) pour un large public technique.
3. Japonais (`ja`) pour les documents de plate-forme haute fidélité.
Références sources
- PRÊT.md
- LECTME.es.md
- wiki/INDEX.md
- wiki/es/INDEX.md
- wiki/es/overview.md
wiki/fr/migration-signed-feed.md
+185
View File
@@ -0,0 +1,185 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../migration-signed-feed.md
Review status: draft
-->
# Enregistrement de migration: Nourriture non signée → Nourriture signée (Complété)
Oui. 1) Objectif et statut
Documentez comment la distribution de conseils ClawSec est passée de la livraison non signée `feed.json` à la vérification de la signature individuelle, la compatibilité étant préservée pour les anciens clients.
Situation actuelle sur `main`:
- La publication de flux signés est active dans les flux de travail de conseil et de déploiement.
- Les consommateurs de Suite et NanoClaw sont par défaut sur les paramètres d'alimentation signés.
- Le comportement non signé n'existe que sous forme de contournement de compatibilité explicite (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`).
Oui. 2) Données de référence (aujourd ' hui, après la migration)
Voies d'alimentation actuelles en utilisation active:
- Source de vérité: `advisories/feed.json`
- Signature de la source: `advisories/feed.json.sig`
- Copie des compétences : `skills/clawsec-feed/advisories/feed.json`
- Signature de la copie de compétence: `skills/clawsec-feed/advisories/feed.json.sig`
- Copie des pages : `public/advisories/feed.json`
- Signature des pages : `public/advisories/feed.json.sig`
- Dernière copie miroir: `public/releases/latest/download/advisories/feed.json` (+ `.sig`)
Par défaut du consommateur actuel :
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- URL par défaut : `https://clawsec.prompt.security/advisories/feed.json`
Oui. 3) Principes migratoires
- **Deuxième publication : publier les signatures avant de procéder à la vérification.
- **Non ouvert seulement pendant la transition** : la période de compatibilité temporaire est explicite et limitée dans le temps.
- **Mentions de déploiement**: faire appliquer la vérification après télémétrie confirme la stabilité de l'édition signée.
- **Fast runback**: préserver un chemin de retour au comportement non signé pendant que la cause racine est étudiée.
Oui. 4) Chronologie progressive (historique)
- Oui. Phase 0 — Préparation (achevée)
Produits livrables:
- clés de signature générées et empreintes digitales enregistrées
- Les secrets de GitHub créés
- clé(s) publique(s) ajoutée(s) en repo
- runbooks approuvés (`security-signing-runbook.md`, ce fichier)
Critères de sortie:
- empreintes clés vérifiées par l'examinateur
- contrôle des branches/flux de travail protégé activé
- Oui. Phase 1 — La signature de l'IC est activée, aucune exécution par le client (achevée)
Mettre en œuvre :
- ajouter l'étape de signature/le flux de travail pour produire `advisories/feed.json.sig`
- produire en option `advisories/checksums.json` + `.sig`
- s'assurer que l'IC vérifie les signatures avant la publication des artefacts
Actualiser également le déploiement :
- copier les artefacts `.sig` vers `public/advisories/`
- miroir `.sig` en `public/releases/latest/download/advisories/`
Critères de sortie:
- signatures générées avec succès pour tous les chemins de mise à jour de flux
- les artefacts de déploiement contiennent à la fois la charge utile et les compagnons de signature
- Oui. Phase 2 — Soutien à double lecture/vérification du consommateur (achevé)
Mettre en œuvre chez les consommateurs:
- lire `feed.json` et `feed.json.sig`
- vérifier avec la clé publique
- garder le contrôle temporaire non signé retour pendant la fenêtre de migration
Validation:
- parcours d'essai à distance signé
- tester le chemin de repli signé local
- essai de refus de signature non valide
Critères de sortie:
- logique de vérification libérée et testée
- aucune défaillance de vérification faussement positive pendant la période de stabilisation
- Oui. Phase 3 — Exécution (achevée)
Actions:
- désactiver le comportement de repli temporaire non signé dans les chemins par défaut
- ajouter des portes CI/publish qui échouent lorsque `.sig` est manquant
- annoncer la date d'exécution dans les notes de diffusion et les documents
Critères de sortie:
- tous les clients de production vérifient les signatures par défaut
- aucune dépendance d'alimentation non signée dans le débit d'installation standard
- Oui. Phase 4 — Stabilisation (en cours)
Actions:
- exécuter la première clé de rotation de la perceuse de table
- perceuse de table en marche arrière
- migration étroite avec examen post-mise en œuvre
Oui. 5) Plan de redressement
### Déclencheurs arrière
Lancer un renversement si l'une des situations suivantes se produit:
- défaillances persistantes de la vérification de la signature entre les clients
- la signature de workflow ne peut pas produire de signatures valides
- compromis clé suspecté mais la clé de remplacement n'est pas encore déployée
- chemin de déploiement publie des paires de charge utile/signature erronées
Niveau de recul
Niveau 1 (préféré): Fenêtre de contournement de vérification, publication signée
Utilisation lorsque : la signature est saine, le vérificateur côté client a un défaut.
Actions:
1. Réactiver le comportement temporaire non signé-acceptation dans la branche de libération du client.
2. Sortie du patch du navire avec date d'expiration explicite pour le contournement.
3. Continuez à signer le pipeline actif pour éviter les lacunes en matière d'authenticité.
Objectif de récupération: restaurer une vérification stricte dans les 24–48h.
Niveau 2 : pipeline signé interrompu, alimentation non signée faisant temporairement autorité
Utiliser lorsque : la signalisation est instable ou produit des artefacts incohérents.
Actions:
1. Désactiver le workflow de signature ou l'étape de signature.
2. Continuer à publier `advisories/feed.json` non signé via les workflows existants.
3. Révertissez les portes de déploiement qui nécessitent des artefacts `.sig`.
4. Ouvrir l'enregistrement des incidents et le temps de suivi en mode non signé.
Objectif de récupération: restaurer l'édition signée ASAP, idéalement <72h.
Niveau 3 : Gel complet
Utiliser quand: compromis ou intégrité du dépôt / flux de travail est en doute.
Actions:
1. Pas de mutation de flux d'alimentation et de déploiement.
2. Restaurer le commit connu-bon pour les fichiers de conseil / flux de travail.
3. Rotation des clés et des références.
4. Reprendre le pipeline seulement après l'approbation de l'examen de la sécurité.
Rouler après le retour
- identifier la cause racine
Ajouter les essais/portes de régression
- redéployer les artefacts signés
- publier un résumé de l'incident + des mesures correctives
Oui. 6) Plan de communication
Pour les événements d'exécution et de recul, communiquer :
- ce qui a changé
- action attendue de l'opérateur/client
- durée du mode de compatibilité temporaire (le cas échéant)
- commandes de vérification pour les utilisateurs
Chaînes recommandées:
- Notes de sortie de GitHub
- mises à jour du dépôt README/docs
- rapport d'incident dans le dépôt
Oui. 7) Liste de contrôle aller/pas aller
Allez seulement si tout est vrai:
- le taux de réussite des processus de signature est stable
- les signatures sont en miroir avec tous les paramètres d'alimentation documentés
- Voie de vérification du consommateur testée pour la distance + recul local
- le propriétaire de retour est assigné et accessible
- la procédure de rotation clé a été à sec au moins une fois
Références sources
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- avis/feed.json
- wiki/security-signing-runbook.md
wiki/fr/overview.md
+114
View File
@@ -0,0 +1,114 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../overview.md
Review status: draft
-->
♪ Aperçu général
Objet
- ClawSec est un dépôt axé sur la sécurité qui combine un catalogue web public avec des compétences de sécurité installables pour les environnements OpenClaw et NanoClaw.
- Oui. La base de codes prend en charge trois modes de livraison à la fois : l'édition statique du site Web, la distribution de conseils signée et l'emballage de libération par compétence GitHub.
- Les principaux utilisateurs sont les opérateurs d'agents, les développeurs de compétences et les responsables de l'automatisation de la sécurité basée sur l'IC.
![Prompt Security Logo](../assets/overview_img_01_prompt-security-logo.png)
![ClawSec Mascot](../assets/overview_img_02_clawsec-mascot.png)
Oui. Mise en page
Rôle Remarques
- Oui.
`pages/`, `components/`, `App.tsx`, `index.tsx`.Vite + React UI. - Oui.
Chaque compétence a `skill.json`, `SKILL.md`, scripts/tests/docs optionnels. - Oui.
`advisories/` Assemblage d'avis de dépôt Signé `feed.json` + `feed.json.sig` et matériel clé. - Oui.
`scripts/`= Automatisation locale= Popular feed/skills, pré-push checks, aide à la libération. - Oui.
`.github/workflows/`=1 pipelines CI/CD=1 IC, rejets, sondage NVD, ingestion de conseils communautaires, pages déployées. - Oui.
Utilitaires de Python de `utils/` de `utils/`. - Oui.
`public/`S Actifs statiques publiés. - Oui.
`wiki/`=Moyeu de documentation= Architecture, opérations, guides d'exécution, compatibilité et guides de vérification. - Oui.
Points d'entrée
Entrée Type Objet
- Oui.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . - Oui.
`App.tsx`=Définit la carte de route pour les pages home, kills, feed et wiki. - Oui.
`scripts/prepare-to-push.sh` Obtenir le flux de travail Dev Exécute les contrôles de lint/type/build/security avant de pousser. - Oui.
`scripts/populate-local-feed.sh`= Données bootstrap=Pulls CVEs de NVD et met à jour les flux de conseils locaux. - Oui.
`scripts/populate-local-skills.sh`=_____________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ - Oui.
`scripts/generate-wiki-llms.mjs`=Exportation de Docs=Génère `public/wiki/llms.txt` et des exportations wiki par page. - Oui.
`.github/workflows/skill-release.yml`= Entrée de la mainlevée. - Oui.
`.github/workflows/poll-nvd-cves.yml`= Mises à jour des flux programmés= Polls NVD et mises à jour des avis. - Oui.
Les principaux objets
Artefact Produit par Consommé par
- Oui.
`advisories/feed.json` Exclusivité du sondage NVD + flux de travail de conseil communautaire Exclusivité de l'interface Web, crochet clawsec-suite, installateurs. - Oui.
`advisories/feed.json.sig`=Signing workflow steps=Vérification de signature dans l'outil suite/nanoclaw. - Oui.
`public/skills/index.json`=Déployer le workflow / popular local script=`pages/SkillsCatalog.tsx` et `pages/SkillDetail.tsx`. - Oui.
`public/wiki/llms.txt` + `public/wiki/**/llms.txt`= script de générateur de Wiki + build hooks= Exportations de wikis LLM-ready liées depuis l'interface utilisateur wiki. - Oui.
`public/checksums.json` + `public/checksums.sig`.Déployer le flux de travail. - Oui.
`release-assets/checksums.json`=Skill release workflow Release consumers verified zip integrity. - Oui.
`skills/*/skill.json`= Auteurs qualifiés= Génération de catalogue de site, validateurs et pipelines de libération. - Oui.
Oui. Principaux flux de travail
- Développement web local : `npm install` puis `npm run dev`.
- Aperçu des données de sécurité locale: exécutez `./scripts/populate-local-skills.sh` et `./scripts/populate-local-feed.sh` avant de charger les pages `/skills` et `/feed`.
- Porte de qualité prépush: exécuter `./scripts/prepare-to-push.sh` (en option `--fix`).
- Cycle de vie des compétences : éditer `skills/<name>/`, valider avec `python utils/validate_skill.py`, puis marquer `<skill>-vX.Y.Z` pour déclencher le flux de travail de libération.
- Cycle de vie consultatif : le sondage prévu sur la DNV et l'ingestion communautaire fondée sur l'étiquetage des émissions fusionnent dans le même aliment signé.
## Exemples d'extraits
```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
```
Oui. Par où commencer
- Lire `README.md` pour le positionnement des produits et l'installation des chemins.
- Ouvrez `App.tsx` et `pages/` pour comprendre le comportement orienté vers l'utilisateur.
- Ouvrez `skills/clawsec-suite/skill.json` pour comprendre le contrat de suite et les composants intégrés.
- Examiner `.github/workflows/ci.yml`, `.github/workflows/pages-verify.yml`, `.github/workflows/skill-release.yml`, `.github/workflows/deploy-pages.yml` et `.github/workflows/wiki-sync.yml` pour le comportement de production.
Oui. Comment naviguer
- Le comportement de l'interface utilisateur est centré sur `pages/`; les enveloppes visuelles sont placées dans `components/`.
- La logique spécifique à la compétence est isolée par dossier sous `skills/` ; chaque dossier comprend ses propres scripts/tests/docs.
- La gestion des flux apparaît en trois couches : fichiers de flux de dépôt, mises à jour de flux de travail et consommateurs d'exécution (`clawsec-suite`/`clawsec-nanoclaw`).
- Portes de qualité opérationnelle en direct dans les fichiers `scripts/` et YAML workflow.
- Pour les traces de génération et la mise à jour des lignes de base, commencer à partir de `wiki/GENERATION.md` puis brancher dans les pages de module.
Pièges communs
- L'utilisation de jetons d'accueil littéraux (par exemple `\$HOME`) dans le chemin de configuration env vars peut déclencher des défaillances de validation de chemin.
- La saisie de JSON à partir des routes SPA peut retourner HTML avec l'état 200; pages garde pour cela et le traiter comme vide-état.
- Le mode de contournement d'alimentation non signé (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) existe pour la compatibilité de migration et ne doit pas être utilisé en état d'équilibre.
- L'automatisation des sorties de compétences prévoit la parité de version entre `skill.json` et `SKILL.md`.
- Certains scripts sont orientés vers le shell POSIX ; les utilisateurs de Windows devraient préférer les équivalents PowerShell ou WSL.
## Mettre à jour les notes
- 2026-02-26: Mise à jour de la mise en page pour pointer la documentation opérationnelle à `wiki/` au lieu du répertoire racine `docs/` supprimé.
Références sources
- PRÊT.md
- paquet.json
- App.tsx
- index.tsx
- pages/Home.tsx
- pages / SkillsCatalog.tsx
- pages/SkillDetail.tsx
- pages/FeedSetup.tsx
- scripts/prepare-to-poush.sh
- scripts/popular-local-feed.sh
- scripts/popular-local-skills.sh
- compétences/clawsec-suite/skill.json
- .github/workflows/ci.yml
- .github/workflows/pages-vérify.yml
- .github/workflows/kill-release.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/wiki-sync.yml
wiki/fr/platform-verification.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../platform-verification.md
Review status: draft
-->
# Liste de vérification de la plateforme
Utilisez cette liste de contrôle pour valider la portabilité et le comportement de manipulation du chemin après les changements.
## Vérification Linux
1. Exécuter les essais de Noyau:
```bash
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
Prévue : tous les tests sont réussis.
2. Vérifier que le chemin `$HOME` n'est pas accepté au sens littéral :
```bash
CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Attendu : sort non-zéro avec l'erreur `Unexpanded home token`.
3. Vérifier que `$HOME` fonctionne :
```bash
HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
```
Prévu: `$HOME` tests d'extension réussi.
## MacOS Vérification
1. Exécutez la même suite de test Node que Linux.
2. Confirmer que les hypothèses de chemin d'outillage OpenSSL sont documentées :
- Si vous utilisez des variations LibreSSL/OpenSSL, assurez-vous d'utiliser les formulaires de commande testés des docs.
3. Vérifier l'expansion de tilde dans le chemin de configuration :
```bash
OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
```
Attente : le chemin résout correctement (ou efface l'erreur de fichier non trouvée à l'emplacement élargi).
## Vérification de Windows (PowerShell)
1. Essais des nœuds de course:
```powershell
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
```
Attendu : tous passent.
2. Vérifier la puissance Comportement d'extension du chemin Shell env :
```powershell
$env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Attendu : le jeton de chemin est élargi/normalisé ou échoue avec une erreur claire si les fichiers cibles sont manquants.
3. Vérifier le rejet littéral des jetons échappés :
```powershell
$env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
Prévue : erreur `Unexpanded home token` ; aucune création de répertoire avec `$HOME` littérale.
Oui. Sanité des extrémités de ligne
1. Confirmer que la politique de LF est présente :
```bash
test -f .gitattributes && grep -n "eol=lf" .gitattributes
```
Attendu : les modèles de fichiers script/config font appliquer LF.
2. Après une commande CRLF-prone, vérifier les scripts toujours analyse:
```bash
bash -n scripts/populate-local-feed.sh
bash -n scripts/populate-local-skills.sh
```
Prévue : pas d'erreurs `^M` shebang/parse.
## Vérification explicite du bogue: Pas de `$HOME` Création de répertoires
1. Configurer un chemin avec un jeton littéral/échapé.
2. Exécutez la commande configuration/installation.
3. Vérifier la commande échoue tôt avec l'erreur symbolique.
4. Confirmer qu'aucun répertoire de segment `$HOME` n'a été créé sous les répertoires de travail.
Résultat attendu : ** aucun répertoire contenant `$HOME` littéral n'est créé par des scripts de configuration supportés. **
Références sources
- .gitattributes
- scripts/popular-local-feed.sh
- scripts/popular-local-skills.sh
- compétences/clawsec-suite/test/path_resolution.test.mjs
- compétences/clawsec-suite/test/guarded_install.test.mjs
- compétences/clawsec-suite/test/advisory_suppression.test.mjs
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- compétences/openclaw-audit-watchdog/test/suppression_config.test.mjs
wiki/fr/remediation-plan.md
+89
View File
@@ -0,0 +1,89 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../remediation-plan.md
Review status: draft
-->
# Plan d'assainissement transplateforme
Oui. Phase 1 : Fermeture immédiate du risque (achevée)
Jalons
- Mettre en œuvre l'expansion explicite du chemin d'accès à domicile + rejet de jeton suspect dans les chemins d'accès/installation à haut risque.
- Ajouter des tests de régression pour l'expansion du chemin et le rejet du jeton échappé.
- Ajouter la politique `.gitattributes` LF.
- Expand Node lint/type/build CI couverture vers Linux/macOS/Windows.
- Mettre à jour les documents d'installation avec le guidage spécifique au shell et le dépannage littéral `$HOME`.
Résultats
- Bogue de propagation du chemin `$HOME` adressée à la source.
- Core advisory/install path config échoue maintenant rapidement sur les jetons de chemin invalides.
---
Oui. Phase 2: Parité Windows pour les flux de travail critiques (suivant)
### gagne rapidement
- Ajouter de la puissance Équivalents Shell pour les commandes manuelles d'installation/de vérification les plus utilisées dans:
- `skills/clawsec-suite/SKILL.md`
- `skills/openclaw-audit-watchdog/SKILL.md`
- `README.md`
- Ajouter un `scripts/preflight.mjs` léger pour détecter les outils manquants et imprimer des conseils d'installation spécifiques à l'OS.
Jalons
- Pouvoir autochtone Instructions Shell pour la configuration de la suite et le crochet de conseil.
- Retour WSL/Git Bash documenté où les scripts shell sont inévitables.
---
Oui. Phase 3: Réduire le POSIX Surface de la coquille (réfacteur de l'épereur)
Objectifs de refactor
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `scripts/release-skill.sh`
Approche
- Re-implémenter des chemins critiques dans Node/Python pour supprimer la dépendance sur les pipelines `jq/sed/awk/find/chmod`.
- Préserver les enveloppes shell pour la compatibilité arrière; route vers de nouvelles implémentations multiplateforme.
Notes de migration
- Gardez les anciens points d'entrée de script comme enveloppes pour au moins une version mineure.
- Emiter les avertissements de déprécation avec des commandes de migration exactes.
---
Oui. Phase 4 : durcissement de l'IC et vérification continue
Jalons
- Gardez la matrice de nœuds (Linux/macOS/Windows) au besoin.
- Ajouter des tests de fumée Windows ciblés pour la manipulation du chemin d'installation.
- Ajoutez les notes de compatibilité de la commande OpenSSL, le cas échéant.
- Oui. Stratégie d'essai
- Local :
- Exécutez les suites de test Node qui couvrent l'expansion du chemin/la suppression/le comportement d'installation.
- Exécutez des vérifications de syntaxe pour les scripts modifiés.
- Oui.
- Contrôles des nœuds Matrix + essais d'installateur/suppression/path.
- Les scans de sécurité Linux-seulement restent, mais explicitement marqués comme Linux-scoped.
---
## Déroulement / considérations de libération
- Oui. Pas de changement d'interface de rupture introduit dans ce patch set; le comportement est plus strict seulement pour les jetons de chemin invalides/non élargis.
- Communiquer dans les notes de mise en liberté :
- validation du jeton de chemin maintenant appliquée
- comment corriger les valeurs env non valides
- où le pouvoir Exemples de Shell en direct
Références sources
- .gitattributes
- .github/workflows/ci.yml
- scripts/popular-local-feed.sh
- scripts/popular-local-skills.sh
- scripts/release-skill.sh
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- wiki/plateforme-vérification.md
wiki/fr/security-signing-runbook.md
+239
View File
@@ -0,0 +1,239 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../security-signing-runbook.md
Review status: draft
-->
# ClawSec - Manuel des opérations de signature
Oui. 1) Objet
Ce runbook définit les procédures opérationnelles d'introduction et d'exécution de la signature cryptographique dans le dépôt ClawSec.
Il couvre:
- génération clé
- Gestion secrète GitHub
- signature de l'intégration du flux de travail
- rotation et révocation des clés
- réponse incidente
Oui. 2) État d'exploitation actuel (important)
Sur `main`, les canaux de consultation et de diffusion sont signés et vérifiés par défaut:
- Rédactrices :
- `.github/workflows/poll-nvd-cves.yml` mises à jour `advisories/feed.json` et signes `advisories/feed.json.sig`
- `.github/workflows/community-advisory.yml` fait la même chose pour les rapports de diffusion approuvés
- les deux artefacts de flux signés synchronisés dans `skills/clawsec-feed/advisories/`
- Chemin de publication du flux :
- `.github/workflows/deploy-pages.yml` publie `public/advisories/feed.json` + `.sig`
- génère et signe `public/checksums.json` + `public/checksums.sig`
- publie la clé canonique `public/signing-public.pem` et `public/advisories/feed-signing-public.pem`
- les artefacts de compatibilité des miroirs sous `public/releases/latest/download/` (y compris `feed.json`, `feed.json.sig`, `checksums.json`, `checksums.sig`, `signing-public.pem`)
- consommateurs d'aliments pour animaux:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- URL de flux par défaut est `https://clawsec.prompt.security/advisories/feed.json`
Le mode non signé reste un contournement de compatibilité explicite (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) et n'est pas le modèle d'exploitation à l'état stationnaire.
Oui. 3) Artefacts ciblés signés
Voie d'alimentation consultative
- `advisories/feed.json` (charge utile)
- `advisories/feed.json.sig` (signé Ed25519; base64)
- `advisories/feed-signing-public.pem` (clé publique piquée)
- Oui. Release artefact canal
- `<release>/checksums.json`
- `<release>/checksums.sig`
- `<release>/signing-public.pem`
Oui. 4) Rôles clés et garde
- **Propriétaire de la sécurité**: approuve les changements clés du cycle de vie et les mesures d'incident.
- **Platform owner**: maintient les flux de travail et les secrets GitHub.
- **Reviewer**: valide les empreintes digitales dans les PR/releases.
Politique :
- les clés privées ne sont jamais engagées
- les clés publiques sont engagées et revues par code
- la génération de clés se produit sur un poste de travail d'opérateur fiable ou un environnement soutenu par HSM
Oui. 5) Génération de clés (Ed25519)
> Courez depuis un poste de travail sécurisé. Ne pas courir sur les coureurs CI partagés.
```bash
# Feed signing keypair
openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem
openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem
# Release checksums signing keypair (optional separate key)
openssl genpkey -algorithm Ed25519 -out release-signing-private.pem
openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem
```
Générer des empreintes digitales (stocker dans l'enregistrement de ticket/changement):
```bash
openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256
openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256
```
Signe d'essai facultatif avant publication:
```bash
echo '{"probe":"ok"}' > /tmp/probe.json
openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
```
Oui. 6) Configuration des secrets GitHub
- Oui. Secrets requis
- `CLAWSEC_SIGNING_PRIVATE_KEY` — Clé privée Ed25519 codée par PEM (utilisée à la fois pour la signature de flux et de libération)
- `CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (facultatif) passphrase si la clé privée est chiffrée
Procédure
1. Aller à **Paramètres de repo → Secrets et variables → Actions → Nouveau secret de dépôt**.
2. Coller le PEM complet, y compris l'en-tête/le pied.
3. Préférez GitHub ** Secrets environnementaux** (avec les examinateurs requis) pour l'établissement de la portée des tâches, dans la mesure du possible.
4. Enregistrer le ticket de changement avec :
- nom secret
- créateur
- temps de création
- empreinte digitale clé
- Oui. Protections environnementales recommandées
- Exiger l'approbation manuelle des flux de travail qui peuvent utiliser des secrets de signature.
- Restreindre qui peut modifier les workflows protégés.
- Activer la protection des branches pour `main` et exiger un examen pour les changements de flux de travail.
Oui. 7) Points d'intégration des flux de travail
Cette repo impose la signature comme un contrôle post-mutation, pré-publication.
Ligne d'alimentation
Points de mutation d'alimentation actuels:
- `.github/workflows/poll-nvd-cves.yml`
- `.github/workflows/community-advisory.yml`
Comportement actuel :
- l'étape du workflow signe `advisories/feed.json` dans `advisories/feed.json.sig`
- l'action de signature vérifie les signatures générées pendant l'exécution du workflow
- les artefacts signés sont engagés via l'automatisation des PR
- Oui. pipeline de pages
Éditeur actuel :
- `.github/workflows/deploy-pages.yml`
Comportement actuel :
- copie la charge utile/signature à `public/advisories/`
- génère + signes `public/checksums.json` et `public/checksums.sig`
- publie la clé de signature pour `public/signing-public.pem` et `public/advisories/feed-signing-public.pem`
- conseils miroirs + signe/checksum/clés compagnons dans les chemins de compatibilité `public/releases/latest/download/`
- Oui. pipeline de libération des compétences (durcissement recommandé)
Générateur de sortie actuel & #160;:
- `.github/workflows/skill-release.yml`
Comportement actuel :
- crée `checksums.json`, le signe comme `checksums.sig` et vérifie la signature avant de publier
- inclut `signing-public.pem` dans les actifs de libération
- valide les empreintes à clé publique générées par rapport au matériel à clé canonique
Oui. 8) Politique et manuel de rotation
Cadence de rotation
- Routine: tous les 90 jours (ou politique d'orga nisation plus stricte).
- Immédiatement : en cas d'exposition présumée, de changement de flux de travail non autorisé ou d'inadéquation de signature inexpliquée.
Étapes de rotation courantes
1. Générer de nouvelles paires de clés.
2. Ouvrez le PR qui met à jour les fichiers à clé publique et la documentation des empreintes digitales.
3. Ajoutez de nouvelles clés privées comme GitHub secret(s).
4. Fusionner les changements de flux de travail qui utilisent de nouvelles clés.
5. Resigner les derniers manifestes d'alimentation/libération.
6. Valider la vérification en CI et dans un client externe.
7. Enlever l'ancien secret de clé privée.
8. Conserver l'ancienne référence à la clé publique seulement aussi longtemps que nécessaire pour la vérification historique.
Étapes de révocation
1. Désactiver les workflows en utilisant la clé compromise.
2. Supprimer les secrets de GitHub compromis.
3. Communiquez la note de révocation et la nouvelle clé publique.
4. Résignez les derniers artefacts avec la clé de remplacement.
5. Publier un avis d'incident avec horodatage et fenêtre impactée.
Oui. 9) Manuel de réponse aux incidents (spécifique à la signature)
Déclencheurs
- non-vérification de la signature pour les aliments pour animaux/délivrance nouvellement publiés
- validations/modifications de flux de travail inconnues touchant les chemins de signature
- fuite de matériel clé, abattage accidentel ou accès secret suspect
Guide de gravité
- **SEV-1**: publication de la charge utile confirmée ou signée par malveillance
- **SEV-2**: défaillances de vérification pour cause inconnue
- **SEV-3**: non-respect des procédures, pas de compromis actif
- Oui. Phases de réponse
1. **Contenu* *
- pause signature/publication des workflows
- bloquer les flux de fusion si l'authenticité est incertaine
2. **Enquête**
- revoir les journaux d'exécution des flux de travail
- l'examen s'engage à affecter `.github/workflows/`, `advisories/`, et les fichiers clés
- déterminer le premier horodatage et les artefacts affectés
3. **Éradication**
- rotation/revocation des clés compromises
- restaurer des artefacts de confiance à partir de commit de bien connu
4. **Récupération**
- resigner les artefacts
- des pages/éditions redéployées
- vérifier par un contrôle indépendant du client
5. **Après un incident* *
- publier le calendrier et le résumé des mesures correctives
- renforcer les contrôles (portes d'examen, environnements protégés, portée secrète)
## 10) Liste de vérification des éléments probants
Pour chaque cycle de libération ou exécution de la signalisation d'alimentation, conserver:
- Exécuter URL et commit SHA
- empreinte digitale de la clé de signature utilisée
- registres des résultats de vérification
- les agréments d'opérateur/d'examinateur
- toute exception ou justification de contournement
## 11) Critères d'acceptation minimum avant des changements de politique plus stricts
Avant de renforcer la politique (par exemple, supprimer les voies de contournement de compatibilité):
- les artefacts signés sont produits régulièrement pendant au moins 2 semaines
- Déployer les compagnons de signature des miroirs de pipeline
- une perceuse de renversement et une perceuse de rotation clé terminée avec succès
- réponse à l'incident sur appel propriétaire identifié et documenté
Références sources
- avis/feed.json
- avis/feed.json.sig
- avis/signature d'alimentation-public.pem
- clawsec-signing-public.pem
- .github/actions/sign-and-vérify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/kill-release.yml
- scripts/ci/vérify_signing_key_consistance.sh
- wiki/migration-signé-feed.md
wiki/fr/security.md
+83
View File
@@ -0,0 +1,83 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../security.md
Review status: draft
-->
♪ Sécurité
## Aperçu du modèle de sécurité
- ClawSec sécurise à la fois la distribution du contenu (artefacts signés) et le comportement d'exécution (gage consultatif, surveillance de l'intégrité).
- Les ancres de confiance sont piquées les clés publiques engagées en repo et vérifiées par rapport aux sorties générées par le workflow.
- Runtime consommateurs par défaut à la vérification-premier comportement avec des drapeaux de contournement de migration explicite.
Contrôles cryptographiques
Mécanisme de contrôle Lieu
- Oui.
- Oui. Authenticité de l'alimentation: Ed25519 signatures détachées (`feed.json.sig`) . - Oui.
L'intégrité de l'artefact Les manifestes de somme de contrôle SHA-256 (`checksums.json`) - Oui.
- Oui. Comparaison des empreintes digitales entre les docs + PEM canoniques. - Oui.
Mesure de vérification de la signature - Oui.
Contrôles d'exécution
Contrôle Composante Effet
- Oui.
`clawsec-advisory-guardian`= Alertes et conseils prudents basés sur des avis assortis. - Oui.
Installateur double confirmation Depuis `guarded_skill_install.mjs` Sortie `42` jusqu'à confirmation explicite des avis correspondants. - Oui.
Extension de la réputation de `clawsec-clawhub-checker`. - Oui.
`skill-signature-handler.ts` + outil MCP. - Oui.
Moniteur de base de l'intégrité : `soul-guardian` + NanoClaw Moniteur de l'intégrité : détection de la dérive, quarantaine, restauration, historique vérifiable. - Oui.
Contrôles de la chaîne d'approvisionnement et de l'IC
- L'IC court Trivy, npm audit, CodeQL, et Scorecard workflows.
- Les vérifications pré-push locales peuvent exécuter `gitleaks detect` lorsque `gitleaks` est installé.
- Release workflows valide l'existence du fichier SBOM avant l'emballage.
- Déployer le flux de travail vérifie l'empreinte de la clé de signature générée contre le matériel de clé canonique.
- Les documents de publication comprennent des commandes de vérification manuelle pour les consommateurs en aval.
## Livres d'incident et de rotation
- `wiki/security-signing-runbook.md` définit les phases de génération, de garde, de rotation et d'incident.
- `wiki/migration-signed-feed.md` définit les niveaux d'exécution et de renversement par étapes.
- Les chemins de retour priorisent la préservation de l'édition signée dans la mesure du possible et le décalage horaire.
## Exemples d'extraits
```bash
# verify canonical public key fingerprint
openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256
```
```bash
# run repo key-consistency guardrail used in CI
./scripts/ci/verify_signing_key_consistency.sh
```
## Échanges connus sur la sécurité
- Le mode de compatibilité non signé peut réduire l'assurance et devrait être désactivé une fois la migration terminée.
- Certains chemins de déploiement tolèrent les actifs de bilan non signés pour la compatibilité en arrière.
- Les contrôles de réputation reposent sur la sortie d'outillage externe et peuvent inclure les faux positifs/négatifs heuristiques.
- Les scripts locaux héritent de la confiance en l'environnement ; les shells locaux compromis peuvent encore subvertir les workflows de l'opérateur.
Possibilités de durcissement
- Supprimer les drapeaux de compatibilité non signés après stabilisation de la migration.
- Étendre la vérification déterministe de la somme de contrôle/signature de tous les fichiers de libération miroir.
- Ajouter des tests explicites pour les scénarios d'échec de signature au niveau du workflow.
- Augmenter la télémétrie d'exécution pour les défauts de récupération/vérification pour simplifier le triage des incidents.
## Mettre à jour les notes
- 2026-02-26: Repointed signature et références de migration à partir de fichiers racine `docs/` vers les pages d'exploitation `wiki/` dédiées.
Références sources
- Sécurité md
- wiki/security-signing-runbook.md
- wiki/migration-signé-feed.md
- scripts/ci/vérify_signing_key_consistance.sh
- .github/actions/sign-and-vérify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/kill-release.yml
- .github/workflows/deploy-pages.yml
- compétences/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- compétences/clawsec-suite/scripts/guarded_skill_install.mjs
- compétences/clawsec-clawhub-checker/scripts/enhanced_guarded_install.mjs
- compétences/soul-guardian/scripts/soul_guardian.py
- compétences/clawsec-nanoclaw/host-services/skill-signature-handler.ts
- compétences/clawsec-nanoclaw/guardian/integrity-monitor.ts
wiki/fr/testing.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../testing.md
Review status: draft
-->
# Essais
## Stratégie d'essai
- Oui. Le dépôt utilise une vérification en couches plutôt qu'une seule commande racine `npm test`.
- La confiance de base provient de portes en peluche/type/construction plus compétences-local Suites de test de nœud.
- Les outils Python et shell sont validés au moyen de contrôles de lint/security dédiés.
- Les pipelines Workflow exécutent les mêmes classes de commande que celles utilisées pour l'automatisation pré-poussière locale.
## Calques de vérification
Calque Commandes Portée
- Oui.
Contrôles frontaux/statiques - Oui.
Tests d'unité d'aptitudeSpéciaux `node skills/<skill>/test/*.test.mjs`S Signature, correspondance, suppression, contrats d'installation. - Oui.
Qualité du python: `ruff check utils/`, `bandit -r utils/ -ll`. - Oui.
Shell / qualité de l'écriture ShellCheck + script manuel smoke runs. - Oui.
Tests de sécurité CI : Trivy, npm audit, CodeQL, Scorecard. - Oui.
Local pre-push security scan en option `gitleaks detect` via `scripts/prepare-to-push.sh`. - Oui.
## Matrice de test de compétence
Compétences Dossiers de test
- Oui.
`clawsec-suite`= `feed_verification`, `guarded_install`, `path_resolution`, tests de fuzz=Contrôle de signature, mise en garde, sécurité du trajet, robustesse correspondante. - Oui.
`openclaw-audit-watchdog` , config de suppression et render des tests , config parsing , le comportement de suppression , le formatage de rapport . - Oui.
`clawsec-clawhub-checker`.`reputation_check.test.mjs`.`reputation_check.test.mjs`.Z.Vérification d'entrée et comportement de gating de réputation. - Oui.
Couverture du flux de travail de l'IC
Flux de travail - Oui.
- Oui.
Lint/type/build, Python checks, scans de sécurité, tests de compétence. - Oui.
`codeql.yml` (en anglais seulement) - Oui.
`scorecard.yml`="horaire/poussoir" Rapport de posture de la chaîne d'approvisionnement et téléchargement SARIF. - Oui.
Tags de `skill-release.yml` PRs. - Oui.
Commandes locales de test
```bash
# baseline frontend + config checks
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
npm run build
```
```bash
# representative skill tests
node skills/clawsec-suite/test/feed_verification.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
## Modèles d'échec à regarder
- Les dispositifs de signature/test peuvent échouer lorsque les fichiers attendus sont régénérés de façon incohérente.
- Les tests de résolution de trajectoire échouent intentionnellement sur les jetons de maison échappés; ce comportement est attendu et pertinent pour la sécurité.
- Les scripts locaux s'appuyant sur les binaires `openclaw` ou `clawhub` peuvent échouer dans des environnements où ces CLI sont absents.
- Déployer/release logique peut passer localement alors qu'il échoue dans CI si la signature de secrets ou les autorisations de workflow diffèrent.
## Ordre d'essai suggéré
1. Lancez `./scripts/prepare-to-push.sh` pour une porte locale complète.
2. Exécuter des tests de compétence-local directement touchés.
3. Pour les modifications d'alimentation et de signalisation, exécutez d'abord les tests de vérification de la suite (`feed_verification`, `guarded_install`).
4. Pour les modifications de flux de travail ou de publication, exécutez également `scripts/validate-release-links.sh` et le script de cohérence des clés.
## Mettre à jour les notes
- 2026-02-26: Mise à jour des références sources à la liste de contrôle `wiki/platform-verification.md` migrée.
Références sources
- Agents.md
- scripts/prepare-to-poush.sh
- scripts/validate-release-links.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/kill-release.yml
- compétences/clawsec-suite/test/feed_vérification.test.mjs
- compétences/clawsec-suite/test/guarded_install.test.mjs
- compétences/clawsec-suite/test/path_resolution.test.mjs
- compétences/openclaw-audit-watchdog/test/suppression_config.test.mjs
- compétences/clawsec-clawhub-checker/test/reputation_check.test.mjs
- wiki/plateforme-vérification.md
wiki/fr/workflow.md
+87
View File
@@ -0,0 +1,87 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (fr)
Source: ../workflow.md
Review status: draft
-->
# Workflow
## 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 | 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 |
| --- | --- | --- |
| 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. |
## Release Workflow Details
- Version bump and docs parity are enforced for PR/tag paths.
- Skill packaging includes SBOM-declared files and integrity manifests.
- `checksums.json` is signed and immediately verified in workflow execution.
- Optional publish-to-ClawHub job runs after successful GitHub release when configured.
- Older releases within same major line can be superseded/deleted by automation.
## Advisory Workflow Details
- NVD workflow determines incremental window from previous feed `updated` timestamp.
- Transform phase maps CVE metrics to severity/type and normalizes affected targets.
- Community advisory workflow creates deterministic IDs (`CLAW-YYYY-NNNN`) from issue metadata.
- Both advisory workflows update skill feed copies and signature companions.
## Example Snippets
```bash
# manual release prep for a skill
./scripts/release-skill.sh clawsec-feed 0.0.5
# then push tag if running in release branch mode
```
```yaml
# pages deploy depends on successful upstream workflow run
on:
workflow_run:
workflows: ["CI", "Skill Release"]
types: [completed]
```
## Operational Risks
- Workflow permissions and secret scope misconfiguration can block signing/publishing.
- NVD/API transient failures may delay advisory freshness.
- Invalid tag naming or version mismatches halt release automation.
- Local scripts and CI can diverge if operator machine lacks expected binaries (`jq`, `openssl`, `clawhub`).
## Source References
- scripts/release-skill.sh
- 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
wiki/i18n/README.md
+74
View File
@@ -0,0 +1,74 @@
# i18n Pipeline (ClawSec)
This folder defines the translation QA and operations workflow for ClawSec docs.
## Goals
- Keep English as source of truth.
- Make language switching predictable in website/wiki routes.
- Preserve technical integrity in translated docs (commands, code blocks, links, package names).
## Files
- `terminology-en-es.md` — terminology lock and no-translate terms.
- `translation-tracker.md` — coverage and status by page.
- `scripts/i18n/qa_check.py` — translation integrity QA checker.
- `scripts/i18n/bootstrap_language_from_en.py` — scaffold generator for missing language pages.
## Local QA Command
```bash
python scripts/i18n/qa_check.py
```
Or via npm:
```bash
npm run i18n:qa
```
## Bootstrap Commands (language scaffolding)
Dry-run for any language:
```bash
python scripts/i18n/bootstrap_language_from_en.py --lang <code> --dry-run
```
Create missing pages for a language:
```bash
python scripts/i18n/bootstrap_language_from_en.py --lang <code>
```
Overwrite existing scaffolds if needed:
```bash
python scripts/i18n/bootstrap_language_from_en.py --lang <code> --overwrite
```
Convenience npm scripts:
```bash
npm run i18n:bootstrap:ko
npm run i18n:bootstrap:fr
npm run i18n:bootstrap:de
npm run i18n:bootstrap:ja
```
## What QA checks
- Fenced code blocks are preserved exactly from source.
- Critical inline technical tokens are preserved.
- Absolute URLs from source still exist in translation.
- Non-translatable product/skill terms remain unchanged.
## CI integration
Workflow: `.github/workflows/i18n-qa.yml`
Runs on PRs that touch:
- `README*.md`
- `wiki/**/*.md`
- `scripts/i18n/**`
- `.github/workflows/i18n-qa.yml`
## Translation backend strategy (local/free-first)
Recommended approach:
1. Local model for draft translation (NLLB/Marian via CTranslate2 or LibreTranslate self-hosted)
2. Free API fallback for difficult segments
3. Human review for high-impact docs (README, install, security pages)
## Rollout notes
- Add new language under `wiki/<lang>/` and `README.<lang>.md`.
- Add language option in `pages/WikiBrowser.tsx` label map when introducing a new language code.
- Update `translation-tracker.md` for new pages.
wiki/i18n/terminology-en-es.md
+29
View File
@@ -0,0 +1,29 @@
# Terminology Lock (EN -> ES)
Use these canonical translations for consistency across README and wiki translations.
| English term | Spanish standard | Notes |
| --- | --- | --- |
| advisory | advisory | Keep as borrowed technical term in this repo context. |
| advisory feed | feed de advisories | Keep "feed" and "advisories" for consistency with existing docs. |
| signed advisory feed verification | verificación de feed firmado de advisories | Preserve security meaning; do not simplify. |
| drift detection | detección de drift | Keep "drift" literal in technical context. |
| file integrity | integridad de archivos | |
| supply-chain install verification | verificación de instalación de cadena de suministro | |
| fail-closed verification | verificación fail-closed | Keep fail-closed in English. |
| baseline | baseline | Keep baseline in English in this context. |
| security posture | postura de seguridad | |
| self-pen-testing | self-pen-testing | Keep package naming term unchanged. |
| release artifact | artefacto de release | Keep "release" term in English. |
| source of truth | fuente de verdad | |
| quick start | inicio rápido | |
| workflow | workflow | Keep in most headings to match established wiki naming. |
## Non-translatable terms
Always preserve exactly:
- Product/platform names: `ClawSec`, `OpenClaw`, `NanoClaw`, `Hermes`, `Picoclaw`
- Skill package names: `clawsec-suite`, `clawsec-feed`, etc.
- File names, paths, env vars, commands, and flags
## Review rule
If a translator proposes a different term, update this file in the same PR before merging.
wiki/i18n/translation-tracker.md
+62
View File
@@ -0,0 +1,62 @@
# Translation Tracker
Track translation coverage and freshness versus English source docs.
_Last updated: 2026-04-27_
## README Coverage
| Source | Spanish | Status | Notes |
| --- | --- | --- | --- |
| `README.md` | `README.es.md` | partial | Covers onboarding + operations + local dev. Advanced schema/CI details stay in EN for now. |
| `README.md` | `README.ko.md` | partial | Korean scaffold with quickstart and core navigation; advanced details remain in EN. |
## Wiki Coverage (ES)
| Source page | Spanish page | Status |
| --- | --- | --- |
| `wiki/INDEX.md` | `wiki/es/INDEX.md` | done |
| `wiki/overview.md` | `wiki/es/overview.md` | done |
| `wiki/localization.md` | `wiki/es/localization.md` | done |
| `wiki/architecture.md` | — | pending |
| `wiki/security.md` | `wiki/es/security.md` | done |
| `wiki/configuration.md` | — | pending |
| `wiki/testing.md` | — | pending |
| `wiki/workflow.md` | — | pending |
## Wiki Coverage (KO)
| Source page | Korean page | Status |
| --- | --- | --- |
| `wiki/INDEX.md` | `wiki/ko/INDEX.md` | done |
| `wiki/overview.md` | `wiki/ko/overview.md` | partial |
| `wiki/security.md` | `wiki/ko/security.md` | done |
| `wiki/localization.md` | `wiki/ko/localization.md` | done |
| `wiki/configuration.md` | `wiki/ko/configuration.md` | done |
## Wiki Coverage (FR/DE/JA)
| Language | Coverage status | Notes |
| --- | --- | --- |
| `fr` | scaffolded | Auto-generated draft scaffolds for all current wiki pages. |
| `de` | scaffolded | Auto-generated draft scaffolds for all current wiki pages. |
| `ja` | scaffolded | Auto-generated draft scaffolds for all current wiki pages. |
## Phase Plan
### Phase 1 (completed)
- Establish translation baseline:
- `README.es.md`
- `wiki/es/INDEX.md`
- `wiki/es/overview.md`
### Phase 2 (in progress)
- Establish localization process:
- `wiki/localization.md`
- `wiki/es/localization.md`
- terminology lock
- translation tracker
### Phase 3 (next)
- Expand translated wiki coverage for security/operator pages.
- Add second language pilot (recommended: French or German).
wiki/ja/GENERATION.md
+42
View File
@@ -0,0 +1,42 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../GENERATION.md
Review status: draft
-->
# Wiki Generation Metadata
- Commit hash: `c3983a100581a9f27eb8cc3b5baa4f585e6c45e4`
- Branch name: `codex/clawsec-scanner-0.0.2-dast-harness`
- Generation timestamp (local): `2026-03-10T19:06:29+0200`
- Generation mode: `update`
- Output language: `English`
- Assets copied into `wiki/assets/`:
- `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
- `overview_img_02_clawsec-mascot.png` (from `public/img/mascot.png`)
- `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)
## Notes
- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
- Updated index and cross-links to use `wiki/` as the documentation source of truth.
- Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
- Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.
- 2026-04-26: Split Picoclaw self-pen-testing into dedicated `wiki/modules/picoclaw-self-pen-testing.md`, and updated `wiki/modules/picoclaw-security-guardian.md` to cover advisory/drift/supply-chain scope only.
- 2026-04-25: Added DeepWiki-friendly `wiki/modules/picoclaw-security-guardian.md` with support-matrix claims, threat model, default safety posture, frontend/advisory-board wiring, verification commands, and source references. Regenerated `public/wiki/**/llms.txt` exports with `npm run gen:wiki-llms`.
## Source References
- README.md
- package.json
- AGENTS.md
- wiki/overview.md
- wiki/architecture.md
- wiki/modules/clawsec-scanner.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- wiki/dependencies.md
- wiki/data-flow.md
- wiki/glossary.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
wiki/ja/INDEX.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../INDEX.md
Review status: draft
-->
# Wiki Index
## Summary
- Purpose: Document ClawSec as a combined web catalog, signed advisory channel, and multi-skill security distribution system.
- Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines.
- Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`.
- Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing.
- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code.
## Start Here
- [Overview](overview.md)
- [Architecture](architecture.md)
## Translations
- [Español](../es/INDEX.md)
- [한국어](../ko/INDEX.md)
## Guides
- [Localization Workflow](localization.md)
- [Dependencies](dependencies.md)
- [Data Flow](data-flow.md)
- [Configuration](configuration.md)
- [Testing](testing.md)
- [Workflow](workflow.md)
- [Security](security.md)
## Operations
- [Security Signing Runbook](security-signing-runbook.md)
- [Signed Feed Migration Plan](migration-signed-feed.md)
- [Platform Verification Checklist](platform-verification.md)
- [Cross-Platform Remediation Plan](remediation-plan.md)
## Modules
- [Frontend Web App](../modules/frontend-web.md)
- [ClawSec Suite Core](../modules/clawsec-suite.md)
- [ClawSec Scanner](../modules/clawsec-scanner.md)
- [Hermes Attestation Guardian](../modules/hermes-attestation-guardian.md)
- [Hermes Attestation Guardian Draft History (Archived)](../modules/hermes-attestation-guardian-draft-history.md)
- [NanoClaw Integration](../modules/nanoclaw-integration.md)
- [Picoclaw Security Guardian](../modules/picoclaw-security-guardian.md)
- [Picoclaw Self Pen Testing](../modules/picoclaw-self-pen-testing.md)
- [Automation and Release Pipelines](../modules/automation-release.md)
- [Local Validation and Packaging Tools](../modules/local-tooling.md)
## Glossary
- [Glossary](glossary.md)
## Generation Metadata
- [Generation Metadata](GENERATION.md)
## Update Notes
- 2026-04-26: Split Picoclaw self-pen-testing into standalone `picoclaw-self-pen-testing`; updated Picoclaw module docs and references.
- 2026-04-25: Added Picoclaw Security Guardian module for advisory awareness, config drift detection, and chain-of-supply verification.
- 2026-04-19: Moved NanoClaw platform-support and CI/CD pipeline detail sections out of `README.md` into module pages (`modules/nanoclaw-integration.md`, `modules/automation-release.md`) and left README pointers.
- 2026-04-16: Added install-guard compatibility note for Hermes Attestation Guardian (community-source install now SAFE without `--force`; behavior unchanged).
- 2026-04-15: Expanded Hermes Attestation Guardian module page into full narrative, claim-by-claim operator guidance (no claim tables), and added archived draft-history module page.
- 2026-03-10: Added ClawSec Scanner module documentation and linked it under Modules.
- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.
## Source References
- README.md
- App.tsx
- package.json
- scripts/prepare-to-push.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- skills/clawsec-suite/skill.json
- skills/clawsec-scanner/skill.json
- skills/hermes-attestation-guardian/skill.json
- skills/picoclaw-security-guardian/skill.json
- skills/picoclaw-self-pen-testing/skill.json
- wiki/modules/clawsec-scanner.md
- wiki/modules/hermes-attestation-guardian.md
- wiki/modules/hermes-attestation-guardian-draft-history.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- .github/workflows/ci.yml
wiki/ja/architecture.md
+136
View File
@@ -0,0 +1,136 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../architecture.md
Review status: draft
-->
# 建築
## システムコンテキスト
- - - このページは、`INDEX.md`の`Start Here`セクションで表示されます。
- ClawSecは、上流のインテリジェンスソース(NVD +コミュニティの問題)、GitHubの自動化、およびランタイムエージェントの環境間で動作します。
- - - リポジトリは、静的なサイトコンテンツと、使用前にランタイムスキルが検証する署名済みのアーティファクトの両方を公開します。
- 外部俳優グループ:
- GitHub Actions は、CI の実行、リリース、フィードワークフローを実行します。
- OpenClaw/NanoClawエージェントは、スキル、アドバイザリー、検証スクリプトを消費します。
- 諮問的問題の承認とリリース/タグの変更をマージするリポジトリメンテナー。
## コンポーネント
| 製品情報 | 所在地 | 責任 |
| お問い合わせ |
| Web UI | `App.tsx`、`pages/`、`components/` | レンダリングスキル・カタログ・アドバイザリー体験 お問い合わせ
| アドバイザリーフィードコア | `advisories/feed.json*`, `skills/clawsec-suite/.../feed.mjs` | 店舗情報・店舗情報・店舗情報・店舗情報・店舗情報 お問い合わせ
| スキルパッケージ | `skills/*/` | SBOMメタデータによるインストール可能なセキュリティ機能の配布 お問い合わせ
| ローカルオートメーションスクリプト | `scripts/*.sh` | ローカルミラー、プレプッシュチェック、マニュアルリリースヘルパーの構築 お問い合わせ
| CI/CD ワークフロー | `.github/workflows/*.yml` | ライニング・試験・NVD ポーリング・リリース・パッケージ・ページ展開 お問い合わせ
| Pythonユーティリティレイヤー | `utils/*.py` | スキルメタデータ検証とチェックサム生成 お問い合わせ
ツイート キーフロー
- スキルカタログの流れ:
1. スキルアセットを公開するワークフローのリリース/タグ
2。 ワークフローを展開すると、リリースアセットが発見され、`public/skills/index.json`が構築されます。
3. `/skills`のページの`public/skills/index.json`とスキルドキュメントのUIフェッチ。
- アドバイザリーフィードフロー:
1. `poll-nvd-cves.yml`および`community-advisory.yml`の更新`advisories/feed.json`。
2. 飼料は署名され、公道に映ります。
3. Runtime hooks/scripts はローカル署名されたコピーにリモートフィードとフォールバックをロードします。
- ガードされた取付けの流れ:
1。 インストーラ要求の対象スキル+バージョン。
2. アドバイザリー・マッチダーは影響を受けた分光器および重度/リスクヒントを点検します。
3. 終了コード42は、アドバイザリーが一致したときに2番目の確認を実施します。
##ダイアグラム
```mermaid
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"]
```
![Prompt Line Motif](../assets/architecture_img_01_prompt-line.svg)
## インターフェイスと契約
| インターフェース | 受託フォーム | 検証 |
| お問い合わせ |
| スキルメタデータ | `skills/*/skill.json` | Python ユーティリティ + CI 版画チェックで検証 お問い合わせ
| アドバイザリーフィード | JSON + Ed25519 を取り外すシグネチャ | `feed.mjs` と NanoClaw のシグネチャユーティリティで検証 お問い合わせ
| チェックサムスマニフェスト | `checksums.json`(+オプションの`.sig`) | ペイロードを信頼する前に追跡・ハッシュマッチング お問い合わせ
お問い合わせ ホックイベントインターフェース | `HookEvent`(`type`、`action`、`messages`) | ランタイムハンドラは、選択したイベント名だけを処理します。 お問い合わせ
| ワークフローリリース命名 | タグパターン `<skill>-vX.Y.Z` | リリース・デメリットのワークフローで解析し、スキルを身につける お問い合わせ
ツイート 主変数
| パラメーター | デフォルト | 効果 |
| お問い合わせ |
| `CLAWSEC_FEED_URL` | `https://clawsec.prompt.security/advisories/feed.json` | スイートスクリプト・ホックの遠隔アドバイザリーソース お問い合わせ
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | 一時無辞フォールバック対応可能 お問い合わせ
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | 利用可能なチェックサムマニフェスト検証が必要です。 お問い合わせ
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | アドバイザリー・ホックのためのスキャン回転窓 お問い合わせ
| `CLAWSEC_SKILLS_INDEX_TIMEOUT_MS` | `5000` | リモート・スキル・インデックスは、カタログの発見のためのタイムアウトを取得します。 お問い合わせ
| `PROMPTSEC_GIT_PULL` | `0` | ウォッチドッグオーディション前のオプションオートプル お問い合わせ
## エラー処理と信頼性
- フィードのフェッチングは、無効なシグネチャとmalformedマニフェストのために不閉鎖されます。
- 遠隔フェッチの失敗はローカル署名された供給に優雅に落ちます。
- ホックの状態は支えられる厳密なモードと原子ファイル書き込みを使用します。
- UIページでは、HTMLフォールバックがJSONとして機能し、破損したデータをレンダリングすることを避けます。
- ワークフロー手順は、キーフィンガープリントの一貫性を強化し、スプリットキードリフトを回避します。
## サンプルスニペット
```tsx
// 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>
```
```ts
// Guarded feed loading contract in advisory hook
const remoteFeed = await loadRemoteFeed(feedUrl, {
signatureUrl: feedSignatureUrl,
checksumsUrl: feedChecksumsUrl,
checksumsSignatureUrl: feedChecksumsSignatureUrl,
publicKeyPem,
checksumsPublicKeyPem: publicKeyPem,
allowUnsigned,
verifyChecksumManifest,
});
```
## 実行時間と展開
| 稼働時間表 | 実行モデル | 出力 |
| お問い合わせ |
| Viteアプリ(`npm run dev`) | ローカルフロントエンドサーバー | フィード/スキルのインタラクティブウェブアプリ お問い合わせ
| GitHub CI | マルチOS マトリックス + 専用ジョブ | リント/タイプ/ビルド/セキュリティとテストの信頼性 お問い合わせ
お問い合わせ スキルリリースワークフロー | タグ主導の公開 + PR ドライランチェック | リリースアセット, 署名済みのチェックサム, オプションの ClawHub 公開. お問い合わせ
お問い合わせ ページはワークフローをデプロイ | CI/Release の成功によるトリガ | 静的サイト + 顧問/リリースをミラーリングしました。 お問い合わせ
| Runtime hooks | OpenClaw イベントホック / NanoClaw IPC | 諮問的アラート、判断、完全性チェック お問い合わせ
##スケーリングノート
- NVD のポーリングで置かれるキーワードが付いている Advisory の容積スケール; dedupe およびポストろ過制御騒音。
- ワークフロープロセスのリリースリストをデプロイし、インデックス出力で最新のスキルバージョンを維持します。
- スキルフォルダによるモジュール境界により、フロントエンド構造を変更することなく新しいセキュリティ機能を追加できます。
- ペイロードサイズ(フィード/マニフェスト)が小さいため、シグネチャー検証パスは軽量です。
## ソース参照
- App.tsxアプリ
- ページ/SkillsCatalog.tsx
- ページ/フィードSetup.tsx
- ページ/AdvisoryDetail.tsx
- ページ/WikiBrowser.tsx
- スキル/クローセスイート/ホック/クローセ-アドバイザー/ハンドラー.ts
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/clawsec-suite/scripts/discover_skill_catalog.mjs
- スキル/クローセ・ナンクロー/lib/advisories.ts
- スキル/クローセ-ナンクロー/lib/signatures.ts
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
wiki/ja/configuration.md
+93
View File
@@ -0,0 +1,93 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../configuration.md
Review status: draft
-->
# 設定
## スコープ
- 設定は、フロントエンドのビルド設定、ランタイムフィードパス、ワークフロートリガー、およびスキルメタデータ契約を組み合わせます。
- ほとんどのランタイムに敏感な制御は`CLAWSEC_`か`OPENCLAW_`とプレフィックスした環境変数です。
- パス正規化は、セキュリティに敏感であり、意図的に未解決の家庭トークンリテラルを拒否します。
## コアランタイム変数
| 変数 | デフォルト | によって使用される |
| お問い合わせ |
| `CLAWSEC_FEED_URL` | ホストアドバイザリーURL | スイートホークとガードドインストーラーの読み込み お問い合わせ
| `CLAWSEC_FEED_SIG_URL` | `<feed>.sig` | 組織図鑑 | 組織図鑑 お問い合わせ
| `CLAWSEC_FEED_CHECKSUMS_URL` | フィードURL付近の`checksums.json` | 任意チェックサムマニフェストソース お問い合わせ
| `CLAWSEC_FEED_PUBLIC_KEY` | スイートローカルPEMファイル | 特筆記検証 お問い合わせ
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | 一時移行バイパスの旗 お問い合わせ
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | チェックサム・マニフェスト検証を有効にします。 お問い合わせ
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | アドバイザリーホックスキャンスロットル お問い合わせ
## パスの決議規則
| ルール | 行動 | 施行拠点 |
| お問い合わせ |
| `~` 拡張 | 自宅のディレクトリに解決 | スイート/ウォッチドッグスクリプトで共有されたパスユーティリティ機能 お問い合わせ
| `$HOME` / `${HOME}` 拡張 | エスケープ時に解決 | 同じユーティリティ. お問い合わせ
お問い合わせ Windowsホームトークン | `%USERPROFILE%`, `$env:USERPROFILE` 正規化 | 同じユーティリティ. お問い合わせ
| エスケープされたトークン(`\$HOME`) | 明示的なエラーで拒否 | 誤ってリテラルディレクトリの作成を防止します。 お問い合わせ
| 無効な明示的なパス | 警告でデフォルトパスにフォールバックできる | `resolveConfiguredPath`ヘルパー お問い合わせ
## フロントエンドとビルド構成
- `vite.config.ts`はポート(`3000`)、ホスト(`0.0.0.0`)、パスエイリアス(`@`)を定義します。
- `index.html`の提供 Tailwind ランタイムの設定、カスタムフォント、ベースカラートークン。
- `tsconfig.json`は、バンドルモジュールの解像度、`noEmit`、およびJSXランタイムの設定を使用します。
- `eslint.config.js`はTS、React、hooks、およびスクリプト固有のlintルールを適用します。
## スキルメタデータ 仕様
| フィールドグループ | 所在地 | 機能 |
| お問い合わせ |
お問い合わせ コアスキルアイデンティティ | `skills/*/skill.json` | 名称・バージョン・著者・ライセンス・記述メタデータ お問い合わせ
| SBOMファイル一覧 | `skill.json -> sbom.files` | 決定版リリース必須項目です。 お問い合わせ
| プラットフォームメタデータ | `openclaw` または `nanoclaw` ブロック | CLI 要件、トリガー、プラットフォームヒント お問い合わせ
| スイートカタログメタデータ | `skills/clawsec-suite/skill.json -> catalog` | スイートメンバーの統合/デフォルト/一貫性のある動作 お問い合わせ
## ワークフロー構成
- スケジュール設定は、`cron`エントリー(`poll-nvd-cves`、`codeql`、`scorecard`)のワークフローに含まれています。
- リリースワークフローでは、タグのネーミングパターン`<skill>-v<semver>`が期待しています。
- 展開ワークフローは、CI/release `workflow_run`イベントとマニュアルディスパッチで起動します。
- 複合署名アクションは、秘密鍵入力を必要とし、署名直後に署名を検証します。
## サンプルスニペット
```bash
# run guarded install with explicit local signed feed paths
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```
```json
{
"name": "example-skill",
"version": "1.2.3",
"sbom": {
"files": [
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
]
}
}
```
## 操作上の注意
- リポジトリの外にキーを署名し、GitHubの秘密を経由して注入してください。
- ローカル環境変数上書きの絶対パスまたは省略されたホーム式を優先します。
- 一時的なマイグレーション サポートとして署名されていないフィード モードを、正常な操作は扱いません。
- 壊れたアーティファクトの参照を避けるために`SKILL.md` URLを編集するとき再実行の解放リンクの検証。
## ソース参照
- vite.config.ts
- インデックス.html
- tsconfig.json
- eslint.config.js ディレクティブ
- スキル/ clawsec-suite/skill.json
- スキル/clawsec-nanoclaw/skill.json
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs
- スキル/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スクリプト/validate-release-links.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/skill-release.yml
- .github/actions/sign-and-verify/action.yml
wiki/ja/data-flow.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../data-flow.md
Review status: draft
-->
ツイート データフロー
## プライマリフロー
- `Advisory ingestion`:NVD/communityの入力は顧客のために、署名された正常化された諮問的な供給に変えられます。
- `Skill catalog publication`: リリースアセットが発見され、`public/skills/index.json`とパースキルのドキュメント/チェックサムに変換されます。
- `Runtime enforcement`: スイートとナノクローの消費者は、アドバイザリーデータをロードし、スキルと一致し、アラートや確認ゲートを発します。
- - - このページは、`INDEX.md`の`Guides`セクションで表示されます。
## ステップバイステップ
1。 フィードプロデューサーワークフロー/スクリプトフェッチソースデータ (`NVD API` または発行ペイロード).
2。 JSON は、ロジックが重度/種類/影響領域を正規化し、アドバイザリー ID による重複排除を行います。
3。 シグネチャー/チェックサムのステップは、分離されたシグネチャとチェックサムマニフェストを生成します。
4。 `public/`と`public/releases/latest/download/`でワークフローミラー署名済みのアーティファクトを展開します。
5。 UI 消費者は JSON 形状/コンテンツを検証します。ランタイムの消費者は、フィードデータを信頼する前に、署名/チェックサムを検証します。
6。 Matchers は、`affected` の仕様をスキル名/バージョンに比較し、アラートを発したり、確認を強制したりします。
## 入力と出力
入力/出力は下の表でまとめられます。
| 種類 | お名前 | 所在地 | 概要 |
| お問い合わせ |
| 入力 | CVE ペイロード | `services.nvd.nist.gov/rest/json/cves/2.0` | ClawSec キーワードでフィルタリングされた脆弱性 お問い合わせ
| 入力 | コミュニティアドバイザリー問題 | `.github/workflows/community-advisory.yml`イベントペイロード | メンテラー承認問題がアドバイザリーレコードに変身 お問い合わせ
| 入力 | スキルリリースアセット | GitHub リリース API + アセット | ウェブカタログ作成・ミラーダウンロード お問い合わせ
| 入力 | ローカルコンフィグ/env | `OPENCLAW_AUDIT_CONFIG`、`CLAWSEC_*` vars | フィードの経路制御・抑制・検証の動作 お問い合わせ
| 出力 | アドバイザリーフィード | `advisories/feed.json` | キヤノンレポジトリフィード お問い合わせ
| アウトプット | アドバイザリーシグネチャ | `advisories/feed.json.sig` | フィード認証のデタケドシグネチャ お問い合わせ
| アウトプット | スキルカタログ | `public/skills/index.json` | `/skills`ページで使用されるランタイムウェブカタログ お問い合わせ
| アウトプット | リリースチェックサム・サイン | `release-assets/checksums.json(.sig)` | リリースコンシューマー向け整合性マニフェスト お問い合わせ
| 出力 | ホックの状態 | `~/.openclaw/clawsec-suite-feed-state.json` | スキャンのタイミングを追跡し、一致を通知して下さい。 お問い合わせ
ツイート データ構造
| 構成 | 主要分野 | 目的 |
| お問い合わせ |
| アドバイザリーフィードレコード | `id`、`severity`、`type`、`affected[]`、`published` | UIやインストーラーが使用するリスクデータの単位 お問い合わせ
| スキルメタデータレコード | `id`、`name`、`version`、`emoji`、`tag` | ウェブ閲覧・インストールの行 お問い合わせ
| チェックサムスマニフェスト | `schema_version`, `algorithm`, `files` | 予想される消化器の名前をマップします。 お問い合わせ
| 諮問状態 | `known_advisories`、`last_hook_scan`、`notified_matches` | 繰り返しのアラートやスロットルのスキャンを防ぎます。 お問い合わせ
| Suppression config | `enabledFor[]`, `suppressions[]` | `checkId` + `skill` によるスキップリストの対象となります。 お問い合わせ
##ダイアグラム
```mermaid
flowchart LR
A["NVD + Issue Inputs"] --> B["Transform + Deduplicate"]
B --> C["advisories/feed.json"]
C --> D["Sign + checksums"]
D --> E["public/advisories + releases/latest"]
E --> F["Web UI fetch"]
E --> G["Suite/NanoClaw verification"]
G --> H["Match skills + emit alerts/gates"]
```
## 状態とストレージ
| 店舗 | パス・スコープ | パス |
| お問い合わせ |
| キヤノンのアドバイザリー | `advisories/` | NVD + コミュニティワークフローとローカルのポピュレーションスクリプト お問い合わせ
お問い合わせ 組込みアドバイザリーコピー | `skills/clawsec-feed/advisories/` と `skills/clawsec-suite/advisories/` | 同期/包装プロセスとリリースワークフロー お問い合わせ
| パブリックミラー | `public/advisories/`、`public/releases/` | ワークフローの展開 お問い合わせ
| 稼働時間状態 | `~/.openclaw/clawsec-suite-feed-state.json` | 諮問ホックの状態の永続性。 お問い合わせ
| NanoClawキャッシュ | `/workspace/project/data/clawsec-advisory-cache.json` | ホスト・サイド・アドバイザリー・キャッシュ・マネージャー お問い合わせ
| 整合状態 | `/workspace/project/data/soul-guardian/`(ナノクロー) | 整合性モニターベースライン・オーディオストレージ お問い合わせ
## サンプルスニペット
```bash
# Local feed flow (NVD fetch -> transform -> sync)
./scripts/populate-local-feed.sh --days 120
jq '.updated, (.advisories | length)' advisories/feed.json
```
```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
## 失敗モード
- NVD率の限界(`403/429`)は送りを遅らせ、retries/backoffを要求できます。
- 欠損または無効な離脱署名により、異常終了モードのフィード拒否が発生します。
- JSONエンドポイントのHTMLフォールバック応答は、明示的にフィルタリングされていない限り、偽陽性を生成できます。
- パストークンの誤設定(`\$HOME`)は、ローカルのフォールバックパスの解像度を破ることができます。
- ワークフローで公開鍵のフィンガープリントをミスマッチして、ハードなCI障害が発生します。
## ソース参照
- アドバイザリー/フィード.json
- アドバイザリー/フィード.json.sig
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- スキル/クローセスイート/ホック/クローセ-アドバイザー/lib/state.ts
- スキル/クローセスイート/ホック/クローセ管理人/lib/matching.ts
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/クローセ・ナンクロー/lib/advisories.ts
- スキル/法律/犯罪サービス/アドバイザー/キャッシュ.ts
wiki/ja/dependencies.md
+106
View File
@@ -0,0 +1,106 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../dependencies.md
Review status: draft
-->
# 依存関係
##ビルドとランタイム
| レイヤー | プライマリ依存 | プライマリ依存症 | なぜそれが存在なのか |
| お問い合わせ |
| フロントエンドのランタイム | `react`、`react-dom`、`react-router-dom`、`lucide-react` | UIのレンダリング、ルーティング、アイコングラフィ。 お問い合わせ
| マークダウンレンダリング | `react-markdown`、`remark-gfm` | レンダリング・スキル・ドキュメント/readmes、アプリ内ウィキマークダウンページ お問い合わせ
| ビルドツーリング | `vite`, `@vitejs/plugin-react`, `typescript` | 速いTS/TSX束縛と生産ビルド. お問い合わせ
| python ユーティリティ | stdlib + `ruff`/`bandit` ポリシー から `pyproject.toml` | 検証・パッケージのスキルと静的なチェックを実行します。 お問い合わせ
お問い合わせ シェルオートメーション | `bash`、`jq`、`curl`、`openssl`、`sha256sum`/`shasum` | フィードポーリング、サイン、チェックサム生成、リリースチェック。 お問い合わせ
## 依存性の詳細
| パッケージ | バージョン制約 | スコープ |
| お問い合わせ |
| `react` / `react-dom` | `^19.2.4` | フロントエンドランタイム |
| `react-router-dom` | `^7.13.1` | フロントエンドルーティング |
| `lucide-react` | `^0.575.0` | UIアイコンセット |
| `vite` | `^7.3.1` | 開発サーバー | ビルド |
| `typescript` | `~5.8.2` | タイプチェック |
| `eslint` | `^9.39.2` | JS/TSライニング |
| `@typescript-eslint/*` | `^8.55.0` / `^8.56.0` | TSXQTOKEN2QXZ | ツ・リントパーサ・ルール |
| `fast-check` | `^4.5.3` | 物件・機能テスト |
| オーバーライド | ピン留め版 | ライエーレ |
| お問い合わせ |
| `ajv` | `6.14.0` | セキュリティと互換性の安定化 お問い合わせ
| `balanced-match` | `4.0.3` | トランジティブ脆弱性制御 お問い合わせ
| `brace-expansion` | `5.0.2` | 移行依存症の硬化 お問い合わせ
| `minimatch` | `10.2.1` | 決定的な依存行動 お問い合わせ
## 外部サービス
| サービス | ご利用 | | ご利用条件 | ご利用条件 |
| お問い合わせ |
| NVD API(`services.nvd.nist.gov`) | `poll-nvd-cves` ワークフロー + ローカルフィードスクリプト | キーワード/日付ウィンドウでCVEをプルする お問い合わせ
| GitHub API | ワークフローの展開・リリース | リリースの発見、アセットのダウンロード、出力の公開 お問い合わせ
| GitHub Pages | ワークフローの展開 | 静的なサイトを運営し、アーティファクトを映す お問い合わせ
| ClawHub CLI/registry | スクリプトのインストール + オプションの公開ジョブ | インストールと公開スキル. お問い合わせ
| オプションのローカルSMTP/sendmail | `openclaw-audit-watchdog`スクリプト | 監査報告書をメールで配信 お問い合わせ
## 開発ツール
| ツール | 呼び出し | 取材 | 取材 |
| お問い合わせ |
| ESLint | `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0` | フロントエンド・スクリプト・ライニング お問い合わせ
| TypeScript | `npx tsc --noEmit` | コンパイル時間TS契約チェック お問い合わせ
| ラフ | `ruff check utils/` | パイソンスタイルとバグパターンチェック お問い合わせ
| バンディット | `bandit -r utils/ -ll` | python セキュリティー検査 お問い合わせ
| トライビー | ワークフロー + ローカルラン | FS/config 脆弱性スキャン お問い合わせ
| Gitleaks | `scripts/prepare-to-push.sh` オプションのローカルラン | プッシュ前のシークレットリーク検出 お問い合わせ
## サンプルスニペット
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.4",
"react-router-dom": "^7.13.1"
}
}
```
```toml
[tool.ruff]
target-version = "py310"
line-length = 120
[tool.bandit]
exclude_dirs = ["__pycache__", ".venv"]
skips = ["B101"]
```
## 互換性のノート
- `date`と`stat`の使用におけるmacOSとLinuxの違いに対するローカルスクリプトアカウント。
- 一部のワークフロー/スクリプトでは、Ed25519と`pkeyutl -rawin`で使用されるOpenSSL機能が必要です。
- Windows サポートはNodeベースの工具細工のために最も強いです;POSIXの貝パスはWSL/Git Bashを必要とするかもしれません。
- 供給の消費者は移住段階のための両立性バイパスを含んでいます、署名されたモードは意図された安定した状態です。
## 検証ノート
- スキルリリースタグは、`<skill>-v<semver>` をフォローし、CI/deploy 自動化によって解析されます。
- PR検証は、`skill.json`と`SKILL.md`のフロントマッター間でのバージョンパティを強化します。
- - - パブリックスキル指数は、UI表示のためのスキルごとに最新の発見されたバージョンを保持します。
- 署名されたアーティファクトマニフェスト(`checksums.json`)は、リリースごとにバージョンアップされ、ファイルハッシュとURLが含まれています。
## ソース参照
- パッケージ.json
- パッケージ-lock.json
- pyproject.toml
- eslint.config.js ディレクティブ
- tsconfig.json
- スクリプト/prepare-to-push.sh
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
wiki/ja/exploitability-scoring.md
+425
View File
@@ -0,0 +1,425 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../exploitability-scoring.md
Review status: draft
-->
# Exploitability Scoring 方法論
## 概要
ClawSecの悪用性スコアリングシステムは、AIエージェントの展開(OpenClaw/NanoClaw)用に特別に設計されたコンテキスト・ウェアの脆弱性評価を提供します。 すべての環境を均等に扱う一般的なCVSSスコアとは異なり、当社のスコアリングは、アラート疲労を軽減し、実用的な脅威を優先するAIエージェントのユニークな攻撃面と使用パターンを考慮する。
## スコアリングレベル
| レベル | 重症 | 意味 |
お問い合わせ
| `high` | クリティカル・ハイ | 代表的な代理店の展開で期待できる |
| `medium` | ミディアム | 構成、保証調査 |
| `low` | 低 | エージェントのコンテキスト、低優先順位 |
| `unknown` | 不明 | 悪用性を評価するための十分なデータ |
## スコアリング工場
################################################################################################################################################################################################################################################################ 1. CVSSベーススコア(ベースライン)
分析は、CVSSベーススコアを基礎として開始します。
-**CVSS ≥ 9.0**:クリティカルな重度 → 初期スコア `high`
- **CVSS 7.0-8.9**: 高重度 → 初期スコア `high`
- **CVSS 4.0-6.9**: 中程度の重度 → 初期スコア `medium`
- **CVSS 1.0-3.9**:低重度 → 初期スコア `low`
- **CVSS**なし: → 初期スコア `unknown`の特長
################################################################################################################################################################################################################################################################ 2. 攻撃ベクトル解析(CVSSメトリクス)
アナライザは、CVSS v2、v3.0、v3.1 ベクトルを解析して評価します。
####ネットワークのアクセシビリティ
-**AV:N**(ネットワーク):ネットワーク上でリモートで利用
-**AV:A**(隣接):ローカルネットワークアクセスを要求します
- ** AV:L** (ローカル):ローカル システム アクセスを要求して下さい
- **AV:P** (物理的):物理的なアクセスを要求して下さい
**エージェントへの影響**: エージェントはネットワークサービスとして実行したり、外部API呼び出しを行うため、ネットワークアクセス可能な脆弱性が高まります。
####認証要件
-**PR:N / Au:NONE**:認証不要 → スコアアップ
-**PR:L / Au:SINGLE**:必要な低い特権
-**PR:H / Au:MULTIPLE**:高い特権が必要 → スコアを削減
**エージェントへの影響**: 未認証の悪用は、一般に公開されたエージェント API には不可欠です。
#### ユーザーインタラクション
-**UI:N**:ユーザーインタラクションは必要ありません → スコアを上昇させる
-**UI:R**:ユーザーインタラクションを要求し、スコアを削減
**エージェントへの影響**: エージェントは自律的に動作することが多いため、ユーザインタラクションが必要な脆弱性はあまり重要ではありません。
###### 攻撃の複雑さ
- **AC:L**:低い複雑さ→の上昇のスコア
-**AC:M / AC:H**:中/高複雑→中立またはスコアを減らす
**エージェントへの影響**: 低複雑性悪用は、大量攻撃で自動化され、使用される可能性が高い。
################################################################################################################################################################################################################################################################ 3. 脆弱性タイプ(採用コンテキスト)
ClawSecは、脆弱性タイプがAIエージェントのデプロイメントにどのように影響するかに基づいてスコアを調整します。
#### エージェントコンテキスト内の高リスクタイプ
**リモートコード実行(RCE)* * 必須
```
Score: Always HIGH
Rationale: RCE is critical in agent deployments
```
AIエージェントは、その機能の一部として任意のコードを実行します。 RCEの脆弱性により、攻撃者がハイジャックエージェントの実行フローを解除したり、資格情報を公開したり、他のシステムにピボットしたりすることができます。
**サーバー・サイド・リクエスト・フォージェリ(SSRF)* * 必須
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: SSRF affects agents making external requests
```
エージェントは、外部 API を頻繁に呼び出し、内部サービスにアクセスし、リモートリソースを取得します。 SSRF は、攻撃者を次のようになります。
- 内部クラウドメタデータサービス(AWS IMDSv1、GCPメタデータ)にアクセス
- 社内ネットワークへのピボット
- DNSトンネリングによるデータの抽出
**Path Traversal / ディレクトリ Traversal* * 必須
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: Path traversal affects agents with file access
```
エージェントはファイルを読み、スクリプトを実行し、コードベースを管理します。 パス・トラバーサールは以下を可能にします。
- 機密設定ファイル(.env、認証情報)の読み込み
- SSHキー、APIトークンへのアクセス
- 重要なシステムファイルを上書き
**Commandの注入**
```
Score: Always HIGH
Rationale: Command injection is critical in agent deployments
```
RCEと同様に、エージェントはシステムとやり取りするためにシェルコマンドを実行します。 コマンドインジェクションにより、フルシステムの妥協を許します。
#### 中リスクタイプ
**プロトタイプ汚染(Node.js)* * 必須
```
Score: Elevated from LOW to MEDIUM
Rationale: Prototype pollution can escalate in Node.js agents
```
Node.js 上で実行される多くのエージェントフレームワーク。プロトタイプの汚染は、以下につながる可能性があります。
- 認証チェックのバイパス
- 特権エスカレーション
- サービスの拒否
**SQLの注入/NoSQLの注入**
```
Score: Elevated to HIGH if network-accessible and unauthenticated
Rationale: Injection affects agents with database access
```
会話履歴、ユーザーデータ、またはデータベース内のツール結果を保存するエージェントは、インジェクション攻撃に脆弱です。
####下リスクタイプ
**クロスサイトスクリプト(XSS)* * 必須
```
Score: Reduced to MEDIUM if not network-accessible
Rationale: XSS has limited impact in headless agents
```
エージェントは、通常、ブラウザでHTMLをレンダリングせず、XSSの影響を軽減します。 しかし、エージェント管理 UI やチャットインターフェースの XSS は懸念が残っています。
################################################################################################################################################################################################################################################################ 4. 空室状況
`--check-exploits`が有効になっている場合、アナライザはパブリックエクスプロイトのリファレンスURLをチェックします。
**明示的な表示器:**
- 悪用-db.com/悪用-database.com
- パケットtormsecurity.com
- github.com/exploit、github.com/poc
- metasploitフレームワークモジュール
- 「/exploit」、「/poc」、「/proof-of-concept」を含むURL
**スコアの高度:**
- `low` → `medium` (利用できるexploit)
- `medium` → `high` (利用できるexploit)
- `unknown` → `medium` (exploit available + CVSS > 0 )
**Rationale**: 公共は攻撃者のためのスキル障壁を下げ、自動搾取の可能性を高めます。
## スコアリングアルゴリズム
アナライザはこの決定ツリーに従います。
```
1. Parse CVSS score → set baseline (high/medium/low/unknown)
2. Parse CVSS vector → analyze attack characteristics
3. Adjust for attack vector:
- Network-accessible + no auth + no UI → elevate to HIGH
- Local-only access → reduce HIGH to MEDIUM
4. Adjust for vulnerability type:
- Check against agent-specific risk categories
- Elevate or reduce score based on deployment context
5. Check for public exploits (if enabled):
- Elevate score if exploits detected
6. Generate rationale explaining the final score
```
## 例
##例1:クリティカルなRCE(高感度)
```json
{
"cve_id": "CVE-2024-12345",
"cvss_score": 9.8,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"type": "remote_code_execution",
"description": "Unauthenticated RCE in Express.js framework"
}
```
**分析の出力:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments"
}
```
**なぜハイ**:クリティカルCVSS +ネットワークアクセス可能+オースなし+ RCEタイプ。
##例2:エージェントAPIのSSRF(高感度)
```json
{
"cve_id": "CVE-2024-23456",
"cvss_score": 7.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:L",
"type": "server_side_request_forgery",
"description": "SSRF in webhook handler allows internal network access"
}
```
**分析の出力:**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "High CVSS score (7.3); remotely exploitable without authentication; SSRF affects agents making external requests"
}
```
**ハイ**: SSRF は、API 呼び出しを行うエージェントに不可欠です。 認証なしでアクセス可能でリスクが高まります。
##例3:公共の爆発を伴うパストラバース(高感度)
```json
{
"cve_id": "CVE-2024-34567",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"type": "path_traversal",
"references": [
"https://exploit-db.com/exploits/51234",
"https://nvd.nist.gov/vuln/detail/CVE-2024-34567"
]
}
```
**分析出力(--check-exploitsと):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (6.5); network accessible; path traversal affects agents with file access; public exploit available (1 source)"
}
```
**ハイ**:パストラバース+エージェントファイルアクセス+公共利用は、中型CVSSを高悪用性に高めます。
## 例4:エージェントUIのXSS
```json
{
"cve_id": "CVE-2024-45678",
"cvss_score": 7.1,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:L",
"type": "cross_site_scripting",
"description": "Stored XSS in agent management dashboard"
}
```
**分析の出力:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (7.1); network accessible; XSS has limited impact in headless agents"
}
```
**Why MEDIUM**:高いCVSSにもかかわらず、XSSはエージェントのデプロイメント(ヘッドレス操作)ではあまり重要ではありません。 ユーザーインタラクションが必要です。
## 例5: ローカル特権のエスカレーション(媒体の説明)
```json
{
"cve_id": "CVE-2024-56789",
"cvss_score": 8.8,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
"type": "privilege_escalation",
"description": "Local privilege escalation via symbolic link attack"
}
```
**分析の出力:**
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (8.8); requires local access"
}
```
**医療**:高いCVSSにもかかわらず、ローカルアクセスが必要です。 エージェントは、通常、ローカルエスカレーションが限られた影響を持っているコンテナ化された/サンドボックス化された環境で実行されます。
##例6:Exploitによる試作汚染(高感度)
```json
{
"cve_id": "CVE-2024-67890",
"cvss_score": 5.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N",
"type": "prototype_pollution",
"description": "Prototype pollution in lodash merge function",
"references": [
"https://github.com/exploit/prototype-pollution-poc",
"https://snyk.io/vuln/SNYK-JS-LODASH-1234567"
]
}
```
**分析出力(--check-exploitsと):**
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (5.3); remotely exploitable without authentication; prototype pollution can escalate in Node.js agents; public exploit available (1 source)"
}
```
**なぜハイ**:Node.jsエージェントのプロトタイプ汚染 + 公開悪用 + authなしでアクセス可能 = 適度なCVSSにもかかわらず高いリスク。
#ClawSec ワークフローでの ## 利用
###自動スキャリング(NVDフィード)
`poll-nvd-cves.yml`ワークフローは、新しいCVEを自動的にスコアします。
```bash
# Workflow step
python utils/analyze_exploitability.py --json --check-exploits < cve-data.json
```
`advisories/feed.json`のアドバイザリーには、以下が含まれます。
```json
{
"id": "CVE-2024-12345",
"severity": "high",
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments",
"attack_vector_analysis": {
"is_network_accessible": true,
"requires_authentication": false,
"requires_user_interaction": false,
"complexity": "low"
}
}
```
## マニュアル分析
セキュリティ研究者は、CVEを手動で分析することができます。
```bash
# Basic analysis
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"type":"ssrf"}' | \
python utils/analyze_exploitability.py --json
# With exploit detection
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"references":["https://exploit-db.com/exploits/51234"]}' | \
python utils/analyze_exploitability.py --json --check-exploits
```
## Exploitability によるフィルタリング
ユーザーは、悪用性スコアでアドバイザリーをフィルタリングすることができます。
```bash
# Get only high-exploitability advisories
curl -s https://clawsec.prompt.security/feed.json | \
jq '.advisories[] | select(.exploitability_score == "high")'
# Prioritize by exploitability and severity
curl -s https://clawsec.prompt.security/feed.json | \
jq '[.advisories[] | select(.exploitability_score == "high" and .severity == "critical")] | sort_by(.cvss_score) | reverse'
```
## バックフィルディング・アドバイザリー(歴史的メンテナンス)
`scripts/backfill-exploitability.sh`は、リポジトリのメンテナンスのための歴史的なメンテナユーティリティとして保持されます。
通常のアドバイザリー世代の主流ではありません。
優先パス:
1。 CI の正式なパス: NVD ワークフローを init/reset で実行し、NVD のアドバイザリーを再構築し、パイプラインのアーティファクトに署名します。
2。 ローカル開発者パス: `./scripts/populate-local-feed.sh --force` を実行して、ローカルフィードを悪用性のコンテキストで再人口化します。
既に存在しているレガシーフィードコンテンツを明示的に修復するときにのみ、バックフィルを使用してください。
## コミュニティ貢献
コミュニティメンバーは、悪用性評価を提出することができます。
1。 **GitHub の問題による報告**: 悪用性文脈で CVE を報告するために、アドバイザリーテンプレートを使用する
2。 **Automated Analysis**: `community-advisory.yml`ワークフローはコミュニティ報告されたCVEを自動的に得ます
3。 **Manual Review**: 保守者のレビューと悪用性評価の承認
4。 **Feed Update**: 承認されたアドバイザリーは、悪用スコアのフィードに追加されます
## 限界と未来の仕事
##現在の制限
1。 **統計分析**: スコアリングは動的ランタイム解析ではなく、CVEメタデータに基づいています
2.**バージョン検出なし**:特定のバージョンが脆弱であるかどうかはチェックしません
3。 **バイナリ分類**: 部分的な緩和や防衛の深さを考慮することはありません
4。 **限られたコンテキスト**:正確なエージェントの構成やデプロイされたツールがわからない
###将来の強化
1。 **EPSSインテグレーション**:EPSS(Exploit Prediction Scoring System)の確率スコアを組み込む
2。 **KEV Matching**:CISA KEV(Known Exploited Vulnerabilities)カタログのクロスリファレンス
3。 **エージェントプロファイリング**: デプロイされたエージェントの機能と公開された API を検討する
4。 **運転検出**:WAF規則、サンドボックス、その他の補償制御の確認
5。 **MLベースの規模**: 歴史データに基づく悪用性を予測するために機械学習を使用する
## リファレンス
-**CVSS v3.1仕様**:[https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document)
- **CVSS v2 ガイド**:[https://www.first.org/cvss/v2/guide](https://www.first.org/cvss/v2/guide)
- **EPSS**: [https://www.first.org/epss/](https://www.first.org/epss/)
- **CISA KEV**:[https://www.cisa.gov/known-exploited-vulnerabilities-catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- **NVD API**:[https://nvd.nist.gov/developers/vulnerabilities](https://nvd.nist.gov/developers/vulnerabilities)
ツイート 貢献する
悪用性のスコアリング方法論を改善するため:
1。 **テストケースを省略**:`utils/analyze_exploitability.py`にテストケースを追加
2。 **False Positives/Negatives** の報告: CVE の例でGitHub の問題を開いた
3。 **スコープアジャスメントの提案**: 合理的かつ例でPRを提出する
4。 **シェアエージェントコンテキスト**:エージェント固有の脆弱性パターンの投稿
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
お問い合わせ
**によって維持される**: [Prompt Security](https://prompt.security)
**ライセンス**:AGPL-3.0-or-later
**最終更新**:2026-03-01
wiki/ja/glossary.md
+62
View File
@@ -0,0 +1,62 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../glossary.md
Review status: draft
-->
ツイート 用語集
## 利用規約
| 用語 | 定義 |
| お問い合わせ |
| アドバイザリーフィード | スキル/プラットフォームのセキュリティアドバイザリーを含むJSON文書(`feed.json`) お問い合わせ
| `skill@1.2.3`、ワイルドカード、マッチングロジックで使用される範囲などのスキルセレクター お問い合わせ
| ガードド インストール | アドバイザーが一致したときに明示的な確認を必要とする2段階のインストーラーの動作。 お問い合わせ
| SBOMファイル | 包装・検証に用いられる`skill.json`における技術実証済みのアーティファクトリスト お問い合わせ
| 別売のシグネチャー | ベース64 署名ファイル(`.sig`)は、署名されたペイロードから別途保存されます。 お問い合わせ
| チェックサムマニフェスト | ペイロードの完全性を検証するために使用されるファイルハッシュマップ(`checksums.json`) お問い合わせ
## スキル包装条件
| 用語 | 定義 |
| お問い合わせ |
| スキルタグ | リリース自動化で使われる`<skill>-v<semver>`としてフォーマットされたGitタグ。 お問い合わせ
| リリースアセット | GitHub リリースに添付されているファイル(zip、`skill.json`、チェックサム、シグネチャ) お問い合わせ
| カタログのインデックス | `public/skills/index.json`, ウェブカタログで消費される生成リスト お問い合わせ
| 組込み部品 | 別々に含まれている1つのスキルからの機能束(例えばスイートで埋め込まれる供給のために)。 お問い合わせ
## 諮問とセキュリティ規約
| 用語 | 定義 |
| お問い合わせ |
| フェイルクローズド検証 | 署名またはチェックサム検証が失敗した場合のペイロードを差し込みます。 お問い合わせ
| 符号なしの互換性モード | `CLAWSEC_ALLOW_UNSIGNED_FEED=1`で有効な一時的なバイパスパスパス お問い合わせ
| Suppression Rule | 既知の知的/受容性の調査を抑制する`checkId`および`skill`のエントリーマッチングの設定 お問い合わせ
| キー指紋 | キーの一貫性の点検に使用する DER によって符号化される公共のキーの SHA-256 の消化器。 お問い合わせ
##ランタイムとプラットフォーム利用規約
| 用語 | 定義 |
| お問い合わせ |
| OpenClaw Hook | アドバイザリーをチェックするランタイムイベントハンドラ(`clawsec-advisory-guardian`) お問い合わせ
| NanoClaw IPC | 諮問のリフレッシュ、シグネチャ検証、整合性チェックのためのホスト/コンテーナータスク交換 お問い合わせ
| 完全性ベースライン | 保護されたファイルのための承認されたハッシュ/スナップショットを保存しました。 お問い合わせ
| ハッシュチェーン監査ログ | 各エントリーが事前のハッシュに依存する監査ログのみを表示 お問い合わせ
## CI/CD 利用規約
| 用語 | 定義 |
| お問い合わせ |
| NVD CVEs ワークフロー | NVD CVEs をアドバイザリーに送出・変換するワークフローをスケジュール お問い合わせ
| コミュニティ・アドバイザリーワークフロー | 認定コミュニティ・アドバイザリーを発行する課題・ラベル・トリガーワークフロー お問い合わせ
| スキル・リリースワークフロー | スキル・リリース・ワークフロー | タグ・トリガー・パッケージ・署名・出版 パイプライン お問い合わせ
| ページワークフローの展開 | サイトアセットをビルドするワークフローと、リリース/アドバイザーアーティファクトをミラーリングするワークフロー お問い合わせ
## ソース参照
- タイプ。ts
- スキル/ clawsec-suite/skill.json
- スキル/clawsec-nanoclaw/skill.json
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
- スキル/クローセ・ナンクロー/ガーディアン/積分僧侶。ts
- スクリプト/populate-local-feed.sh
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
wiki/ja/localization.md
+71
View File
@@ -0,0 +1,71 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../localization.md
Review status: draft
-->
# ローカリゼーションワークフロー
## 目的
ClawSec README および wiki ページのリピート可能な docs ローカリゼーション パイプラインを定義します。
## スコープ
- ソース言語:英語(`README.md`、`wiki/*.md`)
- 現在の翻訳言語:スペイン語(`README.es.md`、`wiki/es/*.md`)
- 韓国の試験言語:韓国(`README.ko.md`、`wiki/ko/*.md`)
- 将来の言語:`wiki/<lang>/...`と`README.<lang>.md`
## 真実のルールのソース
1。 英語のファイルは正式です。
2. 翻訳は、コマンド、ファイルパス、コードブロック、および識別子を正確に保存する必要があります。
3。 商品名と技術名は翻訳されていないまま(`ClawSec`、`OpenClaw`、`NanoClaw`、`Hermes`、`Picoclaw`、スキルパッケージ名)。
4。 翻訳のカバレッジが部分的である場合、翻訳されたファイルは明示的にスコープを記述する必要があります。
## フォルダー コンベンション
- README 翻訳:
- `README.es.md`
- 未来:`README.fr.md`、`README.de.md`、`README.ja.md`、等。
- ウィキ翻訳:
- `wiki/es/INDEX.md`
- `wiki/es/<page>.md`
- 未来:`wiki/fr/<page>.md`、`wiki/de/<page>.md`、等。
- ローカリゼーションアセット:
- `wiki/i18n/terminology-en-es.md`
- `wiki/i18n/translation-tracker.md`
## ワークフローの更新
1。 **ソースコードの初期化* * 必須
- 翻訳前の明確さと構造のための英語ソースのドキュメントを更新します。
2。 **Record delta **
- `wiki/i18n/translation-tracker.md`で英語ページを変更しました。
3. **Translate changed pages**
- マークダウン構造と見出しレベルを維持します。
- コマンドブロックを無接触に保ちます。
4. **QA pass**
- リンクが解決することを確認します。
- コードブロックとインラインコマンドの検証は変更されません。
- `terminology-en-es.md`を使用した用語集の一貫性を確認します。
5. **Regenerate exports**
- `npm run gen:wiki-llms`を実行します。
6. **Review and PR**
- 翻訳されたページの要約と残りのギャップを含みます。
## 翻訳 QA チェックリスト
- [ ] 階層を保持する。
- [ ] コマンドスニペットは変更され、実行できません。
- [ ] ファイルパスとURLは変更されません。
- [ ] スキルとプラットフォーム名が変更されていない。
- [ ]セキュリティ用語の一貫性。
- [ ] `wiki/INDEX.md`は翻訳リンクエントリを持っています。
- [ ] `wiki/<lang>/INDEX.md`は、翻訳されていないときに重要な英語ページに戻ります。
## おすすめ言語ロールアウト
1。 スペイン語(`es`) - フェーズ1ベースラインで行われます。
2. フランス(`fr`)、ドイツ(`de`)、幅広い技術聴衆のための。
3. 高度のプラットホームの文書のための日本語(`ja`)。
## ソース参照
- README.mdの
- README.es.mdの
- wiki/INDEX.md(ウィキ・インデックス)
- wiki/es/INDEX.md(ウィキ・エス・インデックス)
- wiki/es/overview.md
wiki/ja/migration-signed-feed.md
+185
View File
@@ -0,0 +1,185 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../migration-signed-feed.md
Review status: draft
-->
# 移行記録: 署名されていないフィード → 署名されたフィード (完了)
ツイート 1) 目的とステータス
ClawSec のアドバイザリーディストリビューションが署名されていない `feed.json` デリバリーから、レガシークライアントの互換性が保持された状態の確認に移行する方法を文書化します。
`main`の現在の状態:
- 署名されたフィード・パブリッシングは、アドバイザリー・ワークフローとワークフローのデプロイで有効です。
- スイートおよびNanoClawの消費者は署名された供給のエンドポイントにデフォルトで置きます。
- 署名されていない動作は、明示的な互換性バイパス(`CLAWSEC_ALLOW_UNSIGNED_FEED=1`)としてのみ存在します。
ツイート 2)ベースライン(今日、ポストマイグレーション)
アクティブな使用中の現在のフィードパス:
- 真実の源:`advisories/feed.json`
- ソース署名: `advisories/feed.json.sig`
- スキルコピー:`skills/clawsec-feed/advisories/feed.json`
- スキルコピー署名:`skills/clawsec-feed/advisories/feed.json.sig`
- ページのコピー: `public/advisories/feed.json`
- ページ署名: `public/advisories/feed.json.sig`の特長
- 最も最近のミラーのコピー: `public/releases/latest/download/advisories/feed.json` (+ `.sig`)
現在の消費者のデフォルト:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- デフォルトURL:`https://clawsec.prompt.security/advisories/feed.json`
ツイート 3) 移行原則
-**Dual-publish first**:検証の前に署名を公開します。
- **移行中にのみフェイルオープン**:一時的な互換性期間が明示され、期限が切れる。
- **測定されたロールアウト**:テレメトリーの後で確認を強制して下さい安定した署名された出版を確認します。
-**Fast rollback**: 根本原因が調査される間、符号なしの行動に戻るパスを保存します。
ツイート 4) フェーズドタイムライン(歴史的)
################################################################################################################################################################################################################################################################ フェーズ0 — 準備(完了)
配達可能:
- 生成されたキーと指紋を記録する署名
- GitHubの秘密作成
- リポジトリに公開鍵を追加
- runbooks が承認(`security-signing-runbook.md`、このファイル)
出口の基準:
- レビュアーによって検証される重要な指紋
- 保護された枝/ワークフロー制御は有効にしました
################################################################################################################################################################################################################################################################ フェーズ1 — CI 署名機能、クライアントの執行なし (完了)
実装:
- `advisories/feed.json.sig`を作り出すために供給の印のステップ/ワークフローを加えて下さい
- 任意に農産物 `advisories/checksums.json` + `.sig`の特長
- CIがアーティファクトを公開する前に署名を検証することを確認してください
また更新の展開:
- `.sig`アーティファクトを`public/advisories/`にコピーする
- `public/releases/latest/download/advisories/`のミラー`.sig`
出口の基準:
- すべてのフィード更新パスで正常に生成されたシグネチャ
- アーティファクトには、ペイロードと署名のコンパニオンの両方が含まれている
################################################################################################################################################################################################################################################################ フェーズ 2 — 消費者のデュアル読み取り/デュアル検証サポート(完了)
消費者の実装:
- `feed.json`と`feed.json.sig`を読みます
- ピン留めされた公共のキーと確認して下さい
- migration の窓の間に管理された一時的な署名されていないフォールバックを保って下さい
検証:
- リモート署名されたパスをテストして下さい
- ローカル署名されたフォールバックパスをテストして下さい
- 無効な署名拒否のテスト
出口の基準:
- 検証ロジックのリリースとテスト
- 浸漬期間中に偽陽性検証の失敗はありません
################################################################################################################################################################################################################################################################ フェーズ3 — 強化(完了)
アクション:
- デフォルトパスの一時的な署名されていないフォールバック動作を無効にします
- `.sig`が欠落したときに失敗するCI /公開ゲートを追加します
- リリースノートおよび文書の施行日を発表
出口の基準:
- すべてのプロダクションクライアントは、デフォルトでシグネチャを検証します
- 標準的な設置流れの署名されていない供給の依存性無し
################################################################################################################################################################################################################################################################ フェーズ 4 — 安定化(継続)
アクション:
- 最初のキー回転テーブルトップドリルを実行します
- ロールバックテーブルトップドリルを実行
- 簡単なレビューで移行を閉じる
ツイート 5)ロールバックプラン
## ロールバックトリガー
以下のいずれかが発生した場合は、ロールバックを初期化します。
- クライアント間でシグネチャ認証の失敗を持続
- ワークフローの署名は、有効な署名を生成できません
- 重要な妥協が疑われるが、置換キーはまだ展開されていない
- 展開パスは、不一致したペイロード/署名ペアを公開します
##ロールバックレベル
## レベル 1 (必須): 検証バイパスウィンドウ, 署名された出版を維持
使用時:署名は健康で、クライアント側の修飾子に欠陥があります。
アクション:
1。 クライアントリリースブランチで一時的な署名なしのアクセプタンス動作を再有効。
2。 バイパスの明示的な有効期限でパッチリリースを出荷します。
3。 認証ギャップを避けるためにパイプラインをアクティブに署名し続ける。
回復ターゲット: 24–48h内の厳密な確認を元通りにして下さい。
## レベル 2: パイプラインの注入、署名されていない供給を一時的にauthoritative署名しました
いつ使用して下さい: 署名のパイプラインは不安定ですまたは不連続なアーティファクトを作り出します。
アクション:
1。 ワークフローの署名やステップの署名を無効にします。
2. 既存のワークフローを介した`advisories/feed.json`を公開し続けます。
3。 `.sig`アーティファクトを必要とするデプロイゲートを反転します。
4。 未署名モードでのインシデントレコードを開き、時刻を追跡します。
回復ターゲット:署名された出版ASAPを、理想的に <72h。
##レベル3:フルリリースフリーズ
いつ使う: リポジトリ/ワークフローの妥協や完全性が疑わしい。
アクション:
1。 フィードのミューテーションとデプロイのワークフローを再利用します。
2。 アドバイザリーファイル/ワークフローの既知のコミットを復元します。
3。 キーと認証情報を回転させます。
4。 セキュリティレビューサインオフ後にパイプラインを再開します。
##ロールバック後のロールフォワード
- 根本原因を特定する
- 回帰テスト/ゲートを追加
- redeployの署名されたアーティファクト
- インシデントの公開 + 修正要約
ツイート 6)コミュニケーション計画
執行およびロールバックのでき事のために、伝達します:
- 変更点
- 期待される演算子/クライアントアクション
- 一時的な互換性モードの持続時間(もしあれば)
- ユーザーの検証コマンド
推奨チャンネル:
- GitHubリリースノート
- リポジトリ README/docsの更新
- リポジトリの発行/インシデントレポート
ツイート 7) ゴー/ノーゴーチェックリスト
すべてが真の場合だけ行く:
- ワークフローの成功率の署名は安定しています
- 署名はすべての文書化されたフィードエンドポイントにミラーリングされます
- リモート+ローカルフォールバックのためにテストされた消費者検証パス
- ロールバック所有者が割り当てられ、到達可能
- キーの回転プロシージャは少なくとも一度に乾燥した操業です
## ソース参照
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- スキル/クローセスイート/ホック/クローセ-アドバイザー/ハンドラー.ts
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- アドバイザリー/フィード.json
- wiki/security-signing-runbook.md
wiki/ja/overview.md
+114
View File
@@ -0,0 +1,114 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../overview.md
Review status: draft
-->
ツイート プロフィール
## 目的
- ClawSecは、公開WebカタログとOpenClawおよびNanoClaw環境用のインストール可能なセキュリティスキルを組み合わせたセキュリティ重視のリポジトリです。
- - - コードベースは、静的ウェブサイトの公開、署名されたアドバイザリー配布、およびper-skill GitHubリリースパッケージの3つのデリバリーパスをサポートしています。
- プライマリユーザーは、CIベースのセキュリティ自動化を実行しているエージェント・オペレータ、スキル・デベロッパー、メンテナーです。
![Prompt Security Logo](../assets/overview_img_01_prompt-security-logo.png)
![ClawSec Mascot](../assets/overview_img_02_clawsec-mascot.png)
ツイート リポレイアウト
| パス | ロール | ノート |
| お問い合わせ |
| `pages/`、`components/`、`App.tsx`、`index.tsx` | Vite + React UI | スキルカタログ、アドバイザリーフィード、詳細ページ お問い合わせ
| `skills/` | セキュリティスキルパッケージ | 各スキルは`skill.json`、`SKILL.md`、オプションスクリプト/テスト/ドキュメントを持っています。 お問い合わせ
| `advisories/` | リポジトリアドバイザリーチャンネル | 署名 `feed.json` + `feed.json.sig`と主要素材. お問い合わせ
| `scripts/` | ローカルオートメーション | フィード/スキル、プレプッシュチェック、リリースヘルパーのポップアップ お問い合わせ
| `.github/workflows/` | CI/CD パイプライン | CI、リリース、NVD ポーリング、コミュニティアドバイザリー摂取、ページ展開 お問い合わせ
| `utils/` | パイソンユーティリティ | スキル検証とチェックサム包装ヘルパー お問い合わせ
| `public/` | 静的資産の公開 | サイトメディア、ミラード・アドバイザリー、生成されたスキルアーティファクト。 お問い合わせ
| `wiki/` | ドキュメンテーションハブ | アーキテクチャー・オペレーション・ランブック・互換性・検証ガイド お問い合わせ
## エントリーポイント
| エントリー | タイプ | 目的 |
| お問い合わせ |
| `index.tsx` | フロントエンドブーツ | `#root`にReactアプリをマウント お問い合わせ
| `App.tsx` | フロントエンドルータ | 自宅・スキル・フィード・wikiページのルートマップの定義 お問い合わせ
| `scripts/prepare-to-push.sh` | Devのワークフロー | プッシュ前にlint/type/build/securityのチェックを実行します。 お問い合わせ
| `scripts/populate-local-feed.sh` | データブートストラップ | NVD から CVE をプルし、現地のアドバイザリーフィードを更新します。 お問い合わせ
| `scripts/populate-local-skills.sh` | データブートストラップ | `public/skills/index.json` と 1 スキルチェックサムのビルド お問い合わせ
| `scripts/generate-wiki-llms.mjs` | ドキュメントのエクスポート | `public/wiki/llms.txt` と 1 ページの wiki のエクスポートを生成します。 お問い合わせ
| `.github/workflows/skill-release.yml` | リリースエントリー | ハンドルPR版-parity/dry-run checks and tag-based Packaging/signing/release お問い合わせ
| `.github/workflows/poll-nvd-cves.yml` | フィード更新スケジュール | ポールズNVDとアップデートのアドバイザリー お問い合わせ
## キーアーティファクト
| アーティファクト | プロデュース | | コンセプト |
| お問い合わせ |
| `advisories/feed.json` | NVD 投票 + コミュニティアドバイザリーワークフロー | Web UI、clawsec-suite ホック、インストーラー お問い合わせ
| `advisories/feed.json.sig` | ワークフローの署名 | スイート・アンド・ノークローのシグネチャ検証 お問い合わせ
| `public/skills/index.json` | ワークフロー・ローカル・ポジュレート・スクリプトの展開 | `pages/SkillsCatalog.tsx` と `pages/SkillDetail.tsx` お問い合わせ
| `public/wiki/llms.txt` + `public/wiki/**/llms.txt` | ウィキジェネレータスクリプト + ビルドホック | LLM-ready wiki エクスポート wiki UI からリンクされています。 お問い合わせ
| `public/checksums.json` + `public/checksums.sig` | ワークフローの展開 | オペレータやランタイムのクライアントのための公開整合性アーティファクト. お問い合わせ
| `release-assets/checksums.json` | スキルリリースワークフロー | 消費者がzipの完全性を検証するリリース お問い合わせ
| `skills/*/skill.json` | スキル作者 | サイトカタログ作成・検証・リリースパイプライン お問い合わせ
ツイート キーワークフロー
- ローカルWeb開発: `npm install` は、`npm run dev` です。
- ローカルセキュリティデータプレビュー: `./scripts/populate-local-skills.sh` と `./scripts/populate-local-feed.sh` をロードする前に `/skills` と `/feed` ページを実行します。
- プレパス品質ゲート:`./scripts/prepare-to-push.sh`(オプションで`--fix`)を実行します。
- スキルのライフサイクル:`skills/<name>/`を編集し、`python utils/validate_skill.py`で検証し、`<skill>-vX.Y.Z`にタグを付けてリリースワークフローをトリガーします。
- アドバイザリーのライフサイクル:NVDのポールおよび問題ラベルに基づくコミュニティの摂取量は、同じ署名されたフィードに結合します。
## サンプルスニペット
```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
```
ツイート 開始場所
- `README.md`は、製品位置決めとインストールパスです。
- `App.tsx` と `pages/` を開き、ユーザーフェーシングの動作を把握します。
- `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`の生産行動のレビュー。
ツイート ナビゲートする方法
- `pages/`にUIの動作が集中しています。`components/`にビジュアルラッパーが座っています。
- スキル固有のロジックは、`skills/`のフォルダによって分離されます。各フォルダには独自のスクリプト/テスト/ドキュメントが含まれています。
- フィード処理は、リポジトリフィードファイル、ワークフローの更新、ランタイムの消費者(`clawsec-suite`/`clawsec-nanoclaw`)の3つのレイヤーに表示されます。
- `scripts/`およびワークフローYAMLファイルで動作品質ゲートが稼働します。
- 生成のトレースやベースラインを更新するには、`wiki/GENERATION.md`から始まり、モジュールページにブランチします。
## 共通ピッタフォール
- 設定パス env vars で literal のホームトークン (たとえば `\$HOME`) を使うと、パス検証の失敗をトリガーできます。
- SPA ルートから JSON を取得すると、ステータス 200 で HTML を返すことができます。このページガードは空の状態として扱います。
- 移行の互換性のために、フィードバイパスモード(`CLAWSEC_ALLOW_UNSIGNED_FEED=1`)が存在し、安定した状態では使用しないでください。
- `skill.json`と`SKILL.md`のフロントマッタ間のバージョンのパリティを期待するスキルリリース自動化。
- 一部のスクリプトは、POSIX シェル指向です。 Windows ユーザーは、PowerShell の同等体または WSL を好む必要があります。
## 更新ノート
- 2026-02-26: 削除されたルート`docs/`ディレクトリの代わりに、`wiki/`で運用文書を指すためにリポジトリレイアウトを更新しました。
## ソース参照
- README.mdの
- パッケージ.json
- App.tsxアプリ
- インデックス.tsx
- ページ/ホーム.tsx
- ページ/SkillsCatalog.tsx
- ページ/SkillDetail.tsx
- ページ/フィードSetup.tsx
- スクリプト/prepare-to-push.sh
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- スキル/ 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
wiki/ja/platform-verification.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../platform-verification.md
Review status: draft
-->
# プラットフォーム検証チェックリスト
このチェックリストを使用して、変更後のポータビリティとパス処理の動作を検証します。
## Linux 検証
1。 コアノードのテストを実行します。
```bash
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
期待:すべてのテストパス。
2。 `$HOME`パスの受け入れを検証しません。
```bash
CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
期待:`Unexpanded home token`エラーでゼロを終了します。
3. `$HOME`の拡張機能を検証:
```bash
HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
```
期待:`$HOME`拡張テストパス
# macOS 検証
1。 Linux と同じ Node テスト スイートを実行します。
2。 OpenSSLツーリングパスの仮定が文書化されていることを確認します。
- LibreSSL/OpenSSL のバリエーションを使用する場合は、docs からテストされたコマンドフォームを使用することを確認してください。
3。 設定パスでチルドの拡張を確認します。
```bash
OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
```
期待される: パスは正しく解決します (または拡張された場所での明確なファイルではなく、エラー)。
## Windowsの検証(PowerShell)
1。 ノードテストを実行します。
```powershell
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
```
期待:すべてのパス。
2。 電力を検証 Shell env パス拡張動作:
```powershell
$env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
期待: パストークンが展開/正規化されるか、ターゲットファイルが不足している場合、クリアエラーで失敗します。
3。 エスケープされたリテラルトークン拒否を確認します。
```powershell
$env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
期待: `Unexpanded home token` のエラー、Liteal `$HOME` のディレクトリ作成なし。
ツイート ライン・エンド・サンティ
1。 LFポリシーの提示を確認する:
```bash
test -f .gitattributes && grep -n "eol=lf" .gitattributes
```
期待:スクリプト/コンフィグファイルパターンはLFを強制します。
2。 CRLF-prone のチェックアウト後、スクリプトは引き続き解析します。
```bash
bash -n scripts/populate-local-feed.sh
bash -n scripts/populate-local-skills.sh
```
期待される:`^M`のshbang/parseの間違い無し。
## Explicit Bug Check: 文字無し `$HOME` ディレクトリ作成
1。 リテラル/エスケープされたトークンを持つパスを設定します。
2。 セットアップ/インストールコマンドを実行します。
3。 コマンドがトークンエラーで初期に失敗することを確認します。
4. `$HOME` のセグメントディレクトリは、作業ディレクトリで作成されていないことを確認します。
期待される結果:**Liteal `$HOME` を含むディレクトリはサポートされたセットアップスクリプトによって作成されます。 メニュー
## ソース参照
- .gitattributesの
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- スキル/clawsec-suite/test/path_resolution.test.mjs
- スキル/ clawsec-suite/test/guarded_install.test.mjs
- スキル/ clawsec-suite/test/advisory_suppression.test.mjs
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- スキル/openclaw-audit-watchdog/test/suppression_config.test.mjs
wiki/ja/remediation-plan.md
+89
View File
@@ -0,0 +1,89 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../remediation-plan.md
Review status: draft
-->
# クロスプラットフォームの修復計画
ツイート フェーズ1:リスク閉鎖の即時化(完了)
##マイルストーン
- 高リスクランタイム/インストールパスで明示的なホームパス拡張+疑わしいトークン拒否を実行します。
- パスの拡張とエスケープトケン拒否のための回帰テストを追加します。
- `.gitattributes` LFポリシーを追加します。
- Node lint/type/build CI のカバレッジを Linux/macOS/Windows に拡張します。
- シェル固有のガイダンスとリテラル`$HOME`のトラブルシューティングでインストールドキュメントを更新します。
## アウトカム
- `$HOME`パス伝搬のバグをソースで解決
- コアアドバイザリー/インストールパスコンフィグが無効なパストークンで高速に失敗しました。
お問い合わせ
ツイート フェーズ2:批判的ワークフローのためのWindowsのパリティ(次)
### クイック勝利
- パワーを追加 最も使用されるマニュアルのインストール/チェックコマンドのシェルの同等物:
- `skills/clawsec-suite/SKILL.md`
- `skills/openclaw-audit-watchdog/SKILL.md`
- `README.md`
- 欠けているツールを検出し、OS固有のインストールのヒントを印刷するために、軽量`scripts/preflight.mjs`を追加します。
##マイルストーン
- ネイティブパワー スイートのセットアップとアドバイザリーのホックのためのシェルの指示。
- シェルスクリプトが無効なWSL/Git Bashフォールバックが文書化されました。
お問い合わせ
ツイート フェーズ3:POSIXを削減 貝の表面(Deeper Refactor)
##Refactor ターゲット
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `scripts/release-skill.sh`
### アプローチ
- `jq/sed/awk/find/chmod`パイプラインの依存性を除去するためにNode/Pythonで再実装重要なパス。
- 後方互換性のためのシェルラッパーを保存します。新しいクロスプラットフォームの実装へのルート。
##マイグレーションノート
- 古いスクリプトのエントリは、少なくとも1つのマイナーリリースのラッパーとして設定します。
- 正確なマイグレーションコマンドで非推奨警告を省略します。
お問い合わせ
ツイート フェーズ4:CIの堅くなり、主張する検証
##マイルストーン
- ノード行列(Linux/macOS/Windows)を必須チェックとして保持します。
- パスの処理を取付けるための対象となるWindowsの煙テストを加えて下さい。
- 関連するOpenSSLコマンドの互換性メモのmacOSチェックを追加します。
郵便番号 テスト戦略
- ローカル:
- ノードテストスイートを実行し、パスの拡張/抑制/インストール動作をカバーします。
- 変更されたスクリプトの構文チェックを実行します。
- CI:
- マトリックスノードは+ガードドインストーラ/抑制/パステストをチェックします。
- Linuxのみのセキュリティスキャンは残っていますが、明示的にLinux-scopedとしてマークされています。
お問い合わせ
##ロールアウト/リリース検討
- - - このパッチセットで導入されたインターフェイスの変更を破らない; 動作は無効/未公開のパストークンのみ厳格です。
- リリースノートで通信:
- パストークンの検証が強化されました
- 無効な引用符 env 値を修正する方法
- パワー シェル例ライブ
## ソース参照
- .gitattributesの
- .github/workflows/ci.yml
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- スクリプト/リリース-skill.sh
- スキル/クローセスイート/ホック/クローセ-アドバイザー/ハンドラー.ts
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- wiki/platform-verification.md の
wiki/ja/security-signing-runbook.md
+241
View File
@@ -0,0 +1,241 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../security-signing-runbook.md
Review status: draft
-->
# ClawSec 署名操作 Runbook
> 参照実装: `clawsec-suite`（OpenClawスイート）
ツイート 1) 目的
この runbook は、ClawSec リポジトリに暗号署名を導入および実行するための運用手順を定義します。
それはカバーします:
- キー生成
- GitHubの秘密管理
- ワークフローの統合の署名
- キーの回転およびrevocation
- インシデント対応
ツイート 2) 現在の作動状態(重要)
`main`では、アドバイザリーおよびリリースチャネルは、デフォルトで署名および検証されています。
- フィードライター:
- `.github/workflows/poll-nvd-cves.yml`は`advisories/feed.json`を更新し、`advisories/feed.json.sig`に署名します
- `.github/workflows/community-advisory.yml`は承認された問題のレポートのために同じことをします
- 署名されたフィードアーティファクトを`skills/clawsec-feed/advisories/`に同期する
- フィード公開パス:
- `.github/workflows/deploy-pages.yml`公開 `public/advisories/feed.json` + `.sig`の特長
- `public/checksums.json` + `public/checksums.sig`を生成し、署名します
- `public/signing-public.pem`および`public/advisories/feed-signing-public.pem`としてcanonicalキーを出版して下さい
- `public/releases/latest/download/`(`feed.json`、`feed.json.sig`、`checksums.json`、`checksums.sig`、`signing-public.pem`を含む)に基づく互換性のアーティファクトをミラーリング
- 供給の消費者:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `skills/clawsec-nanoclaw/lib/advisories.ts`
- デフォルトのフィードURLは`https://clawsec.prompt.security/advisories/feed.json`です
符号なしモードは、明示的な互換性バイパス(`CLAWSEC_ALLOW_UNSIGNED_FEED=1`)のままであり、安定した状態の動作モデルではありません。
ツイート 3) ターゲット署名されたアーティファクト
##アドバイザリーフィードチャネル
- `advisories/feed.json` (ペイロード)
- `advisories/feed.json.sig`(Ed25519署名を取り外す)
- `advisories/feed-signing-public.pem`(ピンキー公開)
################################################################################################################################################################################################################################################################ リリースアーティファクトチャンネル
- `<release>/signing-public.pem`
- `<release>/signing-public.pem`
- `<release>/signing-public.pem`
ツイート 4) 主な役割およびcustody
- **セキュリティ所有者**:重要なライフサイクルの変更とインシデントアクションを承認します。
- **プラットフォーム所有者**:ワークフローとGitHubの秘密を保持します。
-**Reviewer**:PR /リリースで指紋を検証します。
ポリシー:
- 秘密鍵は決して約束しません
- 公開鍵はコミットされ、コードレビューされます
- 信頼できるオペレータのワークステーションかHSM支えられた環境で主生成は起こります
ツイート 5)キー生成(Ed25519)
ツイート 安全なワークステーションから実行します。 共有CIランナーで実行しないでください。
```bash
# Feed signing keypair
openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem
openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem
# Release checksums signing keypair (optional separate key)
openssl genpkey -algorithm Ed25519 -out release-signing-private.pem
openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem
```
指紋の生成(チケット/変更記録の保存):
```bash
openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256
openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256
```
出版前の任意テスト署名:
```bash
echo '{"probe":"ok"}' > /tmp/probe.json
openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
```
ツイート 6) GitHubの秘密のセットアップ
郵便番号 必須の秘密
- `CLAWSEC_SIGNING_PRIVATE_KEY` — PEMエンコードEd25519プライベートキー(フィードとリリース署名の両方に使用されます)
- プライベートキーが暗号化されている場合、`CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (オプション) パスフレーズ
### 手順
1。 [Repo 設定] → [秘密と変数] → [アクション] → [新しいリポジトリ] に移動します。
2. ヘッダー/フッターを含む完全なPEMを貼って下さい。
3。 プリファー GitHub **環境の秘密** (必要な査読者と) 可能な場合のワークフロースキャッピング。
4。 レコード変更チケット:
- 秘密名
- クリエイター
- 制作時間
- 主指紋
################################################################################################################################################################################################################################################################ 推奨環境保護
- 署名の秘密を使用できるワークフローの手動承認が必要です。
- 保護されたワークフローを編集できる制限
- `main`のブランチ保護を有効にし、ワークフロー変更のレビューが必要です。
ツイート 7) ワークフロー統合ポイント
このリポジトリは、ポスト・ミュテーション、事前公開制御として署名を強制します。
## フィードパイプライン
現在の供給の変異ポイント:
- `.github/workflows/community-advisory.yml`
- `advisories/feed.json`
現在の動作:
- ワークフローステップは`advisories/feed.json`を`advisories/feed.json.sig`に署名します
- アクションの署名は、ワークフローの実行中に生成された署名を検証します
- 署名されたアーティファクトはPRのオートメーションによって託されます
郵便番号 ページパイプライン
現在のパブリッシャー:
- `public/advisories/`
現在の動作:
- `public/advisories/`にペイロード/署名をコピー
- `public/checksums.json`と`public/checksums.sig`を生成します
- `public/signing-public.pem`と`public/advisories/feed-signing-public.pem`への署名キーを公開
- アドバイザリー+シグネチャ/チェックサム/キーコンパニオンを`public/releases/latest/download/`互換パスにミラーリング
################################################################################################################################################################################################################################################################ スキルリリースパイプライン(推奨硬化)
現在の解放の発電機:
- `checksums.json`
現在の動作:
- `checksums.json` を作成し、`checksums.sig` に署名し、公開する前に署名を検証します。
- リリースアセットに`signing-public.pem`が含まれています
- 生成された公開鍵の指紋を正規キー素材に対して検証
ツイート 8) 回転ポリシーとランブック
## 回転アカデミー
- ルーチン:90日ごとに(または厳格なorgポリシー)。
- 即時:疑わしい暴露、不正なワークフロー変更、または明示されていない署名不一致。
## ルーチン回転ステップ
1。 新しいキーペアを生成します。
2。 パブリックキーファイルと指紋のドキュメントを更新するPRを開きます。
3。 GitHub シークレットとして新しい秘密鍵を追加します。
4。 新しいキーを使用するワークフローの変更をマージします。
5。 最新のフィード/リリースマニフェストを再署名します。
6。 CI および外部クライアントの検証を検証します。
7。 古い秘密鍵を削除します。
8。 過去の公開鍵の参照は、履歴検証に必要な限りのみ保持します。
## 取消ステップ
1。 妥協されたキーを使用してワークフローを無効にします。
2. 承認されたGitHubの秘密を削除します。
3。 取消しメモと公開鍵をコミットします。
4。 交換キーで最新のアーティファクトを再署名します。
5。 タイムスタンプとインパクトのあるウィンドウでインシデントアドバイザリーを発行します。
ツイート 9) インシデント応答 Playbook(署名固有の)
## トリガー
- 新規公開フィード/リリースのシグネチャ検証が失敗
- 未知のコミット/ワークフローは署名パスに触れる編集します
- 漏れたキー素材、誤ったロギング、または疑わしいシークレットアクセス
###重度ガイド
-**SEV-1**:鍵の浸入確認または悪意のある署名されたペイロードが公開
- **SEV-2**:未知の原因で検証障害
- **SEV-3**: 手続き非遵守、活動的な妥協無し
郵便番号 応答フェーズ
1。 **条件* * 必須
- ワークフローの署名/公開を一時停止
- 認証が未認証の場合、さらなるフィードマージをブロック
2. **調査**
- ワークフローの実行ログのレビュー
- `.github/workflows/`、`advisories/`、および主要なファイルに影響を与える検討のコミット
- ファースト・ベイド・タイムスタンプおよび影響を受けたアーティファクトを決定する
3。 **取引**
- 回転/回転調整キー(s)
- 既知のコミットから信頼できるアーティファクトを復元する
4。 **回復**
- 再署名のアーティファクト
- redeployページ/リリース
- 独立したクライアントチェックで確認
5。 **郵便番号* * 必須
- タイムラインと修正要約を公開
- 制御をきつく締めて下さい(眺めのゲート、保護された環境、秘密の規模)
#10 監査証拠チェックリスト
各リリースサイクルまたはフィード署名実行の場合、以下を保持します。
- ワークフロー実行 URL とコミット SHA
- 使用中のサイダーのキー指紋
- 検証結果ログ
- オペレータ/査読者の承認
- 例外かバイパスの合理
#11) 厳格なポリシー変更前の最小受け入れ基準
ポリシーをさらに締める前に(例えば、互換性バイパスパスのパスを削除):
- 署名されたアーティファクトは少なくとも2週のために一貫して作り出されます
- パイプラインミラーのシグネチャーコンをデプロイする
- 1つのロールバックのドリルおよび1つの主回転ドリルは首尾よく完了しました
- インシデント対応のオンコールオーナーが特定および文書化
## ソース参照
- アドバイザリー/フィード.json
- アドバイザリー/フィード.json.sig
- アドバイザリー/フィード署名-public.pem
- clawsec-signing-public.pem
- .github/actions/sign-and-verify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/skill-release.yml
- スクリプト/ci/verify_signing_key_consistency.sh
- wiki/migration-signed-feed.md
wiki/ja/security.md
+83
View File
@@ -0,0 +1,83 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../security.md
Review status: draft
-->
ツイート セキュリティ
##セキュリティモデルの概要
- ClawSec は、コンテンツの配布 (署名されたアーティファクト) とランタイムの動作 (管理者のゲート、完全性監視) の両方を保護します。
- Trust アンカーは、リポジトリにコミットし、ワークフロー生成された出力に対して検証された公開鍵をピン留めします。
- Runtime 消費者は、明示的なマイグレーションバイパスフラグを使用して、検証優先動作にデフォルトでデフォルトで設定します。
## 暗号化制御
| 制御 | 機構 | 位置 |
| お問い合わせ |
お問い合わせ フィード認証 | Ed25519 は署名を取り外す (`feed.json.sig`) | アドバイザリーワークフロー + 消費者検証ライブラリ お問い合わせ
| アーティファクトの完全性 | SHA-256チェックサムマニフェスト(`checksums.json`) | スキルリリースとページ展開ワークフロー お問い合わせ
お問い合わせ 鍵の一貫性 | ドキュメント全体の指紋比較 + 正式PEM | `scripts/ci/verify_signing_key_consistency.sh`. お問い合わせ
| シグネチャー検証アクション | CIでのコンポジットサイン+検証アクション | `.github/actions/sign-and-verify/action.yml` お問い合わせ
#ランタイムの執行制御
| 制御 | コンポーネント | 効果 |
| お問い合わせ |
| アドバイザリーホークギャティング | `clawsec-advisory-guardian` | マッチングアドバイザリーに基づく注意・注意深い指導 お問い合わせ
| ダブルカンファレンスインストーラー | `guarded_skill_install.mjs` | `42`を終了 マッチングアドバイザリーの明示的な確認まで お問い合わせ
| 評判の延長 | `clawsec-clawhub-checker` | インストール前の追加リスクスコアリング お問い合わせ
| ナノクローシグネチャーゲート | `skill-signature-handler.ts` + MCPツール | ブロック改ざん・荷役パッケージをポリシーでインストールします。 お問い合わせ
| 整合性ベースラインモニター | `soul-guardian` + NanoClaw 整合性モニター | ドリフト検知・検疫・復元・監査可能な履歴 お問い合わせ
## サプライチェーンとCIコントロール
- CI実行 トリビー、npm 監査、CodeQL、およびスコアカードワークフロー。
- `gitleaks`がインストールされているときにローカルプレパスチェックが`gitleaks detect`を実行できます。
- リリースワークフローは、パッケージの前にSBOMファイルの存在を検証します。
- ワークフローをデプロイすると、生成された署名キーフィンガープリントをキャノンキー素材に対して検証します。
- リリースドキュメントには、ダウンストリームの消費者向けの手動検証コマンドが含まれます。
## インシデントとローテーションの Playbooks
- `wiki/security-signing-runbook.md`は、キー生成、クラスト、回転、およびインシデントフェーズを定義します。
- `wiki/migration-signed-feed.md`は段階的な執行およびロールバックのレベルを定義します。
- ロールバックパスは、署名された公開を優先順位付けし、可能かつ任意のバイパスをタイムボックス化します。
## サンプルスニペット
```bash
# verify canonical public key fingerprint
openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256
```
```bash
# run repo key-consistency guardrail used in CI
./scripts/ci/verify_signing_key_consistency.sh
```
#既知のセキュリティトレードオフ
- 符号なしの互換性モードは保証を減らすことができ、移行が完了したら無効にする必要があります。
- バックワードの互換性のために署名されていないレガシーチェックサムアセットを許容するパスをいくつかデプロイします。
- 評判は外的な工具細工の出力に依存し、ヒューリスティック偽陽性/負を含むかもしれません。
- ローカルスクリプトは、環境の信頼を継承します。 侵害されたローカルシェルは、オペレータのワークフローをサブバートできます。
## 困難な機会
- 移行の安定化後に署名されていない互換性フラグを削除します。
- すべてのミラーリングされた解放ファイルのための決定的なチェックサム/signatureの確認を拡大して下さい。
- ワークフローレベルのシグネチャー障害シナリオに明示的なテストを追加します。
- アドバイザリー・フェッチ/検証の失敗に対するランタイムテレメトリーを増加させ、インシデント・トライを簡素化します。
## 更新ノート
- 2026-02-26: `docs/`ファイルをroot `wiki/`の操作ページ専用の署名とマイグレーションの参照をリセットしました。
## ソース参照
- セキュリティ.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- スクリプト/ci/verify_signing_key_consistency.sh
- .github/actions/sign-and-verify/action.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
- スキル/ clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- スキル/clawsec-suite/scripts/guarded_skill_install.mjs
- スキル/clawsec-clawhub-checker/scripts/enhanced_guarded_install.mjs
- スキル/ロシア語/スクリプト/soul_guardian.py
- スキル/ clawsec-nanoclaw/host-services/skill-signature-handler.ts
- スキル/クローセ・ナンクロー/ガーディアン/積分僧侶。ts
wiki/ja/testing.md
+82
View File
@@ -0,0 +1,82 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../testing.md
Review status: draft
-->
# テスト
## テスト戦略
- - - リポジトリは、単一のルート`npm test`コマンドではなくレイヤ認証を使用します。
- 中心の信任はlint/type/buildのゲートと巧みなローカルから来ます ノードテストスイート。
- Python とシェルツーリングは、専用の lint/security チェックで検証されます。
- ワークフローパイプラインは、ローカルプリパスオートメーションで使用される同じコマンドクラスを実行します。
## 検証レイヤー
| レイヤー | コマンド | スコープ |
| お問い合わせ |
| フロントエンド/静的チェック | ESLint + `tsc --noEmit` + `npm run build` | TS/TSX の正しさと生存性の構築 お問い合わせ
| スキルユニットテスト | `node skills/<skill>/test/*.test.mjs` | 署名・マッチング・抑制・インストーラー契約 お問い合わせ
| Pythonの品質 | `ruff check utils/`、`bandit -r utils/ -ll` | ユーティリティの正確性とセキュリティのパターン お問い合わせ
| シェル/スクリプトの品質 | ShellCheck + 手動スクリプトスモーク実行 | スクリプト衛生とコマンドの堅牢性。 お問い合わせ
| CIセキュリティスキャン | トライビー、npm監査、CodeQL、スコアカード | 依存性、構成、およびサプライチェーンのセキュリティ姿勢。 お問い合わせ
| ローカルプレパスセキュリティスキャン | `scripts/prepare-to-push.sh`経由のオプション`gitleaks detect` | プッシュ前のシークレットリーク検出 お問い合わせ
##スキルテストマトリックス
| スキル | テストファイル | プライマリフォーカス |
| お問い合わせ |
| `clawsec-suite` | `feed_verification`、`guarded_install`、`path_resolution`、ファズテスト | 署名チェック、アドバイザリーギャング、パスセーフティ、マッチング堅牢性 お問い合わせ
| `openclaw-audit-watchdog` | 抑制設定・レンダリングテスト | 解析・抑制動作の設定、レポートのフォーマット お問い合わせ
| `clawsec-clawhub-checker` | `reputation_check.test.mjs` | 入力検証と評判のゲーミング動作. お問い合わせ
## CIワークフローカバレッジ
| ワークフロー | トリガー | 主旨 お問い合わせ
| お問い合わせ |
| `ci.yml` | PR/push to `main` | リント/タイプ/ビルド、Pythonチェック、セキュリティスキャン、スキルテスト お問い合わせ
| `codeql.yml` | PR/push/schedule | JS/TS 静的セキュリティ解析 お問い合わせ
| `scorecard.yml` | スケジュール・出演 | サプライチェーン姿勢報告・SARIFアップロード お問い合わせ
| `skill-release.yml` | タグ + 広報 | 版画・リリースアーティファクト検証 お問い合わせ
## ローカルテストコマンド
```bash
# baseline frontend + config checks
npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
npx tsc --noEmit
npm run build
```
```bash
# representative skill tests
node skills/clawsec-suite/test/feed_verification.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
## 時計の失敗パターン
- 署名/テストフィクスチャーは、予想されたファイルが意図的に再生されると、キー/ペイロードの不一致から失敗することができます。
- エスケープされたホームトークンに意図的に失敗するパスレゾリューションテスト。この動作は期待され、セキュリティ関連性があります。
- `openclaw`または`clawhub`バイナリに依存するローカルスクリプトは、それらのCLIが存在しない環境で失敗する可能性があります。
- デプロイ/リリース ロジックは、秘密やワークフローのパーミッションが異なる場合、CIで失敗したときにローカルに渡すことができます。
## 推奨テスト注文
1. 完全なローカル ゲートのための `./scripts/prepare-to-push.sh` を実行して下さい。
2。 直接影響を受けたスキルローカルテストを実行します。
3。 フィード/署名変更のため、スイート検証テストを最初に実行します(`feed_verification`、`guarded_install`)。
4。 ワークフローやリリースの変更については、`scripts/validate-release-links.sh`とキーの一貫性スクリプトを実行します。
## 更新ノート
- 2026-02-26: 移行された`wiki/platform-verification.md`チェックリストにソースの参照を更新しました。
## ソース参照
- AGENTS.mdの
- スクリプト/prepare-to-push.sh
- スクリプト/validate-release-links.sh
- .github/workflows/ci.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/workflows/skill-release.yml
- スキル/clawsec-suite/test/feed_verification.test.mjs
- スキル/ clawsec-suite/test/guarded_install.test.mjs
- スキル/clawsec-suite/test/path_resolution.test.mjs
- スキル/openclaw-audit-watchdog/test/suppression_config.test.mjs
- スキル/clawsec-clawhub-checker/test/reputation_check.test.mjs
- wiki/platform-verification.md の
wiki/ja/workflow.md
+87
View File
@@ -0,0 +1,87 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ja)
Source: ../workflow.md
Review status: draft
-->
# ワークフロー
## エンドツーエンドのライフサイクル
- 開発は、ローカルコーディング+ローカルデータ人口と現実的なUIプレビューから始まります。
- PR CI は、品質/セキュリティとスキルテストスイートを検証します。
- PR Pages-verifyは、公開せずに生産ビルド/署名の動作を検証します。
- タグ主導のリリースワークフローパッケージとスキルアーティファクトの署名。
- ページは、ワークフローミラーのリリース/アドバイザーのアーティファクトをデプロイし、静的なサイトを公開します。
- Wiki-sync ワークフローでは、`wiki/` のドキュメントを GitHub Wiki に公開しています。
- スケジュールされたワークフローは、アドバイザリーフィードとサプライチェーンの可視性を継続的に強化します。
## 第一次ワークフローマップ
| ワークフロー | トリガー | 主な工程 |
| お問い合わせ |
| CI | PR/push to `main` | リント、タイプチェック、ビルド、Pythonチェック、セキュリティスキャン、スキルテスト。 お問い合わせ
お問い合わせ ページの検証 | `main`へのPR | ページのアーティファクトを構築し、サインアウトプットを検証 (公開なし). お問い合わせ
| 有料NVD CVE | 日頃のcron + マニュアルディスパッチ | フェッチCVE、トランス/デプス、アップデートフィード、サインアーティファクト、PR変更。 お問い合わせ
| プロセスコミュニティアドバイザリー | 課題ラベル `advisory-approved` | 課題フォーム | 課題フォーム | 諮問・署名フィードの作成・広報オープン・コメント問題 お問い合わせ
| スキルリリース | スキルタグ+メタデータPR変更 | PR: バージョン・パーティー + ドライランチェック、タグ: パッケージ・サイン・公開リリースアセット お問い合わせ
| 展開ページ | CI/Release/手動ディスパッチの成功 | リリース、ミラーアセットの発見、パブリックアドバイザリー/チェックサムの署名、展開サイト お問い合わせ
| シンクウィキ | `main` に `wiki/**` に触れる `wiki/` を `<repo>.wiki.git` に同期し、 `INDEX.md` から `Home.md` を生成します。 お問い合わせ
## ローカルオペレーターワークフロー
| ステップ | コマンド | アウトカム |
| お問い合わせ |
| デプス設置 | `npm install` | 既読のローカル環境 お問い合わせ
| ローカルカタログ | `./scripts/populate-local-skills.sh` | `public/skills/index.json` とファイルチェックサムの人口 お問い合わせ
| ローカルフィード | `./scripts/populate-local-feed.sh --days 120` | ローカルアドバイザリーフィードのコピーを更新しました。 お問い合わせ
| wiki llms のエクスポートを生成する | `npm run gen:wiki-llms` | `public/wiki/llms.txt` とページごとのエクスポートを更新します。 お問い合わせ
| ローカルゲートを走らせて下さい | `./scripts/prepare-to-push.sh` | CIのようなパス/fail信号。 お問い合わせ
| 開発UIスタート | `npm run dev` | ローカルViteエンドポイントでのブラウザプレビュー お問い合わせ
ツイート リリースワークフローの詳細
- PR/tag パスでは、バージョン バンプと docs のパシティが強化されます。
- スキルパッケージには、SBOM-declaredファイルと完全性マニフェストが含まれています。
- `checksums.json`は署名され、ワークフローの実行ですぐに検証されます。
- 設定されたとき、GitHubリリースの成功後、オプションのpublish-to-ClawHubジョブが実行されます。
- 同じ主要なライン内の古いリリースは、自動化によって監督/削除することができます。
## 諮問ワークフローの詳細
- NVDワークフローは、以前のフィード`updated`タイムスタンプから増分ウィンドウを決定します。
- フェーズマップCVEメトリックを重症/タイプに変換し、影響を受けたターゲットを正規化します。
- コミュニティアドバイザリーワークフローは、問題メタデータから決定的なID(`CLAW-YYYY-NNNN`)を作成します。
- アドバイザリーワークフローは、スキルフィードコピーと署名者を更新します。
## サンプルスニペット
```bash
# manual release prep for a skill
./scripts/release-skill.sh clawsec-feed 0.0.5
# then push tag if running in release branch mode
```
```yaml
# pages deploy depends on successful upstream workflow run
on:
workflow_run:
workflows: ["CI", "Skill Release"]
types: [completed]
```
##運用リスク
- ワークフロー権限と秘密のスコープの不正設定は、署名/公開をブロックできます。
- NVD/API の一時的な失敗はアドバイザリーの新鮮さを遅らせるかもしれません。
- Invalidタグのネーミングやバージョンのミスマッチのハレットリリース自動化。
- オペレータ機械が予想されるバイナリ(`jq`、`openssl`、`clawhub`)を欠いているかどうか、ローカルスクリプトとCIは掘り下げることができます。
## ソース参照
- スクリプト/リリース-skill.sh
- スクリプト/prepare-to-push.sh
- スクリプト/populate-local-feed.sh
- スクリプト/populate-local-skills.sh
- スクリプト/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
wiki/ko/GENERATION.md
+42
View File
@@ -0,0 +1,42 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../GENERATION.md
Review status: draft
-->
# Wiki Generation Metadata
- Commit hash: `c3983a100581a9f27eb8cc3b5baa4f585e6c45e4`
- Branch name: `codex/clawsec-scanner-0.0.2-dast-harness`
- Generation timestamp (local): `2026-03-10T19:06:29+0200`
- Generation mode: `update`
- Output language: `English`
- Assets copied into `wiki/assets/`:
- `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
- `overview_img_02_clawsec-mascot.png` (from `public/img/mascot.png`)
- `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)
## Notes
- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
- Updated index and cross-links to use `wiki/` as the documentation source of truth.
- Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
- Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.
- 2026-04-26: Split Picoclaw self-pen-testing into dedicated `wiki/modules/picoclaw-self-pen-testing.md`, and updated `wiki/modules/picoclaw-security-guardian.md` to cover advisory/drift/supply-chain scope only.
- 2026-04-25: Added DeepWiki-friendly `wiki/modules/picoclaw-security-guardian.md` with support-matrix claims, threat model, default safety posture, frontend/advisory-board wiring, verification commands, and source references. Regenerated `public/wiki/**/llms.txt` exports with `npm run gen:wiki-llms`.
## Source References
- README.md
- package.json
- AGENTS.md
- wiki/overview.md
- wiki/architecture.md
- wiki/modules/clawsec-scanner.md
- wiki/modules/picoclaw-security-guardian.md
- wiki/modules/picoclaw-self-pen-testing.md
- wiki/dependencies.md
- wiki/data-flow.md
- wiki/glossary.md
- wiki/security-signing-runbook.md
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
wiki/ko/INDEX.md
+35
View File
@@ -0,0 +1,35 @@
# 위키 인덱스 (한국어)
## 요약
- 이 문서는 ClawSec 위키의 한국어 진입점입니다.
- 영어 문서(`wiki/*.md`)가 정본(source of truth)이며, 한국어는 단계적으로 확장됩니다.
## 시작하기
- [Overview (KO)](overview.md)
- [Overview (EN)](../overview.md)
- [Architecture (EN)](../architecture.md)
## 가이드
- [Localization Workflow (KO)](localization.md)
- [Localization Workflow (EN)](../localization.md)
- [Dependencies](../dependencies.md)
- [Data Flow](../data-flow.md)
- [Configuration (KO)](configuration.md)
- [Testing](../testing.md)
- [Workflow](../workflow.md)
- [Security (KO)](security.md)
## 모듈
- [Frontend Web App](../modules/frontend-web.md)
- [ClawSec Suite Core](../modules/clawsec-suite.md)
- [NanoClaw Integration](../modules/nanoclaw-integration.md)
- [Hermes Attestation Guardian](../modules/hermes-attestation-guardian.md)
- [Picoclaw Security Guardian](../modules/picoclaw-security-guardian.md)
## 번역 노트
- 2026-04-27: 한국어 위키 초기 스캐폴드 추가 (`wiki/ko/INDEX.md`, `wiki/ko/overview.md`).
## 소스 참조
- `wiki/INDEX.md`
- `wiki/overview.md`
- `wiki/localization.md`
wiki/ko/architecture.md
+136
View File
@@ -0,0 +1,136 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../architecture.md
Review status: draft
-->
# 건축
## 체계 콘텍스트
- - - 이 페이지는 `Start Here` 섹션에서 나타납니다.
- ClawSec은 업스트림 인텔리전스 소스 (NVD + 커뮤니티 문제), GitHub 자동화 및 런타임 에이전트 환경 사이에 앉아 있습니다.
- - - Repository는 static 사이트 콘텐츠를 게시하고 사용하기 전에 런타임 기술 검증을 서명했습니다.
- 외부 배우 그룹:
- GitHub Actions runners는 CI, 릴리스 및 피드 워크플로우를 실행합니다.
- OpenClaw/NanoClaw 에이전트 consuming 기술, 고문 및 검증 스크립트.
- Repository maintainers는 자문 문제 및 merging release/tag 변화를 찬성합니다.
## 부품
| 부품 | 위치 | 책임 |
인포메이션
| 웹 UI | `App.tsx`, `pages/`, `components/` | 기술 카탈로그 및 자문 세부 경험 렌더링. ·
| 자문 사료 코어 | `advisories/feed.json*`, `skills/clawsec-suite/.../feed.mjs` | 매장, 검증 및 파스 자문 ·
| 스킬패키지 | `skills/*/` | SBOM 메타데이터를 이용한 분산형 보안 기능 ·
| Local Automation Scripts | `scripts/*.sh` | 현지 미러, 사전 푸시 체크 및 수동 릴리즈 헬퍼 구축 ·
| CI/CD 워크플로 | `.github/workflows/*.yml` | Linting, tests, NVD polling, release Packaging, 페이지 배포. ·
| Python Utility Layer | `utils/*.py` | 기술 메타데이터 검증 및 체크섬 생성 ·
# # # # # # # # # # # 키 흐름
- 기술 카탈로그 흐름:
1. Release/tag 워크플로우 게시 기술 자산.
2. 배포 워크플로우는 릴리스 자산을 발견하고 `public/skills/index.json`를 구축합니다.
3. `/skills` 페이지에 대한 UI fetches `public/skills/index.json` 및 기술 문서.
- 자문 피드 흐름:
1. `poll-nvd-cves.yml` 및 `community-advisory.yml` 업데이트 `advisories/feed.json`.
2. 급식은 서명하고 대중적인 경로에 미러링됩니다.
3. Runtime Hooks/scripts는 국부적으로 서명한 사본에 먼 급식 및 fallback를 적재합니다.
- Guarded 설치 흐름:
1. 설치자 요청 대상 기술 + 버전.
2. 자문 성냥꾼은 specifiers와 severity/risk hints를 검사합니다.
3. 출구 부호 42는 고문 경기 때 두번째 확인을 강제합니다.
## 다이어그램
```mermaid
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"]
```
![Prompt Line Motif](../assets/architecture_img_01_prompt-line.svg)
## 인터페이스 및 계약
| 인터페이스 | 계약서 | 검증 |
인포메이션
| 스킬 메타데이터 | `skills/*/skill.json` | 파이썬 유틸리티 + CI 버전 비교 검사로 검증 ·
| 자문 피드 | JSON + Ed25519 detached 시그니처 | `feed.mjs` 및 NanoClaw 시그니처 유틸리티 인증 ·
| 체크섬 | `checksums.json`(옵션 `.sig`) | 페이로드를 신뢰하기 전에 Parsed 및 해시 일치합니다. ·
· 후크 이벤트 인터페이스 | `HookEvent` (`type`, `action`, `messages`) | 런타임 핸들러만 선택된 이벤트명. ·
| 워크 플로우 릴리즈 naming | 태그 패턴 `<skill>-vX.Y.Z` | 출시/ 배포 워크플로우에서 기술 발견. ·
# # # # # # # # # # # 핵심 모수
| 매개 변수 | 기본 | 효과 |
인포메이션
| `CLAWSEC_FEED_URL` | `https://clawsec.prompt.security/advisories/feed.json` | 스위트 스크립트/훅용 원격 자문 소스 ·
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | 임시 불신뢰도 무상 호환성이 있습니다. ·
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | 자주 묻는 질문(FAQ) ·
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | 고문 후크 스캔 스로틀링 창. ·
| `CLAWSEC_SKILLS_INDEX_TIMEOUT_MS` | `5000` | 카탈로그 검색에 대한 원격 기술 색인 fetch timeout ·
| `PROMPTSEC_GIT_PULL` | `0` | watchdog 감사의 전 선택 자동 요금 ·
## 오류 처리 및 신뢰성
- Feed fetching은 잘못된 서명과 변형 된 표시를 위해 실패합니다.
- 원격 fetch 실패는 완전히 로컬 서명 피드로 돌아갑니다.
- Hook state는 atomic 파일이 지원되는 엄격한 모드로 작성합니다.
- UI 페이지는 JSON으로 제공되는 HTML fallback을 감지하고 손상된 데이터를 렌더링합니다.
- 워크 플로우 단계는 분할 키 드립을 방지하기 위해 키 지문 일관성을 적용합니다.
## 예제 Snippets
```tsx
// 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>
```
```ts
// Guarded feed loading contract in advisory hook
const remoteFeed = await loadRemoteFeed(feedUrl, {
signatureUrl: feedSignatureUrl,
checksumsUrl: feedChecksumsUrl,
checksumsSignatureUrl: feedChecksumsSignatureUrl,
publicKeyPem,
checksumsPublicKeyPem: publicKeyPem,
allowUnsigned,
verifyChecksumManifest,
});
```
## 런타임 및 배포
| 런타임 표면 | 런타임 모델 | 출력 |
인포메이션
| Vite 앱(`npm run dev`) | 로컬 프론트엔드 서버 | 피드/스킬에 대한 인터랙티브 웹 앱. ·
| GitHub CI | 멀티OS 매트릭스 + 전용 구인 | Lint/type/build/security 및 테스트 신뢰 ·
· 기술 릴리스 워크플로우 | 태그 구동 출판 + PR 건식 체크 | 릴리스 자산, 서명된 체크섬, 옵션 ClawHub 출판. ·
· 페이지 배치 워크플로우 | CI/Release Success | 정적 사이트 + 미러링 자문/출판. ·
| 런타임 후크 | OpenClaw 이벤트 후크 / NanoClaw IPC | 자문 경고, 편집 결정, 무결성 검사. ·
## 확장 노트
- NVD polling의 키워드 세트와 자문 볼륨 스케일; dedupe 및 포스트 필터링 제어 소음.
- Deploy 워크플로우 프로세스 릴리스 목록 및 색인 출력의 최신 기술 버전을 유지.
- 기술 폴더에 의해 모듈 경계는 frontend 구조를 변경하지 않고 새로운 보안 기능을 추가 할 수 있습니다.
- 시그니처 검증 경로는 페이로드 크기 (feed/manifests)가 작기 때문에 경량 유지.
## 소스 참조
- 앱.tsx
- 페이지/SkillsCatalog.tsx
- 페이지/FeedSetup.tsx
- 페이지/AdvisoryDetail.tsx
- 페이지/WikiBrowser.tsx
- 기술/하프스위트/훅/하프스위트 자문/handler.ts
- 기술/하프스위트/훅/하프스위트 자문/lib/feed.mjs
- 기술/클래스/scripts/guarded_skill_install.mjs
- 기술/하프스위트/script/discover_skill_catalog.mjs
- 기술/클로슈-nanoclaw/lib/advisories.ts
- 기술/클로슈-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의 경우
wiki/ko/configuration.md
+88
View File
@@ -0,0 +1,88 @@
# Configuration (한국어)
## 범위
- Configuration은 프런트엔드 빌드 설정, 런타임 피드 경로, 워크플로우 트리거, 스킬 메타데이터 계약을 포함합니다.
- 런타임에 민감한 대부분의 제어는 `CLAWSEC_` 또는 `OPENCLAW_` 접두사를 가진 환경 변수를 사용합니다.
- 경로 정규화는 보안 민감 영역이며, 해석되지 않은 home-token literal을 의도적으로 거부합니다.
## 핵심 런타임 변수
| 변하기 쉬운 | 기본 | 이용 |
인포메이션
| `CLAWSEC_FEED_URL` | Hosted advisory URL | Suite hook 및 guarded installer의 피드 로딩 |
| `CLAWSEC_FEED_SIG_URL` | `<feed>.sig` | Detached signature 소스 |
| `CLAWSEC_FEED_CHECKSUMS_URL` | `checksums.json` near feed URL | 선택적 checksum-manifest 소스 |
| `CLAWSEC_FEED_PUBLIC_KEY` | Suite-local PEM file | 피드 서명 검증 |
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | 임시 마이그레이션 bypass 플래그 |
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | checksum-manifest 검증 활성화 |
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | advisory hook 스캔 스로틀 |
## 경로 해석 규칙
| 규칙 | 행동 | 시행 위치 |
인포메이션
| `~` expansion | 감지된 홈 디렉터리로 해석 | suite/watchdog 스크립트의 공용 path 유틸리티 |
| `$HOME` / `${HOME}` expansion | 이스케이프되지 않은 경우 해석 | 동일 유틸리티 |
| Windows home tokens | `%USERPROFILE%`, `$env:USERPROFILE` 정규화 | 동일 유틸리티 |
| Escaped tokens (`\$HOME`) | 명시적 에러와 함께 거부 | 실수로 literal 디렉터리 생성 방지 |
| Invalid explicit path | 경고 후 기본 경로로 fallback 가능 | `resolveConfiguredPath` helpers |
## 프런트엔드 및 빌드 설정
- `vite.config.ts`는 포트(`3000`), 호스트(`0.0.0.0`), path alias(`@`)를 정의합니다.
- `index.html`은 Tailwind runtime config, 커스텀 폰트, 기본 색상 토큰을 제공합니다.
- `tsconfig.json`은 bundler 모듈 해석, `noEmit`, JSX runtime 설정을 사용합니다.
- `eslint.config.js`는 TS/React/hooks 및 스크립트 전용 lint 규칙을 적용합니다.
## 스킬 메타데이터 설정
| 필드 그룹 | 위치 | 기능 |
인포메이션
| Core skill identity | `skills/*/skill.json` | 이름/버전/작성자/라이선스/설명 메타데이터 |
| SBOM file list | `skill.json -> sbom.files` | 릴리스 필수 아티팩트 선언 |
| Platform metadata | `openclaw` or `nanoclaw` blocks | CLI 요구사항, 트리거, 플랫폼 capability 힌트 |
| Suite catalog metadata | `skills/clawsec-suite/skill.json -> catalog` | suite 멤버의 통합/기본/동의 동작 |
## 워크플로우 설정
- 스케줄 설정은 워크플로우의 `cron` 항목(`poll-nvd-cves`, `codeql`, `scorecard`)에 존재합니다.
- 릴리스 워크플로우는 `<skill>-v<semver>` 태그 패턴을 기대합니다.
- 배포 워크플로우는 성공한 CI/release `workflow_run` 이벤트와 수동 실행으로 트리거됩니다.
- composite signing action은 private key 입력이 필요하며, 서명 직후 검증을 수행합니다.
## 예시 스니펫
```bash
# run guarded install with explicit local signed feed paths
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```
```json
{
"name": "example-skill",
"version": "1.2.3",
"sbom": {
"files": [
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
]
}
}
```
## 운영 노트
- signing key는 리포지토리에 두지 말고 GitHub Secrets로만 주입하세요.
- 로컬 환경 변수 override에는 절대 경로나 이스케이프되지 않은 home 표현식을 권장합니다.
- unsigned feed 모드는 정상 운영이 아닌 임시 마이그레이션 지원으로 취급하세요.
- `SKILL.md` URL을 수정하면 broken artifact reference 방지를 위해 release-link validation을 재실행하세요.
## 소스 참조
- `vite.config.ts`
- `index.html`
- `tsconfig.json`
- `eslint.config.js`
- `skills/clawsec-suite/skill.json`
- `skills/clawsec-nanoclaw/skill.json`
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs`
- `skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs`
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
- `scripts/validate-release-links.sh`
- `.github/workflows/poll-nvd-cves.yml`
- `.github/workflows/skill-release.yml`
- `.github/actions/sign-and-verify/action.yml`
wiki/ko/data-flow.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../data-flow.md
Review status: draft
-->
₢ 킹 데이터 흐름
## 1 차적인 교류
- `Advisory ingestion`: NVD/community 입력은 정상화된 자문 급식으로, 서명된, 그 후에 클라이언트를 위해 미러링됩니다.
- `Skill catalog publication` : 릴리스 자산은 `public/skills/index.json` 플러스 per-skill docs/checksums로 발견되고 변환됩니다.
- `Runtime enforcement` : 스위트 및 나노 클로 소비자 부하 자문 데이터, 기술에 대한 일치, 경고 또는 확인 게이트를 방출.
- - - 이 페이지는 `Guides` 섹션에서 나타납니다.
## 단계별
1. 명세 피드 프로듀서 워크 플로우 / 기술 fetches 소스 데이터 (`NVD API` 또는 문제 페이로드).
2. 명세 JSON 변형 논리는 severity/type/affected 필드를 정상화하고 고문 ID에 의해 해독합니다.
3. 명세 시그니처/체크섬 단계는 시그니처 및 체크섬을 생성합니다.
4. 명세 배포 워크플로우 미러는 `public/` 및 `public/releases/latest/download/` 아래 artifacts에 서명했습니다.
5. 명세 UI 소비자는 JSON 모양/내용을 유효하게 합니다; 런타임 소비자는 추가적으로 피드 데이터를 신뢰하기 전에 서명/체크를 확인합니다.
6. 명세 Matchers는 기술 이름/버전에 `affected` specifiers를 비교하고 경고 또는 시행 확인을 방출합니다.
## 입력 및 출력
입력/출력은 아래에 테이블에서 요약됩니다.
| 유형 | 이름 | 위치 | 묘사 |
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| 입력 | CVE 페이로드 | `services.nvd.nist.gov/rest/json/cves/2.0` | ClawSec 키워드로 필터링하는 소스 취약점. ·
| 입력 | 커뮤니티 자문 문제 | `.github/workflows/community-advisory.yml` 이벤트 페이로드 | 옹호자 등록 ·
| 입력 | 기술 릴리스 자산 | GitHub Releases API + Asset | 웹 카탈로그 및 미러 다운로드를 구축하는 데 사용됩니다. ·
| 입력 | Local config/env | `OPENCLAW_AUDIT_CONFIG`, `CLAWSEC_*` vars | 제어 피드 경로, 억제 및 검증 행동. ·
| 출력 | 자문 피드 | `advisories/feed.json` | Canonical repository Feed. ·
| 출력 | 자문 시그니처 | `advisories/feed.json.sig` | 피드 인증 시그니처 ·
| 산출 | 기술 카탈로그 인덱스 | `public/skills/index.json` | `/skills` 페이지에 사용된 런타임 웹 카탈로그. ·
| 출력 | 릴리즈 체크섬/신문 | `release-assets/checksums.json(.sig)` | 출시 소비자의 정수입니다. ·
| 출력 | 후크 상태 | `~/.openclaw/clawsec-suite-feed-state.json` | 타이밍 및 알림을 추적합니다. ·
# # # # # # # # # # # 데이터 구조
| 구조 | 핵심 분야 | 용도 |
인포메이션
| 자문 사료 기록 | `id`, `severity`, `type`, `affected[]`, `published` | UI 및 설치자가 사용하는 위험 데이터 단위. ·
| 기술 메타데이터 레코드 | `id`, `name`, `version`, `emoji`, `tag` | 웹 브라우징 및 설치 명령의 카탈로그 행. ·
| 체크섬 | `schema_version`, `algorithm`, `files` | 예상되는 다이제스트 파일 이름. ·
| 자문 상태 | `known_advisories`, `last_hook_scan`, `notified_matches` | 반복 경고 및 흉상 검사를 방지합니다. ·
| Suppression config | `enabledFor[]`, `suppressions[]` | `checkId` + `skill`의 뚜렷한 건너뛰기 목록. ·
## 다이어그램
```mermaid
flowchart LR
A["NVD + Issue Inputs"] --> B["Transform + Deduplicate"]
B --> C["advisories/feed.json"]
C --> D["Sign + checksums"]
D --> E["public/advisories + releases/latest"]
E --> F["Web UI fetch"]
E --> G["Suite/NanoClaw verification"]
G --> H["Match skills + emit alerts/gates"]
```
## 국가 및 저장
| Store | Path/Scope | 글쓰기 경로 |
인포메이션
| Canonical advisories | `advisories/` | NVD + 커뮤니티 워크플로우 및 로컬 포뮬러 스크립트. ·
· 임베디드 자문부 | `skills/clawsec-feed/advisories/` 및 `skills/clawsec-suite/advisories/` | 동기화/패킹 프로세스 및 릴리스 워크플로우. ·
| 공개 미러 | `public/advisories/`, `public/releases/` | 배포 워크플로우. ·
| 런타임 상태 | `~/.openclaw/clawsec-suite-feed-state.json` | 자문 훅 상태 지속 ·
| 나노 클로 캐시 | `/workspace/project/data/clawsec-advisory-cache.json` | 호스트 사이드 자문 캐시 관리자. ·
| Integrity state | `/workspace/project/data/soul-guardian/`(NanoClaw) | Integrity 모니터 기본/오디오 저장. ·
## 예제 Snippets
```bash
# Local feed flow (NVD fetch -> transform -> sync)
./scripts/populate-local-feed.sh --days 120
jq '.updated, (.advisories | length)' advisories/feed.json
```
```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
## 실패 모드
- NVD 비율 한계 (`403/429`)는 급식을 상쾌하게 연기하고 retries/backoff를 요구합니다.
- 미싱 또는 잘못된 분리 된 서명은 실패 닫힌 모드에서 피드 거부를 유발합니다.
- JSON endpoints에 대한 HTML fallback 응답은 명시적으로 필터링하지 않는 한 false 긍정을 생성할 수 있습니다.
- Path-token misconfiguration (`\$HOME`)는 로컬 fallback 경로 해상도를 깰 수 있습니다.
- 워크플로우에서 매끄러운 공공 키 지문은 어려운 CI 실패를 유발합니다.
## 소스 참조
- 고문/feed.json
- 고문/feed.json.sig
- 스크립트/populate-local-feed.sh
- 스크립트/populate-local-skills.sh
- .github/workflows/poll-nvd-cves.yml의 경우
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml의 경우
- .github/workflows/skill-release.yml의 경우
- 기술/하프스위트/훅/하프스위트 자문/lib/feed.mjs
- 기술/하프스위트/훅/하프스위트 자문/lib/state.ts
- 기술/하프스위트/훅/하프스위트 자문/lib/matching.ts
- 기술/클래스/scripts/guarded_skill_install.mjs
- 기술/클로슈-nanoclaw/lib/advisories.ts
- 기술/하프-nanoclaw/host-services/advisory-cache.ts
wiki/ko/dependencies.md
+106
View File
@@ -0,0 +1,106 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../dependencies.md
Review status: draft
-->
# 통화
## 빌드 및 실행 시간
| 층 | 차종별 | 왜 존재 |
인포메이션
| 프론트엔드 런타임 | `react`, `react-dom`, `react-router-dom`, `lucide-react` | UI 렌더링, 라우팅, 상징. ·
인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 인포메이션 ·
| 툴링 구축 | `vite`, `@vitejs/plugin-react`, `typescript` | 빠른 TS/TSX 번들링 및 생산 빌드. ·
| Python 유틸리티 | stdlib + `ruff`/`bandit` 정책 `pyproject.toml` | 유효성 검사 및 정적 검사를 실행합니다. ·
· 쉘 오토메이션 | `bash`, `jq`, `curl`, `openssl`, `sha256sum`/`shasum` | 펌핑, 서명, 체크섬 생성, 릴리즈 체크. ·
## Dependency 세부사항
| 포장 | 버전 제약 | 범위 |
인포메이션
| `react` / `react-dom` | `^19.2.4` | 프론트엔드런타임 |
| `react-router-dom` | `^7.13.1` | 프론트 라우팅 |
| `lucide-react` | `^0.575.0` | UI 아이콘 세트 |
| `vite` | `^7.3.1` | 개발자 서버 + 빌드 |
| `typescript` | `~5.8.2` | 유형 검사 |
| `eslint` | `^9.39.2` | JS/TS 라이팅 |
| `@typescript-eslint/*` | `^8.55.0` / `^8.56.0` | TS lint 파서/루즈 |
| `fast-check` | `^4.5.3` | 속성/후자 스타일 테스트 |
| Override | Pinned Version | 직업 |
인포메이션
| `ajv` | `6.14.0` | 보안 및 호환성 안정화 ·
| `balanced-match` | `4.0.3` | 교통 취약점 제어 ·
| `brace-expansion` | `5.0.2` | 변속성 경화 ·
| `minimatch` | `10.2.1` | 세터미니즘 의존성 행동 ·
## 외부 서비스
| 서비스 | 이용 | 기능 |
인포메이션
| NVD API (`services.nvd.nist.gov`) | `poll-nvd-cves` 워크플로우 + 로컬 피드 스크립트 | 키워드/날짜 창에서 CVE를 풀 수 있습니다. ·
| GitHub API | Deploy/release 워크플로우 | 릴리스, 다운로드 자산, 게시 출력. ·
| GitHub Pages | 배포 워크플로우 | 정적 사이트와 미러링 아트ifacts. ·
| ClawHub CLI/registry | 스크립트 설치 + 옵션 게시 작업 | 설치 및 출판 기술. ·
| 옵션 로컬 SMTP/sendmail | `openclaw-audit-watchdog` 스크립트 | 이메일에 의한 감사보고서 전달 ·
## 개발 도구
인포메이션 | 인포메이션 | 커버리지 |
인포메이션
| ESLint | `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0` | 프론트엔드・스크립팅 ·
| TypeScript | `npx tsc --noEmit` | 실시간 TS 계약 확인 ·
| Ruff | `ruff check utils/` | 파이썬 스타일과 버그 패턴 체크. ·
| Bandit | `bandit -r utils/ -ll` | Python 보안 검사 ·
| Trivy | 워크플로우+옵션 로컬런 | FS/config 취약점 검사 ·
| 깁스 | `scripts/prepare-to-push.sh` 옵션 로컬 실행 | 푸시 하기 전에 비밀 누출 검출. ·
## 예제 Snippets
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.4",
"react-router-dom": "^7.13.1"
}
}
```
```toml
[tool.ruff]
target-version = "py310"
line-length = 120
[tool.bandit]
exclude_dirs = ["__pycache__", ".venv"]
skips = ["B101"]
```
## 호환성 주
- `date` 및 `stat` 사용의 Linux 차이를 위한 로컬 스크립트 계정.
- 일부 워크플로우/script는 OpenSSL 기능이 Ed25519 및 `pkeyutl -rawin`와 함께 사용됩니다.
- Windows 지원은 노드 기반 툴링에 가장 강합니다. POSIX 쉘 경로는 WSL/Git Bash가 필요할 수 있습니다.
- 급식 소비자는 마이그레이션 단계에 대한 호환성 우회를 포함, 그러나 서명된 형태는 예정된 꾸준한 국가입니다.
## 버전 노트
- 기술 출시 태그는 `<skill>-v<semver>`를 따르고 CI/deploy 자동화에 의해 파싱됩니다.
- PR 검증은 `skill.json`와 `SKILL.md` frontmatter 사이의 버전 패리티를 실행합니다.
- - - 공공 기술 지수는 UI 디스플레이에 대한 기술 당 최신 발견 된 버전을 유지합니다.
- 서명된 artifact는 (`checksums.json`) 방출 당 버전되고 파일 해시와 URL을 포함합니다.
## 소스 참조
- 패키지.json
- 패키지-lock.json
프로젝트
- eslint.config.js에
- tsconfig.json의
- 스크립트/prepare-to-push.sh
- 스크립트/populate-local-feed.sh
- 스크립트/populate-local-skills.sh
- .github/workflows/ci.yml의 경우
- .github/workflows/codeql.yml의
- .github/workflows/scorecard.yml의 경우
- .github/workflows/poll-nvd-cves.yml의 경우
- .github/workflows/deploy-pages.yml의 경우
- .github/workflows/skill-release.yml의 경우
wiki/ko/exploitability-scoring.md
+425
View File
@@ -0,0 +1,425 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../exploitability-scoring.md
Review status: draft
-->
# Exploitability 부식 방법론
## 개요
ClawSec의 악용성 득점 체계는 AI 대리인 배치 (OpenClaw/NanoClaw)를 위해 특별히 디자인된 상황에 인식 취약성 평가를 제공합니다. 모든 환경을 똑같게 대우하는 일반적인 CVSS 점수와는 달리, 우리의 득점은 AI 대리인의 유일한 공격 표면 및 사용법 본을 고려하여 경고 피로를 감소시키고 행동 가능한 위협을 우선시합니다.
## 득점 수준
| 레벨 | 관능 | 의미 |
|---|---||
| `high` | 긴요한/고 | 일반적인 에이전트 배포, 즉각적인 관심 필요 |
| `medium` | 중형 | 구성에 따라 활용 가능 | 보증 조사 |
| `low` | 저소음 | 에이전트 컨텍스트, 저소득층 |
| `unknown` | 알 수없는 | 악용성을 평가하는 충분한 자료 |
## 득점 요인
# # # # # # # # # # # 1. CVSS 기본 점수 (기본값)
분석은 CVSS 기본 점수를 기초로 시작합니다.
- **CVSS ≥ 9.0**: 긴 수명 → 초기 점수 `high`
- **CVSS 7.0-8.9**: 높은 심각성 → 초기 점수 `high`
- **CVSS 4.0-6.9**: 중간 심각성 → 초기 점수 `medium`
- **CVSS 1.0-3.9**: 낮은 severity → 초기 점수 `low`
- ** CVSS**: → 초기 점수 사이트맵
# # # # # # # # # # # 2. 공격 벡터 분석 (CVSS 미터)
분석가는 CVSS v2, v3.0 및 v3.1 벡터를 구문합니다.
### 네트워크 접근성
- **AV:N** (네트워크): 네트워크에 원격으로 악용
- **AV:A** (Adjacent): 로컬 네트워크 액세스를 요구합니다.
- **AV:L** (Local): 로컬 시스템 액세스 필요
- **AV:P** (Physical): 물리적 접근
** 에이전트에 중요 **: Network-accessible 취약점은 일반적으로 네트워크 서비스로 실행되거나 외부 API 호출을 할 수 있기 때문입니다.
#### 인증 요건
- **PR:N / Au:NONE**: 인증 필요 없음 → 점수 상승
- **PR:L / Au:SINGLE**: 낮은 특전
- **PR:H / Au:MULTIPLE**: 요구되는 높은 특권 → 득점
** 에이전트에 중요 **: Unauthenticated 악용은 공개적으로 노출되는 대리인 APIs를 위해 중요합니다.
#### 사용자 상호 작용
- **UI:N**: 사용자 상호 작용이 필요 없음 → 점수 상승
- **UI:R**: 사용자의 상호 작용을 요구 → 점수를 감소
** 에이전트에 중요 **: 에이전트는 종종 자율적으로 작동하므로 사용자 상호 작용이 덜 중요합니다.
#### 공격 Complexity
- **AC:L**: 낮은 복잡성 → 점수 상승
- **AC:M / AC:H**: 중간/고단성 → 중립 또는 점수를 감소
** 에이전트에 중요 **: Low-complexity 악용은 자동화되고 대량 공격에 사용됩니다.
# # # # # # # # # # # 3. 취약점 유형 (Deployment Context)
ClawSec은 취약점 유형이 AI 에이전트 배포에 영향을 미치는 방법에 따라 점수를 조정합니다.
### 대리인 Context에 있는 높 토크 유형
** 원격 코드 실행 (RCE)* * 이름
```
Score: Always HIGH
Rationale: RCE is critical in agent deployments
```
AI Agent는 arbitrary 코드를 함수의 일부로 실행합니다. RCE 취약점은 공격자가 납치 에이전트 실행 흐름, exfiltrate credentials, 또는 다른 시스템에 피벗을 수 있습니다.
** 서버 측 요청 위조 (SSRF) * * 이름
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: SSRF affects agents making external requests
```
에이전트는 외부 API, 내부 서비스에 액세스, 그리고 원격 리소스를 호출. SSRF는 공격자를 허용합니다:
- 내부 클라우드 메타데이터 서비스 접근 (AWS IMDSv1, GCP 메타데이터)
- 내부 네트워크에 Pivot
- DNS 터널링을 통한 Exfiltrate 데이터
**Path Traversal / 디렉토리 트레이널 * * 이름
```
Score: Elevated to HIGH if CVSS ≥ 6.0
Rationale: Path traversal affects agents with file access
```
Agents는 파일을 읽고, 스크립트를 실행하고, codebases를 관리합니다. Path traversal 활성화:
- 민감한 구성 파일 읽기 (.env, credentials)
- SSH 키, API 토큰 접근
- 긴요한 시스템 파일
**공유 **
```
Score: Always HIGH
Rationale: Command injection is critical in agent deployments
```
RCE와 마찬가지로 에이전트는 종종 시스템과 상호 작용하는 쉘 명령을 실행합니다. 명령 주입은 가득 차있는 체계 타협을 허용합니다.
#### 중간 리스크 유형
**Prototype 오염 (Node.js)* * 이름
```
Score: Elevated from LOW to MEDIUM
Rationale: Prototype pollution can escalate in Node.js agents
```
많은 에이전트 프레임 워크는 Node.js에서 실행됩니다. Prototype 오염은 다음과 같습니다.
- 인증 체크
- 특전 에스컬레이션
- 서비스 부인
** SQL 주입 / NoSQL 주입 **
```
Score: Elevated to HIGH if network-accessible and unauthenticated
Rationale: Injection affects agents with database access
```
데이터베이스의 대화 기록, 사용자 데이터 또는 도구 결과를 저장하는 에이전트는 주입 공격에 취약합니다.
# # # # # # 낮잠 유형
**Cross 사이트 스크립트 (XSS) * * 이름
```
Score: Reduced to MEDIUM if not network-accessible
Rationale: XSS has limited impact in headless agents
```
일반적으로 브라우저에서 HTML을 렌더링하지 마십시오. XSS 충격을 줄입니다. 그러나 에이전트 관리 UI 또는 채팅 인터페이스의 XSS는 우려가 있습니다.
# # # # # # # # # # # 4. 폭발성
`--check-exploits`가 활성화되면 분석자는 공개 악용에 대한 참조 URL을 확인합니다.
**Exploit 지표:**
- 악용-db.com / 악용-database.com
- 패킷stormsecurity.com
- github.com/exploit, github.com/poc
- metasploit 프레임 워크 모듈
- "/exploit", "/poc", "/proof-of-concept" 포함 URL
** 핵심 고각: **
- `low` → `medium` (유효한)
- `medium` → `high` (유효한)
- `unknown` → `medium` (유효한 + CVSS > 0)
**Rationale**: 공격자에 대한 기술 장벽을 낮추고 자동화 된 악용의 저명한 증가.
## 득점 알고리즘
해석기는 이 결정 나무를 따릅니다:
```
1. Parse CVSS score → set baseline (high/medium/low/unknown)
2. Parse CVSS vector → analyze attack characteristics
3. Adjust for attack vector:
- Network-accessible + no auth + no UI → elevate to HIGH
- Local-only access → reduce HIGH to MEDIUM
4. Adjust for vulnerability type:
- Check against agent-specific risk categories
- Elevate or reduce score based on deployment context
5. Check for public exploits (if enabled):
- Elevate score if exploits detected
6. Generate rationale explaining the final score
```
## 예제
### 예제 1 : 긴 RCE (높은 폭발성)
```json
{
"cve_id": "CVE-2024-12345",
"cvss_score": 9.8,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"type": "remote_code_execution",
"description": "Unauthenticated RCE in Express.js framework"
}
```
** 분석 출력 : **
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments"
}
```
**왜 높은 **: 긴요한 CVSS + 네트워크 접근 가능 + 아니 auth + RCE 유형.
### 예제 2 : 에이전트 API의 SSRF (높은 폭발성)
```json
{
"cve_id": "CVE-2024-23456",
"cvss_score": 7.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:L",
"type": "server_side_request_forgery",
"description": "SSRF in webhook handler allows internal network access"
}
```
** 분석 출력 : **
```json
{
"exploitability_score": "high",
"exploitability_rationale": "High CVSS score (7.3); remotely exploitable without authentication; SSRF affects agents making external requests"
}
```
**Why HIGH**: SSRF는 API 호출을 하는 에이전트에 대 한 중요 한 (최대). 인증없이 네트워크 접근 가능 위험.
### 예제 3 : 공공 폭발 (높은 폭발성)을 가진 경로 트레이널
```json
{
"cve_id": "CVE-2024-34567",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"type": "path_traversal",
"references": [
"https://exploit-db.com/exploits/51234",
"https://nvd.nist.gov/vuln/detail/CVE-2024-34567"
]
}
```
** 분석 출력 (-check-exploits 포함) : **
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (6.5); network accessible; path traversal affects agents with file access; public exploit available (1 source)"
}
```
**왜 높은 **: 경로 traversal + 에이전트 파일 액세스 + 공공 악용 높은 악용성에 중간 CVSS 상승.
### 예제 4 : 에이전트 UI의 XSS (중간 폭발성)
```json
{
"cve_id": "CVE-2024-45678",
"cvss_score": 7.1,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:L",
"type": "cross_site_scripting",
"description": "Stored XSS in agent management dashboard"
}
```
** 분석 출력 : **
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (7.1); network accessible; XSS has limited impact in headless agents"
}
```
**왜 MEDIUM**: 높은 CVSS에도 불구하고, XSS는 에이전트 배포에 덜 중요 (헤드리스 작동). 사용자의 상호 작용을 요구합니다.
### 예제 5 : 지역 Privilege 에스컬레이션 (중간 폭발성)
```json
{
"cve_id": "CVE-2024-56789",
"cvss_score": 8.8,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
"type": "privilege_escalation",
"description": "Local privilege escalation via symbolic link attack"
}
```
** 분석 출력 : **
```json
{
"exploitability_score": "medium",
"exploitability_rationale": "High CVSS score (8.8); requires local access"
}
```
**왜 MEDIUM **: 높은 CVSS에도 불구하고 로컬 액세스가 필요합니다. 일반적으로 로컬 에스컬레이션이 제한된 영향이 있는 컨테이너/샌드박스 환경에서 실행됩니다.
### 예 6 : Exploit (High Exploitability)의 프로토 타입 오염
```json
{
"cve_id": "CVE-2024-67890",
"cvss_score": 5.3,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N",
"type": "prototype_pollution",
"description": "Prototype pollution in lodash merge function",
"references": [
"https://github.com/exploit/prototype-pollution-poc",
"https://snyk.io/vuln/SNYK-JS-LODASH-1234567"
]
}
```
** 분석 출력 (-check-exploits 포함) : **
```json
{
"exploitability_score": "high",
"exploitability_rationale": "Medium CVSS score (5.3); remotely exploitable without authentication; prototype pollution can escalate in Node.js agents; public exploit available (1 source)"
}
```
**왜 HIGH**: Node.js Agent + public exploit + network-accessible에 있는 Prototype 오염은 온건한 CVSS에도 불구하고 auth = 높은 위험이 없습니다.
## ClawSec Workflows의 사용
## 자동화된 득점 (NVD 급식)
`poll-nvd-cves.yml` 워크플로우는 새로운 CVE를 자동적으로 평가합니다.
```bash
# Workflow step
python utils/analyze_exploitability.py --json --check-exploits < cve-data.json
```
`advisories/feed.json`의 자문은 다음을 포함합니다:
```json
{
"id": "CVE-2024-12345",
"severity": "high",
"exploitability_score": "high",
"exploitability_rationale": "Critical CVSS score (9.8); remotely exploitable without authentication; RCE is critical in agent deployments",
"attack_vector_analysis": {
"is_network_accessible": true,
"requires_authentication": false,
"requires_user_interaction": false,
"complexity": "low"
}
}
```
## 수동 분석
보안 연구원은 수동으로 CVE를 분석 할 수 있습니다 :
```bash
# Basic analysis
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"type":"ssrf"}' | \
python utils/analyze_exploitability.py --json
# With exploit detection
echo '{"cve_id":"CVE-2024-12345","cvss_score":7.3,"references":["https://exploit-db.com/exploits/51234"]}' | \
python utils/analyze_exploitability.py --json --check-exploits
```
### Exploitability에 의해 필터링
사용자는 악용성 점수에 의해 고문을 필터링 할 수 있습니다:
```bash
# Get only high-exploitability advisories
curl -s https://clawsec.prompt.security/feed.json | \
jq '.advisories[] | select(.exploitability_score == "high")'
# Prioritize by exploitability and severity
curl -s https://clawsec.prompt.security/feed.json | \
jq '[.advisories[] | select(.exploitability_score == "high" and .severity == "critical")] | sort_by(.cvss_score) | reverse'
```
## Backfilling Existing Advisories (역사적 유지보수)
사이트맵 QXZ는 One-off 저장소 유지 보수를 위한 역사적인 유지 보수 유틸리티로 유지됩니다.
정상적인 자문 세대의 기본 경로는 아닙니다.
선호하는 경로:
1. 명세 CI canonical 경로: init/reset과 NVD 워크플로우를 실행하여 NVD의 자문을 재개하고 파이프라인에 있는 Artifacts를 서명합니다.
2. 명세 로컬 개발자 경로: `./scripts/populate-local-feed.sh --force`를 실행하여 지역 피드를 분산시킵니다.
명시적으로 레거시 피드 콘텐츠를 복구 할 때 backfill을 사용합니다.
## 커뮤니티 공헌
커뮤니티 회원은 악용성 평가를 제출할 수 있습니다.
1. 명세 ** GitHub Issue를 통해 등록 **: CVE를 악용성 컨텍스트로 보고하기 위한 자문 템플릿 사용
2. 명세 ** 자동화된 분석**: `community-advisory.yml` 워크플로우는 커뮤니티에 등록한 CVE를 자동으로 평가합니다.
3. 명세 ** 수동 검토 **: 유지자 검토 및 승인
4. 명세 **Feed Update** : 승인 된 자문은 악용성 점수로 피드에 추가됩니다.
## 제한 및 미래 작업
## 현재 제한
1. 명세 **Static Analysis**: Scoring은 CVE metadata를 기반으로 동적 실행 시간 분석이 아닙니다.
2.**No Version Detection**: 특정 버전이 취약하다면 확인하지 않습니다.
3. 명세 ** 일정 **: 부분적인 mitigation 또는 Defense-in-depth을 고려하지 마십시오.
4. 명세 **Limited Context**: 정확한 에이전트 구성 또는 배포 툴을 알 수 없습니다.
### 미래 향상
1. 명세 **EPSS 통합 **: EPSS (Exploit Prediction Scoring System) 확률 점수
2. 명세 **KEV Matching**: CISA KEV(Known Exploited Vulnerabilities) 카탈로그를 사용한 Cross-reference
3. 명세 **Agent Profiling**: 배포된 에이전트 기능과 노출된 API를 고려
4. 명세 **Mitigation Detection**: WAF 규칙, 샌드박스링, 기타 보상 제어를 확인
5. 명세 **ML 기반 득점 **: 기계 학습을 사용하여 악용성을 예측합니다.
## 참조
- **CVSS v3.1 사양**: [https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document)
- **CVSS v2 가이드**: [https://www.first.org/cvss/v2/guide](https://www.first.org/cvss/v2/guide)
- **EPSS**: [https://www.first.org/epss/](https://www.first.org/epss/)
- **CISA KEV **: [https://www.cisa.gov/known-exploited-vulnerabilities-catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- **NVD API**: [https://nvd.nist.gov/developers/vulnerabilities](https://nvd.nist.gov/developers/vulnerabilities)
# # # # # # # # # # 관련 기사
악용성 득점 방법론을 개량하기 위하여:
1. 명세 **Submit Test Case**: `utils/analyze_exploitability.py`에 대한 테스트 케이스 추가
2. 명세 **Report False Positives/Negatives**: CVE 예제에서 GitHub 이슈 열기
3. 명세 **Propose Scoring Adjustments**: 합리적이고 예로 PR 제출
4. 명세 **Share Agent Context**: Contribute 에이전트별 취약성 패턴
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
--- ---
**가입 **: [Prompt Security](https://prompt.security)
**라이센스 **: AGPL-3.0-or-later
**최근 업데이트 **: 2026-03-01
wiki/ko/glossary.md
+64
View File
@@ -0,0 +1,64 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../glossary.md
Review status: draft
-->
₢ 킹 회사 소개
> 핵심 용어: `clawsec-suite`
## 약관
| 용어 | 정의 |
인포메이션
| Advisory Feed | JSON 문서(`feed.json`)는 기술/플랫폼에 대한 보안 자문을 포함하고 있습니다. ·
| 액티베이터 | `skill@1.2.3`, 와일드카드 등의 스킬 셀렉터, 또는 일치 논리에 사용되는 범위. ·
| Guarded Install | 고문 경기시 명시적 확인이 필요한 2단계 설치 동작. ·
| SBOM 파일 | 포장 및 검증을 위해 사용되는 `skill.json`의 숙련도 목록. ·
| 시그니처 | Base64 시그니처 파일(`.sig`)는 서명된 페이로드에서 별도로 저장됩니다. ·
| Checksum Manifest | 파일 해시 맵(`checksums.json`)은 페이로드 무결성을 검증하는 데 사용됩니다. ·
## 기술 포장 기간
| 용어 | 정의 |
인포메이션
| 기술 태그 | Git 태그는 릴리스 자동화에 의해 사용되는 `<skill>-v<semver>`로 포맷되었습니다. ·
| Release Assets | GitHub 릴리스에 첨부된 파일(zip, `skill.json`, 체크섬, 서명) ·
| 카탈로그 인덱스 | `public/skills/index.json`, 웹 카탈로그에 의해 생성 된 목록. ·
| 임베디드 부품 | 또 다른 한 기술로부터의 기능 번들(예를 들어, 스위트에 임베디드) ·
## 자문 및 보안 약관
| 용어 | 정의 |
인포메이션
| Fail-Closed Verification | 시그니처 또는 체크섬 유효성 검사가 실패한 경우 급여를 거부합니다. ·
| 할당된 호환성 모드 | `CLAWSEC_ALLOW_UNSIGNED_FEED=1`를 통한 임시 우회 경로. ·
| Suppression Rule | `checkId` 및 `skill`와 일치하는 컨피케이트를 구성하여 알려진 발견을 억제합니다. ·
| 키 지문 | SHA-256 키 일관성 검사에 사용되는 DER-encoded 공공 키의 소화. ·
## 런타임 및 플랫폼 약관
| 용어 | 정의 |
인포메이션
| OpenClaw Hook | 런타임 이벤트 핸들러(`clawsec-advisory-guardian`) ·
| NanoClaw IPC | 자문을 위한 호스트/컨테이너 작업 교환, 서명 검증, 무결성 검사. ·
| Integrity Baseline | 보호된 파일용 hashes/snapshot를 저장했습니다. ·
| 해시체인 감사 로그 | 각 항목이 이전 해시에 따라 달라집니다. ·
## CI/CD 이용 약관
| 용어 | 정의 |
인포메이션
| Poll NVD CVEs Workflow | NVD CVEs를 고문으로 바꾸는 워크플로를 계획했습니다. ·
| Community Advisory Workflow | 승인된 커뮤니티 자문을 출판하는 이슈 라벨 트리거 워크. ·
| 스킬 릴리즈 워크플로 | 태그 트리거 포장/신호/신호 파이프라인 기술 ·
| 배포 페이지 워크플로우 | 사이트 자산과 미러링/사설물을 구축하는 워크플로우. ·
## 소스 참조
- 유형.ts
- 기술/하프스위트/skill.json
- 기술/하프-nanoclaw/skill.json
- 기술/클래스/scripts/guarded_skill_install.mjs
- 기술/하프스위트/훅/하프스위트 자문/lib/feed.mjs
- 기술/하프스위트/훅/하프스위트 자문/lib/suppression.mjs
- 기술/하프-nanoclaw/guardian/integrity-monitor.ts
- 스크립트/populate-local-feed.sh
- .github/workflows/poll-nvd-cves.yml의 경우
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml의 경우
- .github/workflows/deploy-pages.yml의 경우
wiki/ko/localization.md
+66
View File
@@ -0,0 +1,66 @@
# 로컬라이제이션 워크플로우 (한국어)
## 목적
ClawSec README 및 위키 문서를 반복 가능하게 번역/현지화하기 위한 표준 파이프라인을 정의합니다.
## 범위
- 원문(정본) 언어: 영어 (`README.md`, `wiki/*.md`)
- 현재 번역 언어: 스페인어 (`README.es.md`, `wiki/es/*.md`)
- 한국어 파일럿 언어: 한국어 (`README.ko.md`, `wiki/ko/*.md`)
- 향후 언어: `wiki/<lang>/...`, `README.<lang>.md`
## Source of Truth 규칙
1. 영어 문서가 정본입니다.
2. 번역 시 명령어, 파일 경로, 코드 블록, 식별자는 원문과 동일하게 유지합니다.
3. 제품/스킬 이름은 번역하지 않습니다 (`ClawSec`, `OpenClaw`, `NanoClaw`, `Hermes`, `Picoclaw`, 스킬 패키지명).
4. 번역 커버리지가 부분적일 경우, 번역 문서에 범위를 명시합니다.
## 폴더 규칙
- README 번역:
- `README.es.md`의
- `README.ko.md`
- 향후 예시: `README.fr.md`, `README.de.md`, `README.ja.md`
- 위키 번역:
- `wiki/es/INDEX.md`, `wiki/es/<page>.md`
- `wiki/ko/INDEX.md`, `wiki/ko/<page>.md`
- 향후 예시: `wiki/fr/<page>.md`, `wiki/de/<page>.md`
- 로컬라이제이션 자산:
- `wiki/i18n/terminology-en-es.md`의
- `wiki/i18n/translation-tracker.md`의
- `scripts/i18n/qa_check.py`
## 업데이트 워크플로우
1. **원문 정리 우선**
- 번역 전에 영어 원문의 구조/명확성을 먼저 정리합니다.
2. **변경 추적**
- `wiki/i18n/translation-tracker.md`에 변경 페이지를 기록합니다.
3. **변경분 번역**
- Markdown 구조(헤더 레벨/링크/코드 블록)를 보존합니다.
4. **QA 점검**
- 링크 해상도, 코드 블록/인라인 명령어 불변성, 용어 일관성을 확인합니다.
5. **내보내기 재생성**
- `npm run gen:wiki-llms` 실행.
6. **리뷰 및 PR**
- 번역 완료 페이지와 미완료 범위를 PR에 명시합니다.
## 번역 QA 체크리스트
- [ ] 헤더 계층 유지
- [ ] 명령어 스니펫 불변 및 실행 가능
- [ ] 파일 경로/URL 불변
- [ ] 스킬/플랫폼 이름 불변
- [ ] 보안 용어 일관성
- [ ] `wiki/INDEX.md`에 번역 링크 존재
- [ ] `wiki/<lang>/INDEX.md`에서 미번역 문서는 영어 원문으로 연결
## 권장 언어 확장 순서
1. 스페인어 (`es`) — 기본선 완료
2. 한국어 (`ko`) — 파일럿 진행 중
3. 프랑스어/독일어 (`fr`, `de`) — 기술 사용자층 확장
4. 일본어 (`ja`) — 고품질 플랫폼 문서 확장
## 소스 참조
- `wiki/localization.md`
- `wiki/es/localization.md`
- `wiki/ko/INDEX.md`
- `wiki/i18n/translation-tracker.md`
- `scripts/i18n/qa_check.py`
wiki/ko/migration-signed-feed.md
+185
View File
@@ -0,0 +1,185 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../migration-signed-feed.md
Review status: draft
-->
# 마이그레이션 기록 : 위임 된 피드 → 서명 피드 (완료)
# # # # # # # # # # 1) 목표 및 상태
ClawSec 자문 배포가 서명되지 않은 `feed.json` 납품에서 레거시 클라이언트를 위해 보존 된 호환성과 함께 분리 된 서명 확인을 수행하는 방법 문서.
`main`의 현재 상태:
- Signed Feed Publishinging은 자문 작업 흐름과 워크플로우를 배치하는 역할을 합니다.
- Suite 및 NanoClaw 소비자는 기본적으로 피드 엔드포인트를 서명합니다.
- 별도의 호환성 우회(`CLAWSEC_ALLOW_UNSIGNED_FEED=1`)만 존재합니다.
# # # # # # # # # # 2) 기본 (일, 포스트 마이그레이션)
활성 사용의 현재 공급 경로:
- 진실의 근원: `advisories/feed.json`
- 소스 서명 : `advisories/feed.json.sig`
- 기술 복사 : `skills/clawsec-feed/advisories/feed.json`
- 기술 사본 서명: `skills/clawsec-feed/advisories/feed.json.sig`
- 페이지 사본: `public/advisories/feed.json`
- 페이지 서명: 사이트맵
- 최신 미러 복사 : `public/releases/latest/download/advisories/feed.json` (+ `.sig`)
현재 소비자 과태:
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`의
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`의
- `skills/clawsec-nanoclaw/lib/advisories.ts`의
- 기본 URL: `https://clawsec.prompt.security/advisories/feed.json`
# # # # # # # # # # 3) 마이그레이션 원리
-**Dual-publish first**: 검증을 위해 서명을 게시합니다.
- ** 전환 중 만 실패 - ** : 임시 호환성 기간은 명시되어 있으며 시간 제한.
-**Measured rollout**: telemetry 후의 검증은 안정적인 서명 게시를 확인합니다.
-**Fast rollback**: 루트 원인이 조사되는 동안 불신명한 행동으로 다시 길을 보존합니다.
# # # # # # # # # # 4) 단계별 타임라인 (historical)
# # # # # # # # # # # 단계 0 - 준비 (완료)
공급 능력:
- 기록된 키 및 지문 서명
- GitHub 비밀 생성
- 대중 키 (s) repo에 추가
- runbooks 승인 (`security-signing-runbook.md`,이 파일)
출구 기준:
- 검토자가 확인한 키 지문
- 보호된 분지/workflow 통제 활성화
# # # # # # # # # # # 단계 1 - CI 서명 활성화, 클라이언트 집행 없음 (완료)
구현 :
- `advisories/feed.json.sig`를 생성하는 급식 서명 단계/작업 흐름을 추가하십시오
- 선택적으로 생성 `advisories/checksums.json` + `.sig`
- CI는 게시하기 전에 서명을 검증합니다.
또한 업데이트 배포:
- `.sig` artifacts를 `public/advisories/`로 복사
- `.sig`의 미러 `.sig`
출구 기준:
- 모든 피드 업데이트 경로에 성공적으로 생성 된 서명
- 배치 artifacts는 payload와 서명 동반자를 포함합니다
# # # # # # # # # # # 주요연혁 2 — 소비자 듀얼-레드/듀얼-verify 지원 (완료)
소비자의 구현:
- `feed.json` 및 `feed.json.sig`를 읽으십시오
- pinned public key로 확인
- 이동 창 도중 통제되는 임시 불이행한 fallback를 지킵니다
유효성:
- 테스트 원격 서명 경로
- 로컬 서명된 fallback 경로 테스트
- 테스트 잘못된 서명 거부
출구 기준:
- 검증 논리 및 테스트
- 적시에 부정적 검증 실패 없음
# # # # # # # # # # # 3 단계 - 시행 (완료)
활동 :
- 기본 경로의 일시적 불이행된 fallback 동작
- `.sig`가 누락될 때 실패한 CI/publish 문을 추가하십시오
- 릴리스 노트 및 docs의 시행일 발표
출구 기준:
- 모든 생산 클라이언트는 기본적으로 서명을 확인합니다
- 표준 임명 교류에 있는 unsigned 급식 의존도 없음
# # # # # # # # # # # 주요연혁 4 - 안정화 (Ongoing)
활동 :
- 첫번째 열쇠 교체 탁상 교련을 달리십시오
- 롤백 탁상 드릴 실행
- post-implementation 검토와 가까운 이동
# # # # # # # # # # 5) 롤백 계획
## 롤백 트리거
다음의 경우 롤백을 시작:
- 클라이언트의 지속적인 서명 검증 실패
- 서명 워크플로는 유효한 서명을 생성할 수 없습니다
- 키 손상 의심하지만 교체 키는 아직 배포되지 않습니다
- 배포 경로는 잘못된 payload/signature 쌍을 게시
## # 롤백 레벨
## 레벨 1 (preferred): Verification bypass 창, 서명된 게시 유지
사용될 때: signing는 건강합니다, 클라이언트 측 verifier에는 결함이 있습니다.
활동 :
1. 명세 클라이언트 릴리스 지점의 임시 취소 방지 동작.
2. 명세 bypass에 대한 명시된 만료 날짜와 선박 패치 릴리스.
3. 명세 정품 간격을 피하기 위해 파이프라인을 서명하십시오.
복구 대상 : 24 ~ 48h 이내에 엄격한 검증을 복원합니다.
### 레벨 2: 서명된 파이프라인 일시적으로 권한이 없는, 위탁된 급식
사용될 때: signing 파이프라인은 불안정하거나 inconsistent artifacts를 일으키.
활동 :
1. 명세 작업 흐름 또는 서명 단계가 비활성화됩니다.
2. 기존 워크플로우를 통해 `advisories/feed.json`를 서명하지 않는 것을 계속합니다.
3. 명세 `.sig` artifacts가 필요한 게이트를 다시 배포합니다.
4. 명세 사건 기록 및 추적 시간 표시되지 않은 모드에서.
복구 대상 : 서명 된 출판 ASAP, 이상적으로 <72h.
### 레벨 3: 전체 릴리스 동결
사용될 때: repository/workflows의 타협 또는 완전성은 의심합니다.
활동 :
1. 명세 Pause feed mutation 및 배포 워크플로우.
2. 명세 자문 파일 / 워크 플로에 대한 알려진 좋은 커밋 복원.
3. 명세 열쇠와 자격.
4. 명세 보안 검토 표지판 후만 이력서 파이프라인.
## 롤백 후 롤백
- 루트 원인 확인
- 회귀 테스트/게이트 추가
- redeploy 서명된 artifacts
- 출판사 사건 + 재화 요약
# # # # # # # # # # 6) 통신 계획
시행 및 롤백 이벤트의 경우, 통신 :
- 어떤 변경
- 예상 연산자/클라이언트 작업
- 임시 겸용성 형태의 내구 (모든 경우에)
- 사용자의 검증 명령
권장 채널:
- GitHub 릴리스 노트
- 저장소 README/docs 업데이트
- repository에 있는 문제점/incident 보고
# # # # # # # # # # 7) Go/No-Go 체크리스트
모두 true인 경우에만 이동하십시오:
- 대화 워크플로 성공률은 안정
- 서명은 모든 문서 피드 엔드포인트에 미러링됩니다.
- 원격 + 로컬 fallback에 대한 소비자 검증 경로 테스트
- 롤백 소유자는 할당 및 도달 가능
- 열쇠 교체 절차는 적어도 한 번 말립니다
## 소스 참조
- .github/workflows/poll-nvd-cves.yml의 경우
- .github/workflows/community-advisory.yml
- .github/workflows/deploy-pages.yml의 경우
- 기술/하프스위트/훅/하프스위트 자문/handler.ts
- 기술/클래스/scripts/guarded_skill_install.mjs
- 고문/feed.json
- 위키 / 보안 - 서명 - Runbook.md
wiki/ko/overview.md
+52
View File
@@ -0,0 +1,52 @@
# Overview (한국어)
## 목적
- ClawSec은 OpenClaw 및 NanoClaw 환경을 위한 공개 웹 카탈로그와 설치형 보안 스킬을 결합한 보안 중심 저장소입니다.
- 정적 사이트 배포, 서명된 advisory 배포, clawsec-suite 같은 스킬 단위 GitHub 릴리스 패키징을 동시에 지원합니다.
## 저장소 구성
| 경로 | 역할 | 비고 |
인포메이션
| `pages/`, `components/`, `App.tsx`, `index.tsx` | Vite + React UI | 스킬 카탈로그, advisory 피드, 상세 페이지 |
| `skills/` | 보안 스킬 패키지 | 각 스킬은 `skill.json`, `SKILL.md`, 선택적 scripts/tests/docs 포함 |
| `advisories/` | 리포지토리 advisory 채널 | 서명된 `feed.json` + `feed.json.sig` |
| `scripts/` | 로컬 자동화 | feed/skills populate, pre-push 점검, release helper |
| `.github/workflows/` | CI/CD 파이프라인 | CI, release, NVD polling, pages deploy |
| `wiki/` | 문서 허브 | 아키텍처, 운영 런북, 검증 가이드 |
## 진입점
- `index.tsx`: React 앱 부트스트랩
- `App.tsx`: 라우트 정의 (`/`, `/skills`, `/feed`, `/wiki/*`)
- `scripts/prepare-to-push.sh`: 로컬 품질 게이트
- `scripts/generate-wiki-llms.mjs`: wiki `llms.txt` 생성
## 핵심 워크플로우
1. 로컬 개발: `npm install && npm run dev`
2. 로컬 데이터 미리보기:
- `./scripts/populate-local-skills.sh`
- `./scripts/populate-local-feed.sh --days 120`
3. 품질 게이트: `./scripts/prepare-to-push.sh`
## 예시 명령
```bash
npm install
./scripts/populate-local-skills.sh
./scripts/populate-local-feed.sh --days 120
npm run dev
```
## 참고
- 상세 기준 문서는 영어 원문을 참고하세요: [../overview.md](../overview.md)
- 위키 인덱스(한국어): [INDEX.md](INDEX.md)
## 업데이트 노트
- 2026-04-27: 한국어 overview 초기 버전 추가.
## 소스 참조
- `README.md`
- `App.tsx`
- `index.tsx`
- `scripts/prepare-to-push.sh`
- `scripts/populate-local-feed.sh`
- `scripts/populate-local-skills.sh`
- `scripts/generate-wiki-llms.mjs`
wiki/ko/platform-verification.md
+103
View File
@@ -0,0 +1,103 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../platform-verification.md
Review status: draft
-->
# 플랫폼 검증 체크리스트
이 체크리스트를 사용하여 변경 후 포트성과 경로 추적 작업을 검증합니다.
## 리눅스 검증
1. 명세 핵심 노드 테스트를 실행:
```bash
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
```
예상 : 모든 테스트 패스.
2. 명세 리터 `$HOME` 경로 합격을 확인:
```bash
CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
예상 : `Unexpanded home token` 오류로 비소를 종료합니다.
3. `$HOME` 확장 작품을 검증:
```bash
HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
```
예상되는: `$HOME` 확장 시험 통행.
## macOS 인증
1. 명세 같은 노드 테스트 스위트를 Linux로 실행합니다.
2. OpenSSL 도구 경로 가정을 확인:
- LibreSSL/OpenSSL 변형을 사용하는 경우, docs에서 테스트된 명령 양식을 확인합니다.
3. 명세 config 경로에서 tilde 확장을 검증:
```bash
OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
```
예상 : 경로는 올바르게 해결 (또는 확장 된 위치에 명확한 파일 기반 오류).
## 윈도우 검증 (PowerShell)
1. 명세 Node 테스트 실행:
```powershell
node skills/clawsec-suite/test/path_resolution.test.mjs
node skills/clawsec-suite/test/guarded_install.test.mjs
node skills/clawsec-suite/test/advisory_suppression.test.mjs
```
예상 : 모든 패스.
2. 명세 공급 능력 Shell env 경로 확장 동작:
```powershell
$env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
예상 : 경로 토큰은 확장 / 정상화 또는 대상 파일이 누락 된 경우 명확한 오류로 실패합니다.
3. 명세 탈출 된 리터럴 토큰 거부 :
```powershell
$env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```
예상 : `Unexpanded home token` 오류; 리터 `$HOME`와 디렉토리 생성.
# # # # # # # # # # 라인 종료 Sanity
1. 명세 LF 정책 확인은 현재:
```bash
test -f .gitattributes && grep -n "eol=lf" .gitattributes
```
예상 : 스크립트 / 구성 파일 패턴은 LF를 적용합니다.
2. 명세 CRLF-prone 체크 아웃 후, 여전히 스크립트를 확인:
```bash
bash -n scripts/populate-local-feed.sh
bash -n scripts/populate-local-skills.sh
```
예상 : `^M` shebang/parse 오류가 없습니다.
## Explicit 버그 검사: 리터 `$HOME` 없음 연락처
1. 명세 리터/escaped 토큰으로 경로 구성.
2. 명세 설정/설치 명령을 실행합니다.
3. 명세 Verify 명령은 토큰 오류로 일찍 실패합니다.
4. `$HOME` 세그먼트 디렉토리가 작업 디렉터리에 생성되지 않았습니다.
예상 결과: **Laral `$HOME`를 포함하는 디렉터리가 지원되는 설정 스크립트에 의해 생성됩니다. 더 보기
## 소스 참조
- .gitattributes의
- 스크립트/populate-local-feed.sh
- 스크립트/populate-local-skills.sh
- 기술/클래스/테스트/path_resolution.test.mjs
- 기술/클래스/테스트/guarded_install.test.mjs
- 기술/하프스위트/테스트/advisory_suppression.test.mjs
- 기술/클래스/scripts/guarded_skill_install.mjs
- 기술/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- 기술/openclaw-audit-watchdog/test/suppression_config.test.mjs
wiki/ko/remediation-plan.md
+89
View File
@@ -0,0 +1,89 @@
<!-- AUTO-GENERATED TRANSLATION SCAFFOLD (ko)
Source: ../remediation-plan.md
Review status: draft
-->
# 교차 플랫폼 구제 계획
# # # # # # # # # # 단계 1: 즉시 위험 폐쇄 (완료)
## 마일스톤
- 명시된 홈-경로 확장 + 높은-리스크 런타임/설치 경로의 의심스러운 토큰 거부 구현.
- 경로 확장 및 탈출을 위한 회귀 테스트 추가.
- `.gitattributes` LF 정책을 추가하십시오.
- Linux/macOS/Windows에 Node lint/type/build CI 적용을 확장합니다.
- 업데이트는 shell-specific 지도와 리터럴 `$HOME` 문제 해결과 함께 docs를 설치합니다.
## # 결과
- 리터 `$HOME` 경로 propagation 버그는 소스에 주소.
- Core advisory/install 경로 설정은 이제 잘못된 경로 토큰에 빠지지 않습니다.
--- ---
# # # # # # # # # # 단계 2: 긴요한 워크 플로우에 대한 Windows Parity (다음)
## 빠른 승리
- 전원 추가 Shell은 가장 많이 사용되는 수동 설치 / 체크 명령에 해당합니다.
- `skills/clawsec-suite/SKILL.md`의
- `skills/openclaw-audit-watchdog/SKILL.md`의
- `README.md`의
- 경량 `scripts/preflight.mjs`를 추가하여 누락된 도구와 인쇄 OS-특수 설치 힌트를 감지합니다.
## 마일스톤
- 네이티브 파워 스위트 설정 및 자문 후크에 대한 쉘 지침.
- WSL/Git Bash fallback은 쉘 스크립트가 비례 없는 곳에 문서화되었습니다.
--- ---
# # # # # # # # # # 단계 3: POSIX 감소 포탄 표면 (Deeper Refactor)
## Refactor 대상
- `scripts/populate-local-feed.sh`의
- `scripts/populate-local-skills.sh`의
- `scripts/release-skill.sh`의
### 접근
- `jq/sed/awk/find/chmod` 파이프라인에 의존성을 제거하기 위해 Node/Python의 중요한 경로 재개.
- 백워드 호환성을 위한 예비 쉘 래퍼; 새로운 크로스 플랫폼 구현 경로.
### 마이그레이션 노트
- 적어도 하나의 미성년자 릴리스에 대한 래퍼로 오래된 스크립트 엔트리 포인트를 유지.
- 정확한 마이그레이션 명령으로 경고를 전송합니다.
--- ---
# # # # # # # # # # 4 단계 : CI 경화 및 양파 검증
## 마일스톤
- 필요한 체크로 Node matrix (Linux/macOS/Windows)를 유지하십시오.
- 설치 경로 처리를위한 대상 Windows 연기 테스트 추가.
- macOS 체크를 OpenSSL 명령 호환성 메모에 추가하십시오.
# # # # # # # # # # # 시험 전략
- 지역:
- 경로 확장/suppression/install 동작을 커버하는 Node Test Suite를 실행합니다.
- 수정된 스크립트를 위한 구문 체크를 실행합니다.
- CI:
- Matrix Node 체크 + 가드 설치 프로그램 / 압축 / 경로 테스트.
- Linux 전용 보안 검사는 남아 있지만 Linux-scoped로 표시되어 있습니다.
--- ---
## 롤아웃 / 출시 고려
- - - 이 패치 세트에 도입 된 인터페이스 변경 없음; 동작은 잘못된 / 예상 경로 토큰에만 엄격합니다.
- 릴리스 노트에서 Communicate:
- 경로 토큰 유효성 검증
- 잘못된 인용 된 env 값을 수정하는 방법
- 어디 힘 Shell 예제
## 소스 참조
- .gitattributes의
- .github/workflows/ci.yml의 경우
- 스크립트/populate-local-feed.sh
- 스크립트/populate-local-skills.sh
- 스크립트/출시-skill.sh
- 기술/하프스위트/훅/하프스위트 자문/handler.ts
- 기술/클래스/scripts/guarded_skill_install.mjs
- 기술/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- 위키/platform-verification.md

Some files were not shown because too many files have changed in this diff Show More