clawsec/wiki/migration-signed-feed.md

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