Skip to content
Closed
30 changes: 30 additions & 0 deletions .claude/hooks/stop-check.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
#!/usr/bin/env bash
# Stop hook: Claude can't end a turn while `make check` fails.
#
# - Clean working tree: nothing changed, so nothing to check. Exit 0.
# - Missing tools (no .venv tools or no opa): the gate can't run here. Exit 1,
# a non-blocking error the operator sees as a hook notice. A missing tool is
# not Claude's failure to fix, and blocking on it would only loop.
# - `make check` fails: exit 2. The tail of its output goes back to Claude on
# stderr as the reason it can't stop yet.
#
# Claude Code stops honoring a Stop hook after eight consecutive blocks with no
# tool call in between, so a failure Claude can't fix does not trap the session.

cat >/dev/null # hook input is unused; drain it

cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
[ -z "$(git status --porcelain)" ] && exit 0

if ! tools=$(make --no-print-directory require-tools 2>&1); then
echo "make check skipped: tools missing. $(printf '%s' "$tools" | head -1)" >&2
exit 1
fi

if ! out=$(make --no-print-directory check 2>&1); then
printf '%s\n' "$out" | tail -40 >&2
echo "make check failed. Fix the cause, never the gate, test or fixture. If the failure isn't yours to fix, tell the operator what failed and why." >&2
exit 2
fi
exit 0
49 changes: 49 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
{
"permissions": {
"deny": [
"Bash(terraform destroy *)",
"Bash(terraform * destroy *)",
"Bash(make destroy *)",
"Bash(make -C infrastructure destroy *)",
"Bash(git push *--force*)",
"Bash(git push -f *)",
"Bash(git push * -f)",
"Bash(git push * -f *)",
"Bash(aws s3 rm *)"
],
"ask": [
"Bash(terraform apply *)",
"Bash(terraform * apply *)",
"Bash(make apply-infra *)",
"Bash(make pipeline *)",
"Bash(make -C infrastructure apply-infra *)",
"Bash(make -C infrastructure pipeline *)",
"Bash(git push * main)",
"Bash(git push * HEAD:main)",
"Bash(gh pr merge *)",
"Bash(aws iam create-*)",
"Bash(aws iam put-*)",
"Bash(aws iam attach-*)",
"Bash(aws iam detach-*)",
"Bash(aws iam update-*)",
"Bash(aws iam delete-*)",
"Bash(aws s3 cp *)",
"Bash(aws s3 mv *)",
"Bash(aws s3 sync *)",
"Bash(aws s3api put-*)",
"Bash(aws s3api delete-*)"
]
},
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-check.sh"
}
]
}
]
}
}
96 changes: 96 additions & 0 deletions .claude/skills/compliance-pipeline/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
name: compliance-pipeline
description: Use for any change to the samaydlette.com compliance pipeline. That covers artifact generators and gates in scripts/; registers in data/ (decisions.json); Terraform, OPA policies and Lambdas in infrastructure/, including bootstrap/; GitHub workflows; freshness windows; the boundary map; the Trust Center (website/trust/, trust.js); and anything published under /.well-known/. Not for article or page prose, nav or styling: use site-content for those.
---

# Compliance pipeline

Procedures for changing the pipeline. The invariants and the autonomy rules in `CLAUDE.md` apply on top of everything here. Nearly every task here touches a protected path, so **plan first** (CLAUDE.md §2). Use plan mode for generators, gates and `infrastructure/`.

Supporting files. Read them before planning:

- `references/codebase.md`: what each generator, gate and workflow does, and how they connect.
- `references/pitfalls.md`: failures that have already happened here. Check your plan against it.

## Before you plan

1. Read the generator, its tests and fixtures, and the gate that consumes its output.
2. Search `docs/architecture-decisions.md` and `data/decisions.json` for a decision that already covers the topic.
3. Decide which published artifacts change. If any do, the plan says how you will verify the published result.

## Procedures

### Change a generated artifact

1. Change the generator in `scripts/`, never its output.
2. Every artifact builds from one inventory `signal_id` and carries it.
3. A new artifact published under `/.well-known/` needs a freshness window in `infrastructure/schemas/freshness-config.json`, with who decided it and a review date. Otherwise `tests/test_freshness_config.py` fails. Never put a window back as a literal.
4. Keep one unit test per gate invariant, plus a committed broken fixture that must fail the gate.
5. Shared helpers live in `scripts/_common.py`. Scripts import it through an `__file__`-relative `sys.path.insert`, so each stays standalone-runnable from any cwd. A new shared module is a check-in.
6. Never edit the vendored FedRAMP schemas in `infrastructure/schemas/fedramp-2026-06-24/`. The loader refuses any file whose hash differs from `SOURCES.json`.

