diff --git a/.claude/hooks/stop-check.sh b/.claude/hooks/stop-check.sh new file mode 100755 index 00000000..bac90859 --- /dev/null +++ b/.claude/hooks/stop-check.sh @@ -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 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..56f14bf7 --- /dev/null +++ b/.claude/settings.json @@ -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" + } + ] + } + ] + } +} diff --git a/.claude/skills/compliance-pipeline/SKILL.md b/.claude/skills/compliance-pipeline/SKILL.md new file mode 100644 index 00000000..4ad2058e --- /dev/null +++ b/.claude/skills/compliance-pipeline/SKILL.md @@ -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 ` | 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. diff --git a/.claude/skills/compliance-pipeline/references/codebase.md b/.claude/skills/compliance-pipeline/references/codebase.md new file mode 100644 index 00000000..614d5999 --- /dev/null +++ b/.claude/skills/compliance-pipeline/references/codebase.md @@ -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 six objects under `.well-known/vdr-*` (report, bundle, markdown, trend, trend bundle, provenance attestation) 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 | diff --git a/.claude/skills/compliance-pipeline/references/pitfalls.md b/.claude/skills/compliance-pipeline/references/pitfalls.md new file mode 100644 index 00000000..b4d55c1d --- /dev/null +++ b/.claude/skills/compliance-pipeline/references/pitfalls.md @@ -0,0 +1,39 @@ +# Pitfalls that have already happened + +Each entry: what went wrong, and the rule that now prevents it. Check your plan against this list. Add an entry when a new failure teaches a rule; delete one when the code makes it impossible. + +## Evidence and publishing + +- **Twelve days of stale evidence passed with every gate green.** A scheduled deploy could only queue at the `prod` approval gate, and nothing checked staleness. Reconciliation's `check_f_freshness` only asserts that the staged signal carries the current commit and has an `emitted_at`; it never looks at the live edge. + Rule: don't mistake (f) for a freshness check. Freshness is enforced by `freshness-config.json`, the watchdog and `scripts/check-evidence-freshness.py`. `deploy-with-opa.yml` has no `schedule:` trigger; don't add one. +- **Local publishing bypassed the gate** and put a partial, unsigned artifact set over the live evidence. + Rule: there is no local publish path. `make -C infrastructure deploy` refuses. Publishing happens only in CI, behind the gate and the `prod` approval. +- **The old `deploy` target synced the wrong directory with `--delete`.** It removed the whole site and the published evidence. + Rule: same as above. The CI sync uses `website/` with `--exclude ".well-known/*"`. +- **Content sync overwrote the RA-5(6) vulnerability trend ledger, and a deploy deleted published evidence mid-run** (fixed 2026-08-06). + Rule: anything that writes the bucket must leave `.well-known/` to the signed, post-gate publish step. +- **Same-day fixes after the CR26 merges (2026-11-05).** Six fix PRs followed large changes. The AWS account ID reached published output. The redaction gate scanned the working directory instead of what the deploy publishes. Published claims were wrong: directory URLs returned 404, the CPO logo URL didn't exist, the VDR markdown printed contradictory counts, and every policy carried the deploy date. Missing COEP headers were caught by ZAP. + Rule: keep changes small (CLAUDE.md §4). When a change alters what is published, verify the published set itself. `tests/test_published_claims.py` and `scripts/check-published-redaction.py` now hold these. + +## Infrastructure + +- **`make -C infrastructure pipeline` is not a verification step.** It ends in `apply-infra`, which runs `terraform apply` against production. +- **A bootstrap apply from a stale tree reverts merged changes.** A merged `tag:GetResources` grant would have been undone this way. + Rule: sync `infrastructure/bootstrap/` to `origin/main` before editing and before applying. The plan must show only your change. +- **A bootstrap apply during an in-flight deploy (2026-10-05)** published a trust center whose "pending trust-root changes" predated the apply. + Rule: apply first and then deploy, or let the run finish and redeploy. +- **Narratives drifted from deployed config.** Baseline text was out of step with DNSSEC being on and with 365-day CMK log retention (fixed 2026-07-09). + Rule: narrative must match config. Change both in the same PR. + +## Tooling + +- **A stale `opa` binary silently shrinks the policy suite.** An older `opa` can't parse these Rego v1 policies, and it *skips* about 15 policy tests instead of failing. + Rule: check `opa version` against `OPA_VERSION` in `deploy-with-opa.yml` if `test-policies` looks suspiciously green. +- **Vendored FedRAMP schemas are byte-pinned.** The loader refuses any file whose hash differs from `SOURCES.json`. Never edit one, even to fix a typo. + +## Settled decisions: don't "fix" these + +- **WAF is intentionally declined.** SC-7 and SC-5 are met through managed interfaces (CloudFront and API Gateway), AWS Shield Standard and throttling. A WAF's incremental layer-7 filtering is documented as the residual. Don't re-add it. +- **CI proves compliance, not article content.** The prose checks were removed from CI (#356). The long-form checks in `tools/essay/` stay local-only. +- **Parked code doesn't come back as a side effect.** Don't revive a removed generator while doing another change. +- More settled decisions live in `docs/architecture-decisions.md`. Read the relevant section before proposing a change to the same area. diff --git a/.claude/skills/site-content/SKILL.md b/.claude/skills/site-content/SKILL.md new file mode 100644 index 00000000..2a3b502f --- /dev/null +++ b/.claude/skills/site-content/SKILL.md @@ -0,0 +1,78 @@ +--- +name: site-content +description: Use when writing, editing, adding, retiring or restyling anything a visitor reads on samaydlette.com. That covers articles (website/pages/article-N.html); long-form research pages; the home, articles, books, projects, about and contact pages; the nav and footer; CSS and JS under website/assets; feed.xml; and sitemap.xml. Not for the Trust Center, /.well-known artifacts, generators, gates, Terraform or workflows: use compliance-pipeline for those. +--- + +# Site content + +How to change what visitors read. The invariants and autonomy rules in `CLAUDE.md` apply on top of this. + +## Voice and authorship: read first + +- **The opinions are the operator's.** Draft toward the position they have stated, and never supply one. If the position isn't clear, ask rather than fill the gap. +- Draft only what was requested and leave final wording to the operator. List AI-drafted passages in the PR so they can rework them in their own voice. +- Don't "improve" prose you weren't asked to touch: no tightening, retitling or restructuring of neighboring text. +- Every article and long-form page carries the disclaimer, worded identically on every page. Copy it verbatim from an existing article (`
`, which links "outsourcing my opinions" to `/pages/article-22.html`). Change its wording only when asked, and then change every copy in one PR. +- Claims about the system (encryption, controls, authorization) must match deployed config. Never assert a service's FedRAMP status without a current source, and never imply the site is authorized. + +## What a content change really is + +- **Every `*.html` under `website/` is hashed into the compliance inventory.** Editing or adding a page changes the inventory on the next deploy. That is expected and automatic. Never touch `website/.well-known/` or an inventory entry by hand. +- **Cache-busting is automatic.** The deploy rewrites the `?v=` value on every CSS and JS reference. Don't hand-edit those values or commit `npm run cache-bust` output. +- **The CSP is strict:** `script-src 'self'`, `style-src 'self'`, `img-src 'self' data:`, `font-src 'self'`, no frames. That means no inline `