security

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

# verify canonical public key fingerprint
openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256

# 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