### Record a decision about a finding

- Every decision is a record in `data/decisions.json`, read through `scripts/_decisions.py`. Every in-force record carries `decided_by`, `decided_on` and an annual `review_by`; `tests/test_decision_records.py` enforces this.
- Decisions are human. Claude may draft a record, then stops for the operator to confirm who decided and when. A field that was not recorded is published as a gap; never fill it in.
- A dismissed finding is a **false positive** (with justification) or **risk-accepted**. Never drop one.

### Change infrastructure (`infrastructure/`, excluding `bootstrap/`)

1. Run `make -C infrastructure plan` first. The plan in the PR must show only your intended change.
2. Classify any new resource in `docs/boundary/boundary-classification.json` in the same change. Reconciliation invariant (l) fails the deploy on an unclassified component. Never hand-draw the boundary.
3. Run `checkov` per `.checkov.yaml`.
4. Apply policy: an additive, reversible change may be applied after the `terraform plan` review, **if the approved plan names the apply**. For cutovers and deletions, prove the new path works and keep the old one until it does.
5. Recurring cost above ~$2/month is a check-in. WAF is declined on purpose; see `references/pitfalls.md`.
6. Publishing the DNSSEC **DS record** at the registrar is always a human step.

### Change the bootstrap stack (`infrastructure/bootstrap/`)

The operator applies this stack by hand; CI never does. Every build plans it read-only and reports pending changes in the trust center. Its state is remote (`bootstrap/terraform.tfstate` in the state bucket). Its working tree drifts from `main` easily, and an apply from a stale tree silently reverts changes already merged.

1. Before editing it, sync the directory: `git fetch origin && git checkout origin/main -- infrastructure/bootstrap/`.
2. Before any `terraform apply` there, sync again. The plan must show *only* your intended change. Unrelated adds or removes mean the tree is stale: stop and sync.
3. Never apply from a divergent branch.
4. Never apply while a deploy run is in flight. The run plans the trust root before the `prod` approval and reads bootstrap state again after it. Apply first and then start the deploy, or let the run finish and redeploy.
5. If a merged change can't be applied through a synced tree, prefer a surgical, IaC-matching apply over applying a stale stack. Example: the exact `aws iam put-role-policy` the merged config specifies.

A bootstrap apply is a production step. It must be named in the approved plan.

### Touch `evidence-nightly.yml` or its role

It runs twice a day, plus once after every successful deploy to `main`, with **no reviewer**. That is acceptable only because its OIDC role (`infrastructure/bootstrap/evidence-nightly.tf`) is narrow. It can write only the object keys its role policy lists, invalidate CloudFront, and make the read-only calls the `--live` reconciliation needs. It cannot apply Terraform, sync the website, delete an object or write anywhere else.

- "The nightly needs one more permission" means: ask whether that work belongs on the unattended path at all. Don't widen the role; check in.
- It refreshes the VDR only, and binds to the **published** inventory. It fetches `/.well-known/ksi-signal.json` and verifies its Sigstore bundle against the deploy workflow's pinned identity. It fetches and verifies the SDR and CPO **as gate inputs only**: never re-signed, never re-published. A changed inventory means changed infrastructure, which belongs on the reviewed deploy path.
- A newly disclosed CVE cannot auto-publish. Invariant (h) requires an in-force decision record for every finding, so the nightly fails until a person dispositions the CVE. That is the gate working; the `alert` job (a GitHub issue) makes the failure visible.
- The `--live` reconciliation runs even when the vulnerability gate has failed, and the alert names which gate stopped the run. Publishing requires both gates to pass.
- The `prod` environment and its reviewer requirement stay as they are.

### Change the Trust Center

- `website/trust/index.html` and `website/assets/js/trust.js` are a presentational shell over `/.well-known/trust-center.json` and `boundary-map.json`. The JSON is the source of truth. To change what it reports, change `scripts/build-trust-center.py`, not the HTML.
- It is written from an Authorizing Official's seat. The site adheres to FedRAMP 20x Class C requirements; it never claims to be certified or authorized.

## Verify

**Ground truth first.** No artifact, pipeline output or Terraform state proves what is deployed. Confirm live state independently with the `aws` CLI (credentials are configured locally) or Steampipe. A check that only re-reads the build does not count. In the PR, state the outcome; never paste live values (the repo is public).

