From f8ffd97859bf8efcbd512b83baecc4c0fb23ee56 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 14:31:10 -0500 Subject: [PATCH 1/7] SCN: explicit evaluation gate, append-only evaluation log, published notifications and deadline checks Every change now carries an explicit significant-change evaluation (SCN-Type, SCN-Rationale, and SCN-Record for adaptive/transformative/emergency); a missing tag fails instead of defaulting to routine-recurring, and class-change blocks. The deploy appends every merged evaluation to a signed, append-only log and publishes every register row in FedRAMP's SCN schema with a Markdown view and an Atom feed, listed in the CPO. Business-day deadlines (US federal holidays) are read from the vendored rules; a scheduled workflow fails on anything overdue. Notification is publication only; nothing is sent. SCN-Type: not-significant SCN-Rationale: change-management process and compliance reporting only; no component, boundary, data flow or access change to the system. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 41 ++ .github/workflows/scn-deadlines.yml | 68 +++ .github/workflows/scn-tag.yml | 67 ++- data/frr-records.json | 365 ++++++++++---- docs/incident-response.md | 8 +- docs/policies/cm-policy.md | 4 +- docs/scn/README.md | 66 ++- docs/scn/TEMPLATE-transformative.md | 51 ++ docs/scn/evaluation-examples.md | 98 ++++ docs/scn/scn-register.csv | 14 +- infrastructure/schemas/freshness-config.json | 35 ++ scripts/_bizdays.py | 79 ++++ scripts/_scn.py | 408 ++++++++++++++++ scripts/build-cpo.py | 26 + scripts/build-scn.py | 410 ++++++++++++++++ scripts/check-scn-deadlines.py | 77 +++ scripts/scn-evaluate.py | 81 ++++ tests/fixtures/scn/bad/adaptive-no-record.md | 2 + tests/fixtures/scn/bad/class-change.md | 2 + .../scn/bad/index-previous-with-dropped.json | 17 + tests/fixtures/scn/bad/log-rewritten.json | 36 ++ tests/fixtures/scn/bad/log-truncated.json | 16 + tests/fixtures/scn/bad/missing-rationale.md | 4 + tests/fixtures/scn/bad/missing-type.md | 4 + .../fixtures/scn/bad/placeholder-rationale.md | 2 + .../scn/bad/register-adaptive-no-risks.csv | 2 + .../scn/bad/register-dates-out-of-order.csv | 2 + tests/fixtures/scn/bad/register-routine.csv | 2 + .../register-transformative-incomplete.csv | 2 + tests/fixtures/scn/bad/routine-with-record.md | 3 + .../scn/bad/transformative-too-soon.md | 3 + tests/fixtures/scn/bad/two-types.md | 3 + tests/fixtures/scn/bad/unknown-type.md | 2 + tests/fixtures/scn/good/adaptive.md | 3 + tests/fixtures/scn/good/emergency.md | 3 + tests/fixtures/scn/good/not-significant.md | 5 + .../scn/good/register-transformative.csv | 2 + .../good/routine-recurring-legacy-spelling.md | 2 + .../fixtures/scn/good/transformative-ready.md | 3 + tests/fixtures/scn/index.json | 10 + tests/fixtures/scn/log-previous.json | 11 + tests/test_scn.py | 446 ++++++++++++++++++ 42 files changed, 2318 insertions(+), 167 deletions(-) create mode 100644 .github/workflows/scn-deadlines.yml create mode 100644 docs/scn/TEMPLATE-transformative.md create mode 100644 docs/scn/evaluation-examples.md create mode 100644 scripts/_bizdays.py create mode 100644 scripts/_scn.py create mode 100644 scripts/build-scn.py create mode 100644 scripts/check-scn-deadlines.py create mode 100644 scripts/scn-evaluate.py create mode 100644 tests/fixtures/scn/bad/adaptive-no-record.md create mode 100644 tests/fixtures/scn/bad/class-change.md create mode 100644 tests/fixtures/scn/bad/index-previous-with-dropped.json create mode 100644 tests/fixtures/scn/bad/log-rewritten.json create mode 100644 tests/fixtures/scn/bad/log-truncated.json create mode 100644 tests/fixtures/scn/bad/missing-rationale.md create mode 100644 tests/fixtures/scn/bad/missing-type.md create mode 100644 tests/fixtures/scn/bad/placeholder-rationale.md create mode 100644 tests/fixtures/scn/bad/register-adaptive-no-risks.csv create mode 100644 tests/fixtures/scn/bad/register-dates-out-of-order.csv create mode 100644 tests/fixtures/scn/bad/register-routine.csv create mode 100644 tests/fixtures/scn/bad/register-transformative-incomplete.csv create mode 100644 tests/fixtures/scn/bad/routine-with-record.md create mode 100644 tests/fixtures/scn/bad/transformative-too-soon.md create mode 100644 tests/fixtures/scn/bad/two-types.md create mode 100644 tests/fixtures/scn/bad/unknown-type.md create mode 100644 tests/fixtures/scn/good/adaptive.md create mode 100644 tests/fixtures/scn/good/emergency.md create mode 100644 tests/fixtures/scn/good/not-significant.md create mode 100644 tests/fixtures/scn/good/register-transformative.csv create mode 100644 tests/fixtures/scn/good/routine-recurring-legacy-spelling.md create mode 100644 tests/fixtures/scn/good/transformative-ready.md create mode 100644 tests/fixtures/scn/index.json create mode 100644 tests/fixtures/scn/log-previous.json create mode 100644 tests/test_scn.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index a327c2de..f6c9c311 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1608,6 +1608,30 @@ jobs: --offering ../data/cds/offering.json --profile ../data/system-profile.json \ --overview certification-overview-package.json --ksi-signal ksi-signal.json + # Significant Change Notifications (SCN-CSO-HIS/HRM/NOM/INF) and the + # append-only evaluation log (SCN-CSO-MAR). The builder fails if this build + # would drop or rewrite anything the previous published copies hold, so they + # are fetched first: a 404 means nothing has been published yet, any other + # failure stops the deploy rather than restarting the record. + - name: Build Significant Change Notifications and the evaluation log + working-directory: infrastructure + env: + GH_TOKEN: ${{ github.token }} + run: | + fetch() { + code=$(curl -sSL -o "$2" -w '%{http_code}' "https://samaydlette.com/.well-known/$1") \ + || { echo "::error::cannot fetch the published $1"; exit 1; } + case "$code" in + 200) ;; + 404) rm -f "$2"; echo "$1 not published yet" ;; + *) echo "::error::fetching the published $1 returned HTTP $code"; exit 1 ;; + esac + } + fetch significant-change-notifications.json previous-scn-index.json + fetch scn-evaluations.json previous-scn-evaluations.json + python3 ../scripts/build-scn.py --previous-index previous-scn-index.json \ + --previous-log previous-scn-evaluations.json --commit "$GITHUB_SHA" + # The authorization-boundary map the trust center draws: the inventory's # components placed by docs/boundary/boundary-classification.json, connected # by what Terraform state says references what, with the data-flow table @@ -1700,6 +1724,10 @@ jobs: cosign sign-blob --yes --new-bundle-format --bundle policy-index.bundle policy-index.json cosign sign-blob --yes --new-bundle-format --bundle security-decision-record.bundle security-decision-record.json cosign sign-blob --yes --new-bundle-format --bundle certification-package-overview.bundle certification-package-overview.json + for a in significant-change-notifications scn-evaluations; do + cosign sign-blob --yes --new-bundle-format --bundle "$a.bundle" "$a.json" + done + cosign sign-blob --yes --new-bundle-format --bundle significant-change-notifications.atom.bundle significant-change-notifications.atom - name: Sign trust-center artifacts (boundary map, gate report, trust center) working-directory: infrastructure @@ -1728,6 +1756,8 @@ jobs: for a in vdr-detail-report vdr-accepted-vulnerabilities; do files="$files $a.md"; done files="$files ongoing-certification-report.json ongoing-certification-report.md" for a in certification-overview-package availability policy-index security-decision-record certification-package-overview; do files="$files $a.json $a.md"; done + for a in significant-change-notifications scn-evaluations; do files="$files $a.json $a.md"; done + files="$files significant-change-notifications.atom" for a in boundary-map reconcile-report trust-center conformance-results boundary-corroboration; do [ -f "$a.json" ] || continue files="$files $a.json" @@ -1787,6 +1817,14 @@ jobs: aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" aws s3 cp "$a.md" "s3://$BUCKET_NAME/.well-known/$a.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" done + # Significant Change Notifications + evaluation log (SCN-*) + bundles + human-readable, and the Atom feed + for a in significant-change-notifications scn-evaluations; do + aws s3 cp "$a.json" "s3://$BUCKET_NAME/.well-known/$a.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "$a.md" "s3://$BUCKET_NAME/.well-known/$a.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + done + aws s3 cp significant-change-notifications.atom "s3://$BUCKET_NAME/.well-known/significant-change-notifications.atom" --content-type "application/atom+xml; charset=utf-8" --cache-control "public, max-age=300" + aws s3 cp significant-change-notifications.atom.bundle "s3://$BUCKET_NAME/.well-known/significant-change-notifications.atom.bundle" --content-type application/json --cache-control "public, max-age=300" # Trust center: the generated boundary map, the gate's own report (it exists # only because the gate above passed) and the trust center's data. for a in boundary-map reconcile-report trust-center conformance-results boundary-corroboration; do @@ -1877,6 +1915,9 @@ jobs: check policy-index.json .well-known/policy-index.json check security-decision-record.json .well-known/security-decision-record.json check certification-package-overview.json .well-known/certification-package-overview.json + check significant-change-notifications.json .well-known/significant-change-notifications.json + check significant-change-notifications.atom .well-known/significant-change-notifications.atom + check scn-evaluations.json .well-known/scn-evaluations.json check iiw.csv .well-known/iiw.csv check boundary-map.json .well-known/boundary-map.json check reconcile-report.json .well-known/reconcile-report.json diff --git a/.github/workflows/scn-deadlines.yml b/.github/workflows/scn-deadlines.yml new file mode 100644 index 00000000..424efff6 --- /dev/null +++ b/.github/workflows/scn-deadlines.yml @@ -0,0 +1,68 @@ +# ============================================================================= +# SCN DEADLINE CHECK (SCN-ADP-NTF, SCN-TRF-NAF/NAV/UPD, SCN-CSO-EMG) +# ============================================================================= +# Once a business day, compares the published evaluation log and notification +# index with the register on main and fails on anything late and outstanding: +# a change named as adaptive/transformative/emergency with no record by its +# deadline, a notice not yet published after its deadline, or a transformative +# change's documentation not updated within 30 business days. The rules are in +# scripts/_scn.py (tests/test_scn.py). A failure raises or updates one GitHub +# issue, the same paper trail the evidence nightly uses. +# +# Reads only public URLs and this checkout: no AWS credentials, no writes +# outside the issue. +# ============================================================================= + +name: SCN Deadlines + +on: + schedule: + - cron: "17 13 * * 1-5" + workflow_dispatch: + +permissions: + contents: read + +jobs: + deadlines: + runs-on: ubuntu-latest + timeout-minutes: 5 + outputs: + result: ${{ steps.check.outcome }} + steps: + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Check SCN deadlines + id: check + run: python3 scripts/check-scn-deadlines.py + + alert: + name: Raise the overdue-SCN issue + runs-on: ubuntu-latest + needs: [deadlines] + if: always() && needs.deadlines.result == 'failure' + permissions: + issues: write + steps: + - name: Raise or update the overdue-SCN issue + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const TITLE = 'Significant Change Notification overdue'; + const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`; + const body = [ + 'The scheduled SCN deadline check failed: a significant change has a record or notice past its deadline.', + '', + `The "Check SCN deadlines" step in [this run](${runUrl}) names each item. Add the record to docs/scn/scn-register.csv and deploy, which publishes it; a notice is given when the deploy publishes it.`, + ].join('\n'); + const open = (await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, repo: context.repo.repo, state: 'open', per_page: 100, + })).filter(i => i.title === TITLE && !i.pull_request); + if (open.length) { + await github.rest.issues.createComment({ + owner: context.repo.owner, repo: context.repo.repo, issue_number: open[0].number, body, + }); + } else { + await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: TITLE, body }); + } diff --git a/.github/workflows/scn-tag.yml b/.github/workflows/scn-tag.yml index 7492dcbe..54a6d7b4 100644 --- a/.github/workflows/scn-tag.yml +++ b/.github/workflows/scn-tag.yml @@ -1,16 +1,19 @@ # ============================================================================= -# SCN TAG VALIDATOR +# SCN EVALUATION GATE (SCN-CSO-EVA) # ============================================================================= -# Enforces FedRAMP 20x Significant Change Notification rules SCN-CSO-EVA and -# SCN-CSO-MAR by reading the SCN-Type tag from either the PR description (on -# pull_request events) or the commit message (on push events). The git history -# is the SCN audit record (SCN-CSO-MAR), and this gate ensures every entry in -# that record carries a recognized SCN-Type categorization. +# Every change carries an explicit significant-change evaluation: an SCN-Type +# line, a one-line SCN-Rationale and, for adaptive, transformative and emergency +# changes, the SCN-Record it will be documented in. The pull request's +# description is read on pull_request events; on a push to main, the merged +# pull request's description (or the commit message for a direct push). # -# Categorization defaults to routine-recurring per docs/policies/cm-policy.md -# when no SCN-Type line is present. The validator only fails on a malformed -# SCN-Type value; missing tags are treated as the default. Operators must -# explicitly upgrade the categorization for Adaptive or Transformative changes. +# There is no default. A missing type, a missing or placeholder rationale, or an +# unrecognized value fails. class-change always fails: it is a new +# certification, not a significant change. A transformative change fails until +# its initial and final plans have been published 30 and 10 business days +# (SCN-TRF-NIP/NFP). The rules live in scripts/_scn.py and are unit-tested in +# tests/test_scn.py; the deploy writes every merged evaluation to the +# append-only log at /.well-known/scn-evaluations.json (SCN-CSO-MAR). # ============================================================================= name: SCN Tag @@ -28,41 +31,33 @@ permissions: jobs: scn-tag: runs-on: ubuntu-latest + timeout-minutes: 5 steps: - - name: Validate SCN-Type tag + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # Untrusted text (a PR description, a commit message) reaches the script + # only through the environment, never by ${{ }} interpolation into shell. + - name: Validate the SCN evaluation env: PR_BODY: ${{ github.event.pull_request.body }} COMMIT_MSG: ${{ github.event.head_commit.message }} EVENT_NAME: ${{ github.event_name }} + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} run: | set -euo pipefail if [ "${EVENT_NAME}" = "pull_request" ]; then - content="${PR_BODY:-}" + SCN_TEXT="${PR_BODY:-}" source_label="PR description" else - content="${COMMIT_MSG:-}" + SCN_TEXT="${COMMIT_MSG:-}" source_label="commit message" + pr=$(printf '%s\n' "${SCN_TEXT}" | head -n1 | sed -nE 's/^Merge pull request #([0-9]+) from .*/\1/p') + if [ -n "${pr}" ]; then + SCN_TEXT=$(gh api "repos/${REPO}/pulls/${pr}" --jq '.body // ""') + source_label="description of merged PR #${pr}" + fi fi - # Extract the SCN-Type line if present. Match optional leading hashes - # (Markdown heading) and case-insensitive 'SCN-Type:' prefix. - tag=$(printf '%s\n' "${content}" | grep -iE '^[[:space:]]*##?[[:space:]]*SCN-Type:' | head -n1 | sed -E 's/^[[:space:]]*##?[[:space:]]*SCN-Type:[[:space:]]*//I' | tr -d '[:space:]' || true) - case "${tag}" in - adaptive|routine-recurring|transformative) - echo "SCN-Type: ${tag} (from ${source_label})" - ;; - emergency) - # Emergency-change procedure per CR26 SCN-CSO-EMG. The change itself - # is permitted to bypass the formal SCN flow; the retroactive - # documentation is required per the IR runbook. - echo "::warning::SCN-Type: emergency (from ${source_label}). Emergency-change procedure invoked per SCN-CSO-EMG; retroactive SCN documentation required within 5 business days. See docs/incident-response.md." - ;; - "") - # Per CM policy default: missing tag = routine-recurring. This is the - # documented default for sole-operator direct pushes; do not fail. - echo "::notice::No SCN-Type line in ${source_label}; defaulting to routine-recurring per docs/policies/cm-policy.md." - ;; - *) - echo "::error::SCN-Type '${tag}' in ${source_label} is not a recognized value. Must be one of: adaptive | routine-recurring | transformative | emergency. See SCN-CSO-EVA / SCN-CSO-EMG in docs/policies/cm-policy.md." - exit 1 - ;; - esac + export SCN_TEXT + python3 scripts/scn-evaluate.py --text-env SCN_TEXT --source "${source_label}" diff --git a/data/frr-records.json b/data/frr-records.json index d84c52f9..ebfb3e40 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -969,164 +969,343 @@ { "frr_id": "SCN-ADP-NTF", "status": "Partially Implemented", - "implementation": "Each adaptive SCN record carries a new-risks summary (scn-register.csv new_risks_summary; SCN md section 5).", + "implementation": "An adaptive record's notice (with its new-risks summary, which the register requires) is due 10 business days after date_finished, counted with US federal holidays (scripts/_bizdays.py); it is given by publication in the certification data, and the index records the deadline and the date first published. The scheduled SCN deadline check fails and raises an issue when the notice is not published by its deadline. Notification is publication only, the method FedRAMP's rules name (an update to the Certification Data); nothing is sent to FedRAMP or anyone else.", "evidence": [], - "gap": "No notification has been sent to anyone: notify_by says 'No necessary parties'; FedRAMP is always a necessary party (FRD 'All Necessary Parties'), so this is not N/A; no sent-date is recorded for any SCN (artifact requires sent date and applied date). To close: Send each adaptive SCN through the NOM mechanism within 10 business days of date_finished, record sent_on in the register, and add a check that fails when date_finished + 10 business days passes without sent_on.", + "gap": "Not yet shown working: no notice has been published. The first deploy after this change publishes all six adaptive records; SCN-2026-006 is due 2026-11-10 and the other five are already past their deadlines, so they will be published marked late. Closes when a deploy publishes them (the operator approves deploys).", "closes_with": [ - "W5" + "sam" ] }, { "frr_id": "SCN-CSO-ARI", - "status": "Partially Implemented", - "implementation": "docs/scn/SCN-2026-001-silk-reeling.md sections 3-5 (boundary delta, SIA by control family, verification result) add information beyond SCN-CSO-INF.", - "evidence": [], - "gap": "Met at assessment, but no test, workflow step, published artifact or decision record shows it.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Each published notification adds, beyond the required items, the change's status, initiation/finish/verification dates, the pull requests that made it, the new-risks summary, its notices with deadlines and publication dates, and a link to the full record (boundary change, impact by control family, verification result).", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_build_publishes_every_register_row_in_the_fedramp_schema" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.json" + } ], "may_rationale": "Exercised. Change records add the boundary change, the security impact by control family and the verification result, so a reviewer can see why a change was classified as it was." }, { "frr_id": "SCN-CSO-EMG", - "status": "Partially Implemented", - "implementation": "docs/incident-response.md:86-104 emergency-change procedure; scn-tag.yml:53-58 recognizes 'emergency'.", - "evidence": [], - "gap": "Never exercised; 'notify all necessary parties' has no channel; no gate that requires the retroactive SCN materials (only a warning). To close: Add a check that opens/blocks until a retroactive SCN record exists for each emergency-tagged commit within 5 business days; route notification through the NOM mechanism.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "docs/incident-response.md (Emergency-change procedure), linked from the Certification Package Overview: an emergency change carries SCN-Type emergency with its SCN-Record; the gate accepts it and states the record is due; the retroactive register row (emergency = yes) is due within 5 business days of the change merging, enforced by the scheduled SCN deadline check, and the published notification marks each retroactive notice against that deadline. Notification is publication. Not yet invoked.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_emergency_change_owes_its_record_within_five_business_days" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_emergency_notices_are_retroactive_within_five_business_days" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_good_evaluation_passes" + }, + { + "kind": "step", + "ref": "scn-deadlines.yml#Check SCN deadlines" + } ], "may_rationale": "Kept available for emergencies: a security fix may need to ship before notice can be given. When it is used, the retroactive records the rule requires are produced within its timeframe." }, { "frr_id": "SCN-CSO-EVA", - "status": "Partially Implemented", - "implementation": ".github/workflows/scn-tag.yml (required check, confirmed live by check-manual-settings 'main requires 4 status checks', EXPECTED_REQUIRED_CHECKS l.39) validates an SCN-Type line; docs/policies/cm-policy.md:5; six adaptive records with categorization rationale (docs/scn/SCN-2026-00[1-6]*.md section 1).", - "evidence": [], - "gap": "Evaluation is not forced: a missing tag passes as routine-recurring (scn-tag.yml:59), and only 8 of 273 commits since 2026-08-01 carry any SCN-Type, so most changes have no recorded evaluation; the gate has no 'not significant' or 'class change' outcome and requires no rationale; commit 437be7b carries 'SCN-Type: Routine Recurring', a value the case statement (l.49-66) rejects. Adaptive tags do not require an SCN record (e.g. #376 tagged adaptive has none). Artifact gap: no example (real or fictitious) for routine-recurring, transformative or class change. SCN-2026-001 (new non-FedRAMP external interconnection) was judged adaptive 'at the upper edge'; the rationale should be revisited. To close: Require an explicit SCN-Type plus a one-line rationale on every PR (fail when missing); add values not-significant and class-change (class-change blocks and points to reassessment); fail when adaptive/transformative lacks a docs/scn record; add documented examples for each type (fictitious allowed).", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Every pull request (or direct push) must carry SCN-Type (not-significant, routine-recurring, adaptive, transformative, emergency, class-change), a one-line SCN-Rationale and, for adaptive/transformative/emergency, the SCN-Record that will document it; the required scn-tag check (scripts/scn-evaluate.py, rules in scripts/_scn.py) fails a change without them, with no default, and always fails class-change. A change named adaptive, transformative or emergency whose record is not in the register by its deadline fails the scheduled SCN deadline check. docs/scn/evaluation-examples.md gives one example per type (real for adaptive, fictitious otherwise), each checked against the gate. Changes merged before this gate mostly carry no evaluation; the evaluation log starts at the change that introduced it. SCN-2026-001's categorization (adaptive, at the upper edge, for a new external interconnection since removed by SCN-2026-006) is unchanged and left to the operator's review.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_evaluation_fails_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_empty_description_fails_there_is_no_default" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_workflow_runs_the_tested_gate_with_no_default" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_every_type_has_a_documented_example" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_adaptive_change_with_no_record_is_overdue_after_ten_business_days" + }, + { + "kind": "step", + "ref": "scn-tag.yml#Validate the SCN evaluation" + } ] }, { "frr_id": "SCN-CSO-HIS", - "status": "Partially Implemented", - "implementation": "docs/scn/ holds all six SCNs since 2026-06 (README: rows never deleted).", - "evidence": [], - "gap": "The SCN register and records are in the repository only; nothing under /.well-known/ publishes them, and the CPO lists no SCN material or how FedRAMP obtains it.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Every notification is published with the certification data at /.well-known/significant-change-notifications.json (+ .md, Atom feed), listed in the Certification Package Overview, and never pruned: a deploy that would drop a published notification or re-date a notice fails (retention exceeds 12 months). The register rows are never deleted.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_a_build_that_would_drop_a_published_notification_fails" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_a_published_notice_keeps_its_first_publication_date" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_cpo_lists_the_notification_mechanism" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.json" + } ] }, { "frr_id": "SCN-CSO-HRM", - "status": "Partially Implemented", - "implementation": "Human-readable: docs/scn/*.md and scn-register.csv.", - "evidence": [], - "gap": "No JSON form of SCNs or of the related audit records (CSV is not JSON); no explanation of how to request them or how sharing is decided. To close: Emit SCN JSON (schema-valid) and the evaluation log as JSON; add access + sharing statement to the CPO.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Notifications are published in JSON (FedRAMP SCN schema) and as a Markdown view; the related audit records (the evaluation log) likewise in JSON and Markdown. The index and the Certification Package Overview state that everything is public with no request needed, and how sharing is decided (everything is shared: no federal data, no agency customer).", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_build_publishes_every_register_row_in_the_fedramp_schema" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_log_appends_to_the_previous_published_version" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.json" + }, + { + "kind": "artifact", + "ref": ".well-known/scn-evaluations.json" + } ] }, { "frr_id": "SCN-CSO-INF", - "status": "Partially Implemented", - "implementation": "docs/scn/scn-register.csv columns cover all ten items (fedramp_id, assessor_name, related_vulnerability, scn_type, categorization_rationale, short_description, reason_for_change, customer_impact, plan_and_timeline, sia_reference, approver_name/title); per-change SIA in docs/scn/SCN-2026-00x-*.md.", - "evidence": [], - "gap": "Service Offering FedRAMP ID is the placeholder ''; not emitted in FedRAMP's SCN schema (tests/fixtures/cr26/good/scn.json exists but no builder); SCN-2026-006 verification still unrecorded (trust center scn_unverified); some impacted-control lists reference the retired OSCAL SSP/POA&M. To close: Generate per-SCN JSON in fedramp-significant-change-notifications-schema via _fedramp_schema.write_validated; fill the FedRAMP ID when assigned; record SCN-2026-006 verification.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "docs/scn/scn-register.csv carries the ten items for every record and scripts/_scn.py refuses a row missing one; each deploy writes every row as a notification in FedRAMP's SCN schema (scripts/build-scn.py via _fedramp_schema.write_validated) inside /.well-known/significant-change-notifications.json, with the security impact analysis linked. The Service Offering FedRAMP ID is published as not assigned, with the reason (the offering is not certified). SCN-2026-006's verification is recorded (2026-10-27). Older records' plans name artifacts since retired (the OSCAL SSP/POA&M); they describe the plan as it was.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_build_publishes_every_register_row_in_the_fedramp_schema" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_committed_register_is_valid" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_register_fails_for_its_reason" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.json" + } ] }, { "frr_id": "SCN-CSO-MAR", - "status": "Partially Implemented", - "implementation": "Git history + scn-tag.yml run logs; docs/scn/README.md 'How this relates' explains git history is the audit record; register and per-change records in docs/scn/.", - "evidence": [], - "gap": "Records of evaluation are incomplete because the default-to-routine path records no evaluation; Actions logs expire (default 90 days), so the gate's decisions are not durable; no explanation in the Certification Package of how FedRAMP obtains the records. To close: Write each evaluation (commit, type, rationale, evaluator, date) to an append-only signed log published with the certification data; state access in the CPO.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Each deploy appends the evaluation of every first-parent commit on main since the last entry (commit, merge date, pull request, SCN type, rationale, record, who merged it) to /.well-known/scn-evaluations.json (+ .md), signed with Sigstore and freshness-governed. The log is append-only against the previous published version: a build that would drop or rewrite an entry, or whose last entry has left main's history, fails. A change merged without a valid evaluation is logged with the problem, not skipped. The Certification Package Overview states how to obtain the records (public, no request needed). The log starts at the change that introduced it; earlier evaluations exist only for the six records in docs/scn.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_log_appends_to_the_previous_published_version" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_append_only_check_fails_each_known_bad_log" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_collect_logs_every_first_parent_commit_from_the_builder_onward" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_collect_fails_when_the_last_logged_commit_left_history" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_cpo_lists_the_notification_mechanism" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build Significant Change Notifications and the evaluation log" + }, + { + "kind": "artifact", + "ref": ".well-known/scn-evaluations.json" + } ] }, { "frr_id": "SCN-CSO-NOM", - "status": "Partially Implemented", - "implementation": "docs/scn/README.md: notification = publishing updated certification data; register notify_by column says 'No necessary parties ... the public GitHub push ... is the notification'.", - "evidence": [], - "gap": "Mechanism documented only in the repo README, not in the Certification Package (CPO); no list of available notification mechanisms (artifact); a git push is not a notification any party receives. To close: Offer real mechanisms (signed SCN JSON feed + Atom/RSS at /.well-known/, email list) and list them in the CPO.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "Mechanisms: an Atom feed (/.well-known/significant-change-notifications.atom, one entry per notice, subscribable with any feed reader), the signed JSON index and its Markdown view. They are listed, with how to obtain the evaluation records, in the Certification Package Overview's significant_change_notifications section. Notification is publication only, the method FedRAMP's rules name (an update to the Certification Data); nothing is sent to FedRAMP or anyone else.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_cpo_lists_the_notification_mechanism" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_feed_is_atom_with_one_entry_per_notice" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.atom" + } ], "may_rationale": "Exercised. Notice is given by a published, signed feed rather than email, because there are no agency customers to address; the mechanism is documented in the certification package." }, { "frr_id": "SCN-RTR-NNR", - "status": "Partially Implemented", - "implementation": "docs/scn/ contains only adaptive SCNs; cm-policy.md:5 routine-recurring changes produce no SCN record.", - "evidence": [], - "gap": "Met at assessment, but no test, workflow step, published artifact or decision record shows it.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "No formal notification for routine recurring changes: the register refuses a routine-recurring (or not-significant) row, and the evaluation gate refuses an SCN-Record on a routine-recurring or not-significant change.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_register_fails_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_evaluation_fails_for_its_reason" + } ] }, { "frr_id": "SCN-TRF-NAF", - "status": "Partially Implemented", - "implementation": "No transformative change has occurred (scn-register.csv: all adaptive); cm-policy.md:9 lists the transformative windows.", - "evidence": [], - "gap": "No post-finish notice step or 5-business-day deadline check. To close: Add post-finish notice fields and a deadline check (finish + 5 business days).", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "date_finished adds the after-finish notice, due 5 business days later and published with the record's current information; the scheduled SCN deadline check fails while it is unpublished past the deadline. No transformative change has occurred.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_and_deadlines" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_after_finish_and_verification_are_overdue_unpublished" + }, + { + "kind": "step", + "ref": "scn-deadlines.yml#Check SCN deadlines" + } ] }, { "frr_id": "SCN-TRF-NAV", - "status": "Partially Implemented", - "implementation": "No transformative change has occurred (scn-register.csv: all adaptive); cm-policy.md:9 lists the transformative windows.", - "evidence": [], - "gap": "No post-verification notice step carrying updates, new risks and the assessment report; no deadline check. To close: Add post-verification notice fields (updates, new risks, SAR link) and a deadline check (verification complete + 5 business days).", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "verified_on adds the after-verification notice, due 5 business days later; the register requires the new-risks summary and sar_reference (the assessment report, or why there is none) once verified_on is set; the scheduled SCN deadline check fails while the notice is unpublished past the deadline. No transformative change has occurred.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_and_deadlines" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_after_finish_and_verification_are_overdue_unpublished" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_incomplete_transformative_row_names_every_template_field" + }, + { + "kind": "step", + "ref": "scn-deadlines.yml#Check SCN deadlines" + } ] }, { "frr_id": "SCN-TRF-NFP", - "status": "Partially Implemented", - "implementation": "No transformative change has occurred (scn-register.csv: all adaptive); cm-policy.md:9 lists the transformative windows.", - "evidence": [], - "gap": "No final-plan notice step or 10-business-day check. To close: Add final-plan notice fields and gate (>=10 business days before start).", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "plan_final = yes publishes the final-plan notice, which carries the record's current information (every notice republishes all of it). The evaluation gate blocks the merge until it has been published at least 10 business days. No transformative change has occurred.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_evaluation_fails_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_good_evaluation_passes" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_and_deadlines" + }, + { + "kind": "step", + "ref": "scn-tag.yml#Validate the SCN evaluation" + } ] }, { "frr_id": "SCN-TRF-NIP", - "status": "Partially Implemented", - "implementation": "No transformative change has occurred (scn-register.csv: all adaptive); cm-policy.md:9 lists the transformative windows.", - "evidence": [], - "gap": "Only a sentence in policy; no template, no planned-start field, no 30-business-day check, no channel to notify parties. To close: Add a transformative SCN template with initial-plan and security-impact sections, sent_on fields and a gate that blocks merge of a transformative change until initial notice is >=30 business days old.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "A transformative record (docs/scn/TEMPLATE-transformative.md) requires its planned start and a summary of likely security impacts; its initial-plan notice is published with the next deploy and dated. The evaluation gate blocks the merge of the transformative change until the initial-plan notice has been published at least 30 business days (read from the published index; fails closed when the index cannot be read). No transformative change has occurred.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_evaluation_fails_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_good_evaluation_passes" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_fails_closed_without_the_published_index" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_notices_and_deadlines" + }, + { + "kind": "step", + "ref": "scn-tag.yml#Validate the SCN evaluation" + } ] }, { "frr_id": "SCN-TRF-TPR", - "status": "Not Implemented", - "implementation": "No transformative changes; no recorded policy on third-party review.", - "evidence": [], - "gap": "Neither a third-party review nor an explanation of why one was not engaged exists (artifact accepts either). To close: Add to the transformative template a required 'human validation needed? assessor engaged / reason not engaged' field.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "A transformative record must state whether the change needs human validation (tpr_human_validation) and name the third-party assessor engaged or why none was (tpr_assessor_or_reason); the register refuses a transformative row without them, and the published notification carries both. No transformative change has occurred.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_incomplete_transformative_row_names_every_template_field" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_each_known_bad_register_fails_for_its_reason" + } ] }, { "frr_id": "SCN-TRF-UPD", - "status": "Partially Implemented", - "implementation": "Machine-generated documentation (CPO, SDR, OCR) is rebuilt every deploy (deploy-with-opa.yml), so it tracks changes automatically.", - "evidence": [], - "gap": "Hand-written service documentation is not updated after changes: the Secure Configuration Guide still describes the Basic Auth gate retired by SCN-2026-002 (adaptive) months later; no check ties a transformative change to documentation updates within 30 business days. To close: Add a documentation-update checklist/fields to the SCN record (doc, updated_on) and a check that fails 30 business days after finish if listed docs are unchanged; fix the SCG now.", - "closes_with": [ - "W5" + "status": "Implemented", + "implementation": "A finished transformative record must list the service documentation to update (docs_to_update) or say how it was determined none was needed; the published notification carries the 30-business-day deadline and docs_updated_on, and the scheduled SCN deadline check fails when the deadline passes without an update. No transformative change has occurred. (The Secure Configuration Guide's stale Basic Auth text follows an adaptive change, SCN-2026-002, which this rule does not cover.)", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_transformative_documentation_update_is_overdue_after_thirty_business_days" + }, + { + "kind": "step", + "ref": "scn-deadlines.yml#Check SCN deadlines" + } ] }, { diff --git a/docs/incident-response.md b/docs/incident-response.md index 6a3f8f34..88101566 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -91,19 +91,19 @@ CR26 `SCN-CSO-EMG` permits the operator to execute significant changes — inclu **What gets bypassed.** During an emergency the operator may: -- Push directly to `main` without the usual SCN-Type categorization deliberation (an `emergency` label is still required on the commit message — see below). +- Merge without the usual categorization deliberation (an `SCN-Type: emergency` evaluation is still required — see below). - Skip the standard advance-notification timing for Adaptive (`SCN-ADP-NTF`, 10 business days) or Transformative (`SCN-TRF-NIP`/`NFP`/`NAF`/`NAV`, 30 / 10 / 5 / 5 business days, plus the 30-business-day documentation update in `SCN-TRF-UPD`) changes. - Defer the threat-model review and per-control implementation-statement updates that a Transformative change would normally trigger. **What still applies.** During and after an emergency the operator must: -1. Tag the commit message with `SCN-Type: emergency` so the SCN audit record reflects the emergency disposition. The CI workflow recognizes `emergency` as a fourth valid SCN-Type value alongside `routine-recurring`, `adaptive`, and `transformative`. +1. Carry `SCN-Type: emergency`, a one-line `SCN-Rationale:` and the `SCN-Record:` the retroactive record will use in the pull request description (or the commit message of a direct push), so the evaluation log records the emergency disposition. The `scn-tag` check accepts it and says the record is due. 2. Follow the rest of this IR runbook: detect, contain, eradicate, recover, after-action. -3. Within 5 business days of incident closure, retroactively produce the SCN materials that would have been produced in advance for the equivalent non-emergency change (per `SCN-CSO-EMG`): summary of the change, summary of new risks identified, copy of the security impact analysis, plan for any verification or assessment of impacted KSIs. +3. Within 5 business days, retroactively produce the SCN materials that would have been produced in advance for the equivalent non-emergency change (per `SCN-CSO-EMG`): summary of the change, summary of new risks identified, copy of the security impact analysis, plan for any verification or assessment of impacted KSIs. Count the 5 business days from the day the emergency change merged. The materials are a row in `docs/scn/scn-register.csv` with `emergency` = `yes` and the change in `evaluation_prs`, plus its record; the next deploy publishes them, which is the notification to all necessary parties. The scheduled SCN deadline check (`.github/workflows/scn-deadlines.yml`) fails and raises an issue if the record is not in the register within 5 business days of the emergency change merging, and the published index marks each retroactive notice against that deadline. 4. Append an after-action entry to the section above with the emergency-procedure invocation noted in the timeline. 5. Reopen the threat model in `docs/architecture-decisions.md` if the emergency change altered the threat surface, and update before the next security review. -**Documentation evidence.** Emergency-change procedures are documented in this section, in `docs/policies/cm-policy.md` (referenced under SCN integration), and in the `.github/workflows/scn-tag.yml` validator (which accepts `emergency` as a valid tag). Together these satisfy `SCN-CSO-EMG`'s "procedures should be documented in the FedRAMP Certification package" requirement. +**Documentation evidence.** Emergency-change procedures are documented in this section, in `docs/policies/cm-policy.md` (referenced under SCN integration), in the `.github/workflows/scn-tag.yml` gate (which accepts `emergency`), and in the Certification Package Overview, which links this section. Together these satisfy `SCN-CSO-EMG`'s "procedures should be documented in the FedRAMP Certification package" requirement. ## Pattern review (KSI-INR-RPI) diff --git a/docs/policies/cm-policy.md b/docs/policies/cm-policy.md index 0ce6d58c..fe8a41ee 100644 --- a/docs/policies/cm-policy.md +++ b/docs/policies/cm-policy.md @@ -1,8 +1,8 @@ # CM — Configuration Management -Configuration management is GitOps. Every change to infrastructure or content reaches `main` through a commit that triggers the OPA gate, the Terraform plan, the apply, the canonical inventory build, the Sigstore signing, and the publish. The default workflow for the sole operator is **direct push to `main`**; pull requests are used only when collaboration or staged review is desired (rare). The commit (or PR description, when a PR is used) is the change request, the review when applicable, the approval, and the audit record. +Configuration management is GitOps. Every change to infrastructure or content reaches `main` through a commit that triggers the OPA gate, the Terraform plan, the apply, the canonical inventory build, the Sigstore signing, and the publish. Changes reach `main` through pull requests; branch protection requires the status checks, `scn-tag` among them, to pass. The PR description is the change request and carries the significant-change evaluation; the merge is the approval. -The **Significant Change Notification (SCN) category** for any change is **Routine Recurring by default; no label is required for routine work**. The operator upgrades the categorization explicitly only when the change meets Adaptive or Transformative criteria per `SCN-CSO-EVA`, by including a line like `SCN-Type: adaptive` or `SCN-Type: transformative` in the commit message (or in the PR description, if a PR is used). A fourth value, `SCN-Type: emergency`, is reserved for emergency-change scenarios per `SCN-CSO-EMG` (see [`docs/incident-response.md`](../incident-response.md) for procedures and retroactive-documentation requirements). The CI workflow validates the tag on every push to `main` and every PR — it fails the build only on a malformed value (a recognized `SCN-Type:` line with a value that isn't one of the four recognized values). Missing tags are treated as Routine Recurring per the default. Audit records of these evaluations are the git history (`SCN-CSO-MAR`). Adaptive and Transformative changes — which produce a security impact analysis — additionally get a durable, structured record in [`docs/scn/`](../scn/): a per-change SCN record carrying the `SCN-CSO-INF` fields plus a copy of the SIA, and a row in the machine-and-human-readable register [`docs/scn/scn-register.csv`](../scn/scn-register.csv) (`SCN-CSO-HRM`), retained for at least 12 months (`SCN-CSO-HIS`). +The **Significant Change Notification (SCN) evaluation** is explicit on every change (`SCN-CSO-EVA`). Each pull request description (or direct-push commit message) carries an `SCN-Type:` line (`not-significant`, `routine-recurring`, `adaptive`, `transformative`, `emergency` or `class-change`), a one-line `SCN-Rationale:`, and for adaptive, transformative and emergency changes the `SCN-Record:` that will document it. The required `scn-tag` check fails a change without them; there is no default. `class-change` always fails: a change of certification class is a new certification and needs a new assessment. A transformative change cannot merge until its initial plan has been published for 30 business days and its final plan for 10. The format and one example per type are in [`docs/scn/evaluation-examples.md`](../scn/evaluation-examples.md); emergency changes follow [`docs/incident-response.md`](../incident-response.md). Each deploy appends every merged evaluation to the signed, append-only evaluation log at `/.well-known/scn-evaluations.json` (`SCN-CSO-MAR`). Adaptive and transformative changes get a row in [`docs/scn/scn-register.csv`](../scn/scn-register.csv) and a record with the security impact analysis; each deploy publishes them in FedRAMP's SCN schema with an Atom feed, which is how notice is given (`SCN-CSO-NOM`, `SCN-CSO-HIS`, `SCN-CSO-HRM`). A scheduled check fails on any record or notice past its deadline. See [`docs/scn/README.md`](../scn/README.md). The canonical inventory at `/.well-known/ksi-signal.json` is the authoritative system inventory (CM-8 family). It is generated automatically from Terraform state, Lambda package locks, and content hashes — see [`docs/ksi-signal.md`](../ksi-signal.md). Each component carries a normalized identifier (PURL/ARN/SHA-256/HBOM ref), a security category (per FIPS 199), and an information-flow tag (per `MAS-CSO-FLO`). diff --git a/docs/scn/README.md b/docs/scn/README.md index 037ab83a..64310f7e 100644 --- a/docs/scn/README.md +++ b/docs/scn/README.md @@ -5,31 +5,47 @@ per the SCN rules in the CR26 corpus (`providers/20x/rules/significant-change-no ## Contents -- **[`scn-register.csv`](scn-register.csv)** — the machine-readable **and** human-readable - SCN register (`SCN-CSO-HRM`). One row per significant change, carrying the - `SCN-CSO-INF` required fields. CSV is the format the FedRAMP SCN beta used to satisfy - both readability requirements simultaneously. -- **`SCN---.md`** — the human-readable SCN record + copy of the security - impact analysis for each change (`SCN-CSO-INF`, including item 9, the SIA). - -## How this relates to the rest of the system - -- **Audit records (`SCN-CSO-MAR`):** the git history is the audit record of SCN - evaluation activity. Every commit to `main` carries an `SCN-Type:` categorization - validated by [`.github/workflows/scn-tag.yml`](../../.github/workflows/scn-tag.yml); - the default is `routine-recurring` per [`docs/policies/cm-policy.md`](../policies/cm-policy.md), - and the operator upgrades to `adaptive` / `transformative` / `emergency` explicitly. - The register and the per-change records here are the durable, structured complement to - that history for Adaptive and Transformative changes (which produce a SIA). -- **Historical notifications (`SCN-CSO-HIS`):** at least **12 months** of SCNs are kept - here with the FedRAMP Certification data. Rows are never deleted; superseded records - are retained. -- **Notification mechanism (`SCN-CSO-NOM`):** the system has no agency customers today, - so notification is met by publishing the updated certification data — the KSI signal, - SDR, CPO and VDR report at `/.well-known/` — alongside these records. -- **Emergency changes (`SCN-CSO-EMG`):** handled per the IR runbook - ([`docs/incident-response.md`](../incident-response.md)); retroactive SCN materials are - added here within the required window. +- **[`scn-register.csv`](scn-register.csv)** — the register, and the source every published + notification is built from. One row per adaptive or transformative change, carrying the + `SCN-CSO-INF` fields, the dates the notice deadlines count from (`date_started`, + `date_finished`, `verified_on`), and for transformative changes the plan, third-party-review and + documentation-update fields. `scripts/_scn.py` validates it (`tests/test_scn.py`); a + routine-recurring row is refused (`SCN-RTR-NNR`). +- **`SCN---.md`** — the human-readable record and copy of the security impact + analysis for each change (`SCN-CSO-INF` item 9). +- **[`evaluation-examples.md`](evaluation-examples.md)** — the evaluation format and one example + per type (`SCN-CSO-EVA`). +- **[`TEMPLATE-transformative.md`](TEMPLATE-transformative.md)** — the transformative record + template: notice windows, third-party review, verification and documentation update. + +## How the process runs + +- **Evaluation (`SCN-CSO-EVA`).** Every pull request carries `SCN-Type:`, `SCN-Rationale:` and, + for adaptive, transformative and emergency changes, `SCN-Record:`. The required `scn-tag` + check ([`.github/workflows/scn-tag.yml`](../../.github/workflows/scn-tag.yml)) fails without + them; there is no default. `class-change` always fails. A transformative change fails until its + initial plan has been published 30 business days and its final plan 10. +- **Audit records (`SCN-CSO-MAR`).** Each deploy appends the evaluation of every change merged + since the last one (commit, type, rationale, record, who merged it, when) to the signed, + append-only log at `/.well-known/scn-evaluations.json` (and `.md`). A deploy that would drop or + rewrite an entry fails. +- **Notification (`SCN-CSO-NOM`).** FedRAMP's rules name the notification method as an update to + the Certification Data. Each deploy publishes every register row in FedRAMP's SCN schema at + `/.well-known/significant-change-notifications.json` (signed), its human-readable view (`.md`) + and an Atom feed (`significant-change-notifications.atom`) anyone can subscribe to; the + Certification Package Overview lists them. A notice is given when it is first published, and + the index records that date beside its deadline. **Nothing is sent by email or to FedRAMP.** +- **Deadlines.** Business days exclude weekends and US federal holidays (`scripts/_bizdays.py`). + Adaptive: 10 after finishing (`SCN-ADP-NTF`). Transformative: initial plan 30 before starting, + final plan 10 before, 5 after finishing, 5 after verification, documentation within 30 + (`SCN-TRF-*`). Emergency: the retroactive record within 5 (`SCN-CSO-EMG`). The scheduled + [`scn-deadlines`](../../.github/workflows/scn-deadlines.yml) workflow fails and raises an issue + on anything overdue. +- **History (`SCN-CSO-HIS`).** Notifications are never pruned; a deploy that would drop one or + re-date a notice fails. Rows here are never deleted. + +The six records below predate the published index: their notices were first published by the +deploy that introduced it, after their deadlines, and the index says so. ## Index diff --git a/docs/scn/TEMPLATE-transformative.md b/docs/scn/TEMPLATE-transformative.md new file mode 100644 index 00000000..2c5ecdfd --- /dev/null +++ b/docs/scn/TEMPLATE-transformative.md @@ -0,0 +1,51 @@ +# SCN-YYYY-NNN — Transformative change: + +Copy this file to `SCN-YYYY-NNN-<slug>.md` and add the row to +[`scn-register.csv`](scn-register.csv) **before** the change starts. The +register row is what the deploy publishes and what the checks read; the columns +named below are required by [`scripts/_scn.py`](../../scripts/_scn.py) for a +transformative row. + +## Timeline and notices + +| Notice | Rule | When | Register column that drives it | +| --- | --- | --- | --- | +| Initial plan | SCN-TRF-NIP | published ≥ 30 business days before `date_started` | the row exists with `date_started` | +| Final plan | SCN-TRF-NFP | published ≥ 10 business days before `date_started` | `plan_final` = `yes` | +| After finishing | SCN-TRF-NAF | within 5 business days of `date_finished` | `date_finished` | +| After verification | SCN-TRF-NAV | within 5 business days of `verified_on` | `verified_on`, `sar_reference`, `new_risks_summary` | +| Documentation updated | SCN-TRF-UPD | within 30 business days of `date_finished` | `docs_to_update`, `docs_updated_on` (or `docs_update_not_required`) | + +A notice is given when a deploy publishes it: the index records each notice's +deadline and the date it was first published. The SCN gate blocks the merge of +the change until the initial and final plans have been published long enough. +Business days exclude weekends and US federal holidays. + +## 1. Categorization (SCN-CSO-EVA) + +Why this change is transformative (FRD-TRF), and why it is not a class change. + +## 2. Required information (SCN-CSO-INF) + +Register columns: `fedramp_id`, `assessor_name`, `related_vulnerability`, +`categorization_rationale`, `short_description`, `reason_for_change`, +`customer_impact`, `plan_and_timeline`, `sia_reference` (this file), +`approver_name`, `approver_title`. + +## 3. Likely security impacts and changes in risk (SCN-TRF-NIP) + +Summary in `new_risks_summary`; detail here. + +## 4. Third-party review (SCN-TRF-TPR) + +- `tpr_human_validation`: `yes` or `no` — does the scope or impact need human validation? +- `tpr_assessor_or_reason`: the assessor engaged to review the scope and impact before the change starts, or why none was engaged. + +## 5. Verification, assessment and validation (SCN-TRF-NAV) + +The plan, the result, and `sar_reference`: the security assessment report, or why there is none. + +## 6. Documentation updates (SCN-TRF-UPD) + +`docs_to_update` (semicolon-separated paths) and, once done, `docs_updated_on`. +If none is needed, `docs_update_not_required` says how that was determined. diff --git a/docs/scn/evaluation-examples.md b/docs/scn/evaluation-examples.md new file mode 100644 index 00000000..0afe8ffe --- /dev/null +++ b/docs/scn/evaluation-examples.md @@ -0,0 +1,98 @@ +# Significant-change evaluation: format and one example per type (SCN-CSO-EVA) + +Every pull request (or direct push) to `main` carries an evaluation in its +description. [`.github/workflows/scn-tag.yml`](../../.github/workflows/scn-tag.yml) +fails the change without one; there is no default. The rules are in +[`scripts/_scn.py`](../../scripts/_scn.py). + +``` +SCN-Type: <not-significant | routine-recurring | adaptive | transformative | emergency | class-change> +SCN-Rationale: <one line: why the change is this type> +SCN-Record: SCN-YYYY-NNN (adaptive, transformative and emergency only) +``` + +The deploy copies every merged evaluation into the append-only log at +`/.well-known/scn-evaluations.json` (SCN-CSO-MAR). + +The types follow FedRAMP's definitions (FRD-SGC, FRD-RTR, FRD-ADP, FRD-TRF). A +change that is not likely to substantively affect the security or privacy +posture is **not-significant**. Examples marked *fictitious* are permitted by the +SCN-CSO-EVA artifact; they show the reasoning and are not changes to this system. + +## not-significant + +*Fictitious.* A typo fix on the about page. + +``` +SCN-Type: not-significant +SCN-Rationale: content-only edit to a public page; no component, boundary, data flow or access change. +``` + +## routine-recurring + +*Fictitious.* The weekly Dependabot patch bump of a library already in the +inventory, with no breaking change. + +``` +SCN-Type: routine-recurring +SCN-Rationale: weekly patch bump of an inventoried library, part of ongoing vulnerability remediation; no breaking change. +``` + +No notification is made (SCN-RTR-NNR): the gate refuses an `SCN-Record` on this +type, and the register refuses a routine-recurring row. + +## adaptive + +*Real:* [SCN-2026-006](SCN-2026-006-remove-anthropic-interconnection.md), the +removal of the Anthropic API interconnection. + +``` +SCN-Type: adaptive +SCN-Rationale: removes an external interconnection, a boundary-crossing flow and a secret; no new service or data, no class change. +SCN-Record: SCN-2026-006 +``` + +The record goes into [`scn-register.csv`](scn-register.csv) and is published +within 10 business days of the change finishing (SCN-ADP-NTF). + +## transformative + +*Fictitious.* The offering begins accepting agency user accounts and storing +their data: a new capability that changes how customers use the service. + +``` +SCN-Type: transformative +SCN-Rationale: introduces federal customer data and agency accounts, which changes existing risk determinations. +SCN-Record: SCN-2027-001 +``` + +The record is written from [`TEMPLATE-transformative.md`](TEMPLATE-transformative.md) +first. The gate blocks the merge until the initial plan has been published 30 +business days and the final plan 10 (SCN-TRF-NIP, SCN-TRF-NFP). + +## emergency + +*Fictitious.* A leaked credential is rotated immediately. + +``` +SCN-Type: emergency +SCN-Rationale: rotates a leaked credential now; waiting for notice windows would itself raise risk. +SCN-Record: SCN-2026-099 +``` + +The retroactive record is due within 5 business days +([`docs/incident-response.md`](../incident-response.md)); the scheduled deadline +check ([`.github/workflows/scn-deadlines.yml`](../../.github/workflows/scn-deadlines.yml)) +fails until it is in the register. + +## class-change + +*Fictitious.* A change that would move the offering out of Class C. + +``` +SCN-Type: class-change +SCN-Rationale: the offering would hold data that takes it above Class C. +``` + +The gate always fails this type: a class change is a new certification and +needs a new assessment, not a significant change notification. diff --git a/docs/scn/scn-register.csv b/docs/scn/scn-register.csv index a0842d96..9de859a3 100644 --- a/docs/scn/scn-register.csv +++ b/docs/scn/scn-register.csv @@ -1,7 +1,7 @@ -scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_finished,notify_by -SCN-2026-001,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),adaptive,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,"POAM-019..024 (all risk-accepted, Low residual) plus the new-ecosystem SCA blind-spot, remediated by adding Syft/Grype SCA of the built Lambda+SPA artifact to CI feeding the VDR aggregator (RA-5/VDR-CSO-DET).",Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,2026-06-06,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) -SCN-2026-002,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),POAM-021 / POAM-022 / POAM-023 (single-factor shared credential; authorizer-less API; unthrottled credential endpoint),adaptive,"Replaces the end-user authentication mechanism of an existing public-facing component (HTTP Basic Auth -> Cognito with mandatory TOTP MFA + API Gateway JWT authorizer). No class change, no federal customer data, no new external interconnection, so not Transformative; an authentication-model change is not routine-recurring maintenance. Resolves to Adaptive per SCN-CSO-EVA. Backfilled record: the change shipped 2026-06-22 via the gated PR flow; this row completes the register (SCN-CSO-HIS).","Silk Reeling auth replacement: Basic Auth retired; Cognito user pool (mandatory TOTP MFA, 14-char minimum, admin-only creation) with Hosted UI (code + PKCE); JWT authorizer on ANY /api/{proxy+}; $default stays open serving the SPA shell only; stage throttling 20 rps / burst 10; API access logging to a CMK-encrypted log group.",Remediate POAM-021/022/023: retire the single-factor shared credential and gate the data API at the edge with rate limiting.,App users sign in with an invited individual account and mandatory TOTP MFA instead of a shared password. No agency customers exist.,"Gated deploy (OPA + Checkov gate) -> Cognito pool + authorizer + throttling applied via Terraform -> post-implementation verification of live authorizer/MFA/throttling/logging -> KSI signal + OSCAL SSP + POA&M re-emitted. Controls/KSIs re-verified: IA-2(x)/IA-8, AC-7, SC-5, AU-2/AU-3, KSI-IAM-*.",docs/scn/SCN-2026-002-cognito-auth.md,"Shared-credential and unthrottled-endpoint risks retired with POAM-021/023 closure. Residual: TOTP is not phishing-resistant (WebAuthn/FIDO2 upgrade path documented, POAM-025 direction); Cognito availability becomes a sign-in dependency (AWS-managed).",Sam Aydlette,System Owner / Authorizing Operator,"Implemented - live in production since 2026-06-22 (Task 3; POAM-021/022/023 closed); post-implementation verification COMPLETE 2026-07-06 via read-only AWS CLI (JWT authorizer on data routes, MFA ON, 14-char policy, admin-only creation, 20/10 throttling, access logging live)",2026-06-20,2026-06-22,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) -SCN-2026-003,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),AU-2/AU-11 control-plane audit gap (no durable CloudTrail trail; 90-day Event History only),adaptive,"Net-new internal service component (CloudTrail trail + delivery bucket). No new ingress/egress, no auth change, no customer impact, no class change - not Transformative; a net-new component is not routine-recurring maintenance. Conservatively Adaptive per SCN-CSO-EVA (lower edge: purely internal detective tooling).","Multi-region CloudTrail management-events trail with log-file validation, delivered to a dedicated locked-down S3 bucket; AU-11 tiering 12mo active + Deep Archive to 30mo. Deploy role can create/configure but not stop/delete the trail.",Close the control-plane audit gap: SSP AU-family statements assumed CloudTrail coverage that did not durably exist.,None (internal detective control).,"Bootstrap apply (deploy-role cloudtrail-management grant, manual) -> merge -> gated deploy creates trail + bucket -> post-implementation verification (get-trail-status IsLogging, objects delivered, audit_log_trail component in the next signal).",docs/scn/SCN-2026-003-cloudtrail.md,Strictly additive detective coverage. Residuals documented inline: SSE-S3 not CMK (POAM-029-consistent); no CloudWatch Logs integration / SNS (quarterly review per KSI-MLA-RVL).,Sam Aydlette,System Owner / Authorizing Operator,Implemented - trail live and delivering; post-implementation verification COMPLETE 2026-07-09 (gate green end-to-end; AWSLogs/<account>/ objects delivered; audit_log_trail component in the published signal with data_sensitivity internal; POAM-029/032 dispositions in the published VDR),2026-07-08,2026-07-09,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) -SCN-2026-004,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),CA-7/IR-6 monitoring gap (evidence nightly failed 2026-09-09..24 unalerted; VDR 12 days stale vs 24h policy; live drift check skipped),adaptive,"Net-new internal components (watchdog Lambda, 3 CloudWatch alarms, CMK-encrypted SNS topic) plus one new outbound flow: alarm metadata by email to the operator email, out of boundary per ROT #3 (flow I). Not Transformative: no federal data, no critical third party handling significant information, no auth/customer-responsibility/class change. Backfilled: shipping PRs #357/#359/#361 carried no SCN-Type and defaulted to routine-recurring.","Evidence SLA watchdog pages the operator by email (SNS) when published evidence goes stale or the evidence nightly fails; nightly runs twice daily, writes a status beacon, and runs its live drift check independently of the vulnerability gate.",The evidence nightly failed every night 2026-09-09..24 with only a GitHub issue as signal; the published VDR breached the 24h reporting policy and the vulnerability gate short-circuited the live reconciliation.,None (no agency customers; internal detective control).,"Bootstrap grants (deploy role, operators group; operator-applied after plan review) -> merge -> gated deploy creates watchdog/topic/alarms -> out-of-band email subscription -> post-implementation verification (forced alarm, delivery metrics).",docs/scn/SCN-2026-004-evidence-alerting.md,"Additive detective control. New outbound flow carries alarm metadata only (no evidence content or credentials); SNS email is not end-to-end encrypted, recorded as acceptable for that content. Watchdog has no internet egress; unattended-path permissions unchanged. ~$0.80/month.",Sam Aydlette,System Owner / Authorizing Operator,"Implemented 2026-09-25; post-implementation verification COMPLETE 2026-09-25 (forced alarm: 2 delivered, 0 failed; all alarms OK). Inventory/SSP/boundary documentation aligned 2026-09-27.",2026-09-25,2026-09-25,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) -SCN-2026-005,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),AC-6/CM-5 exposure: pull-request CI runs received the full deploy role without the prod environment approval,adaptive,"Changes the privileged-identity model of the CI/CD path (one new read-only IAM role; deploy-role trust narrowed to the reviewer-gated prod environment). Same class as SCN-2026-002's access-model change. Not Transformative: no new external service, data flow or component beyond one IAM role; no federal data; no customer-responsibility or class change.","compliance-check (terraform plan + OPA, on pull requests and main pushes) moves to a read-only plan role; the deploy role then trusts only the reviewer-gated prod environment.","The deploy role trusted pull_request and main-ref subjects because compliance-check planned with it, so every PR run held the full deploy permission set (IAM PutRolePolicy/PassRole on a Lambda role, Lambda code updates) without the prod approval gate.",None (no agency customers).,#374 plan role (operator-applied) -> AWS_PLAN_ROLE_ARN -> #375 compliance-check switch (verified by its CI run) -> this change: deploy trust narrowed to environment:prod (operator-applied after plan review) -> post-implementation verification.,docs/scn/SCN-2026-005-ci-identity-split.md,Net reduction: deploy credentials exist only inside an approved deploy. Plan role reads the Terraform state object (not new exposure: the deploy role already could from the same PRs) and cannot write except the lock item; data-plane reads denied. No cost.,Sam Aydlette,System Owner / Authorizing Operator,"Implemented and verified 2026-09-28 (#374, #375, #378 applied; deploy run 36434974425, PR check 36451980170, main-push check 36483804056).",2026-09-28,,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) -SCN-2026-006,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),"POAM-020 (Anthropic API interconnection, risk-accepted); POAM-019 (Anthropic key rotation, false positive)",adaptive,"Removes an external interconnection, a boundary-crossing data flow and a secret; changes the authorization boundary and SSP interconnections, so more than routine-recurring. Not Transformative: no new service, data flow or component; no federal data; no customer-responsibility or class change.","Silk Reeling app stops calling the Anthropic API and writes feedback from the scores; the API-key secret, its two IAM grants and env var are removed. LLM feedback becomes a customer-configurable option, disabled in this deployment.",The interconnection was a risk-accepted SA-9/CA-3 item to a service without a FedRAMP authorization and its key had expired; the app produces useful feedback without it.,None (no agency customers). App users get feedback written from their scores.,"App default-off (silk-reeling-mirror ADR-0009) -> this change (terraform plan review, gated deploy) -> post-implementation verification -> close POAM-020 and retire POAM-019.",docs/scn/SCN-2026-006-remove-anthropic-interconnection.md,"Net reduction: no app data leaves the boundary, no third-party credential stored, two IAM grants removed. No new risk.",Sam Aydlette,System Owner / Authorizing Operator,Implemented — verified live 2026-10-27 (secret scheduled for deletion; IAM and key policies clear; published SSP and signal without the interconnection; verify-published PASS),2026-10-26,2026-10-27,No necessary parties (no sponsor/customers); the public GitHub push that publishes the certification data is the notification (SCN-CSO-NOM / SCN-ADP-NTF) +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2026-001,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),adaptive,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,"POAM-019..024 (all risk-accepted, Low residual) plus the new-ecosystem SCA blind-spot, remediated by adding Syft/Grype SCA of the built Lambda+SPA artifact to CI feeding the VDR aggregator (RA-5/VDR-CSO-DET).",Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,,2026-06-06,2026-06-08,no,#82,,,,,,, +SCN-2026-002,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),POAM-021 / POAM-022 / POAM-023 (single-factor shared credential; authorizer-less API; unthrottled credential endpoint),adaptive,"Replaces the end-user authentication mechanism of an existing public-facing component (HTTP Basic Auth -> Cognito with mandatory TOTP MFA + API Gateway JWT authorizer). No class change, no federal customer data, no new external interconnection, so not Transformative; an authentication-model change is not routine-recurring maintenance. Resolves to Adaptive per SCN-CSO-EVA. Backfilled record: the change shipped 2026-06-22 via the gated PR flow; this row completes the register (SCN-CSO-HIS).","Silk Reeling auth replacement: Basic Auth retired; Cognito user pool (mandatory TOTP MFA, 14-char minimum, admin-only creation) with Hosted UI (code + PKCE); JWT authorizer on ANY /api/{proxy+}; $default stays open serving the SPA shell only; stage throttling 20 rps / burst 10; API access logging to a CMK-encrypted log group.",Remediate POAM-021/022/023: retire the single-factor shared credential and gate the data API at the edge with rate limiting.,App users sign in with an invited individual account and mandatory TOTP MFA instead of a shared password. No agency customers exist.,"Gated deploy (OPA + Checkov gate) -> Cognito pool + authorizer + throttling applied via Terraform -> post-implementation verification of live authorizer/MFA/throttling/logging -> KSI signal + OSCAL SSP + POA&M re-emitted. Controls/KSIs re-verified: IA-2(x)/IA-8, AC-7, SC-5, AU-2/AU-3, KSI-IAM-*.",docs/scn/SCN-2026-002-cognito-auth.md,"Shared-credential and unthrottled-endpoint risks retired with POAM-021/023 closure. Residual: TOTP is not phishing-resistant (WebAuthn/FIDO2 upgrade path documented, POAM-025 direction); Cognito availability becomes a sign-in dependency (AWS-managed).",Sam Aydlette,System Owner / Authorizing Operator,"Implemented - live in production since 2026-06-22 (Task 3; POAM-021/022/023 closed); post-implementation verification COMPLETE 2026-07-06 via read-only AWS CLI (JWT authorizer on data routes, MFA ON, 14-char policy, admin-only creation, 20/10 throttling, access logging live)",2026-06-20,,2026-06-22,2026-07-06,no,,,,,,,, +SCN-2026-003,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),AU-2/AU-11 control-plane audit gap (no durable CloudTrail trail; 90-day Event History only),adaptive,"Net-new internal service component (CloudTrail trail + delivery bucket). No new ingress/egress, no auth change, no customer impact, no class change - not Transformative; a net-new component is not routine-recurring maintenance. Conservatively Adaptive per SCN-CSO-EVA (lower edge: purely internal detective tooling).","Multi-region CloudTrail management-events trail with log-file validation, delivered to a dedicated locked-down S3 bucket; AU-11 tiering 12mo active + Deep Archive to 30mo. Deploy role can create/configure but not stop/delete the trail.",Close the control-plane audit gap: SSP AU-family statements assumed CloudTrail coverage that did not durably exist.,None (internal detective control).,"Bootstrap apply (deploy-role cloudtrail-management grant, manual) -> merge -> gated deploy creates trail + bucket -> post-implementation verification (get-trail-status IsLogging, objects delivered, audit_log_trail component in the next signal).",docs/scn/SCN-2026-003-cloudtrail.md,Strictly additive detective coverage. Residuals documented inline: SSE-S3 not CMK (POAM-029-consistent); no CloudWatch Logs integration / SNS (quarterly review per KSI-MLA-RVL).,Sam Aydlette,System Owner / Authorizing Operator,Implemented - trail live and delivering; post-implementation verification COMPLETE 2026-07-09 (gate green end-to-end; AWSLogs/<account>/ objects delivered; audit_log_trail component in the published signal with data_sensitivity internal; POAM-029/032 dispositions in the published VDR),2026-07-08,,2026-07-09,2026-07-09,no,#225,,,,,,, +SCN-2026-004,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),CA-7/IR-6 monitoring gap (evidence nightly failed 2026-09-09..24 unalerted; VDR 12 days stale vs 24h policy; live drift check skipped),adaptive,"Net-new internal components (watchdog Lambda, 3 CloudWatch alarms, CMK-encrypted SNS topic) plus one new outbound flow: alarm metadata by email to the operator email, out of boundary per ROT #3 (flow I). Not Transformative: no federal data, no critical third party handling significant information, no auth/customer-responsibility/class change. Backfilled: shipping PRs #357/#359/#361 carried no SCN-Type and defaulted to routine-recurring.","Evidence SLA watchdog pages the operator by email (SNS) when published evidence goes stale or the evidence nightly fails; nightly runs twice daily, writes a status beacon, and runs its live drift check independently of the vulnerability gate.",The evidence nightly failed every night 2026-09-09..24 with only a GitHub issue as signal; the published VDR breached the 24h reporting policy and the vulnerability gate short-circuited the live reconciliation.,None (no agency customers; internal detective control).,"Bootstrap grants (deploy role, operators group; operator-applied after plan review) -> merge -> gated deploy creates watchdog/topic/alarms -> out-of-band email subscription -> post-implementation verification (forced alarm, delivery metrics).",docs/scn/SCN-2026-004-evidence-alerting.md,"Additive detective control. New outbound flow carries alarm metadata only (no evidence content or credentials); SNS email is not end-to-end encrypted, recorded as acceptable for that content. Watchdog has no internet egress; unattended-path permissions unchanged. ~$0.80/month.",Sam Aydlette,System Owner / Authorizing Operator,"Implemented 2026-09-25; post-implementation verification COMPLETE 2026-09-25 (forced alarm: 2 delivered, 0 failed; all alarms OK). Inventory/SSP/boundary documentation aligned 2026-09-27.",2026-09-25,,2026-09-25,2026-09-25,no,#357;#359;#361,,,,,,, +SCN-2026-005,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),AC-6/CM-5 exposure: pull-request CI runs received the full deploy role without the prod environment approval,adaptive,"Changes the privileged-identity model of the CI/CD path (one new read-only IAM role; deploy-role trust narrowed to the reviewer-gated prod environment). Same class as SCN-2026-002's access-model change. Not Transformative: no new external service, data flow or component beyond one IAM role; no federal data; no customer-responsibility or class change.","compliance-check (terraform plan + OPA, on pull requests and main pushes) moves to a read-only plan role; the deploy role then trusts only the reviewer-gated prod environment.","The deploy role trusted pull_request and main-ref subjects because compliance-check planned with it, so every PR run held the full deploy permission set (IAM PutRolePolicy/PassRole on a Lambda role, Lambda code updates) without the prod approval gate.",None (no agency customers).,#374 plan role (operator-applied) -> AWS_PLAN_ROLE_ARN -> #375 compliance-check switch (verified by its CI run) -> this change: deploy trust narrowed to environment:prod (operator-applied after plan review) -> post-implementation verification.,docs/scn/SCN-2026-005-ci-identity-split.md,Net reduction: deploy credentials exist only inside an approved deploy. Plan role reads the Terraform state object (not new exposure: the deploy role already could from the same PRs) and cannot write except the lock item; data-plane reads denied. No cost.,Sam Aydlette,System Owner / Authorizing Operator,"Implemented and verified 2026-09-28 (#374, #375, #378 applied; the deploy, a pull-request check and a main-push check each passed).",2026-09-28,,2026-09-28,2026-09-28,no,#374;#375;#378,,,,,,, +SCN-2026-006,<FR-CERT-ID>,N/A (sole-operator self-attestation; no 3PAO engaged),"POAM-020 (Anthropic API interconnection, risk-accepted); POAM-019 (Anthropic key rotation, false positive)",adaptive,"Removes an external interconnection, a boundary-crossing data flow and a secret; changes the authorization boundary and SSP interconnections, so more than routine-recurring. Not Transformative: no new service, data flow or component; no federal data; no customer-responsibility or class change.","Silk Reeling app stops calling the Anthropic API and writes feedback from the scores; the API-key secret, its two IAM grants and env var are removed. LLM feedback becomes a customer-configurable option, disabled in this deployment.",The interconnection was a risk-accepted SA-9/CA-3 item to a service without a FedRAMP authorization and its key had expired; the app produces useful feedback without it.,None (no agency customers). App users get feedback written from their scores.,"App default-off (silk-reeling-mirror ADR-0009) -> this change (terraform plan review, gated deploy) -> post-implementation verification -> close POAM-020 and retire POAM-019.",docs/scn/SCN-2026-006-remove-anthropic-interconnection.md,"Net reduction: no app data leaves the boundary, no third-party credential stored, two IAM grants removed. No new risk.",Sam Aydlette,System Owner / Authorizing Operator,Implemented and verified 2026-10-27 (secret scheduled for deletion; IAM and key policies clear; published SSP and signal without the interconnection; verify-published PASS),2026-10-26,,2026-10-27,2026-10-27,no,#449,,,,,,, diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index 7d02d3de..cd4b2f02 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -276,6 +276,41 @@ "signed": true, "signature": ".well-known/conformance-results.bundle", "note": "The conformance suite's results for the method profile (REQ-GOV-2), run, signed and published by the deploy." + }, + { + "path": ".well-known/significant-change-notifications.json", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "json", + "field": "generated_at" + }, + "signed": true, + "signature": ".well-known/significant-change-notifications.bundle", + "note": "Significant Change Notifications index (SCN-CSO-HIS/HRM/NOM), rebuilt every deploy from docs/scn/scn-register.csv; never pruned." + }, + { + "path": ".well-known/significant-change-notifications.atom", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "last_modified" + }, + "signed": true, + "signature": ".well-known/significant-change-notifications.atom.bundle", + "note": "Atom feed of the SCN notices (SCN-CSO-NOM); its <updated> is the last notice's date, so the object's last-modified time is used." + }, + { + "path": ".well-known/scn-evaluations.json", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "json", + "field": "generated_at" + }, + "signed": true, + "signature": ".well-known/scn-evaluations.bundle", + "note": "Append-only significant-change evaluation log (SCN-CSO-MAR), one entry per change merged to main." } ] } diff --git a/scripts/_bizdays.py b/scripts/_bizdays.py new file mode 100644 index 00000000..bb529a65 --- /dev/null +++ b/scripts/_bizdays.py @@ -0,0 +1,79 @@ +"""Business-day arithmetic for FedRAMP timeframes ("bizdays" in the rules). + +A business day is a weekday that is not a US federal holiday (5 U.S.C. 6103). +Holidays are computed, not listed, so no year runs out: + + New Year's Day January 1 + Birthday of Martin Luther King, Jr. third Monday in January + Washington's Birthday third Monday in February + Memorial Day last Monday in May + Juneteenth June 19 + Independence Day July 4 + Labor Day first Monday in September + Columbus Day second Monday in October + Veterans Day November 11 + Thanksgiving Day fourth Thursday in November + Christmas Day December 25 + +A fixed-date holiday that falls on a Saturday is observed the Friday before, +one on a Sunday the Monday after (5 U.S.C. 6103(b), Executive Order 11582). +New Year's Day on a Saturday is therefore observed on December 31 of the +year before. + +Stdlib only. +""" + +from datetime import date, timedelta +from functools import lru_cache + +_FIXED = ((1, 1), (6, 19), (7, 4), (11, 11), (12, 25)) + + +def _nth_weekday(year, month, weekday, n): + """The nth `weekday` (Mon=0) of the month; n=-1 is the last.""" + if n > 0: + first = date(year, month, 1) + return first + timedelta(days=(weekday - first.weekday()) % 7 + 7 * (n - 1)) + nxt = date(year + (month == 12), month % 12 + 1, 1) + last = nxt - timedelta(days=1) + return last - timedelta(days=(last.weekday() - weekday) % 7) + + +def _observed(d): + if d.weekday() == 5: + return d - timedelta(days=1) + if d.weekday() == 6: + return d + timedelta(days=1) + return d + + +@lru_cache(maxsize=64) +def federal_holidays(year): + """The observed US federal holidays that fall in `year`.""" + days = set() + for y in (year, year + 1): # next year's New Year's Day may be observed on Dec 31 + days |= {_observed(date(y, m, d)) for m, d in _FIXED} + days |= { + _nth_weekday(y, 1, 0, 3), # MLK + _nth_weekday(y, 2, 0, 3), # Washington's Birthday + _nth_weekday(y, 5, 0, -1), # Memorial Day + _nth_weekday(y, 9, 0, 1), # Labor Day + _nth_weekday(y, 10, 0, 2), # Columbus Day + _nth_weekday(y, 11, 3, 4), # Thanksgiving + } + return frozenset(d for d in days if d.year == year) + + +def is_business_day(d): + return d.weekday() < 5 and d not in federal_holidays(d.year) + + +def add_business_days(d, n): + """The date n business days after d (n < 0: before). n == 0 returns d.""" + step = 1 if n >= 0 else -1 + left = abs(n) + while left: + d += timedelta(days=step) + if is_business_day(d): + left -= 1 + return d diff --git a/scripts/_scn.py b/scripts/_scn.py new file mode 100644 index 00000000..c4645b04 --- /dev/null +++ b/scripts/_scn.py @@ -0,0 +1,408 @@ +"""Significant Change Notification rules as code (SCN-*). + +One module for everything the SCN gate, the deploy-time builder and the +scheduled deadline check share: + +- the evaluation every change carries (SCN-CSO-EVA): an `SCN-Type:` line, an + `SCN-Rationale:` line and, for a change that needs a notification, an + `SCN-Record:` line naming its record in docs/scn/scn-register.csv; +- the register (docs/scn/scn-register.csv) and its validation (SCN-CSO-INF, + SCN-RTR-NNR, the transformative template fields); +- the notices each record owes and their deadlines in business days, read from + the vendored FedRAMP rules (SCN-ADP-NTF, SCN-TRF-NIP/NFP/NAF/NAV/UPD), plus + the operator's 5-business-day retroactive window for emergency changes + (SCN-CSO-EMG, docs/incident-response.md); +- the evaluation log (SCN-CSO-MAR) and the published notification index + (SCN-CSO-HIS): both only ever grow, and a build that would drop or rewrite a + published entry fails. + +Notification is publication: FedRAMP's rules name the method for every SCN +notice as an update to the FedRAMP Certification Data, and that is all this +code does. It sends nothing to anyone. + +Stdlib only; dates are ISO strings in every file. +""" + +import csv +import re +import sys +from datetime import date +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _bizdays # noqa: E402 +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +REGISTER = REPO / "docs" / "scn" / "scn-register.csv" +BASE = "https://samaydlette.com/.well-known/" +INDEX_NAME = "significant-change-notifications" +LOG_NAME = "scn-evaluations" +FEED_NAME = "significant-change-notifications.atom" +SOURCE_URL = "https://github.com/sam-aydlette/samaydlette.com/blob/main/" + +# Every value an evaluation may carry. `class-change` is a valid evaluation +# that the gate refuses: a change of certification class is not a significant +# change at all but a new certification, and it needs a new assessment. +TYPES = ("not-significant", "routine-recurring", "adaptive", "transformative", "emergency", "class-change") +# Evaluations that owe a notification record. +NEEDS_RECORD = ("adaptive", "transformative", "emergency") +# The types a record may have (SCN-RTR-NNR: no formal notification for routine +# recurring changes, and none for changes that are not significant). +RECORD_TYPES = ("adaptive", "transformative") +# Operator procedure (docs/incident-response.md): retroactive SCN materials for +# an emergency change within 5 business days. +EMERGENCY_BIZDAYS = 5 + +SCN_ID_RE = re.compile(r"^SCN-\d{4}-\d{3}$") +_LINE = r"^[ \t>]*(?:#+[ \t]*)?(?:[-*][ \t]+)?(?:\*\*)?{key}(?:\*\*)?[ \t]*:(?:\*\*)?[ \t]*(.*?)[ \t]*$" +TYPE_LINE = re.compile(_LINE.format(key="SCN-Type"), re.I | re.M) +RATIONALE_LINE = re.compile(_LINE.format(key="SCN-Rationale"), re.I | re.M) +RECORD_LINE = re.compile(_LINE.format(key="SCN-Record"), re.I | re.M) +PLACEHOLDER = re.compile(r"^(<.*>|tbd|todo|n/?a|none|-+|\.+|same|see above|see below)$", re.I) +MIN_RATIONALE = 15 +MAX_RATIONALE = 500 + +REGISTER_COLUMNS = ( + "scn_id", "fedramp_id", "assessor_name", "related_vulnerability", "scn_type", "categorization_rationale", + "short_description", "reason_for_change", "customer_impact", "plan_and_timeline", "sia_reference", + "new_risks_summary", "approver_name", "approver_title", "status", "date_initiated", "date_started", + "date_finished", "verified_on", "emergency", "evaluation_prs", "plan_final", "tpr_human_validation", + "tpr_assessor_or_reason", "sar_reference", "docs_to_update", "docs_updated_on", "docs_update_not_required", +) +INF_REQUIRED = ("scn_id", "scn_type", "categorization_rationale", "short_description", "reason_for_change", + "customer_impact", "plan_and_timeline", "sia_reference", "approver_name", "approver_title", + "status", "date_initiated") +DATE_COLUMNS = ("date_initiated", "date_started", "date_finished", "verified_on", "docs_updated_on") +YES_NO = ("yes", "no") + + +class EvaluationError(ValueError): + pass + + +# --- the evaluation on every change ---------------------------------------------- + +def _clean(v): + return v.strip().strip("`*_").strip() + + +def normalize_type(raw): + return re.sub(r"[\s_]+", "-", _clean(raw).lower()) + + +def parse_evaluation(text): + """{type, rationale, record} from a PR body or commit message. + + Raises EvaluationError naming exactly what is missing or wrong. There is no + default: a change with no evaluation is not evaluated.""" + text = text or "" + types = TYPE_LINE.findall(text) + if not types: + raise EvaluationError("no 'SCN-Type:' line: every change needs an explicit significant-change evaluation") + if len(types) > 1: + raise EvaluationError(f"{len(types)} 'SCN-Type:' lines: give exactly one evaluation") + kind = normalize_type(types[0]) + if kind not in TYPES: + raise EvaluationError(f"SCN-Type '{_clean(types[0])}' is not one of: {' | '.join(TYPES)}") + rationales = RATIONALE_LINE.findall(text) + if not rationales: + raise EvaluationError("no 'SCN-Rationale:' line: say in one line why the change is this type") + if len(rationales) > 1: + raise EvaluationError(f"{len(rationales)} 'SCN-Rationale:' lines: give exactly one") + rationale = _clean(rationales[0]) + if PLACEHOLDER.match(rationale) or len(rationale) < MIN_RATIONALE: + raise EvaluationError(f"SCN-Rationale is empty or a placeholder (at least {MIN_RATIONALE} characters " + "explaining the categorization)") + records = [_clean(r) for r in RECORD_LINE.findall(text)] + if len(records) > 1: + raise EvaluationError(f"{len(records)} 'SCN-Record:' lines: name one record") + record = records[0] if records else None + if kind in NEEDS_RECORD: + if not record: + raise EvaluationError(f"SCN-Type {kind} needs an 'SCN-Record: SCN-YYYY-NNN' line naming its record " + "in docs/scn/scn-register.csv (the next free ID if the record is not written yet)") + if not SCN_ID_RE.match(record): + raise EvaluationError(f"SCN-Record '{record}' is not an SCN ID (SCN-YYYY-NNN)") + elif record: + raise EvaluationError(f"SCN-Type {kind} makes no notification (SCN-RTR-NNR), so it names no SCN-Record") + return {"type": kind, "rationale": rationale[:MAX_RATIONALE], "record": record} + + +def gate(text, index=None, today=None): + """(errors, notices, evaluation) for one change's evaluation text. + + `index` is the published notification index, needed only for a + transformative change: it may merge only once its initial plan has been + published 30 business days and its final plan 10 (SCN-TRF-NIP/NFP).""" + today = today or date.today() + try: + ev = parse_evaluation(text) + except EvaluationError as exc: + return [str(exc)], [], None + errors, notices = [], [] + if ev["type"] == "class-change": + errors.append("SCN-Type class-change blocks the merge: a change of certification class is a new " + "certification, not a significant change. Stop and plan a new assessment " + "(docs/policies/cm-policy.md).") + elif ev["type"] == "emergency": + notices.append(f"emergency change (SCN-CSO-EMG): the retroactive record {ev['record']} must be in the " + f"register and published within {EMERGENCY_BIZDAYS} business days " + "(docs/incident-response.md); the scheduled SCN deadline check enforces it") + elif ev["type"] == "transformative": + errors += transformative_lead_errors(ev["record"], index, today) + elif ev["type"] == "adaptive": + notices.append(f"adaptive change: the notice for {ev['record']} must be published within " + f"{timeframe('SCN-ADP-NTF')} business days of finishing (SCN-ADP-NTF)") + return errors, notices, ev + + +def transformative_lead_errors(record, index, today): + if index is None: + return ["cannot read the published notification index, so the transformative lead times cannot be " + "checked (fail closed)"] + scn = next((s for s in index.get("notifications", []) if s.get("scnId") == record), None) + if scn is None: + return [f"{record} has no published notification: a transformative change starts no sooner than " + f"{timeframe('SCN-TRF-NIP')} business days after its initial plan is published (SCN-TRF-NIP)"] + published = {n["stage"]: n.get("publishedOn") for n in scn.get("notices", [])} + errors = [] + for stage, rule in (("initial-plan", "SCN-TRF-NIP"), ("final-plan", "SCN-TRF-NFP")): + on = published.get(stage) + if not on: + errors.append(f"{record}: no {stage} notice published ({rule})") + continue + ready = _bizdays.add_business_days(date.fromisoformat(on), timeframe(rule)) + if today < ready: + errors.append(f"{record}: the {stage} notice was published {on}; the change may start on or after " + f"{ready.isoformat()} ({timeframe(rule)} business days, {rule})") + return errors + + +# --- FedRAMP timeframes ----------------------------------------------------------- + +def timeframe(rule_id): + """The rule's business-day timeframe, from the vendored rules (never typed in).""" + rules, _ = _rules.load_rules() + family, subset = rule_id.split("-")[0], rule_id.split("-")[1] + try: + r = rules["FRR"][family]["data"]["all"][subset][rule_id] + except KeyError: + raise SystemExit(f"::error::SCN: rule {rule_id} not in the vendored rules (fail-closed)") from None + if r.get("timeframe_type") != "bizdays" or not isinstance(r.get("timeframe_num"), int): + raise SystemExit(f"::error::SCN: rule {rule_id} has no business-day timeframe (fail-closed)") + return r["timeframe_num"] + + +# --- the register ------------------------------------------------------------------ + +def read_register(path=REGISTER): + with Path(path).open(newline="", encoding="utf-8") as fh: + reader = csv.DictReader(fh) + header = tuple(reader.fieldnames or ()) + rows = [{k: (v or "").strip() for k, v in r.items()} for r in reader] + return header, rows + + +def _date(v): + try: + return date.fromisoformat(v) if v else None + except ValueError: + return None + + +def validate_register(header, rows, root=REPO): + """Every error in the register; empty means it can be published.""" + errors = [] + if header != REGISTER_COLUMNS: + missing = [c for c in REGISTER_COLUMNS if c not in header] + extra = [c for c in header if c not in REGISTER_COLUMNS] + errors.append(f"register columns differ from the template (missing {missing}, unexpected {extra})") + return errors + seen = set() + for r in rows: + sid = r["scn_id"] or "<no id>" + where = f"{sid}:" + if not SCN_ID_RE.match(r["scn_id"]): + errors.append(f"{where} scn_id is not SCN-YYYY-NNN") + if sid in seen: + errors.append(f"{where} duplicate scn_id") + seen.add(sid) + for c in INF_REQUIRED: + if not r[c]: + errors.append(f"{where} {c} is empty (SCN-CSO-INF)") + if r["scn_type"] and r["scn_type"] not in RECORD_TYPES: + errors.append(f"{where} scn_type '{r['scn_type']}': only adaptive and transformative changes get a " + "notification record (SCN-RTR-NNR)") + for c in DATE_COLUMNS: + if r[c] and _date(r[c]) is None: + errors.append(f"{where} {c} '{r[c]}' is not an ISO date") + order = [(c, _date(r[c])) for c in ("date_initiated", "date_started", "date_finished", "verified_on")] + known = [(c, d) for c, d in order if d] + for (c1, d1), (c2, d2) in zip(known, known[1:], strict=False): + if d2 < d1: + errors.append(f"{where} {c2} {d2} is before {c1} {d1}") + if r["sia_reference"] and not (Path(root) / r["sia_reference"]).is_file(): + errors.append(f"{where} sia_reference {r['sia_reference']} does not exist") + if r["emergency"] not in YES_NO: + errors.append(f"{where} emergency must be yes or no") + if r["emergency"] == "yes" and not r["evaluation_prs"]: + errors.append(f"{where} an emergency record names the change(s) it documents in evaluation_prs") + if r["scn_type"] == "adaptive" and not r["new_risks_summary"]: + errors.append(f"{where} new_risks_summary is empty (SCN-ADP-NTF)") + if r["scn_type"] == "transformative": + errors += [f"{where} {m}" for m in _transformative_errors(r)] + return errors + + +def _transformative_errors(r): + errs = [] + if not r["date_started"]: + errs.append("date_started (the planned start) is required: the notice windows count back from it " + "(SCN-TRF-NIP/NFP)") + if r["plan_final"] not in YES_NO: + errs.append("plan_final must be yes or no (SCN-TRF-NFP)") + if r["tpr_human_validation"] not in YES_NO: + errs.append("tpr_human_validation must be yes or no: does the change need human validation? (SCN-TRF-TPR)") + if not r["tpr_assessor_or_reason"]: + errs.append("tpr_assessor_or_reason: name the third-party assessor engaged, or why none was (SCN-TRF-TPR)") + if not r["new_risks_summary"]: + errs.append("new_risks_summary is empty (SCN-TRF-NIP, SCN-TRF-NAV)") + if r["verified_on"] and not r["sar_reference"]: + errs.append("sar_reference: link the security assessment report, or say why there is none (SCN-TRF-NAV)") + if r["date_finished"] and not (r["docs_to_update"] or r["docs_update_not_required"]): + errs.append("docs_to_update (the service documentation to update) or docs_update_not_required " + "(how that was determined) is required once finished (SCN-TRF-UPD)") + if r["docs_updated_on"] and not r["docs_to_update"]: + errs.append("docs_updated_on without docs_to_update") + return errs + + +# --- notices and deadlines ---------------------------------------------------------- + +def notices_due(row): + """The notices a record owes now: [{stage, rule, deadline, kind}]. + + kind "by": publish on or before the deadline. kind "before-start": publish + at least the rule's business days before the change starts, i.e. on or + before the deadline. An emergency record's notices are retroactive: each is + due within EMERGENCY_BIZDAYS of the change finishing (or starting).""" + out = [] + t = row["scn_type"] + start, finish, verified = _date(row["date_started"]), _date(row["date_finished"]), _date(row["verified_on"]) + emergency = row["emergency"] == "yes" + retro_from = finish or start or _date(row["date_initiated"]) + + def add(stage, rule, deadline, kind): + if emergency: + deadline, kind = _bizdays.add_business_days(retro_from, EMERGENCY_BIZDAYS), "retroactive" + rule = f"{rule}; SCN-CSO-EMG" + out.append({"stage": stage, "rule": rule, "deadline": deadline, "kind": kind}) + + if t == "adaptive" and finish: + add("after-finish", "SCN-ADP-NTF", _bizdays.add_business_days(finish, timeframe("SCN-ADP-NTF")), "by") + if t == "transformative": + if start: + add("initial-plan", "SCN-TRF-NIP", _bizdays.add_business_days(start, -timeframe("SCN-TRF-NIP")), + "before-start") + if row["plan_final"] == "yes": + add("final-plan", "SCN-TRF-NFP", _bizdays.add_business_days(start, -timeframe("SCN-TRF-NFP")), + "before-start") + if finish: + add("after-finish", "SCN-TRF-NAF", _bizdays.add_business_days(finish, timeframe("SCN-TRF-NAF")), "by") + if verified: + add("after-verification", "SCN-TRF-NAV", + _bizdays.add_business_days(verified, timeframe("SCN-TRF-NAV")), "by") + return out + + +def docs_update_deadline(row): + finish = _date(row["date_finished"]) + if row["scn_type"] != "transformative" or not finish: + return None + return _bizdays.add_business_days(finish, timeframe("SCN-TRF-UPD")) + + +def merge_notices(row, previous, today): + """This build's notices for a record. A notice already published keeps the + date it was first published; a new one is published today.""" + prev = {n["stage"]: n for n in previous or []} + out = [] + for n in notices_due(row): + on = prev.get(n["stage"], {}).get("publishedOn") or today.isoformat() + out.append({"stage": n["stage"], "rule": n["rule"], "deadline": n["deadline"].isoformat(), + "publishedOn": on, "onTime": date.fromisoformat(on) <= n["deadline"]}) + # A stage published before is never dropped, even if the record no longer owes it. + for stage, n in prev.items(): + if stage not in {o["stage"] for o in out}: + out.append(n) + return out + + +# --- append-only records ---------------------------------------------------------- + +def append_only_errors(previous, current, key): + """Errors if `current` does not start with every entry of `previous`, + unchanged and in order (`key` names an entry in messages).""" + errors = [] + if len(current) < len(previous): + errors.append(f"{len(previous) - len(current)} published entr(ies) would be dropped") + for i, (p, c) in enumerate(zip(previous, current, strict=False)): + if p != c: + errors.append(f"published entry {i} ({p.get(key)}) would be rewritten") + return errors + + +def retention_errors(previous_index, current_index): + """SCN-CSO-HIS: every notification published before is still published, + with the notices it had and their publication dates.""" + if not previous_index: + return [] + cur = {s["scnId"]: s for s in current_index.get("notifications", [])} + errors = [] + for s in previous_index.get("notifications", []): + sid = s.get("scnId") + if sid not in cur: + errors.append(f"{sid} was published and would be dropped") + continue + now = {n["stage"]: n.get("publishedOn") for n in cur[sid].get("notices", [])} + for n in s.get("notices", []): + if now.get(n["stage"]) != n.get("publishedOn"): + errors.append(f"{sid} {n['stage']} notice published {n.get('publishedOn')} would be " + f"dropped or re-dated") + return errors + + +# --- the scheduled deadline check ------------------------------------------------- + +def overdue(rows, index, log_entries, today): + """Everything late and still outstanding. A notice published late is a + fact the index records (onTime false), not an open item.""" + out = [] + by_id = {r["scn_id"]: r for r in rows} + published = {s["scnId"]: {n["stage"] for n in s.get("notices", [])} + for s in (index or {}).get("notifications", [])} + for e in log_entries: + if e.get("scn_type") not in NEEDS_RECORD or not e.get("scn_record"): + continue + ref, merged = e["scn_record"], date.fromisoformat(e["merged_on"]) + if ref in by_id: + continue + if e["scn_type"] == "transformative": + due = merged + elif e["scn_type"] == "emergency": + due = _bizdays.add_business_days(merged, EMERGENCY_BIZDAYS) + else: + due = _bizdays.add_business_days(merged, timeframe("SCN-ADP-NTF")) + if today > due: + out.append(f"{ref}: named by the {e['scn_type']} change {e.get('commit', '')[:12]} merged {merged}, " + f"but not in the register (due {due.isoformat()})") + for r in rows: + for n in notices_due(r): + if n["stage"] not in published.get(r["scn_id"], set()) and today > n["deadline"]: + out.append(f"{r['scn_id']}: {n['stage']} notice ({n['rule']}) not published; due " + f"{n['deadline'].isoformat()}") + upd = docs_update_deadline(r) + if upd and not r["docs_updated_on"] and not r["docs_update_not_required"] and today > upd: + out.append(f"{r['scn_id']}: service documentation not updated; due {upd.isoformat()} (SCN-TRF-UPD)") + return out diff --git a/scripts/build-cpo.py b/scripts/build-cpo.py index 732986d3..fb5162ef 100644 --- a/scripts/build-cpo.py +++ b/scripts/build-cpo.py @@ -37,8 +37,28 @@ ("availability.json", "Availability feed (CDS-CSO-AVR)", True), ("policy-index.json", "Policy and procedure index (CDS-CSO-IRP)", True), ("iiw.csv", "FedRAMP Integrated Inventory Workbook (Appendix M)", True), + ("significant-change-notifications.json", + "Significant Change Notifications, FedRAMP SCN schema (SCN-CSO-HIS/HRM)", True), + ("significant-change-notifications.atom", "SCN notification feed, Atom (SCN-CSO-NOM)", True), + ("scn-evaluations.json", "Significant-change evaluation log, append-only (SCN-CSO-MAR)", True), ] BASE = "https://samaydlette.com/.well-known/" +# SCN-CSO-NOM / SCN-CSO-MAR / SCN-CSO-HRM: how notifications are given and how +# the records are obtained; scripts/build-scn.py publishes the same statement. +SCN_NOTIFICATION = { + "mechanisms": [ + {"mechanism": "Atom feed", "url": BASE + "significant-change-notifications.atom"}, + {"mechanism": "Signed JSON index", "url": BASE + "significant-change-notifications.json"}, + {"mechanism": "Human-readable view", "url": BASE + "significant-change-notifications.md"}, + ], + "method": "Notification is publication: each notice is an update to the Certification Data at the URLs " + "above, dated when first published. Nothing is sent by email or to FedRAMP directly.", + "evaluation_records": BASE + "scn-evaluations.json", + "access": "Public; no request needed. Everything is published to everyone (no federal data, no agency " + "customer).", + "emergency_procedure": "https://github.com/sam-aydlette/samaydlette.com/blob/main/docs/incident-response.md" + "#emergency-change-procedure-cr26-scn-cso-emg", +} def main(): @@ -100,6 +120,7 @@ def main(): "the Security Decision Record; the independent half is unmet by design.", "current_service": off.get("current_independent_assessment_service"), }, + "significant_change_notifications": SCN_NOTIFICATION, "package_contents": [ {"artifact": fn, "description": desc, "url": BASE + fn, "signed": signed} for fn, desc, signed in PACKAGE_CONTENTS @@ -135,6 +156,11 @@ def render_markdown(c): out.append("| {mod} | {val} | {role} |".format( mod=m.get("module", ""), val=m.get("validation", ""), role=m.get("role", ""))) out += ["", "## Independent assessment (IVV-CSO-ICP)", "", c["independent_assessment"]["status"], ""] + scn = c["significant_change_notifications"] + out += ["## Significant Change Notifications (SCN-CSO-NOM)", "", scn["method"], ""] + out += [f"- {m['mechanism']}: {m['url']}" for m in scn["mechanisms"]] + out += [f"- Evaluation records (SCN-CSO-MAR): {scn['evaluation_records']}", + f"- Access: {scn['access']}", f"- Emergency changes (SCN-CSO-EMG): {scn['emergency_procedure']}", ""] out += ["## Package contents", "", "| Artifact | Description | Signed |", "|---|---|---|"] for p in c["package_contents"]: out.append("| [`{a}`]({u}) | {d} | {s} |".format( diff --git a/scripts/build-scn.py b/scripts/build-scn.py new file mode 100644 index 00000000..a49b803f --- /dev/null +++ b/scripts/build-scn.py @@ -0,0 +1,410 @@ +#!/usr/bin/env python3 +# ============================================================================= +# SIGNIFICANT CHANGE NOTIFICATIONS + EVALUATION LOG (SCN-*) +# ============================================================================= +# Run by the deploy, after the build and before signing. Writes, into --out-dir: +# +# scn/<SCN-ID>.json one notification per register row, +# each validated against FedRAMP's +# SCN schema (write_validated) +# significant-change-notifications.json the index: every notification, +# its notices and their dates (HIS) +# significant-change-notifications.md the human-readable view (HRM) +# significant-change-notifications.atom the subscribable feed (NOM) +# scn-evaluations.json / .md the evaluation log (MAR, HRM) +# +# Both the index and the log only ever grow. The previous published copies are +# fetched by the deploy and passed in; a build that would drop or rewrite a +# published entry fails (SCN-CSO-HIS, SCN-CSO-MAR). A notice keeps the date it +# was first published, which is the date it was given: FedRAMP's rules name the +# notification method for every SCN notice as an update to the Certification +# Data, and this publication is that update. Nothing is sent to anyone. +# +# The evaluation log takes one entry per first-parent commit on main after the +# last one it holds: the SCN-Type, rationale and record from the merged pull +# request's description (or the commit message for a direct push), who merged +# it and when. With no previous log, it starts at the commit that introduced +# this builder, so a lost copy is rebuilt from git rather than restarted. +# +# build-scn.py --previous-index prev-index.json --previous-log prev-log.json +# ============================================================================= + +import argparse +import json +import os +import re +import subprocess +import sys +from datetime import date, datetime, timezone +from pathlib import Path +from xml.sax.saxutils import escape + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _fedramp_schema # noqa: E402 +import _redact # noqa: E402 +import _scn # noqa: E402 + +REPO = _scn.REPO +GENESIS_PATH = "scripts/build-scn.py" +MERGE_RE = re.compile(r"^Merge pull request #(\d+) from ") +RUN_ID_RE = re.compile(r"(actions/runs/|run )\d{6,}") + +MECHANISMS = [ + {"mechanism": "Atom feed", "url": _scn.BASE + _scn.FEED_NAME, + "description": "One entry per notice (adaptive after-finish; transformative initial plan, final plan, " + "after finish, after verification). Any feed reader can subscribe; no account needed."}, + {"mechanism": "Signed JSON index", "url": _scn.BASE + _scn.INDEX_NAME + ".json", + "description": "Every notification in FedRAMP's SCN schema with each notice's publication date and " + "deadline; signed with Sigstore (.bundle beside it)."}, + {"mechanism": "Human-readable view", "url": _scn.BASE + _scn.INDEX_NAME + ".md", + "description": "The same notifications as a Markdown document."}, +] +ACCESS = ("All notifications and the evaluation log are public at the URLs above, in JSON and human-readable " + "form; no request is needed. The register they are built from is docs/scn/scn-register.csv in the " + "public repository.") +SHARING = ("Everything is published to everyone: the system holds no federal data and no agency customer, so " + "there is nothing in a notification to withhold. A notification that ever needed to carry sensitive " + "detail would publish a summary and say how to request the rest.") +NOTIFICATION = ("Notification is publication. FedRAMP's rules name the method for each SCN notice as an update to " + "the FedRAMP Certification Data; publishing here is that update. Nothing is sent by email or to " + "FedRAMP directly. A notice's publishedOn is the first deploy that published it.") + + +def _today(): + return datetime.now(timezone.utc).date() + + +def _load(path): + if not path or not Path(path).is_file() or Path(path).stat().st_size == 0: + return None + return json.loads(Path(path).read_text()) + + +# --- the evaluation log -------------------------------------------------------------- + +def _git(*args, root=REPO): + return subprocess.run(["git", *args], cwd=root, check=True, capture_output=True, text=True).stdout.strip() + + +def gh_pull(number): + """The pull request's description and merger, via the GitHub API (gh, GH_TOKEN).""" + repo = os.environ.get("GITHUB_REPOSITORY", "sam-aydlette/samaydlette.com") + out = subprocess.run(["gh", "api", f"repos/{repo}/pulls/{number}"], check=True, capture_output=True, text=True) + pr = json.loads(out.stdout) + return {"body": pr.get("body") or "", "merged_by": (pr.get("merged_by") or {}).get("login"), + "author": (pr.get("user") or {}).get("login")} + + +def _scrub(text): + """Free text from a PR description, made safe to publish.""" + return LONG_NUMBER.sub("<number>", RUN_ID_RE.sub(r"\1<run>", _redact.redact_text(text))) + + +# A standalone number of 9 to 11 digits in published text is most likely a +# GitHub run ID; 12 digits is an AWS account ID, which the publication gate +# catches. Neither belongs in a notification. +LONG_NUMBER = re.compile(r"(?<![0-9A-Za-z])[0-9]{9,11}(?![0-9A-Za-z])") + + +def long_number_errors(name, text): + return [f"{name}: a {len(m)}-digit number (a run ID?) would be published" for m in LONG_NUMBER.findall(text)] + + +def evaluation_entry(commit, subject, body, merged_on, author, lookup): + m = MERGE_RE.match(subject) + if m: + pr = lookup(int(m.group(1))) + text, evaluator, number = pr["body"], pr.get("merged_by") or pr.get("author"), int(m.group(1)) + else: + text, evaluator, number = f"{subject}\n{body}", author, None + entry = {"commit": commit, "merged_on": merged_on, "pull_request": number, "evaluator": evaluator or "unknown"} + try: + ev = _scn.parse_evaluation(text) + entry.update(scn_type=ev["type"], rationale=_scrub(ev["rationale"]), scn_record=ev["record"], problem=None) + except _scn.EvaluationError as exc: + entry.update(scn_type=None, rationale=None, scn_record=None, problem=f"no valid evaluation: {exc}") + return entry + + +def collect(previous_entries, root=REPO, lookup=gh_pull, head="HEAD"): + """Entries for the first-parent commits after the last one logged.""" + if previous_entries: + last = previous_entries[-1]["commit"] + try: + _git("merge-base", "--is-ancestor", last, head, root=root) + except subprocess.CalledProcessError: + raise SystemExit(f"::error::SCN log: last logged commit {last[:12]} is not an ancestor of {head}; " + "history was rewritten (fail-closed)") from None + span = f"{last}..{head}" + shas = _git("rev-list", "--first-parent", "--reverse", span, root=root).split() + else: + first = _git("log", "--first-parent", "--reverse", "--format=%H", head, "--", GENESIS_PATH, root=root).split() + if not first: + raise SystemExit(f"::error::SCN log: no commit introduces {GENESIS_PATH} (fail-closed)") + parent = _git("rev-list", "--max-count=1", f"{first[0]}^1", root=root) if _has_parent(first[0], root) \ + else None + span = f"{parent}..{head}" if parent else head + shas = _git("rev-list", "--first-parent", "--reverse", span, root=root).split() + out = [] + for sha in shas: + subject, body, when, author = _git("show", "-s", "--format=%s%x00%b%x00%cI%x00%an", sha, root=root) \ + .split("\x00") + out.append(evaluation_entry(sha, subject, body, when[:10], author, lookup)) + return out + + +def _has_parent(sha, root): + try: + _git("rev-parse", "--verify", "--quiet", f"{sha}^1", root=root) + return True + except subprocess.CalledProcessError: + return False + + +def build_log(previous, new_entries, now, commit): + prev = (previous or {}).get("entries", []) + entries = prev + new_entries + errors = _scn.append_only_errors(prev, entries, "commit") + if errors: + raise SystemExit("::error::SCN evaluation log is append-only: " + "; ".join(errors)) + return { + "$comment": "SCN-CSO-MAR: the significant-change evaluation of every change merged to main, one entry per " + "first-parent commit. Append-only: each deploy adds the commits since the last entry, and " + "a deploy that would drop or rewrite an entry fails. Built by scripts/build-scn.py.", + "generated_at": now.isoformat(), + "commit": commit, + "genesis_commit": (previous or {}).get("genesis_commit") or (entries[0]["commit"] if entries else None), + "access": ACCESS, + "entries": entries, + "unrecorded": sum(1 for e in entries if e["problem"]), + } + + +def render_log_md(log): + out = ["# Significant-change evaluation log (SCN-CSO-MAR)", "", + f"_Generated {log['generated_at']} from commit `{log['commit']}`. The signed JSON beside this file is " + "the record; this is its rendering._", "", + f"{len(log['entries'])} evaluations; {log['unrecorded']} without a valid evaluation.", "", + "| Merged | Commit | PR | Type | Record | Evaluator | Rationale |", "|---|---|---|---|---|---|---|"] + for e in reversed(log["entries"]): + rationale = e["rationale"] or f"_{e['problem']}_" + out.append("| {d} | `{c}` | {p} | {t} | {r} | {who} | {why} |".format( + d=e["merged_on"], c=e["commit"][:12], p=f"#{e['pull_request']}" if e["pull_request"] else "direct", + t=e["scn_type"] or "-", r=e["scn_record"] or "", who=e["evaluator"], why=rationale.replace("|", "\\|"))) + return "\n".join(out) + + +# --- notifications ------------------------------------------------------------------- + +def _fedramp_id(row): + v = row["fedramp_id"] + return None if not v or v.startswith("<") else v + + +def scn_document(row, previous_notices, today): + start = row["date_started"] or row["date_initiated"] + plan = {"summary": row["plan_and_timeline"], "plannedStart": start} + if row["date_finished"]: + plan["plannedCompletion"] = row["date_finished"] + doc = { + "$schema": _fedramp_schema.stamp("scn"), + "certificationPackageOverviewUri": _fedramp_schema.CPO_URI, + "scnId": row["scn_id"], + "serviceOfferingFedrampId": _fedramp_id(row), + "serviceOfferingFedrampIdNote": None if _fedramp_id(row) else + "No FedRAMP ID: the offering is not FedRAMP certified (a self-attested demonstration).", + "assessorName": row["assessor_name"], + "relatedVulnerability": row["related_vulnerability"], + "changeType": row["scn_type"].capitalize(), + "changeTypeExplanation": row["categorization_rationale"], + "changeDescription": row["short_description"], + "reason": row["reason_for_change"], + "customerImpact": row["customer_impact"], + "planAndTimeline": plan, + "impactAnalysis": _scn.SOURCE_URL + row["sia_reference"], + "approver": {"name": row["approver_name"], "title": row["approver_title"]}, + "newRisksSummary": row["new_risks_summary"], + "emergency": row["emergency"] == "yes", + "notices": _scn.merge_notices(row, previous_notices, today), + # SCN-CSO-ARI: what else a reviewer needs to judge the change. + "additionalInformation": { + "status": row["status"], + "dateInitiated": row["date_initiated"], + "dateFinished": row["date_finished"] or None, + "verifiedOn": row["verified_on"] or None, + "changes": [p.strip() for p in row["evaluation_prs"].split(";") if p.strip()], + "record": _scn.SOURCE_URL + row["sia_reference"], + }, + } + if row["scn_type"] == "transformative": + doc["transformative"] = { + "planFinal": row["plan_final"] == "yes", + "thirdPartyReview": {"humanValidationNeeded": row["tpr_human_validation"] == "yes", + "assessorOrReasonNotEngaged": row["tpr_assessor_or_reason"]}, + "securityAssessmentReport": row["sar_reference"] or None, + "documentationUpdate": { + "documents": [d.strip() for d in row["docs_to_update"].split(";") if d.strip()], + "updatedOn": row["docs_updated_on"] or None, + "notRequiredBecause": row["docs_update_not_required"] or None, + "deadline": (_scn.docs_update_deadline(row) or date.min).isoformat() + if row["date_finished"] else None, + }, + } + return doc + + +def build_index(rows, previous_index, now, commit, out_dir): + prev = {s["scnId"]: s.get("notices", []) for s in (previous_index or {}).get("notifications", [])} + scn_dir = Path(out_dir) / "scn" + scn_dir.mkdir(parents=True, exist_ok=True) + docs = [] + for row in rows: + doc = scn_document(row, prev.get(row["scn_id"]), now.date()) + path = scn_dir / f"{row['scn_id']}.json" + _fedramp_schema.write_validated(doc, "scn", path) + docs.append(json.loads(path.read_text())) + late = [f"{d['scnId']} {n['stage']}" for d in docs for n in d["notices"] if not n["onTime"]] + index = { + "$comment": "SCN-CSO-HIS / SCN-CSO-HRM / SCN-CSO-NOM: every Significant Change Notification, each in " + "FedRAMP's SCN schema, with each notice's deadline and the date it was published. Never " + "pruned: a deploy that would drop a notification or re-date a notice fails. Built by " + "scripts/build-scn.py from docs/scn/scn-register.csv.", + "generated_at": now.isoformat(), + "commit": commit, + "certificationPackageOverviewUri": _fedramp_schema.CPO_URI, + "notification": NOTIFICATION, + "notificationMechanisms": MECHANISMS, + "access": ACCESS, + "sharing": SHARING, + "retention": "All notifications are kept, which exceeds the 12 months SCN-CSO-HIS requires.", + "evaluationLog": _scn.BASE + _scn.LOG_NAME + ".json", + "lateNotices": late, + "notifications": docs, + } + errors = _scn.retention_errors(previous_index, index) + if errors: + raise SystemExit("::error::SCN notifications are retained (SCN-CSO-HIS): " + "; ".join(errors)) + return index + + +def render_index_md(index): + out = ["# Significant Change Notifications", "", + f"_Generated {index['generated_at']} from commit `{index['commit']}`. The signed JSON beside this " + "file is the record; this is its rendering._", "", + index["notification"], "", + "## How to receive them (SCN-CSO-NOM)", ""] + out += [f"- **{m['mechanism']}:** {m['url']} — {m['description']}" for m in index["notificationMechanisms"]] + out += ["", f"**Access.** {index['access']}", "", f"**Sharing.** {index['sharing']}", "", + f"**Retention.** {index['retention']}", "", + f"**Evaluation log (SCN-CSO-MAR):** {index['evaluationLog']}", ""] + if index["lateNotices"]: + out += ["**Notices published after their deadline:** " + ", ".join(index["lateNotices"]), ""] + for d in reversed(index["notifications"]): + out += [f"## {d['scnId']} — {d['changeType']}{' (emergency)' if d['emergency'] else ''}", "", + d["changeDescription"], "", + f"- **Service Offering FedRAMP ID:** {d['serviceOfferingFedrampId'] or d['serviceOfferingFedrampIdNote']}", + f"- **Assessor:** {d.get('assessorName') or '-'}", + f"- **Related vulnerability:** {d.get('relatedVulnerability') or '-'}", + f"- **Why this type:** {d['changeTypeExplanation']}", + f"- **Reason:** {d['reason']}", + f"- **Customer impact:** {d['customerImpact']}", + f"- **Plan and timeline:** {d['planAndTimeline']['summary']}", + f"- **Impact analysis:** {d['impactAnalysis']}", + f"- **New risks:** {d['newRisksSummary'] or '-'}", + f"- **Approver:** {d['approver']['name']}, {d['approver']['title']}", + f"- **Status:** {d['additionalInformation']['status']}"] + if "transformative" in d: + t = d["transformative"] + tpr = t["thirdPartyReview"] + out += [f"- **Human validation needed:** {'yes' if tpr['humanValidationNeeded'] else 'no'}; " + f"{tpr['assessorOrReasonNotEngaged']}", + f"- **Security assessment report:** {t['securityAssessmentReport'] or '-'}", + f"- **Documentation update:** {', '.join(t['documentationUpdate']['documents']) or '-'}; " + f"updated {t['documentationUpdate']['updatedOn'] or 'not yet'}"] + out += ["", "| Notice | Rule | Deadline | Published | On time |", "|---|---|---|---|---|"] + out += [f"| {n['stage']} | {n['rule']} | {n['deadline']} | {n['publishedOn']} | " + f"{'yes' if n['onTime'] else 'no'} |" for n in d["notices"]] + out.append("") + return "\n".join(out) + + +def render_feed(index): + """Atom (RFC 4287): one entry per notice, dated when it was published.""" + entries = [] + for d in index["notifications"]: + for n in d["notices"]: + entries.append((n["publishedOn"], d, n)) + entries.sort(key=lambda e: (e[0], e[1]["scnId"], e[2]["stage"]), reverse=True) + updated = (entries[0][0] if entries else index["generated_at"][:10]) + "T00:00:00Z" + out = ['<?xml version="1.0" encoding="utf-8"?>', + '<feed xmlns="http://www.w3.org/2005/Atom">', + " <title>samaydlette.com Significant Change Notifications", + " tag:samaydlette.com,2026:significant-change-notifications", + f" {updated}", + f' ', + f' ', + " samaydlette.com"] + for on, d, n in entries: + title = f"{d['scnId']} ({d['changeType']}) {n['stage']} notice: {d['changeDescription'][:120]}" + summary = (f"{d['changeDescription']} Rule {n['rule']}; deadline {n['deadline']}; published {on}" + f"{'' if n['onTime'] else ' (after the deadline)'}. Customer impact: {d['customerImpact']}") + out += [" ", + f" tag:samaydlette.com,2026:scn/{d['scnId']}/{n['stage']}", + f" {escape(title)}", + f" {on}T00:00:00Z", + f' ', + f" {escape(summary)}", + " "] + out.append("") + return "\n".join(out) + "\n" + + +def main(argv=None): + ap = argparse.ArgumentParser(description="Build the SCN notifications and evaluation log.") + ap.add_argument("--register", default=str(_scn.REGISTER)) + ap.add_argument("--previous-index", help="the published index (absent on the first publish)") + ap.add_argument("--previous-log", help="the published evaluation log (absent on the first publish)") + ap.add_argument("--out-dir", default=".") + ap.add_argument("--repo-root", default=str(REPO)) + ap.add_argument("--commit", default=os.environ.get("GITHUB_SHA", "")) + ap.add_argument("--new-evaluations", help="JSON list of entries to append instead of reading git (tests)") + a = ap.parse_args(argv) + + now = datetime.now(timezone.utc).replace(microsecond=0) + header, rows = _scn.read_register(a.register) + errors = _scn.validate_register(header, rows, a.repo_root) + if errors: + for e in errors: + print(f"::error::scn-register: {e}", file=sys.stderr) + return 1 + out = Path(a.out_dir) + prev_index, prev_log = _load(a.previous_index), _load(a.previous_log) + + index = build_index(rows, prev_index, now, a.commit, out) + if a.new_evaluations: + new = json.loads(Path(a.new_evaluations).read_text()) + else: + new = collect((prev_log or {}).get("entries", []), root=a.repo_root) + log = build_log(prev_log, new, now, a.commit) + + outputs = { + f"{_scn.INDEX_NAME}.json": json.dumps(index, indent=2) + "\n", + f"{_scn.INDEX_NAME}.md": render_index_md(index) + "\n", + _scn.FEED_NAME: render_feed(index), + f"{_scn.LOG_NAME}.json": json.dumps(log, indent=2) + "\n", + f"{_scn.LOG_NAME}.md": render_log_md(log) + "\n", + } + errors = [e for name, text in outputs.items() for e in long_number_errors(name, text)] + if errors: + for e in errors: + print(f"::error::{e}", file=sys.stderr) + return 1 + for name, text in outputs.items(): + (out / name).write_text(text) + print(f"scn: {len(index['notifications'])} notifications ({len(index['lateNotices'])} notice(s) published " + f"late); evaluation log {len(log['entries'])} entries (+{len(new)}, {log['unrecorded']} unrecorded)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check-scn-deadlines.py b/scripts/check-scn-deadlines.py new file mode 100644 index 00000000..4e5f8e5c --- /dev/null +++ b/scripts/check-scn-deadlines.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +"""Scheduled SCN deadline check (SCN-ADP-NTF, SCN-TRF-NAF/NAV/UPD, SCN-CSO-EMG). + +Reads the published evaluation log and notification index and the register in +this checkout, and fails (exit 1) on anything late and still outstanding: + +- an adaptive, transformative or emergency change whose named record is not in + the register by its deadline (adaptive: 10 business days after merge, the + earliest it can have finished; emergency: 5; transformative: at merge); +- a notice a register record owes that is not yet published after its + deadline (a record merged but never deployed is not a notification); +- a transformative change whose service documentation is not updated within + 30 business days of finishing. + +A notice published late is not an open item: the index records it (onTime +false) for good. Exit 0 nothing overdue, 1 overdue, 2 cannot read an input. + + check-scn-deadlines.py # the published copies + check-scn-deadlines.py --index-file i.json --log-file l.json --today 2026-11-05 +""" + +import argparse +import json +import sys +import urllib.error +import urllib.request +from datetime import date, datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _scn # noqa: E402 + + +def _read(path, url): + if path: + return json.loads(Path(path).read_text()) + try: + with urllib.request.urlopen(url, timeout=30) as r: # noqa: S310 (fixed https URL) + return json.loads(r.read()) + except urllib.error.HTTPError as exc: + if exc.code == 404: + return {} + raise + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + ap.add_argument("--register", default=str(_scn.REGISTER)) + ap.add_argument("--index-file") + ap.add_argument("--log-file") + ap.add_argument("--today", help="ISO date (tests)") + a = ap.parse_args(argv) + today = date.fromisoformat(a.today) if a.today else datetime.now(timezone.utc).date() + try: + index = _read(a.index_file, _scn.BASE + _scn.INDEX_NAME + ".json") + log = _read(a.log_file, _scn.BASE + _scn.LOG_NAME + ".json") + header, rows = _scn.read_register(a.register) + except (OSError, ValueError, urllib.error.URLError) as exc: + print(f"::error::SCN deadline check cannot read its inputs: {exc}") + return 2 + errors = _scn.validate_register(header, rows) + if errors: + for e in errors: + print(f"::error::scn-register: {e}") + return 2 + late = _scn.overdue(rows, index, log.get("entries", []), today) + for item in late: + print(f"::error::SCN overdue: {item}") + if late: + return 1 + print(f"SCN deadlines: nothing overdue on {today} ({len(rows)} records, " + f"{len(log.get('entries', []))} evaluations)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/scn-evaluate.py b/scripts/scn-evaluate.py new file mode 100644 index 00000000..808c5cae --- /dev/null +++ b/scripts/scn-evaluate.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""The SCN gate (SCN-CSO-EVA): every change carries an explicit evaluation. + +Run by .github/workflows/scn-tag.yml over a pull request's description (or a +direct push's commit message). Passes only when the text carries: + + SCN-Type: not-significant | routine-recurring | adaptive | transformative | emergency | class-change + SCN-Rationale: one line on why the change is that type + SCN-Record: SCN-YYYY-NNN (adaptive, transformative and emergency only) + +There is no default: a missing or placeholder evaluation fails. class-change +always fails: a change of certification class is a new certification. A +transformative change fails until its initial plan has been published for 30 +business days and its final plan for 10 (SCN-TRF-NIP/NFP), read from the +published notification index. Exit 0 pass, 1 fail. + + scn-evaluate.py --text-env PR_BODY --source "PR description" + scn-evaluate.py --text-file body.md --index-file index.json --today 2026-11-05 +""" + +import argparse +import json +import os +import sys +import urllib.error +import urllib.request +from datetime import date +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _scn # noqa: E402 + +INDEX_URL = _scn.BASE + _scn.INDEX_NAME + ".json" + + +def fetch_index(url): + try: + with urllib.request.urlopen(url, timeout=30) as r: # noqa: S310 (fixed https URL) + return json.loads(r.read()) + except urllib.error.HTTPError as exc: + if exc.code == 404: + return {"notifications": []} + return None + except (urllib.error.URLError, TimeoutError, json.JSONDecodeError): + return None + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + src = ap.add_mutually_exclusive_group(required=True) + src.add_argument("--text-env", help="environment variable holding the text") + src.add_argument("--text-file", help="file holding the text") + ap.add_argument("--source", default="change description", help="what the text is, for messages") + ap.add_argument("--index-file", help="the notification index (default: fetch the published one)") + ap.add_argument("--index-url", default=INDEX_URL) + ap.add_argument("--today", help="ISO date (tests)") + a = ap.parse_args(argv) + + text = os.environ.get(a.text_env, "") if a.text_env else Path(a.text_file).read_text() + today = date.fromisoformat(a.today) if a.today else date.today() + needs_index = _scn.TYPE_LINE.search(text or "") and \ + _scn.normalize_type(_scn.TYPE_LINE.search(text).group(1)) == "transformative" + index = None + if needs_index: + index = json.loads(Path(a.index_file).read_text()) if a.index_file else fetch_index(a.index_url) + + errors, notices, ev = _scn.gate(text, index, today) + for n in notices: + print(f"::notice::{n}") + if errors: + for e in errors: + print(f"::error::SCN evaluation ({a.source}): {e}") + print("See docs/policies/cm-policy.md and docs/scn/evaluation-examples.md for the format and examples.") + return 1 + print(f"SCN-Type: {ev['type']} (from {a.source}); rationale: {ev['rationale']}" + + (f"; record {ev['record']}" if ev["record"] else "")) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/scn/bad/adaptive-no-record.md b/tests/fixtures/scn/bad/adaptive-no-record.md new file mode 100644 index 00000000..0d71319a --- /dev/null +++ b/tests/fixtures/scn/bad/adaptive-no-record.md @@ -0,0 +1,2 @@ +SCN-Type: adaptive +SCN-Rationale: adds a new internal component (a CloudWatch alarm) with no new ingress or egress. diff --git a/tests/fixtures/scn/bad/class-change.md b/tests/fixtures/scn/bad/class-change.md new file mode 100644 index 00000000..894d2a21 --- /dev/null +++ b/tests/fixtures/scn/bad/class-change.md @@ -0,0 +1,2 @@ +SCN-Type: class-change +SCN-Rationale: the offering would start holding federal customer data, which changes its certification class. diff --git a/tests/fixtures/scn/bad/index-previous-with-dropped.json b/tests/fixtures/scn/bad/index-previous-with-dropped.json new file mode 100644 index 00000000..813ae5c2 --- /dev/null +++ b/tests/fixtures/scn/bad/index-previous-with-dropped.json @@ -0,0 +1,17 @@ +{ + "$comment": "Known-bad previous index: holds SCN-2025-001, which the current register does not, so a build over it would drop a published notification (SCN-CSO-HIS).", + "notifications": [ + { + "scnId": "SCN-2025-001", + "notices": [ + { + "stage": "after-finish", + "rule": "SCN-ADP-NTF", + "deadline": "2025-12-01", + "publishedOn": "2025-11-20", + "onTime": true + } + ] + } + ] +} \ No newline at end of file diff --git a/tests/fixtures/scn/bad/log-rewritten.json b/tests/fixtures/scn/bad/log-rewritten.json new file mode 100644 index 00000000..f6de6894 --- /dev/null +++ b/tests/fixtures/scn/bad/log-rewritten.json @@ -0,0 +1,36 @@ +{ + "genesis_commit": "1111111111111111111111111111111111111111", + "entries": [ + { + "commit": "1111111111111111111111111111111111111111", + "merged_on": "2026-11-06", + "pull_request": 501, + "evaluator": "sam-aydlette", + "scn_type": "not-significant", + "rationale": "compliance-process change; no component, boundary or access change.", + "scn_record": null, + "problem": null + }, + { + "commit": "2222222222222222222222222222222222222222", + "merged_on": "2026-11-09", + "pull_request": 502, + "evaluator": "sam-aydlette", + "scn_type": "routine-recurring", + "rationale": "adds a new internal alarm with no new ingress or egress.", + "scn_record": null, + "problem": null + }, + { + "commit": "3333333333333333333333333333333333333333", + "merged_on": "2026-11-10", + "pull_request": 503, + "evaluator": "sam-aydlette", + "scn_type": "not-significant", + "rationale": "content-only change to a public page.", + "scn_record": null, + "problem": null + } + ], + "$comment": "Known-bad: rewrites entry 1 of log-previous.json (adaptive -> routine-recurring). The append-only check must fail." +} \ No newline at end of file diff --git a/tests/fixtures/scn/bad/log-truncated.json b/tests/fixtures/scn/bad/log-truncated.json new file mode 100644 index 00000000..2e053028 --- /dev/null +++ b/tests/fixtures/scn/bad/log-truncated.json @@ -0,0 +1,16 @@ +{ + "genesis_commit": "1111111111111111111111111111111111111111", + "entries": [ + { + "commit": "1111111111111111111111111111111111111111", + "merged_on": "2026-11-06", + "pull_request": 501, + "evaluator": "sam-aydlette", + "scn_type": "not-significant", + "rationale": "compliance-process change; no component, boundary or access change.", + "scn_record": null, + "problem": null + } + ], + "$comment": "Known-bad: drops entry 1 of log-previous.json. The append-only check must fail." +} \ No newline at end of file diff --git a/tests/fixtures/scn/bad/missing-rationale.md b/tests/fixtures/scn/bad/missing-rationale.md new file mode 100644 index 00000000..4ebdb1fa --- /dev/null +++ b/tests/fixtures/scn/bad/missing-rationale.md @@ -0,0 +1,4 @@ +## Changed +Bumps a dependency. + +SCN-Type: routine-recurring diff --git a/tests/fixtures/scn/bad/missing-type.md b/tests/fixtures/scn/bad/missing-type.md new file mode 100644 index 00000000..c996bb61 --- /dev/null +++ b/tests/fixtures/scn/bad/missing-type.md @@ -0,0 +1,4 @@ +## Changed +Bumps a dependency. + +SCN-Rationale: dependency version bump with no behaviour change. diff --git a/tests/fixtures/scn/bad/placeholder-rationale.md b/tests/fixtures/scn/bad/placeholder-rationale.md new file mode 100644 index 00000000..9fa83cc9 --- /dev/null +++ b/tests/fixtures/scn/bad/placeholder-rationale.md @@ -0,0 +1,2 @@ +SCN-Type: routine-recurring +SCN-Rationale: diff --git a/tests/fixtures/scn/bad/register-adaptive-no-risks.csv b/tests/fixtures/scn/bad/register-adaptive-no-risks.csv new file mode 100644 index 00000000..c7150d7d --- /dev/null +++ b/tests/fixtures/scn/bad/register-adaptive-no-risks.csv @@ -0,0 +1,2 @@ +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2026-103,,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),adaptive,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,,Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,,2026-06-06,2026-06-08,no,#82,,,,,,, diff --git a/tests/fixtures/scn/bad/register-dates-out-of-order.csv b/tests/fixtures/scn/bad/register-dates-out-of-order.csv new file mode 100644 index 00000000..07948b55 --- /dev/null +++ b/tests/fixtures/scn/bad/register-dates-out-of-order.csv @@ -0,0 +1,2 @@ +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2026-104,,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),adaptive,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,"POAM-019..024 (all risk-accepted, Low residual) plus the new-ecosystem SCA blind-spot, remediated by adding Syft/Grype SCA of the built Lambda+SPA artifact to CI feeding the VDR aggregator (RA-5/VDR-CSO-DET).",Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,,2026-06-01,2026-06-08,no,#82,,,,,,, diff --git a/tests/fixtures/scn/bad/register-routine.csv b/tests/fixtures/scn/bad/register-routine.csv new file mode 100644 index 00000000..ec1175ff --- /dev/null +++ b/tests/fixtures/scn/bad/register-routine.csv @@ -0,0 +1,2 @@ +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2026-101,,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),routine-recurring,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,"POAM-019..024 (all risk-accepted, Low residual) plus the new-ecosystem SCA blind-spot, remediated by adding Syft/Grype SCA of the built Lambda+SPA artifact to CI feeding the VDR aggregator (RA-5/VDR-CSO-DET).",Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,,2026-06-06,2026-06-08,no,#82,,,,,,, diff --git a/tests/fixtures/scn/bad/register-transformative-incomplete.csv b/tests/fixtures/scn/bad/register-transformative-incomplete.csv new file mode 100644 index 00000000..41a48d43 --- /dev/null +++ b/tests/fixtures/scn/bad/register-transformative-incomplete.csv @@ -0,0 +1,2 @@ +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2026-102,,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),transformative,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,"POAM-019..024 (all risk-accepted, Low residual) plus the new-ecosystem SCA blind-spot, remediated by adding Syft/Grype SCA of the built Lambda+SPA artifact to CI feeding the VDR aggregator (RA-5/VDR-CSO-DET).",Sam Aydlette,System Owner / Authorizing Operator,Implemented — live in production (first prod deploy 2026-06-03 via PR #82); post-implementation verification COMPLETE 2026-06-08 at prod commit 354da59 (pass: KEV 0 / blocking 0; SSP data-flow + interconnection rendered; deployed Python/JS deps CVE-free; CM-8 inventory complete),2026-06-03,,,,no,#82,,,,,,, diff --git a/tests/fixtures/scn/bad/routine-with-record.md b/tests/fixtures/scn/bad/routine-with-record.md new file mode 100644 index 00000000..273ae797 --- /dev/null +++ b/tests/fixtures/scn/bad/routine-with-record.md @@ -0,0 +1,3 @@ +SCN-Type: routine-recurring +SCN-Rationale: weekly dependency bump with no breaking change. +SCN-Record: SCN-2026-007 diff --git a/tests/fixtures/scn/bad/transformative-too-soon.md b/tests/fixtures/scn/bad/transformative-too-soon.md new file mode 100644 index 00000000..5d436194 --- /dev/null +++ b/tests/fixtures/scn/bad/transformative-too-soon.md @@ -0,0 +1,3 @@ +SCN-Type: transformative +SCN-Rationale: the offering starts accepting agency user accounts, a new service used differently by customers. +SCN-Record: SCN-2099-001 diff --git a/tests/fixtures/scn/bad/two-types.md b/tests/fixtures/scn/bad/two-types.md new file mode 100644 index 00000000..9f92a1ed --- /dev/null +++ b/tests/fixtures/scn/bad/two-types.md @@ -0,0 +1,3 @@ +SCN-Type: routine-recurring +SCN-Type: adaptive +SCN-Rationale: weekly dependency bump with no breaking change. diff --git a/tests/fixtures/scn/bad/unknown-type.md b/tests/fixtures/scn/bad/unknown-type.md new file mode 100644 index 00000000..474927c4 --- /dev/null +++ b/tests/fixtures/scn/bad/unknown-type.md @@ -0,0 +1,2 @@ +SCN-Type: minor +SCN-Rationale: a small change to the website content only. diff --git a/tests/fixtures/scn/good/adaptive.md b/tests/fixtures/scn/good/adaptive.md new file mode 100644 index 00000000..fb9b18de --- /dev/null +++ b/tests/fixtures/scn/good/adaptive.md @@ -0,0 +1,3 @@ +SCN-Type: adaptive +SCN-Rationale: adds a new internal component (a CloudWatch alarm) with no new ingress or egress. +SCN-Record: SCN-2026-007 diff --git a/tests/fixtures/scn/good/emergency.md b/tests/fixtures/scn/good/emergency.md new file mode 100644 index 00000000..8485df5e --- /dev/null +++ b/tests/fixtures/scn/good/emergency.md @@ -0,0 +1,3 @@ +SCN-Type: emergency +SCN-Rationale: rotates a leaked credential immediately; the retroactive record follows within 5 business days. +SCN-Record: SCN-2026-008 diff --git a/tests/fixtures/scn/good/not-significant.md b/tests/fixtures/scn/good/not-significant.md new file mode 100644 index 00000000..656c1068 --- /dev/null +++ b/tests/fixtures/scn/good/not-significant.md @@ -0,0 +1,5 @@ +## Changed +Fixes a typo on the about page. + +**SCN-Type:** not-significant +**SCN-Rationale:** content-only edit to a public page; no component, boundary, data flow or access change. diff --git a/tests/fixtures/scn/good/register-transformative.csv b/tests/fixtures/scn/good/register-transformative.csv new file mode 100644 index 00000000..51fb364a --- /dev/null +++ b/tests/fixtures/scn/good/register-transformative.csv @@ -0,0 +1,2 @@ +scn_id,fedramp_id,assessor_name,related_vulnerability,scn_type,categorization_rationale,short_description,reason_for_change,customer_impact,plan_and_timeline,sia_reference,new_risks_summary,approver_name,approver_title,status,date_initiated,date_started,date_finished,verified_on,emergency,evaluation_prs,plan_final,tpr_human_validation,tpr_assessor_or_reason,sar_reference,docs_to_update,docs_updated_on,docs_update_not_required +SCN-2099-003,,N/A (sole-operator self-attestation; no 3PAO engaged),None (proactive feature addition),transformative,"Net-new service component with new public ingress and new external egress; no FedRAMP Certification class change and no federal customer data introduced, so not transformative and not a class change; not regular/routine maintenance, so not routine-recurring. Resolves to Adaptive per SCN-CSO-EVA. Sits at the upper edge of Adaptive due to the new non-FedRAMP-authorized external interconnection (Anthropic); the absence of federal customer data is what keeps it out of Transformative.","Adds the gated ""Silk Reeling Mirror"" app: a public, HTTP-Basic-Auth-gated API Gateway HTTP API -> Python 3.13 ZIP Lambda serving a browser SPA; the Lambda calls the Anthropic API to generate movement-feedback text.",New self-service capability addition to the site.,New customer/operator-responsibility control: operator-set HTTP Basic Auth credential (POAM-021). SAML/IdP federation is the recommended upgrade. No change to existing customers' configuration responsibilities.,"Gated deploy (create_silk_reeling=true) -> OPA + Checkov + tfsec gate -> Syft/Grype SCA over the built artifact -> VDR report regenerated -> post-implementation secure-configuration verification (Adaptive requirement) -> KSI signal + OSCAL SSP re-emitted. Controls/KSIs to re-verify: RA-5/VDR-*, SA-9/CA-3, SC-7, AC-3/IA-2, AU-2/AU-3, SC-12/SC-28.",docs/scn/SCN-2026-001-silk-reeling.md,Fictitious example.,Sam Aydlette,System Owner / Authorizing Operator,Fictitious example,2026-09-01,2026-11-02,2026-11-13,2026-11-20,no,#9999,yes,yes,No third-party assessor engaged: none is under contract; the operator validated the scope.,N/A: no assessor engaged; provider verification in docs/scn/SCN-2099-003.md,docs/secure-configuration-guide.md,, diff --git a/tests/fixtures/scn/good/routine-recurring-legacy-spelling.md b/tests/fixtures/scn/good/routine-recurring-legacy-spelling.md new file mode 100644 index 00000000..c1992bd0 --- /dev/null +++ b/tests/fixtures/scn/good/routine-recurring-legacy-spelling.md @@ -0,0 +1,2 @@ +SCN-Type: Routine Recurring +SCN-Rationale: weekly Dependabot patch bump of a library already in the inventory, no breaking change. diff --git a/tests/fixtures/scn/good/transformative-ready.md b/tests/fixtures/scn/good/transformative-ready.md new file mode 100644 index 00000000..ec1ce069 --- /dev/null +++ b/tests/fixtures/scn/good/transformative-ready.md @@ -0,0 +1,3 @@ +SCN-Type: transformative +SCN-Rationale: the offering starts accepting agency user accounts, a new service used differently by customers. +SCN-Record: SCN-2099-002 diff --git a/tests/fixtures/scn/index.json b/tests/fixtures/scn/index.json new file mode 100644 index 00000000..b286cf31 --- /dev/null +++ b/tests/fixtures/scn/index.json @@ -0,0 +1,10 @@ +{ + "notifications": [ + {"scnId": "SCN-2099-001", "notices": [ + {"stage": "initial-plan", "rule": "SCN-TRF-NIP", "deadline": "2099-01-01", "publishedOn": "2026-10-20", "onTime": true}, + {"stage": "final-plan", "rule": "SCN-TRF-NFP", "deadline": "2099-01-01", "publishedOn": "2026-11-02", "onTime": true}]}, + {"scnId": "SCN-2099-002", "notices": [ + {"stage": "initial-plan", "rule": "SCN-TRF-NIP", "deadline": "2099-01-01", "publishedOn": "2026-09-01", "onTime": true}, + {"stage": "final-plan", "rule": "SCN-TRF-NFP", "deadline": "2099-01-01", "publishedOn": "2026-10-15", "onTime": true}]} + ] +} diff --git a/tests/fixtures/scn/log-previous.json b/tests/fixtures/scn/log-previous.json new file mode 100644 index 00000000..63ea19de --- /dev/null +++ b/tests/fixtures/scn/log-previous.json @@ -0,0 +1,11 @@ +{ + "genesis_commit": "1111111111111111111111111111111111111111", + "entries": [ + {"commit": "1111111111111111111111111111111111111111", "merged_on": "2026-11-06", "pull_request": 501, + "evaluator": "sam-aydlette", "scn_type": "not-significant", + "rationale": "compliance-process change; no component, boundary or access change.", "scn_record": null, "problem": null}, + {"commit": "2222222222222222222222222222222222222222", "merged_on": "2026-11-09", "pull_request": 502, + "evaluator": "sam-aydlette", "scn_type": "adaptive", + "rationale": "adds a new internal alarm with no new ingress or egress.", "scn_record": "SCN-2026-007", "problem": null} + ] +} diff --git a/tests/test_scn.py b/tests/test_scn.py new file mode 100644 index 00000000..de58c2de --- /dev/null +++ b/tests/test_scn.py @@ -0,0 +1,446 @@ +"""Significant Change Notifications (SCN-*): the evaluation gate, the register, +the notice deadlines in business days, the append-only evaluation log, the +never-pruned notification index and feed, and the scheduled deadline check. + +Every gate invariant has a committed known-bad fixture under +tests/fixtures/scn/bad/ that fails for its own reason.""" + +import importlib.util +import json +import re +import subprocess +import sys +import xml.etree.ElementTree as ET +from datetime import date +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "scn" +sys.path.insert(0, str(REPO / "scripts")) +import _bizdays # noqa: E402 +import _fedramp_schema # noqa: E402 +import _scn # noqa: E402 + +TODAY = date(2026, 11, 5) + + +def _load(name, path): + spec = importlib.util.spec_from_file_location(name, path) + m = importlib.util.module_from_spec(spec) + spec.loader.exec_module(m) + return m + + +build = _load("build_scn", REPO / "scripts" / "build-scn.py") +evaluate = _load("scn_evaluate", REPO / "scripts" / "scn-evaluate.py") +deadlines = _load("scn_deadlines", REPO / "scripts" / "check-scn-deadlines.py") + + +# --- business days ------------------------------------------------------------------ + +def test_federal_holidays_2026_are_the_observed_eleven(): + assert sorted(_bizdays.federal_holidays(2026)) == [date(2026, m, d) for m, d in ( + (1, 1), (1, 19), (2, 16), (5, 25), (6, 19), (7, 3), (9, 7), (10, 12), (11, 11), (11, 26), (12, 25))] + + +@pytest.mark.parametrize("day,observed", [ + (date(2026, 7, 4), date(2026, 7, 3)), # Saturday -> Friday + (date(2027, 6, 19), date(2027, 6, 18)), # Saturday -> Friday + (date(2027, 7, 4), date(2027, 7, 5)), # Sunday -> Monday + (date(2027, 12, 25), date(2027, 12, 24)), + (date(2028, 1, 1), date(2027, 12, 31)), # New Year's on a Saturday: observed the year before +]) +def test_weekend_holidays_move_to_the_observed_day(day, observed): + assert observed in _bizdays.federal_holidays(observed.year) + assert day not in _bizdays.federal_holidays(day.year) + + +def test_business_day_arithmetic_skips_weekends_and_holidays(): + assert _bizdays.add_business_days(date(2026, 11, 25), 1) == date(2026, 11, 27) # Thanksgiving + assert _bizdays.add_business_days(date(2026, 11, 6), 1) == date(2026, 11, 9) # weekend + assert _bizdays.add_business_days(date(2026, 11, 10), 1) == date(2026, 11, 12) # Veterans Day + assert _bizdays.add_business_days(date(2027, 1, 4), -1) == date(2026, 12, 31) # New Year's Day + assert _bizdays.add_business_days(date(2026, 6, 6), 10) == date(2026, 6, 22) # Juneteenth in the span + assert _bizdays.add_business_days(date(2026, 11, 5), 0) == date(2026, 11, 5) + + +def test_timeframes_come_from_the_vendored_rules(): + assert {r: _scn.timeframe(r) for r in ("SCN-ADP-NTF", "SCN-TRF-NIP", "SCN-TRF-NFP", "SCN-TRF-NAF", + "SCN-TRF-NAV", "SCN-TRF-UPD")} == { + "SCN-ADP-NTF": 10, "SCN-TRF-NIP": 30, "SCN-TRF-NFP": 10, "SCN-TRF-NAF": 5, "SCN-TRF-NAV": 5, + "SCN-TRF-UPD": 30} + + +# --- the evaluation gate (SCN-CSO-EVA) ---------------------------------------------------- + +BAD = { + "missing-type.md": "no 'SCN-Type:' line", + "missing-rationale.md": "no 'SCN-Rationale:' line", + "placeholder-rationale.md": "empty or a placeholder", + "unknown-type.md": "is not one of", + "class-change.md": "class-change blocks the merge", + "adaptive-no-record.md": "needs an 'SCN-Record: SCN-YYYY-NNN' line", + "routine-with-record.md": "names no SCN-Record", + "two-types.md": "2 'SCN-Type:' lines", + "transformative-too-soon.md": "may start on or after", +} + + +@pytest.mark.parametrize("name,why", sorted(BAD.items())) +def test_each_known_bad_evaluation_fails_for_its_reason(name, why): + index = json.loads((FIX / "index.json").read_text()) + errors, _, _ = _scn.gate((FIX / "bad" / name).read_text(), index, TODAY) + assert errors and any(why in e for e in errors), errors + + +@pytest.mark.parametrize("name,kind", [ + ("not-significant.md", "not-significant"), ("routine-recurring-legacy-spelling.md", "routine-recurring"), + ("adaptive.md", "adaptive"), ("emergency.md", "emergency"), ("transformative-ready.md", "transformative")]) +def test_each_good_evaluation_passes(name, kind): + index = json.loads((FIX / "index.json").read_text()) + errors, _, ev = _scn.gate((FIX / "good" / name).read_text(), index, TODAY) + assert errors == [] and ev["type"] == kind + + +def test_an_empty_description_fails_there_is_no_default(): + errors, _, ev = _scn.gate("", None, TODAY) + assert ev is None and "no 'SCN-Type:' line" in errors[0] + + +def test_transformative_fails_closed_without_the_published_index(): + errors, _, _ = _scn.gate((FIX / "good" / "transformative-ready.md").read_text(), None, TODAY) + assert "fail closed" in errors[0] + + +def test_the_cli_exits_nonzero_on_every_known_bad_fixture(capsys): + for name in BAD: + rc = evaluate.main(["--text-file", str(FIX / "bad" / name), "--index-file", str(FIX / "index.json"), + "--today", TODAY.isoformat()]) + assert rc == 1, name + assert evaluate.main(["--text-file", str(FIX / "good" / "adaptive.md"), "--today", TODAY.isoformat()]) == 0 + assert "::error::" in capsys.readouterr().out + + +def test_the_workflow_runs_the_tested_gate_with_no_default(): + text = (REPO / ".github" / "workflows" / "scn-tag.yml").read_text() + assert "python3 scripts/scn-evaluate.py --text-env SCN_TEXT" in text + assert "defaulting" not in text and "routine-recurring)" not in text + # The job keeps the name branch protection requires. + assert re.search(r"^ scn-tag:$", text, re.M) + # Untrusted text only through the environment. + assert "${{ github.event.pull_request.body }}" in text.split("env:", 1)[1].split("run:", 1)[0] + + +def test_every_type_has_a_documented_example(): + doc = (REPO / "docs" / "scn" / "evaluation-examples.md").read_text() + for t in _scn.TYPES: + block = doc.split(f"## {t}\n", 1) + assert len(block) == 2, t + example = block[1].split("## ", 1)[0] + errors, _, ev = _scn.gate(example.split("```")[1], json.loads((FIX / "index.json").read_text()), TODAY) + assert ev and ev["type"] == t, (t, errors) + + +# --- the register (SCN-CSO-INF, SCN-RTR-NNR, transformative template) ----------------------- + +def test_the_committed_register_is_valid(): + header, rows = _scn.read_register() + assert _scn.validate_register(header, rows) == [] + assert len(rows) >= 6 + + +@pytest.mark.parametrize("name,why", [ + ("register-routine.csv", "only adaptive and transformative changes get a notification record (SCN-RTR-NNR)"), + ("register-transformative-incomplete.csv", "tpr_human_validation must be yes or no"), + ("register-adaptive-no-risks.csv", "new_risks_summary is empty (SCN-ADP-NTF)"), + ("register-dates-out-of-order.csv", "is before date_initiated"), +]) +def test_each_known_bad_register_fails_for_its_reason(name, why): + header, rows = _scn.read_register(FIX / "bad" / name) + errors = _scn.validate_register(header, rows) + assert any(why in e for e in errors), errors + + +def test_an_incomplete_transformative_row_names_every_template_field(): + header, rows = _scn.read_register(FIX / "bad" / "register-transformative-incomplete.csv") + text = " ".join(_scn.validate_register(header, rows)) + for field in ("date_started", "plan_final", "tpr_human_validation", "tpr_assessor_or_reason"): + assert field in text + + +def test_transformative_notices_and_deadlines(): + header, rows = _scn.read_register(FIX / "good" / "register-transformative.csv") + assert _scn.validate_register(header, rows) == [] + due = {n["stage"]: n["deadline"] for n in _scn.notices_due(rows[0])} + assert due == { + "initial-plan": date(2026, 9, 18), # 30 business days before 2026-11-02 (Labor Day, Columbus Day) + "final-plan": date(2026, 10, 19), # 10 before + "after-finish": date(2026, 11, 20), # 5 after 2026-11-13 + "after-verification": date(2026, 11, 30), # 5 after 2026-11-20, over Thanksgiving + } + assert _scn.docs_update_deadline(rows[0]) == _bizdays.add_business_days(date(2026, 11, 13), 30) + + +def test_emergency_notices_are_retroactive_within_five_business_days(): + _, rows = _scn.read_register(FIX / "good" / "register-transformative.csv") + row = dict(rows[0], emergency="yes") + for n in _scn.notices_due(row): + assert n["deadline"] == date(2026, 11, 20) and n["kind"] == "retroactive" + assert "SCN-CSO-EMG" in n["rule"] + + +def test_adaptive_notice_is_due_ten_business_days_after_finishing(): + _, rows = _scn.read_register() + by_id = {r["scn_id"]: r for r in rows} + assert _scn.notices_due(by_id["SCN-2026-001"]) == [ + {"stage": "after-finish", "rule": "SCN-ADP-NTF", "deadline": date(2026, 6, 22), "kind": "by"}] + + +# --- publication: index, feed, retention (SCN-CSO-HIS/HRM/NOM/INF) -------------------------- + +def _build(tmp_path, *extra, new_entries=None): + (tmp_path / "new.json").write_text(json.dumps(new_entries or [])) + return build.main(["--out-dir", str(tmp_path), "--commit", "abc123", "--new-evaluations", + str(tmp_path / "new.json"), *extra]) + + +def test_build_publishes_every_register_row_in_the_fedramp_schema(tmp_path): + assert _build(tmp_path) == 0 + _, rows = _scn.read_register() + index = json.loads((tmp_path / "significant-change-notifications.json").read_text()) + assert [d["scnId"] for d in index["notifications"]] == [r["scn_id"] for r in rows] + for d in index["notifications"]: + assert _fedramp_schema.validate(d, "scn") == [] + assert (tmp_path / "scn" / f"{d['scnId']}.json").is_file() + assert d["certificationPackageOverviewUri"] == _fedramp_schema.CPO_URI + # SCN-CSO-ARI: more than the required fields. + assert d["additionalInformation"]["record"].startswith(_scn.SOURCE_URL) + # Human-readable view (SCN-CSO-HRM) carries each one. + md = (tmp_path / "significant-change-notifications.md").read_text() + assert all(d["scnId"] in md for d in index["notifications"]) + assert {m["mechanism"] for m in index["notificationMechanisms"]} == { + "Atom feed", "Signed JSON index", "Human-readable view"} + + +def test_a_new_notice_is_dated_today_and_late_ones_say_so(tmp_path): + assert _build(tmp_path) == 0 + index = json.loads((tmp_path / "significant-change-notifications.json").read_text()) + n = index["notifications"][0]["notices"][0] + assert n["publishedOn"] == build._today().isoformat() + assert n["onTime"] is (date.fromisoformat(n["publishedOn"]) <= date.fromisoformat(n["deadline"])) + assert "SCN-2026-001 after-finish" in index["lateNotices"] + + +def test_a_published_notice_keeps_its_first_publication_date(tmp_path): + prev = {"notifications": [{"scnId": "SCN-2026-001", "notices": [ + {"stage": "after-finish", "rule": "SCN-ADP-NTF", "deadline": "2026-06-22", "publishedOn": "2026-06-15", + "onTime": True}]}]} + (tmp_path / "prev.json").write_text(json.dumps(prev)) + assert _build(tmp_path, "--previous-index", str(tmp_path / "prev.json")) == 0 + index = json.loads((tmp_path / "significant-change-notifications.json").read_text()) + n = index["notifications"][0]["notices"][0] + assert n["publishedOn"] == "2026-06-15" and n["onTime"] is True + + +def test_a_build_that_would_drop_a_published_notification_fails(tmp_path): + with pytest.raises(SystemExit, match="SCN-2025-001 was published and would be dropped"): + _build(tmp_path, "--previous-index", str(FIX / "bad" / "index-previous-with-dropped.json")) + + +def test_the_feed_is_atom_with_one_entry_per_notice(tmp_path): + assert _build(tmp_path) == 0 + index = json.loads((tmp_path / "significant-change-notifications.json").read_text()) + root = ET.parse(tmp_path / "significant-change-notifications.atom").getroot() + ns = {"a": "http://www.w3.org/2005/Atom"} + assert root.tag == "{http://www.w3.org/2005/Atom}feed" + ids = [e.findtext("a:id", namespaces=ns) for e in root.findall("a:entry", ns)] + assert len(ids) == sum(len(d["notices"]) for d in index["notifications"]) == len(set(ids)) + + +def test_a_run_id_in_published_text_fails_the_build(tmp_path): + reg = tmp_path / "reg.csv" + reg.write_text((REPO / "docs" / "scn" / "scn-register.csv").read_text().replace( + "Implemented and verified 2026-10-27", "Implemented and verified 2026-10-27 (run 36434974425)")) + assert _build(tmp_path, "--register", str(reg)) == 1 + + +def test_the_published_outputs_are_listed_signed_and_governed(): + deploy = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() + step = deploy[deploy.index("- name: Build Significant Change Notifications"):] + assert "build-scn.py --previous-index previous-scn-index.json" in step + assert deploy.index("- name: Build Significant Change Notifications") < deploy.index( + "- name: Sign CDS certification-data artifacts") + sign = deploy[deploy.index("- name: Sign CDS certification-data artifacts"):] + sign = sign[:sign.index("\n - name:")] + assert "for a in significant-change-notifications scn-evaluations" in sign + assert "significant-change-notifications.atom.bundle significant-change-notifications.atom" in sign + cfg = {a["path"] for a in json.loads((REPO / "infrastructure" / "schemas" / "freshness-config.json") + .read_text())["artifacts"]} + assert {".well-known/significant-change-notifications.json", ".well-known/significant-change-notifications.atom", + ".well-known/scn-evaluations.json"} <= cfg + + +def test_the_cpo_lists_the_notification_mechanism(tmp_path): + cpo = _load("build_cpo_scn", REPO / "scripts" / "build-cpo.py") + out, md = tmp_path / "cpo.json", tmp_path / "cpo.md" + sys_argv = sys.argv + sys.argv = ["build-cpo.py", "--offering", str(REPO / "data" / "cds" / "offering.json"), + "--profile", str(REPO / "data" / "system-profile.json"), "--overview", str(tmp_path / "x.json"), + "--ksi-signal", str(tmp_path / "y.json"), "--output", str(out), "--md-output", str(md)] + try: + assert cpo.main() == 0 + finally: + sys.argv = sys_argv + doc = json.loads(out.read_text()) + urls = {m["url"] for m in doc["significant_change_notifications"]["mechanisms"]} + assert _scn.BASE + _scn.FEED_NAME in urls + assert {"significant-change-notifications.json", "significant-change-notifications.atom", + "scn-evaluations.json"} <= {p["artifact"] for p in doc["package_contents"]} + assert "Significant Change Notifications (SCN-CSO-NOM)" in md.read_text() + + +# --- the evaluation log (SCN-CSO-MAR) ------------------------------------------------------- + +def test_the_log_appends_to_the_previous_published_version(tmp_path): + prev = json.loads((FIX / "log-previous.json").read_text()) + new = [dict(prev["entries"][0], commit="3" * 40, merged_on="2026-11-10", pull_request=503)] + (tmp_path / "prev.json").write_text(json.dumps(prev)) + assert _build(tmp_path, "--previous-log", str(tmp_path / "prev.json"), new_entries=new) == 0 + log = json.loads((tmp_path / "scn-evaluations.json").read_text()) + assert log["entries"] == prev["entries"] + new + assert log["genesis_commit"] == prev["genesis_commit"] + assert "#503" in (tmp_path / "scn-evaluations.md").read_text() + + +@pytest.mark.parametrize("name,why", [("log-rewritten.json", "entry 1 (2222"), ("log-truncated.json", "dropped")]) +def test_the_append_only_check_fails_each_known_bad_log(name, why): + prev = json.loads((FIX / "log-previous.json").read_text())["entries"] + cur = json.loads((FIX / "bad" / name).read_text())["entries"] + errors = _scn.append_only_errors(prev, cur, "commit") + assert any(why in e for e in errors), errors + + +def _git(repo, *args): + return subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, text=True).stdout.strip() + + +@pytest.fixture +def history(tmp_path): + """main: an old commit, then a merge of PR #7 that adds the builder, then a + direct push, then a merge of PR #8 with no evaluation.""" + repo = tmp_path / "repo" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _git(repo, "config", "user.email", "t@example.invalid") + _git(repo, "config", "user.name", "tester") + (repo / "a").write_text("a") + _git(repo, "add", "-A") + _git(repo, "commit", "-qm", "before the log") + for n, path in ((7, build.GENESIS_PATH), (8, "c")): + _git(repo, "checkout", "-qb", f"b{n}") + (repo / path).parent.mkdir(parents=True, exist_ok=True) + (repo / path).write_text(str(n)) + _git(repo, "add", "-A") + _git(repo, "commit", "-qm", f"work {n}") + _git(repo, "checkout", "-q", "main") + _git(repo, "merge", "-q", "--no-ff", f"b{n}", "-m", f"Merge pull request #{n} from x/b{n}") + if n == 7: + (repo / "d").write_text("d") + _git(repo, "add", "-A") + _git(repo, "commit", "-qm", "direct push\n\nSCN-Type: not-significant\n" + "SCN-Rationale: content-only change to a public page here.") + return repo + + +def _lookup(n): + bodies = {7: "SCN-Type: adaptive\nSCN-Rationale: adds a new internal alarm, no ingress.\nSCN-Record: SCN-2026-007", + 8: "Forgot the evaluation."} + return {"body": bodies[n], "merged_by": "sam-aydlette", "author": "someone"} + + +def test_collect_logs_every_first_parent_commit_from_the_builder_onward(history): + entries = build.collect([], root=history, lookup=_lookup) + assert [(e["pull_request"], e["scn_type"]) for e in entries] == [ + (7, "adaptive"), (None, "not-significant"), (8, None)] + assert entries[0]["scn_record"] == "SCN-2026-007" and entries[0]["evaluator"] == "sam-aydlette" + assert entries[1]["evaluator"] == "tester" + assert entries[2]["problem"].startswith("no valid evaluation") + # Next deploy: only what came after the last entry. + assert build.collect(entries, root=history, lookup=_lookup) == [] + assert build.collect(entries[:1], root=history, lookup=_lookup) == entries[1:] + + +def test_collect_fails_when_the_last_logged_commit_left_history(history): + with pytest.raises(SystemExit, match="not an ancestor"): + build.collect([{"commit": "f" * 40}], root=history, lookup=_lookup) + + +def test_free_text_is_scrubbed_before_it_is_published(): + e = build.evaluation_entry("a" * 40, "direct", "SCN-Type: not-significant\nSCN-Rationale: fixes run 36434974425 " + "for account 123456789012 docs", "2026-11-05", "x", _lookup) + assert "36434974425" not in e["rationale"] and "123456789012" not in e["rationale"] + + +# --- the scheduled deadline check ----------------------------------------------------------- + +def _entry(kind, record, merged): + return {"commit": "9" * 40, "merged_on": merged, "scn_type": kind, "scn_record": record} + + +def test_an_adaptive_change_with_no_record_is_overdue_after_ten_business_days(): + _, rows = _scn.read_register() + index = {"notifications": [{"scnId": r["scn_id"], "notices": [{"stage": "after-finish"}]} for r in rows]} + log = [_entry("adaptive", "SCN-2026-007", "2026-11-02")] + assert _scn.overdue(rows, index, log, date(2026, 11, 17)) == [] # due 2026-11-17 (Veterans Day) + late = _scn.overdue(rows, index, log, date(2026, 11, 18)) + assert len(late) == 1 and "SCN-2026-007" in late[0] and "not in the register" in late[0] + + +def test_an_emergency_change_owes_its_record_within_five_business_days(): + _, rows = _scn.read_register() + index = {"notifications": [{"scnId": r["scn_id"], "notices": [{"stage": "after-finish"}]} for r in rows]} + log = [_entry("emergency", "SCN-2026-099", "2026-11-20")] + assert _scn.overdue(rows, index, log, date(2026, 11, 30)) == [] # Thanksgiving: due 11-30 + assert _scn.overdue(rows, index, log, date(2026, 12, 1)) + + +def test_an_unpublished_notice_is_overdue_until_a_deploy_publishes_it(): + _, rows = _scn.read_register() + late = _scn.overdue(rows, {}, [], TODAY) + assert any("SCN-2026-001: after-finish notice (SCN-ADP-NTF) not published" in x for x in late) + published = {"notifications": [{"scnId": r["scn_id"], "notices": [{"stage": "after-finish"}]} for r in rows]} + assert _scn.overdue(rows, published, [], TODAY) == [] + + +def test_transformative_notices_after_finish_and_verification_are_overdue_unpublished(): + _, rows = _scn.read_register(FIX / "good" / "register-transformative.csv") + index = {"notifications": [{"scnId": "SCN-2099-003", "notices": [ + {"stage": "initial-plan"}, {"stage": "final-plan"}]}]} + assert _scn.overdue(rows, index, [], date(2026, 11, 20)) == [] + late = _scn.overdue(rows, index, [], date(2026, 11, 23)) + assert len(late) == 1 and "after-finish notice (SCN-TRF-NAF)" in late[0] + late = _scn.overdue(rows, index, [], date(2026, 12, 1)) + assert any("after-verification notice (SCN-TRF-NAV)" in x for x in late) + + +def test_transformative_documentation_update_is_overdue_after_thirty_business_days(): + _, rows = _scn.read_register(FIX / "good" / "register-transformative.csv") + stages = ["initial-plan", "final-plan", "after-finish", "after-verification"] + index = {"notifications": [{"scnId": "SCN-2099-003", "notices": [{"stage": s} for s in stages]}]} + due = _scn.docs_update_deadline(rows[0]) + assert _scn.overdue(rows, index, [], due) == [] + assert "SCN-TRF-UPD" in _scn.overdue(rows, index, [], _bizdays.add_business_days(due, 1))[0] + done = [dict(rows[0], docs_updated_on="2026-12-01")] + assert _scn.overdue(done, index, [], _bizdays.add_business_days(due, 1)) == [] + + +def test_the_deadline_cli(tmp_path): + _, rows = _scn.read_register() + index = {"notifications": [{"scnId": r["scn_id"], "notices": [{"stage": "after-finish"}]} for r in rows]} + (tmp_path / "i.json").write_text(json.dumps(index)) + (tmp_path / "l.json").write_text(json.dumps({"entries": [_entry("adaptive", "SCN-2026-007", "2026-11-02")]})) + args = ["--index-file", str(tmp_path / "i.json"), "--log-file", str(tmp_path / "l.json")] + assert deadlines.main([*args, "--today", "2026-11-17"]) == 0 + assert deadlines.main([*args, "--today", "2026-11-18"]) == 1 From e911b5b49912a0d5f03dc1dfe2ab418d1a515e74 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 14:31:53 -0500 Subject: [PATCH 2/7] SCN log: accept only a full commit SHA from the published log (CodeGuard) SCN-Type: not-significant SCN-Rationale: input validation in the new SCN log builder; no system component, boundary or access change. Co-Authored-By: Claude Opus 5.5 --- scripts/build-scn.py | 6 +++++- tests/test_scn.py | 2 ++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/scripts/build-scn.py b/scripts/build-scn.py index a49b803f..3f147272 100644 --- a/scripts/build-scn.py +++ b/scripts/build-scn.py @@ -46,6 +46,7 @@ REPO = _scn.REPO GENESIS_PATH = "scripts/build-scn.py" +SHA_RE = re.compile(r"^[0-9a-f]{40}$") MERGE_RE = re.compile(r"^Merge pull request #(\d+) from ") RUN_ID_RE = re.compile(r"(actions/runs/|run )\d{6,}") @@ -129,7 +130,10 @@ def evaluation_entry(commit, subject, body, merged_on, author, lookup): def collect(previous_entries, root=REPO, lookup=gh_pull, head="HEAD"): """Entries for the first-parent commits after the last one logged.""" if previous_entries: - last = previous_entries[-1]["commit"] + last = previous_entries[-1].get("commit", "") + # Read from the published log: a full SHA or nothing, never an option. + if not SHA_RE.match(last): + raise SystemExit("::error::SCN log: the published log's last entry has no valid commit (fail-closed)") try: _git("merge-base", "--is-ancestor", last, head, root=root) except subprocess.CalledProcessError: diff --git a/tests/test_scn.py b/tests/test_scn.py index de58c2de..500f0b27 100644 --- a/tests/test_scn.py +++ b/tests/test_scn.py @@ -375,6 +375,8 @@ def test_collect_logs_every_first_parent_commit_from_the_builder_onward(history) def test_collect_fails_when_the_last_logged_commit_left_history(history): with pytest.raises(SystemExit, match="not an ancestor"): build.collect([{"commit": "f" * 40}], root=history, lookup=_lookup) + with pytest.raises(SystemExit, match="no valid commit"): + build.collect([{"commit": "--output=/tmp/x"}], root=history, lookup=_lookup) def test_free_text_is_scrubbed_before_it_is_published(): From c3016bedc79ab6a134cba991db0719e9b881946f Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 15:51:25 -0500 Subject: [PATCH 3/7] SCN-ADP-NTF: record the post-deploy state; disclose the five late historical notices The record describes the system after a successful deploy of this commit: the deploy builds and publishes every notice (any failure fails the deploy; the round-trip check compares the served index and feed), so the mechanism is in force. SCN-2026-001..005 were published after their deadlines and are named. SCN-Type: not-significant SCN-Rationale: rule-record text and a test only; no component, boundary, data flow or access change. Co-Authored-By: Claude Opus 5.5 --- data/frr-records.json | 37 +++++++++++++++++++++++++++++++------ tests/test_scn.py | 7 +++++++ 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/data/frr-records.json b/data/frr-records.json index ebfb3e40..535a0498 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -968,12 +968,37 @@ }, { "frr_id": "SCN-ADP-NTF", - "status": "Partially Implemented", - "implementation": "An adaptive record's notice (with its new-risks summary, which the register requires) is due 10 business days after date_finished, counted with US federal holidays (scripts/_bizdays.py); it is given by publication in the certification data, and the index records the deadline and the date first published. The scheduled SCN deadline check fails and raises an issue when the notice is not published by its deadline. Notification is publication only, the method FedRAMP's rules name (an update to the Certification Data); nothing is sent to FedRAMP or anyone else.", - "evidence": [], - "gap": "Not yet shown working: no notice has been published. The first deploy after this change publishes all six adaptive records; SCN-2026-006 is due 2026-11-10 and the other five are already past their deadlines, so they will be published marked late. Closes when a deploy publishes them (the operator approves deploys).", - "closes_with": [ - "sam" + "status": "Implemented", + "implementation": "Each adaptive record's notice, carrying its new-risks summary (required by the register), is due 10 business days after date_finished, counted with US federal holidays (scripts/_bizdays.py). It is given by publication in the certification data, the method FedRAMP's rules name; nothing is sent to FedRAMP or anyone else. Every deploy builds and publishes all notices (a build or publish failure fails the deploy, and the post-publish round-trip compares the served index and feed), and the index records each notice's deadline and the date it was first published. The scheduled SCN deadline check fails and raises an issue when a notice is unpublished past its deadline. History: the six adaptive notices were first published by the deploy that introduced this mechanism. SCN-2026-001, SCN-2026-002, SCN-2026-003, SCN-2026-004 and SCN-2026-005 were published after their deadlines (2026-06-22, 2026-07-07, 2026-07-23, 2026-10-09, 2026-10-13) and are marked late (onTime false, lateNotices). SCN-2026-006 (deadline 2026-11-10) is on time only if that deploy ran by its deadline; the published index records which.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_scn.py::test_adaptive_notice_is_due_ten_business_days_after_finishing" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_a_new_notice_is_dated_today_and_late_ones_say_so" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_an_unpublished_notice_is_overdue_until_a_deploy_publishes_it" + }, + { + "kind": "test", + "ref": "tests/test_scn.py::test_the_published_outputs_are_listed_signed_and_governed" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build Significant Change Notifications and the evaluation log" + }, + { + "kind": "step", + "ref": "scn-deadlines.yml#Check SCN deadlines" + }, + { + "kind": "artifact", + "ref": ".well-known/significant-change-notifications.json" + } ] }, { diff --git a/tests/test_scn.py b/tests/test_scn.py index 500f0b27..9212d63e 100644 --- a/tests/test_scn.py +++ b/tests/test_scn.py @@ -276,6 +276,13 @@ def test_the_published_outputs_are_listed_signed_and_governed(): sign = sign[:sign.index("\n - name:")] assert "for a in significant-change-notifications scn-evaluations" in sign assert "significant-change-notifications.atom.bundle significant-change-notifications.atom" in sign + # A successful deploy means they are out: the build step has no `|| true` + # escape, and the post-publish round-trip compares the served bytes. + assert "|| true" not in step[:step.index("\n - name:")] and "continue-on-error" not in step[:step.index("\n - name:")] + rt = deploy[deploy.index("- name: Post-publish round-trip verify"):] + rt = rt[:rt.index("\n - name:")] + for f in ("significant-change-notifications.json", "significant-change-notifications.atom", "scn-evaluations.json"): + assert f"check {f} .well-known/{f}" in rt cfg = {a["path"] for a in json.loads((REPO / "infrastructure" / "schemas" / "freshness-config.json") .read_text())["artifacts"]} assert {".well-known/significant-change-notifications.json", ".well-known/significant-change-notifications.atom", From c8480a8456fbecd08df1a03a19a0076ab1ec71d5 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 14:36:22 -0500 Subject: [PATCH 4/7] Incident evaluation and reporting: register, IIR/OIR/FIR, clocks, IRI/NRI triggers - data/incidents.json + schema + fail-closed loader (scripts/_incidents.py): every incident carries its FedRAMP reportability evaluation and reason; default N5 until an IEC-CSO-EFI estimate (checked against the rule's rubric). - scripts/build-incident-report.py renders Initial/Ongoing/Final reports in FedRAMP's incident report schema (validated before write) and the incident log; Class C clocks and the rating scale are read from the pinned rules. - policies/triage.rego incident_triggers: VER-TFR-IRI and VER-TFR-NRI, with thresholds parsed from the rule text (fail closed on a changed text). - Reconciliation invariant (m): an open incident's findings are in the VDR. - incident-reports.yml publishes unattended (publish-only; nothing is sent); bootstrap role scoped to .well-known/incident-*; the deploy also publishes; watchdog metric and alarm for overdue reports; freshness entry. - Dated exercise (2026-11-05, exercise: true): IIR -> 2x OIR -> FIR, plus a not-reportable evaluation; run end to end in tests. - FRR records: EFR, DPR, EFI, VER-TFR-IRI, VER-TFR-NRI Implemented; IIR, OIR, FIR, AIR Partially Implemented (publish-only; bootstrap apply pending). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 28 ++ .github/workflows/incident-reports.yml | 245 +++++++++ CLAUDE.md | 1 + data/frr-records.json | 213 ++++++-- data/incidents.json | 109 ++++ docs/boundary/boundary-classification.json | 6 +- docs/cr26-applicability.md | 2 +- docs/incident-response.md | 29 +- docs/policies/ir-policy.md | 19 +- docs/runbooks/evidence-sla-alarm.md | 9 +- infrastructure/bootstrap/incident-reports.tf | 97 ++++ infrastructure/schemas/freshness-config.json | 12 + infrastructure/schemas/gate-modes.json | 3 + infrastructure/schemas/incidents.schema.json | 107 ++++ infrastructure/watchdog.tf | 13 +- infrastructure/watchdog/index.mjs | 3 + infrastructure/watchdog/logic.mjs | 22 +- policies/triage.rego | 98 ++++ policies/triage_test.rego | 102 ++++ scripts/_freshness.py | 1 + scripts/_gates.py | 1 + scripts/_incidents.py | 412 +++++++++++++++ scripts/_rules.py | 81 +++ scripts/build-incident-report.py | 413 +++++++++++++++ scripts/build-ksi-signal.py | 3 + scripts/build-ocr.py | 26 +- scripts/reconcile.py | 39 +- .../fixtures/incidents/bad/duplicate-id.json | 74 +++ .../fixtures/incidents/bad/empty-reason.json | 46 ++ .../bad/evaluated-before-detected.json | 46 ++ .../incidents/bad/final-before-recovery.json | 53 ++ .../incidents/bad/final-not-last.json | 62 +++ .../incidents/bad/first-not-initial.json | 46 ++ .../fixtures/incidents/bad/future-report.json | 53 ++ .../bad/initial-without-description.json | 46 ++ .../fixtures/incidents/bad/not-evaluated.json | 45 ++ .../bad/not-reportable-with-report.json | 46 ++ .../incidents/bad/notification-sends.json | 46 ++ .../incidents/bad/personal-email.json | 46 ++ .../incidents/bad/rating-off-rubric.json | 54 ++ .../bad/report-before-evaluation.json | 46 ++ .../fixtures/incidents/bad/unknown-field.json | 47 ++ .../incidents/bad/vuln-basis-no-finding.json | 44 ++ .../incidents/bad/vuln-basis-not-adopted.json | 46 ++ tests/fixtures/incidents/good.json | 46 ++ tests/fixtures/incidents/reconcile-m-bad.json | 46 ++ tests/test_evidence_watchdog.py | 37 ++ tests/test_incidents.py | 470 ++++++++++++++++++ tests/test_published_redaction.py | 8 + 49 files changed, 3465 insertions(+), 82 deletions(-) create mode 100644 .github/workflows/incident-reports.yml create mode 100644 data/incidents.json create mode 100644 infrastructure/bootstrap/incident-reports.tf create mode 100644 infrastructure/schemas/incidents.schema.json create mode 100644 scripts/_incidents.py create mode 100644 scripts/build-incident-report.py create mode 100644 tests/fixtures/incidents/bad/duplicate-id.json create mode 100644 tests/fixtures/incidents/bad/empty-reason.json create mode 100644 tests/fixtures/incidents/bad/evaluated-before-detected.json create mode 100644 tests/fixtures/incidents/bad/final-before-recovery.json create mode 100644 tests/fixtures/incidents/bad/final-not-last.json create mode 100644 tests/fixtures/incidents/bad/first-not-initial.json create mode 100644 tests/fixtures/incidents/bad/future-report.json create mode 100644 tests/fixtures/incidents/bad/initial-without-description.json create mode 100644 tests/fixtures/incidents/bad/not-evaluated.json create mode 100644 tests/fixtures/incidents/bad/not-reportable-with-report.json create mode 100644 tests/fixtures/incidents/bad/notification-sends.json create mode 100644 tests/fixtures/incidents/bad/personal-email.json create mode 100644 tests/fixtures/incidents/bad/rating-off-rubric.json create mode 100644 tests/fixtures/incidents/bad/report-before-evaluation.json create mode 100644 tests/fixtures/incidents/bad/unknown-field.json create mode 100644 tests/fixtures/incidents/bad/vuln-basis-no-finding.json create mode 100644 tests/fixtures/incidents/bad/vuln-basis-not-adopted.json create mode 100644 tests/fixtures/incidents/good.json create mode 100644 tests/fixtures/incidents/reconcile-m-bad.json create mode 100644 tests/test_incidents.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index f6c9c311..06b22820 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1538,6 +1538,23 @@ jobs: cosign sign-blob --yes --new-bundle-format --bundle "$a.bundle" "$a.json" done + # Incident reports (IEC-CSO-IIR/OIR/FIR) and the incident log, from the + # incident register and this build's VDR (VER-TFR-IRI/NRI triggers). The + # same builder runs unattended in incident-reports.yml on every change to + # the register; the deploy republishes them so a deploy never serves a log + # older than the register it was built from. Each report is validated + # against FedRAMP's schema before it is written. No clock check here: an + # overdue report must not block the deploy that may be the fix; the + # incident-reports workflow and the evidence watchdog alarm on it. + - name: Build incident reports (IIR, OIR, FIR) + working-directory: infrastructure + run: | + set -euo pipefail + python3 ../scripts/build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . + for f in incident-*.json; do + cosign sign-blob --yes --new-bundle-format --bundle "${f%.json}.bundle" "$f" + done + # ------------------------------------------------------------------------- # PROJECT THE CANONICAL INVENTORY INTO FEDRAMP IIW (APPENDIX M) SHAPE # ------------------------------------------------------------------------- @@ -1762,6 +1779,8 @@ jobs: [ -f "$a.json" ] || continue files="$files $a.json" done + # Incident log and reports (built every deploy, so the glob always matches). + for f in incident-*.json incident-*.md; do files="$files $f"; done # shellcheck disable=SC2086 # a word list by design python3 ../scripts/check-published-redaction.py $files @@ -1832,6 +1851,14 @@ jobs: aws s3 cp "$a.json" "s3://$BUCKET_NAME/.well-known/$a.json" --content-type application/json --cache-control "public, max-age=300" aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" done + # Incident log (IEC-CSO-EFR) + every Initial/Ongoing/Final report + signatures + aws s3 cp incident-reports.json "s3://$BUCKET_NAME/.well-known/incident-reports.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp incident-reports.bundle "s3://$BUCKET_NAME/.well-known/incident-reports.bundle" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp incident-reports.md "s3://$BUCKET_NAME/.well-known/incident-reports.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + for f in incident-INC-*.json; do + aws s3 cp "$f" "s3://$BUCKET_NAME/.well-known/$f" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "${f%.json}.bundle" "s3://$BUCKET_NAME/.well-known/${f%.json}.bundle" --content-type application/json --cache-control "public, max-age=300" + done echo "✅ All signed artifacts published to /.well-known/ (post-gate)" # ------------------------------------------------------------------------- @@ -1924,6 +1951,7 @@ jobs: check trust-center.json .well-known/trust-center.json check conformance-results.json .well-known/conformance-results.json if [ -f boundary-corroboration.json ]; then check boundary-corroboration.json .well-known/boundary-corroboration.json; fi + for f in incident-*.json; do check "$f" ".well-known/$f"; done # SLSA/in-toto provenance attestations (S2/S3): served bytes match the build. for a in ksi-signal.json security-decision-record.json vdr-report.json iiw.csv; do check "$a.intoto.jsonl" ".well-known/$a.intoto.jsonl" diff --git a/.github/workflows/incident-reports.yml b/.github/workflows/incident-reports.yml new file mode 100644 index 00000000..fbf92b77 --- /dev/null +++ b/.github/workflows/incident-reports.yml @@ -0,0 +1,245 @@ +# ============================================================================= +# GitHub Actions Workflow: Incident Reports (IEC-CSO-AIR) +# ============================================================================= +# FedRAMP's Incident Evaluation and Communication rules put an Initial Incident +# Report one hour after a FedRAMP Reportable Incident is identified (Class C, +# N3-N5), and an Ongoing report every six hours after that. The deploy path is +# behind a human reviewer and cannot keep those clocks, so reporting runs here, +# unattended, the moment the incident register changes (IEC-CSO-AIR: automate +# reporting; no hand-crafted email): +# +# push to data/incidents.json on main, or by hand, or twice a day, or after +# each nightly VDR refresh +# -> validate the register (scripts/_incidents.py, fail-closed) +# -> fetch the published VDR, verified against the deploy or nightly +# identity, for the vulnerabilities that are reportable incidents +# (VER-TFR-IRI / VER-TFR-NRI, decided by policies/triage.rego) +# -> build every IIR/OIR/FIR (validated against FedRAMP's incident report +# schema) and the incident log (scripts/build-incident-report.py) +# -> sign, redaction-gate, publish under /.well-known/incident-*, invalidate +# -> check the clocks: fail, and raise an issue, when a report is overdue +# +# The evidence watchdog (infrastructure/watchdog.tf) reads the published log +# hourly and pages by email when a listed report passes its deadline, on AWS's +# clock, whether or not this workflow runs. +# +# NOTIFICATION IS PUBLISH-ONLY. Nothing here sends a report to FedRAMP or to an +# agency. The operator has not authorized sending, and this system has no +# FedRAMP certification and no agency customers; the register's policy and +# every report say so. Sending is a separate decision and a separate change. +# +# THE TRADE, as for the evidence nightly: an unattended production write. Its +# role (infrastructure/bootstrap/incident-reports.tf, operator-applied) can put +# objects under `.well-known/incident-*` and invalidate the CDN, and nothing +# else: no Terraform, no website sync, no delete, no read of anything. +# ============================================================================= + +name: Incident Reports + +on: + push: + branches: [main] + paths: [data/incidents.json] + workflow_dispatch: + # Keeps the published log inside its 24-hour freshness window when nothing + # changes, and re-reads the VDR for new VER-TFR-IRI/NRI triggers. + schedule: + - cron: '47 7 * * *' + - cron: '47 19 * * *' + # Right after each nightly VDR refresh, so a vulnerability that has just + # become a reportable incident is in the log within minutes of the VDR. + workflow_run: + workflows: [Evidence Nightly (VDR refresh)] + types: [completed] + branches: [main] + +concurrency: + group: incident-reports + cancel-in-progress: false + +permissions: + contents: read + +env: + AWS_REGION: us-east-2 + # Same pins as the deploy and the nightly (tests/test_incidents.py checks). + OPA_VERSION: 1.18.2 + OPA_SHA256: 9903e5125ac281104f2c4b7371d10cc3b74a98933743fcbfc174f9bf0ab20de8 + SITE_BUCKET: samaydlette.com + SITE_ORIGIN: https://samaydlette.com + COSIGN_OIDC_ISSUER: https://token.actions.githubusercontent.com + +jobs: + report: + name: Build, sign and publish incident reports + runs-on: ubuntu-latest + timeout-minutes: 20 + # A nightly that did not succeed published no new VDR; a pull request never + # reaches the role. The event check closes a fork branch named `main`. + if: >- + github.event_name != 'workflow_run' || ( + github.event.workflow_run.conclusion == 'success' && + github.event.workflow_run.event != 'pull_request' && + github.event.workflow_run.head_repository.full_name == github.repository) + # No required reviewer: the clocks run while nobody is awake. The role this + # environment can assume writes only .well-known/incident-*. + environment: incident-reports + outputs: + clock: ${{ steps.clock.outcome }} + publish: ${{ steps.publish.outcome }} + permissions: + contents: read + id-token: write + + steps: + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install cosign + uses: sigstore/cosign-installer@7e8b541eb2e61bf99390e1afd4be13a184e9ebc5 # v3.10.1 + + - name: Setup OPA (triage policy) + run: | + curl -fL --retry 5 --retry-delay 5 --connect-timeout 10 --max-time 120 \ + -o opa "https://openpolicyagent.org/downloads/v${{ env.OPA_VERSION }}/opa_linux_amd64_static" + echo "${{ env.OPA_SHA256 }} opa" | sha256sum -c - + chmod 755 ./opa + sudo mv opa /usr/local/bin + opa version + + # The VDR arrives over the public internet, so it is verified before a byte + # of it is used: it must be signed by the deploy or the nightly on main. + - name: Fetch and verify the published VDR report + run: | + set -euo pipefail + mkdir -p out + curl -sfL --retry 3 --retry-delay 5 -o vdr-report.json "${SITE_ORIGIN}/.well-known/vdr-report.json" + curl -sfL --retry 3 --retry-delay 5 -o vdr-report.bundle "${SITE_ORIGIN}/.well-known/vdr-report.bundle" + ok=0 + for wf in deploy-with-opa evidence-nightly; do + if cosign verify-blob --bundle vdr-report.bundle \ + --certificate-identity "https://github.com/${{ github.repository }}/.github/workflows/$wf.yml@refs/heads/main" \ + --certificate-oidc-issuer "${COSIGN_OIDC_ISSUER}" vdr-report.json 2>/dev/null; then ok=1; break; fi + done + [ "$ok" -eq 1 ] || { echo "::error::the published VDR does not verify; refusing to derive incidents from it"; exit 1; } + + - name: Build incident reports (IIR, OIR, FIR) + id: build + run: python3 scripts/build-incident-report.py --incidents data/incidents.json --vdr vdr-report.json --out-dir out + + - name: Sign incident reports + working-directory: out + run: | + set -euo pipefail + for f in incident-*.json; do + cosign sign-blob --yes --new-bundle-format --bundle "${f%.json}.bundle" "$f" + done + + - name: Publication redaction gate (no AWS account ID) + working-directory: out + run: python3 ../scripts/check-published-redaction.py incident-*.json incident-*.md + + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0 + timeout-minutes: 6 + with: + # Defined in infrastructure/bootstrap/incident-reports.tf. Unset until + # the operator applies it and sets the variable; this step then fails + # and the alert job says so. + role-to-assume: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }} + aws-region: ${{ env.AWS_REGION }} + retry-max-attempts: 5 + + - name: Publish incident reports to /.well-known/ + id: publish + working-directory: out + run: | + set -euo pipefail + put() { + aws s3api put-object --bucket "${SITE_BUCKET}" --key ".well-known/$1" --body "$1" \ + --content-type "$2" --cache-control "public, max-age=300" --query 'ETag' --output text > /dev/null + echo "published .well-known/$1" + } + # Every report first, the log that lists them last. + for f in incident-INC-*.json; do + put "$f" "application/json" + put "${f%.json}.bundle" "application/json" + done + put incident-reports.md "text/markdown; charset=utf-8" + put incident-reports.bundle "application/json" + put incident-reports.json "application/json" + + - name: Invalidate CloudFront cache (incident paths only) + env: + DISTRIBUTION_ID: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} + run: | + set -euo pipefail + aws cloudfront create-invalidation --distribution-id "${DISTRIBUTION_ID}" \ + --paths "/.well-known/incident-*" --query 'Invalidation.Id' --output text + + - name: Assert the published incident log is fresh at the edge + run: | + set -euo pipefail + python3 scripts/check-evidence-freshness.py \ + --url "${SITE_ORIGIN}/.well-known/incident-reports.json" \ + --expect-sha256 "$(sha256sum out/incident-reports.json | awk '{print $1}')" \ + --retries 12 --retry-delay 20 + + # Last, so an overdue report is published (the log says what is late) and + # still fails the run. The watchdog pages on the same list independently. + - name: Incident report clocks (fail when a report is due and missing) + id: clock + if: ${{ !cancelled() && steps.build.outcome == 'success' }} + run: python3 scripts/build-incident-report.py --check out/incident-reports.json + + alert: + name: Alert on incident reporting + runs-on: ubuntu-latest + needs: [report] + if: always() && needs.report.result == 'failure' + permissions: + contents: read + issues: write + steps: + - name: Raise or update the incident-reporting issue + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + CLOCK: ${{ needs.report.outputs.clock }} + PUBLISH: ${{ needs.report.outputs.publish }} + with: + script: | + const TITLE = 'Incident reporting: a report is overdue or was not published'; + const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`; + const clock = process.env.CLOCK || 'not reached'; + const publish = process.env.PUBLISH || 'not reached'; + const runbook = `${context.payload.repository.html_url}/blob/main/docs/incident-response.md#reporting-fedramp-reportable-incidents-iec`; + const body = [ + `The incident reports workflow failed ([run](${runUrl}), trigger \`${context.eventName}\`).`, + ``, + `| | |`, `|---|---|`, + `| Report clocks | \`${clock}\` |`, + `| Publish | \`${publish}\` |`, + ``, + clock === 'failure' + ? `**A FedRAMP incident report is past its Class C deadline.** The "Incident report clocks" step names each one. Record the report (or open the incident) in data/incidents.json and push; this workflow publishes it.` + : `**The reports were not built or published.** Check the failing step. If "Configure AWS credentials" failed, the incident-reports role or the AWS_INCIDENT_REPORTS_ROLE_ARN variable is missing (infrastructure/bootstrap/incident-reports.tf).`, + ``, + `Runbook: ${runbook}. This issue is reused; each failure adds a comment.`, + ].join('\n'); + const existing = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, repo: context.repo.repo, state: 'all', per_page: 100, + labels: 'incident-reporting', + }); + const match = existing.filter(i => i.title === TITLE && !i.pull_request) + .sort((a, b) => (a.state === b.state ? a.number - b.number : a.state === 'open' ? -1 : 1))[0]; + if (match) { + if (match.state === 'closed') { + await github.rest.issues.update({ owner: context.repo.owner, repo: context.repo.repo, + issue_number: match.number, state: 'open' }); + } + await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, + issue_number: match.number, body }); + } else { + await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: TITLE, + body, labels: ['compliance', 'incident-reporting', 'urgent'], assignees: [context.repo.owner] }); + } diff --git a/CLAUDE.md b/CLAUDE.md index d092298d..96af2dfe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,6 +28,7 @@ Confirm against the working tree on first run; correct this section if reality d - `tools/boundary-map/corroborate.py` (local only) — independent corroboration of the map by 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. - `scripts/build-trust-center.py` — the trust center's data (`/.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 derived from this build's artifacts and the registers. Built after the reconciliation gate; fails closed if its inputs are bound to another inventory. A register field that is not recorded (who decided, when, review date) is published as a gap, never filled in. - `.github/workflows/deploy-with-opa.yml`, `infrastructure/Makefile`, `.checkov.yaml` — the pipeline, entry points, and IaC scan config. +- `data/incidents.json` + `scripts/_incidents.py` + `scripts/build-incident-report.py` — the incident register and FedRAMP incident reporting (IEC-CSO-*; VER-TFR-IRI/NRI via `policies/triage.rego` `incident_triggers`). Every incident carries its reportability evaluation; reportable ones get Initial/Ongoing/Final reports in FedRAMP's schema on the Class C clocks read from the pinned rules, published with the incident log at `/.well-known/incident-reports.json`. `.github/workflows/incident-reports.yml` publishes them unattended (role in `infrastructure/bootstrap/incident-reports.tf`, `.well-known/incident-*` only); the watchdog pages on an overdue report. Notification is publish-only: nothing is sent to FedRAMP or an agency. Exercises are records with `exercise: true`. - `.github/workflows/evidence-nightly.yml` — the unattended VDR refresh, **twice a day**, plus once after every successful deploy to `main` (`workflow_run`, so a deploy that fixes a failing nightly also clears its beacon): re-scan (Syft + Grype against a fresh vulnerability DB), rebuild the VDR + trend, run the same vulnerability and reconciliation gates, republish six objects under `.well-known/vdr-*` (report, bundle, markdown, trend, trend bundle, provenance attestation), and on every run, pass or fail, write a status beacon (`.well-known/vdr-status.json`, outcomes only, unsigned). No `terraform apply`, no website sync. Its alerting is the `alert` job (a GitHub issue), not the deploy workflow's `notify`. - `infrastructure/watchdog.tf` + `infrastructure/watchdog/` — the **evidence SLA watchdog**: an hourly Lambda reads every artifact listed in the governed freshness config from the bucket (AWS APIs only, no internet egress), publishes the VDR's and runtime signal's ages, the nightly's result and a count of artifacts past their window as CloudWatch metrics, and four alarms email the operator via a CMK-encrypted SNS topic. This is the page; the GitHub issue is the paper trail. The email subscription is created out of band so no address enters Terraform state. Runbook: `docs/runbooks/evidence-sla-alarm.md`. diff --git a/data/frr-records.json b/data/frr-records.json index 535a0498..4e1103cc 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -658,72 +658,163 @@ }, { "frr_id": "IEC-CSO-AIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No automation exists for incident reporting; nothing exists to automate. To close: Once the incident register and report builder exist, run them from a workflow (workflow_dispatch + on push to the incident register) that validates, signs, publishes and sends IIR/OIR/FIR automatically, and pages through the existing watchdog/SNS when a report deadline is near or missed.", + "status": "Partially Implemented", + "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "step", + "ref": "incident-reports.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "step", + "ref": "incident-reports.yml#Incident report clocks (fail when a report is due and missing)" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_air_workflow_validates_builds_signs_publishes_and_checks_the_clock_in_order" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Not yet running: the role in infrastructure/bootstrap/incident-reports.tf is operator-applied, and the incident-reports GitHub Environment and AWS_INCIDENT_REPORTS_ROLE_ARN variable must be set. Reporting reaches no affected party automatically because delivery is publish-only by the operator's choice. To close: apply the bootstrap role and set the environment and variable; then the operator's delivery decision (IEC-CSO-IIR).", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-DPR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "Nothing assigns a PAIN rating to an incident, so there is no default-to-N5 behaviour and no record of whether a prompt estimate replaced it. The VDR PAIN classifier (scripts/build-vdr-report.py:1730 assign_pain) rates vulnerabilities, not incidents. To close: In the incident register, set pain=5 with basis 'default (IEC-CSO-DPR)' when a record becomes reportable, and allow it to drop only through an EFI estimate record (rating, reason, estimated_at). Drive the IIR/OIR/FIR clocks from the effective rating. Test both paths and show them in the simulated-incident log.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A reportable incident is rated at the default the IEC-CSO-DPR text states (N5, read from the rule) until an IEC-CSO-EFI estimate record exists, and the report clocks use the rating in force at each start time. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_shows_the_default_rating_then_the_estimate" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-EFI", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No Incident Rating step: nothing estimates likely adverse impact on agency customers for an incident or assigns N1-N5 using the minimal/narrow/disruptive/debilitating x 1 or >1 agency scale. The required artifact (an incident log showing the evaluation and its reason) does not exist. To close: Add an EFI record type to the incident register: rating N1-N5, the customer-effect word, single or multiple agencies, reason, estimated_at. Document the rubric in docs/incident-response.md (it can reuse the VDR effect words from infrastructure/schemas/vdr-pain-config.json). Exercise it in the simulated incidents.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). An estimate record carries rating, customer effect (minimal/narrow/disruptive/debilitating), one or several agencies, reason and time; the loader refuses a rating that is not the one the IEC-CSO-EFI bullets give for that effect and agency count (the rubric is parsed from the rule text). Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_each_known_bad_register_fails_closed_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_rating_scale_and_default_come_from_the_rules" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_shows_the_default_rating_then_the_estimate" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-EFR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. docs/policies/ir-policy.md:15 only restates the trigger.", - "evidence": [], - "gap": "No step that evaluates each incident for effect (actual or likely) on confidentiality/integrity of federal customer data, no recorded determination with its reason, and no incident log. The required artifact (an incident log showing one or more real or simulated incidents evaluated, with the reason for the determination) does not exist. The runbook explicitly scopes federal-data incidents out, so it can't make the determination the rule asks for. To close: Add an incident register (e.g. data/incidents.json + schema) whose records carry detected_at, evaluated_at, reportable (bool), reason, and the federal-customer-data types considered. Add an 'Evaluate FedRAMP reportability' step to docs/incident-response.md triage (before Contain), define the data types that would be federal customer data for this offering, and fail a check if any incident record lacks an evaluation. Exercise it with at least two simulated incidents (one reportable, one not) and publish the log.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Every incident record must carry an evaluation (evaluated_at, reportable true/false, basis, reason, the federal customer data considered); a record without one does not load. docs/incident-response.md triage now evaluates reportability before containment. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. The published incident log is the artifact the rule asks for.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_each_known_bad_register_fails_closed_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_logs_a_not_reportable_evaluation_with_its_reason" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-FIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. A schema test fixture (tests/fixtures/cr26/good/incident.json, reportType Final, CVE-2099-0142) checks the validator only; it is not an incident.", - "evidence": [], - "gap": "No Final Incident Report generation on resolution/recovery, no final updates to all previously reported items, no clock (Class C: within 6 hours for N3-N5, 1 business day for N1-N2, after recovery), no delivery. No sample FIR. To close: Add reportType=Final generation when the incident record gets resolved_at and recovery_complete_at, with final values for every earlier IIR/OIR field. Alarm on the FIR deadline. Close the simulated incident with a FIR and link it from the incident log and the Ongoing Certification Report.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A Final report is allowed only after resolved_at and recovery_complete_at, restates final values for every earlier item, carries resolvedAt, and is due an FIR period after recovery (6 hours at N3-N5, 1 business day at N1-N2); overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_the_final_report_is_due_after_recovery_and_ongoing_reports_stop" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_and_final_reports_restate_every_earlier_item" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Published, not delivered (see IEC-CSO-IIR). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-IIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. The vendored schema infrastructure/schemas/fedramp-2026-06-24/fedramp-incident-report-schema-2026-06-24.json (reportType Initial/Ongoing/Final, federalIncidentCoordinator, timeline, potentialImpact, functionalImpact, recoveryPlan, affectedAgencies) and its validator are in place, but nothing produces a report.", - "evidence": [], - "gap": "No Initial Incident Report generator, no delivery to all affected parties (FedRAMP + affected agencies), and no clock (Class C: within 1 hour for N3-N5, 24 hours for N2, 1 business day for N1). None of the 8 items exists in any record: federal incident response coordinator contact, tracking ID, description, timeline (start, detection time/source, evaluation time, milestones), historical/current PAIN with EFI explanation, functional impact incl. C/I and federal data types, recovery plan/milestones, likely affected agencies. No sample IIR exists, real or simulated. To close: Build scripts/build-incident-report.py that renders an IIR from the incident register into the vendored schema (validated before write) plus a human-readable version; name the federal incident response coordinator contact; add a delivery step (e.g. signed publication to a restricted location plus email to a configured recipient list holding FedRAMP's incident address and each agency's contact) that starts on 'reportable' and is alarmed against the PAIN-based deadline (watchdog). Run a timed simulated incident end to end and keep the IIR.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). The Initial report carries all eight items (coordinator, tracking ID, description, timeline with start/detection/evaluation/milestones, historical and current rating with the EFI explanation, functional impact, recovery plan, likely affected agencies). Its clock (1 hour at N3-N5, 24 hours at N2, 1 business day at N1) runs from the evaluation; the incident-reports workflow fails and the evidence watchdog pages (IncidentReportsOverdue) once it passes. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_runs_initial_ongoing_final_all_on_time" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_every_report_validates_against_fedramps_schema_and_is_listed_with_its_hash" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Reports are published, not delivered: nothing notifies FedRAMP or an agency, and the operator has not decided to send. The unattended publisher needs infrastructure/bootstrap/incident-reports.tf applied and the AWS_INCIDENT_REPORTS_ROLE_ARN variable and incident-reports environment set before it runs. To close: the operator decides the delivery channel (e.g. SES from the system's domain to FedRAMP's incident address) and it is built behind that decision.", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-OIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No Ongoing Incident Report mechanism or cadence (Class C: every 6 hours for N3-N5, 24 hours for N2, 1 business day for N1), no 'updates or lack of updates' logic, and none of the additional items recorded: observed activity, IOCs, related CVE, root cause, response/recovery activities. No sample OIR. To close: Extend the incident report builder for reportType=Ongoing: diff against the previous report so every earlier item is restated (changed or 'no update'), add the 5 OIR fields to the incident record, and schedule/alarm the next OIR from the effective PAIN. Produce OIRs in the simulated exercise.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Each Ongoing report restates every earlier item with its latest value and marks each 'updated' or 'no update', and adds observed activity, indicators of compromise, related CVEs, root cause and response/recovery activities. The next one is due an OIR period (6 hours at N3-N5, 24 at N2, 1 business day at N1) after the previous report until the incident is resolved; overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_reports_are_due_every_oir_period_until_resolved" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_and_final_reports_restate_every_earlier_item" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Published, not delivered (see IEC-CSO-IIR). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ - "W6" + "sam" ] }, { @@ -1756,12 +1847,25 @@ }, { "frr_id": "VER-TFR-IRI", - "status": "Not Implemented", - "implementation": "Checked: policies/triage.rego block_rule 'top-impact-lev-irv' (G2) blocks only N5+LEV+IRV, as a pipeline block; docs/policies/ir-policy.md:13 states the IRI rule in prose.", - "evidence": [], - "gap": "Nothing treats an internet-reachable likely exploitable vulnerability at N4 or N5 as a FedRAMP Reportable Incident: no incident record is opened, no IIR/OIR/FIR clocks start, and nothing ends that status when it's partially mitigated to N3 or below. N4 IRV+LEV isn't even flagged beyond its 4-day deadline. Depends on the missing IEC machinery. To close: In triage.rego add an 'incident' decision (IRV and LEV and PAIN > N3) and in the builder open/update an incident record in the incident register (see IEC-CSO-EFR) with default PAIN-5 treatment, closing it when a verified partial mitigation brings it to N3 or below. Test with a synthetic finding.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "policies/triage.rego (incident_triggers) names every VDR finding that is internet-reachable, likely exploitable and above the N-rating the VER-TFR-IRI Class C text states (read from the rule; a changed text fails closed), unless it is a false positive or fully mitigated; once partially mitigated to N3 or below it no longer triggers. scripts/build-incident-report.py publishes each trigger in the incident log and, while no unresolved incident in data/incidents.json names it, puts an Initial report due from the finding's first evaluation at the default N5 clock: the incident-reports workflow fails and the evidence watchdog pages when that passes. Opening the incident record is the operator's act; its reports then follow IEC-CSO-IIR/OIR/FIR. Reconciliation invariant (m) fails a build whose open incident names a finding the VDR does not carry. Adopted in data/incidents.json policy.adopted_vulnerability_rules.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_irv_lev_n4_finding_with_no_incident_is_due_an_initial_report" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_a_partially_mitigated_finding_at_n3_is_no_longer_an_incident" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_reconcile_m_fails_the_known_bad_register" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { @@ -1796,12 +1900,21 @@ }, { "frr_id": "VER-TFR-NRI", - "status": "Not Implemented", - "implementation": "Checked: docs/policies/ir-policy.md:13 adopts NRI in prose ('non-internet-reachable likely-exploitable vulnerabilities at PAIN N5 are reportable until N4 or below per VER-TFR-NRI'); no code implements it.", - "evidence": [], - "gap": "MAY rule: optional, but the published policy claims it's adopted and nothing implements it. NLEV-IRV N5 findings never open an incident. To close: Either implement alongside IRI (NIRV and LEV and PAIN = N5 -> incident until a partial mitigation brings it to N4) or remove the claim from ir-policy.md and record the decision not to use the MAY.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "Adopted (docs/policies/ir-policy.md; data/incidents.json policy.adopted_vulnerability_rules). policies/triage.rego names every likely exploitable, not internet-reachable VDR finding at the N-rating the VER-TFR-NRI Class C text states (N5), until partially mitigated to N4 or below; the incident log and clocks treat it exactly as VER-TFR-IRI does. An unadopted rule's triggers are still shown but start no clock.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_nirv_lev_n5_finding_opens_under_nri_and_n4_does_not" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unadopted_rule_is_shown_but_starts_no_clock" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ], "may_rationale": "Adopted, as the incident response policy states: treating a likely exploitable, non-internet-reachable N5 vulnerability as reportable is stricter than required and costs little at this scale." } diff --git a/data/incidents.json b/data/incidents.json new file mode 100644 index 00000000..f00b35da --- /dev/null +++ b/data/incidents.json @@ -0,0 +1,109 @@ +{ + "$comment": "The incident register (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR). Every incident is recorded here once, with its FedRAMP reportability evaluation and reason; a reportable one carries its Incident Rating estimates and the Initial, Ongoing and Final reports issued, each with when it was issued and what it set. scripts/_incidents.py validates it (fail-closed) and scripts/build-incident-report.py renders the reports and the incident log; .github/workflows/incident-reports.yml publishes them on every change to this file. The report clocks are FedRAMP's Class C timeframes, read from the pinned rules, never set here. Everything in this file is published. Exercises are marked exercise: true. Shape: infrastructure/schemas/incidents.schema.json.", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Sam Aydlette, System Owner and incident response lead; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only. Each report is signed and published under https://samaydlette.com/.well-known/ (incident-reports.json lists every report and its sha256). Nothing is sent to FedRAMP or to any agency: the operator has not authorized sending, and this system has no FedRAMP certification and no agency customers.", + "adopted_vulnerability_rules": ["VER-TFR-IRI", "VER-TFR-NRI"], + "federal_customer_data": "None. This system holds no federal customer data (FRD-FCD) and has no agency customers. Were an agency to use the Silk Reeling application, what its users supply to it (pose landmarks) would be the federal customer data to consider; the operator's public site content, account information and the published evidence are not.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-001", + "title": "Exercise: internet-reachable likely exploitable N5 vulnerability in the Silk Reeling API", + "exercise": true, + "started_at": "2026-11-05T02:40:00Z", + "detected_at": "2026-11-05T03:00:00Z", + "detection_source": "Exercise inject: a simulated VDR finding that policies/triage.rego flags under VER-TFR-IRI", + "evaluation": { + "evaluated_at": "2026-11-05T03:10:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Simulated timeline. An internet-reachable, likely exploitable vulnerability rated N5 in a dependency of the Silk Reeling API. The operator treats such a vulnerability as a FedRAMP Reportable Incident (VER-TFR-IRI) until it is partially mitigated to N3 or below. The scenario assumes one agency whose users supply data to the application.", + "federal_customer_data_considered": "Scenario assumption: pose landmarks supplied by one agency's users of the Silk Reeling application. In reality the system holds no federal customer data." + }, + "findings": ["CVE-2099-0001"], + "estimates": [ + { + "estimated_at": "2026-11-05T04:30:00Z", + "rating": 3, + "customer_effect": "disruptive", + "agencies": "single", + "reason": "Exploitation could expose the landmark data of many of the assumed agency's users without interrupting the service for long; no other agency is assumed." + } + ], + "reports": [ + { + "type": "Initial", + "at": "2026-11-05T03:40:00Z", + "set": { + "description": "A request-parsing dependency of the Silk Reeling API has a vulnerability (simulated CVE-2099-0001) that an unauthenticated client could exploit over the internet to read other users' submitted data.", + "functional_impact": "Potential loss of confidentiality of pose landmarks submitted by the assumed agency's users; no integrity or availability effect is expected.", + "recovery_plan": "Throttle the affected endpoint now; upgrade the dependency to the fixed release and redeploy through the reviewed pipeline. Targets: partial mitigation within 3 hours, remediation within 1 day.", + "affected_agencies": ["Hypothetical agency A (exercise assumption)"], + "related_cves": ["CVE-2099-0001"], + "milestones": [ + {"at": "2026-11-05T03:00:00Z", "description": "Triage flagged the finding under VER-TFR-IRI (simulated)"} + ] + } + }, + { + "type": "Ongoing", + "at": "2026-11-05T09:20:00Z", + "set": { + "observed_activity": "No exploitation attempts in the API Gateway access logs since the vulnerable release was deployed (simulated review).", + "indicators_of_compromise": ["None observed (simulated)"], + "root_cause": "A vulnerable release of a request-parsing dependency (simulated CVE-2099-0001).", + "response_and_recovery_activities": "Endpoint throttled at 04:15 (simulated), a partial mitigation; Incident Rating estimated at N3; fixed release identified.", + "milestones": [ + {"at": "2026-11-05T04:15:00Z", "description": "Partial mitigation: affected endpoint throttled (simulated)"} + ] + } + }, + { + "type": "Ongoing", + "at": "2026-11-05T15:00:00Z", + "set": { + "response_and_recovery_activities": "Fixed release built and passing the pipeline's gates; deploy awaiting approval (simulated)." + } + }, + { + "type": "Final", + "at": "2026-11-05T17:45:00Z", + "set": { + "response_and_recovery_activities": "Fixed release deployed at 16:30 and the finding no longer appears in the VDR (simulated); recovery verified at 17:00.", + "recovery_plan": "Complete.", + "milestones": [ + {"at": "2026-11-05T16:30:00Z", "description": "Fixed release deployed (simulated)"} + ] + } + } + ], + "resolved_at": "2026-11-05T16:30:00Z", + "recovery_complete_at": "2026-11-05T17:00:00Z" + }, + { + "id": "INC-2026-002", + "title": "Exercise: unauthorized change to a page of the public site", + "exercise": true, + "started_at": "2026-11-05T10:00:00Z", + "detected_at": "2026-11-05T10:20:00Z", + "detection_source": "Exercise inject: simulated drift of a website HTML artifact between the deploy-time and runtime KSI signals", + "evaluation": { + "evaluated_at": "2026-11-05T10:35:00Z", + "reportable": false, + "basis": "IEC-CSO-EFR", + "reason": "Simulated timeline. The changed content is the operator's public site content, which is not federal customer data (FRD-FCD), and the change is not likely to affect the confidentiality or integrity of any federal customer data. Not a FedRAMP Reportable Incident; handled under the incident response runbook without FedRAMP reports.", + "federal_customer_data_considered": "None present: public website content only." + }, + "estimates": [], + "reports": [], + "resolved_at": "2026-11-05T11:30:00Z", + "recovery_complete_at": "2026-11-05T11:45:00Z" + } + ] +} diff --git a/docs/boundary/boundary-classification.json b/docs/boundary/boundary-classification.json index 69d1e17c..48d2e591 100644 --- a/docs/boundary/boundary-classification.json +++ b/docs/boundary/boundary-classification.json @@ -20,7 +20,7 @@ {"key": "audit", "zone": "system", "label": "Audit and shared keys", "match": ["aws::audit_log_trail::*", "aws::object_store::cloudtrail", "aws::kms_key::at_rest"]}, {"key": "trust-root", "zone": "system", "label": "CI/CD trust root (operator-applied bootstrap stack)", - "match": ["aws::oidc_provider::*", "aws::iam_role::deploy", "aws::iam_role::evidence_nightly", "aws::iam_role::plan", "aws::iam_group::*", "aws::iam_policy::*", "aws::object_store::tfstate", "aws::kv_table::*"]}, + "match": ["aws::oidc_provider::*", "aws::iam_role::deploy", "aws::iam_role::evidence_nightly", "aws::iam_role::incident_reports", "aws::iam_role::plan", "aws::iam_group::*", "aws::iam_policy::*", "aws::object_store::tfstate", "aws::kv_table::*"]}, {"key": "github", "zone": "external", "label": "GitHub repository, Actions and OIDC", "match": ["ext::github-repo", "ext::github-oidc"]}, {"key": "sigstore", "zone": "external", "label": "Sigstore (Fulcio CA and Rekor log)", @@ -69,6 +69,8 @@ {"id": "J", "label": "Evidence Nightly → S3 (.well-known/vdr-*)", "path": [{"component": "ext::github-oidc"}, {"component": "aws::iam_role::evidence_nightly"}, {"component": "aws::object_store::website"}], "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "GitHub OIDC → STS; the role can write only .well-known/vdr-* (unattended)", "encryption": "In transit TLS; at rest SSE-S3", "data": "Refreshed VDR and trend (Sigstore-signed)"}, {"id": "K", "label": "Watchdog → S3 (evidence freshness read)", "path": [{"component": "aws::event_schedule::evidence_watchdog"}, {"component": "aws::function::evidence_watchdog"}, {"component": "aws::object_store::website"}], - "protocol": "AWS-internal", "auth": "Watchdog Lambda role: s3:GetObject on the published evidence keys only", "encryption": "In transit: TLS", "data": "Published evidence timestamps; results go out as CloudWatch metrics that drive flow I's alarms"} + "protocol": "AWS-internal", "auth": "Watchdog Lambda role: s3:GetObject on the published evidence keys only", "encryption": "In transit: TLS", "data": "Published evidence timestamps; results go out as CloudWatch metrics that drive flow I's alarms"}, + {"id": "L", "label": "Incident Reports → S3 (.well-known/incident-*)", "path": [{"component": "ext::github-oidc"}, {"component": "aws::iam_role::incident_reports"}, {"component": "aws::object_store::website"}], + "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "GitHub OIDC → STS; the role can write only .well-known/incident-* (unattended)", "encryption": "In transit TLS; at rest SSE-S3", "data": "Incident log and IIR/OIR/FIR reports (Sigstore-signed)"} ] } diff --git a/docs/cr26-applicability.md b/docs/cr26-applicability.md index 0d20e28d..642739e1 100644 --- a/docs/cr26-applicability.md +++ b/docs/cr26-applicability.md @@ -25,6 +25,6 @@ The POA&M is retired (2026-11-04): CR26 has no POA&M. Open findings and their de - **IVV — Independent Verification and Validation.** `IVV-CSO-FIA` (Class C MUST) requires a persistent independent assessment by a **FedRAMP Recognized independent assessment service** (the artifact formerly called a 3PAO) or by FedRAMP. This system is self-attested and has engaged no such assessor, so the *independent* half cannot be met. The provider-side verification and validation an assessor would consume **are** produced (in the Security Decision Record); the independent half is unmet by design and recorded N/A. - **MKT — Marketplace Listing.** `MKT-IIP-AGU` requires demonstrating the offering is for agency use within 44 USC § 3506 scope, and the rule text is explicit that *"services used by private companies to meet other compliance requirements (such as CMMC) that do not also meet one of the above use cases are outside the scope of FedRAMP."* There is no agency use case and no intent to list, so MKT is N/A by statutory scope. - **AFC — Addressing FedRAMP Communication.** `AFC-CSO-INB` and the rest require maintaining a FedRAMP Security Inbox and handling FedRAMP correspondence. With no listing and no sponsor, FedRAMP has no reason to correspond, so there is no channel to maintain. AFC's grace period already ended **2026-07-01**; it is recorded N/A absent a sponsor. -- **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so no incident is FedRAMP-reportable and the `IEC-CSO-IIR` reporting clocks never start. The evaluation step still runs — the VDR aggregator assigns a PAIN rating to every finding — so the machinery is in place the moment federal data ever enters scope. +- **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so in practice no incident is FedRAMP-reportable. Every incident is still evaluated and recorded in `data/incidents.json`; reportable ones get Initial, Ongoing and Final reports in FedRAMP's schema, on the Class C clocks, published under `/.well-known/` (publish-only: nothing is sent). Exercised 2026-11-05 with simulated incidents marked as exercises; see `docs/incident-response.md`. These four are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. diff --git a/docs/incident-response.md b/docs/incident-response.md index 88101566..bae342b8 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -15,9 +15,10 @@ In-scope incidents: Out of scope: -- Any incident involving federal customer data, end-user accounts, or downstream agencies — this system has none of those - Service-level incidents around availability promises to anyone, since none exist +Federal customer data, end-user accounts and downstream agencies: this system has none, so no incident here is expected to be a FedRAMP Reportable Incident. Every incident is still evaluated for it (step 2 below) and the determination is recorded, because the evaluation is what the rules ask for, and because a wrong assumption would otherwise go unrecorded. + ## Detection Active detection sources: @@ -32,14 +33,30 @@ Active detection sources: ## Triage and response procedures 1. **Confirm.** Compare the runtime KSI signal at `/.well-known/ksi-signal-runtime.json` against the deploy-time signal. Any unexplained `result: "fail"` validation, or any component drift, is high-confidence signal of a real change. -2. **Contain.** +2. **Record and evaluate FedRAMP reportability (IEC-CSO-EFR).** Add the incident to [`data/incidents.json`](../data/incidents.json) with `detected_at`, `detection_source` and an `evaluation`: when it was evaluated, `reportable` true or false, the `basis` (`IEC-CSO-EFR`, or `VER-TFR-IRI` / `VER-TFR-NRI` for a vulnerability), the `reason`, and the federal customer data considered. Does it affect, or is it likely to affect, the confidentiality or integrity of federal customer data (data an agency or its users supply to the service, not account information or telemetry)? If yes it is a FedRAMP Reportable Incident: continue with [Reporting](#reporting-fedramp-reportable-incidents-iec) in parallel with containment. Push the record; the incident log republishes within minutes. +3. **Contain.** - **Credential compromise (AWS):** rotate the IAM access keys via the IAM console; revoke any active sessions; rotate the GitHub Actions secret holding the credentials. - **Credential compromise (GitHub):** revoke any compromised PATs; rotate the workflow's `GITHUB_TOKEN` is automatic per-run; reset OAuth grants if external apps are involved. - **Content compromise:** revert via `git`, push to `main`, and approve the `prod` deploy. S3 versioning preserves the prior state; CloudFront invalidation refreshes the edge. - **Supply-chain compromise:** pin the offending dependency to a known-good version, redeploy, and file a Dependabot suppression if the alert source is the GitHub Advisory Database. -3. **Eradicate.** Identify the root cause (credential, code, or config) and patch it. Confirm the patch holds via a fresh approved deploy. -4. **Recover.** Verify the runtime signal returns to clean. Verify `cosign verify-blob` still passes against the new signal and bundle. Confirm the site is reachable end-to-end. -5. **Lessons learned.** Append an after-action entry to the section below. +4. **Eradicate.** Identify the root cause (credential, code, or config) and patch it. Confirm the patch holds via a fresh approved deploy. +5. **Recover.** Verify the runtime signal returns to clean. Verify `cosign verify-blob` still passes against the new signal and bundle. Confirm the site is reachable end-to-end. +6. **Lessons learned.** Append an after-action entry to the section below. + +## Reporting FedRAMP Reportable Incidents (IEC) + +_AI-drafted (2026-11-05) to describe what is now built; for the operator's review._ + +Reporting is automated from the incident register. A person records facts; the pipeline renders, validates, signs, publishes and keeps the clocks. + +- **Register.** [`data/incidents.json`](../data/incidents.json), read through `scripts/_incidents.py` (fails closed; shape in `infrastructure/schemas/incidents.schema.json`). Each report is an entry in the incident's `reports` list (`Initial`, then `Ongoing`, then `Final`) with the time it is issued and the items it sets: description, functional impact, recovery plan, likely affected agencies, observed activity, indicators of compromise, related CVEs, root cause, response and recovery activities, milestones. A report restates everything set before it. +- **Rating.** Until an `estimates` entry exists, the incident is rated N5 (`IEC-CSO-DPR`). An estimate (`IEC-CSO-EFI`) records the customer effect (minimal, narrow, disruptive, debilitating), whether one agency or more than one is likely affected, the reason and the time; the register refuses a rating that is not the one the rules give for that combination (N1 minimal, N2 narrow, N3 disruptive on one agency, N4 debilitating on one or disruptive on several, N5 debilitating on several). +- **Clocks.** Read from FedRAMP's Class C rules: the Initial report is due from the evaluation, each Ongoing report from the previous report until the incident is resolved, and the Final report from `recovery_complete_at` (hours at N3-N5; 24 hours or one business day at N1-N2; business days skip weekends, and holidays are counted, which can only make a deadline earlier). The rating in force when each clock starts sets its length. +- **Build and publish.** `scripts/build-incident-report.py` writes each report in FedRAMP's incident report schema (`incident---.json`, validated before it is written) and the incident log (`incident-reports.json` and `.md`: every incident, its evaluation and reason, its rating history, each report with its sha256 and what changed, and each clock). `.github/workflows/incident-reports.yml` runs it on every push of the register to `main`, by hand, twice a day and after each nightly VDR refresh; it signs, redaction-gates and publishes under `/.well-known/incident-*` with a role that can write nothing else. Every deploy republishes the same set. +- **Alarms.** The workflow's last step fails, and raises a GitHub issue, when a report is past its deadline. The evidence SLA watchdog reads the published log hourly and pages by email (`incident-report-overdue`, [`runbooks/evidence-sla-alarm.md`](runbooks/evidence-sla-alarm.md)). +- **Vulnerabilities as incidents.** The operator adopts `VER-TFR-IRI` and `VER-TFR-NRI` (`policy.adopted_vulnerability_rules`). The VDR triage policy names each finding they cover; until an unresolved incident in the register lists it under `findings`, its Initial report is due from the finding's first evaluation at N5, so the alarms fire. Open the incident with basis `VER-TFR-IRI` or `VER-TFR-NRI` and the finding's tracking ID or CVE. Reconciliation invariant (m) fails a build whose open incident names a finding the VDR no longer carries: close it with a Final report. +- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency; the operator has not authorized sending, and the system has no certification and no agency customers. Every report says so. FedRAMP and the affected agencies are "all affected parties" under the rules; reaching them is a decision for the operator. +- **Exercises.** A simulated incident is recorded with `exercise: true` and is published marked as one. Exercised 2026-11-05: `INC-2026-001` (a simulated internet-reachable N5 vulnerability: Initial, two Ongoing and a Final report on a simulated timeline, all on time; rated N5 by default, then estimated N3) and `INC-2026-002` (a simulated page change, evaluated not reportable with its reason). `tests/test_incidents.py` runs the same exercise through the builder on every `make check`. ## After-action reports (KSI-INR-AAR) @@ -117,5 +134,5 @@ Single-tier. Author → author. External escalations: - **GitHub Support** — if the issue is GitHub-side (account, repo, workflow infrastructure) - The mailbox in `security.txt` for acknowledging external reporters -There is no actual FedRAMP authorization in scope, so the FedRAMP Security Inbox (FSI) and Incident Communications Procedures (ICP) do not apply. +There is no actual FedRAMP certification in scope, so the FedRAMP Security Inbox (FSI) does not apply. Incident reports under the FedRAMP Incident Evaluation and Communication rules are generated and published as described above; they are not sent. diff --git a/docs/policies/ir-policy.md b/docs/policies/ir-policy.md index 81be6cb0..03c4e0db 100644 --- a/docs/policies/ir-policy.md +++ b/docs/policies/ir-policy.md @@ -1,15 +1,24 @@ # IR — Incident Response -Incident response procedures are documented in [`incident-response.md`](../incident-response.md), which satisfies KSI-INR-RIR through KSI-INR-AAR and the IR-9 family (information spillage). The runbook covers detection sources, triage, containment, eradication, recovery, and after-action reporting. The IR lead is the operator; escalation is single-tier. +Incident response procedures are documented in [`incident-response.md`](../incident-response.md), which satisfies KSI-INR-RIR through KSI-INR-AAR and the IR-9 family (information spillage). The runbook covers detection sources, triage (including the FedRAMP reportability evaluation), containment, eradication, recovery, FedRAMP incident reporting, and after-action reporting. The IR lead is the operator; escalation is single-tier. External communication paths: - **Public reporter:** [`/.well-known/security.txt`](../../website/.well-known/security.txt) is the published vulnerability-reporting mailbox. -- **Incident Communications Procedures (ICP, 20x):** the ICP rules apply at the procedure-documented level even though the system has no actual FedRAMP-customer reporting obligation. The runbook describes what would be communicated and to whom for a real FedRAMP-certified service. +- **FedRAMP incident reports (IEC):** every incident is recorded in the incident register, [`data/incidents.json`](../../data/incidents.json), with its reportability evaluation. Initial, Ongoing and Final Incident Reports for a FedRAMP Reportable Incident are generated from it, validated against FedRAMP's incident report schema, signed, and published under `/.well-known/` (the incident log is `/.well-known/incident-reports.json`) by an unattended workflow on every change to the register. +- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency. The operator has not authorized sending, and the system has no FedRAMP certification and no agency customers. Choosing a delivery channel is an operator decision; until it is made, publication is the only channel and every report says so. - **FedRAMP Security Inbox (FSI, 20x):** the system is not FedRAMP-certified; no actual FSI obligation applies. Notification path is documented in the runbook for reference. -**20x rule integration.** KSI-INR (Incident Response), ICP (Incident Communications Procedures), FSI (FedRAMP Security Inbox). +**20x rule integration.** KSI-INR (Incident Response), IEC (Incident Evaluation and Communication), FSI (FedRAMP Security Inbox). -**Review cadence.** Annually with the [security review](../security-review.md); after every actual incident (currently zero). VDR thresholds (Class C) treat internet-reachable likely-exploitable vulnerabilities above PAIN N3 (i.e. N4 or N5) as FedRAMP Reportable Incidents per `VER-TFR-IRI`, until they are partially mitigated to N3 or below; non-internet-reachable likely-exploitable vulnerabilities at PAIN N5 are reportable until N4 or below per `VER-TFR-NRI`. +**Reportability (IEC-CSO-EFR).** Every incident is evaluated, promptly and before containment, for whether it affects or is likely to affect the confidentiality or integrity of **federal customer data**; such an incident is a FedRAMP Reportable Incident. The determination, its reason and the federal customer data considered are recorded in the register and published in the incident log. This system holds no federal customer data, so in practice the evaluation is "not reportable"; the machinery runs either way, and it was exercised on 2026-11-05 with one simulated reportable incident and one simulated non-reportable one, both marked as exercises. -**Reportability trigger (IEC).** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so no finding here is FedRAMP-reportable in practice and the `IEC-CSO-IIR` reporting clocks (Class C: 1 hour for PAIN 3/4/5) never start. The evaluation step still runs — the VDR aggregator assigns the PAIN rating to every finding — so the machinery is in place the moment federal data ever enters scope. +**Rating (IEC-CSO-DPR, IEC-CSO-EFI).** A reportable incident is rated at the default the rules set (N5) until the operator records an Incident Rating estimate: a likely minimal, narrow, disruptive or debilitating customer effect on one or more than one agency, with a reason. The register refuses an estimate whose rating is not the one the rules give for that effect. + +**Report clocks.** The Initial, Ongoing and Final report deadlines are FedRAMP's Class C timeframes, read from the pinned rules and never restated. An overdue report fails the incident reports workflow (raising a GitHub issue) and pages the operator through the evidence SLA watchdog. + +**Vulnerabilities as incidents (VER-TFR-IRI, VER-TFR-NRI).** The operator adopts both rules. An internet-reachable likely exploitable vulnerability above PAIN N3 (i.e. N4 or N5) is a FedRAMP Reportable Incident until it is partially mitigated to N3 or below (`VER-TFR-IRI`), and a non-internet-reachable likely exploitable vulnerability at PAIN N5 is one until it is N4 or below (`VER-TFR-NRI`, a MAY the operator has chosen to use). The VDR triage policy names each such finding; the incident log shows it, and until an incident in the register names it, its Initial report is due and the alarms above apply. + +**Review cadence.** Annually with the [security review](../security-review.md); after every actual incident (currently zero; the two recorded incidents are exercises). + +_AI-drafted (2026-11-05) to describe what the incident register, report builder and workflow now do; for the operator's review._ diff --git a/docs/runbooks/evidence-sla-alarm.md b/docs/runbooks/evidence-sla-alarm.md index 4057bb84..79f3f7c5 100644 --- a/docs/runbooks/evidence-sla-alarm.md +++ b/docs/runbooks/evidence-sla-alarm.md @@ -7,11 +7,12 @@ The evidence SLA watchdog (`infrastructure/watchdog.tf`) emails the operator thr | `nightly-failed` | the evidence nightly's last run failed, or no run has reported in 26h | a gate failed; or the cron is disabled or stuck | | `vdr-age` | the published VDR is more than 24h old | the reporting policy is breached; nightly runs have failed or stopped | | `runtime-age` | the runtime signal is more than 26h old | the daily runtime-check Lambda has failed or stopped | +| `incident-report-overdue` | an incident report listed as due in `/.well-known/incident-reports.json` is past its Class C deadline, or the incident log is missing or unreadable | an Initial, Ongoing or Final incident report was not issued in time; or a vulnerability that is a FedRAMP Reportable Incident (VER-TFR-IRI/NRI) has no incident opened | | `artifact-stale` | any artifact listed in `infrastructure/schemas/freshness-config.json` is past its window, missing, or has no readable timestamp | no deploy within the deploy-cadence window; the corroboration was not re-run; or one of the above | The windows are governed values in `infrastructure/schemas/freshness-config.json`; the thresholds above are read from it. Change a window there, through review, never in the alarm. -Any alarm also fires if the watchdog stops publishing metrics, because missing data counts as a breach. If all four fire together, check the watchdog itself first (a missing or invalid freshness config stops it before it publishes anything). +Any alarm also fires if the watchdog stops publishing metrics, because missing data counts as a breach. If all five fire together, check the watchdog itself first (a missing or invalid freshness config stops it before it publishes anything). ## `nightly-failed` @@ -30,6 +31,10 @@ The policy is already breached, so treat this as the priority. It usually follow Check the compliance Lambda (`samaydlette-com-opa-compliance`): its CloudWatch logs, its EventBridge rule, and the shared dead-letter queue `samaydlette-com-opa-compliance-dlq` for failed invocations. +## `incident-report-overdue` + +The published incident log (`/.well-known/incident-reports.json`, `obligations_due`) names each report still due, for which incident or finding, and its deadline. Follow [`docs/incident-response.md`](../incident-response.md#reporting-fedramp-reportable-incidents-iec): record the report (or, for a finding with no incident, open the incident) in `data/incidents.json` and push it; the **Incident Reports** workflow validates, builds, signs and publishes within minutes, and the alarm clears once the republished log no longer lists the report as due. If the log itself is missing or unreadable, run the workflow by hand and check its publish step. + ## `artifact-stale` The watchdog's log line for the run lists the stale artifacts under `stale`. To see the same from outside, run `python3 scripts/check-evidence-freshness.py --all https://samaydlette.com`. @@ -38,7 +43,7 @@ The watchdog's log line for the run lists the stale artifacts under `stale`. To - **`boundary-corroboration.json`:** re-run `tools/boundary-map/corroborate.py`, commit the result, and deploy. - **Nightly artifacts** (`vdr-*`): follow `nightly-failed` / `vdr-age` above. -## All four at once +## All five at once Check the watchdog: its log group `/aws/lambda/samaydlette-com-evidence-watchdog`, the dead-letter queue, and its EventBridge rule. Each run logs one JSON line with the values it published, the config version, and the stale artifacts. diff --git a/infrastructure/bootstrap/incident-reports.tf b/infrastructure/bootstrap/incident-reports.tf new file mode 100644 index 00000000..d38fb120 --- /dev/null +++ b/infrastructure/bootstrap/incident-reports.tf @@ -0,0 +1,97 @@ +# ============================================================================= +# BOOTSTRAP: GitHub OIDC role for unattended incident reporting (IEC-CSO-AIR) +# ============================================================================= +# Operator-applied (not CI), like everything else in this stack. +# +# WHY A ROLE OF ITS OWN. FedRAMP's Class C incident report clocks are hours (an +# Initial Incident Report within one hour for N3-N5, an Ongoing report every +# six). The deploy role sits behind the `prod` reviewer and cannot keep them, +# and the evidence nightly's role is scoped to `.well-known/vdr-*` on purpose: +# widening it to carry incident reports would make the VDR refresh's grant +# about something else. `.github/workflows/incident-reports.yml` runs in its +# own GitHub Environment with no required reviewer and assumes this role. +# +# THE WHOLE PERMISSION SET: PutObject under `.well-known/incident-*` and a CDN +# invalidation. No delete (an unattended job never unpublishes evidence), no +# read of any kind (the workflow verifies its publish through the public URL), +# no Terraform state, no website sync. The bucket default-encrypts with SSE-S3, +# so no KMS grant is involved. If a future change needs more, re-examine +# whether that work belongs on the unattended path before widening this. +# ============================================================================= + +variable "incident_reports_environment" { + type = string + description = "GitHub Environment the incident reports workflow runs in. No required reviewer; the role it grants is scoped to .well-known/incident-*." + default = "incident-reports" +} + +# TRUST: this repository, this GitHub Environment, nothing else. A pull request +# cannot assume it, and neither can a workflow that does not declare the +# environment. +data "aws_iam_policy_document" "incident_reports_trust" { + statement { + effect = "Allow" + actions = ["sts:AssumeRoleWithWebIdentity"] + + principals { + type = "Federated" + identifiers = [aws_iam_openid_connect_provider.github.arn] + } + + condition { + test = "StringEquals" + variable = "token.actions.githubusercontent.com:aud" + values = ["sts.amazonaws.com"] + } + + condition { + test = "StringEquals" + variable = "token.actions.githubusercontent.com:sub" + values = ["repo:${var.github_repo}:environment:${var.incident_reports_environment}"] + } + } +} + +resource "aws_iam_role" "incident_reports" { + name = "github-actions-incident-reports-oidc" + description = "Unattended incident reporting (IEC-CSO-AIR). PutObject under .well-known/incident-* and a CDN invalidation; nothing else." + assume_role_policy = data.aws_iam_policy_document.incident_reports_trust.json + max_session_duration = 3600 + + tags = merge(local.bootstrap_tags, local.bootstrap_cls.identity_secrets_internal, { Name = "github-actions-incident-reports-oidc" }) +} + +data "aws_iam_policy_document" "incident_reports_publish" { + statement { + sid = "PublishIncidentReportsOnly" + effect = "Allow" + actions = ["s3:PutObject"] + resources = ["arn:aws:s3:::${var.domain_name}/.well-known/incident-*"] + } +} + +resource "aws_iam_role_policy" "incident_reports_publish" { + name = "incident-reports-publish" + role = aws_iam_role.incident_reports.id + policy = data.aws_iam_policy_document.incident_reports_publish.json +} + +data "aws_iam_policy_document" "incident_reports_cdn" { + statement { + sid = "InvalidateIncidentPaths" + effect = "Allow" + actions = ["cloudfront:CreateInvalidation"] + resources = [aws_cloudfront_distribution.website.arn] + } +} + +resource "aws_iam_role_policy" "incident_reports_cdn" { + name = "incident-reports-cdn" + role = aws_iam_role.incident_reports.id + policy = data.aws_iam_policy_document.incident_reports_cdn.json +} + +output "incident_reports_role_arn" { + value = aws_iam_role.incident_reports.arn + description = "Set as the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN, which incident-reports.yml passes to configure-aws-credentials." +} diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index cd4b2f02..c81d4307 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -86,6 +86,18 @@ "signed": false, "note": "The nightly's status beacon. Unsigned and not evidence; listed because the watchdog pages on its age. The nightly runs twice a day, so 26 hours means runs have been missed." }, + { + "path": ".well-known/incident-reports.json", + "cadence": "nightly", + "max_age_hours": 24, + "timestamp": { + "source": "json", + "field": "emitted_at" + }, + "signed": true, + "signature": ".well-known/incident-reports.bundle", + "note": "The incident log (IEC-CSO-EFR) and, through it, every incident report it lists with its sha256. Rebuilt by .github/workflows/incident-reports.yml on every change to data/incidents.json and twice a day, and by every deploy. The report deadlines themselves are hours, so the watchdog also pages on each listed report past its deadline (IncidentReportsOverdue)." + }, { "path": ".well-known/ksi-signal-runtime.json", "cadence": "runtime", diff --git a/infrastructure/schemas/gate-modes.json b/infrastructure/schemas/gate-modes.json index d1e87bc2..cb7d7bc6 100644 --- a/infrastructure/schemas/gate-modes.json +++ b/infrastructure/schemas/gate-modes.json @@ -50,6 +50,9 @@ "decided_by": "Sam Aydlette", "decided_on": "2026-11-04", "review_by": "2027-11-04"}, {"check": "reconcile.l", "gate": "G6", "mode": "block", "method_default": "block", "decided_by": "Sam Aydlette", "decided_on": "2026-11-04", "review_by": "2027-11-04"}, + {"check": "reconcile.m", "gate": "G5", "mode": "block", "method_default": "block", + "reason": "Proposed with the incident register (W6, AI-drafted): an open incident naming a finding the VDR does not carry blocks, like every other cross-artifact invariant. Confirm at review.", + "decided_by": "Operator (proposed; confirm at review)", "decided_on": "2026-11-05", "review_by": "2027-11-05"}, { "check": "reconcile.i.unreadable", "gate": "G7", diff --git a/infrastructure/schemas/incidents.schema.json b/infrastructure/schemas/incidents.schema.json new file mode 100644 index 00000000..d933d0d4 --- /dev/null +++ b/infrastructure/schemas/incidents.schema.json @@ -0,0 +1,107 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "incidents.schema.json", + "title": "Incident register", + "description": "data/incidents.json: every incident, its FedRAMP reportability evaluation (IEC-CSO-EFR), its Incident Rating estimates (IEC-CSO-EFI; until one exists the IEC-CSO-DPR default applies) and the Initial, Ongoing and Final reports issued (IEC-CSO-IIR/OIR/FIR). scripts/_incidents.py enforces these rules at build time without a jsonschema dependency, plus the ones a schema cannot state: IDs are unique; times are in order (started, detected, evaluated, each report); an estimate's rating is the IEC-CSO-EFI rating for its customer effect and agency count; the first report is Initial and sets the description, and a Final report is last and follows recovery; a vulnerability basis is an adopted rule and names a finding; nothing is dated after now; and no account ID or outside email address appears.", + "type": "object", + "required": ["schema", "policy", "incidents"], + "properties": { + "$comment": {"type": "string"}, + "schema": {"const": "incidents/1"}, + "policy": {"$ref": "#/$defs/policy"}, + "incidents": {"type": "array", "items": {"$ref": "#/$defs/incident"}} + }, + "additionalProperties": false, + "$defs": { + "text": {"type": "string", "minLength": 1, "pattern": "\\S"}, + "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, + "time": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"}, + "texts": {"type": "array", "items": {"$ref": "#/$defs/text"}, "uniqueItems": true}, + "policy": { + "type": "object", + "required": ["federal_incident_coordinator", "notification", "notification_text", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by"], + "properties": { + "federal_incident_coordinator": {"$ref": "#/$defs/text", "description": "Who coordinates federal incident response and how to reach them (IEC-CSO-IIR item 1)."}, + "notification": {"enum": ["published-only"], "description": "How reports reach all affected parties. Only publication under /.well-known/ is built; sending is the operator's decision."}, + "notification_text": {"$ref": "#/$defs/text"}, + "adopted_vulnerability_rules": {"type": "array", "items": {"enum": ["VER-TFR-IRI", "VER-TFR-NRI"]}, "uniqueItems": true, "description": "Which of VER-TFR-IRI (SHOULD) and VER-TFR-NRI (MAY) the operator applies."}, + "federal_customer_data": {"$ref": "#/$defs/text", "description": "What would be federal customer data (FRD-FCD) for this offering."}, + "decided_by": {"$ref": "#/$defs/text"}, + "decided_on": {"$ref": "#/$defs/date"}, + "review_by": {"$ref": "#/$defs/date"} + }, + "additionalProperties": false + }, + "incident": { + "type": "object", + "required": ["id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", "estimates", "reports"], + "properties": { + "id": {"type": "string", "pattern": "^INC-\\d{4}-\\d{3}$"}, + "title": {"$ref": "#/$defs/text"}, + "exercise": {"type": "boolean", "description": "true for a simulated incident run to exercise the process."}, + "started_at": {"$ref": "#/$defs/time"}, + "detected_at": {"$ref": "#/$defs/time"}, + "detection_source": {"$ref": "#/$defs/text"}, + "evaluation": { + "type": "object", + "required": ["evaluated_at", "reportable", "basis", "reason", "federal_customer_data_considered"], + "properties": { + "evaluated_at": {"$ref": "#/$defs/time"}, + "reportable": {"type": "boolean"}, + "basis": {"enum": ["IEC-CSO-EFR", "VER-TFR-IRI", "VER-TFR-NRI"]}, + "reason": {"$ref": "#/$defs/text"}, + "federal_customer_data_considered": {"$ref": "#/$defs/text"} + }, + "additionalProperties": false + }, + "findings": {"$ref": "#/$defs/texts", "description": "VDR tracking IDs or CVE IDs the incident is about."}, + "estimates": {"type": "array", "items": { + "type": "object", + "required": ["estimated_at", "rating", "customer_effect", "agencies", "reason"], + "properties": { + "estimated_at": {"$ref": "#/$defs/time"}, + "rating": {"type": "integer", "minimum": 1, "maximum": 5}, + "customer_effect": {"enum": ["minimal", "narrow", "disruptive", "debilitating"]}, + "agencies": {"enum": ["single", "multiple"]}, + "reason": {"$ref": "#/$defs/text"} + }, + "additionalProperties": false + }}, + "reports": {"type": "array", "items": { + "type": "object", + "required": ["type", "at"], + "properties": { + "type": {"enum": ["Initial", "Ongoing", "Final"]}, + "at": {"$ref": "#/$defs/time"}, + "set": { + "type": "object", + "minProperties": 1, + "properties": { + "description": {"$ref": "#/$defs/text"}, + "functional_impact": {"$ref": "#/$defs/text"}, + "recovery_plan": {"$ref": "#/$defs/text"}, + "observed_activity": {"$ref": "#/$defs/text"}, + "root_cause": {"$ref": "#/$defs/text"}, + "response_and_recovery_activities": {"$ref": "#/$defs/text"}, + "affected_agencies": {"$ref": "#/$defs/texts"}, + "indicators_of_compromise": {"$ref": "#/$defs/texts"}, + "related_cves": {"type": "array", "items": {"type": "string", "pattern": "^CVE-[0-9]{4}-[0-9]{4,}$"}, "uniqueItems": true}, + "milestones": {"type": "array", "items": { + "type": "object", "required": ["at", "description"], + "properties": {"at": {"$ref": "#/$defs/time"}, "description": {"$ref": "#/$defs/text"}}, + "additionalProperties": false + }} + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }}, + "resolved_at": {"$ref": "#/$defs/time"}, + "recovery_complete_at": {"$ref": "#/$defs/time"} + }, + "additionalProperties": false + } + } +} diff --git a/infrastructure/watchdog.tf b/infrastructure/watchdog.tf index 16f1777f..19764d91 100644 --- a/infrastructure/watchdog.tf +++ b/infrastructure/watchdog.tf @@ -14,7 +14,7 @@ # nightly's status beacon and every other signed output under # /.well-known/) straight from the site bucket # -> CloudWatch metrics (Samaydlette/Evidence) -# -> four alarms -> SNS topic (CMK-encrypted) -> operator email +# -> five alarms -> SNS topic (CMK-encrypted) -> operator email # # The freshness windows are governed values (REQ-PUB-2, REQ-GOV-1). They are # read here with jsondecode(file(...)): the alarm thresholds, the objects the @@ -30,7 +30,8 @@ # Terraform lands in state and in the uploaded plan artifact of a public repo. # It is created once, out of band (docs/runbooks/evidence-sla-alarm.md). # -# Cost: four standard alarms plus four custom metrics, roughly $1.60/month. +# Cost: five standard alarms plus five custom metrics, roughly $2.00/month (the +# fifth pair, for overdue incident reports, adds about $0.40). # Every listed artifact feeds one StaleArtifacts count rather than a metric # each, so the cost stays flat as the list grows. # SNS email at this volume and 720 short invocations a month are within free @@ -78,6 +79,14 @@ locals { threshold = 0 summary = "At least one published /.well-known/ artifact is older than its governed freshness window, or unreadable. The watchdog's log names which." } + # The Class C incident report clocks (IEC-CSO-IIR/OIR/FIR) are hours, not + # days, so this reads the deadlines the incident log lists rather than the + # log's age, and pages once one has passed without its report. + "incident-report-overdue" = { + metric = "IncidentReportsOverdue" + threshold = 0 + summary = "An incident report is past its FedRAMP Class C deadline and has not been issued, or the incident log is unreadable. /.well-known/incident-reports.json lists what is due; issue it by adding the report to data/incidents.json." + } } } diff --git a/infrastructure/watchdog/index.mjs b/infrastructure/watchdog/index.mjs index dd1b50af..e744b5b3 100644 --- a/infrastructure/watchdog/index.mjs +++ b/infrastructure/watchdog/index.mjs @@ -25,6 +25,9 @@ // missing, or is too old to trust; else 0 // StaleArtifacts how many listed artifacts are past their governed // window, unreadable, or without a usable timestamp +// IncidentReportsOverdue how many incident reports the published incident +// log lists as due whose Class C deadline has passed +// (1 if the log is missing or unreadable) // // A missing or invalid config fails the run before anything is published; the // alarms read the missing data as a breach and page. diff --git a/infrastructure/watchdog/logic.mjs b/infrastructure/watchdog/logic.mjs index 97692b70..8e896f03 100644 --- a/infrastructure/watchdog/logic.mjs +++ b/infrastructure/watchdog/logic.mjs @@ -13,10 +13,11 @@ export const KEYS = { vdr: '.well-known/vdr-report.json', runtime: '.well-known/ksi-signal-runtime.json', status: '.well-known/vdr-status.json', + incidents: '.well-known/incident-reports.json', }; // Every artifact a metric below depends on. The config must list them. -export const REQUIRED = [KEYS.vdr, KEYS.runtime, KEYS.status, '.well-known/boundary-corroboration.json']; +export const REQUIRED = [KEYS.vdr, KEYS.runtime, KEYS.status, KEYS.incidents, '.well-known/boundary-corroboration.json']; // Reported when an artifact cannot be read or has no usable timestamp. Far past // any threshold, so it reads as a breach on every alarm. @@ -98,6 +99,22 @@ export function nightlyFailed(status, maxBeaconAgeHours, now = Date.now()) { return status.result === 'success' ? 0 : 1; } +// How many incident reports are past their Class C deadline and not issued +// (IEC-CSO-IIR/OIR/FIR). The incident log lists each report still due with its +// deadline (scripts/build-incident-report.py, obligations_due); this counts the +// ones whose time has passed on AWS's clock, so a missed one-hour Initial +// report pages within the hour even if nothing republishes the log. A log that +// is missing, unreadable or has no list is a breach (1), never zero. +export function incidentReportsOverdue(log, now = Date.now()) { + if (!log || typeof log !== 'object' || !Array.isArray(log.obligations_due)) return 1; + let overdue = 0; + for (const d of log.obligations_due) { + const due = Date.parse(d && d.due_at); + if (Number.isNaN(due) || due < now) overdue += 1; + } + return overdue; +} + // Every listed artifact past its window, or unreadable, or without a usable // timestamp. One metric for all of them keeps the cost flat as the list grows; // the log line names which. @@ -123,12 +140,13 @@ export function computeMetrics(config, readings, now = Date.now()) { RuntimeSignalAgeHours: age(KEYS.runtime), NightlyFailed: nightlyFailed(parsedBody(readings[KEYS.status]), config.windows[KEYS.status], now), StaleArtifacts: stale.length, + IncidentReportsOverdue: incidentReportsOverdue(parsedBody(readings[KEYS.incidents]), now), }, stale, }; } -const COUNTS = new Set(['NightlyFailed', 'StaleArtifacts']); +const COUNTS = new Set(['NightlyFailed', 'StaleArtifacts', 'IncidentReportsOverdue']); export function metricData(metrics, now) { return Object.entries(metrics).map(([MetricName, Value]) => ({ diff --git a/policies/triage.rego b/policies/triage.rego index 8058d105..071839f0 100644 --- a/policies/triage.rego +++ b/policies/triage.rego @@ -444,3 +444,101 @@ decide(item) := { } decisions := [decide(item) | some item in input.items] + +# ============================================================================= +# VULNERABILITIES TREATED AS FEDRAMP REPORTABLE INCIDENTS (VER-TFR-IRI, -NRI) +# ============================================================================= +# Entry points, over the findings of a built VDR report (input.findings): +# data.vdr.triage.incident_triggers one entry per finding a rule makes a +# FedRAMP Reportable Incident +# data.vdr.triage.incident_errors non-empty => the caller fails closed +# +# The N-rating comparisons are read from the Class C rule text in data.rules, +# not restated here: "N-rating > 3 ... until ... at N3 or below" (IRI) and +# "N-rating = 5 ... until ... at N4 or below" (NRI). A rule stays in force for a +# finding until its current rating (after partial mitigation) is at or below +# the "until" level, which for both rules is the trigger level's complement. +# A false positive is not a vulnerability and a fully mitigated finding is not +# exploitable, so neither triggers. Whether the operator has adopted each rule +# (IRI is a SHOULD, NRI a MAY at Class C) is the incident register's policy, +# applied by scripts/build-incident-report.py. +ver_tfr := data.rules.FRR.VER.data.all.TFR + +class_c_statement(rid) := s if { + s := ver_tfr[rid].varies_by_class.c.statement +} else := ver_tfr[rid].statement + +rule_digit(pattern, rid) := to_number(m[0][1]) if { + m := regex.find_all_string_submatch_n(pattern, class_c_statement(rid), 1) + count(m) == 1 +} + +iri_above := rule_digit(`N-rating > ([0-9])`, "VER-TFR-IRI") + +iri_until := rule_digit(`at N([0-9]) or below`, "VER-TFR-IRI") + +nri_equals := rule_digit(`N-rating = ([0-9])`, "VER-TFR-NRI") + +nri_until := rule_digit(`at N([0-9]) or below`, "VER-TFR-NRI") + +incident_errors contains "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" if { + not iri_above +} + +incident_errors contains "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" if { + not iri_until +} + +incident_errors contains "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" if { + not nri_equals +} + +incident_errors contains "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" if { + not nri_until +} + +# The trigger and the exit must be complements; anything else is a changed rule +# that needs reading before it is trusted. +incident_errors contains "VER-TFR-IRI: the trigger and the 'until' level are not complements" if { + iri_above != iri_until +} + +incident_errors contains "VER-TFR-NRI: the trigger and the 'until' level are not complements" if { + nri_until != nri_equals - 1 +} + +incident_errors contains msg if { + some f in input.findings + not regex.match(`^N[0-9]$`, sprintf("%v", [f.pain])) + msg := sprintf("%v: impact %v is not an N-rating", [f.tracking_id, f.pain]) +} + +pain_number(p) := to_number(substring(p, 1, -1)) + +still_a_vulnerability(f) if { + f.fully_mitigated != true + f.final_disposition != "false-positive" +} + +incident_rule(f) := "VER-TFR-IRI" if { + f.internet_reachable == true + f.likely_exploitable == true + pain_number(f.pain) > iri_above +} else := "VER-TFR-NRI" if { + f.internet_reachable == false + f.likely_exploitable == true + pain_number(f.pain) == nri_equals +} + +incident_triggers := [t | + some f in input.findings + still_a_vulnerability(f) + rule := incident_rule(f) + t := { + "tracking_id": f.tracking_id, + "cve": object.get(f, "cve", null), + "rule": rule, + "pain": f.pain, + "first_evaluated": object.get(f, "first_evaluated", null), + } +] diff --git a/policies/triage_test.rego b/policies/triage_test.rego index c8af8841..4f6aadea 100644 --- a/policies/triage_test.rego +++ b/policies/triage_test.rego @@ -254,3 +254,105 @@ test_observed_reachability_beats_not_reachable_mitigation if { }) d.irv_basis == "observed" } + +# ---- VER-TFR-IRI / VER-TFR-NRI: vulnerabilities treated as incidents ------------------ +iri_text := concat(" ", [ + "Providers with Class C Certifications SHOULD treat internet-reachable likely exploitable vulnerabilities", + "where Potential Agency Impact N-rating > 3 as a FedRAMP Reportable Incident", + "until they are partially mitigated vulnerabilities at N3 or below.", +]) + +nri_text := concat(" ", [ + "Providers with Class C Certifications MAY treat likely exploitable vulnerabilities that are NOT internet-reachable", + "where Potential Agency Impact N-rating = 5 as a FedRAMP Reportable Incident", + "until they are partially mitigated vulnerabilities at N4 or below.", +]) + +ver_rules(iri, nri) := {"FRR": {"VER": {"data": {"all": {"TFR": { + "VER-TFR-IRI": {"varies_by_class": {"c": {"statement": iri}}}, + "VER-TFR-NRI": nri, +}}}}}} + +good_ver := ver_rules(iri_text, {"varies_by_class": {"c": {"statement": nri_text}}}) + +vf := { + "tracking_id": "t1", "cve": "CVE-2099-0001", "pain": "N4", "internet_reachable": true, + "likely_exploitable": true, "fully_mitigated": false, "final_disposition": "open", + "first_evaluated": "2026-11-01T00:00:00+00:00", +} + +triggers(patch, r) := ts if { + ts := triage.incident_triggers with data.rules as r + with input as {"findings": [object.union(vf, patch)]} +} + +ierrs(findings, r) := es if { + es := triage.incident_errors with data.rules as r with input as {"findings": findings} +} + +test_iri_opens_above_n3 if { + ts := triggers({}, good_ver) + ts == [{ + "tracking_id": "t1", "cve": "CVE-2099-0001", "rule": "VER-TFR-IRI", "pain": "N4", + "first_evaluated": "2026-11-01T00:00:00+00:00", + }] + triggers({"pain": "N5"}, good_ver)[0].rule == "VER-TFR-IRI" +} + +test_iri_ends_at_n3_or_below if { + triggers({"pain": "N3"}, good_ver) == [] + triggers({"pain": "N1"}, good_ver) == [] +} + +test_nri_opens_only_at_n5 if { + triggers({"internet_reachable": false, "pain": "N5"}, good_ver)[0].rule == "VER-TFR-NRI" + triggers({"internet_reachable": false, "pain": "N4"}, good_ver) == [] +} + +test_not_likely_exploitable_never_triggers if { + triggers({"likely_exploitable": false, "pain": "N5"}, good_ver) == [] + triggers({"likely_exploitable": false, "internet_reachable": false, "pain": "N5"}, good_ver) == [] +} + +test_false_positive_and_fully_mitigated_never_trigger if { + triggers({"final_disposition": "false-positive", "pain": "N5"}, good_ver) == [] + triggers({"fully_mitigated": true, "pain": "N5"}, good_ver) == [] +} + +test_accepted_still_triggers if { + triggers({"final_disposition": "accepted", "pain": "N5"}, good_ver)[0].rule == "VER-TFR-IRI" +} + +test_missing_cve_is_null if { + ts := triage.incident_triggers with data.rules as good_ver + with input as {"findings": [object.remove(vf, ["cve", "first_evaluated"])]} + ts[0].cve == null + ts[0].first_evaluated == null +} + +test_rules_read_cleanly if { + ierrs([vf], good_ver) == set() +} + +test_changed_iri_text_fails_closed if { + es := ierrs([vf], ver_rules("treat them as incidents", {"statement": nri_text})) + "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" in es +} + +test_changed_nri_text_fails_closed if { + es := ierrs([vf], ver_rules(iri_text, {"statement": "treat them as incidents"})) + "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" in es +} + +test_non_complement_fails_closed if { + bad_iri := replace(iri_text, "at N3 or below", "at N2 or below") + bad_nri := replace(nri_text, "at N4 or below", "at N3 or below") + es := ierrs([vf], ver_rules(bad_iri, {"statement": bad_nri})) + "VER-TFR-IRI: the trigger and the 'until' level are not complements" in es + "VER-TFR-NRI: the trigger and the 'until' level are not complements" in es +} + +test_bad_rating_fails_closed if { + es := ierrs([object.union(vf, {"pain": "high"})], good_ver) + "t1: impact high is not an N-rating" in es +} diff --git a/scripts/_freshness.py b/scripts/_freshness.py index 8272426c..06024ef4 100644 --- a/scripts/_freshness.py +++ b/scripts/_freshness.py @@ -33,6 +33,7 @@ ".well-known/vdr-report.json", ".well-known/ksi-signal-runtime.json", ".well-known/vdr-status.json", + ".well-known/incident-reports.json", ".well-known/boundary-corroboration.json", ) diff --git a/scripts/_gates.py b/scripts/_gates.py index d9c48274..0335c57a 100644 --- a/scripts/_gates.py +++ b/scripts/_gates.py @@ -62,6 +62,7 @@ "reconcile.e": "G6", "reconcile.f": "G6", "reconcile.l": "G6", + "reconcile.m": "G5", "reconcile.i.unreadable": "G7", "runtime-divergence.observer-fault": "G7", "detection.zap.missing": "G7", diff --git a/scripts/_incidents.py b/scripts/_incidents.py new file mode 100644 index 00000000..14fd68c2 --- /dev/null +++ b/scripts/_incidents.py @@ -0,0 +1,412 @@ +"""The incident register: data/incidents.json (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR). + +Every incident the operator records lives here, once, with the evaluation the +FedRAMP Incident Evaluation and Communication rules ask for: + +- evaluation when it was evaluated, whether it is a FedRAMP Reportable + Incident (IEC-CSO-EFR) and why; the basis is IEC-CSO-EFR, or + VER-TFR-IRI / VER-TFR-NRI for a vulnerability treated as one +- estimates Incident Rating records (IEC-CSO-EFI): rating, customer effect, + one or several agencies, reason, when. Until the first one, a + reportable incident is rated at the default (IEC-CSO-DPR) +- reports the Initial, Ongoing and Final reports, each with when it was + issued and what it set; a report restates everything set before +- resolved_at / recovery_complete_at, which start the Final report's clock + +The clocks (when each report is due) come from FedRAMP's Class C timeframes +through scripts/_rules.py, never from this file. scripts/build-incident-report.py +renders the reports and the incident log from it; reconciliation checks the +findings an incident names against the VDR. + +Fails closed, stdlib only (the deploy job installs no jsonschema), following +scripts/_decisions.py: a missing or invalid register stops the build. The JSON +schema beside it (infrastructure/schemas/incidents.schema.json) documents the +same shape and is checked in tests. +""" + +import json +import re +import sys +from datetime import datetime, timedelta, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _redact # noqa: E402 +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +DEFAULT_PATH = REPO / "data" / "incidents.json" +SCHEMA_PATH = REPO / "infrastructure" / "schemas" / "incidents.schema.json" + +ID_RE = re.compile(r"^INC-\d{4}-\d{3}$") +DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +TS_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$") +CVE_RE = re.compile(r"^CVE-[0-9]{4}-[0-9]{4,}$") +EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)") +# Addresses a published report may name: the system's own domain and FedRAMP's. +EMAIL_DOMAINS = ("samaydlette.com", "fedramp.gov", "gsa.gov") + +BASES = ("IEC-CSO-EFR", "VER-TFR-IRI", "VER-TFR-NRI") +VULN_RULES = ("VER-TFR-IRI", "VER-TFR-NRI") +REPORT_TYPES = ("Initial", "Ongoing", "Final") +EFFECTS = ("minimal", "narrow", "disruptive", "debilitating") +AGENCY_SCOPES = ("single", "multiple") +# Delivery the pipeline performs. Only publication is built; sending to FedRAMP +# or an agency is the operator's decision and is not implemented. +NOTIFICATION_MODES = ("published-only",) + +TOP_KEYS = {"$comment", "schema", "policy", "incidents"} +POLICY_KEYS = {"federal_incident_coordinator", "notification", "notification_text", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by"} +INCIDENT_KEYS = {"id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", + "findings", "estimates", "reports", "resolved_at", "recovery_complete_at"} +EVALUATION_KEYS = {"evaluated_at", "reportable", "basis", "reason", "federal_customer_data_considered"} +ESTIMATE_KEYS = {"estimated_at", "rating", "customer_effect", "agencies", "reason"} +REPORT_KEYS = {"type", "at", "set"} +# What a report can set, by the field it fills in the FedRAMP incident report. +TEXT_FIELDS = { + "description": "incidentDescription", + "functional_impact": "functionalImpact", + "recovery_plan": "recoveryPlan", + "observed_activity": "observedActivity", + "root_cause": "rootCause", + "response_and_recovery_activities": "responseAndRecoveryActivities", +} +LIST_FIELDS = { + "affected_agencies": "affectedAgencies", + "indicators_of_compromise": "indicatorsOfCompromise", + "related_cves": "relatedCveIds", +} +SET_KEYS = set(TEXT_FIELDS) | set(LIST_FIELDS) | {"milestones"} +MILESTONE_KEYS = {"at", "description"} + + +def _fail(msg): + raise SystemExit(f"::error::incident register: {msg} (fail-closed)") + + +def parse_ts(value, where): + """An aware datetime from an ISO 8601 timestamp with an offset, or fail.""" + if not isinstance(value, str) or not TS_RE.match(value): + _fail(f"{where} must be an ISO 8601 timestamp with a UTC offset, got {value!r}") + try: + return datetime.fromisoformat(value.replace("Z", "+00:00")) + except ValueError: + _fail(f"{where} is not a valid timestamp: {value!r}") + + +def _text(value, where): + if not isinstance(value, str) or not value.strip(): + _fail(f"{where} must be a non-empty string") + return value + + +def _strings(value, where, pattern=None): + if not isinstance(value, list) or not all(isinstance(x, str) and x.strip() for x in value): + _fail(f"{where} must be a list of non-empty strings") + if pattern is not None: + for x in value: + if not pattern.match(x): + _fail(f"{where}: {x!r} does not match {pattern.pattern}") + if len(set(value)) != len(value): + _fail(f"{where} lists an entry twice") + return value + + +def _published_text_ok(doc, where): + """Everything in the register is published: no AWS account ID, and no email + address outside the system's domain and FedRAMP's.""" + text = json.dumps(doc) + if _redact.find(text): + _fail(f"{where} contains an AWS account ID; the register is published") + for m in EMAIL_RE.finditer(text): + if not m.group(1).lower().endswith(EMAIL_DOMAINS): + _fail(f"{where} names an email address outside {', '.join(EMAIL_DOMAINS)}; the register is published") + + +def _validate_policy(p, where): + if not isinstance(p, dict) or set(p) - POLICY_KEYS or POLICY_KEYS - set(p): + _fail(f"{where}.policy must have exactly {sorted(POLICY_KEYS)}") + for k in ("federal_incident_coordinator", "notification_text", "decided_by"): + _text(p[k], f"{where}.policy.{k}") + for k in ("decided_on", "review_by"): + if not isinstance(p[k], str) or not DATE_RE.match(p[k]): + _fail(f"{where}.policy.{k} must be an ISO date") + if p["notification"] not in NOTIFICATION_MODES: + _fail(f"{where}.policy.notification {p['notification']!r} is not one of {list(NOTIFICATION_MODES)}; " + f"no other delivery is built") + adopted = _strings(p["adopted_vulnerability_rules"], f"{where}.policy.adopted_vulnerability_rules") + if set(adopted) - set(VULN_RULES): + _fail(f"{where}.policy.adopted_vulnerability_rules may name only {list(VULN_RULES)}") + _text(p["federal_customer_data"], f"{where}.policy.federal_customer_data") + + +def _validate_estimate(e, where, rubric, floor): + if not isinstance(e, dict) or set(e) != ESTIMATE_KEYS: + _fail(f"{where} must have exactly {sorted(ESTIMATE_KEYS)}") + at = parse_ts(e["estimated_at"], f"{where}.estimated_at") + if at < floor: + _fail(f"{where}.estimated_at is before the incident was detected") + if e["customer_effect"] not in EFFECTS or e["agencies"] not in AGENCY_SCOPES: + _fail(f"{where}: customer_effect must be one of {list(EFFECTS)} and agencies one of {list(AGENCY_SCOPES)}") + want = rubric[(e["customer_effect"], e["agencies"])] + if e["rating"] != want or isinstance(e["rating"], bool): + _fail(f"{where}: a likely {e['customer_effect']} effect on {e['agencies']} agenc" + f"{'y' if e['agencies'] == 'single' else 'ies'} is N{want} under IEC-CSO-EFI, not {e['rating']!r}") + _text(e["reason"], f"{where}.reason") + return at + + +def _validate_set(s, where): + if not isinstance(s, dict) or not s or set(s) - SET_KEYS: + _fail(f"{where}.set must be a non-empty object with only {sorted(SET_KEYS)}") + for k in TEXT_FIELDS: + if k in s: + _text(s[k], f"{where}.set.{k}") + for k in LIST_FIELDS: + if k in s: + _strings(s[k], f"{where}.set.{k}", CVE_RE if k == "related_cves" else None) + milestones = s.get("milestones", []) + if not isinstance(milestones, list): + _fail(f"{where}.set.milestones must be a list") + for i, m in enumerate(milestones): + if not isinstance(m, dict) or set(m) != MILESTONE_KEYS: + _fail(f"{where}.set.milestones[{i}] must have exactly {sorted(MILESTONE_KEYS)}") + parse_ts(m["at"], f"{where}.set.milestones[{i}].at") + _text(m["description"], f"{where}.set.milestones[{i}].description") + + +def _validate_incident(inc, where, policy, rubric, now): + rid = inc.get("id") if isinstance(inc, dict) else None + if not isinstance(rid, str) or not ID_RE.match(rid): + _fail(f"{where}: incident id {rid!r} is not INC-YYYY-NNN") + where = rid + required = {"id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", + "estimates", "reports"} + if set(inc) - INCIDENT_KEYS or required - set(inc): + _fail(f"{where}: unknown field(s) {sorted(set(inc) - INCIDENT_KEYS)}, missing {sorted(required - set(inc))}") + _text(inc["title"], f"{where}.title") + _text(inc["detection_source"], f"{where}.detection_source") + if not isinstance(inc["exercise"], bool): + _fail(f"{where}.exercise must be true or false") + started = parse_ts(inc["started_at"], f"{where}.started_at") + detected = parse_ts(inc["detected_at"], f"{where}.detected_at") + if detected < started: + _fail(f"{where}: detected before it started") + + ev = inc["evaluation"] + if not isinstance(ev, dict) or set(ev) != EVALUATION_KEYS: + _fail(f"{where}.evaluation must have exactly {sorted(EVALUATION_KEYS)} (IEC-CSO-EFR: when, the " + f"determination, its basis and reason, and the federal customer data considered)") + evaluated = parse_ts(ev["evaluated_at"], f"{where}.evaluation.evaluated_at") + if evaluated < detected: + _fail(f"{where}: evaluated before it was detected") + if not isinstance(ev["reportable"], bool): + _fail(f"{where}.evaluation.reportable must be true or false") + _text(ev["reason"], f"{where}.evaluation.reason") + _text(ev["federal_customer_data_considered"], f"{where}.evaluation.federal_customer_data_considered") + if ev["basis"] not in BASES: + _fail(f"{where}.evaluation.basis must be one of {list(BASES)}") + findings = _strings(inc.get("findings", []), f"{where}.findings") + if ev["basis"] in VULN_RULES: + if ev["basis"] not in policy["adopted_vulnerability_rules"]: + _fail(f"{where}: basis {ev['basis']} is not an adopted rule in policy.adopted_vulnerability_rules") + if not ev["reportable"]: + _fail(f"{where}: a vulnerability treated as a FedRAMP Reportable Incident under {ev['basis']} is reportable") + if not findings: + _fail(f"{where}: basis {ev['basis']} names no finding") + + if not isinstance(inc["estimates"], list) or not isinstance(inc["reports"], list): + _fail(f"{where}: estimates and reports must be lists") + if not ev["reportable"] and (inc["estimates"] or inc["reports"]): + _fail(f"{where}: not a FedRAMP Reportable Incident, so it carries no rating or report") + last = detected + for i, e in enumerate(inc["estimates"]): + at = _validate_estimate(e, f"{where}.estimates[{i}]", rubric, detected) + if at < last: + _fail(f"{where}.estimates are not in time order") + last = at + + resolved = parse_ts(inc["resolved_at"], f"{where}.resolved_at") if "resolved_at" in inc else None + recovered = (parse_ts(inc["recovery_complete_at"], f"{where}.recovery_complete_at") + if "recovery_complete_at" in inc else None) + if recovered and not resolved: + _fail(f"{where}: recovery is complete but the incident is not resolved") + if resolved and resolved < detected or recovered and resolved and recovered < resolved: + _fail(f"{where}: resolved_at / recovery_complete_at are out of order") + + reports = inc["reports"] + prev = evaluated + for i, r in enumerate(reports): + w = f"{where}.reports[{i}]" + if not isinstance(r, dict) or set(r) - REPORT_KEYS or {"type", "at"} - set(r): + _fail(f"{w} must have type, at and optionally set") + if r["type"] not in REPORT_TYPES: + _fail(f"{w}.type must be one of {list(REPORT_TYPES)}") + want = "Initial" if i == 0 else None + if want and r["type"] != want: + _fail(f"{where}: the first report is the Initial Incident Report (IEC-CSO-IIR)") + if i > 0 and r["type"] == "Initial": + _fail(f"{where}: only the first report is Initial") + if r["type"] == "Final" and i != len(reports) - 1: + _fail(f"{where}: nothing follows the Final Incident Report") + at = parse_ts(r["at"], f"{w}.at") + if at < prev: + _fail(f"{w}.at is before the evaluation or the previous report") + prev = at + if "set" in r: + _validate_set(r["set"], w) + elif r["type"] == "Initial": + _fail(f"{w}: the Initial report sets at least the description") + if reports and "description" not in reports[0].get("set", {}): + _fail(f"{where}: the Initial report must describe the incident (IEC-CSO-IIR)") + if reports and reports[-1]["type"] == "Final": + if not recovered: + _fail(f"{where}: a Final Incident Report needs resolved_at and recovery_complete_at (IEC-CSO-FIR)") + if parse_ts(reports[-1]["at"], "") < recovered: + _fail(f"{where}: the Final report is dated before recovery completed") + + if now is not None: + stamps = [started, detected, evaluated, resolved, recovered] + stamps += [parse_ts(e["estimated_at"], "") for e in inc["estimates"]] + stamps += [parse_ts(r["at"], "") for r in reports] + if any(t and t > now for t in stamps): + _fail(f"{where} records a time after now; a report cannot be issued in the future") + + +def validate(doc, where="data/incidents.json", now=None, rules_dir=_rules.RULES_DIR): + """Structural and rule checks, enforced at build time without a jsonschema + dependency. `now` (aware datetime), when given, also refuses future times.""" + if not isinstance(doc, dict) or doc.get("schema") != "incidents/1": + _fail(f"{where} is not an incidents/1 document") + if set(doc) - TOP_KEYS or {"schema", "policy", "incidents"} - set(doc): + _fail(f"{where}: top-level fields must be {sorted(TOP_KEYS)}") + _validate_policy(doc["policy"], where) + if not isinstance(doc["incidents"], list): + _fail(f"{where}: incidents must be a list") + rubric = _rules.incident_rating_rubric(rules_dir) + seen = set() + for i, inc in enumerate(doc["incidents"]): + _validate_incident(inc, f"{where} incidents[{i}]", doc["policy"], rubric, now) + if inc["id"] in seen: + _fail(f"{where}: duplicate id {inc['id']}") + seen.add(inc["id"]) + _published_text_ok(doc, where) + return doc + + +def load(path=None, now=None, rules_dir=_rules.RULES_DIR): + p = Path(path) if path else DEFAULT_PATH + if not p.is_file(): + _fail(f"{p} not found") + try: + doc = json.loads(p.read_text()) + except (json.JSONDecodeError, UnicodeDecodeError) as exc: + _fail(f"{p} is not valid JSON: {exc}") + return validate(doc, str(p), now=now, rules_dir=rules_dir) + + +# ---- ratings and clocks ------------------------------------------------------- + +def add_clock(start, unit, n): + """`start` plus n hours, or n business days. A business day here is Monday to + Friday in UTC; federal holidays are counted as business days, which can only + make a deadline earlier, never later.""" + if unit == "hours": + return start + timedelta(hours=n) + if unit == "bizdays": + t, left = start.astimezone(timezone.utc), n + while left: + t += timedelta(days=1) + if t.weekday() < 5: + left -= 1 + return t + _fail(f"unknown clock unit {unit!r}") + + +def rating_at(inc, t, default): + """(N-rating, basis) in force at time t: the latest Incident Rating estimate + made by then (IEC-CSO-EFI), else the default (IEC-CSO-DPR).""" + best = None + for e in inc["estimates"]: + if parse_ts(e["estimated_at"], "") <= t: + best = e + if best is None: + return default, "default (IEC-CSO-DPR)" + return best["rating"], f"estimated (IEC-CSO-EFI) at {best['estimated_at']}" + + +def rating_history(inc, default, until=None): + """[(when, rating, basis)] from evaluation through `until` (inclusive).""" + out = [(inc["evaluation"]["evaluated_at"], default, "default (IEC-CSO-DPR)")] + for e in inc["estimates"]: + if until is None or parse_ts(e["estimated_at"], "") <= until: + out.append((e["estimated_at"], e["rating"], f"estimated (IEC-CSO-EFI): {e['reason']}")) + return out + + +def _obligation(kind, due, report, index, now): + met_at = parse_ts(report["at"], "") if report else None + return {"report": kind, "due_at": due.isoformat(), "report_index": index, + "issued_at": report["at"] if report else None, + "on_time": (met_at <= due) if report else None, + "overdue": (report is None and now > due)} + + +def obligations(inc, timeframes, default, now): + """Every report the Class C clocks call for, in order, and whether each was + issued by its deadline. The last entry with report_index None is the one + still due. Not reportable: no obligations.""" + if not inc["evaluation"]["reportable"]: + return [] + reports = inc["reports"] + resolved = parse_ts(inc["resolved_at"], "") if "resolved_at" in inc else None + recovered = parse_ts(inc["recovery_complete_at"], "") if "recovery_complete_at" in inc else None + evaluated = parse_ts(inc["evaluation"]["evaluated_at"], "") + + def due(kind, start): + return add_clock(start, *timeframes[kind][rating_at(inc, start, default)[0]]) + + out = [_obligation("Initial", due("iir", evaluated), reports[0] if reports else None, 0 if reports else None, now)] + if not reports: + return out + i, prev = 1, parse_ts(reports[0]["at"], "") + while True: + oir_due = due("oir", prev) + if resolved is not None and resolved <= oir_due: + # Resolved before the next Ongoing report fell due: any further + # Ongoing reports are voluntary, and the Final report's clock starts + # when recovery completes (IEC-CSO-FIR). + while i < len(reports) and reports[i]["type"] == "Ongoing": + i += 1 + if recovered is not None: + final = reports[i] if i < len(reports) else None + out.append(_obligation("Final", due("fir", recovered), final, i if final else None, now)) + return out + nxt = reports[i] if i < len(reports) and reports[i]["type"] == "Ongoing" else None + out.append(_obligation("Ongoing", oir_due, nxt, i if nxt else None, now)) + if nxt is None: + return out + prev, i = parse_ts(nxt["at"], ""), i + 1 + + +def status(inc): + if not inc["evaluation"]["reportable"]: + return "not-reportable" + if inc["reports"] and inc["reports"][-1]["type"] == "Final": + return "closed" + if "resolved_at" in inc: + return "resolved" + return "open" + + +def open_findings(reg, include_exercises=False): + """{finding or CVE: incident id} named by incidents that are not yet resolved.""" + out = {} + for inc in reg["incidents"]: + if inc["exercise"] and not include_exercises: + continue + if status(inc) == "open": + for f in inc.get("findings", []): + out[f] = inc["id"] + return out diff --git a/scripts/_rules.py b/scripts/_rules.py index ed703e1c..26bb5ebe 100644 --- a/scripts/_rules.py +++ b/scripts/_rules.py @@ -9,6 +9,7 @@ import hashlib import json +import re from functools import lru_cache from pathlib import Path @@ -188,3 +189,83 @@ def applicable_provider_rules(rules_dir=RULES_DIR): if not out: _fail("no provider rules apply; the applicability metadata has changed shape") return out + + +# ---- Incident Evaluation and Communication (IEC), Class C --------------------- +# The report clocks and the Incident Rating scale are FedRAMP's, read here from +# the pinned corpus like the remediation matrix above, never typed in. + +INCIDENT_REPORTS = {"iir": "IEC-CSO-IIR", "oir": "IEC-CSO-OIR", "fir": "IEC-CSO-FIR"} +_CLOCK_UNITS = ("hours", "bizdays") + + +def _iec(rules, rule_id): + try: + return rules["FRR"]["IEC"]["data"]["all"]["CSO"][rule_id] + except (KeyError, TypeError): + _fail(f"{rule_id} not found at FRR/IEC/data/all/CSO") + + +def incident_report_timeframes(rules_dir=RULES_DIR): + """{"iir"|"oir"|"fir": {1..5: (unit, n)}} for Class C, unit "hours" or + "bizdays". Every impact level must carry every clock: a report with no + deadline cannot be alarmed.""" + rules, _ = load_rules(rules_dir) + out = {} + for kind, rid in INCIDENT_REPORTS.items(): + try: + table = _iec(rules, rid)["varies_by_class"][CERT_CLASS]["pain_timeframes"] + except (KeyError, TypeError): + _fail(f"{rid} has no Class {CERT_CLASS.upper()} pain_timeframes") + clocks = {} + for n in ("1", "2", "3", "4", "5"): + cell = (table.get(n) or {}).get(kind) + if not isinstance(cell, dict) or cell.get("timeframe_type") not in _CLOCK_UNITS \ + or not isinstance(cell.get("timeframe_num"), int) or isinstance(cell["timeframe_num"], bool) \ + or cell["timeframe_num"] <= 0: + _fail(f"{rid} Class C N{n} {kind} is not a positive number of hours or business days") + clocks[int(n)] = (cell["timeframe_type"], cell["timeframe_num"]) + out[kind] = clocks + return out + + +_RATING_RE = re.compile(r"^\*\*N([1-5])\*\* for (.+)\.$") +_CLAUSE_RE = re.compile(r"likely (minimal|narrow|disruptive|debilitating) customer effect on " + r"(1 or more agencies|more than 1 agency|1 agency)") +_SCOPES_BY_TEXT = {"1 or more agencies": ("single", "multiple"), "1 agency": ("single",), + "more than 1 agency": ("multiple",)} + + +def incident_rating_rubric(rules_dir=RULES_DIR): + """{(customer effect, "single"|"multiple" agencies): N-rating 1..5} from the + IEC-CSO-EFI bullets. Every (effect, scope) pair must be rated exactly once, + or the text has changed shape and the rubric is not trusted.""" + rules, _ = load_rules(rules_dir) + bullets = _iec(rules, "IEC-CSO-EFI").get("following_information_bullets") + if not isinstance(bullets, list) or not bullets: + _fail("IEC-CSO-EFI has no rating bullets") + out = {} + for b in bullets: + m = _RATING_RE.match(b) if isinstance(b, str) else None + clauses = _CLAUSE_RE.findall(m.group(2)) if m else [] + if not clauses: + _fail(f"IEC-CSO-EFI bullet {b!r} is not in the expected form") + for effect, scope_text in clauses: + for scope in _SCOPES_BY_TEXT[scope_text]: + if (effect, scope) in out: + _fail(f"IEC-CSO-EFI rates {effect}/{scope} twice") + out[(effect, scope)] = int(m.group(1)) + effects = ("minimal", "narrow", "disruptive", "debilitating") + if set(out) != {(e, s) for e in effects for s in ("single", "multiple")}: + _fail("IEC-CSO-EFI does not rate every customer effect for one and for several agencies") + return out + + +def default_incident_rating(rules_dir=RULES_DIR): + """IEC-CSO-DPR: the N-rating a FedRAMP Reportable Incident has until it is estimated.""" + rules, _ = load_rules(rules_dir) + stmt = _iec(rules, "IEC-CSO-DPR").get("statement", "") + m = re.search(r"\(PAIN\) of ([1-5])\b", stmt) + if not m: + _fail("IEC-CSO-DPR no longer states a default PAIN rating") + return int(m.group(1)) diff --git a/scripts/build-incident-report.py b/scripts/build-incident-report.py new file mode 100644 index 00000000..7c67def4 --- /dev/null +++ b/scripts/build-incident-report.py @@ -0,0 +1,413 @@ +#!/usr/bin/env python3 +# ============================================================================= +# INCIDENT REPORTS: IIR, OIR and FIR from the incident register +# ============================================================================= +# The incident register (data/incidents.json, read through scripts/_incidents.py) +# records each incident's FedRAMP reportability evaluation (IEC-CSO-EFR), its +# Incident Rating (IEC-CSO-EFI, or the IEC-CSO-DPR default) and the reports +# issued. This renders, for every FedRAMP Reportable Incident, each report in +# FedRAMP's 2026-06-24 incident report schema: +# +# incident---initial.json IEC-CSO-IIR +# incident---ongoing.json IEC-CSO-OIR (restates every earlier item) +# incident---final.json IEC-CSO-FIR (final values for every item) +# +# each validated before it is written (scripts/_fedramp_schema.py), plus the +# incident log: +# +# incident-reports.json every incident, its evaluation and reason, its rating +# history, each report (file, sha256, what changed) and +# each report clock (due, issued, on time) +# incident-reports.md the same, human-readable, with every report's content +# +# The clocks are FedRAMP's Class C timeframes, read through scripts/_rules.py. +# +# Vulnerabilities as incidents (VER-TFR-IRI, VER-TFR-NRI). Given the VDR report, +# policies/triage.rego names each finding a rule makes a FedRAMP Reportable +# Incident. One the operator has adopted that rule for and that no unresolved +# incident names is published as a trigger with no incident, its Initial +# report due from the finding's first evaluation at the default rating; the +# clock check fails, and the evidence watchdog pages, once that time passes. +# +# Notification. Delivery to FedRAMP and agencies is not built: the register's +# policy says "published-only" and every report says so. Publication under +# /.well-known/ is the only channel until the operator decides otherwise. +# +# build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . +# build-incident-report.py --check incident-reports.json # exit 1 if a report is overdue +# ============================================================================= + +import argparse +import hashlib +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _fedramp_schema as fs # noqa: E402 +import _incidents # noqa: E402 +import _rules # noqa: E402 + +INDEX = "incident-reports.json" +INDEX_MD = "incident-reports.md" +EXERCISE_PREFIX = "EXERCISE: a simulated incident; no real system, data or agency was affected. " + +# The items an Initial report carries (IEC-CSO-IIR) and the further items an +# Ongoing report adds (IEC-CSO-OIR), in the rules' order, by register field. +IIR_ITEMS = [("coordinator", "Federal incident response coordinator"), + ("tracking_id", "Provider tracking identifier"), + ("description", "Description of the incident"), + ("timeline", "Timeline"), + ("rating", "Potential Agency Impact N-rating (historical and current)"), + ("functional_impact", "Functional impact to federal agency customers"), + ("recovery_plan", "Estimated recovery plan, milestones and timelines"), + ("affected_agencies", "Likely affected customer agencies")] +OIR_ITEMS = [("observed_activity", "Observed incident activity"), + ("indicators_of_compromise", "Indicators of compromise"), + ("related_cves", "Related CVE identifiers"), + ("root_cause", "Root cause"), + ("response_and_recovery_activities", "Response and recovery activities")] + + +def _fail(msg): + raise SystemExit(f"::error::incident reports: {msg} (fail-closed)") + + +def _iso(dt): + return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") + + +def vulnerability_triggers(vdr): + """The VDR findings policies/triage.rego treats as FedRAMP Reportable Incidents.""" + import _triage + findings = [{k: f.get(k) for k in ("tracking_id", "cve", "pain", "internet_reachable", "likely_exploitable", + "fully_mitigated", "final_disposition", "first_evaluated")} + for f in vdr.get("findings", [])] + out = _triage.evaluate('{"triggers": data.vdr.triage.incident_triggers, ' + '"errors": data.vdr.triage.incident_errors}', {"findings": findings}) + if out.get("errors"): + _fail("; ".join(sorted(out["errors"]))) + if not isinstance(out.get("triggers"), list): + _fail("the triage policy returned no incident triggers") + return out["triggers"] + + +def _milestones(inc, upto, default): + """Every milestone known at `upto`: the register's, plus the ones the + register's own fields mark (evaluation, each rating, resolution, recovery).""" + ms = [] + for r in inc["reports"]: + if _incidents.parse_ts(r["at"], "") > upto: + break + ms += [(m["at"], m["description"]) for m in r.get("set", {}).get("milestones", [])] + ev = inc["evaluation"] + ms.append((ev["evaluated_at"], f"FedRAMP reportability evaluated ({ev['basis']}): reportable; " + f"rated N{default} by default (IEC-CSO-DPR)")) + for e in inc["estimates"]: + ms.append((e["estimated_at"], f"Incident Rating estimated N{e['rating']} (IEC-CSO-EFI)")) + for k, text in (("resolved_at", "Incident resolved"), ("recovery_complete_at", "Recovery complete")): + if k in inc: + ms.append((inc[k], text)) + known = [(at, d) for at, d in ms if _incidents.parse_ts(at, "") <= upto] + return [{"occurredAt": at, "milestoneDescription": d} + for at, d in sorted(known, key=lambda x: _incidents.parse_ts(x[0], ""))] + + +def _state(inc, k): + """The register fields as known after report k, and which report last set each.""" + state, set_by = {}, {} + for i, r in enumerate(inc["reports"][:k + 1]): + for key, val in r.get("set", {}).items(): + if key != "milestones": + state[key], set_by[key] = val, i + return state, set_by + + +def _rating_notes(inc, at, default): + rating, basis = _incidents.rating_at(inc, at, default) + hist = [f"N{r} from {when} ({b})" for when, r, b in _incidents.rating_history(inc, default, at)] + if basis.startswith("default"): + lead = (f"No Incident Rating estimate had been made; rated N{rating} by default as IEC-CSO-DPR requires.") + else: + e = [x for x in inc["estimates"] if _incidents.parse_ts(x["estimated_at"], "") <= at][-1] + scope = "one agency" if e["agencies"] == "single" else "more than one agency" + lead = (f"Estimated N{rating} under IEC-CSO-EFI: a likely {e['customer_effect']} customer effect on " + f"{scope}. {e['reason']}") + return rating, f"{lead} History: {'; '.join(hist)}." + + +def report_document(inc, k, policy, default): + """Report k of incident `inc` in the FedRAMP incident report schema. Every + item set by report k or earlier is restated with its latest value.""" + r = inc["reports"][k] + at = _incidents.parse_ts(r["at"], "") + state, _ = _state(inc, k) + rating, notes = _rating_notes(inc, at, default) + doc = { + "$schema": fs.stamp("incident"), + "certificationPackageOverviewUri": fs.CPO_URI, + "reportType": r["type"], + "providerTrackingId": inc["id"], + "federalIncidentCoordinator": policy["federal_incident_coordinator"], + "incidentDescription": (EXERCISE_PREFIX if inc["exercise"] else "") + state["description"], + "timeline": { + "startedAt": inc["started_at"], + "detectedAt": inc["detected_at"], + "detectionSource": inc["detection_source"], + "evaluationCompletedAt": inc["evaluation"]["evaluated_at"], + "milestones": _milestones(inc, at, default), + }, + "potentialImpact": { + "historicalRating": [n for _, n, _ in _incidents.rating_history(inc, default, at)], + "currentRating": rating, + "evaluationNotes": notes, + }, + } + for key, field in _incidents.TEXT_FIELDS.items(): + if key in state and key != "description": + doc[field] = state[key] + for key, field in _incidents.LIST_FIELDS.items(): + if key in state: + doc[field] = state[key] + if r["type"] == "Final": + doc["resolvedAt"] = inc["recovery_complete_at"] + return doc + + +def _changes(inc, k): + """{item: "updated" | "no update" | "not yet available"} for report k.""" + state, set_by = _state(inc, k) + out = {} + for key, _ in IIR_ITEMS + OIR_ITEMS: + if key in ("coordinator", "tracking_id"): + out[key] = "updated" if k == 0 else "no update" + elif key == "timeline": + out[key] = "updated" if k == 0 or inc["reports"][k].get("set", {}).get("milestones") else "no update" + elif key == "rating": + prev = _incidents.parse_ts(inc["reports"][k - 1]["at"], "") if k else None + now = _incidents.parse_ts(inc["reports"][k]["at"], "") + moved = k == 0 or any(prev < _incidents.parse_ts(e["estimated_at"], "") <= now for e in inc["estimates"]) + out[key] = "updated" if moved else "no update" + elif key not in state: + out[key] = "not yet available" + else: + out[key] = "updated" if set_by[key] == k else "no update" + return out + + +def build(reg, vdr, now, out_dir, rules_dir=_rules.RULES_DIR): + """Write every report and the incident log; return the log.""" + out_dir = Path(out_dir) + timeframes = _rules.incident_report_timeframes(rules_dir) + default = _rules.default_incident_rating(rules_dir) + policy = reg["policy"] + registry = fs.load_registry() + incidents, due = [], [] + for inc in reg["incidents"]: + reports = [] + for k, r in enumerate(inc["reports"]): + name = f"incident-{inc['id']}-{k + 1:02d}-{r['type'].lower()}.json" + fs.write_validated(report_document(inc, k, policy, default), "incident", out_dir / name, registry) + reports.append({"type": r["type"], "issued_at": r["at"], "file": name, + "sha256": hashlib.sha256((out_dir / name).read_bytes()).hexdigest(), + "changes": _changes(inc, k)}) + obligations = _incidents.obligations(inc, timeframes, default, now) + pending = [o for o in obligations if o["report_index"] is None] + for o in pending: + due.append({"incident": inc["id"], "finding": None, "report": o["report"], "due_at": o["due_at"], + "overdue": o["overdue"]}) + last = inc["reports"][-1]["at"] if inc["reports"] else inc["evaluation"]["evaluated_at"] + rating, basis = _incidents.rating_at(inc, _incidents.parse_ts(last, ""), default) + incidents.append({ + "id": inc["id"], "title": inc["title"], "exercise": inc["exercise"], + "status": _incidents.status(inc), + "detected_at": inc["detected_at"], "detection_source": inc["detection_source"], + "evaluation": inc["evaluation"], "findings": inc.get("findings", []), + "rating": ({"current": rating, "basis": basis, + "history": [{"from": w, "rating": n, "basis": b} + for w, n, b in _incidents.rating_history(inc, default)]} + if inc["evaluation"]["reportable"] else None), + "resolved_at": inc.get("resolved_at"), "recovery_complete_at": inc.get("recovery_complete_at"), + "reports": reports, "obligations": obligations, + "next_report_due_at": pending[0]["due_at"] if pending else None, + }) + + triggers = [] + covered = _incidents.open_findings(reg) + if vdr is not None: + for t in vulnerability_triggers(vdr): + adopted = t["rule"] in policy["adopted_vulnerability_rules"] + inc_id = covered.get(t["tracking_id"]) or (covered.get(t["cve"]) if t["cve"] else None) + entry = {**t, "adopted": adopted, "incident": inc_id} + triggers.append(entry) + if adopted and inc_id is None: + start = _incidents.parse_ts(t["first_evaluated"], "") if t["first_evaluated"] else now + unit, n = timeframes["iir"][default] + at = _incidents.add_clock(start, unit, n) + due.append({"incident": None, "finding": t["tracking_id"], "report": "Initial", + "due_at": at.isoformat(), "overdue": now > at}) + overdue = [d for d in due if d["overdue"]] + log = { + "schema": "incident-reports/1", + "emitted_at": _iso(now), + "generator": "scripts/build-incident-report.py", + "description": ("The incident log: every incident recorded in data/incidents.json, its FedRAMP " + "reportability evaluation and reason (IEC-CSO-EFR), its Incident Rating (IEC-CSO-EFI, " + "or the IEC-CSO-DPR default), each Initial, Ongoing and Final report issued, and each " + "Class C report clock. Exercises are marked exercise: true."), + "rules": _rules.pin(rules_dir), + "notification": {"mode": policy["notification"], "text": policy["notification_text"]}, + "policy": {k: policy[k] for k in ("federal_incident_coordinator", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by")}, + "vdr": ({"emitted_at": vdr.get("emitted_at"), "report_id": vdr.get("report_id")} if vdr is not None + else None), + "vulnerability_triggers": triggers, + "obligations_due": due, + "clock_status": "overdue" if overdue else "ok", + "summary": { + "incidents": len(incidents), + "reportable": sum(1 for i in incidents if i["evaluation"]["reportable"]), + "open": sum(1 for i in incidents if i["status"] in ("open", "resolved")), + "exercises": sum(1 for i in incidents if i["exercise"]), + "reports": sum(len(i["reports"]) for i in incidents), + "triggers_without_incident": sum(1 for t in triggers if t["adopted"] and t["incident"] is None), + "overdue": len(overdue), + }, + "incidents": incidents, + } + (out_dir / INDEX).write_text(json.dumps(log, indent=2) + "\n") + (out_dir / INDEX_MD).write_text(render_markdown(log, out_dir) + "\n") + return log + + +def _item_text(key, doc): + if key == "coordinator": + return doc["federalIncidentCoordinator"] + if key == "tracking_id": + return doc["providerTrackingId"] + if key == "description": + return doc["incidentDescription"] + if key == "timeline": + t = doc["timeline"] + lines = [f"started {t['startedAt']}; detected {t['detectedAt']} by {t['detectionSource']}; " + f"reportability evaluated {t['evaluationCompletedAt']}"] + lines += [f"{m['occurredAt']}: {m['milestoneDescription']}" for m in t["milestones"]] + return "\n".join(f" - {x}" for x in lines) + if key == "rating": + p = doc["potentialImpact"] + return f"N{p['currentRating']} (history {', '.join(f'N{n}' for n in p['historicalRating'])}). " \ + f"{p['evaluationNotes']}" + field = _incidents.TEXT_FIELDS.get(key) or _incidents.LIST_FIELDS.get(key) + val = doc.get(field) + if isinstance(val, list): + return ", ".join(val) if val else "none" + return val or "not yet available" + + +def render_markdown(log, out_dir): + s = log["summary"] + out = ["# Incident log and reports", "", + "_Generated by scripts/build-incident-report.py from data/incidents.json. The JSON beside this file " + "(incident-reports.json, signed) is the record; this is a rendering of it._", "", + f"- **Emitted:** {log['emitted_at']}", + f"- **Incidents:** {s['incidents']} ({s['reportable']} FedRAMP Reportable; {s['exercises']} exercises); " + f"**reports issued:** {s['reports']}; **overdue:** {s['overdue']}", + f"- **Notification:** {log['notification']['mode']}. {log['notification']['text']}", + f"- **Federal incident response coordinator:** {log['policy']['federal_incident_coordinator']}", + f"- **Vulnerabilities treated as incidents:** {', '.join(log['policy']['adopted_vulnerability_rules'])}", + ""] + out += ["## Vulnerabilities that are FedRAMP Reportable Incidents (VER-TFR-IRI / VER-TFR-NRI)", ""] + if log["vdr"] is None: + out += ["No VDR report was supplied to this build.", ""] + elif not log["vulnerability_triggers"]: + out += [f"None in the VDR report emitted {log['vdr']['emitted_at']}.", ""] + else: + out += ["| Finding | Rule | PAIN | Adopted | Incident |", "|---|---|---|---|---|"] + out += [f"| `{t['tracking_id']}` | {t['rule']} | {t['pain']} | {t['adopted']} | {t['incident'] or 'NONE'} |" + for t in log["vulnerability_triggers"]] + out.append("") + if log["obligations_due"]: + out += ["## Reports due", "", "| Incident / finding | Report | Due | Overdue |", "|---|---|---|---|"] + out += [f"| {d['incident'] or d['finding']} | {d['report']} | {d['due_at']} | {d['overdue']} |" + for d in log["obligations_due"]] + out.append("") + for entry in log["incidents"]: + ev = entry["evaluation"] + out += [f"## {entry['id']}: {entry['title']}" + (" (EXERCISE)" if entry["exercise"] else ""), "", + f"- **Status:** {entry['status']}", + f"- **Detected:** {entry['detected_at']} by {entry['detection_source']}", + f"- **Reportability (IEC-CSO-EFR, evaluated {ev['evaluated_at']}, basis {ev['basis']}):** " + f"{'FedRAMP Reportable Incident' if ev['reportable'] else 'not a FedRAMP Reportable Incident'}. " + f"{ev['reason']}", + f"- **Federal customer data considered:** {ev['federal_customer_data_considered']}"] + if entry["findings"]: + out.append(f"- **Findings named:** {', '.join(f'`{f}`' for f in entry['findings'])}") + if entry["rating"]: + out.append(f"- **Rating:** N{entry['rating']['current']} ({entry['rating']['basis']})") + if entry["obligations"]: + out += ["", "| Report | Due | Issued | On time |", "|---|---|---|---|"] + out += [f"| {o['report']} | {o['due_at']} | {o['issued_at'] or 'not yet'} | " + f"{'yes' if o['on_time'] else 'no' if o['on_time'] is False else ('OVERDUE' if o['overdue'] else 'pending')} |" + for o in entry["obligations"]] + out.append("") + for k, rep in enumerate(entry["reports"]): + doc = json.loads((Path(out_dir) / rep["file"]).read_text()) + out += [f"### {rep['type']} report, issued {rep['issued_at']} ({rep['file']})", "", + f"_Notification: {log['notification']['mode']}; see above._", ""] + items = IIR_ITEMS + (OIR_ITEMS if k else + [x for x in OIR_ITEMS if rep["changes"][x[0]] != "not yet available"]) + for key, label in items: + change = rep["changes"][key] + text = _item_text(key, doc) + sep = "\n" if text.startswith(" - ") else " " + out.append(f"- **{label}** ({change}):{sep}{text}") + if rep["type"] == "Final": + out.append(f"- **Resolved and recovered:** {doc['resolvedAt']}") + out.append("") + return "\n".join(out).rstrip() + + +def check(index_path, now): + """Exit status for the clock check: 1 when a report is due and missing.""" + log = json.loads(Path(index_path).read_text()) + late = [d for d in log.get("obligations_due", []) + if _incidents.parse_ts(d["due_at"], "obligations_due.due_at") < now] + for d in late: + who = d["incident"] or f"finding {d['finding']} (no incident opened)" + print(f"::error::{who}: the {d['report']} incident report was due at {d['due_at']} and has not been issued") + if not late: + print(f"incident report clocks: ok ({len(log.get('obligations_due', []))} report(s) pending, none overdue)") + return 1 if late else 0 + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--incidents", default=str(_incidents.DEFAULT_PATH)) + ap.add_argument("--vdr", default=None, help="the built VDR report, for VER-TFR-IRI/NRI triggers") + ap.add_argument("--out-dir", default=".") + ap.add_argument("--now", default=None, help="ISO 8601 time to evaluate the clocks at (default: now)") + ap.add_argument("--check", default=None, metavar="INDEX", + help="check a built incident-reports.json and exit 1 if a report is overdue") + a = ap.parse_args(argv) + now = _incidents.parse_ts(a.now, "--now") if a.now else datetime.now(timezone.utc) + if a.check: + return check(a.check, now) + reg = _incidents.load(a.incidents, now=now) + vdr = None + if a.vdr: + try: + vdr = json.loads(Path(a.vdr).read_text()) + except (OSError, json.JSONDecodeError) as exc: + _fail(f"cannot read the VDR report {a.vdr}: {exc}") + if not isinstance(vdr, dict) or not isinstance(vdr.get("findings"), list): + _fail(f"{a.vdr} is not a VDR report") + log = build(reg, vdr, now, a.out_dir) + s = log["summary"] + print(f"incident reports: {s['incidents']} incident(s), {s['reports']} report(s), " + f"{s['triggers_without_incident']} trigger(s) without an incident, clocks {log['clock_status']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-ksi-signal.py b/scripts/build-ksi-signal.py index 1d570b1c..08f2b07e 100755 --- a/scripts/build-ksi-signal.py +++ b/scripts/build-ksi-signal.py @@ -556,6 +556,9 @@ ("iam_role", "evidence_nightly"): { "function": "Nightly evidence workflow role", }, + ("iam_role", "incident_reports"): { + "function": "Incident reports workflow role (unattended IIR/OIR/FIR publication)", + }, ("object_store", "logs"): { "function": "Access-log bucket for the site bucket and CDN", "diagram_label": "S3 access-log bucket", diff --git a/scripts/build-ocr.py b/scripts/build-ocr.py index cad56d46..08f126ea 100644 --- a/scripts/build-ocr.py +++ b/scripts/build-ocr.py @@ -30,6 +30,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import _decisions # noqa: E402 +import _incidents # noqa: E402 QUARTER_DAYS = 91 @@ -50,7 +51,22 @@ def _scn_rows(path): return list(csv.DictReader(f)) -def build_ocr(vdr, decisions, scn_rows, signal_id, now): +def incident_summary(incidents, period_start): + """CCM-OCR-AVL item 7, from the incident register: the FedRAMP Reportable + Incidents detected this period, or an attestation of none. Exercises are + not incidents and are never counted.""" + log = "The incident log, /.well-known/incident-reports.json, records every incident evaluated, exercises included." + real = [i for i in (incidents or {}).get("incidents", []) + if not i["exercise"] and i["evaluation"]["reportable"] and i["detected_at"][:10] >= period_start] + if real: + return (f"{len(real)} FedRAMP Reportable Incident(s) this period: " + + "; ".join(f"{i['id']} ({_incidents.status(i)})" for i in real) + f". {log}") + return ("No FedRAMP Reportable Incidents occurred during this reporting period. The system holds " + "no federal customer data, so the IEC-CSO-EFR trigger does not apply; this is an " + f"attestation of none, not an omission. {log}") + + +def build_ocr(vdr, decisions, scn_rows, signal_id, now, incidents=None): period_start = (now - timedelta(days=QUARTER_DAYS)).date().isoformat() period_end = now.date().isoformat() @@ -97,10 +113,7 @@ def build_ocr(vdr, decisions, scn_rows, signal_id, now): "No new customer recommendations this period; the Secure Configuration " "Guidance at /.well-known/ remains current."], "agencies_using_product": [], # 6 (none) - "reportable_incidents_or_attestation": # 7 - "No FedRAMP Reportable Incidents occurred during this reporting period. " - "The system holds no federal customer data, so the IEC-CSO-EFR trigger " - "does not apply; this is an attestation of none, not an omission.", + "reportable_incidents_or_attestation": incident_summary(incidents, period_start), # 7 "lessons_learned_from_incidents": [], # 8 (none) }, "relationship_obligations_status": ( @@ -162,6 +175,7 @@ def main(): ap.add_argument("--vdr", default="vdr-report.json") ap.add_argument("--decisions", default="../data/decisions.json") ap.add_argument("--scn-register", default="../docs/scn/scn-register.csv") + ap.add_argument("--incidents", default="../data/incidents.json") ap.add_argument("--ksi-signal", default="ksi-signal.json") ap.add_argument("--output", default="ongoing-certification-report.json") ap.add_argument("--md-output", default="ongoing-certification-report.md") @@ -174,7 +188,7 @@ def main(): signal_id = sig.get("signal_id") if sig else None scn_rows = _scn_rows(a.scn_register) - report = build_ocr(vdr, decisions, scn_rows, signal_id, now) + report = build_ocr(vdr, decisions, scn_rows, signal_id, now, _incidents.load(a.incidents)) Path(a.output).write_text(json.dumps(report, indent=2) + "\n") if a.md_output: Path(a.md_output).write_text(render_markdown(report) + "\n") diff --git a/scripts/reconcile.py b/scripts/reconcile.py index 5f187a81..402194d3 100644 --- a/scripts/reconcile.py +++ b/scripts/reconcile.py @@ -42,6 +42,10 @@ # every boundary component of the inventory (no more, no # fewer), leaves none unclassified, and carries no ARN, # account ID or email address +# (m) incident findings — every finding or CVE an unresolved incident in the +# incident register (data/incidents.json) names is in +# this build's VDR report; exercises are exempt (their +# findings are simulated) # # Usage: # reconcile.py --artifacts-dir infrastructure [--live] [--expect-commit SHA] @@ -64,6 +68,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import _decisions # noqa: E402 import _gates # noqa: E402 +import _incidents # noqa: E402 import _redact # noqa: E402 REPO = Path(__file__).resolve().parent.parent @@ -525,9 +530,26 @@ def check_l_boundary_map(signal, boundary_map, expected_commit=None): return violations +def check_m_incident_findings(vdr, incidents): + """(m) Every finding an unresolved, non-exercise incident names (a VDR + tracking ID or a CVE ID) is in this build's VDR report. An incident about a + vulnerability the VDR does not carry is reporting on something the + vulnerability evidence says is not there: one of the two is wrong.""" + if incidents is None: + return [] + ids, cves = set(), set() + for f in _all_vdr_findings(vdr): + ids.add(f.get("tracking_id")) + if f.get("cve"): + cves.add(f["cve"]) + return [f"(m) incident {inc_id} names {ref!r}, which is not in the VDR report" + for ref, inc_id in sorted(_incidents.open_findings(incidents).items()) + if ref not in ids and ref not in cves] + + def run_all(signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, live_arns=None, expected_commit=None, live_tags=None, - boundary_map=None): + boundary_map=None, incidents=None): violations = [] violations += check_d_impact(signal, sdr, cpo, vdr, dashboard_html) violations += check_e_binding(signal, sdr, cpo, vdr) @@ -537,6 +559,7 @@ def run_all(signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, violations += check_h_finding_coverage(vdr, register) violations += check_j_decision_id_validity(signal, sdr, cpo, vdr, register) violations += check_l_boundary_map(signal, boundary_map, expected_commit) + violations += check_m_incident_findings(vdr, incidents) if live_arns is not None: violations += check_a_completeness(signal, live_arns) if live_tags is not None: @@ -562,6 +585,8 @@ def main(): help="path to .checkov.yaml (overridable for hermetic tests)") ap.add_argument("--decisions", default=str(_decisions.DEFAULT_PATH), help="the decision register (overridable for hermetic tests); missing or invalid fails closed") + ap.add_argument("--incidents", default=str(_incidents.DEFAULT_PATH), + help="the incident register (overridable for hermetic tests); missing or invalid fails closed") args = ap.parse_args() gates = _gates.load_gate_modes() @@ -583,6 +608,7 @@ def main(): dashboard_html = Path(args.dashboard).read_text() if Path(args.dashboard).exists() else None checkov_text = Path(args.checkov).read_text() register = _decisions.load(args.decisions) + incidents = _incidents.load(args.incidents) live_arns = None live_tags = None @@ -617,7 +643,7 @@ def main(): violations = run_all( signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, live_arns=live_arns, expected_commit=args.expect_commit, live_tags=live_tags, - boundary_map=boundary_map, + boundary_map=boundary_map, incidents=incidents, ) # Each violation names its invariant, "(x) ..."; its check's governed mode @@ -638,12 +664,12 @@ def main(): return 1 optional = ",l" if boundary_map is not None else "" if live_arns is not None and live_tags is not None: - checks = "a-f,h-j" + optional + checks = "a-f,h-j" + optional + ",m" elif live_arns is not None: - checks = "a-f,h,j" + optional + " (i deferred: no live tags)" + checks = "a-f,h,j" + optional + ",m (i deferred: no live tags)" else: - checks = "b-f,h,j" + optional + " (a,i deferred: no --live)" - print(f"reconciliation OK — invariants {checks} hold across signal/VDR/SDR/CPO/decisions/dashboard") + checks = "b-f,h,j" + optional + ",m (a,i deferred: no --live)" + print(f"reconciliation OK — invariants {checks} hold across signal/VDR/SDR/CPO/decisions/incidents/dashboard") if args.report: Path(args.report).write_text(json.dumps(build_report( signal, args.expect_commit, @@ -666,6 +692,7 @@ def main(): "j": "Every decision reference resolves", # (k) is retired: the bundle it bound is no longer published by this site. "l": "The boundary map describes exactly this build's inventory", + "m": "Every finding an open incident names is in the VDR report", } diff --git a/tests/fixtures/incidents/bad/duplicate-id.json b/tests/fixtures/incidents/bad/duplicate-id.json new file mode 100644 index 00000000..54fc3da0 --- /dev/null +++ b/tests/fixtures/incidents/bad/duplicate-id.json @@ -0,0 +1,74 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: two incidents share an ID", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + }, + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/empty-reason.json b/tests/fixtures/incidents/bad/empty-reason.json new file mode 100644 index 00000000..db9cbf11 --- /dev/null +++ b/tests/fixtures/incidents/bad/empty-reason.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the reportability determination states no reason", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": " ", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/evaluated-before-detected.json b/tests/fixtures/incidents/bad/evaluated-before-detected.json new file mode 100644 index 00000000..84050cc7 --- /dev/null +++ b/tests/fixtures/incidents/bad/evaluated-before-detected.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the evaluation is dated before detection", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T09:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/final-before-recovery.json b/tests/fixtures/incidents/bad/final-before-recovery.json new file mode 100644 index 00000000..8b094b83 --- /dev/null +++ b/tests/fixtures/incidents/bad/final-before-recovery.json @@ -0,0 +1,53 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a Final report with no recovery recorded", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Final", + "at": "2026-11-02T12:00:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/final-not-last.json b/tests/fixtures/incidents/bad/final-not-last.json new file mode 100644 index 00000000..67d2550e --- /dev/null +++ b/tests/fixtures/incidents/bad/final-not-last.json @@ -0,0 +1,62 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report follows the Final report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Final", + "at": "2026-11-02T12:00:00Z", + "set": { + "root_cause": "x" + } + }, + { + "type": "Ongoing", + "at": "2026-11-02T13:00:00Z", + "set": { + "root_cause": "y" + } + } + ], + "resolved_at": "2026-11-02T11:00:00Z", + "recovery_complete_at": "2026-11-02T11:10:00Z" + } + ] +} diff --git a/tests/fixtures/incidents/bad/first-not-initial.json b/tests/fixtures/incidents/bad/first-not-initial.json new file mode 100644 index 00000000..9dd86033 --- /dev/null +++ b/tests/fixtures/incidents/bad/first-not-initial.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the first report is not the Initial report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Ongoing", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/future-report.json b/tests/fixtures/incidents/bad/future-report.json new file mode 100644 index 00000000..e4e76502 --- /dev/null +++ b/tests/fixtures/incidents/bad/future-report.json @@ -0,0 +1,53 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report is dated after now (the test runs with now = 2026-11-03)", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Ongoing", + "at": "2026-11-04T00:00:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/initial-without-description.json b/tests/fixtures/incidents/bad/initial-without-description.json new file mode 100644 index 00000000..e50f60d6 --- /dev/null +++ b/tests/fixtures/incidents/bad/initial-without-description.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the Initial report does not describe the incident", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/not-evaluated.json b/tests/fixtures/incidents/bad/not-evaluated.json new file mode 100644 index 00000000..5814ef50 --- /dev/null +++ b/tests/fixtures/incidents/bad/not-evaluated.json @@ -0,0 +1,45 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the incident has no reportability reason (IEC-CSO-EFR)", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/not-reportable-with-report.json b/tests/fixtures/incidents/bad/not-reportable-with-report.json new file mode 100644 index 00000000..bff5c9f1 --- /dev/null +++ b/tests/fixtures/incidents/bad/not-reportable-with-report.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an incident evaluated as not reportable carries a report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": false, + "basis": "IEC-CSO-EFR", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/notification-sends.json b/tests/fixtures/incidents/bad/notification-sends.json new file mode 100644 index 00000000..1e40df8f --- /dev/null +++ b/tests/fixtures/incidents/bad/notification-sends.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the policy claims a delivery mode that is not built", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "email", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/personal-email.json b/tests/fixtures/incidents/bad/personal-email.json new file mode 100644 index 00000000..b1bdd4c1 --- /dev/null +++ b/tests/fixtures/incidents/bad/personal-email.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a published field names a personal email address", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "someone@example.org", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/rating-off-rubric.json b/tests/fixtures/incidents/bad/rating-off-rubric.json new file mode 100644 index 00000000..a40bbe99 --- /dev/null +++ b/tests/fixtures/incidents/bad/rating-off-rubric.json @@ -0,0 +1,54 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an estimate's rating is not the IEC-CSO-EFI rating for its effect and agency count", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [ + { + "estimated_at": "2026-11-02T11:00:00Z", + "rating": 2, + "customer_effect": "disruptive", + "agencies": "single", + "reason": "x" + } + ], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/report-before-evaluation.json b/tests/fixtures/incidents/bad/report-before-evaluation.json new file mode 100644 index 00000000..b1bee965 --- /dev/null +++ b/tests/fixtures/incidents/bad/report-before-evaluation.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report is dated before the evaluation", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T09:45:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/unknown-field.json b/tests/fixtures/incidents/bad/unknown-field.json new file mode 100644 index 00000000..6cf3e552 --- /dev/null +++ b/tests/fixtures/incidents/bad/unknown-field.json @@ -0,0 +1,47 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an incident carries a field the register does not define", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ], + "severity": "high" + } + ] +} diff --git a/tests/fixtures/incidents/bad/vuln-basis-no-finding.json b/tests/fixtures/incidents/bad/vuln-basis-no-finding.json new file mode 100644 index 00000000..03de43ae --- /dev/null +++ b/tests/fixtures/incidents/bad/vuln-basis-no-finding.json @@ -0,0 +1,44 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a VER-TFR-IRI incident names no finding", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json b/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json new file mode 100644 index 00000000..2cb36efc --- /dev/null +++ b/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the basis is VER-TFR-NRI, which the policy has not adopted", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-NRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/good.json b/tests/fixtures/incidents/good.json new file mode 100644 index 00000000..55c20493 --- /dev/null +++ b/tests/fixtures/incidents/good.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-GOOD FIXTURE: a minimal valid incident register (one open, reportable, non-exercise incident).", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/reconcile-m-bad.json b/tests/fixtures/incidents/reconcile-m-bad.json new file mode 100644 index 00000000..5c830fee --- /dev/null +++ b/tests/fixtures/incidents/reconcile-m-bad.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE for reconcile invariant (m): an open incident names CVE-2099-9999, which the VDR report fixture does not carry.", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-9999" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/test_evidence_watchdog.py b/tests/test_evidence_watchdog.py index 0bdd0e27..9ae0184d 100644 --- a/tests/test_evidence_watchdog.py +++ b/tests/test_evidence_watchdog.py @@ -55,6 +55,7 @@ def fresh_objects(): node[leaf] = FRESH objects[a["path"]] = doc objects[".well-known/vdr-status.json"] = status() + objects[".well-known/incident-reports.json"]["obligations_due"] = [] return objects @@ -287,3 +288,39 @@ def test_alarm_thresholds_and_reads_come_from_the_governed_config(): # No window is a literal in the watchdog any more. assert "MAX_BEACON_AGE_HOURS" not in logic assert not re.search(r"threshold\s*=\s*(24|26)\b", tf) + + +# ---- incident report deadlines (IEC-CSO-IIR/OIR/FIR) -------------------------------- + +def _incident_log(*due): + return {"emitted_at": FRESH, "obligations_due": [{"incident": "INC-2026-009", "report": "Ongoing", + "due_at": d} for d in due]} + + +def test_no_report_due_pages_nobody(): + out = compute(fresh_objects()) + assert out["metrics"]["IncidentReportsOverdue"] == 0 + + +def test_a_report_past_its_deadline_pages_even_while_the_log_is_fresh(): + objects = fresh_objects() + # NOW is 12:00. One report due at 11:00 has not been issued; one due at 13:00 is not late yet. + objects[".well-known/incident-reports.json"] = _incident_log("2026-09-25T11:00:00Z", "2026-09-25T13:00:00Z") + out = compute(objects) + assert out["metrics"]["IncidentReportsOverdue"] == 1 + assert out["metrics"]["StaleArtifacts"] == 0 + + +def test_a_missing_or_malformed_incident_log_is_a_breach_not_zero(): + objects = fresh_objects() + objects[".well-known/incident-reports.json"] = {"emitted_at": FRESH} + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + objects[".well-known/incident-reports.json"] = _incident_log("not a date") + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + del objects[".well-known/incident-reports.json"] + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + + +def test_the_incident_alarm_pages_on_the_first_overdue_report(): + tf = (REPO / "infrastructure" / "watchdog.tf").read_text() + assert 'metric = "IncidentReportsOverdue"\n threshold = 0' in tf diff --git a/tests/test_incidents.py b/tests/test_incidents.py new file mode 100644 index 00000000..5df3f472 --- /dev/null +++ b/tests/test_incidents.py @@ -0,0 +1,470 @@ +"""Incident evaluation and reporting (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR/AIR, +VER-TFR-IRI, VER-TFR-NRI). + +- the register (data/incidents.json) loads, matches its schema, and every + known-bad register fails closed for its own reason; +- the Class C report clocks and the Incident Rating scale are read from the + pinned FedRAMP rules, and a changed rule fails closed; +- the clocks: default N5 until estimated (DPR), the IIR/OIR/FIR deadlines, + business days, overdue detection; +- the exercise runs end to end, IIR -> OIR -> FIR, every report validates + against FedRAMP's schema, restates every earlier item and was on time; +- a VDR finding that VER-TFR-IRI/NRI makes reportable with no incident is due + an Initial report, and the clock check fails once it is late; +- reconciliation invariant (m) and the unattended reporting workflow. +""" + +import copy +import hashlib +import importlib.util +import json +import re +import shutil +import sys +from datetime import datetime, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO / "scripts")) +import _fedramp_schema as fs # noqa: E402 +import _incidents # noqa: E402 +import _rules # noqa: E402 + +FIX = REPO / "tests" / "fixtures" / "incidents" +REGISTER = REPO / "data" / "incidents.json" +SCHEMA = REPO / "infrastructure" / "schemas" / "incidents.schema.json" +RULES_DIR = REPO / "infrastructure" / "schemas" / "fedramp-rules" +WF = REPO / ".github" / "workflows" +NOW = datetime(2026, 11, 3, tzinfo=timezone.utc) + + +def _load(name, rel): + spec = importlib.util.spec_from_file_location(name, REPO / rel) + m = importlib.util.module_from_spec(spec) + spec.loader.exec_module(m) + return m + + +bir = _load("bir", "scripts/build-incident-report.py") +rec = _load("rec_incidents", "scripts/reconcile.py") + + +def ts(s): + return datetime.fromisoformat(s.replace("Z", "+00:00")) + + +def good(): + return json.loads((FIX / "good.json").read_text()) + + +# ---- the register ---------------------------------------------------------------- + +def test_the_committed_register_loads_and_matches_its_schema(): + _incidents.load(REGISTER, now=datetime.now(timezone.utc)) + jsonschema = pytest.importorskip("jsonschema") + jsonschema.validate(json.loads(REGISTER.read_text()), json.loads(SCHEMA.read_text())) + jsonschema.validate(good(), json.loads(SCHEMA.read_text())) + + +def test_the_committed_register_adopts_both_vulnerability_rules_and_publishes_only(): + """docs/policies/ir-policy.md adopts VER-TFR-NRI (a MAY) and IRI; nothing is sent.""" + p = json.loads(REGISTER.read_text())["policy"] + assert set(p["adopted_vulnerability_rules"]) == {"VER-TFR-IRI", "VER-TFR-NRI"} + assert p["notification"] == "published-only" + assert "not authorized" in p["notification_text"] + + +BAD = { + "not-evaluated": "evaluation must have exactly", + "empty-reason": "reason must be a non-empty string", + "rating-off-rubric": "is N3 under IEC-CSO-EFI", + "first-not-initial": "first report is the Initial Incident Report", + "initial-without-description": "must describe the incident", + "final-before-recovery": "needs resolved_at and recovery_complete_at", + "final-not-last": "nothing follows the Final Incident Report", + "not-reportable-with-report": "carries no rating or report", + "vuln-basis-not-adopted": "is not an adopted rule", + "vuln-basis-no-finding": "names no finding", + "evaluated-before-detected": "evaluated before it was detected", + "report-before-evaluation": "before the evaluation or the previous report", + "notification-sends": "no other delivery is built", + "personal-email": "names an email address outside", + "unknown-field": "unknown field", + "duplicate-id": "duplicate id", + "future-report": "records a time after now", +} + + +def test_every_known_bad_fixture_is_listed(): + assert {p.stem for p in (FIX / "bad").glob("*.json")} == set(BAD) + + +@pytest.mark.parametrize("name,why", sorted(BAD.items())) +def test_each_known_bad_register_fails_closed_for_its_reason(name, why): + _incidents.load(FIX / "good.json", now=NOW) # the base it was made from is valid + with pytest.raises(SystemExit) as exc: + _incidents.load(FIX / "bad" / f"{name}.json", now=NOW) + assert why in str(exc.value), str(exc.value) + + +@pytest.mark.parametrize("name", ["not-evaluated", "empty-reason", "notification-sends", "unknown-field"]) +def test_the_schema_refuses_the_structural_ones(name): + jsonschema = pytest.importorskip("jsonschema") + with pytest.raises(jsonschema.ValidationError): + jsonschema.validate(json.loads((FIX / "bad" / f"{name}.json").read_text()), json.loads(SCHEMA.read_text())) + + +def test_a_missing_or_unparseable_register_fails_closed(tmp_path): + with pytest.raises(SystemExit): + _incidents.load(tmp_path / "absent.json") + (tmp_path / "x.json").write_text("{") + with pytest.raises(SystemExit): + _incidents.load(tmp_path / "x.json") + + +# ---- rules as data -------------------------------------------------------------- + +def _corpus(): + return json.loads((RULES_DIR / "fedramp-consolidated-rules.json").read_text()) + + +def test_report_clocks_equal_the_pinned_rules(): + cso = _corpus()["FRR"]["IEC"]["data"]["all"]["CSO"] + got = _rules.incident_report_timeframes(RULES_DIR) + for kind, rid in (("iir", "IEC-CSO-IIR"), ("oir", "IEC-CSO-OIR"), ("fir", "IEC-CSO-FIR")): + table = cso[rid]["varies_by_class"]["c"]["pain_timeframes"] + assert got[kind] == {int(n): (c[kind]["timeframe_type"], c[kind]["timeframe_num"]) for n, c in table.items()} + # The Class C values the reports rely on, as published on 2026-06-24. + assert got["iir"][5] == ("hours", 1) and got["oir"][5] == ("hours", 6) and got["fir"][1] == ("bizdays", 1) + + +def test_rating_scale_and_default_come_from_the_rules(): + rubric = _rules.incident_rating_rubric(RULES_DIR) + assert rubric[("debilitating", "multiple")] == 5 and rubric[("disruptive", "multiple")] == 4 + assert rubric[("debilitating", "single")] == 4 and rubric[("minimal", "single")] == 1 + assert _rules.default_incident_rating(RULES_DIR) == 5 + + +def test_no_clock_is_typed_into_the_incident_code(): + for rel in ("scripts/_incidents.py", "scripts/build-incident-report.py"): + src = (REPO / rel).read_text() + assert not re.search(r"timedelta\(hours=(1|6|24)\)", src), rel + + +def _mutated_rules(tmp_path, mutate): + d = tmp_path / "rules" + d.mkdir() + corpus = _corpus() + mutate(corpus) + raw = json.dumps(corpus).encode() + (d / "fedramp-consolidated-rules.json").write_bytes(raw) + src = json.loads((RULES_DIR / "SOURCES.json").read_text()) + src["sha256"] = hashlib.sha256(raw).hexdigest() + (d / "SOURCES.json").write_text(json.dumps(src)) + return d + + +def test_a_changed_rating_scale_fails_closed(tmp_path): + def drop(c): + c["FRR"]["IEC"]["data"]["all"]["CSO"]["IEC-CSO-EFI"]["following_information_bullets"].pop() + with pytest.raises(SystemExit, match="does not rate every customer effect"): + _rules.incident_rating_rubric(_mutated_rules(tmp_path, drop)) + + +def test_a_missing_report_clock_fails_closed(tmp_path): + def drop(c): + c["FRR"]["IEC"]["data"]["all"]["CSO"]["IEC-CSO-OIR"]["varies_by_class"]["c"]["pain_timeframes"]["5"] = {} + with pytest.raises(SystemExit, match="IEC-CSO-OIR Class C N5 oir"): + _rules.incident_report_timeframes(_mutated_rules(tmp_path, drop)) + + +# ---- clocks (IEC-CSO-DPR, IIR, OIR, FIR) ------------------------------------------ + +TF = _rules.incident_report_timeframes(RULES_DIR) + + +def _open(evaluated="2026-11-02T10:00:00Z", reports=(), estimates=()): + inc = copy.deepcopy(good()["incidents"][0]) + inc["evaluation"]["evaluated_at"] = evaluated + inc["reports"] = list(reports) + inc["estimates"] = list(estimates) + return inc + + +def test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour(): + inc = _open() + assert _incidents.rating_at(inc, ts("2026-11-02T10:00:00Z"), 5) == (5, "default (IEC-CSO-DPR)") + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-02T10:30:00Z")) + assert o["report"] == "Initial" and o["due_at"] == "2026-11-02T11:00:00+00:00" and not o["overdue"] + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-02T11:01:00Z")) + assert o["overdue"] + + +def test_a_prompt_estimate_replaces_the_default_and_its_clock(): + est = {"estimated_at": "2026-11-06T10:00:00Z", "rating": 1, "customer_effect": "minimal", + "agencies": "single", "reason": "x"} + # Evaluated on a Friday, rated N1 at once: one business day, so Monday. + inc = _open(evaluated="2026-11-06T10:00:00Z", estimates=[est]) + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-06T12:00:00Z")) + assert o["due_at"] == "2026-11-09T10:00:00+00:00" + + +def test_business_days_skip_the_weekend(): + assert _incidents.add_clock(ts("2026-11-06T23:00:00Z"), "bizdays", 1) == ts("2026-11-09T23:00:00Z") + assert _incidents.add_clock(ts("2026-11-04T08:00:00Z"), "bizdays", 1) == ts("2026-11-05T08:00:00Z") + + +def test_ongoing_reports_are_due_every_oir_period_until_resolved(): + reports = [{"type": "Initial", "at": "2026-11-02T10:30:00Z", "set": {"description": "d"}}] + obs = _incidents.obligations(_open(reports=reports), TF, 5, ts("2026-11-02T17:00:00Z")) + assert [o["report"] for o in obs] == ["Initial", "Ongoing"] + assert obs[1]["due_at"] == "2026-11-02T16:30:00+00:00" and obs[1]["overdue"] + + +def test_the_final_report_is_due_after_recovery_and_ongoing_reports_stop(): + inc = _open(reports=[{"type": "Initial", "at": "2026-11-02T10:30:00Z", "set": {"description": "d"}}]) + inc["resolved_at"], inc["recovery_complete_at"] = "2026-11-02T12:00:00Z", "2026-11-02T13:00:00Z" + obs = _incidents.obligations(inc, TF, 5, ts("2026-11-02T20:00:00Z")) + assert [o["report"] for o in obs] == ["Initial", "Final"] + assert obs[1]["due_at"] == "2026-11-02T19:00:00+00:00" and obs[1]["overdue"] + + +def test_a_not_reportable_incident_has_no_clock(): + inc = _open() + inc["evaluation"]["reportable"] = False + assert _incidents.obligations(inc, TF, 5, NOW) == [] + + +# ---- the exercise, end to end (IIR -> OIR -> FIR) --------------------------------- + +@pytest.fixture(scope="module") +def exercise(tmp_path_factory): + out = tmp_path_factory.mktemp("incident-reports") + reg = _incidents.load(REGISTER, now=ts("2026-11-05T19:00:00Z")) + log = bir.build(reg, None, ts("2026-11-05T19:00:00Z"), out) + return reg, log, out + + +def test_exercise_runs_initial_ongoing_final_all_on_time(exercise): + _, log, _ = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-001") + assert inc["exercise"] is True and inc["status"] == "closed" + assert [r["type"] for r in inc["reports"]] == ["Initial", "Ongoing", "Ongoing", "Final"] + assert [o["report"] for o in inc["obligations"]] == ["Initial", "Ongoing", "Ongoing", "Final"] + assert all(o["on_time"] for o in inc["obligations"]) + assert log["obligations_due"] == [] and log["clock_status"] == "ok" + + +def test_exercise_shows_the_default_rating_then_the_estimate(exercise): + _, log, out = exercise + initial = json.loads((out / "incident-INC-2026-001-01-initial.json").read_text()) + final = json.loads((out / "incident-INC-2026-001-04-final.json").read_text()) + assert initial["potentialImpact"]["currentRating"] == 5 + assert "IEC-CSO-DPR" in initial["potentialImpact"]["evaluationNotes"] + assert final["potentialImpact"]["historicalRating"] == [5, 3] and final["potentialImpact"]["currentRating"] == 3 + assert initial["incidentDescription"].startswith("EXERCISE") + + +def test_exercise_logs_a_not_reportable_evaluation_with_its_reason(exercise): + _, log, _ = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-002") + assert inc["status"] == "not-reportable" and inc["reports"] == [] and inc["rating"] is None + assert "not federal customer data" in inc["evaluation"]["reason"] + + +def test_every_report_validates_against_fedramps_schema_and_is_listed_with_its_hash(exercise): + _, log, out = exercise + files = sorted(p.name for p in out.glob("incident-INC-*.json")) + listed = [r for i in log["incidents"] for r in i["reports"]] + assert sorted(r["file"] for r in listed) == files + for r in listed: + doc = json.loads((out / r["file"]).read_text()) + assert fs.validate(doc, "incident") == [] + assert hashlib.sha256((out / r["file"]).read_bytes()).hexdigest() == r["sha256"] + + +def test_ongoing_and_final_reports_restate_every_earlier_item(exercise): + _, log, out = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-001") + first = json.loads((out / inc["reports"][0]["file"]).read_text()) + for r in inc["reports"][1:]: + doc = json.loads((out / r["file"]).read_text()) + assert set(first) <= set(doc), r["file"] + # Every item is either updated or explicitly "no update". + assert set(r["changes"].values()) <= {"updated", "no update"}, r["changes"] + assert inc["reports"][2]["changes"]["root_cause"] == "no update" + assert inc["reports"][2]["changes"]["response_and_recovery_activities"] == "updated" + final = json.loads((out / inc["reports"][-1]["file"]).read_text()) + assert final["reportType"] == "Final" and final["resolvedAt"] == "2026-11-05T17:00:00Z" + + +def test_reports_are_deterministic_and_say_they_are_published_only(exercise, tmp_path): + reg, log, out = exercise + again = bir.build(reg, None, ts("2026-11-05T19:30:00Z"), tmp_path) + for a, b in zip(log["incidents"], again["incidents"], strict=True): + assert [r["sha256"] for r in a["reports"]] == [r["sha256"] for r in b["reports"]] + md = (out / "incident-reports.md").read_text() + assert "published-only" in md and "not authorized" in md and "(no update)" in md + assert log["notification"]["mode"] == "published-only" + + +def test_the_cli_builds_and_checks(tmp_path): + assert bir.main(["--incidents", str(REGISTER), "--out-dir", str(tmp_path), + "--now", "2026-11-05T19:00:00Z"]) == 0 + assert bir.main(["--check", str(tmp_path / "incident-reports.json"), "--now", "2026-11-05T19:00:00Z"]) == 0 + + +# ---- vulnerabilities as incidents (VER-TFR-IRI / VER-TFR-NRI) ---------------------- + +pytestmark_opa = pytest.mark.skipif(shutil.which("opa") is None, reason="opa not available") + + +def _vdr(**patch): + f = {"tracking_id": "grype-CVE-2099-0777-api", "cve": "CVE-2099-0777", "pain": "N4", + "internet_reachable": True, "likely_exploitable": True, "fully_mitigated": False, + "final_disposition": "open", "first_evaluated": "2026-11-02T10:00:00+00:00"} + f.update(patch) + return {"emitted_at": "2026-11-02T12:00:00+00:00", "report_id": "r", "findings": [f]} + + +def _empty_register(adopted=("VER-TFR-IRI", "VER-TFR-NRI")): + reg = good() + reg["incidents"] = [] + reg["policy"]["adopted_vulnerability_rules"] = list(adopted) + return _incidents.validate(reg) + + +@pytestmark_opa +def test_an_irv_lev_n4_finding_with_no_incident_is_due_an_initial_report(tmp_path): + log = bir.build(_empty_register(), _vdr(), ts("2026-11-02T10:30:00Z"), tmp_path) + (t,) = log["vulnerability_triggers"] + assert t["rule"] == "VER-TFR-IRI" and t["adopted"] and t["incident"] is None + (d,) = log["obligations_due"] + assert d["report"] == "Initial" and d["due_at"] == "2026-11-02T11:00:00+00:00" and not d["overdue"] + assert bir.check(tmp_path / "incident-reports.json", ts("2026-11-02T10:59:00Z")) == 0 + assert bir.check(tmp_path / "incident-reports.json", ts("2026-11-02T11:01:00Z")) == 1 + + +@pytestmark_opa +def test_an_nirv_lev_n5_finding_opens_under_nri_and_n4_does_not(tmp_path): + log = bir.build(_empty_register(), _vdr(internet_reachable=False, pain="N5"), NOW, tmp_path) + assert log["vulnerability_triggers"][0]["rule"] == "VER-TFR-NRI" + log = bir.build(_empty_register(), _vdr(internet_reachable=False, pain="N4"), NOW, tmp_path) + assert log["vulnerability_triggers"] == [] + + +@pytestmark_opa +def test_a_partially_mitigated_finding_at_n3_is_no_longer_an_incident(tmp_path): + log = bir.build(_empty_register(), _vdr(pain="N3"), NOW, tmp_path) + assert log["vulnerability_triggers"] == [] and log["obligations_due"] == [] + + +@pytestmark_opa +def test_an_unadopted_rule_is_shown_but_starts_no_clock(tmp_path): + log = bir.build(_empty_register(adopted=("VER-TFR-IRI",)), _vdr(internet_reachable=False, pain="N5"), + NOW, tmp_path) + assert log["vulnerability_triggers"][0]["adopted"] is False and log["obligations_due"] == [] + + +@pytestmark_opa +def test_an_open_incident_naming_the_finding_covers_it(tmp_path): + reg = good() + reg["incidents"][0]["findings"] = ["CVE-2099-0777"] + log = bir.build(_incidents.validate(reg), _vdr(), ts("2026-11-02T10:40:00Z"), tmp_path) + assert log["vulnerability_triggers"][0]["incident"] == "INC-2026-101" + assert [d["incident"] for d in log["obligations_due"]] == ["INC-2026-101"] # its next Ongoing report + + +# ---- reconciliation (m) ---------------------------------------------------------- + +def _cr26_vdr(): + return json.loads((REPO / "tests" / "fixtures" / "cr26" / "vdr-report.json").read_text()) + + +def test_reconcile_m_passes_when_every_named_finding_is_in_the_vdr(): + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(good())) == [] + + +def test_reconcile_m_fails_the_known_bad_register(): + reg = _incidents.load(FIX / "reconcile-m-bad.json") + v = rec.check_m_incident_findings(_cr26_vdr(), reg) + assert v == ["(m) incident INC-2026-101 names 'CVE-2099-9999', which is not in the VDR report"] + + +def test_reconcile_m_exempts_exercises_and_resolved_incidents(): + reg = json.loads((FIX / "reconcile-m-bad.json").read_text()) + reg["incidents"][0]["exercise"] = True + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(reg)) == [] + reg["incidents"][0]["exercise"] = False + reg["incidents"][0]["resolved_at"] = "2026-11-02T11:00:00Z" + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(reg)) == [] + + +def test_reconcile_m_holds_for_the_committed_register(): + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.load(REGISTER)) == [] + + +# ---- the unattended reporting workflow (IEC-CSO-AIR) -------------------------------- + +def _wf(): + return (WF / "incident-reports.yml").read_text() + + +def test_air_workflow_runs_on_register_change_by_hand_and_on_a_schedule(): + yaml = pytest.importorskip("yaml") + on = yaml.safe_load(_wf())[True] + assert on["push"]["paths"] == ["data/incidents.json"] and on["push"]["branches"] == ["main"] + assert "workflow_dispatch" in on and on["schedule"] + + +def test_air_workflow_validates_builds_signs_publishes_and_checks_the_clock_in_order(): + names = re.findall(r"^ - name: (.+)$", _wf(), re.M) + order = ["Fetch and verify the published VDR report", "Build incident reports (IIR, OIR, FIR)", + "Sign incident reports", "Publication redaction gate (no AWS account ID)", + "Publish incident reports to /.well-known/", + "Incident report clocks (fail when a report is due and missing)"] + assert [n for n in names if n in order] == order + + +def test_air_workflow_writes_only_incident_objects_and_sends_nothing(): + text = _wf() + keys = re.findall(r'--key "\.well-known/([^"]+)"', text) + assert keys == ["$1"] + puts = [p.strip('"') for p in re.findall(r"^\s*put (\S+) ", text, re.M)] + assert puts and all(p.startswith(("incident-", "$f", "${f")) for p in puts), puts + assert "for f in incident-INC-*.json; do" in text + assert "environment: incident-reports" in text and "AWS_INCIDENT_REPORTS_ROLE_ARN" in text + assert not re.search(r"\b(ses|sendmail|send-email|smtp)\b", text, re.I) + assert "aws s3 sync" not in text and "aws s3 rm" not in text and not re.search(r"^\s*terraform ", text, re.M) + + +def test_air_role_is_scoped_to_incident_objects(): + tf = (REPO / "infrastructure" / "bootstrap" / "incident-reports.tf").read_text() + assert '"arn:aws:s3:::${var.domain_name}/.well-known/incident-*"' in tf + actions = set(re.findall(r'"((?:s3|cloudfront):[A-Za-z*]+)"', tf)) + assert actions == {"s3:PutObject", "cloudfront:CreateInvalidation"} + assert 'environment:${var.incident_reports_environment}' in tf + + +def test_all_three_workflows_pin_the_same_opa(): + def pins(name): + text = (WF / name).read_text() + return {k: re.search(rf"^ {k}: (\S+)", text, re.M).group(1) for k in ("OPA_VERSION", "OPA_SHA256")} + assert pins("incident-reports.yml") == pins("deploy-with-opa.yml") == pins("evidence-nightly.yml") + + +# ---- the Ongoing Certification Report's incident summary (CCM-OCR-AVL item 7) ------- + +def test_ocr_attests_none_when_only_exercises_are_recorded(): + ocr = _load("ocr_inc", "scripts/build-ocr.py") + text = ocr.incident_summary(_incidents.load(REGISTER), "2026-08-01") + assert text.startswith("No FedRAMP Reportable Incidents occurred") and "incident-reports.json" in text + + +def test_ocr_lists_a_real_reportable_incident_in_the_period(): + ocr = _load("ocr_inc2", "scripts/build-ocr.py") + text = ocr.incident_summary(_incidents.validate(good()), "2026-08-01") + assert text.startswith("1 FedRAMP Reportable Incident(s) this period: INC-2026-101 (open)") + assert ocr.incident_summary(_incidents.validate(good()), "2026-11-03").startswith("No FedRAMP") diff --git a/tests/test_published_redaction.py b/tests/test_published_redaction.py index 53fb8e84..c63752c0 100644 --- a/tests/test_published_redaction.py +++ b/tests/test_published_redaction.py @@ -198,6 +198,14 @@ def test_deploy_gates_exactly_what_it_publishes(tmp_path): optional = ("boundary-map", "reconcile-report", "trust-center", "conformance-results", "boundary-corroboration") for a in optional: (tmp_path / f"{a}.json").write_text("{}") + # The incident reports are named by incident, so the steps use globs; with + # the files the builder writes present, both expand to the same set. + incident_files = ("incident-reports.json", "incident-reports.md", "incident-INC-2026-001-01-initial.json") + for f in incident_files: + (tmp_path / f).write_text("{}") + assert "incident-INC-*.json" in publish + publish = {n for n in publish if "*" not in n} | {f for f in incident_files if f.startswith("incident-INC-")} + assert {"incident-reports.json", "incident-reports.md"} <= publish assert _gate_files(gate_step, tmp_path) == publish # One absent (the operator-run corroboration): it is neither uploaded nor scanned. (tmp_path / "boundary-corroboration.json").unlink() From e56396610a05c4a8a54fbef6c0baf2366eb2952e Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 15:56:11 -0500 Subject: [PATCH 5/7] Incident reports: deploy preflight and proof of the publisher; records state the deployed system The deploy fails before applying anything unless AWS_INCIDENT_REPORTS_ROLE_ARN names the bootstrap incident-reports role and the incident-reports environment deploys only from main (scripts/check-incident-publisher.py; known-bad fixture with the variable missing). After the deploy job, the deploy calls incident-reports.yml (now also workflow_call) on its own role, passing only the CloudFront secret, so a green deploy proves the publisher publishes. IEC-CSO-IIR/OIR/FIR/AIR gaps now state only what holds after a successful deploy: published, not delivered to FedRAMP or agencies, by the operator's decision. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 35 ++++- .github/workflows/incident-reports.yml | 9 ++ data/frr-records.json | 18 ++- scripts/check-incident-publisher.py | 139 ++++++++++++++++++ tests/fixtures/incidents/preflight-good.json | 7 + .../incidents/preflight-missing-variable.json | 7 + tests/test_incidents.py | 92 ++++++++++++ 7 files changed, 300 insertions(+), 7 deletions(-) create mode 100644 scripts/check-incident-publisher.py create mode 100644 tests/fixtures/incidents/preflight-good.json create mode 100644 tests/fixtures/incidents/preflight-missing-variable.json diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 06b22820..7cf23ab4 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -612,6 +612,19 @@ jobs: with: fetch-depth: 0 + # The incident report records (IEC-CSO-IIR/OIR/FIR/AIR) describe the system + # after a successful deploy, which includes the unattended publisher in + # .github/workflows/incident-reports.yml. Fail before anything is applied if + # its prerequisites are missing: the role variable set and naming the + # bootstrap role, and the incident-reports environment main-only (checked + # when the job token can read it; said so when it cannot). The + # incident-publisher job below then proves the role publishes. + - name: Incident report publisher preflight + env: + INCIDENT_REPORTS_ROLE_ARN: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }} + GITHUB_TOKEN: ${{ github.token }} + run: python3 scripts/check-incident-publisher.py + - name: Setup Terraform uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1 with: @@ -2249,11 +2262,27 @@ jobs: # which is functionally the same as no alert: nothing distinguishes the one # that matters. It now reuses a single issue, reopening and commenting, and # assigns it to the repository owner so it reaches a person. + # A deploy is not done until the unattended incident report publisher has run + # on its own role from the incident-reports environment: the IEC records say + # it publishes, so a deploy where it cannot fails here. + incident-publisher: + name: Prove the incident report publisher + needs: [deploy] + if: needs.deploy.result == 'success' + permissions: + contents: read + id-token: write + issues: write + uses: ./.github/workflows/incident-reports.yml + # Least privilege: the one secret the publisher uses, not `inherit`. + secrets: + CLOUDFRONT_DISTRIBUTION_ID: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} + notify: name: Notify on Failure runs-on: ubuntu-latest - needs: [compliance-check, deploy] - if: always() && (needs.compliance-check.result == 'failure' || needs.deploy.result == 'failure') + needs: [compliance-check, deploy, incident-publisher] + if: always() && (needs.compliance-check.result == 'failure' || needs.deploy.result == 'failure' || needs.incident-publisher.result == 'failure') permissions: contents: read issues: write @@ -2267,6 +2296,7 @@ jobs: env: COMPLIANCE_RESULT: ${{ needs.compliance-check.result }} DEPLOY_RESULT: ${{ needs.deploy.result }} + PUBLISHER_RESULT: ${{ needs.incident-publisher.result }} with: script: | const TITLE = `Deployment failing: ${context.workflow}`; @@ -2282,6 +2312,7 @@ jobs: `| Ref | ${context.ref} |`, `| Compliance check | \`${process.env.COMPLIANCE_RESULT}\` |`, `| Deploy | \`${process.env.DEPLOY_RESULT}\` |`, + `| Incident report publisher | \`${process.env.PUBLISHER_RESULT}\` |`, ``, `Review the failing step in the run log, and the compliance reports it uploaded.`, ``, diff --git a/.github/workflows/incident-reports.yml b/.github/workflows/incident-reports.yml index fbf92b77..e8b2abee 100644 --- a/.github/workflows/incident-reports.yml +++ b/.github/workflows/incident-reports.yml @@ -41,6 +41,15 @@ on: branches: [main] paths: [data/incidents.json] workflow_dispatch: + # Called by every deploy (deploy-with-opa.yml, job incident-publisher) after + # the deploy job succeeds, so a green deploy proves this publisher assumes its + # role from the incident-reports environment and publishes; a deploy whose + # publisher cannot fails. + workflow_call: + # Only the secret the publish step uses; the caller passes it by name. + secrets: + CLOUDFRONT_DISTRIBUTION_ID: + required: true # Keeps the published log inside its 24-hour freshness window when nothing # changes, and re-reads the VDR for new VER-TFR-IRI/NRI triggers. schedule: diff --git a/data/frr-records.json b/data/frr-records.json index 4e1103cc..823b1694 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -659,7 +659,7 @@ { "frr_id": "IEC-CSO-AIR", "status": "Partially Implemented", - "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). Every deploy checks the publisher's prerequisites before it applies anything (scripts/check-incident-publisher.py: the role variable names the bootstrap role and the incident-reports environment deploys only from main) and, after the deploy job, runs this workflow on its own role (deploy-with-opa.yml job incident-publisher), so the deploy fails if the publisher cannot publish.", "evidence": [ { "kind": "step", @@ -669,6 +669,14 @@ "kind": "step", "ref": "incident-reports.yml#Incident report clocks (fail when a report is due and missing)" }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Incident report publisher preflight" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_deploy_proves_the_publisher_by_calling_it_after_the_deploy" + }, { "kind": "test", "ref": "tests/test_incidents.py::test_air_workflow_validates_builds_signs_publishes_and_checks_the_clock_in_order" @@ -678,7 +686,7 @@ "ref": ".well-known/incident-reports.json" } ], - "gap": "Not yet running: the role in infrastructure/bootstrap/incident-reports.tf is operator-applied, and the incident-reports GitHub Environment and AWS_INCIDENT_REPORTS_ROLE_ARN variable must be set. Reporting reaches no affected party automatically because delivery is publish-only by the operator's choice. To close: apply the bootstrap role and set the environment and variable; then the operator's delivery decision (IEC-CSO-IIR).", + "gap": "Everything up to publication is automated; what is left is the last step of the rule, reaching all affected parties. Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). A person still records the incident's facts in the register, which the rule allows (it asks to minimize human intervention, not remove it). To close: the operator's delivery decision (IEC-CSO-IIR); the delivery is then built into this workflow.", "closes_with": [ "sam" ] @@ -762,7 +770,7 @@ "ref": ".well-known/incident-reports.json" } ], - "gap": "Published, not delivered (see IEC-CSO-IIR). To close: the operator's delivery decision, as for IEC-CSO-IIR.", + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ "sam" ] @@ -789,7 +797,7 @@ "ref": ".well-known/incident-reports.json" } ], - "gap": "Reports are published, not delivered: nothing notifies FedRAMP or an agency, and the operator has not decided to send. The unattended publisher needs infrastructure/bootstrap/incident-reports.tf applied and the AWS_INCIDENT_REPORTS_ROLE_ARN variable and incident-reports environment set before it runs. To close: the operator decides the delivery channel (e.g. SES from the system's domain to FedRAMP's incident address) and it is built behind that decision.", + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator decides a delivery channel (e.g. SES from the system's domain to FedRAMP's incident address) and it is built behind that decision.", "closes_with": [ "sam" ] @@ -812,7 +820,7 @@ "ref": ".well-known/incident-reports.json" } ], - "gap": "Published, not delivered (see IEC-CSO-IIR). To close: the operator's delivery decision, as for IEC-CSO-IIR.", + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ "sam" ] diff --git a/scripts/check-incident-publisher.py b/scripts/check-incident-publisher.py new file mode 100644 index 00000000..e31d3cfa --- /dev/null +++ b/scripts/check-incident-publisher.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +"""Deploy preflight: the unattended incident report publisher is in place. + +The FedRAMP incident report records (IEC-CSO-IIR/OIR/FIR/AIR) describe the +system as it is after a successful deploy, so a deploy must not succeed +without the prerequisites they rely on. Run early in the deploy job, before +anything is applied, this fails the deploy unless: + + 1. the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is set, and + 2. it names the role infrastructure/bootstrap/incident-reports.tf creates + (github-actions-incident-reports-oidc, an IAM role ARN), and + 3. the `incident-reports` GitHub Environment exists and deploys only from + main (a custom branch policy naming exactly `main`). + +Check 3 reads GitHub's API with the job token. A missing environment (404) +fails. If the token cannot read the environment at all (any other error), the +check is reported as not observed and the deploy continues on checks 1-2: +the deploy's later incident-publisher job assumes the role from that +environment, so a wrong environment still fails the deploy there. + +Whether the role itself works is proved later in the same run: the +`incident-publisher` job calls .github/workflows/incident-reports.yml, which +assumes the role, publishes, and fails the deploy if it cannot. + +Prints no ARN or account ID. Exit 0 pass, 1 fail. +""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +import urllib.error +import urllib.request +from typing import Any + +EXPECTED_ROLE_NAME = "github-actions-incident-reports-oidc" +ENVIRONMENT = "incident-reports" +EXPECTED_BRANCHES = {"main"} +ROLE_ARN_RE = re.compile(r"^arn:aws(-[a-z]+)*:iam::[0-9]{12}:role/(?:[\w+=,.@-]+/)*([\w+=,.@-]+)$") + + +def check_variable(role_arn: str | None) -> list[str]: + if not role_arn or not role_arn.strip(): + return ["the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is not set: apply " + "infrastructure/bootstrap/incident-reports.tf and set it from the incident_reports_role_arn output"] + m = ROLE_ARN_RE.match(role_arn.strip()) + if not m: + return ["AWS_INCIDENT_REPORTS_ROLE_ARN is not an IAM role ARN"] + if m.group(2) != EXPECTED_ROLE_NAME: + return [f"AWS_INCIDENT_REPORTS_ROLE_ARN names a role other than {EXPECTED_ROLE_NAME}"] + return [] + + +def check_environment(env: dict[str, Any] | None, branch_policies: list[str] | None) -> tuple[list[str], str]: + """(problems, note). env None = the environment does not exist.""" + if env is None: + return [f"the {ENVIRONMENT} GitHub Environment does not exist"], "" + policy = env.get("deployment_branch_policy") or {} + if not policy.get("custom_branch_policies") or policy.get("protected_branches"): + return [f"the {ENVIRONMENT} environment does not restrict deployments to a custom branch list"], "" + if branch_policies is None: + return [], "branch policies not observed" + if set(branch_policies) != EXPECTED_BRANCHES: + return [f"the {ENVIRONMENT} environment deploys from {sorted(branch_policies) or 'no branch'}, " + "not only main"], "" + return [], f"{ENVIRONMENT} deploys only from main" + + +def _get(url: str, token: str | None) -> Any: + if not url.startswith("https://"): + raise ValueError("refusing non-HTTPS URL") + headers = {"Accept": "application/vnd.github+json", "User-Agent": "samaydlette-preflight"} + if token: + headers["Authorization"] = f"Bearer {token}" + with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=15) as r: # noqa: S310 + return json.loads(r.read().decode()) + + +def read_environment(repo: str, token: str | None) -> tuple[str, dict[str, Any] | None, list[str] | None]: + """("ok"|"missing"|"unreadable", environment, branch policy names).""" + api = f"https://api.github.com/repos/{repo}/environments/{ENVIRONMENT}" + try: + env = _get(api, token) + except urllib.error.HTTPError as exc: + return ("missing" if exc.code == 404 else "unreadable"), None, None + except Exception: # noqa: BLE001 (any other failure: not observed) + return "unreadable", None, None + try: + pols = _get(f"{api}/deployment-branch-policies", token) + names = [p.get("name", "") for p in pols.get("branch_policies", [])] + except Exception: # noqa: BLE001 + names = None + return "ok", env, names + + +def evaluate(role_arn: str | None, env_state: str, env: dict[str, Any] | None, + branch_policies: list[str] | None) -> tuple[list[str], list[str]]: + """(problems, notes) for one run; pure, for tests.""" + problems = check_variable(role_arn) + notes = [] + if env_state == "unreadable": + notes.append(f"the {ENVIRONMENT} environment could not be read with the job token; not observed " + "(the incident-publisher job still fails the deploy if the role cannot be assumed from it)") + else: + p, note = check_environment(env if env_state == "ok" else None, branch_policies) + problems += p + if note: + notes.append(note) + return problems, notes + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("--fixture", default=None, + help="JSON {role_arn, env_state, environment, branch_policies} instead of live reads (tests)") + a = ap.parse_args(argv) + if a.fixture: + with open(a.fixture) as fh: + fx = json.load(fh) + problems, notes = evaluate(fx.get("role_arn"), fx["env_state"], fx.get("environment"), + fx.get("branch_policies")) + else: + state, env, pols = read_environment(os.environ.get("GITHUB_REPOSITORY", "sam-aydlette/samaydlette.com"), + os.environ.get("GITHUB_TOKEN")) + problems, notes = evaluate(os.environ.get("INCIDENT_REPORTS_ROLE_ARN"), state, env, pols) + for n in notes: + print(f"incident publisher preflight: {n}") + for p in problems: + print(f"::error::incident publisher preflight: {p}") + if not problems: + print("incident publisher preflight: role variable names the incident-reports role; ok") + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/incidents/preflight-good.json b/tests/fixtures/incidents/preflight-good.json new file mode 100644 index 00000000..c7738649 --- /dev/null +++ b/tests/fixtures/incidents/preflight-good.json @@ -0,0 +1,7 @@ +{ + "_comment": "Good: variable names the incident-reports role (example account), environment deploys only from main.", + "role_arn": "arn:aws:iam::000000000000:role/github-actions-incident-reports-oidc", + "env_state": "ok", + "environment": {"name": "incident-reports", "deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}, + "branch_policies": ["main"] +} diff --git a/tests/fixtures/incidents/preflight-missing-variable.json b/tests/fixtures/incidents/preflight-missing-variable.json new file mode 100644 index 00000000..6ce86a33 --- /dev/null +++ b/tests/fixtures/incidents/preflight-missing-variable.json @@ -0,0 +1,7 @@ +{ + "_comment": "Known-bad: the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is unset; the environment is correct. check-incident-publisher.py must fail for the variable alone.", + "role_arn": "", + "env_state": "ok", + "environment": {"name": "incident-reports", "deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}, + "branch_policies": ["main"] +} diff --git a/tests/test_incidents.py b/tests/test_incidents.py index 5df3f472..36cc70ba 100644 --- a/tests/test_incidents.py +++ b/tests/test_incidents.py @@ -455,6 +455,98 @@ def pins(name): assert pins("incident-reports.yml") == pins("deploy-with-opa.yml") == pins("evidence-nightly.yml") +# ---- deploy preflight and proof of the publisher (the records hold once deployed) ---- + +preflight = _load("preflight", "scripts/check-incident-publisher.py") +ENV_OK = {"name": "incident-reports", + "deployment_branch_policy": {"protected_branches": False, "custom_branch_policies": True}} +ARN_OK = "arn:aws:iam::000000000000:role/github-actions-incident-reports-oidc" + + +def test_preflight_role_name_is_the_bootstrap_role(): + tf = (REPO / "infrastructure" / "bootstrap" / "incident-reports.tf").read_text() + assert f'"{preflight.EXPECTED_ROLE_NAME}"' in tf + assert f"environment: {preflight.ENVIRONMENT}" in _wf() + + +def test_preflight_passes_a_set_variable_and_a_main_only_environment(): + assert preflight.evaluate(ARN_OK, "ok", ENV_OK, ["main"]) == ([], ["incident-reports deploys only from main"]) + assert preflight.main(["--fixture", str(FIX / "preflight-good.json")]) == 0 + + +def test_preflight_fails_the_known_bad_fixture_for_the_missing_variable(capsys): + fx = json.loads((FIX / "preflight-missing-variable.json").read_text()) + problems, _ = preflight.evaluate(fx["role_arn"], fx["env_state"], fx["environment"], fx["branch_policies"]) + assert len(problems) == 1 and "AWS_INCIDENT_REPORTS_ROLE_ARN is not set" in problems[0] + assert preflight.main(["--fixture", str(FIX / "preflight-missing-variable.json")]) == 1 + assert "::error::" in capsys.readouterr().out + + +@pytest.mark.parametrize("arn,why", [ + (None, "is not set"), + ("arn:aws:iam::000000000000:role/github-actions-oidc", "names a role other than"), + ("arn:aws:iam::000000000000:user/github-actions-incident-reports-oidc", "is not an IAM role ARN"), + ("github-actions-incident-reports-oidc", "is not an IAM role ARN"), +]) +def test_preflight_fails_a_variable_that_does_not_name_the_role(arn, why): + problems, _ = preflight.evaluate(arn, "ok", ENV_OK, ["main"]) + assert len(problems) == 1 and why in problems[0] + + +def test_preflight_never_prints_the_arn_or_account(capsys, tmp_path): + fx = tmp_path / "fx.json" + fx.write_text(json.dumps({"role_arn": "arn:aws:iam::123456789012:role/other", "env_state": "ok", + "environment": ENV_OK, "branch_policies": ["main"]})) + preflight.main(["--fixture", str(fx)]) + assert "123456789012" not in capsys.readouterr().out + + +@pytest.mark.parametrize("state,env,branches,why", [ + ("missing", None, None, "does not exist"), + ("ok", {"deployment_branch_policy": None}, None, "custom branch list"), + ("ok", {"deployment_branch_policy": {"protected_branches": True, "custom_branch_policies": False}}, None, + "custom branch list"), + ("ok", ENV_OK, ["main", "feat/*"], "not only main"), + ("ok", ENV_OK, [], "not only main"), +]) +def test_preflight_fails_a_missing_or_unrestricted_environment(state, env, branches, why): + problems, _ = preflight.evaluate(ARN_OK, state, env, branches) + assert len(problems) == 1 and why in problems[0] + + +def test_preflight_says_so_when_the_environment_cannot_be_read_and_checks_the_variable(): + problems, notes = preflight.evaluate(ARN_OK, "unreadable", None, None) + assert problems == [] and "not observed" in notes[0] + problems, _ = preflight.evaluate("", "unreadable", None, None) + assert problems and "is not set" in problems[0] + + +def _deploy(): + return (WF / "deploy-with-opa.yml").read_text() + + +def test_deploy_runs_the_preflight_before_anything_is_applied(): + yaml = pytest.importorskip("yaml") + steps = yaml.safe_load(_deploy())["jobs"]["deploy"]["steps"] + names = [st.get("name") for st in steps] + i = names.index("Incident report publisher preflight") + assert i < names.index("Configure AWS credentials") < names.index("Terraform Apply") + assert "INCIDENT_REPORTS_ROLE_ARN: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }}" in _deploy() + assert "run: python3 scripts/check-incident-publisher.py" in _deploy() + + +def test_deploy_proves_the_publisher_by_calling_it_after_the_deploy(): + yaml = pytest.importorskip("yaml") + jobs = yaml.safe_load(_deploy())["jobs"] + job = jobs["incident-publisher"] + assert job["uses"] == "./.github/workflows/incident-reports.yml" and job["needs"] == ["deploy"] + assert job["permissions"]["id-token"] == "write" + assert job["secrets"] == {"CLOUDFRONT_DISTRIBUTION_ID": "${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}"} + assert list(yaml.safe_load(_wf())[True]["workflow_call"]["secrets"]) == ["CLOUDFRONT_DISTRIBUTION_ID"] + assert "incident-publisher" in jobs["notify"]["needs"] + assert "needs.incident-publisher.result == 'failure'" in jobs["notify"]["if"] + assert "workflow_call" in yaml.safe_load(_wf())[True] + # ---- the Ongoing Certification Report's incident summary (CCM-OCR-AVL item 7) ------- def test_ocr_attests_none_when_only_exercises_are_recorded(): From 15d59e73f3c5db89643062bb0c95b99b97196d43 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:35:50 -0500 Subject: [PATCH 6/7] FedRAMP Security Inbox, simulated (AFC-CSO-*) The inbox is simulated for this proof of concept by the operator's decision: nothing is received or sent. scripts/_fsi.py is the inbox logic (classification, designators, Class C deadline, register, header-safe acknowledgement sent once, paging). Every deploy runs it over committed synthetic messages before the SDR build, fails on any unexpected outcome, and publishes the signed, dated result as fedramp-inbox-simulation.json, labelled as a simulation. The published contact says so and points to LinkedIn; the AFC-CSO-NOC check applies to that contact. AFC records are Implemented with simulated {counterparty: mail}. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 38 +- data/cds/offering.json | 14 + data/frr-records.json | 262 +++++++++--- data/fsi-simulation/messages.json | 366 +++++++++++++++++ docs/cr26-applicability.md | 5 +- docs/incident-response.md | 2 +- docs/policies/ir-policy.md | 2 +- docs/runbooks/fedramp-security-inbox.md | 78 ++++ infrastructure/schemas/freshness-config.json | 12 + scripts/_fsi.py | 322 +++++++++++++++ scripts/build-cpo.py | 17 + scripts/build-fsi-simulation.py | 221 +++++++++++ scripts/check-fsi-notice.py | 123 ++++++ .../fsi/offering-changed-with-notice.json | 21 + .../fsi/offering-changed-without-history.json | 13 + .../fsi/offering-changed-without-notice.json | 17 + .../fsi/simulation-wrong-expectation.json | 366 +++++++++++++++++ tests/test_fedramp_inbox.py | 374 ++++++++++++++++++ tests/test_frr_records.py | 6 +- tests/test_fsi_notice.py | 94 +++++ 20 files changed, 2291 insertions(+), 62 deletions(-) create mode 100644 data/fsi-simulation/messages.json create mode 100644 docs/runbooks/fedramp-security-inbox.md create mode 100644 scripts/_fsi.py create mode 100644 scripts/build-fsi-simulation.py create mode 100644 scripts/check-fsi-notice.py create mode 100644 tests/fixtures/fsi/offering-changed-with-notice.json create mode 100644 tests/fixtures/fsi/offering-changed-without-history.json create mode 100644 tests/fixtures/fsi/offering-changed-without-notice.json create mode 100644 tests/fixtures/fsi/simulation-wrong-expectation.json create mode 100644 tests/test_fedramp_inbox.py create mode 100644 tests/test_fsi_notice.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 7cf23ab4..2af5f99a 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -249,6 +249,24 @@ jobs: - name: Exception register expiry check run: python3 scripts/check-exceptions.py + # AFC-CSO-NOC: the FedRAMP Security Inbox contact (data/cds/offering.json) + # cannot change without a history entry recording that FedRAMP was + # notified. Compared with the merge base on a pull request and with the + # previous commit on a push, so the history is also append-only. + - name: FedRAMP Security Inbox change notice (AFC-CSO-NOC) + env: + BASE_REF: ${{ github.event_name == 'pull_request' && github.base_ref || '' }} + BEFORE_SHA: ${{ github.event_name == 'push' && github.event.before || '' }} + run: | + base="" + if [ -n "$BASE_REF" ] && git fetch --no-tags --depth=1 origin "$BASE_REF"; then + git show FETCH_HEAD:data/cds/offering.json > fsi-base.json 2>/dev/null && base="--base fsi-base.json" + elif [ -n "$BEFORE_SHA" ] && git fetch --no-tags --depth=1 origin "$BEFORE_SHA"; then + git show "$BEFORE_SHA":data/cds/offering.json > fsi-base.json 2>/dev/null && base="--base fsi-base.json" + fi + # shellcheck disable=SC2086 # $base is an optional flag pair + python3 scripts/check-fsi-notice.py $base + # Known Go-vs-Wasm builtin divergences (%q, %v-on-sets, host time) are # banned at lint time; the parity test catches what the corpus exercises, # this catches the rest before it exists. It also requires every sprintf @@ -1617,6 +1635,19 @@ jobs: --previous previous-availability.json --ksi-signal ksi-signal.json python3 ../scripts/build-policy-index.py --output policy-index.json --md-output policy-index.md + # SIMULATION. The FedRAMP Security Inbox is simulated for this proof of + # concept (operator's decision): nothing real is received or sent. This + # runs the inbox logic (scripts/_fsi.py) over committed synthetic messages + # and fails the deploy if any outcome differs from the expected one + # (AFC-CSO-INB/TFG/RCV/CRA/EMR/IMA/ACK, simulated). + - name: FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent) + working-directory: infrastructure + run: | + python3 ../scripts/build-fsi-simulation.py \ + --messages ../data/fsi-simulation/messages.json \ + --offering ../data/cds/offering.json \ + --output fedramp-inbox-simulation.json + - name: Build Security Decision Record (SDR — 20x SSP replacement) working-directory: infrastructure run: | @@ -1744,6 +1775,8 @@ jobs: run: | echo "Signing ongoing-certification-report.json with cosign keyless..." cosign sign-blob --yes --new-bundle-format --bundle ongoing-certification-report.bundle ongoing-certification-report.json + echo "Signing fedramp-inbox-simulation.json (SIMULATION) with cosign keyless..." + cosign sign-blob --yes --new-bundle-format --bundle fedramp-inbox-simulation.bundle fedramp-inbox-simulation.json - name: Sign CDS certification-data artifacts working-directory: infrastructure @@ -1784,7 +1817,7 @@ jobs: files="ksi-signal.json schemas/ksi-signal.schema.json vdr-report.json vdr-report.md vdr-trend.json iiw.csv" for a in vdr-detail-report vdr-accepted-vulnerabilities vdr-history; do files="$files $a.json"; done for a in vdr-detail-report vdr-accepted-vulnerabilities; do files="$files $a.md"; done - files="$files ongoing-certification-report.json ongoing-certification-report.md" + files="$files ongoing-certification-report.json ongoing-certification-report.md fedramp-inbox-simulation.json" for a in certification-overview-package availability policy-index security-decision-record certification-package-overview; do files="$files $a.json $a.md"; done for a in significant-change-notifications scn-evaluations; do files="$files $a.json $a.md"; done files="$files significant-change-notifications.atom" @@ -1843,6 +1876,8 @@ jobs: aws s3 cp ongoing-certification-report.json "s3://$BUCKET_NAME/.well-known/ongoing-certification-report.json" --content-type application/json --cache-control "public, max-age=300" aws s3 cp ongoing-certification-report.bundle "s3://$BUCKET_NAME/.well-known/ongoing-certification-report.bundle" --content-type application/json --cache-control "public, max-age=300" aws s3 cp ongoing-certification-report.md "s3://$BUCKET_NAME/.well-known/ongoing-certification-report.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + aws s3 cp fedramp-inbox-simulation.json "s3://$BUCKET_NAME/.well-known/fedramp-inbox-simulation.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp fedramp-inbox-simulation.bundle "s3://$BUCKET_NAME/.well-known/fedramp-inbox-simulation.bundle" --content-type application/json --cache-control "public, max-age=300" # CDS certification-data artifacts (overview package, availability feed, policy index) + bundles + human-readable for a in certification-overview-package availability policy-index security-decision-record certification-package-overview; do aws s3 cp "$a.json" "s3://$BUCKET_NAME/.well-known/$a.json" --content-type application/json --cache-control "public, max-age=300" @@ -1950,6 +1985,7 @@ jobs: check "$a.json" ".well-known/$a.json" done check ongoing-certification-report.json .well-known/ongoing-certification-report.json + check fedramp-inbox-simulation.json .well-known/fedramp-inbox-simulation.json check certification-overview-package.json .well-known/certification-overview-package.json check availability.json .well-known/availability.json check policy-index.json .well-known/policy-index.json diff --git a/data/cds/offering.json b/data/cds/offering.json index 27be34e5..ce1c5cd5 100644 --- a/data/cds/offering.json +++ b/data/cds/offering.json @@ -7,6 +7,20 @@ "uei": "", "sales_contact": { "name": "Sam Aydlette", "url": "https://samaydlette.com/pages/contact.html" }, "security_contact": { "name": "Sam Aydlette", "email": "sam.aydlette@gmail.com", "source": "/.well-known/security.txt" }, + "fedramp_security_inbox": { + "_note": "The FedRAMP Security Inbox contact (AFC-CSO-INB), written in this one place. By the operator's decision the inbox is SIMULATED for this proof of concept: the inbox logic (scripts/_fsi.py) runs on every deploy over synthetic messages and publishes /.well-known/fedramp-inbox-simulation.json, and nothing real is received or sent. The CPO publishes this contact, and scripts/check-fsi-notice.py fails any change to it that does not record notifying FedRAMP (AFC-CSO-NOC). To change it: add a history entry with fedramp_notified, then change contact.", + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/", + "simulation": "https://samaydlette.com/.well-known/fedramp-inbox-simulation.json", + "runbook": "https://github.com/sam-aydlette/samaydlette.com/blob/main/docs/runbooks/fedramp-security-inbox.md", + "history": [ + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/", + "since": "2026-11-05", + "fedramp_notified": null, + "basis": "Established. No earlier FedRAMP Security Inbox or Marketplace Security Email is on file with FedRAMP for this unsponsored system, so there was no prior contact to change from." + } + ] + }, "product_website": "https://samaydlette.com", "logo_url": "https://samaydlette.com/assets/images/brand/logo.png", "service_description": "A static personal website on AWS that doubles as a working continuous-compliance pipeline: every deploy derives signed, machine-readable compliance artifacts from one canonical inventory and publishes them under /.well-known/. Includes the Silk Reeling Mirror application, a Cognito-gated Tai Chi coaching API.", diff --git a/data/frr-records.json b/data/frr-records.json index 823b1694..2ebc5672 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -5,83 +5,235 @@ "records": [ { "frr_id": "AFC-CSO-ACK", - "status": "Not Implemented", - "implementation": "No FSI; no auto-responder.", - "evidence": [], - "gap": "No prompt automatic acknowledgment of FedRAMP messages. To close: Configure an auto-acknowledgment for mail from @fedramp.gov/@gsa.gov (e.g. SES receipt rule -> Lambda reply, or provider auto-reply rule) and include it in the nightly configuration check.", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). The acknowledgement logic (scripts/_fsi.py, build_ack and receive) acknowledges each FedRAMP message once, even when it is redelivered, with headers inbound content cannot inject, and never to auto-replies, bulk mail, bounces, mail without a From address, or mail failing SPF/DKIM/DMARC (FedRAMP's own mail passes them, AFC-FRP-VRE; this keeps a forged sender from using the inbox as a reflector; such mail is still registered and paged). In the simulation each acknowledgement is built and checked for header safety, then filed nowhere. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_nothing_from_the_inbound_message_can_inject_a_header" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_redelivered_message_is_acknowledged_and_paged_once" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_unauthenticated_fedramp_mail_is_registered_and_paged_but_not_acknowledged" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_no_acknowledgement_to_auto_replies_bulk_mail_or_bounces" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-CRA", - "status": "Not Implemented", - "implementation": "No FSI, no Emergency/Emergency Test handling runbook in docs/incident-response.md or ir-policy.md.", - "evidence": [], - "gap": "No procedure to recognize Emergency / Emergency Test designated messages, extract the required actions and timeframe, and complete them; no record of completion. To close: Write an FSI runbook (classify by designation, open a tracked item with the message's deadline, complete, reply with completion) and wire Emergency-designated mail to page the operator; keep a completion log. Rehearse with a self-generated Emergency Test.", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). Emergency and Emergency Test messages (subject designator, AFC-FRP-CDS) get a register item with a deadline: by default 3:00 p.m. ET on the 2nd business day (AFC-FRP-ERT, Class C; the receipt day counts and holidays are not skipped, both erring earlier), replaced at triage by the timeframe the message states; the register reports an item past its deadline until it is closed (scripts/_fsi.py, deadlines, triage, close, overdue). In the simulation the Emergency Test received on a Friday is due 3:00 p.m. ET the following Monday, is reported once that passes, and stops being reported when closed. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_class_c_default_deadline_is_3pm_eastern_on_the_second_business_day" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_emergency_records_carry_a_deadline_and_important_ones_ask_for_the_messages_own" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_overdue_counts_untriaged_unclosed_and_failed_legs" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-EMR", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No routing of Emergency-designated messages to a senior security official; no mailbox configuration or automated validation (both artifacts missing). To close: Add a mail rule that routes subject-designated 'Emergency' FedRAMP messages to the senior security official (the accountable official in the CPO, plus SNS page), and include it in the nightly mailbox-configuration check.", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). Every FedRAMP message, Emergency-designated ones included, produces a page to the senior security official (the accountable official named in the CPO, the operator) naming the designation and the sender's domain (scripts/_fsi.py, receive and page_subject); an Emergency from an address other than FedRAMP's designated Emergency senders (AFC-FRP-UFS) is flagged, not demoted. In the simulation the page is recorded, not delivered: the operator's phone stays blissfully quiet. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_emergency_from_an_address_other_than_fedramp_security_is_flagged_not_demoted" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_page_subject_is_ascii_and_names_the_domain_not_the_address" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-IMA", - "status": "Not Implemented", - "implementation": "No FSI; no handling procedure for Important-designated messages.", - "evidence": [], - "gap": "No procedure to complete actions in Important messages within their stated timeframe. To close: Extend the FSI runbook to Important messages with tracked deadlines (same tracker as CRA).", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). Important-designated messages open a register item that cannot be triaged without recording the timeframe the message states; the register reports it while untriaged after 24 hours, triaged without a timeframe, or past that timeframe and not closed (scripts/_fsi.py, triage and overdue). The simulation checks each of these. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_important_message_cannot_be_triaged_without_its_stated_timeframe" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_overdue_counts_untriaged_unclosed_and_failed_legs" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-INB", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No dedicated FedRAMP Security Inbox address exists or is designated; the required artifact (an email address to receive messages from FedRAMP) cannot be produced. To close: Create a dedicated address on the system's domain (e.g. fedramp-security@samaydlette.com: MX record in dns.tf plus SES inbound or a mail provider, with SPF/DKIM/DMARC), document it as the FSI in the CPO certification_data (security_contact block) and trust center, and monitor it (alarm on delivery failure).", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). The published FedRAMP Security Inbox contact (data/cds/offering.json, fedramp_security_inbox.contact, published in the CPO's certification_data) says, plainly, that the inbox does not exist and to hit the operator up on LinkedIn. The logic a real inbox would run receives, classifies, registers, acknowledges and pages. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_simulation_passes_and_publishes_a_labelled_result_without_addresses" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_cpo_publishes_the_simulated_contact_not_an_email_address" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-NOC", - "status": "Not Implemented", - "implementation": "No FSI exists, so no change-notification process exists; nothing in docs/incident-response.md or docs/policies/ir-policy.md covers notifying FedRAMP of an inbox change.", - "evidence": [], - "gap": "No process (manual or automated) to notify FedRAMP when the FSI address changes. To close: Make the FSI address a single value in the canonical inventory and add a CI check that fails a change to it unless the commit carries a 'FedRAMP notified on via ' record; document the runbook step (email FedRAMP from the old and new address) in ir-policy.md.", - "closes_with": [ - "W9" + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). The published contact has one source (data/cds/offering.json, fedramp_security_inbox.contact) with an append-only history, and the notice rule applies to it unchanged. scripts/check-fsi-notice.py, run in the unit-test job on every pull request and push, fails a change to the contact unless a new history entry carries a dated fedramp_notified marker naming the channel (FedRAMP's '[CSP] Notification of Changes' form), and fails a rewritten history against the merge base. Known-bad fixtures in tests/fixtures/fsi/. Procedure: docs/runbooks/fedramp-security-inbox.md. The contact was established 2026-11-05 with nothing earlier on file with FedRAMP, so there has been no change to notify.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_a_contact_change_without_the_fedramp_notified_marker_fails" + }, + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_a_contact_change_without_a_history_entry_fails" + }, + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_rewriting_history_fails_against_the_base" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox change notice (AFC-CSO-NOC)" + } ] }, { "frr_id": "AFC-CSO-RCV", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "Nothing receives FedRAMP mail without disruption (no inbox, no anti-spam allowlisting, no monitoring, no backup reader for a one-person operation). To close: After INB/TFG: allowlist FedRAMP senders, add delivery-failure and unread-age alarms (SNS to operator, reusing the watchdog path), and name a backup reader or an out-of-office auto-forward so a single absent operator does not disrupt receipt. Provider half is fully buildable; only an actual FedRAMP message demonstrates it end-to-end.", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). Nothing in the inbox logic asks anything of FedRAMP or drops FedRAMP mail: every FedRAMP message is registered and paged whatever its verdicts (the simulation fails the deploy otherwise), a failed acknowledgement is recorded, reported overdue and sent once on retry, and overdue items are reported by the register (scripts/_fsi.py, receive and overdue). Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_failed_acknowledgement_is_recorded_retried_and_counted_overdue" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_overdue_counts_untriaged_unclosed_and_failed_legs" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_each_register_check_fails_the_simulation_when_its_outcome_differs" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "AFC-CSO-TFG", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No mailbox configuration treating @fedramp.gov / @gsa.gov senders as FedRAMP, and no automated validation of that configuration (both listed artifacts missing). To close: In the FSI mail rules, tag/route all mail from @fedramp.gov and @gsa.gov as FedRAMP (never spam-filtered/quarantined); export the rule set as code and add a nightly check (evidence-nightly.yml) that reads the live rules and compares them with the expected configuration, published to the trust center like check-manual-settings.py does for GitHub settings.", - "closes_with": [ - "W9" - ] + "status": "Implemented", + "implementation": "SIMULATED FOR THIS PROOF OF CONCEPT: there is no FedRAMP Security Inbox, no mail is received or sent, and FedRAMP is directed to the operator on LinkedIn (https://www.linkedin.com/in/sa2/). Classification (scripts/_fsi.py, classify): a message whose From address or envelope sender is exactly @fedramp.gov or @gsa.gov is FedRAMP, whatever its spam verdict or SPF/DKIM/DMARC result; look-alike domains and display-name spoofs are not; failed authentication is recorded so the operator can confirm the sender, never used to filter. The simulation includes a forged @gsa.gov message (still FedRAMP), a FedRAMP envelope sender behind an unreadable From (still FedRAMP), a look-alike domain and a display-name spoof (neither is FedRAMP). Automated validation of the configuration is the deploy-time simulation itself. Every deploy runs this logic (scripts/_fsi.py) over committed synthetic messages (data/fsi-simulation/messages.json) in the step 'FedRAMP Security Inbox simulation', fails the deploy if any outcome differs from the expected one, and publishes the signed, dated result, labelled as a simulation, as /.well-known/fedramp-inbox-simulation.json.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + }, + { + "kind": "artifact", + "ref": ".well-known/fedramp-inbox-simulation.json" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_fedramp_senders_are_fedramp_even_when_unauthenticated" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_look_alike_domains_and_display_name_spoofs_are_not_fedramp" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_fedramp_envelope_sender_counts_even_if_the_from_header_is_unparseable" + } + ], + "simulated": { + "counterparty": "mail", + "how": "The mail system and FedRAMP's messages are simulated: synthetic messages run through the real inbox logic on every deploy, outbound acknowledgements and pages are recorded, never sent, and the published contact is 'Hit me up on LinkedIn'." + } }, { "frr_id": "CCM-OCR-AFS", diff --git a/data/fsi-simulation/messages.json b/data/fsi-simulation/messages.json new file mode 100644 index 00000000..4e556857 --- /dev/null +++ b/data/fsi-simulation/messages.json @@ -0,0 +1,366 @@ +{ + "_note": "SIMULATION INPUT. Synthetic messages for the simulated FedRAMP Security Inbox (this proof of concept receives and sends no mail, by the operator's decision). scripts/build-fsi-simulation.py runs scripts/_fsi.py over these on every deploy and fails the deploy if any observed outcome differs from 'expected'. Addresses here are synthetic test values and are never published; the published result carries sender domains only.", + "inbox": "fedramp-security-inbox@simulation.invalid", + "register_check": { + "now": "2026-11-06T17:00:00Z", + "expected_overdue": [ + "sim-ack-send-fails", + "sim-emergency-other-sender", + "sim-emergency-test", + "sim-forged-gsa" + ], + "expected_retry": { + "acknowledgements_sent_again": 1, + "pages_sent_again": 0 + }, + "important_case": "sim-important", + "important_respond_by": "2026-11-10T22:00:00Z", + "later": "2026-11-09T21:00:00Z", + "emergency_case": "sim-emergency-test", + "untriaged_important_case": "sim-envelope-only" + }, + "messages": [ + { + "case": "emergency-test", + "description": "Emergency Test from FedRAMP's Emergency sender (AFC-FRP-UFS), authenticated", + "message_id": "sim-emergency-test", + "received_at": "2026-11-06T14:05:00Z", + "from": "FedRAMP Security ", + "envelope": "fedramp_security@fedramp.gov", + "subject": "EMERGENCY TEST: FedRAMP Security Inbox exercise", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY_TEST", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": true, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-06T16:05:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "important", + "description": "Important message whose subject and Message-ID try to inject a Bcc header", + "message_id": "sim-important", + "received_at": "2026-11-06T14:10:00Z", + "from": "FedRAMP PMO ", + "envelope": "info@fedramp.gov", + "subject": "IMPORTANT: action requested\r\nBcc: injected@attacker.invalid", + "headers": { + "Message-ID": "\r\nBcc: injected@attacker.invalid" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "IMPORTANT", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "sent", + "in_reply_to": false, + "page": true, + "triage_by": "2026-11-07T14:10:00Z", + "respond_by": null + } + }, + { + "case": "general", + "description": "General communication from @gsa.gov, no designator", + "message_id": "sim-general", + "received_at": "2026-11-06T14:15:00Z", + "from": "info@gsa.gov", + "envelope": "info@gsa.gov", + "subject": "FedRAMP program update", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-09T14:15:00Z", + "respond_by": null + } + }, + { + "case": "forged-gsa", + "description": "Forged Emergency claiming to be from the gsa.gov Emergency sender; SPF, DKIM and DMARC fail. Still FedRAMP by default (AFC-CSO-TFG) and paged, but not acknowledged", + "message_id": "sim-forged-gsa", + "received_at": "2026-11-06T14:20:00Z", + "from": "FedRAMP Security ", + "envelope": "bounce@attacker.invalid", + "subject": "EMERGENCY: reply with your credentials", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "FAIL", + "dkim": "FAIL", + "dmarc": "FAIL" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY", + "sender_domain": "gsa.gov", + "authenticated": false, + "emergency_sender_ok": true, + "ack": "suppressed:unauthenticated", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-06T16:20:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "auto-reply", + "description": "An auto-reply from @fedramp.gov: registered, never answered (no mail loop)", + "message_id": "sim-auto-reply", + "received_at": "2026-11-06T14:25:00Z", + "from": "info@fedramp.gov", + "envelope": "info@fedramp.gov", + "subject": "Automatic reply: Received: FedRAMP Security Inbox exercise", + "headers": { + "Auto-Submitted": "auto-replied", + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:auto-submitted", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:25:00Z", + "respond_by": null + } + }, + { + "case": "look-alike", + "description": "Emergency from a look-alike domain (fedramp.gov.attacker.invalid): not FedRAMP, exact domains only", + "message_id": "sim-look-alike", + "received_at": "2026-11-06T14:30:00Z", + "from": "fedramp_security@fedramp.gov.attacker.invalid", + "envelope": "fedramp_security@fedramp.gov.attacker.invalid", + "subject": "EMERGENCY: act now", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "other", + "designation": "GENERAL", + "sender_domain": "fedramp.gov.attacker.invalid", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "none", + "in_reply_to": null, + "page": false, + "triage_by": null, + "respond_by": null + } + }, + { + "case": "display-name-spoof", + "description": "Display name impersonates the gsa.gov Emergency sender, actual address does not: not FedRAMP", + "message_id": "sim-display-name-spoof", + "received_at": "2026-11-06T14:35:00Z", + "from": "\"fedramp_security@gsa.gov\" ", + "envelope": "attacker@attacker.invalid", + "subject": "EMERGENCY: trust me", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "other", + "designation": "GENERAL", + "sender_domain": "attacker.invalid", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "none", + "in_reply_to": null, + "page": false, + "triage_by": null, + "respond_by": null + } + }, + { + "case": "envelope-only", + "description": "Unreadable From header, @gsa.gov envelope sender: still FedRAMP, registered and paged; no reply without a From address", + "message_id": "sim-envelope-only", + "received_at": "2026-11-06T14:40:00Z", + "from": "garbage <<>>", + "envelope": "bounces@gsa.gov", + "subject": "Important: please confirm", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "IMPORTANT", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:no-from-address", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-07T14:40:00Z", + "respond_by": null + } + }, + { + "case": "emergency-other-sender", + "description": "Emergency from an @gsa.gov address other than the designated Emergency senders (AFC-FRP-UFS): flagged, not demoted, still paged", + "message_id": "sim-emergency-other-sender", + "received_at": "2026-11-06T14:45:00Z", + "from": "Someone ", + "envelope": "someone@gsa.gov", + "subject": "EMERGENCY: rotate your keys", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": false, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-06T16:45:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "bulk", + "description": "Bulk mail from @gsa.gov: registered, not answered", + "message_id": "sim-bulk", + "received_at": "2026-11-06T14:50:00Z", + "from": "news@gsa.gov", + "envelope": "news@gsa.gov", + "subject": "Newsletter", + "headers": { + "Precedence": "bulk" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:precedence", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:50:00Z", + "respond_by": null + } + }, + { + "case": "bounce", + "description": "A bounce (null envelope sender) from @gsa.gov: registered, not answered", + "message_id": "sim-bounce", + "received_at": "2026-11-06T14:55:00Z", + "from": "mailer-daemon@gsa.gov", + "envelope": "<>", + "subject": "Undeliverable: Received: FedRAMP program update", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:null-sender", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:55:00Z", + "respond_by": null + } + }, + { + "case": "ack-send-fails", + "description": "The first acknowledgement attempt fails: recorded as failed, reported overdue, and sent exactly once on the retry", + "message_id": "sim-ack-send-fails", + "received_at": "2026-11-06T15:00:00Z", + "simulate_send_failure": true, + "from": "info@fedramp.gov", + "envelope": "info@fedramp.gov", + "subject": "Checking in", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "failed", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T15:00:00Z", + "respond_by": null + } + } + ] +} diff --git a/docs/cr26-applicability.md b/docs/cr26-applicability.md index 642739e1..30052eba 100644 --- a/docs/cr26-applicability.md +++ b/docs/cr26-applicability.md @@ -24,7 +24,8 @@ The POA&M is retired (2026-11-04): CR26 has no POA&M. Open findings and their de - **IVV — Independent Verification and Validation.** `IVV-CSO-FIA` (Class C MUST) requires a persistent independent assessment by a **FedRAMP Recognized independent assessment service** (the artifact formerly called a 3PAO) or by FedRAMP. This system is self-attested and has engaged no such assessor, so the *independent* half cannot be met. The provider-side verification and validation an assessor would consume **are** produced (in the Security Decision Record); the independent half is unmet by design and recorded N/A. - **MKT — Marketplace Listing.** `MKT-IIP-AGU` requires demonstrating the offering is for agency use within 44 USC § 3506 scope, and the rule text is explicit that *"services used by private companies to meet other compliance requirements (such as CMMC) that do not also meet one of the above use cases are outside the scope of FedRAMP."* There is no agency use case and no intent to list, so MKT is N/A by statutory scope. -- **AFC — Addressing FedRAMP Communication.** `AFC-CSO-INB` and the rest require maintaining a FedRAMP Security Inbox and handling FedRAMP correspondence. With no listing and no sponsor, FedRAMP has no reason to correspond, so there is no channel to maintain. AFC's grace period already ended **2026-07-01**; it is recorded N/A absent a sponsor. - **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so in practice no incident is FedRAMP-reportable. Every incident is still evaluated and recorded in `data/incidents.json`; reportable ones get Initial, Ongoing and Final reports in FedRAMP's schema, on the Class C clocks, published under `/.well-known/` (publish-only: nothing is sent). Exercised 2026-11-05 with simulated incidents marked as exercises; see `docs/incident-response.md`. -These four are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. +These three are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. + +**AFC — Addressing FedRAMP Communication** is no longer recorded N/A (operator's decision, 2026-11-05): it is implemented against a *simulated* FedRAMP Security Inbox. The inbox logic (`scripts/_fsi.py`) runs on every deploy over committed synthetic messages and publishes `/.well-known/fedramp-inbox-simulation.json`, labelled as a simulation; no mail is received or sent, and the published contact sends FedRAMP to the operator on LinkedIn. See `docs/runbooks/fedramp-security-inbox.md`. diff --git a/docs/incident-response.md b/docs/incident-response.md index bae342b8..657682a8 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -134,5 +134,5 @@ Single-tier. Author → author. External escalations: - **GitHub Support** — if the issue is GitHub-side (account, repo, workflow infrastructure) - The mailbox in `security.txt` for acknowledging external reporters -There is no actual FedRAMP certification in scope, so the FedRAMP Security Inbox (FSI) does not apply. Incident reports under the FedRAMP Incident Evaluation and Communication rules are generated and published as described above; they are not sent. +There is no actual FedRAMP certification in scope. Incident reports under the FedRAMP Incident Evaluation and Communication rules are generated and published as described above; they are not sent. The FedRAMP Security Inbox (FSI) is simulated for this proof of concept: no mail is received or sent, and its published contact directs FedRAMP to the operator on LinkedIn (`docs/runbooks/fedramp-security-inbox.md`). diff --git a/docs/policies/ir-policy.md b/docs/policies/ir-policy.md index 03c4e0db..aa3bd3e3 100644 --- a/docs/policies/ir-policy.md +++ b/docs/policies/ir-policy.md @@ -7,7 +7,7 @@ External communication paths: - **Public reporter:** [`/.well-known/security.txt`](../../website/.well-known/security.txt) is the published vulnerability-reporting mailbox. - **FedRAMP incident reports (IEC):** every incident is recorded in the incident register, [`data/incidents.json`](../../data/incidents.json), with its reportability evaluation. Initial, Ongoing and Final Incident Reports for a FedRAMP Reportable Incident are generated from it, validated against FedRAMP's incident report schema, signed, and published under `/.well-known/` (the incident log is `/.well-known/incident-reports.json`) by an unattended workflow on every change to the register. - **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency. The operator has not authorized sending, and the system has no FedRAMP certification and no agency customers. Choosing a delivery channel is an operator decision; until it is made, publication is the only channel and every report says so. -- **FedRAMP Security Inbox (FSI, 20x):** the system is not FedRAMP-certified; no actual FSI obligation applies. Notification path is documented in the runbook for reference. +- **FedRAMP Security Inbox (FSI, 20x):** simulated for this proof of concept. No mail is received or sent; the inbox logic runs on every deploy over synthetic messages and its result is published as `/.well-known/fedramp-inbox-simulation.json`. The published contact directs FedRAMP to the operator on LinkedIn. Procedure: `docs/runbooks/fedramp-security-inbox.md`. **20x rule integration.** KSI-INR (Incident Response), IEC (Incident Evaluation and Communication), FSI (FedRAMP Security Inbox). diff --git a/docs/runbooks/fedramp-security-inbox.md b/docs/runbooks/fedramp-security-inbox.md new file mode 100644 index 00000000..a2d053f4 --- /dev/null +++ b/docs/runbooks/fedramp-security-inbox.md @@ -0,0 +1,78 @@ +# FedRAMP Security Inbox (simulated) + +> **This inbox is a simulation.** By the operator's decision, the FedRAMP Security Inbox does not exist for this proof of concept. No mail is received and none is sent. Its published contact reads: "Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/". + +Rules: AFC-CSO-INB, TFG, RCV, CRA, EMR, IMA, ACK and NOC (FedRAMP Consolidated Rules 2026, AFC family). + +## What is real and what is simulated + +| Part | Real or simulated | +|---|---| +| Inbox logic (`scripts/_fsi.py`): classification, designators, deadlines, register, acknowledgement, paging | Real code, tested | +| Messages from FedRAMP | Simulated: synthetic messages in `data/fsi-simulation/messages.json` | +| Mail system (receiving, sending acknowledgements, delivering pages) | Simulated: outbound legs are recorded, never sent | +| Published contact (`data/cds/offering.json`, `fedramp_security_inbox.contact`, published in the CPO) | Real, and it says it is a simulation | +| Change-notice check (AFC-CSO-NOC, `scripts/check-fsi-notice.py`) | Real, runs on every pull request and push | + +## What runs on every deploy + +The deploy step "FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" runs before the Security Decision Record is built. It calls `scripts/build-fsi-simulation.py`, which: + +1. Runs each synthetic message through the inbox logic: + - an Emergency Test from FedRAMP's Emergency sender; + - an Important message that tries to inject a header; + - a general message; + - a forged @gsa.gov Emergency that fails SPF, DKIM and DMARC; + - an auto-reply, bulk mail and a bounce; + - a message with an unreadable From line and a FedRAMP envelope sender; + - an Emergency from a non-designated sender; + - a look-alike domain and a display-name spoof; + - a message whose first acknowledgement attempt fails. +2. Compares every outcome with the expected one written beside the message: + - classification, designation and sender checks; + - whether the acknowledgement is sent or suppressed, and why; + - the page; + - the deadlines. +3. Checks each acknowledgement for header safety. Then it runs the messages again, and the retry pass must send only the failed acknowledgement and nothing twice. +4. Exercises the register: + - overdue items; + - an Important message refused triage until its stated timeframe is recorded; + - an Emergency reported once past its deadline until it is closed. +5. Exits 1 and writes nothing if any outcome differs. That fails the deploy before anything is published. + +On success, the deploy signs `fedramp-inbox-simulation.json` and publishes it at `/.well-known/fedramp-inbox-simulation.json`. The file is labelled `"simulation": true` and holds sender domains only. Its freshness is governed by `infrastructure/schemas/freshness-config.json`. + +## Reading the published result + +- `result` is `pass` on every published copy, because a failing run publishes nothing. +- `cases[].observed` shows what the logic did with each synthetic message. +- `register_check.checks[]` lists each register behaviour with its expected and observed values. +- `retry_pass` shows that redelivery sends nothing twice. + +## Changing a simulated outcome or adding a case + +Edit `data/fsi-simulation/messages.json`, including the `expected` block, and run: + + python3 scripts/build-fsi-simulation.py --output /tmp/fsi-sim.json + python3 -m pytest tests/test_fedramp_inbox.py + +`tests/fixtures/fsi/simulation-wrong-expectation.json` must stay identical to the messages file except for its one wrong expectation. A test enforces this. + +## Changing the published contact (AFC-CSO-NOC) + +1. Notify FedRAMP through the "[CSP] Notification of Changes" form on help.fedramp.gov. For this simulated system, that step is itself hypothetical. +2. In `data/cds/offering.json`, append a `history` entry with the new contact, `since`, and `fedramp_notified: {"on": "YYYY-MM-DD", "channel": "..."}`. +3. Change `contact`. + +`scripts/check-fsi-notice.py` fails the pull request if the contact changes without that entry, or if the history is rewritten. + +## What a real inbox would need + +A real inbox would need four things: + +- a mail receiver for an address on the system's domain; +- storage for received messages; +- authenticated outbound mail for acknowledgements; +- delivery of pages to the operator. + +`scripts/_fsi.py` is written to be the logic behind them. None of this is deployed, by decision. diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index c81d4307..ccb9eb40 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -169,6 +169,18 @@ "signed": true, "signature": ".well-known/ongoing-certification-report.bundle" }, + { + "path": ".well-known/fedramp-inbox-simulation.json", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "json", + "field": "emitted_at" + }, + "signed": true, + "signature": ".well-known/fedramp-inbox-simulation.bundle", + "note": "SIMULATION: the FedRAMP Security Inbox is simulated for this proof of concept; this is the deploy's run of the inbox logic over synthetic messages." + }, { "path": ".well-known/certification-overview-package.json", "cadence": "deploy", diff --git a/scripts/_fsi.py b/scripts/_fsi.py new file mode 100644 index 00000000..d9f0a7c4 --- /dev/null +++ b/scripts/_fsi.py @@ -0,0 +1,322 @@ +"""FedRAMP Security Inbox logic, as pure functions (no I/O, no network). + +The FedRAMP Security Inbox is SIMULATED for this proof of concept, by the +operator's decision: no mail is received and none is sent. This module is the +logic a real inbox would run, and scripts/build-fsi-simulation.py runs it on +every deploy over committed synthetic messages (data/fsi-simulation/), failing +the deploy if any outcome differs from what the message file expects. + +Rules the logic implements (FedRAMP Consolidated Rules 2026, AFC family): + AFC-CSO-TFG mail from @fedramp.gov or @gsa.gov (exact domains) is FedRAMP + by default, whatever its spam or authentication verdict + AFC-CSO-EMR Emergency-designated mail pages the senior security official + AFC-CSO-CRA Emergency / Emergency Test mail gets a tracked deadline + AFC-CSO-IMA Important mail gets a tracked item, triaged with its timeframe + AFC-CSO-ACK FedRAMP mail is acknowledged automatically, once +with the designators from AFC-FRP-CDS, the Emergency senders from AFC-FRP-UFS +and the default Class C timeframe from AFC-FRP-ERT. + +Every string taken from a message is untrusted: it is length-capped and +stripped of control and bidirectional-override characters before it is stored +or used, and nothing from a message reaches an outbound header except as a +validated address, a validated Message-ID, or base64. +""" + +from __future__ import annotations + +import base64 +import re +from datetime import datetime, timedelta, timezone +from zoneinfo import ZoneInfo + +FEDRAMP_DOMAINS = ("fedramp.gov", "gsa.gov") +EMERGENCY_SENDERS = ("fedramp_security@gsa.gov", "fedramp_security@fedramp.gov") +DESIGNATIONS = ("EMERGENCY", "EMERGENCY_TEST", "IMPORTANT", "GENERAL") +TRIAGE_HOURS = {"EMERGENCY": 2, "EMERGENCY_TEST": 2, "IMPORTANT": 24, "GENERAL": 72} +CLASS_C_BUSINESS_DAYS = 2 +CLASS_C_HOUR_ET = 15 +VERDICTS = ("PASS", "FAIL", "GRAY", "PROCESSING_FAILED") +MAX_SUBJECT = 200 +MAX_ADDRESS = 254 +ET = ZoneInfo("America/New_York") + +CONTROL = re.compile("[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]") +ADDR_SPEC = re.compile(r"^[a-z0-9!#$%&'*+/=?^_`{|}~.-]{1,64}@[a-z0-9-]{1,63}(?:\.[a-z0-9-]{1,63})+$") +RFC_MESSAGE_ID = re.compile(r"^<[\x21-\x3b\x3d\x3f-\x7e]{1,250}>$") +ANGLED = re.compile(r"<([^<>\s]+)>") +LABEL = {"EMERGENCY": "EMERGENCY", "EMERGENCY_TEST": "EMERGENCY TEST", "IMPORTANT": "IMPORTANT", "GENERAL": "General"} + + +def clean_text(value, limit: int = MAX_SUBJECT) -> str: + """One safe line: no control or bidi characters, whitespace collapsed, capped.""" + s = CONTROL.sub(" ", "" if value is None else str(value)) + return " ".join(s.split())[:limit] + + +def parse_address(value) -> str | None: + """The addr-spec in a From-style value, lower-cased, or None.""" + s = clean_text(value, 1000) + if not s: + return None + angled = ANGLED.findall(s) + candidate = (angled[-1] if angled else s).lower() + if len(candidate) > MAX_ADDRESS or not ADDR_SPEC.match(candidate): + return None + return candidate + + +def domain_of(address: str | None) -> str | None: + return address.rsplit("@", 1)[1] if address else None + + +def is_fedramp_address(address: str | None) -> bool: + """AFC-CSO-TFG: exact domains only. Subdomains and look-alikes are not FedRAMP.""" + return domain_of(address) in FEDRAMP_DOMAINS + + +def designation_of(subject) -> str: + """AFC-FRP-CDS designator anywhere in the subject, any case. Broad on purpose: + a false Emergency costs a page; a missed one costs the deadline.""" + s = clean_text(subject, 1000).lower() + if re.search(r"\bemergency[\s_-]*test\b", s): + return "EMERGENCY_TEST" + if re.search(r"\bemergency\b", s): + return "EMERGENCY" + if re.search(r"\bimportant\b", s): + return "IMPORTANT" + return "GENERAL" + + +def _header(headers, name: str) -> str | None: + want = name.lower() + for k, v in (headers or {}).items(): + if isinstance(k, str) and k.lower() == want: + return clean_text(v, 1000) + return None + + +def _verdict(v) -> str: + s = v.upper() if isinstance(v, str) else "MISSING" + return s if s in VERDICTS else "MISSING" + + +def authenticated(auth: dict) -> bool: + """AFC-FRP-VRE: FedRAMP sends with SPF, DKIM and DMARC configured.""" + return auth["dmarc"] == "PASS" or (auth["dkim"] == "PASS" and auth["spf"] == "PASS") + + +def loop_reason(headers, source, sender: str | None) -> str | None: + """Why an automatic reply must not be sent to this message, or None.""" + auto = _header(headers, "auto-submitted") + if auto and auto.lower() != "no": + return "auto-submitted" + if (_header(headers, "precedence") or "").lower() in ("bulk", "junk", "list", "auto_reply"): + return "precedence" + src = str(source or "").strip() + if not src or src == "<>": + return "null-sender" + if sender and sender.split("@", 1)[0] in ("mailer-daemon", "postmaster"): + return "daemon" + if not sender: + return "no-from-address" + return None + + +def classify(msg: dict) -> dict: + """Classify one message: {from, envelope, subject, headers, auth}. + + FedRAMP if the From address or the envelope sender is at an exact FedRAMP + domain. Spam and authentication verdicts are recorded and never change the + classification. They do stop the acknowledgement: FedRAMP's own mail passes + SPF/DKIM/DMARC, so suppressing the reply to unauthenticated mail loses + nothing genuine and stops a forged @gsa.gov From from turning the inbox into + a reflector that mails attacker-chosen text to any government address. + """ + sender = parse_address(msg.get("from")) + envelope = parse_address(msg.get("envelope")) + subject = clean_text(msg.get("subject")) + fedramp = is_fedramp_address(sender) or is_fedramp_address(envelope) + designation = designation_of(subject) if fedramp else "GENERAL" + raw_auth = msg.get("auth") or {} + auth = {k: _verdict(raw_auth.get(k)) for k in ("spf", "dkim", "dmarc")} + authed = authenticated(auth) + emergency = designation in ("EMERGENCY", "EMERGENCY_TEST") + mid = _header(msg.get("headers"), "message-id") + return { + "kind": "fedramp" if fedramp else "other", + "from": sender, + "sender_domain": domain_of(sender if is_fedramp_address(sender) else (envelope or sender)), + "subject": subject, + "designation": designation, + "auth": auth, + "authenticated": authed, + "emergency_sender_ok": (sender in EMERGENCY_SENDERS) if emergency else None, + "rfc_message_id": mid if mid and RFC_MESSAGE_ID.match(mid) else None, + "loop": loop_reason(msg.get("headers"), msg.get("envelope"), sender) or (None if authed else "unauthenticated"), + } + + +# --- deadlines ---------------------------------------------------------------- + +def parse_time(value: str) -> datetime: + t = datetime.fromisoformat(str(value).replace("Z", "+00:00")) + if t.tzinfo is None: + raise ValueError(f"timestamp without a zone: {value!r}") + return t.astimezone(timezone.utc) + + +def iso(t: datetime) -> str: + return t.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def class_c_deadline(received: datetime, business_days: int = CLASS_C_BUSINESS_DAYS, + hour_et: int = CLASS_C_HOUR_ET) -> datetime: + """3:00 p.m. ET on the Nth business day, counting the day of receipt as day 1 + when it is a weekday. That reading of "the 2nd business day" gives the + earlier of the two possible deadlines, and federal holidays are not skipped, + which can only make it earlier still. Both err toward acting sooner.""" + day = received.astimezone(ET).date() + counted = 0 + for _ in range(14): + if day.weekday() < 5: + counted += 1 + if counted == business_days: + return datetime(day.year, day.month, day.day, hour_et, tzinfo=ET).astimezone(timezone.utc) + day += timedelta(days=1) + raise RuntimeError("business-day search did not terminate") + + +def deadlines(designation: str, received: datetime) -> dict: + triage_by = iso(received + timedelta(hours=TRIAGE_HOURS[designation])) + if designation in ("EMERGENCY", "EMERGENCY_TEST"): + return {"triage_by": triage_by, "respond_by": iso(class_c_deadline(received)), + "deadline_basis": "AFC-FRP-ERT Class C default (3:00 p.m. ET, 2nd business day); " + "replace with the timeframe stated in the message"} + if designation == "IMPORTANT": + return {"triage_by": triage_by, "respond_by": None, + "deadline_basis": "Record the timeframe stated in the message (AFC-CSO-IMA) when triaging"} + return {"triage_by": triage_by, "respond_by": None, + "deadline_basis": "General communication: no elevated timeframe (AFC-FRP-CDS)"} + + +# --- register ------------------------------------------------------------------- + +def new_record(rid: str, c: dict, received: datetime) -> dict: + return {"id": rid, "received_at": iso(received), "kind": c["kind"], "sender_domain": c["sender_domain"], + "subject": c["subject"], "designation": c["designation"], "auth": c["auth"], + "authenticated": c["authenticated"], "emergency_sender_ok": c["emergency_sender_ok"], + "status": "open", **deadlines(c["designation"], received), + "ack": {"status": "pending"}, "page": {"status": "pending"}, "history": []} + + +def triage(record: dict, at: datetime, respond_by: str | None = None) -> dict: + """Mark a record triaged. An Important message cannot be triaged without the + timeframe stated in it (AFC-CSO-IMA); a stated timeframe replaces the default.""" + if record["status"] == "closed": + raise ValueError(f"{record['id']} is closed") + if respond_by: + record["respond_by"] = iso(parse_time(respond_by)) + record["deadline_basis"] = "Timeframe stated in the message, recorded at triage" + if record["designation"] == "IMPORTANT" and not record.get("respond_by"): + raise ValueError(f"{record['id']}: an Important message needs the timeframe it states (respond_by)") + record["status"] = "triaged" + record["history"].append({"at": iso(at), "event": "triaged"}) + return record + + +def close(record: dict, at: datetime, outcome: str) -> dict: + if not clean_text(outcome): + raise ValueError("closing needs an outcome") + record["status"] = "closed" + record["closed_at"] = iso(at) + record["history"].append({"at": iso(at), "event": "closed", "outcome": clean_text(outcome)}) + return record + + +def overdue(records, now: datetime) -> list[str]: + """Problems that should page: untriaged past triage_by, not closed past + respond_by, Important triaged without its timeframe, ack or page failed.""" + problems = [] + for r in records: + tag = f"{r['id']} ({r['designation']})" + if r["status"] == "open" and r.get("triage_by") and now > parse_time(r["triage_by"]): + problems.append(f"{tag}: not triaged by {r['triage_by']}") + if r["status"] != "closed" and r.get("respond_by") and now > parse_time(r["respond_by"]): + problems.append(f"{tag}: required actions not closed by {r['respond_by']}") + if r["designation"] == "IMPORTANT" and r["status"] != "open" and not r.get("respond_by"): + problems.append(f"{tag}: triaged without recording the message's timeframe") + for leg in ("ack", "page"): + if (r.get(leg) or {}).get("status") == "failed": + problems.append(f"{tag}: {leg} failed") + return problems + + +# --- outbound text ------------------------------------------------------------------ + +def _b64(s: str) -> str: + return base64.b64encode(s.encode("utf-8")).decode("ascii") + + +def build_ack(*, inbox: str, to: str, subject: str, rfc_message_id: str | None, + received_at: str, designation: str, ref: str) -> str: + """The raw acknowledgement (RFC 5322). Every header value is a constant, a + validated address, a validated Message-ID, or base64, so nothing from the + inbound message can inject a header.""" + frm, rcpt = parse_address(inbox), parse_address(to) + if not frm or not rcpt: + raise ValueError("acknowledgement needs valid From and To addresses") + subj = clean_text(subject) or "(no subject)" + lines = [f"From: FedRAMP Security Inbox <{frm}>", f"To: <{rcpt}>", + f"Subject: =?UTF-8?B?{_b64('Received: ' + subj)}?=", + "Auto-Submitted: auto-replied", "X-Auto-Response-Suppress: All", "MIME-Version: 1.0", + "Content-Type: text/plain; charset=UTF-8", "Content-Transfer-Encoding: base64"] + if rfc_message_id and RFC_MESSAGE_ID.match(rfc_message_id): + lines += [f"In-Reply-To: {rfc_message_id}", f"References: {rfc_message_id}"] + body = "\n".join([ + f"This is an automatic acknowledgement from the FedRAMP Security Inbox ({frm}).", "", + f"Your message was received at {clean_text(received_at, 40)}.", + f"Designation recognised from the subject line: {LABEL.get(designation, 'General')}.", + f"Reference: {clean_text(ref, 80)}", "", + "The security official has been notified. This reply is automatic; a person will respond separately."]) + b64 = _b64(body) + wrapped = "\r\n".join(b64[i:i + 76] for i in range(0, len(b64), 76)) + return "\r\n".join(lines) + "\r\n\r\n" + wrapped + "\r\n" + + +def page_subject(record: dict) -> str: + """The page's subject: ASCII, at most 100 characters, sender domain only.""" + s = f"[FSI] {LABEL.get(record['designation'], 'General')} FedRAMP message from {record['sender_domain'] or 'unknown'}" + return re.sub(r"[^\x20-\x7e]", "?", s)[:100] + + +# --- one message through the inbox ------------------------------------------------------ + +def receive(msg: dict, register: dict, *, inbox: str, send, page) -> dict: + """Handle one message the way the inbox would. `send(to, raw)` and + `page(subject)` are the outbound legs (in the simulation, recorders that + send nothing). Idempotent: a message already in the register only retries + the legs that did not complete, so a sender is acknowledged once.""" + c = classify(msg) + if c["kind"] != "fedramp": + return {"classification": c, "record": None} + rid = clean_text(msg.get("message_id"), 128) + if not re.fullmatch(r"[A-Za-z0-9._-]{1,128}", rid): + raise ValueError("message_id must be a safe register identifier") + received = parse_time(msg["received_at"]) + record = register.get(rid) or new_record(rid, c, received) + register[rid] = record + if record["ack"]["status"] in ("pending", "failed"): + if c["loop"]: + record["ack"] = {"status": "suppressed", "reason": c["loop"]} + else: + try: + send(c["from"], build_ack(inbox=inbox, to=c["from"], subject=c["subject"], + rfc_message_id=c["rfc_message_id"], received_at=record["received_at"], + designation=c["designation"], ref=rid)) + record["ack"] = {"status": "sent"} + except Exception as e: # noqa: BLE001 - a failed leg is recorded and paged by overdue() + record["ack"] = {"status": "failed", "error": type(e).__name__} + if record["page"]["status"] != "sent": + page(page_subject(record)) + record["page"] = {"status": "sent"} + return {"classification": c, "record": record} diff --git a/scripts/build-cpo.py b/scripts/build-cpo.py index fb5162ef..892933f2 100644 --- a/scripts/build-cpo.py +++ b/scripts/build-cpo.py @@ -61,6 +61,18 @@ } +def _fsi(off): + """The FedRAMP Security Inbox as published. The inbox is simulated for this + proof of concept, so this is a contact statement, never an email address, + plus the simulation's published results. The change history stays in the + repository.""" + fsi = off.get("fedramp_security_inbox") + if not fsi: + return None + return {"simulated": True, "contact": fsi["contact"], "rule": "AFC-CSO-INB", + "simulation": fsi.get("simulation"), "runbook": fsi.get("runbook")} + + def main(): ap = argparse.ArgumentParser() ap.add_argument("--offering", default="../data/cds/offering.json") @@ -102,6 +114,9 @@ def main(): "service_model": off.get("service_model"), "deployment_model": off.get("deployment_model"), "security_contact": off.get("security_contact"), + # AFC-CSO-INB: the FedRAMP Security Inbox contact, from its one + # source. Simulated for this proof of concept (no mail is received). + "fedramp_security_inbox": _fsi(off), "overview_package": BASE + "certification-overview-package.json", }, "minimum_assessment_scope": { # MAS @@ -141,6 +156,8 @@ def render_markdown(c): out = ["# Certification Package Overview", "", f"_{c['note']}_", "", f"- **Accountable official:** {ao.get('name')}, {ao.get('title')} ({ao.get('contact')})", + f"- **FedRAMP Security Inbox (AFC-CSO-INB):** " + f"{(c['certification_data'].get('fedramp_security_inbox') or {}).get('contact', 'not established')}", f"- **Class:** {c['class']} | **Impact:** {c['impact_level_canonical']}", f"- **Version:** {c['metadata']['version']} | **Last updated:** {c['metadata']['last_updated']}", f"- **Maintenance:** {c['maintenance_cadence']}", diff --git a/scripts/build-fsi-simulation.py b/scripts/build-fsi-simulation.py new file mode 100644 index 00000000..71174f6a --- /dev/null +++ b/scripts/build-fsi-simulation.py @@ -0,0 +1,221 @@ +#!/usr/bin/env python3 +"""Run the SIMULATED FedRAMP Security Inbox over committed synthetic messages. + +The FedRAMP Security Inbox is simulated for this proof of concept, by the +operator's decision: nothing real is received or sent. This script feeds the +synthetic messages in data/fsi-simulation/messages.json through the inbox logic +(scripts/_fsi.py) with outbound legs that only record what they would have +sent, then checks every observed outcome against the file's "expected" block: + + - classification (AFC-CSO-TFG: exact @fedramp.gov / @gsa.gov, never filtered) + - designation, Emergency sender, and the default deadlines (AFC-CSO-CRA/EMR/IMA) + - the acknowledgement (AFC-CSO-ACK): built and header-injection safe when + sent; suppressed for auto-replies and for mail failing SPF/DKIM/DMARC + - every FedRAMP message is registered and paged (AFC-CSO-RCV) + - a failed acknowledgement is recorded and reported, and a retry pass over + the same messages sends it once and sends nothing twice + - the triage register: overdue items; an Important message refused triage + until its stated timeframe is recorded; an Emergency past its deadline + reported until closed + +Any difference exits 1 and writes nothing, which fails the deploy. On success it +writes fedramp-inbox-simulation.json, labelled as a simulation, with sender +domains only (no addresses, no subjects), for the deploy to sign and publish. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import sys +from datetime import datetime, timezone +from email import policy +from email.parser import Parser +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _fsi # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +ACK_HEADERS = {"from", "to", "subject", "auto-submitted", "x-auto-response-suppress", "mime-version", + "content-type", "content-transfer-encoding", "in-reply-to", "references"} +NOTICE = ("SIMULATION. The FedRAMP Security Inbox is simulated for this proof of concept, by the operator's " + "decision: no mail is received and none is sent. Nothing arrived, nothing was acknowledged, and no FedRAMP " + "staff were paged, emailed or otherwise inconvenienced. These results come from running the inbox logic over " + "committed synthetic messages on every deploy; a deploy whose results differ from the expected ones fails. " + "To reach the operator, see 'contact' (spoiler: it is LinkedIn).") +RULES = ["AFC-CSO-INB", "AFC-CSO-TFG", "AFC-CSO-RCV", "AFC-CSO-CRA", "AFC-CSO-EMR", "AFC-CSO-IMA", "AFC-CSO-ACK"] + + +def ack_problems(raw: str, to: str, subject: str) -> list[str]: + """Why a built acknowledgement is unsafe or wrong, or [].""" + out = [] + head = raw.split("\r\n\r\n", 1)[0] + for line in head.split("\r\n"): + if "\n" in line or "\r" in line or ":" not in line: + out.append("a header line is malformed") + msg = Parser(policy=policy.default).parsestr(raw) + names = [k.lower() for k in msg.keys()] + if set(names) - ACK_HEADERS: + out.append(f"unexpected headers {sorted(set(names) - ACK_HEADERS)}") + if len(names) != len(set(names)): + out.append("a header appears twice") + if [ln for ln in head.split("\r\n") if ln.lower().startswith("to:")] != [f"To: <{to}>"]: + out.append("To is not exactly the sender") + if str(msg["subject"]) != "Received: " + (subject or "(no subject)"): + out.append("the subject does not round-trip") + if msg["auto-submitted"] != "auto-replied": + out.append("Auto-Submitted: auto-replied is missing") + return out + + +def run(doc: dict) -> tuple[list[dict], dict, dict, list[str]]: + inbox = doc["inbox"] + register: dict = {} + sent: list[tuple[str, str]] = [] + pages: list[str] = [] + fail_once = {m["message_id"] for m in doc["messages"] if m.get("simulate_send_failure")} + current = {"id": None} + + def send(to, raw): # records only; nothing is sent + if current["id"] in fail_once: + fail_once.discard(current["id"]) + raise ConnectionError("simulated send failure") + sent.append((to, raw)) + + page = pages.append + failures: list[str] = [] + cases = [] + for m in doc["messages"]: + n_sent, n_pages = len(sent), len(pages) + current["id"] = m["message_id"] + res = _fsi.receive(m, register, inbox=inbox, send=send, page=page) + c, r = res["classification"], res["record"] + ack = "none" + in_reply_to = None + if r: + ack = r["ack"]["status"] + (f":{r['ack']['reason']}" if r["ack"].get("reason") else "") + if len(sent) > n_sent: + to, raw = sent[-1] + for p in ack_problems(raw, c["from"], c["subject"]): + failures.append(f"{m['case']}: acknowledgement {p}") + in_reply_to = "\r\nIn-Reply-To: " in raw + observed = {"kind": c["kind"], "designation": c["designation"], "sender_domain": c["sender_domain"], + "authenticated": c["authenticated"], "emergency_sender_ok": c["emergency_sender_ok"], + "ack": ack, "in_reply_to": in_reply_to, "page": len(pages) > n_pages, + "triage_by": r["triage_by"] if r else None, "respond_by": r["respond_by"] if r else None} + # AFC-CSO-RCV: nothing FedRAMP is dropped: every FedRAMP message is + # registered and paged, whatever its verdicts. + if c["kind"] == "fedramp" and not (r and observed["page"]): + failures.append(f"{m['case']}: a FedRAMP message was not registered and paged") + diffs = sorted(k for k, v in m["expected"].items() if observed.get(k) != v) + diffs += sorted(set(observed) - set(m["expected"])) + for k in diffs: + failures.append(f"{m['case']}: {k} expected {m['expected'].get(k)!r}, observed {observed.get(k)!r}") + cases.append({"case": m["case"], "description": m["description"], "received_at": m["received_at"], + "auth": c["auth"], "observed": observed, "matches_expected": not diffs}) + + rc = doc["register_check"] + checks: list[dict] = [] + + def check(name, expected, observed): + checks.append({"check": name, "expected": expected, "observed": observed, "ok": expected == observed}) + if expected != observed: + failures.append(f"register: {name}: expected {expected!r}, observed {observed!r}") + + def overdue_ids(at): + return sorted({p.split(" ", 1)[0] for p in _fsi.overdue(register.values(), at)}) + + def reported(rid, at, needle): + return any(p.startswith(rid + " ") and needle in p for p in _fsi.overdue(register.values(), at)) + + now = _fsi.parse_time(rc["now"]) + check(f"items overdue at {rc['now']} (untriaged Emergencies, a failed acknowledgement)", + sorted(rc["expected_overdue"]), overdue_ids(now)) + + # Retry: the same messages again (a redelivery or a retried invocation). + before = (len(sent), len(pages)) + for m in doc["messages"]: + current["id"] = m["message_id"] + _fsi.receive(m, register, inbox=inbox, send=send, page=page) + retry = {"acknowledgements_sent_again": len(sent) - before[0], "pages_sent_again": len(pages) - before[1]} + check("retry pass: only the failed acknowledgement is sent again, nothing twice", rc["expected_retry"], retry) + failed_ids = [m["message_id"] for m in doc["messages"] if m.get("simulate_send_failure")] + check("failed acknowledgements are sent on the retry", + ["sent"] * len(failed_ids), [register[i]["ack"]["status"] for i in failed_ids]) + check("a failed acknowledgement, once sent, is no longer overdue", + False, any(reported(i, now, "ack failed") for i in failed_ids)) + + # AFC-CSO-IMA: an Important message cannot be triaged without its timeframe. + imp = register[rc["important_case"]] + try: + _fsi.triage(imp, now) + refused = False + except ValueError: + refused = True + check("Important triage without the message's timeframe is refused", True, refused) + _fsi.triage(imp, now, respond_by=rc["important_respond_by"]) + check("Important triage records the message's timeframe", rc["important_respond_by"], imp["respond_by"]) + later = _fsi.parse_time(rc["later"]) + check("an Important message untriaged after 24 hours is reported", True, + reported(rc["untriaged_important_case"], later, "not triaged")) + forced = dict(imp, id="sim-forced-state", status="triaged", respond_by=None, history=[]) + check("an Important item triaged without a timeframe is reported", True, + any("timeframe" in p for p in _fsi.overdue([forced], now))) + + # AFC-CSO-CRA: an Emergency past its deadline and not closed is reported; + # closing it clears the report. + em = register[rc["emergency_case"]] + _fsi.triage(em, now) + check("a triaged Emergency is no longer reported as untriaged", False, reported(em["id"], now, "not triaged")) + check("an Emergency past its deadline and not closed is reported", True, + reported(em["id"], later, "not closed")) + _fsi.close(em, later, "required actions completed (simulated)") + check("closing the Emergency clears the report", False, reported(em["id"], later, "not closed")) + + register_check = {"now": rc["now"], "later": rc["later"], "checks": checks} + return cases, retry, register_check, failures + + +def main(argv=None) -> int: + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--messages", type=Path, default=REPO / "data" / "fsi-simulation" / "messages.json") + ap.add_argument("--offering", type=Path, default=REPO / "data" / "cds" / "offering.json") + ap.add_argument("--output", type=Path, default=Path("fedramp-inbox-simulation.json")) + a = ap.parse_args(argv) + raw = a.messages.read_bytes() + doc = json.loads(raw) + cases, retry, register_check, failures = run(doc) + for f in failures: + print(f"::error::FedRAMP Security Inbox simulation: {f}") + if failures: + print(f"FedRAMP Security Inbox simulation: {len(failures)} outcome(s) differ from expected; nothing written") + return 1 + contact = ((json.loads(a.offering.read_text()).get("fedramp_security_inbox") or {}).get("contact")) + sha = os.environ.get("GITHUB_SHA", "") + report = { + "report_type": "fedramp-inbox-simulation", + "simulation": True, + "notice": NOTICE, + "contact": contact, + "emitted_at": datetime.now(timezone.utc).isoformat(), + "commit": sha if len(sha) == 40 and all(ch in "0123456789abcdef" for ch in sha) else None, + "logic": "scripts/_fsi.py", + "input": "data/fsi-simulation/messages.json", + "input_sha256": hashlib.sha256(raw).hexdigest(), + "rules_exercised": RULES, + "result": "pass", + "cases": cases, + "retry_pass": retry, + "register_check": register_check, + } + a.output.write_text(json.dumps(report, indent=2) + "\n") + print(f"FedRAMP Security Inbox simulation: {len(cases)} synthetic messages, all outcomes as expected; " + f"wrote {a.output} (SIMULATION: nothing received or sent)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check-fsi-notice.py b/scripts/check-fsi-notice.py new file mode 100644 index 00000000..3481d703 --- /dev/null +++ b/scripts/check-fsi-notice.py @@ -0,0 +1,123 @@ +#!/usr/bin/env python3 +"""AFC-CSO-NOC: a change to the FedRAMP Security Inbox contact must record that +FedRAMP was notified. + +The inbox is simulated for this proof of concept (no mail is received), so what +is published is a contact statement rather than a mailbox. It lives in one +place, data/cds/offering.json (fedramp_security_inbox.contact), with an +append-only history. Each entry after the first is a change, and a change must +carry the notification marker: + + "fedramp_notified": {"on": "YYYY-MM-DD", "channel": ""} + +FedRAMP's channel for this is the "[CSP] Notification of Changes" form on +help.fedramp.gov (the rule's notification target). The first entry establishes +the contact and needs no marker only when there was no earlier contact to +change from; it must say why in "basis". + +Checks (each failure names itself; exit 1 on any): + - the contact is one non-empty line of printable text + - the newest history entry is the current contact + - every later entry changes the contact and carries a dated, non-future + fedramp_notified marker with a channel + - with --base (the same file at the merge base): the history is append-only, + and if the contact changed, the new entries are the ones that say so + +Stdlib only; runs in the unit-test job on every pull request and push. +""" + +from __future__ import annotations + +import argparse +import json +import re +import sys +from datetime import date +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent +DEFAULT = REPO / "data" / "cds" / "offering.json" +CONTACT = re.compile(r"^[\x20-\x7e]{1,300}$") +DAY = re.compile(r"^\d{4}-\d{2}-\d{2}$") + + +def _inbox(doc): + return doc.get("fedramp_security_inbox") if isinstance(doc, dict) else None + + +def _date(value): + if not isinstance(value, str) or not DAY.match(value): + return None + try: + return date.fromisoformat(value) + except ValueError: + return None + + +def check(head: dict, base: dict | None = None, today: date | None = None) -> list[str]: + """Violations of AFC-CSO-NOC in head (and in the step from base to head).""" + today = today or date.today() + out: list[str] = [] + fsi = _inbox(head) + if not isinstance(fsi, dict): + return ["fedramp_security_inbox is missing from data/cds/offering.json (AFC-CSO-INB)"] + contact = fsi.get("contact") + if not isinstance(contact, str) or not CONTACT.match(contact) or not contact.strip(): + out.append("fedramp_security_inbox.contact must be one non-empty line of printable text (at most 300 characters)") + history = fsi.get("history") + if not isinstance(history, list) or not history or not all(isinstance(h, dict) for h in history): + return out + ["fedramp_security_inbox.history must list every contact the inbox has had"] + if history[-1].get("contact") != contact: + out.append("the contact changed without a history entry recording the change and notifying FedRAMP") + first = history[0] + if first.get("fedramp_notified") is None and not (isinstance(first.get("basis"), str) and first["basis"].strip()): + out.append("the first history entry has no fedramp_notified and no basis saying why none was needed") + for i, h in enumerate(history): + since = _date(h.get("since")) + if since is None or since > today: + out.append(f"history[{i}].since must be a date, not in the future") + if i == 0: + continue + if h.get("contact") == history[i - 1].get("contact"): + out.append(f"history[{i}] repeats the previous contact") + marker = h.get("fedramp_notified") + if not isinstance(marker, dict): + out.append(f"history[{i}] changes the contact without a fedramp_notified marker (AFC-CSO-NOC)") + continue + on = _date(marker.get("on")) + if on is None or on > today: + out.append(f"history[{i}].fedramp_notified.on must be the date FedRAMP was notified, not in the future") + channel = marker.get("channel") + if not isinstance(channel, str) or not channel.strip(): + out.append(f"history[{i}].fedramp_notified.channel must say how FedRAMP was notified") + base_fsi = _inbox(base) if base is not None else None + if isinstance(base_fsi, dict): + base_hist = base_fsi.get("history") or [] + if history[:len(base_hist)] != base_hist: + out.append("fedramp_security_inbox.history was rewritten; it is append-only") + if base_fsi.get("contact") != contact and len(history) <= len(base_hist): + out.append("the contact changed but no history entry was added for the change") + return out + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--offering", type=Path, default=DEFAULT) + ap.add_argument("--base", type=Path, help="offering.json at the merge base (optional)") + a = ap.parse_args(argv) + head = json.loads(a.offering.read_text()) + base = None + if a.base and a.base.is_file() and a.base.stat().st_size: + base = json.loads(a.base.read_text()) + problems = check(head, base) + for p in problems: + print(f"::error::FedRAMP Security Inbox (AFC-CSO-NOC): {p}") + if not problems: + fsi = _inbox(head) + print(f"FedRAMP Security Inbox: {len(fsi['history'])} history entr{'y' if len(fsi['history']) == 1 else 'ies'}; " + f"{'compared with the merge base' if base else 'no merge base given'}; ok") + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/fsi/offering-changed-with-notice.json b/tests/fixtures/fsi/offering-changed-with-notice.json new file mode 100644 index 00000000..8b83ed8b --- /dev/null +++ b/tests/fixtures/fsi/offering-changed-with-notice.json @@ -0,0 +1,21 @@ +{ + "fedramp_security_inbox": { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox. Hit me up on LinkedIn (new profile): https://www.linkedin.com/in/example/", + "history": [ + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/", + "since": "2026-11-05", + "fedramp_notified": null, + "basis": "Established. No earlier FedRAMP Security Inbox or Marketplace Security Email is on file with FedRAMP for this unsponsored system, so there was no prior contact to change from." + }, + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox. Hit me up on LinkedIn (new profile): https://www.linkedin.com/in/example/", + "since": "2026-12-01", + "fedramp_notified": { + "on": "2026-11-30", + "channel": "help.fedramp.gov [CSP] Notification of Changes form" + } + } + ] + } +} diff --git a/tests/fixtures/fsi/offering-changed-without-history.json b/tests/fixtures/fsi/offering-changed-without-history.json new file mode 100644 index 00000000..d03a272d --- /dev/null +++ b/tests/fixtures/fsi/offering-changed-without-history.json @@ -0,0 +1,13 @@ +{ + "fedramp_security_inbox": { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox. Hit me up on LinkedIn (new profile): https://www.linkedin.com/in/example/", + "history": [ + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/", + "since": "2026-11-05", + "fedramp_notified": null, + "basis": "Established. No earlier FedRAMP Security Inbox or Marketplace Security Email is on file with FedRAMP for this unsponsored system, so there was no prior contact to change from." + } + ] + } +} diff --git a/tests/fixtures/fsi/offering-changed-without-notice.json b/tests/fixtures/fsi/offering-changed-without-notice.json new file mode 100644 index 00000000..c788d5ee --- /dev/null +++ b/tests/fixtures/fsi/offering-changed-without-notice.json @@ -0,0 +1,17 @@ +{ + "fedramp_security_inbox": { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox. Hit me up on LinkedIn (new profile): https://www.linkedin.com/in/example/", + "history": [ + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/", + "since": "2026-11-05", + "fedramp_notified": null, + "basis": "Established. No earlier FedRAMP Security Inbox or Marketplace Security Email is on file with FedRAMP for this unsponsored system, so there was no prior contact to change from." + }, + { + "contact": "Simulated for this proof of concept: there is no FedRAMP Security Inbox. Hit me up on LinkedIn (new profile): https://www.linkedin.com/in/example/", + "since": "2026-12-01" + } + ] + } +} diff --git a/tests/fixtures/fsi/simulation-wrong-expectation.json b/tests/fixtures/fsi/simulation-wrong-expectation.json new file mode 100644 index 00000000..cad4d96b --- /dev/null +++ b/tests/fixtures/fsi/simulation-wrong-expectation.json @@ -0,0 +1,366 @@ +{ + "_note": "KNOWN-BAD FIXTURE (tests/test_fedramp_inbox.py): identical to data/fsi-simulation/messages.json except that the forged @gsa.gov message is expected to be acknowledged. The simulation must fail on it, because an unauthenticated message is never acknowledged.", + "inbox": "fedramp-security-inbox@simulation.invalid", + "register_check": { + "now": "2026-11-06T17:00:00Z", + "expected_overdue": [ + "sim-ack-send-fails", + "sim-emergency-other-sender", + "sim-emergency-test", + "sim-forged-gsa" + ], + "expected_retry": { + "acknowledgements_sent_again": 1, + "pages_sent_again": 0 + }, + "important_case": "sim-important", + "important_respond_by": "2026-11-10T22:00:00Z", + "later": "2026-11-09T21:00:00Z", + "emergency_case": "sim-emergency-test", + "untriaged_important_case": "sim-envelope-only" + }, + "messages": [ + { + "case": "emergency-test", + "description": "Emergency Test from FedRAMP's Emergency sender (AFC-FRP-UFS), authenticated", + "message_id": "sim-emergency-test", + "received_at": "2026-11-06T14:05:00Z", + "from": "FedRAMP Security ", + "envelope": "fedramp_security@fedramp.gov", + "subject": "EMERGENCY TEST: FedRAMP Security Inbox exercise", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY_TEST", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": true, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-06T16:05:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "important", + "description": "Important message whose subject and Message-ID try to inject a Bcc header", + "message_id": "sim-important", + "received_at": "2026-11-06T14:10:00Z", + "from": "FedRAMP PMO ", + "envelope": "info@fedramp.gov", + "subject": "IMPORTANT: action requested\r\nBcc: injected@attacker.invalid", + "headers": { + "Message-ID": "\r\nBcc: injected@attacker.invalid" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "IMPORTANT", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "sent", + "in_reply_to": false, + "page": true, + "triage_by": "2026-11-07T14:10:00Z", + "respond_by": null + } + }, + { + "case": "general", + "description": "General communication from @gsa.gov, no designator", + "message_id": "sim-general", + "received_at": "2026-11-06T14:15:00Z", + "from": "info@gsa.gov", + "envelope": "info@gsa.gov", + "subject": "FedRAMP program update", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-09T14:15:00Z", + "respond_by": null + } + }, + { + "case": "forged-gsa", + "description": "Forged Emergency claiming to be from the gsa.gov Emergency sender; SPF, DKIM and DMARC fail. Still FedRAMP by default (AFC-CSO-TFG) and paged, but not acknowledged", + "message_id": "sim-forged-gsa", + "received_at": "2026-11-06T14:20:00Z", + "from": "FedRAMP Security ", + "envelope": "bounce@attacker.invalid", + "subject": "EMERGENCY: reply with your credentials", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "FAIL", + "dkim": "FAIL", + "dmarc": "FAIL" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY", + "sender_domain": "gsa.gov", + "authenticated": false, + "emergency_sender_ok": true, + "ack": "sent", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-06T16:20:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "auto-reply", + "description": "An auto-reply from @fedramp.gov: registered, never answered (no mail loop)", + "message_id": "sim-auto-reply", + "received_at": "2026-11-06T14:25:00Z", + "from": "info@fedramp.gov", + "envelope": "info@fedramp.gov", + "subject": "Automatic reply: Received: FedRAMP Security Inbox exercise", + "headers": { + "Auto-Submitted": "auto-replied", + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:auto-submitted", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:25:00Z", + "respond_by": null + } + }, + { + "case": "look-alike", + "description": "Emergency from a look-alike domain (fedramp.gov.attacker.invalid): not FedRAMP, exact domains only", + "message_id": "sim-look-alike", + "received_at": "2026-11-06T14:30:00Z", + "from": "fedramp_security@fedramp.gov.attacker.invalid", + "envelope": "fedramp_security@fedramp.gov.attacker.invalid", + "subject": "EMERGENCY: act now", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "other", + "designation": "GENERAL", + "sender_domain": "fedramp.gov.attacker.invalid", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "none", + "in_reply_to": null, + "page": false, + "triage_by": null, + "respond_by": null + } + }, + { + "case": "display-name-spoof", + "description": "Display name impersonates the gsa.gov Emergency sender, actual address does not: not FedRAMP", + "message_id": "sim-display-name-spoof", + "received_at": "2026-11-06T14:35:00Z", + "from": "\"fedramp_security@gsa.gov\" ", + "envelope": "attacker@attacker.invalid", + "subject": "EMERGENCY: trust me", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "other", + "designation": "GENERAL", + "sender_domain": "attacker.invalid", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "none", + "in_reply_to": null, + "page": false, + "triage_by": null, + "respond_by": null + } + }, + { + "case": "envelope-only", + "description": "Unreadable From header, @gsa.gov envelope sender: still FedRAMP, registered and paged; no reply without a From address", + "message_id": "sim-envelope-only", + "received_at": "2026-11-06T14:40:00Z", + "from": "garbage <<>>", + "envelope": "bounces@gsa.gov", + "subject": "Important: please confirm", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "IMPORTANT", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:no-from-address", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-07T14:40:00Z", + "respond_by": null + } + }, + { + "case": "emergency-other-sender", + "description": "Emergency from an @gsa.gov address other than the designated Emergency senders (AFC-FRP-UFS): flagged, not demoted, still paged", + "message_id": "sim-emergency-other-sender", + "received_at": "2026-11-06T14:45:00Z", + "from": "Someone ", + "envelope": "someone@gsa.gov", + "subject": "EMERGENCY: rotate your keys", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "EMERGENCY", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": false, + "ack": "sent", + "in_reply_to": true, + "page": true, + "triage_by": "2026-11-06T16:45:00Z", + "respond_by": "2026-11-09T20:00:00Z" + } + }, + { + "case": "bulk", + "description": "Bulk mail from @gsa.gov: registered, not answered", + "message_id": "sim-bulk", + "received_at": "2026-11-06T14:50:00Z", + "from": "news@gsa.gov", + "envelope": "news@gsa.gov", + "subject": "Newsletter", + "headers": { + "Precedence": "bulk" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:precedence", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:50:00Z", + "respond_by": null + } + }, + { + "case": "bounce", + "description": "A bounce (null envelope sender) from @gsa.gov: registered, not answered", + "message_id": "sim-bounce", + "received_at": "2026-11-06T14:55:00Z", + "from": "mailer-daemon@gsa.gov", + "envelope": "<>", + "subject": "Undeliverable: Received: FedRAMP program update", + "headers": {}, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "gsa.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "suppressed:null-sender", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T14:55:00Z", + "respond_by": null + } + }, + { + "case": "ack-send-fails", + "description": "The first acknowledgement attempt fails: recorded as failed, reported overdue, and sent exactly once on the retry", + "message_id": "sim-ack-send-fails", + "received_at": "2026-11-06T15:00:00Z", + "simulate_send_failure": true, + "from": "info@fedramp.gov", + "envelope": "info@fedramp.gov", + "subject": "Checking in", + "headers": { + "Message-ID": "" + }, + "auth": { + "spf": "PASS", + "dkim": "PASS", + "dmarc": "PASS" + }, + "expected": { + "kind": "fedramp", + "designation": "GENERAL", + "sender_domain": "fedramp.gov", + "authenticated": true, + "emergency_sender_ok": null, + "ack": "failed", + "in_reply_to": null, + "page": true, + "triage_by": "2026-11-09T15:00:00Z", + "respond_by": null + } + } + ] +} diff --git a/tests/test_fedramp_inbox.py b/tests/test_fedramp_inbox.py new file mode 100644 index 00000000..9e33e889 --- /dev/null +++ b/tests/test_fedramp_inbox.py @@ -0,0 +1,374 @@ +"""The SIMULATED FedRAMP Security Inbox (AFC-CSO-INB, TFG, RCV, CRA, EMR, IMA, ACK). + +By the operator's decision the inbox is simulated for this proof of concept: +nothing real is received or sent. scripts/_fsi.py is the logic a real inbox +would run, and scripts/build-fsi-simulation.py runs it on every deploy over the +synthetic messages in data/fsi-simulation/messages.json, failing the deploy if +any outcome differs. These tests pin the logic and that deploy wiring: + + TFG mail from @fedramp.gov / @gsa.gov is FedRAMP, whatever its spam verdict + or authentication result; look-alike domains are not + ACK FedRAMP mail is acknowledged once, header-injection safe, never to an + auto-reply and never to mail failing SPF/DKIM/DMARC + EMR every FedRAMP message pages, Emergency included + CRA Emergency / Emergency Test mail gets a deadline in the register + IMA Important mail cannot be triaged without its stated timeframe +""" + +import copy +import json +import re +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO / "scripts")) +import _fsi # noqa: E402 + +WORKFLOW = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() +OFFERING = REPO / "data" / "cds" / "offering.json" +MESSAGES = REPO / "data" / "fsi-simulation" / "messages.json" +BAD = REPO / "tests" / "fixtures" / "fsi" / "simulation-wrong-expectation.json" +SIM = REPO / "scripts" / "build-fsi-simulation.py" +NOW = datetime(2026, 11, 9, 15, 0, tzinfo=timezone.utc) # Monday 10:00 a.m. EST +PASS = {"spf": "PASS", "dkim": "PASS", "dmarc": "PASS"} +FAIL = {"spf": "FAIL", "dkim": "FAIL", "dmarc": "FAIL"} +SIMULATED_RULES = ["AFC-CSO-INB", "AFC-CSO-TFG", "AFC-CSO-RCV", "AFC-CSO-CRA", "AFC-CSO-EMR", + "AFC-CSO-IMA", "AFC-CSO-ACK"] + + +def msg(frm="FedRAMP ", subject="Emergency: action required", envelope=None, + headers=None, auth=PASS, message_id="m1", received_at="2026-11-09T15:00:00Z"): + return {"from": frm, "envelope": envelope if envelope is not None else _fsi.parse_address(frm) or "", + "subject": subject, "headers": headers or {}, "auth": auth, "message_id": message_id, + "received_at": received_at} + + +# --- classification (AFC-CSO-TFG) --------------------------------------------------- + +@pytest.mark.parametrize("frm", ["FedRAMP PMO ", "someone@FedRAMP.gov", + "\"F20B Team\" "]) +def test_fedramp_senders_are_fedramp_even_when_unauthenticated(frm): + c = _fsi.classify(msg(frm=frm, auth=FAIL)) + assert c["kind"] == "fedramp" and c["designation"] == "EMERGENCY" + assert c["authenticated"] is False and c["loop"] == "unauthenticated" + + +@pytest.mark.parametrize("frm,envelope", [ + ("x ", "a@fedramp.gov.example.com"), + ("x ", "a@notfedramp.gov"), + ("x ", "a@mail.gsa.gov"), + ("\"fedramp_security@gsa.gov\" ", "attacker@example.com"), + ("fedramp_security@gsa.gov ", "attacker@example.com"), +]) +def test_look_alike_domains_and_display_name_spoofs_are_not_fedramp(frm, envelope): + assert _fsi.classify(msg(frm=frm, envelope=envelope))["kind"] == "other" + + +def test_a_fedramp_envelope_sender_counts_even_if_the_from_header_is_unparseable(): + c = _fsi.classify(msg(frm="garbage <<>>", envelope="bounces@gsa.gov")) + assert c["kind"] == "fedramp" and c["sender_domain"] == "gsa.gov" + + +@pytest.mark.parametrize("subject,want", [ + ("Emergency Test: confirm your FSI", "EMERGENCY_TEST"), + ("[EMERGENCY-TEST] reply by Tuesday", "EMERGENCY_TEST"), + ("EMERGENCY: CVE-2026-0001 in your boundary", "EMERGENCY"), + ("Re: [Emergency] follow-up", "EMERGENCY"), + ("Important: update your Marketplace listing", "IMPORTANT"), + ("Monthly community update", "GENERAL"), + ("Emergencyish newsletter", "GENERAL"), +]) +def test_designators_follow_afc_frp_cds(subject, want): + assert _fsi.designation_of(subject) == want + + +def test_an_emergency_from_an_address_other_than_fedramp_security_is_flagged_not_demoted(): + c = _fsi.classify(msg(frm="Someone ")) + assert c["designation"] == "EMERGENCY" and c["emergency_sender_ok"] is False + + +# --- deadlines and register (AFC-CSO-CRA, AFC-CSO-IMA, AFC-FRP-ERT) ---------------------- + +@pytest.mark.parametrize("received,due", [ + ("2026-11-09T15:00:00Z", "2026-11-10T20:00:00Z"), # Mon 10:00 EST -> Tue 15:00 EST + ("2026-11-13T21:30:00Z", "2026-11-16T20:00:00Z"), # Fri 16:30 EST -> Mon 15:00 EST + ("2026-11-14T15:00:00Z", "2026-11-17T20:00:00Z"), # Sat -> Tue (Mon is day 1) + ("2026-10-30T14:00:00Z", "2026-11-02T20:00:00Z"), # Fri 10:00 EDT -> Mon 15:00 EST (DST ends Sun) + ("2026-11-10T04:30:00Z", "2026-11-10T20:00:00Z"), # Mon 23:30 EST counts Monday as day 1 +]) +def test_class_c_default_deadline_is_3pm_eastern_on_the_second_business_day(received, due): + assert _fsi.iso(_fsi.class_c_deadline(_fsi.parse_time(received))) == due + + +def test_emergency_records_carry_a_deadline_and_important_ones_ask_for_the_messages_own(): + e = _fsi.deadlines("EMERGENCY", NOW) + assert e["respond_by"] == "2026-11-10T20:00:00Z" and "ERT" in e["deadline_basis"] + assert e["triage_by"] == "2026-11-09T17:00:00Z" + i = _fsi.deadlines("IMPORTANT", NOW) + assert i["respond_by"] is None and "IMA" in i["deadline_basis"] + + +def record(**kw): + r = _fsi.new_record("m", _fsi.classify(msg()), NOW) + r.update(ack={"status": "sent"}, page={"status": "sent"}) + r.update(kw) + return r + + +def test_overdue_counts_untriaged_unclosed_and_failed_legs(): + later = datetime(2026, 11, 9, 18, 0, tzinfo=timezone.utc) + assert len(_fsi.overdue([record()], later)) == 1 # not triaged within 2 hours + assert _fsi.overdue([record(status="triaged")], later) == [] + late = _fsi.overdue([record(status="triaged")], datetime(2026, 11, 11, tzinfo=timezone.utc)) + assert len(late) == 1 and "not closed" in late[0] + failed = _fsi.overdue([record(status="triaged", ack={"status": "failed"})], later) + assert failed and "ack failed" in failed[0] + important = record(designation="IMPORTANT", status="triaged", respond_by=None) + assert "timeframe" in _fsi.overdue([important], later)[0] + + +def test_an_important_message_cannot_be_triaged_without_its_stated_timeframe(): + r = _fsi.new_record("m", _fsi.classify(msg(subject="Important: do X")), NOW) + with pytest.raises(ValueError, match="timeframe"): + _fsi.triage(r, NOW) + _fsi.triage(r, NOW, respond_by="2026-11-12T17:00:00-05:00") + assert r["status"] == "triaged" and r["respond_by"] == "2026-11-12T22:00:00Z" + _fsi.close(r, NOW, "done") + with pytest.raises(ValueError): + _fsi.triage(r, NOW) + + +# --- acknowledgement (AFC-CSO-ACK) ------------------------------------------------------ + +def ack(**kw): + args = {"inbox": "fedramp-security@example.com", "to": "fedramp_security@gsa.gov", "subject": "Emergency: x", + "rfc_message_id": "", "received_at": "2026-11-09T15:00:00Z", "designation": "EMERGENCY", + "ref": "abc", **kw} + return _fsi.build_ack(**args) + + +def header_names(raw): + return [line.split(":", 1)[0] for line in raw.split("\r\n\r\n", 1)[0].split("\r\n")] + + +def test_the_acknowledgement_marks_itself_automatic_and_threads_to_the_message(): + raw = ack() + assert header_names(raw) == ["From", "To", "Subject", "Auto-Submitted", "X-Auto-Response-Suppress", + "MIME-Version", "Content-Type", "Content-Transfer-Encoding", "In-Reply-To", + "References"] + assert "Auto-Submitted: auto-replied" in raw and "In-Reply-To: " in raw + + +@pytest.mark.parametrize("subject,msgid", [ + ("Emergency\r\nBcc: victim@example.com", ""), + ("ok", "\r\nBcc: victim@example.com"), + ("ok", ""), + ("\u202eEmergency\u2066", "\nTo: y@z"), +]) +def test_nothing_from_the_inbound_message_can_inject_a_header(subject, msgid): + names = header_names(ack(subject=subject, rfc_message_id=msgid)) + assert "Bcc" not in names and names.count("To") == 1 and len(names) in (8, 10) + + +def test_an_invalid_recipient_raises_rather_than_sending(): + with pytest.raises(ValueError): + ack(to="victim@example.com\r\nBcc: x@y.z") + + +@pytest.mark.parametrize("headers,envelope,reason", [ + ({"Auto-Submitted": "auto-replied"}, "a@gsa.gov", "auto-submitted"), + ({"Precedence": "bulk"}, "a@gsa.gov", "precedence"), + ({}, "", "null-sender"), + ({}, "<>", "null-sender"), +]) +def test_no_acknowledgement_to_auto_replies_bulk_mail_or_bounces(headers, envelope, reason): + c = _fsi.classify(msg(frm="a@gsa.gov", headers=headers, envelope=envelope)) + assert c["kind"] == "fedramp" and c["loop"] == reason + + +def run_receive(m, register, send_fails=False): + sent, pages = [], [] + + def send(to, raw): + if send_fails: + raise ConnectionError("simulated") + sent.append((to, raw)) + out = _fsi.receive(m, register, inbox="fedramp-security@example.com", send=send, page=pages.append) + return out, sent, pages + + +def test_a_redelivered_message_is_acknowledged_and_paged_once(): + register = {} + _, sent, pages = run_receive(msg(), register) + assert len(sent) == 1 and len(pages) == 1 + _, sent, pages = run_receive(msg(), register) + assert sent == [] and pages == [] + + +def test_a_failed_acknowledgement_is_recorded_retried_and_counted_overdue(): + register = {} + out, _, _ = run_receive(msg(), register, send_fails=True) + assert out["record"]["ack"] == {"status": "failed", "error": "ConnectionError"} + assert any("ack failed" in p for p in _fsi.overdue(register.values(), NOW)) + _, sent, _ = run_receive(msg(), register) + assert len(sent) == 1 and register["m1"]["ack"]["status"] == "sent" + + +def test_unauthenticated_fedramp_mail_is_registered_and_paged_but_not_acknowledged(): + out, sent, pages = run_receive(msg(auth=FAIL), {}) + assert sent == [] and len(pages) == 1 + assert out["record"]["ack"] == {"status": "suppressed", "reason": "unauthenticated"} + + +def test_other_mail_is_not_registered_acknowledged_or_paged(): + out, sent, pages = run_receive(msg(frm="a@example.com"), {}) + assert out["record"] is None and sent == [] and pages == [] + + +def test_the_page_subject_is_ascii_and_names_the_domain_not_the_address(): + s = _fsi.page_subject(record()) + assert s == "[FSI] EMERGENCY FedRAMP message from gsa.gov" and "@" not in s + + +# --- the deploy's simulation step ----------------------------------------------------------- + +def simulate(tmp_path, messages=MESSAGES): + out = tmp_path / "sim.json" + p = subprocess.run([sys.executable, str(SIM), "--messages", str(messages), "--offering", str(OFFERING), + "--output", str(out)], capture_output=True, text=True) + return p, out + + +def test_the_committed_synthetic_messages_cover_the_required_cases(): + cases = {m["case"]: m for m in json.loads(MESSAGES.read_text())["messages"]} + assert {"emergency-test", "important", "general", "forged-gsa", "auto-reply"} <= set(cases) + assert cases["emergency-test"]["expected"]["designation"] == "EMERGENCY_TEST" + assert cases["forged-gsa"]["expected"]["ack"] == "suppressed:unauthenticated" + assert cases["forged-gsa"]["expected"]["kind"] == "fedramp" + assert cases["auto-reply"]["expected"]["ack"] == "suppressed:auto-submitted" + + +def test_the_simulation_passes_and_publishes_a_labelled_result_without_addresses(tmp_path): + p, out = simulate(tmp_path) + assert p.returncode == 0, p.stdout + p.stderr + text = out.read_text() + doc = json.loads(text) + assert doc["simulation"] is True and doc["notice"].startswith("SIMULATION.") + assert "no mail is received and none is sent" in doc["notice"] + assert doc["result"] == "pass" and all(c["matches_expected"] for c in doc["cases"]) + assert doc["retry_pass"] == {"acknowledgements_sent_again": 1, "pages_sent_again": 0} + checks = doc["register_check"]["checks"] + assert len(checks) >= 10 and all(c["ok"] for c in checks) + assert doc["contact"].endswith("Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/") + assert doc["emitted_at"] and doc["rules_exercised"] == SIMULATED_RULES + assert not re.search(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}", text), "published result carries an address" + + +@pytest.mark.parametrize("case,needle", [ + ("display-name-spoof", '"kind": "other"'), + ("envelope-only", '"ack": "suppressed:no-from-address"'), + ("emergency-other-sender", '"emergency_sender_ok": false'), + ("bulk", '"ack": "suppressed:precedence"'), + ("bounce", '"ack": "suppressed:null-sender"'), + ("ack-send-fails", '"ack": "failed"'), +]) +def test_the_simulation_exercises_each_behaviour_the_records_claim(case, needle): + m = next(m for m in json.loads(MESSAGES.read_text())["messages"] if m["case"] == case) + assert needle in json.dumps(m["expected"]).replace(": False", ": false") + + +@pytest.mark.parametrize("mutate,needle", [ + (lambda d: d["register_check"].update(expected_retry={"acknowledgements_sent_again": 0, "pages_sent_again": 0}), + "retry pass"), + (lambda d: d["register_check"].update(later="2026-11-09T19:00:00Z"), "past its deadline"), + (lambda d: d["register_check"]["expected_overdue"].remove("sim-ack-send-fails"), "items overdue"), +]) +def test_each_register_check_fails_the_simulation_when_its_outcome_differs(tmp_path, mutate, needle): + d = json.loads(MESSAGES.read_text()) + mutate(d) + bad = tmp_path / "m.json" + bad.write_text(json.dumps(d)) + p, out = simulate(tmp_path, bad) + assert p.returncode == 1 and not out.exists() and needle in p.stdout, p.stdout + + +def test_a_differing_outcome_fails_the_simulation_and_writes_nothing(tmp_path): + """Known-bad fixture: the forged @gsa.gov message is expected to be acknowledged.""" + p, out = simulate(tmp_path, BAD) + assert p.returncode == 1 and not out.exists() + assert "forged-gsa: ack expected 'sent', observed 'suppressed:unauthenticated'" in p.stdout + + +def test_the_known_bad_fixture_differs_from_the_committed_messages_only_in_that_expectation(): + good, bad = json.loads(MESSAGES.read_text()), json.loads(BAD.read_text()) + fixed = copy.deepcopy(bad) + next(m for m in fixed["messages"] if m["case"] == "forged-gsa")["expected"]["ack"] = "suppressed:unauthenticated" + fixed["_note"] = good["_note"] + assert fixed == good + + +def step(name): + m = re.search(r"\n - name: " + re.escape(name) + r"\n(.*?)(?=\n - name: |\Z)", WORKFLOW, re.S) + assert m, name + return m.group(1) + + +def test_the_simulation_runs_on_every_deploy_before_the_sdr_build(): + name = "FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" + body = step(name) + assert "build-fsi-simulation.py" in body and "--output fedramp-inbox-simulation.json" in body + assert "continue-on-error" not in body and "|| true" not in body + assert WORKFLOW.index("- name: " + name) < WORKFLOW.index("- name: Build Security Decision Record") + + +def test_the_simulation_result_is_signed_gated_published_verified_and_freshness_governed(): + assert ("cosign sign-blob --yes --new-bundle-format --bundle fedramp-inbox-simulation.bundle " + "fedramp-inbox-simulation.json") in WORKFLOW + assert "fedramp-inbox-simulation.json" in step("Publication redaction gate (no AWS account ID)") + publish = step("Publish all signed artifacts to /.well-known/") + for f in ("fedramp-inbox-simulation.json", "fedramp-inbox-simulation.bundle"): + assert f'aws s3 cp {f} "s3://$BUCKET_NAME/.well-known/{f}"' in publish + assert "check fedramp-inbox-simulation.json .well-known/fedramp-inbox-simulation.json" in WORKFLOW + cfg = json.loads((REPO / "infrastructure" / "schemas" / "freshness-config.json").read_text()) + entries = [a for a in cfg["artifacts"] if a["path"] == ".well-known/fedramp-inbox-simulation.json"] + assert len(entries) == 1 and entries[0]["signed"] is True and entries[0]["cadence"] == "deploy" + assert entries[0]["timestamp"] == {"source": "json", "field": "emitted_at"} + assert entries[0]["note"].startswith("SIMULATION") + + +# --- what is published and recorded ------------------------------------------------------------ + +def test_the_cpo_publishes_the_simulated_contact_not_an_email_address(tmp_path): + out = tmp_path / "cpo.json" + subprocess.run([sys.executable, str(REPO / "scripts" / "build-cpo.py"), "--offering", str(OFFERING), + "--profile", str(REPO / "data" / "system-profile.json"), "--overview", str(tmp_path / "none"), + "--ksi-signal", str(tmp_path / "none"), "--output", str(out), "--md-output", ""], + check=True, capture_output=True) + fsi = json.loads(out.read_text())["certification_data"]["fedramp_security_inbox"] + off = json.loads(OFFERING.read_text())["fedramp_security_inbox"] + assert fsi["simulated"] is True and fsi["contact"] == off["contact"] + assert "Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/" in fsi["contact"] and "@" not in fsi["contact"] + assert fsi["simulation"] == "https://samaydlette.com/.well-known/fedramp-inbox-simulation.json" + + +def test_every_afc_record_is_implemented_and_discloses_the_simulation(): + recs = {r["frr_id"]: r for r in json.loads((REPO / "data" / "frr-records.json").read_text())["records"]} + afc = [rid for rid in recs if rid.startswith("AFC-")] + assert sorted(afc) == sorted(SIMULATED_RULES + ["AFC-CSO-NOC"]) + for rid in afc: + r = recs[rid] + assert r["status"] == "Implemented" and "gap" not in r and "closes_with" not in r, rid + text = r["implementation"] + assert text.startswith("SIMULATED FOR THIS PROOF OF CONCEPT"), rid + assert "no mail is received or sent" in text and "https://www.linkedin.com/in/sa2/" in text, rid + for rid in SIMULATED_RULES: + r = recs[rid] + assert r["simulated"]["counterparty"] == "mail", rid + refs = [e["ref"] for e in r["evidence"]] + assert ".well-known/fedramp-inbox-simulation.json" in refs, rid + assert any(ref.startswith("deploy-with-opa.yml#FedRAMP Security Inbox simulation") for ref in refs), rid diff --git a/tests/test_frr_records.py b/tests/test_frr_records.py index e9977e6c..018130e7 100644 --- a/tests/test_frr_records.py +++ b/tests/test_frr_records.py @@ -193,7 +193,7 @@ def test_the_system_and_fedramp_addresses_are_allowed(applicable, resolve): doc = copy.deepcopy(_committed()) for r in doc["records"]: if r["frr_id"] == "AFC-CSO-ACK": - r["gap"] = "Acknowledge mail from x@fedramp.gov and x@gsa.gov at fedramp-security@samaydlette.com." + r["implementation"] = "Acknowledge mail from x@fedramp.gov and x@gsa.gov at fedramp-security@samaydlette.com." _frr.validate(doc, applicable, resolve) @@ -266,7 +266,9 @@ def test_the_summary_counts_simulated_counterparties(applicable, resolve): evidence=[{"kind": "step", "ref": "deploy-with-opa.yml#Run OPA Compliance Check"}], simulated={"counterparty": "assessor", "how": "A plainly fictional assessor."}) _frr.validate(doc, applicable, resolve) - assert _frr.summary(doc, applicable)["simulated"] == {"assessor": 1} + before = _frr.summary(_committed(), applicable)["simulated"] + assert "simulated" not in next(r for r in _committed()["records"] if r["frr_id"] == "VDR-CSO-MSP") + assert _frr.summary(doc, applicable)["simulated"] == {**before, "assessor": before.get("assessor", 0) + 1} def test_the_gate_runs_before_anything_is_applied(): diff --git a/tests/test_fsi_notice.py b/tests/test_fsi_notice.py new file mode 100644 index 00000000..e52215b0 --- /dev/null +++ b/tests/test_fsi_notice.py @@ -0,0 +1,94 @@ +"""AFC-CSO-NOC: changing the FedRAMP Security Inbox contact (simulated inbox; +the contact is a statement, not a mailbox) without recording +that FedRAMP was notified fails the unit-test job (scripts/check-fsi-notice.py). + +Known-bad fixtures under tests/fixtures/fsi/ each fail for one reason; the good +one shows what a compliant change looks like.""" + +import copy +import importlib.util +import json +from datetime import date +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "fsi" +TODAY = date(2026, 12, 15) + +spec = importlib.util.spec_from_file_location("check_fsi_notice", REPO / "scripts" / "check-fsi-notice.py") +mod = importlib.util.module_from_spec(spec) +spec.loader.exec_module(mod) + + +def load(name): + return json.loads((FIX / f"offering-{name}.json").read_text()) + + +def live(): + return json.loads((REPO / "data" / "cds" / "offering.json").read_text()) + + +def test_the_committed_inbox_record_passes(): + assert mod.check(live(), today=date.today()) == [] + assert mod.main([]) == 0 + + +def test_a_contact_change_without_a_history_entry_fails(): + out = mod.check(load("changed-without-history"), base=live(), today=TODAY) + assert any("without a history entry" in p for p in out), out + assert any("no history entry was added" in p for p in out), out + + +def test_a_contact_change_without_the_fedramp_notified_marker_fails(): + out = mod.check(load("changed-without-notice"), base=live(), today=TODAY) + assert out and all("fedramp_notified" in p for p in out), out + + +def test_a_contact_change_that_records_the_notification_passes(): + assert mod.check(load("changed-with-notice"), base=live(), today=TODAY) == [] + + +def test_the_cli_fails_the_known_bad_fixture(tmp_path): + base = tmp_path / "base.json" + base.write_text(json.dumps(live())) + assert mod.main(["--offering", str(FIX / "offering-changed-without-notice.json"), "--base", str(base)]) == 1 + + +def test_a_notification_dated_in_the_future_fails(): + doc = load("changed-with-notice") + doc["fedramp_security_inbox"]["history"][-1]["fedramp_notified"]["on"] = "2027-01-01" + assert any("not in the future" in p for p in mod.check(doc, today=TODAY)) + + +def test_rewriting_history_fails_against_the_base(): + good = load("changed-with-notice") + rewritten = copy.deepcopy(good) + rewritten["fedramp_security_inbox"]["history"][0]["since"] = "2026-01-01" + assert any("append-only" in p for p in mod.check(rewritten, base=good, today=TODAY)) + + +@pytest.mark.parametrize("contact", ["", " ", "two\nlines", "x" * 301, None]) +def test_the_contact_must_be_one_printable_line(contact): + doc = live() + doc["fedramp_security_inbox"]["contact"] = contact + doc["fedramp_security_inbox"]["history"][-1]["contact"] = contact + assert any("must be one non-empty line" in p for p in mod.check(doc, today=TODAY)) + + +def test_the_published_contact_says_simulated_and_points_to_linkedin(): + contact = live()["fedramp_security_inbox"]["contact"] + assert "Simulated for this proof of concept" in contact + assert "https://www.linkedin.com/in/sa2/" in contact + assert "@" not in contact + + +def test_establishing_the_inbox_needs_a_basis_when_nobody_was_notified(): + doc = live() + doc["fedramp_security_inbox"]["history"][0]["basis"] = "" + assert any("basis" in p for p in mod.check(doc, today=TODAY)) + + +def test_a_missing_inbox_block_fails(): + assert mod.check({}, today=TODAY) From 3709afbbe7223619b30b34acfe913ddeae0010e3 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:42:42 -0500 Subject: [PATCH 7/7] Incident reports: simulated delivery, publisher role proved before the SDR Every deploy and every unattended publish now "delivers" each incident report the log lists to a simulated FedRAMP and agency recipient (scripts/deliver-incident-reports.py): read back, checked against the published sha256 and FedRAMP's schema, and recorded in the signed delivery log /.well-known/incident-deliveries.json. Nothing is sent. A failed delivery stops publication. The deploy job assumes the incident publisher's role before it builds the SDR (scripts/check-incident-role.py), so a deploy whose publisher role does not work stops before publishing records that claim it. The role's trust gains the reviewer-gated deploy environment (bootstrap apply). IEC-CSO-IIR/OIR/FIR/AIR are Implemented with simulated {incident-recipient}. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 16 ++ .github/workflows/incident-reports.yml | 8 + data/frr-records.json | 112 ++++++++-- data/incidents.json | 2 +- docs/cr26-applicability.md | 5 +- docs/incident-response.md | 3 +- docs/policies/ir-policy.md | 2 +- infrastructure/bootstrap/incident-reports.tf | 14 +- infrastructure/schemas/freshness-config.json | 12 + scripts/build-incident-report.py | 7 +- scripts/check-incident-publisher.py | 7 +- scripts/check-incident-role.py | 104 +++++++++ scripts/deliver-incident-reports.py | 127 +++++++++++ .../incidents/delivery-hash-mismatch.json | 37 +++ .../incidents/delivery-missing-report.json | 37 +++ .../incidents/delivery-not-reportable.json | 37 +++ .../fixtures/incidents/sts-access-denied.xml | 7 + tests/fixtures/incidents/sts-assumed.xml | 9 + tests/fixtures/incidents/sts-wrong-role.xml | 9 + tests/test_incident_delivery.py | 210 ++++++++++++++++++ tests/test_incidents.py | 4 +- tests/test_published_redaction.py | 5 +- 22 files changed, 731 insertions(+), 43 deletions(-) create mode 100644 scripts/check-incident-role.py create mode 100644 scripts/deliver-incident-reports.py create mode 100644 tests/fixtures/incidents/delivery-hash-mismatch.json create mode 100644 tests/fixtures/incidents/delivery-missing-report.json create mode 100644 tests/fixtures/incidents/delivery-not-reportable.json create mode 100644 tests/fixtures/incidents/sts-access-denied.xml create mode 100644 tests/fixtures/incidents/sts-assumed.xml create mode 100644 tests/fixtures/incidents/sts-wrong-role.xml create mode 100644 tests/test_incident_delivery.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 2af5f99a..411cc8ed 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1582,6 +1582,11 @@ jobs: run: | set -euo pipefail python3 ../scripts/build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . + # SIMULATED delivery (IEC-CSO-IIR/OIR/FIR/AIR): every listed report is + # read back, hash- and schema-checked and "delivered" to a simulated + # FedRAMP and agency recipient; nothing is sent. A failed delivery + # stops the deploy here, before the SDR is built or anything published. + python3 ../scripts/deliver-incident-reports.py --dir . for f in incident-*.json; do cosign sign-blob --yes --new-bundle-format --bundle "${f%.json}.bundle" "$f" done @@ -1635,6 +1640,15 @@ jobs: --previous previous-availability.json --ksi-signal ksi-signal.json python3 ../scripts/build-policy-index.py --output policy-index.json --md-output policy-index.md + # The IEC records claim an unattended publisher that assumes its own role. + # Prove the role can be assumed, from this job, before the SDR is built: + # if it cannot, the deploy stops here and nothing claiming it is published. + # The incident-publisher job after the deploy then runs the publisher itself. + - name: Incident report publisher role can be assumed + env: + INCIDENT_REPORTS_ROLE_ARN: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }} + run: python3 scripts/check-incident-role.py + # SIMULATION. The FedRAMP Security Inbox is simulated for this proof of # concept (operator's decision): nothing real is received or sent. This # runs the inbox logic (scripts/_fsi.py) over committed synthetic messages @@ -1903,6 +1917,8 @@ jobs: aws s3 cp incident-reports.json "s3://$BUCKET_NAME/.well-known/incident-reports.json" --content-type application/json --cache-control "public, max-age=300" aws s3 cp incident-reports.bundle "s3://$BUCKET_NAME/.well-known/incident-reports.bundle" --content-type application/json --cache-control "public, max-age=300" aws s3 cp incident-reports.md "s3://$BUCKET_NAME/.well-known/incident-reports.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + aws s3 cp incident-deliveries.json "s3://$BUCKET_NAME/.well-known/incident-deliveries.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp incident-deliveries.bundle "s3://$BUCKET_NAME/.well-known/incident-deliveries.bundle" --content-type application/json --cache-control "public, max-age=300" for f in incident-INC-*.json; do aws s3 cp "$f" "s3://$BUCKET_NAME/.well-known/$f" --content-type application/json --cache-control "public, max-age=300" aws s3 cp "${f%.json}.bundle" "s3://$BUCKET_NAME/.well-known/${f%.json}.bundle" --content-type application/json --cache-control "public, max-age=300" diff --git a/.github/workflows/incident-reports.yml b/.github/workflows/incident-reports.yml index e8b2abee..74b713de 100644 --- a/.github/workflows/incident-reports.yml +++ b/.github/workflows/incident-reports.yml @@ -136,6 +136,12 @@ jobs: id: build run: python3 scripts/build-incident-report.py --incidents data/incidents.json --vdr vdr-report.json --out-dir out + # SIMULATED delivery: each report goes to a simulated FedRAMP and agency + # recipient and the delivery log records it. Nothing is sent. A failed + # delivery fails the run before anything is published. + - name: Deliver incident reports (simulated recipients; nothing sent) + run: python3 scripts/deliver-incident-reports.py --dir out + - name: Sign incident reports working-directory: out run: | @@ -174,6 +180,8 @@ jobs: put "$f" "application/json" put "${f%.json}.bundle" "application/json" done + put incident-deliveries.json "application/json" + put incident-deliveries.bundle "application/json" put incident-reports.md "text/markdown; charset=utf-8" put incident-reports.bundle "application/json" put incident-reports.json "application/json" diff --git a/data/frr-records.json b/data/frr-records.json index 2ebc5672..848197d0 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -810,8 +810,8 @@ }, { "frr_id": "IEC-CSO-AIR", - "status": "Partially Implemented", - "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). Every deploy checks the publisher's prerequisites before it applies anything (scripts/check-incident-publisher.py: the role variable names the bootstrap role and the incident-reports environment deploys only from main) and, after the deploy job, runs this workflow on its own role (deploy-with-opa.yml job incident-publisher), so the deploy fails if the publisher cannot publish.", + "status": "Implemented", + "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Every deploy checks the publisher's prerequisites before it applies anything (scripts/check-incident-publisher.py: the role variable names the bootstrap role and the incident-reports environment deploys only from main), assumes the publisher's role from the deploy job before the SDR is built (scripts/check-incident-role.py, step 'Incident report publisher role can be assumed'), so a deploy whose publisher role does not work stops before anything is published, and after the deploy job runs this workflow on its own role (job incident-publisher). Delivery is SIMULATED: on every deploy and every unattended publish, scripts/deliver-incident-reports.py reads back each report the incident log lists, checks it against the published sha256 and FedRAMP's incident report schema, and 'delivers' it to a simulated FedRAMP recipient ('FedRAMP Incident Desk (simulated)') and to each affected agency, also simulated; a delivery that fails stops publication. The signed delivery log is /.well-known/incident-deliveries.json. Nothing is sent to FedRAMP or to any agency: there is no FedRAMP certification and no agency customer to send to.", "evidence": [ { "kind": "step", @@ -836,12 +836,36 @@ { "kind": "artifact", "ref": ".well-known/incident-reports.json" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-deliveries.json" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Incident report publisher role can be assumed" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_the_role_check_runs_in_the_deploy_job_before_the_sdr_build" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_a_role_that_cannot_be_assumed_fails_the_deploy" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_delivery_runs_before_signing_in_the_deploy_and_before_publishing_in_the_publisher" } ], - "gap": "Everything up to publication is automated; what is left is the last step of the rule, reaching all affected parties. Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). A person still records the incident's facts in the register, which the rule allows (it asks to minimize human intervention, not remove it). To close: the operator's delivery decision (IEC-CSO-IIR); the delivery is then built into this workflow.", - "closes_with": [ - "sam" - ] + "simulated": { + "counterparty": "incident-recipient", + "how": "FedRAMP and the affected agencies are simulated recipients: each report is read back, hash- and schema-checked and recorded as delivered in /.well-known/incident-deliveries.json on every deploy and every unattended publish; nothing is sent." + } }, { "frr_id": "IEC-CSO-DPR", @@ -906,8 +930,8 @@ }, { "frr_id": "IEC-CSO-FIR", - "status": "Partially Implemented", - "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A Final report is allowed only after resolved_at and recovery_complete_at, restates final values for every earlier item, carries resolvedAt, and is due an FIR period after recovery (6 hours at N3-N5, 1 business day at N1-N2); overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A Final report is allowed only after resolved_at and recovery_complete_at, restates final values for every earlier item, carries resolvedAt, and is due an FIR period after recovery (6 hours at N3-N5, 1 business day at N1-N2); overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is SIMULATED: on every deploy and every unattended publish, scripts/deliver-incident-reports.py reads back each report the incident log lists, checks it against the published sha256 and FedRAMP's incident report schema, and 'delivers' it to a simulated FedRAMP recipient ('FedRAMP Incident Desk (simulated)') and to each affected agency, also simulated; a delivery that fails stops publication. The signed delivery log is /.well-known/incident-deliveries.json. Nothing is sent to FedRAMP or to any agency: there is no FedRAMP certification and no agency customer to send to.", "evidence": [ { "kind": "test", @@ -920,17 +944,29 @@ { "kind": "artifact", "ref": ".well-known/incident-reports.json" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-deliveries.json" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_every_report_is_delivered_to_a_simulated_fedramp_and_agency_recipient" } ], - "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", - "closes_with": [ - "sam" - ] + "simulated": { + "counterparty": "incident-recipient", + "how": "FedRAMP and the affected agencies are simulated recipients: each report is read back, hash- and schema-checked and recorded as delivered in /.well-known/incident-deliveries.json on every deploy and every unattended publish; nothing is sent." + } }, { "frr_id": "IEC-CSO-IIR", - "status": "Partially Implemented", - "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). The Initial report carries all eight items (coordinator, tracking ID, description, timeline with start/detection/evaluation/milestones, historical and current rating with the EFI explanation, functional impact, recovery plan, likely affected agencies). Its clock (1 hour at N3-N5, 24 hours at N2, 1 business day at N1) runs from the evaluation; the incident-reports workflow fails and the evidence watchdog pages (IncidentReportsOverdue) once it passes. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). The Initial report carries all eight items (coordinator, tracking ID, description, timeline with start/detection/evaluation/milestones, historical and current rating with the EFI explanation, functional impact, recovery plan, likely affected agencies). Its clock (1 hour at N3-N5, 24 hours at N2, 1 business day at N1) runs from the evaluation; the incident-reports workflow fails and the evidence watchdog pages (IncidentReportsOverdue) once it passes. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is SIMULATED: on every deploy and every unattended publish, scripts/deliver-incident-reports.py reads back each report the incident log lists, checks it against the published sha256 and FedRAMP's incident report schema, and 'delivers' it to a simulated FedRAMP recipient ('FedRAMP Incident Desk (simulated)') and to each affected agency, also simulated; a delivery that fails stops publication. The signed delivery log is /.well-known/incident-deliveries.json. Nothing is sent to FedRAMP or to any agency: there is no FedRAMP certification and no agency customer to send to.", "evidence": [ { "kind": "test", @@ -947,17 +983,33 @@ { "kind": "artifact", "ref": ".well-known/incident-reports.json" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-deliveries.json" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_every_report_is_delivered_to_a_simulated_fedramp_and_agency_recipient" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_known_bad_logs_fail_delivery_and_write_nothing" } ], - "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator decides a delivery channel (e.g. SES from the system's domain to FedRAMP's incident address) and it is built behind that decision.", - "closes_with": [ - "sam" - ] + "simulated": { + "counterparty": "incident-recipient", + "how": "FedRAMP and the affected agencies are simulated recipients: each report is read back, hash- and schema-checked and recorded as delivered in /.well-known/incident-deliveries.json on every deploy and every unattended publish; nothing is sent." + } }, { "frr_id": "IEC-CSO-OIR", - "status": "Partially Implemented", - "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Each Ongoing report restates every earlier item with its latest value and marks each 'updated' or 'no update', and adds observed activity, indicators of compromise, related CVEs, root cause and response/recovery activities. The next one is due an OIR period (6 hours at N3-N5, 24 at N2, 1 business day at N1) after the previous report until the incident is resolved; overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Each Ongoing report restates every earlier item with its latest value and marks each 'updated' or 'no update', and adds observed activity, indicators of compromise, related CVEs, root cause and response/recovery activities. The next one is due an OIR period (6 hours at N3-N5, 24 at N2, 1 business day at N1) after the previous report until the incident is resolved; overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is SIMULATED: on every deploy and every unattended publish, scripts/deliver-incident-reports.py reads back each report the incident log lists, checks it against the published sha256 and FedRAMP's incident report schema, and 'delivers' it to a simulated FedRAMP recipient ('FedRAMP Incident Desk (simulated)') and to each affected agency, also simulated; a delivery that fails stops publication. The signed delivery log is /.well-known/incident-deliveries.json. Nothing is sent to FedRAMP or to any agency: there is no FedRAMP certification and no agency customer to send to.", "evidence": [ { "kind": "test", @@ -970,12 +1022,24 @@ { "kind": "artifact", "ref": ".well-known/incident-reports.json" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-deliveries.json" + }, + { + "kind": "test", + "ref": "tests/test_incident_delivery.py::test_every_report_is_delivered_to_a_simulated_fedramp_and_agency_recipient" } ], - "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", - "closes_with": [ - "sam" - ] + "simulated": { + "counterparty": "incident-recipient", + "how": "FedRAMP and the affected agencies are simulated recipients: each report is read back, hash- and schema-checked and recorded as delivered in /.well-known/incident-deliveries.json on every deploy and every unattended publish; nothing is sent." + } }, { "frr_id": "IVV-CSO-DUS", diff --git a/data/incidents.json b/data/incidents.json index f00b35da..0bd171dc 100644 --- a/data/incidents.json +++ b/data/incidents.json @@ -4,7 +4,7 @@ "policy": { "federal_incident_coordinator": "Sam Aydlette, System Owner and incident response lead; contact through https://samaydlette.com/.well-known/security.txt", "notification": "published-only", - "notification_text": "Published only. Each report is signed and published under https://samaydlette.com/.well-known/ (incident-reports.json lists every report and its sha256). Nothing is sent to FedRAMP or to any agency: the operator has not authorized sending, and this system has no FedRAMP certification and no agency customers.", + "notification_text": "Published, and delivered to SIMULATED recipients. Each report is signed and published under https://samaydlette.com/.well-known/ (incident-reports.json lists every report and its sha256) and 'delivered' to a simulated FedRAMP and agency recipient, recorded in incident-deliveries.json. Nothing is sent to FedRAMP or to any agency: this system has no FedRAMP certification and no agency customers.", "adopted_vulnerability_rules": ["VER-TFR-IRI", "VER-TFR-NRI"], "federal_customer_data": "None. This system holds no federal customer data (FRD-FCD) and has no agency customers. Were an agency to use the Silk Reeling application, what its users supply to it (pose landmarks) would be the federal customer data to consider; the operator's public site content, account information and the published evidence are not.", "decided_by": "Operator", diff --git a/docs/cr26-applicability.md b/docs/cr26-applicability.md index 30052eba..9ae361aa 100644 --- a/docs/cr26-applicability.md +++ b/docs/cr26-applicability.md @@ -24,8 +24,9 @@ The POA&M is retired (2026-11-04): CR26 has no POA&M. Open findings and their de - **IVV — Independent Verification and Validation.** `IVV-CSO-FIA` (Class C MUST) requires a persistent independent assessment by a **FedRAMP Recognized independent assessment service** (the artifact formerly called a 3PAO) or by FedRAMP. This system is self-attested and has engaged no such assessor, so the *independent* half cannot be met. The provider-side verification and validation an assessor would consume **are** produced (in the Security Decision Record); the independent half is unmet by design and recorded N/A. - **MKT — Marketplace Listing.** `MKT-IIP-AGU` requires demonstrating the offering is for agency use within 44 USC § 3506 scope, and the rule text is explicit that *"services used by private companies to meet other compliance requirements (such as CMMC) that do not also meet one of the above use cases are outside the scope of FedRAMP."* There is no agency use case and no intent to list, so MKT is N/A by statutory scope. -- **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so in practice no incident is FedRAMP-reportable. Every incident is still evaluated and recorded in `data/incidents.json`; reportable ones get Initial, Ongoing and Final reports in FedRAMP's schema, on the Class C clocks, published under `/.well-known/` (publish-only: nothing is sent). Exercised 2026-11-05 with simulated incidents marked as exercises; see `docs/incident-response.md`. -These three are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. +These two are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. **AFC — Addressing FedRAMP Communication** is no longer recorded N/A (operator's decision, 2026-11-05): it is implemented against a *simulated* FedRAMP Security Inbox. The inbox logic (`scripts/_fsi.py`) runs on every deploy over committed synthetic messages and publishes `/.well-known/fedramp-inbox-simulation.json`, labelled as a simulation; no mail is received or sent, and the published contact sends FedRAMP to the operator on LinkedIn. See `docs/runbooks/fedramp-security-inbox.md`. + +**IEC — Incident Evaluation and Communication** is not recorded N/A either. This system holds no federal customer data, so in practice no incident is FedRAMP-reportable, but every incident is evaluated and recorded in `data/incidents.json`, and reportable ones get Initial, Ongoing and Final reports in FedRAMP's schema, on the Class C clocks, published under `/.well-known/` and delivered to *simulated* FedRAMP and agency recipients (`/.well-known/incident-deliveries.json`; nothing is sent). Exercised 2026-11-05 with simulated incidents marked as exercises; see `docs/incident-response.md`. diff --git a/docs/incident-response.md b/docs/incident-response.md index 657682a8..bb5e1382 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -55,7 +55,8 @@ Reporting is automated from the incident register. A person records facts; the p - **Build and publish.** `scripts/build-incident-report.py` writes each report in FedRAMP's incident report schema (`incident---.json`, validated before it is written) and the incident log (`incident-reports.json` and `.md`: every incident, its evaluation and reason, its rating history, each report with its sha256 and what changed, and each clock). `.github/workflows/incident-reports.yml` runs it on every push of the register to `main`, by hand, twice a day and after each nightly VDR refresh; it signs, redaction-gates and publishes under `/.well-known/incident-*` with a role that can write nothing else. Every deploy republishes the same set. - **Alarms.** The workflow's last step fails, and raises a GitHub issue, when a report is past its deadline. The evidence SLA watchdog reads the published log hourly and pages by email (`incident-report-overdue`, [`runbooks/evidence-sla-alarm.md`](runbooks/evidence-sla-alarm.md)). - **Vulnerabilities as incidents.** The operator adopts `VER-TFR-IRI` and `VER-TFR-NRI` (`policy.adopted_vulnerability_rules`). The VDR triage policy names each finding they cover; until an unresolved incident in the register lists it under `findings`, its Initial report is due from the finding's first evaluation at N5, so the alarms fire. Open the incident with basis `VER-TFR-IRI` or `VER-TFR-NRI` and the finding's tracking ID or CVE. Reconciliation invariant (m) fails a build whose open incident names a finding the VDR no longer carries: close it with a Final report. -- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency; the operator has not authorized sending, and the system has no certification and no agency customers. Every report says so. FedRAMP and the affected agencies are "all affected parties" under the rules; reaching them is a decision for the operator. +- **Delivery is simulated.** FedRAMP and the affected agencies are "all affected parties" under the rules. This system has no certification and no agency customers, so they are simulated recipients: on every deploy and every run of the incident reports workflow, `scripts/deliver-incident-reports.py` reads back each report the log lists, checks its sha256 and FedRAMP's schema, and records its "delivery" to "FedRAMP Incident Desk (simulated)" and to each affected agency (simulated) in `/.well-known/incident-deliveries.json`. A delivery that fails stops publication. Nothing is sent to anyone. +- **The publisher's role is proved on every deploy.** Before the Security Decision Record is built, the deploy job assumes the incident reports role (`scripts/check-incident-role.py`); if it cannot, the deploy stops. - **Exercises.** A simulated incident is recorded with `exercise: true` and is published marked as one. Exercised 2026-11-05: `INC-2026-001` (a simulated internet-reachable N5 vulnerability: Initial, two Ongoing and a Final report on a simulated timeline, all on time; rated N5 by default, then estimated N3) and `INC-2026-002` (a simulated page change, evaluated not reportable with its reason). `tests/test_incidents.py` runs the same exercise through the builder on every `make check`. ## After-action reports (KSI-INR-AAR) diff --git a/docs/policies/ir-policy.md b/docs/policies/ir-policy.md index aa3bd3e3..17408ddd 100644 --- a/docs/policies/ir-policy.md +++ b/docs/policies/ir-policy.md @@ -6,7 +6,7 @@ External communication paths: - **Public reporter:** [`/.well-known/security.txt`](../../website/.well-known/security.txt) is the published vulnerability-reporting mailbox. - **FedRAMP incident reports (IEC):** every incident is recorded in the incident register, [`data/incidents.json`](../../data/incidents.json), with its reportability evaluation. Initial, Ongoing and Final Incident Reports for a FedRAMP Reportable Incident are generated from it, validated against FedRAMP's incident report schema, signed, and published under `/.well-known/` (the incident log is `/.well-known/incident-reports.json`) by an unattended workflow on every change to the register. -- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency. The operator has not authorized sending, and the system has no FedRAMP certification and no agency customers. Choosing a delivery channel is an operator decision; until it is made, publication is the only channel and every report says so. +- **Delivery is simulated.** Nothing is sent to FedRAMP or to any agency: the system has no FedRAMP certification and no agency customers. Each report is published and "delivered" to simulated FedRAMP and agency recipients, recorded in `/.well-known/incident-deliveries.json`; a delivery that fails stops publication. - **FedRAMP Security Inbox (FSI, 20x):** simulated for this proof of concept. No mail is received or sent; the inbox logic runs on every deploy over synthetic messages and its result is published as `/.well-known/fedramp-inbox-simulation.json`. The published contact directs FedRAMP to the operator on LinkedIn. Procedure: `docs/runbooks/fedramp-security-inbox.md`. **20x rule integration.** KSI-INR (Incident Response), IEC (Incident Evaluation and Communication), FSI (FedRAMP Security Inbox). diff --git a/infrastructure/bootstrap/incident-reports.tf b/infrastructure/bootstrap/incident-reports.tf index d38fb120..27328344 100644 --- a/infrastructure/bootstrap/incident-reports.tf +++ b/infrastructure/bootstrap/incident-reports.tf @@ -25,9 +25,12 @@ variable "incident_reports_environment" { default = "incident-reports" } -# TRUST: this repository, this GitHub Environment, nothing else. A pull request -# cannot assume it, and neither can a workflow that does not declare the -# environment. +# TRUST: this repository, two GitHub Environments, nothing else. A pull request +# cannot assume it, and neither can a workflow that does not declare one of +# them. The second is the reviewer-gated deploy environment: every deploy +# assumes this role before it builds the SDR (scripts/check-incident-role.py), +# so a deploy cannot publish records claiming a publisher whose role does not +# work. That adds no privilege: the deploy role can already write the bucket. data "aws_iam_policy_document" "incident_reports_trust" { statement { effect = "Allow" @@ -47,7 +50,10 @@ data "aws_iam_policy_document" "incident_reports_trust" { condition { test = "StringEquals" variable = "token.actions.githubusercontent.com:sub" - values = ["repo:${var.github_repo}:environment:${var.incident_reports_environment}"] + values = [ + "repo:${var.github_repo}:environment:${var.incident_reports_environment}", + "repo:${var.github_repo}:environment:${var.deploy_environment}", + ] } } } diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index ccb9eb40..7d129210 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -98,6 +98,18 @@ "signature": ".well-known/incident-reports.bundle", "note": "The incident log (IEC-CSO-EFR) and, through it, every incident report it lists with its sha256. Rebuilt by .github/workflows/incident-reports.yml on every change to data/incidents.json and twice a day, and by every deploy. The report deadlines themselves are hours, so the watchdog also pages on each listed report past its deadline (IncidentReportsOverdue)." }, + { + "path": ".well-known/incident-deliveries.json", + "cadence": "nightly", + "max_age_hours": 24, + "timestamp": { + "source": "json", + "field": "emitted_at" + }, + "signed": true, + "signature": ".well-known/incident-deliveries.bundle", + "note": "SIMULATION: the delivery log of every incident report to a simulated FedRAMP and agency recipient; nothing is sent. Rebuilt with the incident log by every deploy and by .github/workflows/incident-reports.yml." + }, { "path": ".well-known/ksi-signal-runtime.json", "cadence": "runtime", diff --git a/scripts/build-incident-report.py b/scripts/build-incident-report.py index 7c67def4..2c6a1076 100644 --- a/scripts/build-incident-report.py +++ b/scripts/build-incident-report.py @@ -29,9 +29,10 @@ # report due from the finding's first evaluation at the default rating; the # clock check fails, and the evidence watchdog pages, once that time passes. # -# Notification. Delivery to FedRAMP and agencies is not built: the register's -# policy says "published-only" and every report says so. Publication under -# /.well-known/ is the only channel until the operator decides otherwise. +# Notification. Nothing is sent to FedRAMP or to agencies: the register's +# policy says "published-only" and every report says so. After this builder, +# scripts/deliver-incident-reports.py "delivers" each report to SIMULATED +# FedRAMP and agency recipients and writes the delivery log. # # build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . # build-incident-report.py --check incident-reports.json # exit 1 if a report is overdue diff --git a/scripts/check-incident-publisher.py b/scripts/check-incident-publisher.py index e31d3cfa..cd07288b 100644 --- a/scripts/check-incident-publisher.py +++ b/scripts/check-incident-publisher.py @@ -18,9 +18,10 @@ the deploy's later incident-publisher job assumes the role from that environment, so a wrong environment still fails the deploy there. -Whether the role itself works is proved later in the same run: the -`incident-publisher` job calls .github/workflows/incident-reports.yml, which -assumes the role, publishes, and fails the deploy if it cannot. +Whether the role itself works is proved in the same job before the SDR is +built (scripts/check-incident-role.py assumes it), and again after the deploy: +the `incident-publisher` job calls .github/workflows/incident-reports.yml, +which assumes the role, publishes, and fails the deploy if it cannot. Prints no ARN or account ID. Exit 0 pass, 1 fail. """ diff --git a/scripts/check-incident-role.py b/scripts/check-incident-role.py new file mode 100644 index 00000000..192c5241 --- /dev/null +++ b/scripts/check-incident-role.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +"""Deploy gate: the incident report publisher's role can actually be assumed. + +The IEC records describe a system whose unattended publisher +(.github/workflows/incident-reports.yml) assumes the role +infrastructure/bootstrap/incident-reports.tf creates. The deploy job runs this +before it builds the SDR, so a deploy whose publisher role does not work stops +before any record claiming it is published: + + 1. request the job's GitHub OIDC token (audience sts.amazonaws.com); + 2. call STS AssumeRoleWithWebIdentity for AWS_INCIDENT_REPORTS_ROLE_ARN; + 3. require success, and that the assumed role is + github-actions-incident-reports-oidc. + +The temporary credentials STS returns are discarded unused. Prints no token, +credential, ARN or account ID. Stdlib only. Exit 0 pass, 1 fail. +""" + +from __future__ import annotations + +import json +import os +import re +import sys +import urllib.error +import urllib.parse +import urllib.request +import xml.etree.ElementTree as ET + +EXPECTED_ROLE_NAME = "github-actions-incident-reports-oidc" +SESSION = "deploy-proves-incident-publisher" +STS_URL = "https://sts.{region}.amazonaws.com/" +REGION_RE = re.compile(r"^[a-z]{2}(-[a-z]+)+-[0-9]$") +ASSUMED_RE = re.compile(r"^arn:aws(-[a-z]+)*:sts::[0-9]{12}:assumed-role/([\w+=,.@-]+)/[\w+=,.@-]+$") + + +def _local(tag: str) -> str: + return tag.rsplit("}", 1)[-1] + + +def parse_sts(status: int, body: str) -> list[str]: + """Problems with an AssumeRoleWithWebIdentity response, or [].""" + try: + root = ET.fromstring(body) + except ET.ParseError: + return [f"STS returned HTTP {status} with a body that is not XML"] + found = {_local(e.tag): (e.text or "").strip() for e in root.iter()} + if status != 200 or "Error" in found: + code = re.sub(r"[^A-Za-z.]", "", found.get("Code", "unknown"))[:64] + return [f"STS refused the incident publisher role ({code}, HTTP {status}): the role or its trust for the " + f"deploy environment is missing; apply infrastructure/bootstrap/incident-reports.tf"] + m = ASSUMED_RE.match(found.get("Arn", "")) + if not m: + return ["STS answered without an assumed-role identity"] + if m.group(2) != EXPECTED_ROLE_NAME: + return [f"the assumed role is not {EXPECTED_ROLE_NAME}"] + return [] + + +def oidc_token(env=os.environ, opener=urllib.request.urlopen) -> str: + url, bearer = env.get("ACTIONS_ID_TOKEN_REQUEST_URL"), env.get("ACTIONS_ID_TOKEN_REQUEST_TOKEN") + if not url or not bearer: + raise RuntimeError("no GitHub OIDC token available (the job needs permissions: id-token: write)") + sep = "&" if "?" in url else "?" + req = urllib.request.Request(url + sep + "audience=sts.amazonaws.com", headers={"Authorization": f"bearer {bearer}"}) + with opener(req, timeout=30) as r: + return json.loads(r.read())["value"] + + +def assume(role_arn: str, token: str, region: str, opener=urllib.request.urlopen) -> tuple[int, str]: + data = urllib.parse.urlencode({"Action": "AssumeRoleWithWebIdentity", "Version": "2011-06-15", + "RoleArn": role_arn, "RoleSessionName": SESSION, "DurationSeconds": "900", + "WebIdentityToken": token}).encode() + req = urllib.request.Request(STS_URL.format(region=region), data=data, method="POST") + try: + with opener(req, timeout=30) as r: + return r.status, r.read().decode("utf-8", "replace") + except urllib.error.HTTPError as e: + return e.code, e.read().decode("utf-8", "replace") + + +def main(argv=None, env=os.environ, opener=urllib.request.urlopen) -> int: + role_arn = (env.get("INCIDENT_REPORTS_ROLE_ARN") or "").strip() + region = env.get("AWS_REGION") or "us-east-2" + if not REGION_RE.match(region): + # The region becomes part of the STS host name; never let it pick the host. + problems = ["AWS_REGION is not an AWS region name"] + elif not role_arn: + problems = ["AWS_INCIDENT_REPORTS_ROLE_ARN is not set"] + else: + try: + status, body = assume(role_arn, oidc_token(env, opener), region, opener) + problems = parse_sts(status, body) + except (RuntimeError, urllib.error.URLError, KeyError, ValueError) as e: + problems = [f"could not ask STS: {type(e).__name__}"] + for p in problems: + print(f"::error::incident publisher role: {p}") + if not problems: + print(f"incident publisher role: assumed {EXPECTED_ROLE_NAME} from the deploy job; credentials discarded") + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/deliver-incident-reports.py b/scripts/deliver-incident-reports.py new file mode 100644 index 00000000..00140170 --- /dev/null +++ b/scripts/deliver-incident-reports.py @@ -0,0 +1,127 @@ +#!/usr/bin/env python3 +"""Deliver every incident report to a SIMULATED FedRAMP and agency recipient. + +IEC-CSO-IIR/OIR/FIR ask that each report reach FedRAMP and every affected +agency; IEC-CSO-AIR asks that this be automated. This proof of concept has no +FedRAMP certification and no agency customer, so by the operator's decision the +recipients are simulated and NOTHING IS SENT. What is real is the mechanism: +every report the incident log lists is read back, checked against the sha256 +the log published for it and against FedRAMP's incident report schema, and +handed to each recipient, whose (simulated) receipt is the hash it received. + +Any failure exits 1 and writes nothing, which stops the deploy (and the +unattended publisher) before anything is published: + - a report the log lists is missing, or its bytes differ from the log's sha256 + - a report does not validate against FedRAMP's incident report schema + - a report file in the directory is not listed in the log + - a reportable incident has a report with no FedRAMP or no agency recipient + +On success it writes incident-deliveries.json, the delivery log, labelled as a +simulation, for the workflow to sign and publish under /.well-known/. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _fedramp_schema as fs # noqa: E402 + +FEDRAMP = "FedRAMP Incident Desk (simulated): accepts every report, replies to none, and has never heard of this system" +DEFAULT_AGENCY = "Department of Hypothetical Affairs (simulated): this system has no agency customer" +NOTICE = ("SIMULATION. Every incident report below was 'delivered' to simulated recipients: nothing was sent to " + "FedRAMP or to any agency, and no inbox anywhere received anything. The delivery mechanism is real and runs " + "on every deploy and every unattended publish: each report is read back, checked against the sha256 in " + "incident-reports.json and against FedRAMP's incident report schema, and its receipt is that hash. A " + "delivery that fails stops publication. Real recipients would need an operator decision and a FedRAMP " + "certification, neither of which exists.") + + +def sha256(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def deliver(log: dict, report_dir: Path, now: str | None = None, registry=None) -> tuple[dict | None, list[str]]: + """(delivery log, problems). The delivery log is None when there are problems.""" + problems: list[str] = [] + deliveries = [] + listed = set() + for inc in log.get("incidents", []): + reports = inc.get("reports") or [] + if reports and not (inc.get("evaluation") or {}).get("reportable"): + problems.append(f"{inc.get('id')}: reports issued for an incident evaluated not reportable") + for r in reports: + name = r.get("file") or "" + listed.add(name) + path = report_dir / name + if "/" in name or not name.startswith("incident-INC-") or not path.is_file(): + problems.append(f"{inc.get('id')}: report {name!r} is listed but missing") + continue + got = sha256(path) + if got != r.get("sha256"): + problems.append(f"{name}: bytes differ from the sha256 the incident log publishes") + continue + doc = json.loads(path.read_text()) + errors = fs.validate(doc, "incident", registry) + if errors: + problems.append(f"{name}: does not validate against FedRAMP's incident report schema ({errors[0]})") + continue + agencies = [a for a in (doc.get("affectedAgencies") or []) if isinstance(a, str) and a.strip()] + recipients: list[dict[str, object]] = [{"recipient": FEDRAMP, "kind": "fedramp"}] + recipients += [{"recipient": f"{a} (simulated)", "kind": "agency"} for a in agencies] or \ + [{"recipient": DEFAULT_AGENCY, "kind": "agency"}] + for rc in recipients: + rc.update(simulated=True, transport="none: simulated, nothing sent", receipt_sha256=got, + result="accepted (simulated)") + kinds = {rc["kind"] for rc in recipients} + if kinds != {"fedramp", "agency"}: + problems.append(f"{name}: no FedRAMP and agency recipient") + deliveries.append({"incident": inc.get("id"), "exercise": bool(inc.get("exercise")), + "report_type": r.get("type"), "file": name, "sha256": got, + "issued_at": r.get("issued_at"), "recipients": recipients}) + for path in sorted(report_dir.glob("incident-INC-*.json")): + if path.name not in listed: + problems.append(f"{path.name}: a report file the incident log does not list") + if problems: + return None, problems + return { + "schema": "incident-deliveries/1", + "simulation": True, + "notice": NOTICE, + "emitted_at": now or datetime.now(timezone.utc).isoformat(), + "generator": "scripts/deliver-incident-reports.py", + "incident_log": "https://samaydlette.com/.well-known/incident-reports.json", + "incident_log_emitted_at": log.get("emitted_at"), + "summary": {"reports_delivered": len(deliveries), + "recipients_reached": sum(len(d["recipients"]) for d in deliveries), + "messages_actually_sent": 0}, + "deliveries": deliveries, + }, [] + + +def main(argv=None) -> int: + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--dir", type=Path, default=Path("."), help="where incident-reports.json and the reports are") + ap.add_argument("--output", type=Path, default=None) + a = ap.parse_args(argv) + log = json.loads((a.dir / "incident-reports.json").read_text()) + out, problems = deliver(log, a.dir) + for p in problems: + print(f"::error::incident report delivery (simulated): {p}") + if problems or out is None: + print(f"incident report delivery: {len(problems)} problem(s); nothing delivered, nothing written") + return 1 + target = a.output or (a.dir / "incident-deliveries.json") + target.write_text(json.dumps(out, indent=2) + "\n") + print(f"incident report delivery (SIMULATED, nothing sent): {out['summary']['reports_delivered']} report(s) to " + f"{out['summary']['recipients_reached']} simulated recipient(s); wrote {target}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/incidents/delivery-hash-mismatch.json b/tests/fixtures/incidents/delivery-hash-mismatch.json new file mode 100644 index 00000000..5c98f87d --- /dev/null +++ b/tests/fixtures/incidents/delivery-hash-mismatch.json @@ -0,0 +1,37 @@ +{ + "schema": "incident-reports/1", + "emitted_at": "2026-11-05T00:00:00Z", + "incidents": [ + { + "id": "INC-2026-001", + "exercise": true, + "evaluation": { + "reportable": true + }, + "reports": [ + { + "type": "Initial", + "issued_at": "2026-11-05T03:40:00Z", + "file": "incident-INC-2026-001-01-initial.json", + "sha256": "0000000000000000000000000000000000000000000000000000000000000000", + "changes": { + "coordinator": "updated", + "tracking_id": "updated", + "description": "updated", + "timeline": "updated", + "rating": "updated", + "functional_impact": "updated", + "recovery_plan": "updated", + "affected_agencies": "updated", + "observed_activity": "not yet available", + "indicators_of_compromise": "not yet available", + "related_cves": "updated", + "root_cause": "not yet available", + "response_and_recovery_activities": "not yet available" + } + } + ] + } + ], + "_note": "KNOWN-BAD: the log's sha256 for the Initial report is not the report's; delivery must refuse it." +} diff --git a/tests/fixtures/incidents/delivery-missing-report.json b/tests/fixtures/incidents/delivery-missing-report.json new file mode 100644 index 00000000..a04c457b --- /dev/null +++ b/tests/fixtures/incidents/delivery-missing-report.json @@ -0,0 +1,37 @@ +{ + "schema": "incident-reports/1", + "emitted_at": "2026-11-05T00:00:00Z", + "incidents": [ + { + "id": "INC-2026-001", + "exercise": true, + "evaluation": { + "reportable": true + }, + "reports": [ + { + "type": "Initial", + "issued_at": "2026-11-05T03:40:00Z", + "file": "incident-INC-2026-001-09-ongoing.json", + "sha256": "5857e833e1eb8103600a828261e7e51cc3a2aad0e63ba23bd02292f678433d93", + "changes": { + "coordinator": "updated", + "tracking_id": "updated", + "description": "updated", + "timeline": "updated", + "rating": "updated", + "functional_impact": "updated", + "recovery_plan": "updated", + "affected_agencies": "updated", + "observed_activity": "not yet available", + "indicators_of_compromise": "not yet available", + "related_cves": "updated", + "root_cause": "not yet available", + "response_and_recovery_activities": "not yet available" + } + } + ] + } + ], + "_note": "KNOWN-BAD: the log lists a report that was never written; delivery must refuse it." +} diff --git a/tests/fixtures/incidents/delivery-not-reportable.json b/tests/fixtures/incidents/delivery-not-reportable.json new file mode 100644 index 00000000..1be3e9b3 --- /dev/null +++ b/tests/fixtures/incidents/delivery-not-reportable.json @@ -0,0 +1,37 @@ +{ + "schema": "incident-reports/1", + "emitted_at": "2026-11-05T00:00:00Z", + "incidents": [ + { + "id": "INC-2026-002", + "exercise": true, + "evaluation": { + "reportable": false + }, + "reports": [ + { + "type": "Initial", + "issued_at": "2026-11-05T03:40:00Z", + "file": "incident-INC-2026-001-01-initial.json", + "sha256": "5857e833e1eb8103600a828261e7e51cc3a2aad0e63ba23bd02292f678433d93", + "changes": { + "coordinator": "updated", + "tracking_id": "updated", + "description": "updated", + "timeline": "updated", + "rating": "updated", + "functional_impact": "updated", + "recovery_plan": "updated", + "affected_agencies": "updated", + "observed_activity": "not yet available", + "indicators_of_compromise": "not yet available", + "related_cves": "updated", + "root_cause": "not yet available", + "response_and_recovery_activities": "not yet available" + } + } + ] + } + ], + "_note": "KNOWN-BAD: reports listed under an incident evaluated not reportable; delivery must refuse them." +} diff --git a/tests/fixtures/incidents/sts-access-denied.xml b/tests/fixtures/incidents/sts-access-denied.xml new file mode 100644 index 00000000..a3f7cdb3 --- /dev/null +++ b/tests/fixtures/incidents/sts-access-denied.xml @@ -0,0 +1,7 @@ + + + Sender + AccessDenied + Not authorized to perform sts:AssumeRoleWithWebIdentity + + diff --git a/tests/fixtures/incidents/sts-assumed.xml b/tests/fixtures/incidents/sts-assumed.xml new file mode 100644 index 00000000..3326d81c --- /dev/null +++ b/tests/fixtures/incidents/sts-assumed.xml @@ -0,0 +1,9 @@ + + + + arn:aws:sts::000000000000:assumed-role/github-actions-incident-reports-oidc/deploy-proves-incident-publisher + AROAEXAMPLE:deploy-proves-incident-publisher + + EXAMPLEEXAMPLEEXAMPLE + + diff --git a/tests/fixtures/incidents/sts-wrong-role.xml b/tests/fixtures/incidents/sts-wrong-role.xml new file mode 100644 index 00000000..e6db430a --- /dev/null +++ b/tests/fixtures/incidents/sts-wrong-role.xml @@ -0,0 +1,9 @@ + + + + arn:aws:sts::000000000000:assumed-role/github-actions-deploy-oidc/deploy-proves-incident-publisher + AROAEXAMPLE:deploy-proves-incident-publisher + + EXAMPLEEXAMPLEEXAMPLE + + diff --git a/tests/test_incident_delivery.py b/tests/test_incident_delivery.py new file mode 100644 index 00000000..f2e8cafa --- /dev/null +++ b/tests/test_incident_delivery.py @@ -0,0 +1,210 @@ +"""Incident reports reach a SIMULATED FedRAMP and agency recipient, and the +publisher's role is proved before the SDR is built (IEC-CSO-IIR/OIR/FIR/AIR). + +scripts/deliver-incident-reports.py "delivers" every report the incident log +lists (nothing is sent) and fails the deploy when one cannot be delivered; +scripts/check-incident-role.py assumes the incident publisher's role from the +deploy job. Known-bad fixtures under tests/fixtures/incidents/ each fail for +one reason.""" + +import importlib.util +import io +import json +import re +import shutil +import subprocess +import sys +import urllib.error +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "incidents" +WORKFLOW = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() +PUBLISHER = (REPO / ".github" / "workflows" / "incident-reports.yml").read_text() + + +def _load(name, file): + spec = importlib.util.spec_from_file_location(name, REPO / "scripts" / file) + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +deliver = _load("deliver_incident_reports", "deliver-incident-reports.py") +role = _load("check_incident_role", "check-incident-role.py") + + +@pytest.fixture +def built(tmp_path): + """The committed register's reports, built as the deploy builds them.""" + (tmp_path / "vdr.json").write_text('{"findings": []}') + subprocess.run([sys.executable, str(REPO / "scripts" / "build-incident-report.py"), "--incidents", + str(REPO / "data" / "incidents.json"), "--vdr", str(tmp_path / "vdr.json"), + "--out-dir", str(tmp_path)], check=True, capture_output=True) + return tmp_path + + +def _log(d): + return json.loads((d / "incident-reports.json").read_text()) + + +# --- delivery ------------------------------------------------------------------- + +def test_every_report_is_delivered_to_a_simulated_fedramp_and_agency_recipient(built): + out, problems = deliver.deliver(_log(built), built) + assert problems == [] + listed = [r["file"] for i in _log(built)["incidents"] for r in i.get("reports", [])] + assert listed and [d["file"] for d in out["deliveries"]] == listed + for d in out["deliveries"]: + assert {r["kind"] for r in d["recipients"]} == {"fedramp", "agency"} + assert all(r["simulated"] is True and "(simulated)" in r["recipient"] for r in d["recipients"]) + assert all(r["receipt_sha256"] == d["sha256"] for r in d["recipients"]) + assert out["simulation"] is True and out["notice"].startswith("SIMULATION.") + assert out["summary"]["messages_actually_sent"] == 0 + + +def test_the_cli_writes_the_delivery_log_and_it_carries_no_address(built): + assert deliver.main(["--dir", str(built)]) == 0 + text = (built / "incident-deliveries.json").read_text() + assert not re.search(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}", text) + assert not re.search(r"\b\d{12}\b", text) + + +def _with_fixture(built, name, keep): + shutil.copy(FIX / f"{name}.json", built / "incident-reports.json") + for p in built.glob("incident-INC-*.json"): + if p.name not in keep: + p.unlink() + return deliver.main(["--dir", str(built)]) + + +@pytest.mark.parametrize("name,keep,reason", [ + ("delivery-hash-mismatch", {"incident-INC-2026-001-01-initial.json"}, "bytes differ from the sha256"), + ("delivery-missing-report", set(), "is listed but missing"), + ("delivery-not-reportable", {"incident-INC-2026-001-01-initial.json"}, "evaluated not reportable"), +]) +def test_known_bad_logs_fail_delivery_and_write_nothing(built, capsys, name, keep, reason): + assert _with_fixture(built, name, keep) == 1 + out = capsys.readouterr().out + assert reason in out and not (built / "incident-deliveries.json").exists() + assert len([ln for ln in out.splitlines() if ln.startswith("::error::")]) == 1, out + + +def test_an_unlisted_report_file_fails_delivery(built): + (built / "incident-INC-2099-999-01-initial.json").write_text("{}") + _, problems = deliver.deliver(_log(built), built) + assert problems == ["incident-INC-2099-999-01-initial.json: a report file the incident log does not list"] + + +def test_a_report_that_does_not_validate_against_fedramps_schema_fails_delivery(built): + log = _log(built) + r = log["incidents"][0]["reports"][0] + p = built / r["file"] + doc = json.loads(p.read_text()) + doc.pop("reportType") + p.write_text(json.dumps(doc)) + r["sha256"] = deliver.sha256(p) + _, problems = deliver.deliver(log, built) + assert len(problems) == 1 and "does not validate" in problems[0] + + +def test_delivery_runs_before_signing_in_the_deploy_and_before_publishing_in_the_publisher(): + build = WORKFLOW[WORKFLOW.index("- name: Build incident reports (IIR, OIR, FIR)"):] + build = build[:build.index("\n - name: ")] + assert build.index("deliver-incident-reports.py --dir .") < build.index("cosign sign-blob") + assert "|| true" not in build + assert WORKFLOW.index("- name: Build incident reports") < WORKFLOW.index("- name: Build Security Decision Record") + for f in ("incident-deliveries.json", "incident-deliveries.bundle"): + assert f'aws s3 cp {f} "s3://$BUCKET_NAME/.well-known/{f}"' in WORKFLOW + assert f'put {f} "application/json"' in PUBLISHER + step = PUBLISHER.index("- name: Deliver incident reports (simulated recipients; nothing sent)") + assert PUBLISHER.index("- name: Build incident reports") < step < PUBLISHER.index("- name: Sign incident reports") + cfg = json.loads((REPO / "infrastructure" / "schemas" / "freshness-config.json").read_text()) + e = [a for a in cfg["artifacts"] if a["path"] == ".well-known/incident-deliveries.json"] + assert len(e) == 1 and e[0]["signed"] and e[0]["note"].startswith("SIMULATION") + + +# --- the role, proved from the deploy job ------------------------------------------- + +@pytest.mark.parametrize("fixture,ok", [("sts-assumed.xml", True), ("sts-access-denied.xml", False), + ("sts-wrong-role.xml", False)]) +def test_sts_responses(fixture, ok): + status = 403 if "denied" in fixture else 200 + problems = role.parse_sts(status, (FIX / fixture).read_text()) + assert (problems == []) is ok, problems + + +class _Resp(io.BytesIO): + def __init__(self, body, status=200): + super().__init__(body.encode()) + self.status = status + + def __enter__(self): + return self + + def __exit__(self, *a): + return False + + +def _opener(sts_fixture): + calls = [] + + def opener(req, timeout=None): + calls.append(req) + if req.full_url.startswith("https://token.example/"): + assert "audience=sts.amazonaws.com" in req.full_url + return _Resp(json.dumps({"value": "oidc-token"})) + assert req.full_url == "https://sts.us-east-2.amazonaws.com/" and b"AssumeRoleWithWebIdentity" in req.data + body = (FIX / sts_fixture).read_text() + if "denied" in sts_fixture: + raise urllib.error.HTTPError(req.full_url, 403, "Forbidden", {}, io.BytesIO(body.encode())) + return _Resp(body) + return opener, calls + + +ENV = {"INCIDENT_REPORTS_ROLE_ARN": "arn:aws:iam::000000000000:role/github-actions-incident-reports-oidc", + "ACTIONS_ID_TOKEN_REQUEST_URL": "https://token.example/?x=1", "ACTIONS_ID_TOKEN_REQUEST_TOKEN": "t", + "AWS_REGION": "us-east-2"} + + +def test_the_deploy_proves_the_role_by_assuming_it(capsys): + opener, calls = _opener("sts-assumed.xml") + assert role.main(env=ENV, opener=opener) == 0 and len(calls) == 2 + out = capsys.readouterr().out + assert "000000000000" not in out and "oidc-token" not in out and "EXAMPLE" not in out + + +@pytest.mark.parametrize("fixture", ["sts-access-denied.xml", "sts-wrong-role.xml"]) +def test_a_role_that_cannot_be_assumed_fails_the_deploy(capsys, fixture): + opener, _ = _opener(fixture) + assert role.main(env=ENV, opener=opener) == 1 + assert "000000000000" not in capsys.readouterr().out + + +def test_no_variable_or_no_oidc_token_fails_the_deploy(): + assert role.main(env={**ENV, "INCIDENT_REPORTS_ROLE_ARN": ""}, opener=None) == 1 + env = {k: v for k, v in ENV.items() if not k.startswith("ACTIONS_")} + assert role.main(env=env, opener=_opener("sts-assumed.xml")[0]) == 1 + + +def test_the_role_check_runs_in_the_deploy_job_before_the_sdr_build(): + deploy_job = WORKFLOW[WORKFLOW.index("\n deploy:\n"):] + deploy_job = deploy_job[:re.search(r"\n [a-z][\w-]*:\n", deploy_job[1:]).start() + 1] + i = deploy_job.index("- name: Incident report publisher role can be assumed") + assert i < deploy_job.index("- name: Build Security Decision Record") + step = deploy_job[i:deploy_job.index("\n - name: ", i)] + assert "python3 scripts/check-incident-role.py" in step and "continue-on-error" not in step + assert "vars.AWS_INCIDENT_REPORTS_ROLE_ARN" in step + + +def test_the_role_trusts_the_deploy_environment(): + tf = (REPO / "infrastructure" / "bootstrap" / "incident-reports.tf").read_text() + assert "environment:${var.deploy_environment}" in tf + assert "environment:${var.incident_reports_environment}" in tf + + +def test_the_region_cannot_redirect_the_token_to_another_host(): + opener, calls = _opener("sts-assumed.xml") + assert role.main(env={**ENV, "AWS_REGION": "evil.example/x"}, opener=opener) == 1 and calls == [] diff --git a/tests/test_incidents.py b/tests/test_incidents.py index 36cc70ba..1f1b435f 100644 --- a/tests/test_incidents.py +++ b/tests/test_incidents.py @@ -73,7 +73,7 @@ def test_the_committed_register_adopts_both_vulnerability_rules_and_publishes_on p = json.loads(REGISTER.read_text())["policy"] assert set(p["adopted_vulnerability_rules"]) == {"VER-TFR-IRI", "VER-TFR-NRI"} assert p["notification"] == "published-only" - assert "not authorized" in p["notification_text"] + assert "Nothing is sent" in p["notification_text"] and "SIMULATED" in p["notification_text"] BAD = { @@ -306,7 +306,7 @@ def test_reports_are_deterministic_and_say_they_are_published_only(exercise, tmp for a, b in zip(log["incidents"], again["incidents"], strict=True): assert [r["sha256"] for r in a["reports"]] == [r["sha256"] for r in b["reports"]] md = (out / "incident-reports.md").read_text() - assert "published-only" in md and "not authorized" in md and "(no update)" in md + assert "published-only" in md and "Nothing is sent" in md and "(no update)" in md assert log["notification"]["mode"] == "published-only" diff --git a/tests/test_published_redaction.py b/tests/test_published_redaction.py index c63752c0..96068092 100644 --- a/tests/test_published_redaction.py +++ b/tests/test_published_redaction.py @@ -200,12 +200,13 @@ def test_deploy_gates_exactly_what_it_publishes(tmp_path): (tmp_path / f"{a}.json").write_text("{}") # The incident reports are named by incident, so the steps use globs; with # the files the builder writes present, both expand to the same set. - incident_files = ("incident-reports.json", "incident-reports.md", "incident-INC-2026-001-01-initial.json") + incident_files = ("incident-reports.json", "incident-reports.md", "incident-deliveries.json", + "incident-INC-2026-001-01-initial.json") for f in incident_files: (tmp_path / f).write_text("{}") assert "incident-INC-*.json" in publish publish = {n for n in publish if "*" not in n} | {f for f in incident_files if f.startswith("incident-INC-")} - assert {"incident-reports.json", "incident-reports.md"} <= publish + assert {"incident-reports.json", "incident-reports.md", "incident-deliveries.json"} <= publish assert _gate_files(gate_step, tmp_path) == publish # One absent (the operator-run corroboration): it is neither uploaded nor scanned. (tmp_path / "boundary-corroboration.json").unlink()