mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-21 01:11:21 +03:00
davida-ps
fefecaa60a
* feat(wiki): add full in-app wiki browser and llms index * feat(wiki): auto-generate per-page llms exports * vuln package * fix(wiki): guard malformed route decoding * fix(wiki): preserve markdown anchor fragments across page links * refactor(markdown): share default render components * fix(wiki): block unsafe markdown link schemes * fix(wiki): block unsafe markdown image schemes * docs(wiki): migrate root docs into wiki pages * chore(wiki): de-track generated llms exports * chore(wiki): ignore generated public wiki artifacts * fix(wiki): align llms urls with per-page endpoint pattern * fix(wiki): derive llms index from wiki index page * refactor(markdown): share frontmatter and title helpers * refactor(wiki): share route and llms path mapping * ci(pages): add pr verify workflow and tighten deploy triggers
78 lines
4.1 KiB
Markdown
78 lines
4.1 KiB
Markdown
# 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, gitleaks, CodeQL, and Scorecard workflows.
|
|
- 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
|