| Command | When |
|---|---|
| `make check` | Always. The exit code is the verdict. `test-policies` needs `opa` at the `OPA_VERSION` pinned in `deploy-with-opa.yml`; see pitfalls |
| `make check-full` | Generator or gate changes, with AWS access. Adds `reconcile` over artifacts built from `terraform output -json`, and fails loudly when they are absent |
| `make -C infrastructure reconcile RECONCILE_FLAGS=--live` | Infrastructure changes. Enumerates live AWS |
| `make -C infrastructure plan` | Before any apply |
| `checkov` per `.checkov.yaml` | Infrastructure changes |
| `make -C infrastructure verify-published` | After a deploy: checks the live evidence from outside |
| `scripts/check-evidence-freshness.py --all <site>` | After a deploy, or when freshness is in doubt |

**Publish freshness.** A green pipeline must publish *this run's* artifacts: the served `/.well-known/*` carries the current commit and a fresh `emitted_at`. A stale serve is a bug, not a cache quirk; verify the post-deploy round-trip.

## Parallel work

- One `git worktree`, branch and directory per concurrent task. Never two agents in one checkout.
- Parallelize the leaves, serialize the trunk. Anything that touches the inventory builder, the reconciliation gate, `data/decisions.json` or a `/.well-known/*` artifact has one owner at a time.
- The fail-closed gate arbitrates conflicts: rebase and regenerate, never weaken the gate.
- Fan read-only investigation out to subagents, and keep artifact-mutating work to one owner per artifact.
- Realistic parallelism here is a handful of genuinely independent tasks.
67 changes: 67 additions & 0 deletions .claude/skills/compliance-pipeline/references/codebase.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Compliance pipeline: codebase map

Confirm against the working tree on first use, and correct this file in the same PR when reality differs.

## The canonical inventory and its artifacts

- `scripts/build-ksi-signal.py` builds **the canonical inventory** (the KSI signal). `build_html_components()` hashes every `*.html` under `website/` into it as an `html_artifact`.
- The VDR builder (`scripts/build-vdr-report.py`) and the CR26 record builders derive from the inventory:
- `build-sdr.py`: the Security Decision Record. Its `rev5_controls` publishes the per-control view.
- `build-cpo.py`: the Certification Package Overview.
- `build-cr26-vdr.py`: turns the VDR report into FedRAMP's VDT, AVI and history reports.
- The CR26 reports are validated against FedRAMP's 2026-06-24 JSON schemas by `scripts/_fedramp_schema.py` before they are written; a report that does not validate is never written. The schemas are vendored verbatim, with their sha256s, in `infrastructure/schemas/fedramp-2026-06-24/`.
- `scripts/_controls.py` holds the control projection: status, origination and statement per NIST 800-53 control, computed in memory from the inventory and the KSI catalog. It replaced the OSCAL SSP, which was retired under CR26 on 2026-11-05.
- `scripts/_decisions.py` reads the decision register `data/decisions.json`. Under CR26 the register replaced the POA&M. The VDR builder, the vulnerability gate, reconciliation and the trust center all read it.
- `scripts/_common.py` holds the shared helpers: `classify` (the inheritance rule that four artifacts must agree on), `sha256_file`, `prop`, `load_hub`, `sid`.

## Gates

- `scripts/reconcile.py`: the reconciliation gate. It runs in CI before publish and fails closed. Its invariants are lettered (a)–(l) in the file header; (g) and (k) are retired. The ones referred to most:
- (e) binding: the VDR, SDR and CPO are built from one inventory `signal_id`.
- (f) publish freshness: the staged artifacts carry the current commit and an `emitted_at`. It has **no staleness threshold**; see pitfalls.
- (h) finding coverage: every VDR finding carries a `decision_id` that resolves to an in-force record in `data/decisions.json`.
- (l) boundary map: fails on an unclassified component.
- OPA policies live in `infrastructure/policy/` (`accessibility.rego` among them), plus `policies/triage.rego`, which decides the VDR triage.
- `scripts/vuln-gate.py` is the vulnerability gate; `scripts/detection-gate.py` fails the run when a scanner or feed failed.
- `scripts/check-published-redaction.py` scans what the deploy publishes for identifiers that must not leave.

## Published artifacts (`/.well-known/`)

- `website/.well-known/` is the publish root. In git it tracks only `security.txt` and `vdr-trend.json`. Everything else there is gitignored build output that the deploy signs and uploads, and the website sync excludes `.well-known/*`.
- Every freshness window is a governed value in `infrastructure/schemas/freshness-config.json`: one entry per published artifact, schema-validated, with who decided it and a review date. The trust center, the watchdog (Lambda and alarm thresholds) and `scripts/check-evidence-freshness.py` all read it and fail closed without it.
- Published reporting must be under 24 hours old.

## Boundary map

- `scripts/build-boundary-graph.py` generates the map **on every deploy** from the inventory and Terraform state, and publishes it signed at `/.well-known/boundary-map.json`.
- `docs/boundary/boundary-classification.json` is the operator-owned meaning: zones, groups, declared nodes and the data-flow table.
- `tools/boundary-map/corroborate.py` (local only) corroborates the map independently with RAMPART on TAP, which collects the account from the AWS APIs. The operator runs it and commits `docs/boundary/corroboration.json`. The deploy signs and publishes it as `/.well-known/boundary-corroboration.json`, and the trust center reports its result and age (30-day window). Resources only TAP sees go to the decision queue.

## Trust Center

- `scripts/build-trust-center.py` builds `/.well-known/trust-center.json` (signed): the "is this picture true?" checks, the queue of decisions that need a person, the policy catalog, the escalation rate and the decision log. All of it is derived from this build's artifacts and the registers. It runs after the reconciliation gate, and fails closed if its inputs are bound to another inventory.
- `website/trust/index.html` and `website/assets/js/trust.js` render it. The page re-checks the runtime signal and the nightly beacon live against the published freshness windows. `/viewer.html` is a redirect stub.

## Workflows and runtime

- `.github/workflows/deploy-with-opa.yml`: the gated deploy. The `deploy` job is bound to the `prod` environment (human reviewer). It has **no `schedule:` trigger**: every path to `terraform apply` is human-initiated and human-approved. It also runs the accessibility scan (pa11y) and `update-cache-version.js` before the S3 sync.
- `.github/workflows/evidence-nightly.yml`: the unattended VDR refresh, twice a day plus once after every successful deploy (`workflow_run`). It re-scans with Syft and Grype against a fresh vulnerability DB, rebuilds the VDR and trend, and runs the vulnerability and reconciliation gates. It then republishes its objects under `.well-known/` (the publish step lists each one) and, pass or fail, writes the unsigned status beacon `.well-known/vdr-status.json`. Its alerting is its own `alert` job (a GitHub issue).
- `infrastructure/watchdog.tf` and `infrastructure/watchdog/`: the evidence SLA watchdog. An hourly Lambda reads every artifact in the freshness config from the bucket (AWS APIs only, no internet egress) and publishes ages and counts as CloudWatch metrics. Four alarms email the operator through a CMK-encrypted SNS topic. The email subscription is created out of band so no address enters Terraform state. Runbook: `docs/runbooks/evidence-sla-alarm.md`.
- `infrastructure/lambda/`: the runtime Lambda. `infrastructure/bootstrap/`: the IAM trust layer, CloudFront (including the site CSP and headers), DNSSEC and the remote-state backend. The operator applies it by hand.

## AWS

The account is referenced in the published KSI signal; never commit it. `us-east-2` holds the site, app, Lambda, S3, CloudWatch, API Gateway and Secrets Manager. `us-east-1` holds ACM, CloudFront and the DNSSEC and CloudFront KMS keys. Confirm before acting.

## Make targets

| Target | What it does |
|---|---|
| `make dev-setup` | Creates `.venv` from `requirements-dev.txt`, which pins exactly what CI installs |
| `make check` | `lint` (ruff), `typecheck` (mypy, `scripts/`), `test` (pytest), `test-policies` (opa fmt, coverage floor, policy tests). Hermetic: no AWS, network, state or generated artifacts. About 4s; the first non-zero exit wins |
| `make check-full` | `check` plus `reconcile`. Needs generated artifacts, so it needs AWS |
| `make -C infrastructure plan` | `terraform plan` with the OPA compliance check |
| `make -C infrastructure apply-infra` | Applies the reviewed plan, **against production**. Publishes nothing |
| `make -C infrastructure pipeline` | `dev-setup validate plan apply-infra`, which **applies to production**. Never use it to check anything |
| `make -C infrastructure deploy` | A stub that refuses, by design |
| `make -C infrastructure verify-published` | Fetches and verifies the live published evidence |
Loading
Loading