Skip to content

wshobson/agents / plugins/signed-audit-trails/skills/signed-audit-trails-recipe

signed-audit-trails-recipe

Verified

Step-by-step cookbook for setting up cryptographically signed audit trails on Claude Code tool calls. Use when explaining, evaluating, or demonstrating the pattern before committing to the protect-mcp runtime hooks. Covers Cedar policy, Ed25519 receipts, offline verification, tamper detection, CI/CD integration, and SLSA composition.

FileKindSize
SKILL.mdskill md10.2 KB
references/cedar-policy.mdmarkdown3.9 KB
references/ci-cd.mdmarkdown2.1 KB
references/hook-wiring.mdmarkdown1.6 KB
references/receipt-format.mdmarkdown4.2 KB

references/ci-cd.md

View on GitHub
# CI/CD workflow for the signed audit trail recipe

The signing key is gitignored, so a CI job needs it from a secret. Create an
environment named `receipt-signing` and limit its deployment branches to the
default branch. Store the contents of `./protect-mcp.key` as that
environment's secret `PROTECT_MCP_KEY`, and store its `publicKey` value as the
repository variable `PROTECT_MCP_PUBLIC_KEY`. The hooks sign receipts with the
secret key while the agent runs, and the verify step checks them with the
public key. Without the key, the receipts are unsigned and the verify step
exits 1.

Run this job only on reviewed code, such as pushes to the default branch. Do
not run it on pull requests, for two reasons:

- GitHub does not pass secrets to a workflow run for a pull request from a
  fork, so the key is empty and the verify step fails.
- On a pull request from a branch in the same repository, the job would run
  that branch's `scripts/run_agent.py` after it writes the key to disk. The
  branch could change the script to read the key and send it elsewhere.

The environment's branch limit is a second guard: if someone later adds a
pull request trigger, jobs for other branches still cannot read the key.

```yaml
# .github/workflows/verify-receipts.yml
name: Verify Decision Receipts
on:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    environment: receipt-signing
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Install signing key
        env: { KEY: '${{ secrets.PROTECT_MCP_KEY }}' }
        run: umask 077 && printf '%s' "$KEY" > protect-mcp.key
      - name: Run governed agent
        run: python scripts/run_agent.py
      - name: Verify receipts
        env: { PUB: '${{ vars.PROTECT_MCP_PUBLIC_KEY }}' }
        run: npx @veritasacta/verify@0.11.1 --replay-chain receipts/receipts.jsonl --key "$PUB"
      - name: Upload receipts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: decision-receipts
          path: receipts/
```

The upload step keeps the receipts after the job ends, including when the
verify step fails.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall