diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 933f590b..20e83db0 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1602,6 +1602,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 @@ -1694,6 +1718,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 @@ -1722,6 +1750,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" @@ -1781,6 +1811,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 @@ -1871,6 +1909,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 c7d069f9..a437dff0 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -968,165 +968,369 @@ }, { "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).", - "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.", - "closes_with": [ - "W5" + "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" + } ] }, { "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..3f147272 --- /dev/null +++ b/scripts/build-scn.py @@ -0,0 +1,414 @@ +#!/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" +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,}") + +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].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: + 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..9212d63e --- /dev/null +++ b/tests/test_scn.py @@ -0,0 +1,455 @@ +"""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 + # 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", + ".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) + 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(): + 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