diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 933f590b..3b0a58aa 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -606,6 +606,19 @@ jobs: with: fetch-depth: 0 + # The incident report records (IEC-CSO-IIR/OIR/FIR/AIR) describe the system + # after a successful deploy, which includes the unattended publisher in + # .github/workflows/incident-reports.yml. Fail before anything is applied if + # its prerequisites are missing: the role variable set and naming the + # bootstrap role, and the incident-reports environment main-only (checked + # when the job token can read it; said so when it cannot). The + # incident-publisher job below then proves the role publishes. + - name: Incident report publisher preflight + env: + INCIDENT_REPORTS_ROLE_ARN: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }} + GITHUB_TOKEN: ${{ github.token }} + run: python3 scripts/check-incident-publisher.py + - name: Setup Terraform uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1 with: @@ -1532,6 +1545,23 @@ jobs: cosign sign-blob --yes --new-bundle-format --bundle "$a.bundle" "$a.json" done + # Incident reports (IEC-CSO-IIR/OIR/FIR) and the incident log, from the + # incident register and this build's VDR (VER-TFR-IRI/NRI triggers). The + # same builder runs unattended in incident-reports.yml on every change to + # the register; the deploy republishes them so a deploy never serves a log + # older than the register it was built from. Each report is validated + # against FedRAMP's schema before it is written. No clock check here: an + # overdue report must not block the deploy that may be the fix; the + # incident-reports workflow and the evidence watchdog alarm on it. + - name: Build incident reports (IIR, OIR, FIR) + working-directory: infrastructure + run: | + set -euo pipefail + python3 ../scripts/build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . + for f in incident-*.json; do + cosign sign-blob --yes --new-bundle-format --bundle "${f%.json}.bundle" "$f" + done + # ------------------------------------------------------------------------- # PROJECT THE CANONICAL INVENTORY INTO FEDRAMP IIW (APPENDIX M) SHAPE # ------------------------------------------------------------------------- @@ -1726,6 +1756,8 @@ jobs: [ -f "$a.json" ] || continue files="$files $a.json" done + # Incident log and reports (built every deploy, so the glob always matches). + for f in incident-*.json incident-*.md; do files="$files $f"; done # shellcheck disable=SC2086 # a word list by design python3 ../scripts/check-published-redaction.py $files @@ -1788,6 +1820,14 @@ jobs: aws s3 cp "$a.json" "s3://$BUCKET_NAME/.well-known/$a.json" --content-type application/json --cache-control "public, max-age=300" aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" done + # Incident log (IEC-CSO-EFR) + every Initial/Ongoing/Final report + signatures + aws s3 cp incident-reports.json "s3://$BUCKET_NAME/.well-known/incident-reports.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp incident-reports.bundle "s3://$BUCKET_NAME/.well-known/incident-reports.bundle" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp incident-reports.md "s3://$BUCKET_NAME/.well-known/incident-reports.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + for f in incident-INC-*.json; do + aws s3 cp "$f" "s3://$BUCKET_NAME/.well-known/$f" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "${f%.json}.bundle" "s3://$BUCKET_NAME/.well-known/${f%.json}.bundle" --content-type application/json --cache-control "public, max-age=300" + done echo "✅ All signed artifacts published to /.well-known/ (post-gate)" # ------------------------------------------------------------------------- @@ -1877,6 +1917,7 @@ jobs: check trust-center.json .well-known/trust-center.json check conformance-results.json .well-known/conformance-results.json if [ -f boundary-corroboration.json ]; then check boundary-corroboration.json .well-known/boundary-corroboration.json; fi + for f in incident-*.json; do check "$f" ".well-known/$f"; done # SLSA/in-toto provenance attestations (S2/S3): served bytes match the build. for a in ksi-signal.json security-decision-record.json vdr-report.json iiw.csv; do check "$a.intoto.jsonl" ".well-known/$a.intoto.jsonl" @@ -2174,11 +2215,27 @@ jobs: # which is functionally the same as no alert: nothing distinguishes the one # that matters. It now reuses a single issue, reopening and commenting, and # assigns it to the repository owner so it reaches a person. + # A deploy is not done until the unattended incident report publisher has run + # on its own role from the incident-reports environment: the IEC records say + # it publishes, so a deploy where it cannot fails here. + incident-publisher: + name: Prove the incident report publisher + needs: [deploy] + if: needs.deploy.result == 'success' + permissions: + contents: read + id-token: write + issues: write + uses: ./.github/workflows/incident-reports.yml + # Least privilege: the one secret the publisher uses, not `inherit`. + secrets: + CLOUDFRONT_DISTRIBUTION_ID: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} + notify: name: Notify on Failure runs-on: ubuntu-latest - needs: [compliance-check, deploy] - if: always() && (needs.compliance-check.result == 'failure' || needs.deploy.result == 'failure') + needs: [compliance-check, deploy, incident-publisher] + if: always() && (needs.compliance-check.result == 'failure' || needs.deploy.result == 'failure' || needs.incident-publisher.result == 'failure') permissions: contents: read issues: write @@ -2192,6 +2249,7 @@ jobs: env: COMPLIANCE_RESULT: ${{ needs.compliance-check.result }} DEPLOY_RESULT: ${{ needs.deploy.result }} + PUBLISHER_RESULT: ${{ needs.incident-publisher.result }} with: script: | const TITLE = `Deployment failing: ${context.workflow}`; @@ -2207,6 +2265,7 @@ jobs: `| Ref | ${context.ref} |`, `| Compliance check | \`${process.env.COMPLIANCE_RESULT}\` |`, `| Deploy | \`${process.env.DEPLOY_RESULT}\` |`, + `| Incident report publisher | \`${process.env.PUBLISHER_RESULT}\` |`, ``, `Review the failing step in the run log, and the compliance reports it uploaded.`, ``, diff --git a/.github/workflows/incident-reports.yml b/.github/workflows/incident-reports.yml new file mode 100644 index 00000000..e8b2abee --- /dev/null +++ b/.github/workflows/incident-reports.yml @@ -0,0 +1,254 @@ +# ============================================================================= +# GitHub Actions Workflow: Incident Reports (IEC-CSO-AIR) +# ============================================================================= +# FedRAMP's Incident Evaluation and Communication rules put an Initial Incident +# Report one hour after a FedRAMP Reportable Incident is identified (Class C, +# N3-N5), and an Ongoing report every six hours after that. The deploy path is +# behind a human reviewer and cannot keep those clocks, so reporting runs here, +# unattended, the moment the incident register changes (IEC-CSO-AIR: automate +# reporting; no hand-crafted email): +# +# push to data/incidents.json on main, or by hand, or twice a day, or after +# each nightly VDR refresh +# -> validate the register (scripts/_incidents.py, fail-closed) +# -> fetch the published VDR, verified against the deploy or nightly +# identity, for the vulnerabilities that are reportable incidents +# (VER-TFR-IRI / VER-TFR-NRI, decided by policies/triage.rego) +# -> build every IIR/OIR/FIR (validated against FedRAMP's incident report +# schema) and the incident log (scripts/build-incident-report.py) +# -> sign, redaction-gate, publish under /.well-known/incident-*, invalidate +# -> check the clocks: fail, and raise an issue, when a report is overdue +# +# The evidence watchdog (infrastructure/watchdog.tf) reads the published log +# hourly and pages by email when a listed report passes its deadline, on AWS's +# clock, whether or not this workflow runs. +# +# NOTIFICATION IS PUBLISH-ONLY. Nothing here sends a report to FedRAMP or to an +# agency. The operator has not authorized sending, and this system has no +# FedRAMP certification and no agency customers; the register's policy and +# every report say so. Sending is a separate decision and a separate change. +# +# THE TRADE, as for the evidence nightly: an unattended production write. Its +# role (infrastructure/bootstrap/incident-reports.tf, operator-applied) can put +# objects under `.well-known/incident-*` and invalidate the CDN, and nothing +# else: no Terraform, no website sync, no delete, no read of anything. +# ============================================================================= + +name: Incident Reports + +on: + push: + branches: [main] + paths: [data/incidents.json] + workflow_dispatch: + # Called by every deploy (deploy-with-opa.yml, job incident-publisher) after + # the deploy job succeeds, so a green deploy proves this publisher assumes its + # role from the incident-reports environment and publishes; a deploy whose + # publisher cannot fails. + workflow_call: + # Only the secret the publish step uses; the caller passes it by name. + secrets: + CLOUDFRONT_DISTRIBUTION_ID: + required: true + # Keeps the published log inside its 24-hour freshness window when nothing + # changes, and re-reads the VDR for new VER-TFR-IRI/NRI triggers. + schedule: + - cron: '47 7 * * *' + - cron: '47 19 * * *' + # Right after each nightly VDR refresh, so a vulnerability that has just + # become a reportable incident is in the log within minutes of the VDR. + workflow_run: + workflows: [Evidence Nightly (VDR refresh)] + types: [completed] + branches: [main] + +concurrency: + group: incident-reports + cancel-in-progress: false + +permissions: + contents: read + +env: + AWS_REGION: us-east-2 + # Same pins as the deploy and the nightly (tests/test_incidents.py checks). + OPA_VERSION: 1.18.2 + OPA_SHA256: 9903e5125ac281104f2c4b7371d10cc3b74a98933743fcbfc174f9bf0ab20de8 + SITE_BUCKET: samaydlette.com + SITE_ORIGIN: https://samaydlette.com + COSIGN_OIDC_ISSUER: https://token.actions.githubusercontent.com + +jobs: + report: + name: Build, sign and publish incident reports + runs-on: ubuntu-latest + timeout-minutes: 20 + # A nightly that did not succeed published no new VDR; a pull request never + # reaches the role. The event check closes a fork branch named `main`. + if: >- + github.event_name != 'workflow_run' || ( + github.event.workflow_run.conclusion == 'success' && + github.event.workflow_run.event != 'pull_request' && + github.event.workflow_run.head_repository.full_name == github.repository) + # No required reviewer: the clocks run while nobody is awake. The role this + # environment can assume writes only .well-known/incident-*. + environment: incident-reports + outputs: + clock: ${{ steps.clock.outcome }} + publish: ${{ steps.publish.outcome }} + permissions: + contents: read + id-token: write + + steps: + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install cosign + uses: sigstore/cosign-installer@7e8b541eb2e61bf99390e1afd4be13a184e9ebc5 # v3.10.1 + + - name: Setup OPA (triage policy) + run: | + curl -fL --retry 5 --retry-delay 5 --connect-timeout 10 --max-time 120 \ + -o opa "https://openpolicyagent.org/downloads/v${{ env.OPA_VERSION }}/opa_linux_amd64_static" + echo "${{ env.OPA_SHA256 }} opa" | sha256sum -c - + chmod 755 ./opa + sudo mv opa /usr/local/bin + opa version + + # The VDR arrives over the public internet, so it is verified before a byte + # of it is used: it must be signed by the deploy or the nightly on main. + - name: Fetch and verify the published VDR report + run: | + set -euo pipefail + mkdir -p out + curl -sfL --retry 3 --retry-delay 5 -o vdr-report.json "${SITE_ORIGIN}/.well-known/vdr-report.json" + curl -sfL --retry 3 --retry-delay 5 -o vdr-report.bundle "${SITE_ORIGIN}/.well-known/vdr-report.bundle" + ok=0 + for wf in deploy-with-opa evidence-nightly; do + if cosign verify-blob --bundle vdr-report.bundle \ + --certificate-identity "https://github.com/${{ github.repository }}/.github/workflows/$wf.yml@refs/heads/main" \ + --certificate-oidc-issuer "${COSIGN_OIDC_ISSUER}" vdr-report.json 2>/dev/null; then ok=1; break; fi + done + [ "$ok" -eq 1 ] || { echo "::error::the published VDR does not verify; refusing to derive incidents from it"; exit 1; } + + - name: Build incident reports (IIR, OIR, FIR) + id: build + run: python3 scripts/build-incident-report.py --incidents data/incidents.json --vdr vdr-report.json --out-dir out + + - name: Sign incident reports + working-directory: out + run: | + set -euo pipefail + for f in incident-*.json; do + cosign sign-blob --yes --new-bundle-format --bundle "${f%.json}.bundle" "$f" + done + + - name: Publication redaction gate (no AWS account ID) + working-directory: out + run: python3 ../scripts/check-published-redaction.py incident-*.json incident-*.md + + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0 + timeout-minutes: 6 + with: + # Defined in infrastructure/bootstrap/incident-reports.tf. Unset until + # the operator applies it and sets the variable; this step then fails + # and the alert job says so. + role-to-assume: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }} + aws-region: ${{ env.AWS_REGION }} + retry-max-attempts: 5 + + - name: Publish incident reports to /.well-known/ + id: publish + working-directory: out + run: | + set -euo pipefail + put() { + aws s3api put-object --bucket "${SITE_BUCKET}" --key ".well-known/$1" --body "$1" \ + --content-type "$2" --cache-control "public, max-age=300" --query 'ETag' --output text > /dev/null + echo "published .well-known/$1" + } + # Every report first, the log that lists them last. + for f in incident-INC-*.json; do + put "$f" "application/json" + put "${f%.json}.bundle" "application/json" + done + put incident-reports.md "text/markdown; charset=utf-8" + put incident-reports.bundle "application/json" + put incident-reports.json "application/json" + + - name: Invalidate CloudFront cache (incident paths only) + env: + DISTRIBUTION_ID: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} + run: | + set -euo pipefail + aws cloudfront create-invalidation --distribution-id "${DISTRIBUTION_ID}" \ + --paths "/.well-known/incident-*" --query 'Invalidation.Id' --output text + + - name: Assert the published incident log is fresh at the edge + run: | + set -euo pipefail + python3 scripts/check-evidence-freshness.py \ + --url "${SITE_ORIGIN}/.well-known/incident-reports.json" \ + --expect-sha256 "$(sha256sum out/incident-reports.json | awk '{print $1}')" \ + --retries 12 --retry-delay 20 + + # Last, so an overdue report is published (the log says what is late) and + # still fails the run. The watchdog pages on the same list independently. + - name: Incident report clocks (fail when a report is due and missing) + id: clock + if: ${{ !cancelled() && steps.build.outcome == 'success' }} + run: python3 scripts/build-incident-report.py --check out/incident-reports.json + + alert: + name: Alert on incident reporting + runs-on: ubuntu-latest + needs: [report] + if: always() && needs.report.result == 'failure' + permissions: + contents: read + issues: write + steps: + - name: Raise or update the incident-reporting issue + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + CLOCK: ${{ needs.report.outputs.clock }} + PUBLISH: ${{ needs.report.outputs.publish }} + with: + script: | + const TITLE = 'Incident reporting: a report is overdue or was not published'; + const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`; + const clock = process.env.CLOCK || 'not reached'; + const publish = process.env.PUBLISH || 'not reached'; + const runbook = `${context.payload.repository.html_url}/blob/main/docs/incident-response.md#reporting-fedramp-reportable-incidents-iec`; + const body = [ + `The incident reports workflow failed ([run](${runUrl}), trigger \`${context.eventName}\`).`, + ``, + `| | |`, `|---|---|`, + `| Report clocks | \`${clock}\` |`, + `| Publish | \`${publish}\` |`, + ``, + clock === 'failure' + ? `**A FedRAMP incident report is past its Class C deadline.** The "Incident report clocks" step names each one. Record the report (or open the incident) in data/incidents.json and push; this workflow publishes it.` + : `**The reports were not built or published.** Check the failing step. If "Configure AWS credentials" failed, the incident-reports role or the AWS_INCIDENT_REPORTS_ROLE_ARN variable is missing (infrastructure/bootstrap/incident-reports.tf).`, + ``, + `Runbook: ${runbook}. This issue is reused; each failure adds a comment.`, + ].join('\n'); + const existing = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, repo: context.repo.repo, state: 'all', per_page: 100, + labels: 'incident-reporting', + }); + const match = existing.filter(i => i.title === TITLE && !i.pull_request) + .sort((a, b) => (a.state === b.state ? a.number - b.number : a.state === 'open' ? -1 : 1))[0]; + if (match) { + if (match.state === 'closed') { + await github.rest.issues.update({ owner: context.repo.owner, repo: context.repo.repo, + issue_number: match.number, state: 'open' }); + } + await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, + issue_number: match.number, body }); + } else { + await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: TITLE, + body, labels: ['compliance', 'incident-reporting', 'urgent'], assignees: [context.repo.owner] }); + } diff --git a/CLAUDE.md b/CLAUDE.md index f0a24b76..e7916cd8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,6 +28,7 @@ Confirm against the working tree on first run; correct this section if reality d - `tools/boundary-map/corroborate.py` (local only) — independent corroboration of the map by RAMPART on TAP, which collects the account from the AWS APIs. The operator runs it and commits `docs/boundary/corroboration.json`; the deploy signs and publishes it as `/.well-known/boundary-corroboration.json`, and the trust center reports its result and age (30-day window). Resources only TAP sees go to the decision queue. - `scripts/build-trust-center.py` — the trust center's data (`/.well-known/trust-center.json`, signed): the "is this picture true?" checks, the queue of decisions that need a person, the policy catalog, the escalation rate and the decision log, all derived from this build's artifacts and the registers. Built after the reconciliation gate; fails closed if its inputs are bound to another inventory. A register field that is not recorded (who decided, when, review date) is published as a gap, never filled in. - `.github/workflows/deploy-with-opa.yml`, `infrastructure/Makefile`, `.checkov.yaml` — the pipeline, entry points, and IaC scan config. +- `data/incidents.json` + `scripts/_incidents.py` + `scripts/build-incident-report.py` — the incident register and FedRAMP incident reporting (IEC-CSO-*; VER-TFR-IRI/NRI via `policies/triage.rego` `incident_triggers`). Every incident carries its reportability evaluation; reportable ones get Initial/Ongoing/Final reports in FedRAMP's schema on the Class C clocks read from the pinned rules, published with the incident log at `/.well-known/incident-reports.json`. `.github/workflows/incident-reports.yml` publishes them unattended (role in `infrastructure/bootstrap/incident-reports.tf`, `.well-known/incident-*` only); the watchdog pages on an overdue report. Notification is publish-only: nothing is sent to FedRAMP or an agency. Exercises are records with `exercise: true`. - `.github/workflows/evidence-nightly.yml` — the unattended VDR refresh, **twice a day**, plus once after every successful deploy to `main` (`workflow_run`, so a deploy that fixes a failing nightly also clears its beacon): re-scan (Syft + Grype against a fresh vulnerability DB), rebuild the VDR + trend, run the same vulnerability and reconciliation gates, republish six objects under `.well-known/vdr-*` (report, bundle, markdown, trend, trend bundle, provenance attestation), and on every run, pass or fail, write a status beacon (`.well-known/vdr-status.json`, outcomes only, unsigned). No `terraform apply`, no website sync. Its alerting is the `alert` job (a GitHub issue), not the deploy workflow's `notify`. - `infrastructure/watchdog.tf` + `infrastructure/watchdog/` — the **evidence SLA watchdog**: an hourly Lambda reads every artifact listed in the governed freshness config from the bucket (AWS APIs only, no internet egress), publishes the VDR's and runtime signal's ages, the nightly's result and a count of artifacts past their window as CloudWatch metrics, and four alarms email the operator via a CMK-encrypted SNS topic. This is the page; the GitHub issue is the paper trail. The email subscription is created out of band so no address enters Terraform state. Runbook: `docs/runbooks/evidence-sla-alarm.md`. diff --git a/data/frr-records.json b/data/frr-records.json index c7d069f9..79011eb3 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -658,72 +658,171 @@ }, { "frr_id": "IEC-CSO-AIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No automation exists for incident reporting; nothing exists to automate. To close: Once the incident register and report builder exist, run them from a workflow (workflow_dispatch + on push to the incident register) that validates, signs, publishes and sends IIR/OIR/FIR automatically, and pages through the existing watchdog/SNS when a report deadline is near or missed.", + "status": "Partially Implemented", + "implementation": ".github/workflows/incident-reports.yml runs on every push of data/incidents.json to main, by hand, twice a day and after each nightly VDR refresh: it validates the register, verifies the published VDR, builds every report against FedRAMP's schema, signs, redaction-gates and publishes under /.well-known/incident-* with its own least-privilege role (infrastructure/bootstrap/incident-reports.tf), and fails with a GitHub issue when a report is overdue; the evidence watchdog pages on the same deadlines hourly. A person records the facts in the register; nothing else is done by hand. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). Every deploy checks the publisher's prerequisites before it applies anything (scripts/check-incident-publisher.py: the role variable names the bootstrap role and the incident-reports environment deploys only from main) and, after the deploy job, runs this workflow on its own role (deploy-with-opa.yml job incident-publisher), so the deploy fails if the publisher cannot publish.", + "evidence": [ + { + "kind": "step", + "ref": "incident-reports.yml#Build incident reports (IIR, OIR, FIR)" + }, + { + "kind": "step", + "ref": "incident-reports.yml#Incident report clocks (fail when a report is due and missing)" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Incident report publisher preflight" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_deploy_proves_the_publisher_by_calling_it_after_the_deploy" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_air_workflow_validates_builds_signs_publishes_and_checks_the_clock_in_order" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Everything up to publication is automated; what is left is the last step of the rule, reaching all affected parties. Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). A person still records the incident's facts in the register, which the rule allows (it asks to minimize human intervention, not remove it). To close: the operator's delivery decision (IEC-CSO-IIR); the delivery is then built into this workflow.", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-DPR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "Nothing assigns a PAIN rating to an incident, so there is no default-to-N5 behaviour and no record of whether a prompt estimate replaced it. The VDR PAIN classifier (scripts/build-vdr-report.py:1730 assign_pain) rates vulnerabilities, not incidents. To close: In the incident register, set pain=5 with basis 'default (IEC-CSO-DPR)' when a record becomes reportable, and allow it to drop only through an EFI estimate record (rating, reason, estimated_at). Drive the IIR/OIR/FIR clocks from the effective rating. Test both paths and show them in the simulated-incident log.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A reportable incident is rated at the default the IEC-CSO-DPR text states (N5, read from the rule) until an IEC-CSO-EFI estimate record exists, and the report clocks use the rating in force at each start time. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_shows_the_default_rating_then_the_estimate" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-EFI", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No Incident Rating step: nothing estimates likely adverse impact on agency customers for an incident or assigns N1-N5 using the minimal/narrow/disruptive/debilitating x 1 or >1 agency scale. The required artifact (an incident log showing the evaluation and its reason) does not exist. To close: Add an EFI record type to the incident register: rating N1-N5, the customer-effect word, single or multiple agencies, reason, estimated_at. Document the rubric in docs/incident-response.md (it can reuse the VDR effect words from infrastructure/schemas/vdr-pain-config.json). Exercise it in the simulated incidents.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). An estimate record carries rating, customer effect (minimal/narrow/disruptive/debilitating), one or several agencies, reason and time; the loader refuses a rating that is not the one the IEC-CSO-EFI bullets give for that effect and agency count (the rubric is parsed from the rule text). Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_each_known_bad_register_fails_closed_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_rating_scale_and_default_come_from_the_rules" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_shows_the_default_rating_then_the_estimate" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-EFR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. docs/policies/ir-policy.md:15 only restates the trigger.", - "evidence": [], - "gap": "No step that evaluates each incident for effect (actual or likely) on confidentiality/integrity of federal customer data, no recorded determination with its reason, and no incident log. The required artifact (an incident log showing one or more real or simulated incidents evaluated, with the reason for the determination) does not exist. The runbook explicitly scopes federal-data incidents out, so it can't make the determination the rule asks for. To close: Add an incident register (e.g. data/incidents.json + schema) whose records carry detected_at, evaluated_at, reportable (bool), reason, and the federal-customer-data types considered. Add an 'Evaluate FedRAMP reportability' step to docs/incident-response.md triage (before Contain), define the data types that would be federal customer data for this offering, and fail a check if any incident record lacks an evaluation. Exercise it with at least two simulated incidents (one reportable, one not) and publish the log.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Every incident record must carry an evaluation (evaluated_at, reportable true/false, basis, reason, the federal customer data considered); a record without one does not load. docs/incident-response.md triage now evaluates reportability before containment. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. The published incident log is the artifact the rule asks for.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_each_known_bad_register_fails_closed_for_its_reason" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_logs_a_not_reportable_evaluation_with_its_reason" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { "frr_id": "IEC-CSO-FIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. A schema test fixture (tests/fixtures/cr26/good/incident.json, reportType Final, CVE-2099-0142) checks the validator only; it is not an incident.", - "evidence": [], - "gap": "No Final Incident Report generation on resolution/recovery, no final updates to all previously reported items, no clock (Class C: within 6 hours for N3-N5, 1 business day for N1-N2, after recovery), no delivery. No sample FIR. To close: Add reportType=Final generation when the incident record gets resolved_at and recovery_complete_at, with final values for every earlier IIR/OIR field. Alarm on the FIR deadline. Close the simulated incident with a FIR and link it from the incident log and the Ongoing Certification Report.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). A Final report is allowed only after resolved_at and recovery_complete_at, restates final values for every earlier item, carries resolvedAt, and is due an FIR period after recovery (6 hours at N3-N5, 1 business day at N1-N2); overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_the_final_report_is_due_after_recovery_and_ongoing_reports_stop" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_and_final_reports_restate_every_earlier_item" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-IIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A. The vendored schema infrastructure/schemas/fedramp-2026-06-24/fedramp-incident-report-schema-2026-06-24.json (reportType Initial/Ongoing/Final, federalIncidentCoordinator, timeline, potentialImpact, functionalImpact, recoveryPlan, affectedAgencies) and its validator are in place, but nothing produces a report.", - "evidence": [], - "gap": "No Initial Incident Report generator, no delivery to all affected parties (FedRAMP + affected agencies), and no clock (Class C: within 1 hour for N3-N5, 24 hours for N2, 1 business day for N1). None of the 8 items exists in any record: federal incident response coordinator contact, tracking ID, description, timeline (start, detection time/source, evaluation time, milestones), historical/current PAIN with EFI explanation, functional impact incl. C/I and federal data types, recovery plan/milestones, likely affected agencies. No sample IIR exists, real or simulated. To close: Build scripts/build-incident-report.py that renders an IIR from the incident register into the vendored schema (validated before write) plus a human-readable version; name the federal incident response coordinator contact; add a delivery step (e.g. signed publication to a restricted location plus email to a configured recipient list holding FedRAMP's incident address and each agency's contact) that starts on 'reportable' and is alarmed against the PAIN-based deadline (watchdog). Run a timed simulated incident end to end and keep the IIR.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). The Initial report carries all eight items (coordinator, tracking ID, description, timeline with start/detection/evaluation/milestones, historical and current rating with the EFI explanation, functional impact, recovery plan, likely affected agencies). Its clock (1 hour at N3-N5, 24 hours at N2, 1 business day at N1) runs from the evaluation; the incident-reports workflow fails and the evidence watchdog pages (IncidentReportsOverdue) once it passes. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_exercise_runs_initial_ongoing_final_all_on_time" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_every_report_validates_against_fedramps_schema_and_is_listed_with_its_hash" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator decides a delivery channel (e.g. SES from the system's domain to FedRAMP's incident address) and it is built behind that decision.", "closes_with": [ - "W6" + "sam" ] }, { "frr_id": "IEC-CSO-OIR", - "status": "Not Implemented", - "implementation": "No incident record, incident log, evaluation step or report generator exists in scripts/, policies/ or .github/workflows/ (grep for incident/IEC finds only build-ocr.py's static attestation text, scripts/_fedramp_schema.py:41 registering the vendored incident-report schema, and test fixtures tests/fixtures/cr26/{good,bad}/incident*.json). docs/incident-response.md 'Scope' lists federal-customer-data incidents as out of scope; docs/cr26-applicability.md records IEC as N/A.", - "evidence": [], - "gap": "No Ongoing Incident Report mechanism or cadence (Class C: every 6 hours for N3-N5, 24 hours for N2, 1 business day for N1), no 'updates or lack of updates' logic, and none of the additional items recorded: observed activity, IOCs, related CVE, root cause, response/recovery activities. No sample OIR. To close: Extend the incident report builder for reportType=Ongoing: diff against the previous report so every earlier item is restated (changed or 'no update'), add the 5 OIR fields to the incident record, and schedule/alarm the next OIR from the effective PAIN. Produce OIRs in the simulated exercise.", + "status": "Partially Implemented", + "implementation": "data/incidents.json (the incident register; shape infrastructure/schemas/incidents.schema.json) is read through scripts/_incidents.py, which fails closed. scripts/build-incident-report.py renders the Initial, Ongoing and Final reports in FedRAMP's 2026-06-24 incident report schema (validated before write) and the incident log, published signed as /.well-known/incident-reports.json by every deploy and by .github/workflows/incident-reports.yml on every change to the register. Class C report clocks and the Incident Rating scale are read from the pinned rules (scripts/_rules.py). Each Ongoing report restates every earlier item with its latest value and marks each 'updated' or 'no update', and adds observed activity, indicators of compromise, related CVEs, root cause and response/recovery activities. The next one is due an OIR period (6 hours at N3-N5, 24 at N2, 1 business day at N1) after the previous report until the incident is resolved; overdue fails the workflow and pages. Exercised once, 2026-11-05: INC-2026-001 (simulated, exercise: true) runs IIR, two OIRs and an FIR on a simulated timeline, all inside their clocks; INC-2026-002 (simulated) is evaluated not reportable with its reason. Delivery is publish-only: nothing is sent to FedRAMP or to any agency (the operator has not authorized sending; there is no FedRAMP certification and no agency customer). ", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_reports_are_due_every_oir_period_until_resolved" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_ongoing_and_final_reports_restate_every_earlier_item" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } + ], + "gap": "Reports are published under /.well-known/incident-* and not delivered: nothing sends them to FedRAMP or to an agency, by the operator's decision (notification: published-only in data/incidents.json; this system has no FedRAMP certification and no agency customer). To close: the operator's delivery decision, as for IEC-CSO-IIR.", "closes_with": [ - "W6" + "sam" ] }, { @@ -1552,12 +1651,25 @@ }, { "frr_id": "VER-TFR-IRI", - "status": "Not Implemented", - "implementation": "Checked: policies/triage.rego block_rule 'top-impact-lev-irv' (G2) blocks only N5+LEV+IRV, as a pipeline block; docs/policies/ir-policy.md:13 states the IRI rule in prose.", - "evidence": [], - "gap": "Nothing treats an internet-reachable likely exploitable vulnerability at N4 or N5 as a FedRAMP Reportable Incident: no incident record is opened, no IIR/OIR/FIR clocks start, and nothing ends that status when it's partially mitigated to N3 or below. N4 IRV+LEV isn't even flagged beyond its 4-day deadline. Depends on the missing IEC machinery. To close: In triage.rego add an 'incident' decision (IRV and LEV and PAIN > N3) and in the builder open/update an incident record in the incident register (see IEC-CSO-EFR) with default PAIN-5 treatment, closing it when a verified partial mitigation brings it to N3 or below. Test with a synthetic finding.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "policies/triage.rego (incident_triggers) names every VDR finding that is internet-reachable, likely exploitable and above the N-rating the VER-TFR-IRI Class C text states (read from the rule; a changed text fails closed), unless it is a false positive or fully mitigated; once partially mitigated to N3 or below it no longer triggers. scripts/build-incident-report.py publishes each trigger in the incident log and, while no unresolved incident in data/incidents.json names it, puts an Initial report due from the finding's first evaluation at the default N5 clock: the incident-reports workflow fails and the evidence watchdog pages when that passes. Opening the incident record is the operator's act; its reports then follow IEC-CSO-IIR/OIR/FIR. Reconciliation invariant (m) fails a build whose open incident names a finding the VDR does not carry. Adopted in data/incidents.json policy.adopted_vulnerability_rules.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_irv_lev_n4_finding_with_no_incident_is_due_an_initial_report" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_a_partially_mitigated_finding_at_n3_is_no_longer_an_incident" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_reconcile_m_fails_the_known_bad_register" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ] }, { @@ -1592,12 +1704,21 @@ }, { "frr_id": "VER-TFR-NRI", - "status": "Not Implemented", - "implementation": "Checked: docs/policies/ir-policy.md:13 adopts NRI in prose ('non-internet-reachable likely-exploitable vulnerabilities at PAIN N5 are reportable until N4 or below per VER-TFR-NRI'); no code implements it.", - "evidence": [], - "gap": "MAY rule: optional, but the published policy claims it's adopted and nothing implements it. NLEV-IRV N5 findings never open an incident. To close: Either implement alongside IRI (NIRV and LEV and PAIN = N5 -> incident until a partial mitigation brings it to N4) or remove the claim from ir-policy.md and record the decision not to use the MAY.", - "closes_with": [ - "W6" + "status": "Implemented", + "implementation": "Adopted (docs/policies/ir-policy.md; data/incidents.json policy.adopted_vulnerability_rules). policies/triage.rego names every likely exploitable, not internet-reachable VDR finding at the N-rating the VER-TFR-NRI Class C text states (N5), until partially mitigated to N4 or below; the incident log and clocks treat it exactly as VER-TFR-IRI does. An unadopted rule's triggers are still shown but start no clock.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_nirv_lev_n5_finding_opens_under_nri_and_n4_does_not" + }, + { + "kind": "test", + "ref": "tests/test_incidents.py::test_an_unadopted_rule_is_shown_but_starts_no_clock" + }, + { + "kind": "artifact", + "ref": ".well-known/incident-reports.json" + } ], "may_rationale": "Adopted, as the incident response policy states: treating a likely exploitable, non-internet-reachable N5 vulnerability as reportable is stricter than required and costs little at this scale." } diff --git a/data/incidents.json b/data/incidents.json new file mode 100644 index 00000000..f00b35da --- /dev/null +++ b/data/incidents.json @@ -0,0 +1,109 @@ +{ + "$comment": "The incident register (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR). Every incident is recorded here once, with its FedRAMP reportability evaluation and reason; a reportable one carries its Incident Rating estimates and the Initial, Ongoing and Final reports issued, each with when it was issued and what it set. scripts/_incidents.py validates it (fail-closed) and scripts/build-incident-report.py renders the reports and the incident log; .github/workflows/incident-reports.yml publishes them on every change to this file. The report clocks are FedRAMP's Class C timeframes, read from the pinned rules, never set here. Everything in this file is published. Exercises are marked exercise: true. Shape: infrastructure/schemas/incidents.schema.json.", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Sam Aydlette, System Owner and incident response lead; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only. Each report is signed and published under https://samaydlette.com/.well-known/ (incident-reports.json lists every report and its sha256). Nothing is sent to FedRAMP or to any agency: the operator has not authorized sending, and this system has no FedRAMP certification and no agency customers.", + "adopted_vulnerability_rules": ["VER-TFR-IRI", "VER-TFR-NRI"], + "federal_customer_data": "None. This system holds no federal customer data (FRD-FCD) and has no agency customers. Were an agency to use the Silk Reeling application, what its users supply to it (pose landmarks) would be the federal customer data to consider; the operator's public site content, account information and the published evidence are not.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-001", + "title": "Exercise: internet-reachable likely exploitable N5 vulnerability in the Silk Reeling API", + "exercise": true, + "started_at": "2026-11-05T02:40:00Z", + "detected_at": "2026-11-05T03:00:00Z", + "detection_source": "Exercise inject: a simulated VDR finding that policies/triage.rego flags under VER-TFR-IRI", + "evaluation": { + "evaluated_at": "2026-11-05T03:10:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Simulated timeline. An internet-reachable, likely exploitable vulnerability rated N5 in a dependency of the Silk Reeling API. The operator treats such a vulnerability as a FedRAMP Reportable Incident (VER-TFR-IRI) until it is partially mitigated to N3 or below. The scenario assumes one agency whose users supply data to the application.", + "federal_customer_data_considered": "Scenario assumption: pose landmarks supplied by one agency's users of the Silk Reeling application. In reality the system holds no federal customer data." + }, + "findings": ["CVE-2099-0001"], + "estimates": [ + { + "estimated_at": "2026-11-05T04:30:00Z", + "rating": 3, + "customer_effect": "disruptive", + "agencies": "single", + "reason": "Exploitation could expose the landmark data of many of the assumed agency's users without interrupting the service for long; no other agency is assumed." + } + ], + "reports": [ + { + "type": "Initial", + "at": "2026-11-05T03:40:00Z", + "set": { + "description": "A request-parsing dependency of the Silk Reeling API has a vulnerability (simulated CVE-2099-0001) that an unauthenticated client could exploit over the internet to read other users' submitted data.", + "functional_impact": "Potential loss of confidentiality of pose landmarks submitted by the assumed agency's users; no integrity or availability effect is expected.", + "recovery_plan": "Throttle the affected endpoint now; upgrade the dependency to the fixed release and redeploy through the reviewed pipeline. Targets: partial mitigation within 3 hours, remediation within 1 day.", + "affected_agencies": ["Hypothetical agency A (exercise assumption)"], + "related_cves": ["CVE-2099-0001"], + "milestones": [ + {"at": "2026-11-05T03:00:00Z", "description": "Triage flagged the finding under VER-TFR-IRI (simulated)"} + ] + } + }, + { + "type": "Ongoing", + "at": "2026-11-05T09:20:00Z", + "set": { + "observed_activity": "No exploitation attempts in the API Gateway access logs since the vulnerable release was deployed (simulated review).", + "indicators_of_compromise": ["None observed (simulated)"], + "root_cause": "A vulnerable release of a request-parsing dependency (simulated CVE-2099-0001).", + "response_and_recovery_activities": "Endpoint throttled at 04:15 (simulated), a partial mitigation; Incident Rating estimated at N3; fixed release identified.", + "milestones": [ + {"at": "2026-11-05T04:15:00Z", "description": "Partial mitigation: affected endpoint throttled (simulated)"} + ] + } + }, + { + "type": "Ongoing", + "at": "2026-11-05T15:00:00Z", + "set": { + "response_and_recovery_activities": "Fixed release built and passing the pipeline's gates; deploy awaiting approval (simulated)." + } + }, + { + "type": "Final", + "at": "2026-11-05T17:45:00Z", + "set": { + "response_and_recovery_activities": "Fixed release deployed at 16:30 and the finding no longer appears in the VDR (simulated); recovery verified at 17:00.", + "recovery_plan": "Complete.", + "milestones": [ + {"at": "2026-11-05T16:30:00Z", "description": "Fixed release deployed (simulated)"} + ] + } + } + ], + "resolved_at": "2026-11-05T16:30:00Z", + "recovery_complete_at": "2026-11-05T17:00:00Z" + }, + { + "id": "INC-2026-002", + "title": "Exercise: unauthorized change to a page of the public site", + "exercise": true, + "started_at": "2026-11-05T10:00:00Z", + "detected_at": "2026-11-05T10:20:00Z", + "detection_source": "Exercise inject: simulated drift of a website HTML artifact between the deploy-time and runtime KSI signals", + "evaluation": { + "evaluated_at": "2026-11-05T10:35:00Z", + "reportable": false, + "basis": "IEC-CSO-EFR", + "reason": "Simulated timeline. The changed content is the operator's public site content, which is not federal customer data (FRD-FCD), and the change is not likely to affect the confidentiality or integrity of any federal customer data. Not a FedRAMP Reportable Incident; handled under the incident response runbook without FedRAMP reports.", + "federal_customer_data_considered": "None present: public website content only." + }, + "estimates": [], + "reports": [], + "resolved_at": "2026-11-05T11:30:00Z", + "recovery_complete_at": "2026-11-05T11:45:00Z" + } + ] +} diff --git a/docs/boundary/boundary-classification.json b/docs/boundary/boundary-classification.json index 69d1e17c..48d2e591 100644 --- a/docs/boundary/boundary-classification.json +++ b/docs/boundary/boundary-classification.json @@ -20,7 +20,7 @@ {"key": "audit", "zone": "system", "label": "Audit and shared keys", "match": ["aws::audit_log_trail::*", "aws::object_store::cloudtrail", "aws::kms_key::at_rest"]}, {"key": "trust-root", "zone": "system", "label": "CI/CD trust root (operator-applied bootstrap stack)", - "match": ["aws::oidc_provider::*", "aws::iam_role::deploy", "aws::iam_role::evidence_nightly", "aws::iam_role::plan", "aws::iam_group::*", "aws::iam_policy::*", "aws::object_store::tfstate", "aws::kv_table::*"]}, + "match": ["aws::oidc_provider::*", "aws::iam_role::deploy", "aws::iam_role::evidence_nightly", "aws::iam_role::incident_reports", "aws::iam_role::plan", "aws::iam_group::*", "aws::iam_policy::*", "aws::object_store::tfstate", "aws::kv_table::*"]}, {"key": "github", "zone": "external", "label": "GitHub repository, Actions and OIDC", "match": ["ext::github-repo", "ext::github-oidc"]}, {"key": "sigstore", "zone": "external", "label": "Sigstore (Fulcio CA and Rekor log)", @@ -69,6 +69,8 @@ {"id": "J", "label": "Evidence Nightly → S3 (.well-known/vdr-*)", "path": [{"component": "ext::github-oidc"}, {"component": "aws::iam_role::evidence_nightly"}, {"component": "aws::object_store::website"}], "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "GitHub OIDC → STS; the role can write only .well-known/vdr-* (unattended)", "encryption": "In transit TLS; at rest SSE-S3", "data": "Refreshed VDR and trend (Sigstore-signed)"}, {"id": "K", "label": "Watchdog → S3 (evidence freshness read)", "path": [{"component": "aws::event_schedule::evidence_watchdog"}, {"component": "aws::function::evidence_watchdog"}, {"component": "aws::object_store::website"}], - "protocol": "AWS-internal", "auth": "Watchdog Lambda role: s3:GetObject on the published evidence keys only", "encryption": "In transit: TLS", "data": "Published evidence timestamps; results go out as CloudWatch metrics that drive flow I's alarms"} + "protocol": "AWS-internal", "auth": "Watchdog Lambda role: s3:GetObject on the published evidence keys only", "encryption": "In transit: TLS", "data": "Published evidence timestamps; results go out as CloudWatch metrics that drive flow I's alarms"}, + {"id": "L", "label": "Incident Reports → S3 (.well-known/incident-*)", "path": [{"component": "ext::github-oidc"}, {"component": "aws::iam_role::incident_reports"}, {"component": "aws::object_store::website"}], + "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "GitHub OIDC → STS; the role can write only .well-known/incident-* (unattended)", "encryption": "In transit TLS; at rest SSE-S3", "data": "Incident log and IIR/OIR/FIR reports (Sigstore-signed)"} ] } diff --git a/docs/cr26-applicability.md b/docs/cr26-applicability.md index 0d20e28d..642739e1 100644 --- a/docs/cr26-applicability.md +++ b/docs/cr26-applicability.md @@ -25,6 +25,6 @@ The POA&M is retired (2026-11-04): CR26 has no POA&M. Open findings and their de - **IVV — Independent Verification and Validation.** `IVV-CSO-FIA` (Class C MUST) requires a persistent independent assessment by a **FedRAMP Recognized independent assessment service** (the artifact formerly called a 3PAO) or by FedRAMP. This system is self-attested and has engaged no such assessor, so the *independent* half cannot be met. The provider-side verification and validation an assessor would consume **are** produced (in the Security Decision Record); the independent half is unmet by design and recorded N/A. - **MKT — Marketplace Listing.** `MKT-IIP-AGU` requires demonstrating the offering is for agency use within 44 USC § 3506 scope, and the rule text is explicit that *"services used by private companies to meet other compliance requirements (such as CMMC) that do not also meet one of the above use cases are outside the scope of FedRAMP."* There is no agency use case and no intent to list, so MKT is N/A by statutory scope. - **AFC — Addressing FedRAMP Communication.** `AFC-CSO-INB` and the rest require maintaining a FedRAMP Security Inbox and handling FedRAMP correspondence. With no listing and no sponsor, FedRAMP has no reason to correspond, so there is no channel to maintain. AFC's grace period already ended **2026-07-01**; it is recorded N/A absent a sponsor. -- **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so no incident is FedRAMP-reportable and the `IEC-CSO-IIR` reporting clocks never start. The evaluation step still runs — the VDR aggregator assigns a PAIN rating to every finding — so the machinery is in place the moment federal data ever enters scope. +- **IEC — Incident Evaluation and Communication.** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so in practice no incident is FedRAMP-reportable. Every incident is still evaluated and recorded in `data/incidents.json`; reportable ones get Initial, Ongoing and Final reports in FedRAMP's schema, on the Class C clocks, published under `/.well-known/` (publish-only: nothing is sent). Exercised 2026-11-05 with simulated incidents marked as exercises; see `docs/incident-response.md`. These four are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. diff --git a/docs/incident-response.md b/docs/incident-response.md index 6a3f8f34..35eab85f 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -15,9 +15,10 @@ In-scope incidents: Out of scope: -- Any incident involving federal customer data, end-user accounts, or downstream agencies — this system has none of those - Service-level incidents around availability promises to anyone, since none exist +Federal customer data, end-user accounts and downstream agencies: this system has none, so no incident here is expected to be a FedRAMP Reportable Incident. Every incident is still evaluated for it (step 2 below) and the determination is recorded, because the evaluation is what the rules ask for, and because a wrong assumption would otherwise go unrecorded. + ## Detection Active detection sources: @@ -32,14 +33,30 @@ Active detection sources: ## Triage and response procedures 1. **Confirm.** Compare the runtime KSI signal at `/.well-known/ksi-signal-runtime.json` against the deploy-time signal. Any unexplained `result: "fail"` validation, or any component drift, is high-confidence signal of a real change. -2. **Contain.** +2. **Record and evaluate FedRAMP reportability (IEC-CSO-EFR).** Add the incident to [`data/incidents.json`](../data/incidents.json) with `detected_at`, `detection_source` and an `evaluation`: when it was evaluated, `reportable` true or false, the `basis` (`IEC-CSO-EFR`, or `VER-TFR-IRI` / `VER-TFR-NRI` for a vulnerability), the `reason`, and the federal customer data considered. Does it affect, or is it likely to affect, the confidentiality or integrity of federal customer data (data an agency or its users supply to the service, not account information or telemetry)? If yes it is a FedRAMP Reportable Incident: continue with [Reporting](#reporting-fedramp-reportable-incidents-iec) in parallel with containment. Push the record; the incident log republishes within minutes. +3. **Contain.** - **Credential compromise (AWS):** rotate the IAM access keys via the IAM console; revoke any active sessions; rotate the GitHub Actions secret holding the credentials. - **Credential compromise (GitHub):** revoke any compromised PATs; rotate the workflow's `GITHUB_TOKEN` is automatic per-run; reset OAuth grants if external apps are involved. - **Content compromise:** revert via `git`, push to `main`, and approve the `prod` deploy. S3 versioning preserves the prior state; CloudFront invalidation refreshes the edge. - **Supply-chain compromise:** pin the offending dependency to a known-good version, redeploy, and file a Dependabot suppression if the alert source is the GitHub Advisory Database. -3. **Eradicate.** Identify the root cause (credential, code, or config) and patch it. Confirm the patch holds via a fresh approved deploy. -4. **Recover.** Verify the runtime signal returns to clean. Verify `cosign verify-blob` still passes against the new signal and bundle. Confirm the site is reachable end-to-end. -5. **Lessons learned.** Append an after-action entry to the section below. +4. **Eradicate.** Identify the root cause (credential, code, or config) and patch it. Confirm the patch holds via a fresh approved deploy. +5. **Recover.** Verify the runtime signal returns to clean. Verify `cosign verify-blob` still passes against the new signal and bundle. Confirm the site is reachable end-to-end. +6. **Lessons learned.** Append an after-action entry to the section below. + +## Reporting FedRAMP Reportable Incidents (IEC) + +_AI-drafted (2026-11-05) to describe what is now built; for the operator's review._ + +Reporting is automated from the incident register. A person records facts; the pipeline renders, validates, signs, publishes and keeps the clocks. + +- **Register.** [`data/incidents.json`](../data/incidents.json), read through `scripts/_incidents.py` (fails closed; shape in `infrastructure/schemas/incidents.schema.json`). Each report is an entry in the incident's `reports` list (`Initial`, then `Ongoing`, then `Final`) with the time it is issued and the items it sets: description, functional impact, recovery plan, likely affected agencies, observed activity, indicators of compromise, related CVEs, root cause, response and recovery activities, milestones. A report restates everything set before it. +- **Rating.** Until an `estimates` entry exists, the incident is rated N5 (`IEC-CSO-DPR`). An estimate (`IEC-CSO-EFI`) records the customer effect (minimal, narrow, disruptive, debilitating), whether one agency or more than one is likely affected, the reason and the time; the register refuses a rating that is not the one the rules give for that combination (N1 minimal, N2 narrow, N3 disruptive on one agency, N4 debilitating on one or disruptive on several, N5 debilitating on several). +- **Clocks.** Read from FedRAMP's Class C rules: the Initial report is due from the evaluation, each Ongoing report from the previous report until the incident is resolved, and the Final report from `recovery_complete_at` (hours at N3-N5; 24 hours or one business day at N1-N2; business days skip weekends, and holidays are counted, which can only make a deadline earlier). The rating in force when each clock starts sets its length. +- **Build and publish.** `scripts/build-incident-report.py` writes each report in FedRAMP's incident report schema (`incident---.json`, validated before it is written) and the incident log (`incident-reports.json` and `.md`: every incident, its evaluation and reason, its rating history, each report with its sha256 and what changed, and each clock). `.github/workflows/incident-reports.yml` runs it on every push of the register to `main`, by hand, twice a day and after each nightly VDR refresh; it signs, redaction-gates and publishes under `/.well-known/incident-*` with a role that can write nothing else. Every deploy republishes the same set. +- **Alarms.** The workflow's last step fails, and raises a GitHub issue, when a report is past its deadline. The evidence SLA watchdog reads the published log hourly and pages by email (`incident-report-overdue`, [`runbooks/evidence-sla-alarm.md`](runbooks/evidence-sla-alarm.md)). +- **Vulnerabilities as incidents.** The operator adopts `VER-TFR-IRI` and `VER-TFR-NRI` (`policy.adopted_vulnerability_rules`). The VDR triage policy names each finding they cover; until an unresolved incident in the register lists it under `findings`, its Initial report is due from the finding's first evaluation at N5, so the alarms fire. Open the incident with basis `VER-TFR-IRI` or `VER-TFR-NRI` and the finding's tracking ID or CVE. Reconciliation invariant (m) fails a build whose open incident names a finding the VDR no longer carries: close it with a Final report. +- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency; the operator has not authorized sending, and the system has no certification and no agency customers. Every report says so. FedRAMP and the affected agencies are "all affected parties" under the rules; reaching them is a decision for the operator. +- **Exercises.** A simulated incident is recorded with `exercise: true` and is published marked as one. Exercised 2026-11-05: `INC-2026-001` (a simulated internet-reachable N5 vulnerability: Initial, two Ongoing and a Final report on a simulated timeline, all on time; rated N5 by default, then estimated N3) and `INC-2026-002` (a simulated page change, evaluated not reportable with its reason). `tests/test_incidents.py` runs the same exercise through the builder on every `make check`. ## After-action reports (KSI-INR-AAR) @@ -117,5 +134,5 @@ Single-tier. Author → author. External escalations: - **GitHub Support** — if the issue is GitHub-side (account, repo, workflow infrastructure) - The mailbox in `security.txt` for acknowledging external reporters -There is no actual FedRAMP authorization in scope, so the FedRAMP Security Inbox (FSI) and Incident Communications Procedures (ICP) do not apply. +There is no actual FedRAMP certification in scope, so the FedRAMP Security Inbox (FSI) does not apply. Incident reports under the FedRAMP Incident Evaluation and Communication rules are generated and published as described above; they are not sent. diff --git a/docs/policies/ir-policy.md b/docs/policies/ir-policy.md index 81be6cb0..03c4e0db 100644 --- a/docs/policies/ir-policy.md +++ b/docs/policies/ir-policy.md @@ -1,15 +1,24 @@ # IR — Incident Response -Incident response procedures are documented in [`incident-response.md`](../incident-response.md), which satisfies KSI-INR-RIR through KSI-INR-AAR and the IR-9 family (information spillage). The runbook covers detection sources, triage, containment, eradication, recovery, and after-action reporting. The IR lead is the operator; escalation is single-tier. +Incident response procedures are documented in [`incident-response.md`](../incident-response.md), which satisfies KSI-INR-RIR through KSI-INR-AAR and the IR-9 family (information spillage). The runbook covers detection sources, triage (including the FedRAMP reportability evaluation), containment, eradication, recovery, FedRAMP incident reporting, and after-action reporting. The IR lead is the operator; escalation is single-tier. External communication paths: - **Public reporter:** [`/.well-known/security.txt`](../../website/.well-known/security.txt) is the published vulnerability-reporting mailbox. -- **Incident Communications Procedures (ICP, 20x):** the ICP rules apply at the procedure-documented level even though the system has no actual FedRAMP-customer reporting obligation. The runbook describes what would be communicated and to whom for a real FedRAMP-certified service. +- **FedRAMP incident reports (IEC):** every incident is recorded in the incident register, [`data/incidents.json`](../../data/incidents.json), with its reportability evaluation. Initial, Ongoing and Final Incident Reports for a FedRAMP Reportable Incident are generated from it, validated against FedRAMP's incident report schema, signed, and published under `/.well-known/` (the incident log is `/.well-known/incident-reports.json`) by an unattended workflow on every change to the register. +- **Notification is publish-only.** Nothing is sent to FedRAMP or to any agency. The operator has not authorized sending, and the system has no FedRAMP certification and no agency customers. Choosing a delivery channel is an operator decision; until it is made, publication is the only channel and every report says so. - **FedRAMP Security Inbox (FSI, 20x):** the system is not FedRAMP-certified; no actual FSI obligation applies. Notification path is documented in the runbook for reference. -**20x rule integration.** KSI-INR (Incident Response), ICP (Incident Communications Procedures), FSI (FedRAMP Security Inbox). +**20x rule integration.** KSI-INR (Incident Response), IEC (Incident Evaluation and Communication), FSI (FedRAMP Security Inbox). -**Review cadence.** Annually with the [security review](../security-review.md); after every actual incident (currently zero). VDR thresholds (Class C) treat internet-reachable likely-exploitable vulnerabilities above PAIN N3 (i.e. N4 or N5) as FedRAMP Reportable Incidents per `VER-TFR-IRI`, until they are partially mitigated to N3 or below; non-internet-reachable likely-exploitable vulnerabilities at PAIN N5 are reportable until N4 or below per `VER-TFR-NRI`. +**Reportability (IEC-CSO-EFR).** Every incident is evaluated, promptly and before containment, for whether it affects or is likely to affect the confidentiality or integrity of **federal customer data**; such an incident is a FedRAMP Reportable Incident. The determination, its reason and the federal customer data considered are recorded in the register and published in the incident log. This system holds no federal customer data, so in practice the evaluation is "not reportable"; the machinery runs either way, and it was exercised on 2026-11-05 with one simulated reportable incident and one simulated non-reportable one, both marked as exercises. -**Reportability trigger (IEC).** A FedRAMP Reportable Incident under `IEC-CSO-EFR` is triggered by an effect on the confidentiality or integrity of **federal customer data**. This system holds none, so no finding here is FedRAMP-reportable in practice and the `IEC-CSO-IIR` reporting clocks (Class C: 1 hour for PAIN 3/4/5) never start. The evaluation step still runs — the VDR aggregator assigns the PAIN rating to every finding — so the machinery is in place the moment federal data ever enters scope. +**Rating (IEC-CSO-DPR, IEC-CSO-EFI).** A reportable incident is rated at the default the rules set (N5) until the operator records an Incident Rating estimate: a likely minimal, narrow, disruptive or debilitating customer effect on one or more than one agency, with a reason. The register refuses an estimate whose rating is not the one the rules give for that effect. + +**Report clocks.** The Initial, Ongoing and Final report deadlines are FedRAMP's Class C timeframes, read from the pinned rules and never restated. An overdue report fails the incident reports workflow (raising a GitHub issue) and pages the operator through the evidence SLA watchdog. + +**Vulnerabilities as incidents (VER-TFR-IRI, VER-TFR-NRI).** The operator adopts both rules. An internet-reachable likely exploitable vulnerability above PAIN N3 (i.e. N4 or N5) is a FedRAMP Reportable Incident until it is partially mitigated to N3 or below (`VER-TFR-IRI`), and a non-internet-reachable likely exploitable vulnerability at PAIN N5 is one until it is N4 or below (`VER-TFR-NRI`, a MAY the operator has chosen to use). The VDR triage policy names each such finding; the incident log shows it, and until an incident in the register names it, its Initial report is due and the alarms above apply. + +**Review cadence.** Annually with the [security review](../security-review.md); after every actual incident (currently zero; the two recorded incidents are exercises). + +_AI-drafted (2026-11-05) to describe what the incident register, report builder and workflow now do; for the operator's review._ diff --git a/docs/runbooks/evidence-sla-alarm.md b/docs/runbooks/evidence-sla-alarm.md index 4057bb84..79f3f7c5 100644 --- a/docs/runbooks/evidence-sla-alarm.md +++ b/docs/runbooks/evidence-sla-alarm.md @@ -7,11 +7,12 @@ The evidence SLA watchdog (`infrastructure/watchdog.tf`) emails the operator thr | `nightly-failed` | the evidence nightly's last run failed, or no run has reported in 26h | a gate failed; or the cron is disabled or stuck | | `vdr-age` | the published VDR is more than 24h old | the reporting policy is breached; nightly runs have failed or stopped | | `runtime-age` | the runtime signal is more than 26h old | the daily runtime-check Lambda has failed or stopped | +| `incident-report-overdue` | an incident report listed as due in `/.well-known/incident-reports.json` is past its Class C deadline, or the incident log is missing or unreadable | an Initial, Ongoing or Final incident report was not issued in time; or a vulnerability that is a FedRAMP Reportable Incident (VER-TFR-IRI/NRI) has no incident opened | | `artifact-stale` | any artifact listed in `infrastructure/schemas/freshness-config.json` is past its window, missing, or has no readable timestamp | no deploy within the deploy-cadence window; the corroboration was not re-run; or one of the above | The windows are governed values in `infrastructure/schemas/freshness-config.json`; the thresholds above are read from it. Change a window there, through review, never in the alarm. -Any alarm also fires if the watchdog stops publishing metrics, because missing data counts as a breach. If all four fire together, check the watchdog itself first (a missing or invalid freshness config stops it before it publishes anything). +Any alarm also fires if the watchdog stops publishing metrics, because missing data counts as a breach. If all five fire together, check the watchdog itself first (a missing or invalid freshness config stops it before it publishes anything). ## `nightly-failed` @@ -30,6 +31,10 @@ The policy is already breached, so treat this as the priority. It usually follow Check the compliance Lambda (`samaydlette-com-opa-compliance`): its CloudWatch logs, its EventBridge rule, and the shared dead-letter queue `samaydlette-com-opa-compliance-dlq` for failed invocations. +## `incident-report-overdue` + +The published incident log (`/.well-known/incident-reports.json`, `obligations_due`) names each report still due, for which incident or finding, and its deadline. Follow [`docs/incident-response.md`](../incident-response.md#reporting-fedramp-reportable-incidents-iec): record the report (or, for a finding with no incident, open the incident) in `data/incidents.json` and push it; the **Incident Reports** workflow validates, builds, signs and publishes within minutes, and the alarm clears once the republished log no longer lists the report as due. If the log itself is missing or unreadable, run the workflow by hand and check its publish step. + ## `artifact-stale` The watchdog's log line for the run lists the stale artifacts under `stale`. To see the same from outside, run `python3 scripts/check-evidence-freshness.py --all https://samaydlette.com`. @@ -38,7 +43,7 @@ The watchdog's log line for the run lists the stale artifacts under `stale`. To - **`boundary-corroboration.json`:** re-run `tools/boundary-map/corroborate.py`, commit the result, and deploy. - **Nightly artifacts** (`vdr-*`): follow `nightly-failed` / `vdr-age` above. -## All four at once +## All five at once Check the watchdog: its log group `/aws/lambda/samaydlette-com-evidence-watchdog`, the dead-letter queue, and its EventBridge rule. Each run logs one JSON line with the values it published, the config version, and the stale artifacts. diff --git a/infrastructure/bootstrap/incident-reports.tf b/infrastructure/bootstrap/incident-reports.tf new file mode 100644 index 00000000..d38fb120 --- /dev/null +++ b/infrastructure/bootstrap/incident-reports.tf @@ -0,0 +1,97 @@ +# ============================================================================= +# BOOTSTRAP: GitHub OIDC role for unattended incident reporting (IEC-CSO-AIR) +# ============================================================================= +# Operator-applied (not CI), like everything else in this stack. +# +# WHY A ROLE OF ITS OWN. FedRAMP's Class C incident report clocks are hours (an +# Initial Incident Report within one hour for N3-N5, an Ongoing report every +# six). The deploy role sits behind the `prod` reviewer and cannot keep them, +# and the evidence nightly's role is scoped to `.well-known/vdr-*` on purpose: +# widening it to carry incident reports would make the VDR refresh's grant +# about something else. `.github/workflows/incident-reports.yml` runs in its +# own GitHub Environment with no required reviewer and assumes this role. +# +# THE WHOLE PERMISSION SET: PutObject under `.well-known/incident-*` and a CDN +# invalidation. No delete (an unattended job never unpublishes evidence), no +# read of any kind (the workflow verifies its publish through the public URL), +# no Terraform state, no website sync. The bucket default-encrypts with SSE-S3, +# so no KMS grant is involved. If a future change needs more, re-examine +# whether that work belongs on the unattended path before widening this. +# ============================================================================= + +variable "incident_reports_environment" { + type = string + description = "GitHub Environment the incident reports workflow runs in. No required reviewer; the role it grants is scoped to .well-known/incident-*." + default = "incident-reports" +} + +# TRUST: this repository, this GitHub Environment, nothing else. A pull request +# cannot assume it, and neither can a workflow that does not declare the +# environment. +data "aws_iam_policy_document" "incident_reports_trust" { + statement { + effect = "Allow" + actions = ["sts:AssumeRoleWithWebIdentity"] + + principals { + type = "Federated" + identifiers = [aws_iam_openid_connect_provider.github.arn] + } + + condition { + test = "StringEquals" + variable = "token.actions.githubusercontent.com:aud" + values = ["sts.amazonaws.com"] + } + + condition { + test = "StringEquals" + variable = "token.actions.githubusercontent.com:sub" + values = ["repo:${var.github_repo}:environment:${var.incident_reports_environment}"] + } + } +} + +resource "aws_iam_role" "incident_reports" { + name = "github-actions-incident-reports-oidc" + description = "Unattended incident reporting (IEC-CSO-AIR). PutObject under .well-known/incident-* and a CDN invalidation; nothing else." + assume_role_policy = data.aws_iam_policy_document.incident_reports_trust.json + max_session_duration = 3600 + + tags = merge(local.bootstrap_tags, local.bootstrap_cls.identity_secrets_internal, { Name = "github-actions-incident-reports-oidc" }) +} + +data "aws_iam_policy_document" "incident_reports_publish" { + statement { + sid = "PublishIncidentReportsOnly" + effect = "Allow" + actions = ["s3:PutObject"] + resources = ["arn:aws:s3:::${var.domain_name}/.well-known/incident-*"] + } +} + +resource "aws_iam_role_policy" "incident_reports_publish" { + name = "incident-reports-publish" + role = aws_iam_role.incident_reports.id + policy = data.aws_iam_policy_document.incident_reports_publish.json +} + +data "aws_iam_policy_document" "incident_reports_cdn" { + statement { + sid = "InvalidateIncidentPaths" + effect = "Allow" + actions = ["cloudfront:CreateInvalidation"] + resources = [aws_cloudfront_distribution.website.arn] + } +} + +resource "aws_iam_role_policy" "incident_reports_cdn" { + name = "incident-reports-cdn" + role = aws_iam_role.incident_reports.id + policy = data.aws_iam_policy_document.incident_reports_cdn.json +} + +output "incident_reports_role_arn" { + value = aws_iam_role.incident_reports.arn + description = "Set as the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN, which incident-reports.yml passes to configure-aws-credentials." +} diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index 7d02d3de..ebf2a5fc 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -86,6 +86,18 @@ "signed": false, "note": "The nightly's status beacon. Unsigned and not evidence; listed because the watchdog pages on its age. The nightly runs twice a day, so 26 hours means runs have been missed." }, + { + "path": ".well-known/incident-reports.json", + "cadence": "nightly", + "max_age_hours": 24, + "timestamp": { + "source": "json", + "field": "emitted_at" + }, + "signed": true, + "signature": ".well-known/incident-reports.bundle", + "note": "The incident log (IEC-CSO-EFR) and, through it, every incident report it lists with its sha256. Rebuilt by .github/workflows/incident-reports.yml on every change to data/incidents.json and twice a day, and by every deploy. The report deadlines themselves are hours, so the watchdog also pages on each listed report past its deadline (IncidentReportsOverdue)." + }, { "path": ".well-known/ksi-signal-runtime.json", "cadence": "runtime", diff --git a/infrastructure/schemas/gate-modes.json b/infrastructure/schemas/gate-modes.json index d1e87bc2..cb7d7bc6 100644 --- a/infrastructure/schemas/gate-modes.json +++ b/infrastructure/schemas/gate-modes.json @@ -50,6 +50,9 @@ "decided_by": "Sam Aydlette", "decided_on": "2026-11-04", "review_by": "2027-11-04"}, {"check": "reconcile.l", "gate": "G6", "mode": "block", "method_default": "block", "decided_by": "Sam Aydlette", "decided_on": "2026-11-04", "review_by": "2027-11-04"}, + {"check": "reconcile.m", "gate": "G5", "mode": "block", "method_default": "block", + "reason": "Proposed with the incident register (W6, AI-drafted): an open incident naming a finding the VDR does not carry blocks, like every other cross-artifact invariant. Confirm at review.", + "decided_by": "Operator (proposed; confirm at review)", "decided_on": "2026-11-05", "review_by": "2027-11-05"}, { "check": "reconcile.i.unreadable", "gate": "G7", diff --git a/infrastructure/schemas/incidents.schema.json b/infrastructure/schemas/incidents.schema.json new file mode 100644 index 00000000..d933d0d4 --- /dev/null +++ b/infrastructure/schemas/incidents.schema.json @@ -0,0 +1,107 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "incidents.schema.json", + "title": "Incident register", + "description": "data/incidents.json: every incident, its FedRAMP reportability evaluation (IEC-CSO-EFR), its Incident Rating estimates (IEC-CSO-EFI; until one exists the IEC-CSO-DPR default applies) and the Initial, Ongoing and Final reports issued (IEC-CSO-IIR/OIR/FIR). scripts/_incidents.py enforces these rules at build time without a jsonschema dependency, plus the ones a schema cannot state: IDs are unique; times are in order (started, detected, evaluated, each report); an estimate's rating is the IEC-CSO-EFI rating for its customer effect and agency count; the first report is Initial and sets the description, and a Final report is last and follows recovery; a vulnerability basis is an adopted rule and names a finding; nothing is dated after now; and no account ID or outside email address appears.", + "type": "object", + "required": ["schema", "policy", "incidents"], + "properties": { + "$comment": {"type": "string"}, + "schema": {"const": "incidents/1"}, + "policy": {"$ref": "#/$defs/policy"}, + "incidents": {"type": "array", "items": {"$ref": "#/$defs/incident"}} + }, + "additionalProperties": false, + "$defs": { + "text": {"type": "string", "minLength": 1, "pattern": "\\S"}, + "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, + "time": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"}, + "texts": {"type": "array", "items": {"$ref": "#/$defs/text"}, "uniqueItems": true}, + "policy": { + "type": "object", + "required": ["federal_incident_coordinator", "notification", "notification_text", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by"], + "properties": { + "federal_incident_coordinator": {"$ref": "#/$defs/text", "description": "Who coordinates federal incident response and how to reach them (IEC-CSO-IIR item 1)."}, + "notification": {"enum": ["published-only"], "description": "How reports reach all affected parties. Only publication under /.well-known/ is built; sending is the operator's decision."}, + "notification_text": {"$ref": "#/$defs/text"}, + "adopted_vulnerability_rules": {"type": "array", "items": {"enum": ["VER-TFR-IRI", "VER-TFR-NRI"]}, "uniqueItems": true, "description": "Which of VER-TFR-IRI (SHOULD) and VER-TFR-NRI (MAY) the operator applies."}, + "federal_customer_data": {"$ref": "#/$defs/text", "description": "What would be federal customer data (FRD-FCD) for this offering."}, + "decided_by": {"$ref": "#/$defs/text"}, + "decided_on": {"$ref": "#/$defs/date"}, + "review_by": {"$ref": "#/$defs/date"} + }, + "additionalProperties": false + }, + "incident": { + "type": "object", + "required": ["id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", "estimates", "reports"], + "properties": { + "id": {"type": "string", "pattern": "^INC-\\d{4}-\\d{3}$"}, + "title": {"$ref": "#/$defs/text"}, + "exercise": {"type": "boolean", "description": "true for a simulated incident run to exercise the process."}, + "started_at": {"$ref": "#/$defs/time"}, + "detected_at": {"$ref": "#/$defs/time"}, + "detection_source": {"$ref": "#/$defs/text"}, + "evaluation": { + "type": "object", + "required": ["evaluated_at", "reportable", "basis", "reason", "federal_customer_data_considered"], + "properties": { + "evaluated_at": {"$ref": "#/$defs/time"}, + "reportable": {"type": "boolean"}, + "basis": {"enum": ["IEC-CSO-EFR", "VER-TFR-IRI", "VER-TFR-NRI"]}, + "reason": {"$ref": "#/$defs/text"}, + "federal_customer_data_considered": {"$ref": "#/$defs/text"} + }, + "additionalProperties": false + }, + "findings": {"$ref": "#/$defs/texts", "description": "VDR tracking IDs or CVE IDs the incident is about."}, + "estimates": {"type": "array", "items": { + "type": "object", + "required": ["estimated_at", "rating", "customer_effect", "agencies", "reason"], + "properties": { + "estimated_at": {"$ref": "#/$defs/time"}, + "rating": {"type": "integer", "minimum": 1, "maximum": 5}, + "customer_effect": {"enum": ["minimal", "narrow", "disruptive", "debilitating"]}, + "agencies": {"enum": ["single", "multiple"]}, + "reason": {"$ref": "#/$defs/text"} + }, + "additionalProperties": false + }}, + "reports": {"type": "array", "items": { + "type": "object", + "required": ["type", "at"], + "properties": { + "type": {"enum": ["Initial", "Ongoing", "Final"]}, + "at": {"$ref": "#/$defs/time"}, + "set": { + "type": "object", + "minProperties": 1, + "properties": { + "description": {"$ref": "#/$defs/text"}, + "functional_impact": {"$ref": "#/$defs/text"}, + "recovery_plan": {"$ref": "#/$defs/text"}, + "observed_activity": {"$ref": "#/$defs/text"}, + "root_cause": {"$ref": "#/$defs/text"}, + "response_and_recovery_activities": {"$ref": "#/$defs/text"}, + "affected_agencies": {"$ref": "#/$defs/texts"}, + "indicators_of_compromise": {"$ref": "#/$defs/texts"}, + "related_cves": {"type": "array", "items": {"type": "string", "pattern": "^CVE-[0-9]{4}-[0-9]{4,}$"}, "uniqueItems": true}, + "milestones": {"type": "array", "items": { + "type": "object", "required": ["at", "description"], + "properties": {"at": {"$ref": "#/$defs/time"}, "description": {"$ref": "#/$defs/text"}}, + "additionalProperties": false + }} + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }}, + "resolved_at": {"$ref": "#/$defs/time"}, + "recovery_complete_at": {"$ref": "#/$defs/time"} + }, + "additionalProperties": false + } + } +} diff --git a/infrastructure/watchdog.tf b/infrastructure/watchdog.tf index 16f1777f..19764d91 100644 --- a/infrastructure/watchdog.tf +++ b/infrastructure/watchdog.tf @@ -14,7 +14,7 @@ # nightly's status beacon and every other signed output under # /.well-known/) straight from the site bucket # -> CloudWatch metrics (Samaydlette/Evidence) -# -> four alarms -> SNS topic (CMK-encrypted) -> operator email +# -> five alarms -> SNS topic (CMK-encrypted) -> operator email # # The freshness windows are governed values (REQ-PUB-2, REQ-GOV-1). They are # read here with jsondecode(file(...)): the alarm thresholds, the objects the @@ -30,7 +30,8 @@ # Terraform lands in state and in the uploaded plan artifact of a public repo. # It is created once, out of band (docs/runbooks/evidence-sla-alarm.md). # -# Cost: four standard alarms plus four custom metrics, roughly $1.60/month. +# Cost: five standard alarms plus five custom metrics, roughly $2.00/month (the +# fifth pair, for overdue incident reports, adds about $0.40). # Every listed artifact feeds one StaleArtifacts count rather than a metric # each, so the cost stays flat as the list grows. # SNS email at this volume and 720 short invocations a month are within free @@ -78,6 +79,14 @@ locals { threshold = 0 summary = "At least one published /.well-known/ artifact is older than its governed freshness window, or unreadable. The watchdog's log names which." } + # The Class C incident report clocks (IEC-CSO-IIR/OIR/FIR) are hours, not + # days, so this reads the deadlines the incident log lists rather than the + # log's age, and pages once one has passed without its report. + "incident-report-overdue" = { + metric = "IncidentReportsOverdue" + threshold = 0 + summary = "An incident report is past its FedRAMP Class C deadline and has not been issued, or the incident log is unreadable. /.well-known/incident-reports.json lists what is due; issue it by adding the report to data/incidents.json." + } } } diff --git a/infrastructure/watchdog/index.mjs b/infrastructure/watchdog/index.mjs index dd1b50af..e744b5b3 100644 --- a/infrastructure/watchdog/index.mjs +++ b/infrastructure/watchdog/index.mjs @@ -25,6 +25,9 @@ // missing, or is too old to trust; else 0 // StaleArtifacts how many listed artifacts are past their governed // window, unreadable, or without a usable timestamp +// IncidentReportsOverdue how many incident reports the published incident +// log lists as due whose Class C deadline has passed +// (1 if the log is missing or unreadable) // // A missing or invalid config fails the run before anything is published; the // alarms read the missing data as a breach and page. diff --git a/infrastructure/watchdog/logic.mjs b/infrastructure/watchdog/logic.mjs index 97692b70..8e896f03 100644 --- a/infrastructure/watchdog/logic.mjs +++ b/infrastructure/watchdog/logic.mjs @@ -13,10 +13,11 @@ export const KEYS = { vdr: '.well-known/vdr-report.json', runtime: '.well-known/ksi-signal-runtime.json', status: '.well-known/vdr-status.json', + incidents: '.well-known/incident-reports.json', }; // Every artifact a metric below depends on. The config must list them. -export const REQUIRED = [KEYS.vdr, KEYS.runtime, KEYS.status, '.well-known/boundary-corroboration.json']; +export const REQUIRED = [KEYS.vdr, KEYS.runtime, KEYS.status, KEYS.incidents, '.well-known/boundary-corroboration.json']; // Reported when an artifact cannot be read or has no usable timestamp. Far past // any threshold, so it reads as a breach on every alarm. @@ -98,6 +99,22 @@ export function nightlyFailed(status, maxBeaconAgeHours, now = Date.now()) { return status.result === 'success' ? 0 : 1; } +// How many incident reports are past their Class C deadline and not issued +// (IEC-CSO-IIR/OIR/FIR). The incident log lists each report still due with its +// deadline (scripts/build-incident-report.py, obligations_due); this counts the +// ones whose time has passed on AWS's clock, so a missed one-hour Initial +// report pages within the hour even if nothing republishes the log. A log that +// is missing, unreadable or has no list is a breach (1), never zero. +export function incidentReportsOverdue(log, now = Date.now()) { + if (!log || typeof log !== 'object' || !Array.isArray(log.obligations_due)) return 1; + let overdue = 0; + for (const d of log.obligations_due) { + const due = Date.parse(d && d.due_at); + if (Number.isNaN(due) || due < now) overdue += 1; + } + return overdue; +} + // Every listed artifact past its window, or unreadable, or without a usable // timestamp. One metric for all of them keeps the cost flat as the list grows; // the log line names which. @@ -123,12 +140,13 @@ export function computeMetrics(config, readings, now = Date.now()) { RuntimeSignalAgeHours: age(KEYS.runtime), NightlyFailed: nightlyFailed(parsedBody(readings[KEYS.status]), config.windows[KEYS.status], now), StaleArtifacts: stale.length, + IncidentReportsOverdue: incidentReportsOverdue(parsedBody(readings[KEYS.incidents]), now), }, stale, }; } -const COUNTS = new Set(['NightlyFailed', 'StaleArtifacts']); +const COUNTS = new Set(['NightlyFailed', 'StaleArtifacts', 'IncidentReportsOverdue']); export function metricData(metrics, now) { return Object.entries(metrics).map(([MetricName, Value]) => ({ diff --git a/policies/triage.rego b/policies/triage.rego index 8058d105..071839f0 100644 --- a/policies/triage.rego +++ b/policies/triage.rego @@ -444,3 +444,101 @@ decide(item) := { } decisions := [decide(item) | some item in input.items] + +# ============================================================================= +# VULNERABILITIES TREATED AS FEDRAMP REPORTABLE INCIDENTS (VER-TFR-IRI, -NRI) +# ============================================================================= +# Entry points, over the findings of a built VDR report (input.findings): +# data.vdr.triage.incident_triggers one entry per finding a rule makes a +# FedRAMP Reportable Incident +# data.vdr.triage.incident_errors non-empty => the caller fails closed +# +# The N-rating comparisons are read from the Class C rule text in data.rules, +# not restated here: "N-rating > 3 ... until ... at N3 or below" (IRI) and +# "N-rating = 5 ... until ... at N4 or below" (NRI). A rule stays in force for a +# finding until its current rating (after partial mitigation) is at or below +# the "until" level, which for both rules is the trigger level's complement. +# A false positive is not a vulnerability and a fully mitigated finding is not +# exploitable, so neither triggers. Whether the operator has adopted each rule +# (IRI is a SHOULD, NRI a MAY at Class C) is the incident register's policy, +# applied by scripts/build-incident-report.py. +ver_tfr := data.rules.FRR.VER.data.all.TFR + +class_c_statement(rid) := s if { + s := ver_tfr[rid].varies_by_class.c.statement +} else := ver_tfr[rid].statement + +rule_digit(pattern, rid) := to_number(m[0][1]) if { + m := regex.find_all_string_submatch_n(pattern, class_c_statement(rid), 1) + count(m) == 1 +} + +iri_above := rule_digit(`N-rating > ([0-9])`, "VER-TFR-IRI") + +iri_until := rule_digit(`at N([0-9]) or below`, "VER-TFR-IRI") + +nri_equals := rule_digit(`N-rating = ([0-9])`, "VER-TFR-NRI") + +nri_until := rule_digit(`at N([0-9]) or below`, "VER-TFR-NRI") + +incident_errors contains "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" if { + not iri_above +} + +incident_errors contains "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" if { + not iri_until +} + +incident_errors contains "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" if { + not nri_equals +} + +incident_errors contains "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" if { + not nri_until +} + +# The trigger and the exit must be complements; anything else is a changed rule +# that needs reading before it is trusted. +incident_errors contains "VER-TFR-IRI: the trigger and the 'until' level are not complements" if { + iri_above != iri_until +} + +incident_errors contains "VER-TFR-NRI: the trigger and the 'until' level are not complements" if { + nri_until != nri_equals - 1 +} + +incident_errors contains msg if { + some f in input.findings + not regex.match(`^N[0-9]$`, sprintf("%v", [f.pain])) + msg := sprintf("%v: impact %v is not an N-rating", [f.tracking_id, f.pain]) +} + +pain_number(p) := to_number(substring(p, 1, -1)) + +still_a_vulnerability(f) if { + f.fully_mitigated != true + f.final_disposition != "false-positive" +} + +incident_rule(f) := "VER-TFR-IRI" if { + f.internet_reachable == true + f.likely_exploitable == true + pain_number(f.pain) > iri_above +} else := "VER-TFR-NRI" if { + f.internet_reachable == false + f.likely_exploitable == true + pain_number(f.pain) == nri_equals +} + +incident_triggers := [t | + some f in input.findings + still_a_vulnerability(f) + rule := incident_rule(f) + t := { + "tracking_id": f.tracking_id, + "cve": object.get(f, "cve", null), + "rule": rule, + "pain": f.pain, + "first_evaluated": object.get(f, "first_evaluated", null), + } +] diff --git a/policies/triage_test.rego b/policies/triage_test.rego index c8af8841..4f6aadea 100644 --- a/policies/triage_test.rego +++ b/policies/triage_test.rego @@ -254,3 +254,105 @@ test_observed_reachability_beats_not_reachable_mitigation if { }) d.irv_basis == "observed" } + +# ---- VER-TFR-IRI / VER-TFR-NRI: vulnerabilities treated as incidents ------------------ +iri_text := concat(" ", [ + "Providers with Class C Certifications SHOULD treat internet-reachable likely exploitable vulnerabilities", + "where Potential Agency Impact N-rating > 3 as a FedRAMP Reportable Incident", + "until they are partially mitigated vulnerabilities at N3 or below.", +]) + +nri_text := concat(" ", [ + "Providers with Class C Certifications MAY treat likely exploitable vulnerabilities that are NOT internet-reachable", + "where Potential Agency Impact N-rating = 5 as a FedRAMP Reportable Incident", + "until they are partially mitigated vulnerabilities at N4 or below.", +]) + +ver_rules(iri, nri) := {"FRR": {"VER": {"data": {"all": {"TFR": { + "VER-TFR-IRI": {"varies_by_class": {"c": {"statement": iri}}}, + "VER-TFR-NRI": nri, +}}}}}} + +good_ver := ver_rules(iri_text, {"varies_by_class": {"c": {"statement": nri_text}}}) + +vf := { + "tracking_id": "t1", "cve": "CVE-2099-0001", "pain": "N4", "internet_reachable": true, + "likely_exploitable": true, "fully_mitigated": false, "final_disposition": "open", + "first_evaluated": "2026-11-01T00:00:00+00:00", +} + +triggers(patch, r) := ts if { + ts := triage.incident_triggers with data.rules as r + with input as {"findings": [object.union(vf, patch)]} +} + +ierrs(findings, r) := es if { + es := triage.incident_errors with data.rules as r with input as {"findings": findings} +} + +test_iri_opens_above_n3 if { + ts := triggers({}, good_ver) + ts == [{ + "tracking_id": "t1", "cve": "CVE-2099-0001", "rule": "VER-TFR-IRI", "pain": "N4", + "first_evaluated": "2026-11-01T00:00:00+00:00", + }] + triggers({"pain": "N5"}, good_ver)[0].rule == "VER-TFR-IRI" +} + +test_iri_ends_at_n3_or_below if { + triggers({"pain": "N3"}, good_ver) == [] + triggers({"pain": "N1"}, good_ver) == [] +} + +test_nri_opens_only_at_n5 if { + triggers({"internet_reachable": false, "pain": "N5"}, good_ver)[0].rule == "VER-TFR-NRI" + triggers({"internet_reachable": false, "pain": "N4"}, good_ver) == [] +} + +test_not_likely_exploitable_never_triggers if { + triggers({"likely_exploitable": false, "pain": "N5"}, good_ver) == [] + triggers({"likely_exploitable": false, "internet_reachable": false, "pain": "N5"}, good_ver) == [] +} + +test_false_positive_and_fully_mitigated_never_trigger if { + triggers({"final_disposition": "false-positive", "pain": "N5"}, good_ver) == [] + triggers({"fully_mitigated": true, "pain": "N5"}, good_ver) == [] +} + +test_accepted_still_triggers if { + triggers({"final_disposition": "accepted", "pain": "N5"}, good_ver)[0].rule == "VER-TFR-IRI" +} + +test_missing_cve_is_null if { + ts := triage.incident_triggers with data.rules as good_ver + with input as {"findings": [object.remove(vf, ["cve", "first_evaluated"])]} + ts[0].cve == null + ts[0].first_evaluated == null +} + +test_rules_read_cleanly if { + ierrs([vf], good_ver) == set() +} + +test_changed_iri_text_fails_closed if { + es := ierrs([vf], ver_rules("treat them as incidents", {"statement": nri_text})) + "VER-TFR-IRI Class C statement no longer reads 'N-rating > n ... at Nn or below'" in es +} + +test_changed_nri_text_fails_closed if { + es := ierrs([vf], ver_rules(iri_text, {"statement": "treat them as incidents"})) + "VER-TFR-NRI Class C statement no longer reads 'N-rating = n ... at Nn or below'" in es +} + +test_non_complement_fails_closed if { + bad_iri := replace(iri_text, "at N3 or below", "at N2 or below") + bad_nri := replace(nri_text, "at N4 or below", "at N3 or below") + es := ierrs([vf], ver_rules(bad_iri, {"statement": bad_nri})) + "VER-TFR-IRI: the trigger and the 'until' level are not complements" in es + "VER-TFR-NRI: the trigger and the 'until' level are not complements" in es +} + +test_bad_rating_fails_closed if { + es := ierrs([object.union(vf, {"pain": "high"})], good_ver) + "t1: impact high is not an N-rating" in es +} diff --git a/scripts/_freshness.py b/scripts/_freshness.py index 8272426c..06024ef4 100644 --- a/scripts/_freshness.py +++ b/scripts/_freshness.py @@ -33,6 +33,7 @@ ".well-known/vdr-report.json", ".well-known/ksi-signal-runtime.json", ".well-known/vdr-status.json", + ".well-known/incident-reports.json", ".well-known/boundary-corroboration.json", ) diff --git a/scripts/_gates.py b/scripts/_gates.py index d9c48274..0335c57a 100644 --- a/scripts/_gates.py +++ b/scripts/_gates.py @@ -62,6 +62,7 @@ "reconcile.e": "G6", "reconcile.f": "G6", "reconcile.l": "G6", + "reconcile.m": "G5", "reconcile.i.unreadable": "G7", "runtime-divergence.observer-fault": "G7", "detection.zap.missing": "G7", diff --git a/scripts/_incidents.py b/scripts/_incidents.py new file mode 100644 index 00000000..14fd68c2 --- /dev/null +++ b/scripts/_incidents.py @@ -0,0 +1,412 @@ +"""The incident register: data/incidents.json (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR). + +Every incident the operator records lives here, once, with the evaluation the +FedRAMP Incident Evaluation and Communication rules ask for: + +- evaluation when it was evaluated, whether it is a FedRAMP Reportable + Incident (IEC-CSO-EFR) and why; the basis is IEC-CSO-EFR, or + VER-TFR-IRI / VER-TFR-NRI for a vulnerability treated as one +- estimates Incident Rating records (IEC-CSO-EFI): rating, customer effect, + one or several agencies, reason, when. Until the first one, a + reportable incident is rated at the default (IEC-CSO-DPR) +- reports the Initial, Ongoing and Final reports, each with when it was + issued and what it set; a report restates everything set before +- resolved_at / recovery_complete_at, which start the Final report's clock + +The clocks (when each report is due) come from FedRAMP's Class C timeframes +through scripts/_rules.py, never from this file. scripts/build-incident-report.py +renders the reports and the incident log from it; reconciliation checks the +findings an incident names against the VDR. + +Fails closed, stdlib only (the deploy job installs no jsonschema), following +scripts/_decisions.py: a missing or invalid register stops the build. The JSON +schema beside it (infrastructure/schemas/incidents.schema.json) documents the +same shape and is checked in tests. +""" + +import json +import re +import sys +from datetime import datetime, timedelta, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _redact # noqa: E402 +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +DEFAULT_PATH = REPO / "data" / "incidents.json" +SCHEMA_PATH = REPO / "infrastructure" / "schemas" / "incidents.schema.json" + +ID_RE = re.compile(r"^INC-\d{4}-\d{3}$") +DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +TS_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$") +CVE_RE = re.compile(r"^CVE-[0-9]{4}-[0-9]{4,}$") +EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)") +# Addresses a published report may name: the system's own domain and FedRAMP's. +EMAIL_DOMAINS = ("samaydlette.com", "fedramp.gov", "gsa.gov") + +BASES = ("IEC-CSO-EFR", "VER-TFR-IRI", "VER-TFR-NRI") +VULN_RULES = ("VER-TFR-IRI", "VER-TFR-NRI") +REPORT_TYPES = ("Initial", "Ongoing", "Final") +EFFECTS = ("minimal", "narrow", "disruptive", "debilitating") +AGENCY_SCOPES = ("single", "multiple") +# Delivery the pipeline performs. Only publication is built; sending to FedRAMP +# or an agency is the operator's decision and is not implemented. +NOTIFICATION_MODES = ("published-only",) + +TOP_KEYS = {"$comment", "schema", "policy", "incidents"} +POLICY_KEYS = {"federal_incident_coordinator", "notification", "notification_text", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by"} +INCIDENT_KEYS = {"id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", + "findings", "estimates", "reports", "resolved_at", "recovery_complete_at"} +EVALUATION_KEYS = {"evaluated_at", "reportable", "basis", "reason", "federal_customer_data_considered"} +ESTIMATE_KEYS = {"estimated_at", "rating", "customer_effect", "agencies", "reason"} +REPORT_KEYS = {"type", "at", "set"} +# What a report can set, by the field it fills in the FedRAMP incident report. +TEXT_FIELDS = { + "description": "incidentDescription", + "functional_impact": "functionalImpact", + "recovery_plan": "recoveryPlan", + "observed_activity": "observedActivity", + "root_cause": "rootCause", + "response_and_recovery_activities": "responseAndRecoveryActivities", +} +LIST_FIELDS = { + "affected_agencies": "affectedAgencies", + "indicators_of_compromise": "indicatorsOfCompromise", + "related_cves": "relatedCveIds", +} +SET_KEYS = set(TEXT_FIELDS) | set(LIST_FIELDS) | {"milestones"} +MILESTONE_KEYS = {"at", "description"} + + +def _fail(msg): + raise SystemExit(f"::error::incident register: {msg} (fail-closed)") + + +def parse_ts(value, where): + """An aware datetime from an ISO 8601 timestamp with an offset, or fail.""" + if not isinstance(value, str) or not TS_RE.match(value): + _fail(f"{where} must be an ISO 8601 timestamp with a UTC offset, got {value!r}") + try: + return datetime.fromisoformat(value.replace("Z", "+00:00")) + except ValueError: + _fail(f"{where} is not a valid timestamp: {value!r}") + + +def _text(value, where): + if not isinstance(value, str) or not value.strip(): + _fail(f"{where} must be a non-empty string") + return value + + +def _strings(value, where, pattern=None): + if not isinstance(value, list) or not all(isinstance(x, str) and x.strip() for x in value): + _fail(f"{where} must be a list of non-empty strings") + if pattern is not None: + for x in value: + if not pattern.match(x): + _fail(f"{where}: {x!r} does not match {pattern.pattern}") + if len(set(value)) != len(value): + _fail(f"{where} lists an entry twice") + return value + + +def _published_text_ok(doc, where): + """Everything in the register is published: no AWS account ID, and no email + address outside the system's domain and FedRAMP's.""" + text = json.dumps(doc) + if _redact.find(text): + _fail(f"{where} contains an AWS account ID; the register is published") + for m in EMAIL_RE.finditer(text): + if not m.group(1).lower().endswith(EMAIL_DOMAINS): + _fail(f"{where} names an email address outside {', '.join(EMAIL_DOMAINS)}; the register is published") + + +def _validate_policy(p, where): + if not isinstance(p, dict) or set(p) - POLICY_KEYS or POLICY_KEYS - set(p): + _fail(f"{where}.policy must have exactly {sorted(POLICY_KEYS)}") + for k in ("federal_incident_coordinator", "notification_text", "decided_by"): + _text(p[k], f"{where}.policy.{k}") + for k in ("decided_on", "review_by"): + if not isinstance(p[k], str) or not DATE_RE.match(p[k]): + _fail(f"{where}.policy.{k} must be an ISO date") + if p["notification"] not in NOTIFICATION_MODES: + _fail(f"{where}.policy.notification {p['notification']!r} is not one of {list(NOTIFICATION_MODES)}; " + f"no other delivery is built") + adopted = _strings(p["adopted_vulnerability_rules"], f"{where}.policy.adopted_vulnerability_rules") + if set(adopted) - set(VULN_RULES): + _fail(f"{where}.policy.adopted_vulnerability_rules may name only {list(VULN_RULES)}") + _text(p["federal_customer_data"], f"{where}.policy.federal_customer_data") + + +def _validate_estimate(e, where, rubric, floor): + if not isinstance(e, dict) or set(e) != ESTIMATE_KEYS: + _fail(f"{where} must have exactly {sorted(ESTIMATE_KEYS)}") + at = parse_ts(e["estimated_at"], f"{where}.estimated_at") + if at < floor: + _fail(f"{where}.estimated_at is before the incident was detected") + if e["customer_effect"] not in EFFECTS or e["agencies"] not in AGENCY_SCOPES: + _fail(f"{where}: customer_effect must be one of {list(EFFECTS)} and agencies one of {list(AGENCY_SCOPES)}") + want = rubric[(e["customer_effect"], e["agencies"])] + if e["rating"] != want or isinstance(e["rating"], bool): + _fail(f"{where}: a likely {e['customer_effect']} effect on {e['agencies']} agenc" + f"{'y' if e['agencies'] == 'single' else 'ies'} is N{want} under IEC-CSO-EFI, not {e['rating']!r}") + _text(e["reason"], f"{where}.reason") + return at + + +def _validate_set(s, where): + if not isinstance(s, dict) or not s or set(s) - SET_KEYS: + _fail(f"{where}.set must be a non-empty object with only {sorted(SET_KEYS)}") + for k in TEXT_FIELDS: + if k in s: + _text(s[k], f"{where}.set.{k}") + for k in LIST_FIELDS: + if k in s: + _strings(s[k], f"{where}.set.{k}", CVE_RE if k == "related_cves" else None) + milestones = s.get("milestones", []) + if not isinstance(milestones, list): + _fail(f"{where}.set.milestones must be a list") + for i, m in enumerate(milestones): + if not isinstance(m, dict) or set(m) != MILESTONE_KEYS: + _fail(f"{where}.set.milestones[{i}] must have exactly {sorted(MILESTONE_KEYS)}") + parse_ts(m["at"], f"{where}.set.milestones[{i}].at") + _text(m["description"], f"{where}.set.milestones[{i}].description") + + +def _validate_incident(inc, where, policy, rubric, now): + rid = inc.get("id") if isinstance(inc, dict) else None + if not isinstance(rid, str) or not ID_RE.match(rid): + _fail(f"{where}: incident id {rid!r} is not INC-YYYY-NNN") + where = rid + required = {"id", "title", "exercise", "started_at", "detected_at", "detection_source", "evaluation", + "estimates", "reports"} + if set(inc) - INCIDENT_KEYS or required - set(inc): + _fail(f"{where}: unknown field(s) {sorted(set(inc) - INCIDENT_KEYS)}, missing {sorted(required - set(inc))}") + _text(inc["title"], f"{where}.title") + _text(inc["detection_source"], f"{where}.detection_source") + if not isinstance(inc["exercise"], bool): + _fail(f"{where}.exercise must be true or false") + started = parse_ts(inc["started_at"], f"{where}.started_at") + detected = parse_ts(inc["detected_at"], f"{where}.detected_at") + if detected < started: + _fail(f"{where}: detected before it started") + + ev = inc["evaluation"] + if not isinstance(ev, dict) or set(ev) != EVALUATION_KEYS: + _fail(f"{where}.evaluation must have exactly {sorted(EVALUATION_KEYS)} (IEC-CSO-EFR: when, the " + f"determination, its basis and reason, and the federal customer data considered)") + evaluated = parse_ts(ev["evaluated_at"], f"{where}.evaluation.evaluated_at") + if evaluated < detected: + _fail(f"{where}: evaluated before it was detected") + if not isinstance(ev["reportable"], bool): + _fail(f"{where}.evaluation.reportable must be true or false") + _text(ev["reason"], f"{where}.evaluation.reason") + _text(ev["federal_customer_data_considered"], f"{where}.evaluation.federal_customer_data_considered") + if ev["basis"] not in BASES: + _fail(f"{where}.evaluation.basis must be one of {list(BASES)}") + findings = _strings(inc.get("findings", []), f"{where}.findings") + if ev["basis"] in VULN_RULES: + if ev["basis"] not in policy["adopted_vulnerability_rules"]: + _fail(f"{where}: basis {ev['basis']} is not an adopted rule in policy.adopted_vulnerability_rules") + if not ev["reportable"]: + _fail(f"{where}: a vulnerability treated as a FedRAMP Reportable Incident under {ev['basis']} is reportable") + if not findings: + _fail(f"{where}: basis {ev['basis']} names no finding") + + if not isinstance(inc["estimates"], list) or not isinstance(inc["reports"], list): + _fail(f"{where}: estimates and reports must be lists") + if not ev["reportable"] and (inc["estimates"] or inc["reports"]): + _fail(f"{where}: not a FedRAMP Reportable Incident, so it carries no rating or report") + last = detected + for i, e in enumerate(inc["estimates"]): + at = _validate_estimate(e, f"{where}.estimates[{i}]", rubric, detected) + if at < last: + _fail(f"{where}.estimates are not in time order") + last = at + + resolved = parse_ts(inc["resolved_at"], f"{where}.resolved_at") if "resolved_at" in inc else None + recovered = (parse_ts(inc["recovery_complete_at"], f"{where}.recovery_complete_at") + if "recovery_complete_at" in inc else None) + if recovered and not resolved: + _fail(f"{where}: recovery is complete but the incident is not resolved") + if resolved and resolved < detected or recovered and resolved and recovered < resolved: + _fail(f"{where}: resolved_at / recovery_complete_at are out of order") + + reports = inc["reports"] + prev = evaluated + for i, r in enumerate(reports): + w = f"{where}.reports[{i}]" + if not isinstance(r, dict) or set(r) - REPORT_KEYS or {"type", "at"} - set(r): + _fail(f"{w} must have type, at and optionally set") + if r["type"] not in REPORT_TYPES: + _fail(f"{w}.type must be one of {list(REPORT_TYPES)}") + want = "Initial" if i == 0 else None + if want and r["type"] != want: + _fail(f"{where}: the first report is the Initial Incident Report (IEC-CSO-IIR)") + if i > 0 and r["type"] == "Initial": + _fail(f"{where}: only the first report is Initial") + if r["type"] == "Final" and i != len(reports) - 1: + _fail(f"{where}: nothing follows the Final Incident Report") + at = parse_ts(r["at"], f"{w}.at") + if at < prev: + _fail(f"{w}.at is before the evaluation or the previous report") + prev = at + if "set" in r: + _validate_set(r["set"], w) + elif r["type"] == "Initial": + _fail(f"{w}: the Initial report sets at least the description") + if reports and "description" not in reports[0].get("set", {}): + _fail(f"{where}: the Initial report must describe the incident (IEC-CSO-IIR)") + if reports and reports[-1]["type"] == "Final": + if not recovered: + _fail(f"{where}: a Final Incident Report needs resolved_at and recovery_complete_at (IEC-CSO-FIR)") + if parse_ts(reports[-1]["at"], "") < recovered: + _fail(f"{where}: the Final report is dated before recovery completed") + + if now is not None: + stamps = [started, detected, evaluated, resolved, recovered] + stamps += [parse_ts(e["estimated_at"], "") for e in inc["estimates"]] + stamps += [parse_ts(r["at"], "") for r in reports] + if any(t and t > now for t in stamps): + _fail(f"{where} records a time after now; a report cannot be issued in the future") + + +def validate(doc, where="data/incidents.json", now=None, rules_dir=_rules.RULES_DIR): + """Structural and rule checks, enforced at build time without a jsonschema + dependency. `now` (aware datetime), when given, also refuses future times.""" + if not isinstance(doc, dict) or doc.get("schema") != "incidents/1": + _fail(f"{where} is not an incidents/1 document") + if set(doc) - TOP_KEYS or {"schema", "policy", "incidents"} - set(doc): + _fail(f"{where}: top-level fields must be {sorted(TOP_KEYS)}") + _validate_policy(doc["policy"], where) + if not isinstance(doc["incidents"], list): + _fail(f"{where}: incidents must be a list") + rubric = _rules.incident_rating_rubric(rules_dir) + seen = set() + for i, inc in enumerate(doc["incidents"]): + _validate_incident(inc, f"{where} incidents[{i}]", doc["policy"], rubric, now) + if inc["id"] in seen: + _fail(f"{where}: duplicate id {inc['id']}") + seen.add(inc["id"]) + _published_text_ok(doc, where) + return doc + + +def load(path=None, now=None, rules_dir=_rules.RULES_DIR): + p = Path(path) if path else DEFAULT_PATH + if not p.is_file(): + _fail(f"{p} not found") + try: + doc = json.loads(p.read_text()) + except (json.JSONDecodeError, UnicodeDecodeError) as exc: + _fail(f"{p} is not valid JSON: {exc}") + return validate(doc, str(p), now=now, rules_dir=rules_dir) + + +# ---- ratings and clocks ------------------------------------------------------- + +def add_clock(start, unit, n): + """`start` plus n hours, or n business days. A business day here is Monday to + Friday in UTC; federal holidays are counted as business days, which can only + make a deadline earlier, never later.""" + if unit == "hours": + return start + timedelta(hours=n) + if unit == "bizdays": + t, left = start.astimezone(timezone.utc), n + while left: + t += timedelta(days=1) + if t.weekday() < 5: + left -= 1 + return t + _fail(f"unknown clock unit {unit!r}") + + +def rating_at(inc, t, default): + """(N-rating, basis) in force at time t: the latest Incident Rating estimate + made by then (IEC-CSO-EFI), else the default (IEC-CSO-DPR).""" + best = None + for e in inc["estimates"]: + if parse_ts(e["estimated_at"], "") <= t: + best = e + if best is None: + return default, "default (IEC-CSO-DPR)" + return best["rating"], f"estimated (IEC-CSO-EFI) at {best['estimated_at']}" + + +def rating_history(inc, default, until=None): + """[(when, rating, basis)] from evaluation through `until` (inclusive).""" + out = [(inc["evaluation"]["evaluated_at"], default, "default (IEC-CSO-DPR)")] + for e in inc["estimates"]: + if until is None or parse_ts(e["estimated_at"], "") <= until: + out.append((e["estimated_at"], e["rating"], f"estimated (IEC-CSO-EFI): {e['reason']}")) + return out + + +def _obligation(kind, due, report, index, now): + met_at = parse_ts(report["at"], "") if report else None + return {"report": kind, "due_at": due.isoformat(), "report_index": index, + "issued_at": report["at"] if report else None, + "on_time": (met_at <= due) if report else None, + "overdue": (report is None and now > due)} + + +def obligations(inc, timeframes, default, now): + """Every report the Class C clocks call for, in order, and whether each was + issued by its deadline. The last entry with report_index None is the one + still due. Not reportable: no obligations.""" + if not inc["evaluation"]["reportable"]: + return [] + reports = inc["reports"] + resolved = parse_ts(inc["resolved_at"], "") if "resolved_at" in inc else None + recovered = parse_ts(inc["recovery_complete_at"], "") if "recovery_complete_at" in inc else None + evaluated = parse_ts(inc["evaluation"]["evaluated_at"], "") + + def due(kind, start): + return add_clock(start, *timeframes[kind][rating_at(inc, start, default)[0]]) + + out = [_obligation("Initial", due("iir", evaluated), reports[0] if reports else None, 0 if reports else None, now)] + if not reports: + return out + i, prev = 1, parse_ts(reports[0]["at"], "") + while True: + oir_due = due("oir", prev) + if resolved is not None and resolved <= oir_due: + # Resolved before the next Ongoing report fell due: any further + # Ongoing reports are voluntary, and the Final report's clock starts + # when recovery completes (IEC-CSO-FIR). + while i < len(reports) and reports[i]["type"] == "Ongoing": + i += 1 + if recovered is not None: + final = reports[i] if i < len(reports) else None + out.append(_obligation("Final", due("fir", recovered), final, i if final else None, now)) + return out + nxt = reports[i] if i < len(reports) and reports[i]["type"] == "Ongoing" else None + out.append(_obligation("Ongoing", oir_due, nxt, i if nxt else None, now)) + if nxt is None: + return out + prev, i = parse_ts(nxt["at"], ""), i + 1 + + +def status(inc): + if not inc["evaluation"]["reportable"]: + return "not-reportable" + if inc["reports"] and inc["reports"][-1]["type"] == "Final": + return "closed" + if "resolved_at" in inc: + return "resolved" + return "open" + + +def open_findings(reg, include_exercises=False): + """{finding or CVE: incident id} named by incidents that are not yet resolved.""" + out = {} + for inc in reg["incidents"]: + if inc["exercise"] and not include_exercises: + continue + if status(inc) == "open": + for f in inc.get("findings", []): + out[f] = inc["id"] + return out diff --git a/scripts/_rules.py b/scripts/_rules.py index ed703e1c..26bb5ebe 100644 --- a/scripts/_rules.py +++ b/scripts/_rules.py @@ -9,6 +9,7 @@ import hashlib import json +import re from functools import lru_cache from pathlib import Path @@ -188,3 +189,83 @@ def applicable_provider_rules(rules_dir=RULES_DIR): if not out: _fail("no provider rules apply; the applicability metadata has changed shape") return out + + +# ---- Incident Evaluation and Communication (IEC), Class C --------------------- +# The report clocks and the Incident Rating scale are FedRAMP's, read here from +# the pinned corpus like the remediation matrix above, never typed in. + +INCIDENT_REPORTS = {"iir": "IEC-CSO-IIR", "oir": "IEC-CSO-OIR", "fir": "IEC-CSO-FIR"} +_CLOCK_UNITS = ("hours", "bizdays") + + +def _iec(rules, rule_id): + try: + return rules["FRR"]["IEC"]["data"]["all"]["CSO"][rule_id] + except (KeyError, TypeError): + _fail(f"{rule_id} not found at FRR/IEC/data/all/CSO") + + +def incident_report_timeframes(rules_dir=RULES_DIR): + """{"iir"|"oir"|"fir": {1..5: (unit, n)}} for Class C, unit "hours" or + "bizdays". Every impact level must carry every clock: a report with no + deadline cannot be alarmed.""" + rules, _ = load_rules(rules_dir) + out = {} + for kind, rid in INCIDENT_REPORTS.items(): + try: + table = _iec(rules, rid)["varies_by_class"][CERT_CLASS]["pain_timeframes"] + except (KeyError, TypeError): + _fail(f"{rid} has no Class {CERT_CLASS.upper()} pain_timeframes") + clocks = {} + for n in ("1", "2", "3", "4", "5"): + cell = (table.get(n) or {}).get(kind) + if not isinstance(cell, dict) or cell.get("timeframe_type") not in _CLOCK_UNITS \ + or not isinstance(cell.get("timeframe_num"), int) or isinstance(cell["timeframe_num"], bool) \ + or cell["timeframe_num"] <= 0: + _fail(f"{rid} Class C N{n} {kind} is not a positive number of hours or business days") + clocks[int(n)] = (cell["timeframe_type"], cell["timeframe_num"]) + out[kind] = clocks + return out + + +_RATING_RE = re.compile(r"^\*\*N([1-5])\*\* for (.+)\.$") +_CLAUSE_RE = re.compile(r"likely (minimal|narrow|disruptive|debilitating) customer effect on " + r"(1 or more agencies|more than 1 agency|1 agency)") +_SCOPES_BY_TEXT = {"1 or more agencies": ("single", "multiple"), "1 agency": ("single",), + "more than 1 agency": ("multiple",)} + + +def incident_rating_rubric(rules_dir=RULES_DIR): + """{(customer effect, "single"|"multiple" agencies): N-rating 1..5} from the + IEC-CSO-EFI bullets. Every (effect, scope) pair must be rated exactly once, + or the text has changed shape and the rubric is not trusted.""" + rules, _ = load_rules(rules_dir) + bullets = _iec(rules, "IEC-CSO-EFI").get("following_information_bullets") + if not isinstance(bullets, list) or not bullets: + _fail("IEC-CSO-EFI has no rating bullets") + out = {} + for b in bullets: + m = _RATING_RE.match(b) if isinstance(b, str) else None + clauses = _CLAUSE_RE.findall(m.group(2)) if m else [] + if not clauses: + _fail(f"IEC-CSO-EFI bullet {b!r} is not in the expected form") + for effect, scope_text in clauses: + for scope in _SCOPES_BY_TEXT[scope_text]: + if (effect, scope) in out: + _fail(f"IEC-CSO-EFI rates {effect}/{scope} twice") + out[(effect, scope)] = int(m.group(1)) + effects = ("minimal", "narrow", "disruptive", "debilitating") + if set(out) != {(e, s) for e in effects for s in ("single", "multiple")}: + _fail("IEC-CSO-EFI does not rate every customer effect for one and for several agencies") + return out + + +def default_incident_rating(rules_dir=RULES_DIR): + """IEC-CSO-DPR: the N-rating a FedRAMP Reportable Incident has until it is estimated.""" + rules, _ = load_rules(rules_dir) + stmt = _iec(rules, "IEC-CSO-DPR").get("statement", "") + m = re.search(r"\(PAIN\) of ([1-5])\b", stmt) + if not m: + _fail("IEC-CSO-DPR no longer states a default PAIN rating") + return int(m.group(1)) diff --git a/scripts/build-incident-report.py b/scripts/build-incident-report.py new file mode 100644 index 00000000..7c67def4 --- /dev/null +++ b/scripts/build-incident-report.py @@ -0,0 +1,413 @@ +#!/usr/bin/env python3 +# ============================================================================= +# INCIDENT REPORTS: IIR, OIR and FIR from the incident register +# ============================================================================= +# The incident register (data/incidents.json, read through scripts/_incidents.py) +# records each incident's FedRAMP reportability evaluation (IEC-CSO-EFR), its +# Incident Rating (IEC-CSO-EFI, or the IEC-CSO-DPR default) and the reports +# issued. This renders, for every FedRAMP Reportable Incident, each report in +# FedRAMP's 2026-06-24 incident report schema: +# +# incident---initial.json IEC-CSO-IIR +# incident---ongoing.json IEC-CSO-OIR (restates every earlier item) +# incident---final.json IEC-CSO-FIR (final values for every item) +# +# each validated before it is written (scripts/_fedramp_schema.py), plus the +# incident log: +# +# incident-reports.json every incident, its evaluation and reason, its rating +# history, each report (file, sha256, what changed) and +# each report clock (due, issued, on time) +# incident-reports.md the same, human-readable, with every report's content +# +# The clocks are FedRAMP's Class C timeframes, read through scripts/_rules.py. +# +# Vulnerabilities as incidents (VER-TFR-IRI, VER-TFR-NRI). Given the VDR report, +# policies/triage.rego names each finding a rule makes a FedRAMP Reportable +# Incident. One the operator has adopted that rule for and that no unresolved +# incident names is published as a trigger with no incident, its Initial +# report due from the finding's first evaluation at the default rating; the +# clock check fails, and the evidence watchdog pages, once that time passes. +# +# Notification. Delivery to FedRAMP and agencies is not built: the register's +# policy says "published-only" and every report says so. Publication under +# /.well-known/ is the only channel until the operator decides otherwise. +# +# build-incident-report.py --incidents ../data/incidents.json --vdr vdr-report.json --out-dir . +# build-incident-report.py --check incident-reports.json # exit 1 if a report is overdue +# ============================================================================= + +import argparse +import hashlib +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _fedramp_schema as fs # noqa: E402 +import _incidents # noqa: E402 +import _rules # noqa: E402 + +INDEX = "incident-reports.json" +INDEX_MD = "incident-reports.md" +EXERCISE_PREFIX = "EXERCISE: a simulated incident; no real system, data or agency was affected. " + +# The items an Initial report carries (IEC-CSO-IIR) and the further items an +# Ongoing report adds (IEC-CSO-OIR), in the rules' order, by register field. +IIR_ITEMS = [("coordinator", "Federal incident response coordinator"), + ("tracking_id", "Provider tracking identifier"), + ("description", "Description of the incident"), + ("timeline", "Timeline"), + ("rating", "Potential Agency Impact N-rating (historical and current)"), + ("functional_impact", "Functional impact to federal agency customers"), + ("recovery_plan", "Estimated recovery plan, milestones and timelines"), + ("affected_agencies", "Likely affected customer agencies")] +OIR_ITEMS = [("observed_activity", "Observed incident activity"), + ("indicators_of_compromise", "Indicators of compromise"), + ("related_cves", "Related CVE identifiers"), + ("root_cause", "Root cause"), + ("response_and_recovery_activities", "Response and recovery activities")] + + +def _fail(msg): + raise SystemExit(f"::error::incident reports: {msg} (fail-closed)") + + +def _iso(dt): + return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") + + +def vulnerability_triggers(vdr): + """The VDR findings policies/triage.rego treats as FedRAMP Reportable Incidents.""" + import _triage + findings = [{k: f.get(k) for k in ("tracking_id", "cve", "pain", "internet_reachable", "likely_exploitable", + "fully_mitigated", "final_disposition", "first_evaluated")} + for f in vdr.get("findings", [])] + out = _triage.evaluate('{"triggers": data.vdr.triage.incident_triggers, ' + '"errors": data.vdr.triage.incident_errors}', {"findings": findings}) + if out.get("errors"): + _fail("; ".join(sorted(out["errors"]))) + if not isinstance(out.get("triggers"), list): + _fail("the triage policy returned no incident triggers") + return out["triggers"] + + +def _milestones(inc, upto, default): + """Every milestone known at `upto`: the register's, plus the ones the + register's own fields mark (evaluation, each rating, resolution, recovery).""" + ms = [] + for r in inc["reports"]: + if _incidents.parse_ts(r["at"], "") > upto: + break + ms += [(m["at"], m["description"]) for m in r.get("set", {}).get("milestones", [])] + ev = inc["evaluation"] + ms.append((ev["evaluated_at"], f"FedRAMP reportability evaluated ({ev['basis']}): reportable; " + f"rated N{default} by default (IEC-CSO-DPR)")) + for e in inc["estimates"]: + ms.append((e["estimated_at"], f"Incident Rating estimated N{e['rating']} (IEC-CSO-EFI)")) + for k, text in (("resolved_at", "Incident resolved"), ("recovery_complete_at", "Recovery complete")): + if k in inc: + ms.append((inc[k], text)) + known = [(at, d) for at, d in ms if _incidents.parse_ts(at, "") <= upto] + return [{"occurredAt": at, "milestoneDescription": d} + for at, d in sorted(known, key=lambda x: _incidents.parse_ts(x[0], ""))] + + +def _state(inc, k): + """The register fields as known after report k, and which report last set each.""" + state, set_by = {}, {} + for i, r in enumerate(inc["reports"][:k + 1]): + for key, val in r.get("set", {}).items(): + if key != "milestones": + state[key], set_by[key] = val, i + return state, set_by + + +def _rating_notes(inc, at, default): + rating, basis = _incidents.rating_at(inc, at, default) + hist = [f"N{r} from {when} ({b})" for when, r, b in _incidents.rating_history(inc, default, at)] + if basis.startswith("default"): + lead = (f"No Incident Rating estimate had been made; rated N{rating} by default as IEC-CSO-DPR requires.") + else: + e = [x for x in inc["estimates"] if _incidents.parse_ts(x["estimated_at"], "") <= at][-1] + scope = "one agency" if e["agencies"] == "single" else "more than one agency" + lead = (f"Estimated N{rating} under IEC-CSO-EFI: a likely {e['customer_effect']} customer effect on " + f"{scope}. {e['reason']}") + return rating, f"{lead} History: {'; '.join(hist)}." + + +def report_document(inc, k, policy, default): + """Report k of incident `inc` in the FedRAMP incident report schema. Every + item set by report k or earlier is restated with its latest value.""" + r = inc["reports"][k] + at = _incidents.parse_ts(r["at"], "") + state, _ = _state(inc, k) + rating, notes = _rating_notes(inc, at, default) + doc = { + "$schema": fs.stamp("incident"), + "certificationPackageOverviewUri": fs.CPO_URI, + "reportType": r["type"], + "providerTrackingId": inc["id"], + "federalIncidentCoordinator": policy["federal_incident_coordinator"], + "incidentDescription": (EXERCISE_PREFIX if inc["exercise"] else "") + state["description"], + "timeline": { + "startedAt": inc["started_at"], + "detectedAt": inc["detected_at"], + "detectionSource": inc["detection_source"], + "evaluationCompletedAt": inc["evaluation"]["evaluated_at"], + "milestones": _milestones(inc, at, default), + }, + "potentialImpact": { + "historicalRating": [n for _, n, _ in _incidents.rating_history(inc, default, at)], + "currentRating": rating, + "evaluationNotes": notes, + }, + } + for key, field in _incidents.TEXT_FIELDS.items(): + if key in state and key != "description": + doc[field] = state[key] + for key, field in _incidents.LIST_FIELDS.items(): + if key in state: + doc[field] = state[key] + if r["type"] == "Final": + doc["resolvedAt"] = inc["recovery_complete_at"] + return doc + + +def _changes(inc, k): + """{item: "updated" | "no update" | "not yet available"} for report k.""" + state, set_by = _state(inc, k) + out = {} + for key, _ in IIR_ITEMS + OIR_ITEMS: + if key in ("coordinator", "tracking_id"): + out[key] = "updated" if k == 0 else "no update" + elif key == "timeline": + out[key] = "updated" if k == 0 or inc["reports"][k].get("set", {}).get("milestones") else "no update" + elif key == "rating": + prev = _incidents.parse_ts(inc["reports"][k - 1]["at"], "") if k else None + now = _incidents.parse_ts(inc["reports"][k]["at"], "") + moved = k == 0 or any(prev < _incidents.parse_ts(e["estimated_at"], "") <= now for e in inc["estimates"]) + out[key] = "updated" if moved else "no update" + elif key not in state: + out[key] = "not yet available" + else: + out[key] = "updated" if set_by[key] == k else "no update" + return out + + +def build(reg, vdr, now, out_dir, rules_dir=_rules.RULES_DIR): + """Write every report and the incident log; return the log.""" + out_dir = Path(out_dir) + timeframes = _rules.incident_report_timeframes(rules_dir) + default = _rules.default_incident_rating(rules_dir) + policy = reg["policy"] + registry = fs.load_registry() + incidents, due = [], [] + for inc in reg["incidents"]: + reports = [] + for k, r in enumerate(inc["reports"]): + name = f"incident-{inc['id']}-{k + 1:02d}-{r['type'].lower()}.json" + fs.write_validated(report_document(inc, k, policy, default), "incident", out_dir / name, registry) + reports.append({"type": r["type"], "issued_at": r["at"], "file": name, + "sha256": hashlib.sha256((out_dir / name).read_bytes()).hexdigest(), + "changes": _changes(inc, k)}) + obligations = _incidents.obligations(inc, timeframes, default, now) + pending = [o for o in obligations if o["report_index"] is None] + for o in pending: + due.append({"incident": inc["id"], "finding": None, "report": o["report"], "due_at": o["due_at"], + "overdue": o["overdue"]}) + last = inc["reports"][-1]["at"] if inc["reports"] else inc["evaluation"]["evaluated_at"] + rating, basis = _incidents.rating_at(inc, _incidents.parse_ts(last, ""), default) + incidents.append({ + "id": inc["id"], "title": inc["title"], "exercise": inc["exercise"], + "status": _incidents.status(inc), + "detected_at": inc["detected_at"], "detection_source": inc["detection_source"], + "evaluation": inc["evaluation"], "findings": inc.get("findings", []), + "rating": ({"current": rating, "basis": basis, + "history": [{"from": w, "rating": n, "basis": b} + for w, n, b in _incidents.rating_history(inc, default)]} + if inc["evaluation"]["reportable"] else None), + "resolved_at": inc.get("resolved_at"), "recovery_complete_at": inc.get("recovery_complete_at"), + "reports": reports, "obligations": obligations, + "next_report_due_at": pending[0]["due_at"] if pending else None, + }) + + triggers = [] + covered = _incidents.open_findings(reg) + if vdr is not None: + for t in vulnerability_triggers(vdr): + adopted = t["rule"] in policy["adopted_vulnerability_rules"] + inc_id = covered.get(t["tracking_id"]) or (covered.get(t["cve"]) if t["cve"] else None) + entry = {**t, "adopted": adopted, "incident": inc_id} + triggers.append(entry) + if adopted and inc_id is None: + start = _incidents.parse_ts(t["first_evaluated"], "") if t["first_evaluated"] else now + unit, n = timeframes["iir"][default] + at = _incidents.add_clock(start, unit, n) + due.append({"incident": None, "finding": t["tracking_id"], "report": "Initial", + "due_at": at.isoformat(), "overdue": now > at}) + overdue = [d for d in due if d["overdue"]] + log = { + "schema": "incident-reports/1", + "emitted_at": _iso(now), + "generator": "scripts/build-incident-report.py", + "description": ("The incident log: every incident recorded in data/incidents.json, its FedRAMP " + "reportability evaluation and reason (IEC-CSO-EFR), its Incident Rating (IEC-CSO-EFI, " + "or the IEC-CSO-DPR default), each Initial, Ongoing and Final report issued, and each " + "Class C report clock. Exercises are marked exercise: true."), + "rules": _rules.pin(rules_dir), + "notification": {"mode": policy["notification"], "text": policy["notification_text"]}, + "policy": {k: policy[k] for k in ("federal_incident_coordinator", "adopted_vulnerability_rules", + "federal_customer_data", "decided_by", "decided_on", "review_by")}, + "vdr": ({"emitted_at": vdr.get("emitted_at"), "report_id": vdr.get("report_id")} if vdr is not None + else None), + "vulnerability_triggers": triggers, + "obligations_due": due, + "clock_status": "overdue" if overdue else "ok", + "summary": { + "incidents": len(incidents), + "reportable": sum(1 for i in incidents if i["evaluation"]["reportable"]), + "open": sum(1 for i in incidents if i["status"] in ("open", "resolved")), + "exercises": sum(1 for i in incidents if i["exercise"]), + "reports": sum(len(i["reports"]) for i in incidents), + "triggers_without_incident": sum(1 for t in triggers if t["adopted"] and t["incident"] is None), + "overdue": len(overdue), + }, + "incidents": incidents, + } + (out_dir / INDEX).write_text(json.dumps(log, indent=2) + "\n") + (out_dir / INDEX_MD).write_text(render_markdown(log, out_dir) + "\n") + return log + + +def _item_text(key, doc): + if key == "coordinator": + return doc["federalIncidentCoordinator"] + if key == "tracking_id": + return doc["providerTrackingId"] + if key == "description": + return doc["incidentDescription"] + if key == "timeline": + t = doc["timeline"] + lines = [f"started {t['startedAt']}; detected {t['detectedAt']} by {t['detectionSource']}; " + f"reportability evaluated {t['evaluationCompletedAt']}"] + lines += [f"{m['occurredAt']}: {m['milestoneDescription']}" for m in t["milestones"]] + return "\n".join(f" - {x}" for x in lines) + if key == "rating": + p = doc["potentialImpact"] + return f"N{p['currentRating']} (history {', '.join(f'N{n}' for n in p['historicalRating'])}). " \ + f"{p['evaluationNotes']}" + field = _incidents.TEXT_FIELDS.get(key) or _incidents.LIST_FIELDS.get(key) + val = doc.get(field) + if isinstance(val, list): + return ", ".join(val) if val else "none" + return val or "not yet available" + + +def render_markdown(log, out_dir): + s = log["summary"] + out = ["# Incident log and reports", "", + "_Generated by scripts/build-incident-report.py from data/incidents.json. The JSON beside this file " + "(incident-reports.json, signed) is the record; this is a rendering of it._", "", + f"- **Emitted:** {log['emitted_at']}", + f"- **Incidents:** {s['incidents']} ({s['reportable']} FedRAMP Reportable; {s['exercises']} exercises); " + f"**reports issued:** {s['reports']}; **overdue:** {s['overdue']}", + f"- **Notification:** {log['notification']['mode']}. {log['notification']['text']}", + f"- **Federal incident response coordinator:** {log['policy']['federal_incident_coordinator']}", + f"- **Vulnerabilities treated as incidents:** {', '.join(log['policy']['adopted_vulnerability_rules'])}", + ""] + out += ["## Vulnerabilities that are FedRAMP Reportable Incidents (VER-TFR-IRI / VER-TFR-NRI)", ""] + if log["vdr"] is None: + out += ["No VDR report was supplied to this build.", ""] + elif not log["vulnerability_triggers"]: + out += [f"None in the VDR report emitted {log['vdr']['emitted_at']}.", ""] + else: + out += ["| Finding | Rule | PAIN | Adopted | Incident |", "|---|---|---|---|---|"] + out += [f"| `{t['tracking_id']}` | {t['rule']} | {t['pain']} | {t['adopted']} | {t['incident'] or 'NONE'} |" + for t in log["vulnerability_triggers"]] + out.append("") + if log["obligations_due"]: + out += ["## Reports due", "", "| Incident / finding | Report | Due | Overdue |", "|---|---|---|---|"] + out += [f"| {d['incident'] or d['finding']} | {d['report']} | {d['due_at']} | {d['overdue']} |" + for d in log["obligations_due"]] + out.append("") + for entry in log["incidents"]: + ev = entry["evaluation"] + out += [f"## {entry['id']}: {entry['title']}" + (" (EXERCISE)" if entry["exercise"] else ""), "", + f"- **Status:** {entry['status']}", + f"- **Detected:** {entry['detected_at']} by {entry['detection_source']}", + f"- **Reportability (IEC-CSO-EFR, evaluated {ev['evaluated_at']}, basis {ev['basis']}):** " + f"{'FedRAMP Reportable Incident' if ev['reportable'] else 'not a FedRAMP Reportable Incident'}. " + f"{ev['reason']}", + f"- **Federal customer data considered:** {ev['federal_customer_data_considered']}"] + if entry["findings"]: + out.append(f"- **Findings named:** {', '.join(f'`{f}`' for f in entry['findings'])}") + if entry["rating"]: + out.append(f"- **Rating:** N{entry['rating']['current']} ({entry['rating']['basis']})") + if entry["obligations"]: + out += ["", "| Report | Due | Issued | On time |", "|---|---|---|---|"] + out += [f"| {o['report']} | {o['due_at']} | {o['issued_at'] or 'not yet'} | " + f"{'yes' if o['on_time'] else 'no' if o['on_time'] is False else ('OVERDUE' if o['overdue'] else 'pending')} |" + for o in entry["obligations"]] + out.append("") + for k, rep in enumerate(entry["reports"]): + doc = json.loads((Path(out_dir) / rep["file"]).read_text()) + out += [f"### {rep['type']} report, issued {rep['issued_at']} ({rep['file']})", "", + f"_Notification: {log['notification']['mode']}; see above._", ""] + items = IIR_ITEMS + (OIR_ITEMS if k else + [x for x in OIR_ITEMS if rep["changes"][x[0]] != "not yet available"]) + for key, label in items: + change = rep["changes"][key] + text = _item_text(key, doc) + sep = "\n" if text.startswith(" - ") else " " + out.append(f"- **{label}** ({change}):{sep}{text}") + if rep["type"] == "Final": + out.append(f"- **Resolved and recovered:** {doc['resolvedAt']}") + out.append("") + return "\n".join(out).rstrip() + + +def check(index_path, now): + """Exit status for the clock check: 1 when a report is due and missing.""" + log = json.loads(Path(index_path).read_text()) + late = [d for d in log.get("obligations_due", []) + if _incidents.parse_ts(d["due_at"], "obligations_due.due_at") < now] + for d in late: + who = d["incident"] or f"finding {d['finding']} (no incident opened)" + print(f"::error::{who}: the {d['report']} incident report was due at {d['due_at']} and has not been issued") + if not late: + print(f"incident report clocks: ok ({len(log.get('obligations_due', []))} report(s) pending, none overdue)") + return 1 if late else 0 + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--incidents", default=str(_incidents.DEFAULT_PATH)) + ap.add_argument("--vdr", default=None, help="the built VDR report, for VER-TFR-IRI/NRI triggers") + ap.add_argument("--out-dir", default=".") + ap.add_argument("--now", default=None, help="ISO 8601 time to evaluate the clocks at (default: now)") + ap.add_argument("--check", default=None, metavar="INDEX", + help="check a built incident-reports.json and exit 1 if a report is overdue") + a = ap.parse_args(argv) + now = _incidents.parse_ts(a.now, "--now") if a.now else datetime.now(timezone.utc) + if a.check: + return check(a.check, now) + reg = _incidents.load(a.incidents, now=now) + vdr = None + if a.vdr: + try: + vdr = json.loads(Path(a.vdr).read_text()) + except (OSError, json.JSONDecodeError) as exc: + _fail(f"cannot read the VDR report {a.vdr}: {exc}") + if not isinstance(vdr, dict) or not isinstance(vdr.get("findings"), list): + _fail(f"{a.vdr} is not a VDR report") + log = build(reg, vdr, now, a.out_dir) + s = log["summary"] + print(f"incident reports: {s['incidents']} incident(s), {s['reports']} report(s), " + f"{s['triggers_without_incident']} trigger(s) without an incident, clocks {log['clock_status']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-ksi-signal.py b/scripts/build-ksi-signal.py index 1d570b1c..08f2b07e 100755 --- a/scripts/build-ksi-signal.py +++ b/scripts/build-ksi-signal.py @@ -556,6 +556,9 @@ ("iam_role", "evidence_nightly"): { "function": "Nightly evidence workflow role", }, + ("iam_role", "incident_reports"): { + "function": "Incident reports workflow role (unattended IIR/OIR/FIR publication)", + }, ("object_store", "logs"): { "function": "Access-log bucket for the site bucket and CDN", "diagram_label": "S3 access-log bucket", diff --git a/scripts/build-ocr.py b/scripts/build-ocr.py index cad56d46..08f126ea 100644 --- a/scripts/build-ocr.py +++ b/scripts/build-ocr.py @@ -30,6 +30,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import _decisions # noqa: E402 +import _incidents # noqa: E402 QUARTER_DAYS = 91 @@ -50,7 +51,22 @@ def _scn_rows(path): return list(csv.DictReader(f)) -def build_ocr(vdr, decisions, scn_rows, signal_id, now): +def incident_summary(incidents, period_start): + """CCM-OCR-AVL item 7, from the incident register: the FedRAMP Reportable + Incidents detected this period, or an attestation of none. Exercises are + not incidents and are never counted.""" + log = "The incident log, /.well-known/incident-reports.json, records every incident evaluated, exercises included." + real = [i for i in (incidents or {}).get("incidents", []) + if not i["exercise"] and i["evaluation"]["reportable"] and i["detected_at"][:10] >= period_start] + if real: + return (f"{len(real)} FedRAMP Reportable Incident(s) this period: " + + "; ".join(f"{i['id']} ({_incidents.status(i)})" for i in real) + f". {log}") + return ("No FedRAMP Reportable Incidents occurred during this reporting period. The system holds " + "no federal customer data, so the IEC-CSO-EFR trigger does not apply; this is an " + f"attestation of none, not an omission. {log}") + + +def build_ocr(vdr, decisions, scn_rows, signal_id, now, incidents=None): period_start = (now - timedelta(days=QUARTER_DAYS)).date().isoformat() period_end = now.date().isoformat() @@ -97,10 +113,7 @@ def build_ocr(vdr, decisions, scn_rows, signal_id, now): "No new customer recommendations this period; the Secure Configuration " "Guidance at /.well-known/ remains current."], "agencies_using_product": [], # 6 (none) - "reportable_incidents_or_attestation": # 7 - "No FedRAMP Reportable Incidents occurred during this reporting period. " - "The system holds no federal customer data, so the IEC-CSO-EFR trigger " - "does not apply; this is an attestation of none, not an omission.", + "reportable_incidents_or_attestation": incident_summary(incidents, period_start), # 7 "lessons_learned_from_incidents": [], # 8 (none) }, "relationship_obligations_status": ( @@ -162,6 +175,7 @@ def main(): ap.add_argument("--vdr", default="vdr-report.json") ap.add_argument("--decisions", default="../data/decisions.json") ap.add_argument("--scn-register", default="../docs/scn/scn-register.csv") + ap.add_argument("--incidents", default="../data/incidents.json") ap.add_argument("--ksi-signal", default="ksi-signal.json") ap.add_argument("--output", default="ongoing-certification-report.json") ap.add_argument("--md-output", default="ongoing-certification-report.md") @@ -174,7 +188,7 @@ def main(): signal_id = sig.get("signal_id") if sig else None scn_rows = _scn_rows(a.scn_register) - report = build_ocr(vdr, decisions, scn_rows, signal_id, now) + report = build_ocr(vdr, decisions, scn_rows, signal_id, now, _incidents.load(a.incidents)) Path(a.output).write_text(json.dumps(report, indent=2) + "\n") if a.md_output: Path(a.md_output).write_text(render_markdown(report) + "\n") diff --git a/scripts/check-incident-publisher.py b/scripts/check-incident-publisher.py new file mode 100644 index 00000000..e31d3cfa --- /dev/null +++ b/scripts/check-incident-publisher.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +"""Deploy preflight: the unattended incident report publisher is in place. + +The FedRAMP incident report records (IEC-CSO-IIR/OIR/FIR/AIR) describe the +system as it is after a successful deploy, so a deploy must not succeed +without the prerequisites they rely on. Run early in the deploy job, before +anything is applied, this fails the deploy unless: + + 1. the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is set, and + 2. it names the role infrastructure/bootstrap/incident-reports.tf creates + (github-actions-incident-reports-oidc, an IAM role ARN), and + 3. the `incident-reports` GitHub Environment exists and deploys only from + main (a custom branch policy naming exactly `main`). + +Check 3 reads GitHub's API with the job token. A missing environment (404) +fails. If the token cannot read the environment at all (any other error), the +check is reported as not observed and the deploy continues on checks 1-2: +the deploy's later incident-publisher job assumes the role from that +environment, so a wrong environment still fails the deploy there. + +Whether the role itself works is proved later in the same run: the +`incident-publisher` job calls .github/workflows/incident-reports.yml, which +assumes the role, publishes, and fails the deploy if it cannot. + +Prints no ARN or account ID. Exit 0 pass, 1 fail. +""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +import urllib.error +import urllib.request +from typing import Any + +EXPECTED_ROLE_NAME = "github-actions-incident-reports-oidc" +ENVIRONMENT = "incident-reports" +EXPECTED_BRANCHES = {"main"} +ROLE_ARN_RE = re.compile(r"^arn:aws(-[a-z]+)*:iam::[0-9]{12}:role/(?:[\w+=,.@-]+/)*([\w+=,.@-]+)$") + + +def check_variable(role_arn: str | None) -> list[str]: + if not role_arn or not role_arn.strip(): + return ["the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is not set: apply " + "infrastructure/bootstrap/incident-reports.tf and set it from the incident_reports_role_arn output"] + m = ROLE_ARN_RE.match(role_arn.strip()) + if not m: + return ["AWS_INCIDENT_REPORTS_ROLE_ARN is not an IAM role ARN"] + if m.group(2) != EXPECTED_ROLE_NAME: + return [f"AWS_INCIDENT_REPORTS_ROLE_ARN names a role other than {EXPECTED_ROLE_NAME}"] + return [] + + +def check_environment(env: dict[str, Any] | None, branch_policies: list[str] | None) -> tuple[list[str], str]: + """(problems, note). env None = the environment does not exist.""" + if env is None: + return [f"the {ENVIRONMENT} GitHub Environment does not exist"], "" + policy = env.get("deployment_branch_policy") or {} + if not policy.get("custom_branch_policies") or policy.get("protected_branches"): + return [f"the {ENVIRONMENT} environment does not restrict deployments to a custom branch list"], "" + if branch_policies is None: + return [], "branch policies not observed" + if set(branch_policies) != EXPECTED_BRANCHES: + return [f"the {ENVIRONMENT} environment deploys from {sorted(branch_policies) or 'no branch'}, " + "not only main"], "" + return [], f"{ENVIRONMENT} deploys only from main" + + +def _get(url: str, token: str | None) -> Any: + if not url.startswith("https://"): + raise ValueError("refusing non-HTTPS URL") + headers = {"Accept": "application/vnd.github+json", "User-Agent": "samaydlette-preflight"} + if token: + headers["Authorization"] = f"Bearer {token}" + with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=15) as r: # noqa: S310 + return json.loads(r.read().decode()) + + +def read_environment(repo: str, token: str | None) -> tuple[str, dict[str, Any] | None, list[str] | None]: + """("ok"|"missing"|"unreadable", environment, branch policy names).""" + api = f"https://api.github.com/repos/{repo}/environments/{ENVIRONMENT}" + try: + env = _get(api, token) + except urllib.error.HTTPError as exc: + return ("missing" if exc.code == 404 else "unreadable"), None, None + except Exception: # noqa: BLE001 (any other failure: not observed) + return "unreadable", None, None + try: + pols = _get(f"{api}/deployment-branch-policies", token) + names = [p.get("name", "") for p in pols.get("branch_policies", [])] + except Exception: # noqa: BLE001 + names = None + return "ok", env, names + + +def evaluate(role_arn: str | None, env_state: str, env: dict[str, Any] | None, + branch_policies: list[str] | None) -> tuple[list[str], list[str]]: + """(problems, notes) for one run; pure, for tests.""" + problems = check_variable(role_arn) + notes = [] + if env_state == "unreadable": + notes.append(f"the {ENVIRONMENT} environment could not be read with the job token; not observed " + "(the incident-publisher job still fails the deploy if the role cannot be assumed from it)") + else: + p, note = check_environment(env if env_state == "ok" else None, branch_policies) + problems += p + if note: + notes.append(note) + return problems, notes + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("--fixture", default=None, + help="JSON {role_arn, env_state, environment, branch_policies} instead of live reads (tests)") + a = ap.parse_args(argv) + if a.fixture: + with open(a.fixture) as fh: + fx = json.load(fh) + problems, notes = evaluate(fx.get("role_arn"), fx["env_state"], fx.get("environment"), + fx.get("branch_policies")) + else: + state, env, pols = read_environment(os.environ.get("GITHUB_REPOSITORY", "sam-aydlette/samaydlette.com"), + os.environ.get("GITHUB_TOKEN")) + problems, notes = evaluate(os.environ.get("INCIDENT_REPORTS_ROLE_ARN"), state, env, pols) + for n in notes: + print(f"incident publisher preflight: {n}") + for p in problems: + print(f"::error::incident publisher preflight: {p}") + if not problems: + print("incident publisher preflight: role variable names the incident-reports role; ok") + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/reconcile.py b/scripts/reconcile.py index 5f187a81..402194d3 100644 --- a/scripts/reconcile.py +++ b/scripts/reconcile.py @@ -42,6 +42,10 @@ # every boundary component of the inventory (no more, no # fewer), leaves none unclassified, and carries no ARN, # account ID or email address +# (m) incident findings — every finding or CVE an unresolved incident in the +# incident register (data/incidents.json) names is in +# this build's VDR report; exercises are exempt (their +# findings are simulated) # # Usage: # reconcile.py --artifacts-dir infrastructure [--live] [--expect-commit SHA] @@ -64,6 +68,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import _decisions # noqa: E402 import _gates # noqa: E402 +import _incidents # noqa: E402 import _redact # noqa: E402 REPO = Path(__file__).resolve().parent.parent @@ -525,9 +530,26 @@ def check_l_boundary_map(signal, boundary_map, expected_commit=None): return violations +def check_m_incident_findings(vdr, incidents): + """(m) Every finding an unresolved, non-exercise incident names (a VDR + tracking ID or a CVE ID) is in this build's VDR report. An incident about a + vulnerability the VDR does not carry is reporting on something the + vulnerability evidence says is not there: one of the two is wrong.""" + if incidents is None: + return [] + ids, cves = set(), set() + for f in _all_vdr_findings(vdr): + ids.add(f.get("tracking_id")) + if f.get("cve"): + cves.add(f["cve"]) + return [f"(m) incident {inc_id} names {ref!r}, which is not in the VDR report" + for ref, inc_id in sorted(_incidents.open_findings(incidents).items()) + if ref not in ids and ref not in cves] + + def run_all(signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, live_arns=None, expected_commit=None, live_tags=None, - boundary_map=None): + boundary_map=None, incidents=None): violations = [] violations += check_d_impact(signal, sdr, cpo, vdr, dashboard_html) violations += check_e_binding(signal, sdr, cpo, vdr) @@ -537,6 +559,7 @@ def run_all(signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, violations += check_h_finding_coverage(vdr, register) violations += check_j_decision_id_validity(signal, sdr, cpo, vdr, register) violations += check_l_boundary_map(signal, boundary_map, expected_commit) + violations += check_m_incident_findings(vdr, incidents) if live_arns is not None: violations += check_a_completeness(signal, live_arns) if live_tags is not None: @@ -562,6 +585,8 @@ def main(): help="path to .checkov.yaml (overridable for hermetic tests)") ap.add_argument("--decisions", default=str(_decisions.DEFAULT_PATH), help="the decision register (overridable for hermetic tests); missing or invalid fails closed") + ap.add_argument("--incidents", default=str(_incidents.DEFAULT_PATH), + help="the incident register (overridable for hermetic tests); missing or invalid fails closed") args = ap.parse_args() gates = _gates.load_gate_modes() @@ -583,6 +608,7 @@ def main(): dashboard_html = Path(args.dashboard).read_text() if Path(args.dashboard).exists() else None checkov_text = Path(args.checkov).read_text() register = _decisions.load(args.decisions) + incidents = _incidents.load(args.incidents) live_arns = None live_tags = None @@ -617,7 +643,7 @@ def main(): violations = run_all( signal, sdr, cpo, vdr, dashboard_html, checkov_text, register, live_arns=live_arns, expected_commit=args.expect_commit, live_tags=live_tags, - boundary_map=boundary_map, + boundary_map=boundary_map, incidents=incidents, ) # Each violation names its invariant, "(x) ..."; its check's governed mode @@ -638,12 +664,12 @@ def main(): return 1 optional = ",l" if boundary_map is not None else "" if live_arns is not None and live_tags is not None: - checks = "a-f,h-j" + optional + checks = "a-f,h-j" + optional + ",m" elif live_arns is not None: - checks = "a-f,h,j" + optional + " (i deferred: no live tags)" + checks = "a-f,h,j" + optional + ",m (i deferred: no live tags)" else: - checks = "b-f,h,j" + optional + " (a,i deferred: no --live)" - print(f"reconciliation OK — invariants {checks} hold across signal/VDR/SDR/CPO/decisions/dashboard") + checks = "b-f,h,j" + optional + ",m (a,i deferred: no --live)" + print(f"reconciliation OK — invariants {checks} hold across signal/VDR/SDR/CPO/decisions/incidents/dashboard") if args.report: Path(args.report).write_text(json.dumps(build_report( signal, args.expect_commit, @@ -666,6 +692,7 @@ def main(): "j": "Every decision reference resolves", # (k) is retired: the bundle it bound is no longer published by this site. "l": "The boundary map describes exactly this build's inventory", + "m": "Every finding an open incident names is in the VDR report", } diff --git a/tests/fixtures/incidents/bad/duplicate-id.json b/tests/fixtures/incidents/bad/duplicate-id.json new file mode 100644 index 00000000..54fc3da0 --- /dev/null +++ b/tests/fixtures/incidents/bad/duplicate-id.json @@ -0,0 +1,74 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: two incidents share an ID", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + }, + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/empty-reason.json b/tests/fixtures/incidents/bad/empty-reason.json new file mode 100644 index 00000000..db9cbf11 --- /dev/null +++ b/tests/fixtures/incidents/bad/empty-reason.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the reportability determination states no reason", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": " ", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/evaluated-before-detected.json b/tests/fixtures/incidents/bad/evaluated-before-detected.json new file mode 100644 index 00000000..84050cc7 --- /dev/null +++ b/tests/fixtures/incidents/bad/evaluated-before-detected.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the evaluation is dated before detection", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T09:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/final-before-recovery.json b/tests/fixtures/incidents/bad/final-before-recovery.json new file mode 100644 index 00000000..8b094b83 --- /dev/null +++ b/tests/fixtures/incidents/bad/final-before-recovery.json @@ -0,0 +1,53 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a Final report with no recovery recorded", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Final", + "at": "2026-11-02T12:00:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/final-not-last.json b/tests/fixtures/incidents/bad/final-not-last.json new file mode 100644 index 00000000..67d2550e --- /dev/null +++ b/tests/fixtures/incidents/bad/final-not-last.json @@ -0,0 +1,62 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report follows the Final report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Final", + "at": "2026-11-02T12:00:00Z", + "set": { + "root_cause": "x" + } + }, + { + "type": "Ongoing", + "at": "2026-11-02T13:00:00Z", + "set": { + "root_cause": "y" + } + } + ], + "resolved_at": "2026-11-02T11:00:00Z", + "recovery_complete_at": "2026-11-02T11:10:00Z" + } + ] +} diff --git a/tests/fixtures/incidents/bad/first-not-initial.json b/tests/fixtures/incidents/bad/first-not-initial.json new file mode 100644 index 00000000..9dd86033 --- /dev/null +++ b/tests/fixtures/incidents/bad/first-not-initial.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the first report is not the Initial report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Ongoing", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/future-report.json b/tests/fixtures/incidents/bad/future-report.json new file mode 100644 index 00000000..e4e76502 --- /dev/null +++ b/tests/fixtures/incidents/bad/future-report.json @@ -0,0 +1,53 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report is dated after now (the test runs with now = 2026-11-03)", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + }, + { + "type": "Ongoing", + "at": "2026-11-04T00:00:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/initial-without-description.json b/tests/fixtures/incidents/bad/initial-without-description.json new file mode 100644 index 00000000..e50f60d6 --- /dev/null +++ b/tests/fixtures/incidents/bad/initial-without-description.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the Initial report does not describe the incident", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "root_cause": "x" + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/not-evaluated.json b/tests/fixtures/incidents/bad/not-evaluated.json new file mode 100644 index 00000000..5814ef50 --- /dev/null +++ b/tests/fixtures/incidents/bad/not-evaluated.json @@ -0,0 +1,45 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the incident has no reportability reason (IEC-CSO-EFR)", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/not-reportable-with-report.json b/tests/fixtures/incidents/bad/not-reportable-with-report.json new file mode 100644 index 00000000..bff5c9f1 --- /dev/null +++ b/tests/fixtures/incidents/bad/not-reportable-with-report.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an incident evaluated as not reportable carries a report", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": false, + "basis": "IEC-CSO-EFR", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/notification-sends.json b/tests/fixtures/incidents/bad/notification-sends.json new file mode 100644 index 00000000..1e40df8f --- /dev/null +++ b/tests/fixtures/incidents/bad/notification-sends.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the policy claims a delivery mode that is not built", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "email", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/personal-email.json b/tests/fixtures/incidents/bad/personal-email.json new file mode 100644 index 00000000..b1bdd4c1 --- /dev/null +++ b/tests/fixtures/incidents/bad/personal-email.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a published field names a personal email address", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "someone@example.org", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/rating-off-rubric.json b/tests/fixtures/incidents/bad/rating-off-rubric.json new file mode 100644 index 00000000..a40bbe99 --- /dev/null +++ b/tests/fixtures/incidents/bad/rating-off-rubric.json @@ -0,0 +1,54 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an estimate's rating is not the IEC-CSO-EFI rating for its effect and agency count", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [ + { + "estimated_at": "2026-11-02T11:00:00Z", + "rating": 2, + "customer_effect": "disruptive", + "agencies": "single", + "reason": "x" + } + ], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/report-before-evaluation.json b/tests/fixtures/incidents/bad/report-before-evaluation.json new file mode 100644 index 00000000..b1bee965 --- /dev/null +++ b/tests/fixtures/incidents/bad/report-before-evaluation.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a report is dated before the evaluation", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T09:45:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/unknown-field.json b/tests/fixtures/incidents/bad/unknown-field.json new file mode 100644 index 00000000..6cf3e552 --- /dev/null +++ b/tests/fixtures/incidents/bad/unknown-field.json @@ -0,0 +1,47 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: an incident carries a field the register does not define", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ], + "severity": "high" + } + ] +} diff --git a/tests/fixtures/incidents/bad/vuln-basis-no-finding.json b/tests/fixtures/incidents/bad/vuln-basis-no-finding.json new file mode 100644 index 00000000..03de43ae --- /dev/null +++ b/tests/fixtures/incidents/bad/vuln-basis-no-finding.json @@ -0,0 +1,44 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: a VER-TFR-IRI incident names no finding", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json b/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json new file mode 100644 index 00000000..2cb36efc --- /dev/null +++ b/tests/fixtures/incidents/bad/vuln-basis-not-adopted.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE: the basis is VER-TFR-NRI, which the policy has not adopted", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-NRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/good.json b/tests/fixtures/incidents/good.json new file mode 100644 index 00000000..55c20493 --- /dev/null +++ b/tests/fixtures/incidents/good.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-GOOD FIXTURE: a minimal valid incident register (one open, reportable, non-exercise incident).", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-0001" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/fixtures/incidents/preflight-good.json b/tests/fixtures/incidents/preflight-good.json new file mode 100644 index 00000000..c7738649 --- /dev/null +++ b/tests/fixtures/incidents/preflight-good.json @@ -0,0 +1,7 @@ +{ + "_comment": "Good: variable names the incident-reports role (example account), environment deploys only from main.", + "role_arn": "arn:aws:iam::000000000000:role/github-actions-incident-reports-oidc", + "env_state": "ok", + "environment": {"name": "incident-reports", "deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}, + "branch_policies": ["main"] +} diff --git a/tests/fixtures/incidents/preflight-missing-variable.json b/tests/fixtures/incidents/preflight-missing-variable.json new file mode 100644 index 00000000..6ce86a33 --- /dev/null +++ b/tests/fixtures/incidents/preflight-missing-variable.json @@ -0,0 +1,7 @@ +{ + "_comment": "Known-bad: the repository variable AWS_INCIDENT_REPORTS_ROLE_ARN is unset; the environment is correct. check-incident-publisher.py must fail for the variable alone.", + "role_arn": "", + "env_state": "ok", + "environment": {"name": "incident-reports", "deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}, + "branch_policies": ["main"] +} diff --git a/tests/fixtures/incidents/reconcile-m-bad.json b/tests/fixtures/incidents/reconcile-m-bad.json new file mode 100644 index 00000000..5c830fee --- /dev/null +++ b/tests/fixtures/incidents/reconcile-m-bad.json @@ -0,0 +1,46 @@ +{ + "$comment": "KNOWN-BAD FIXTURE for reconcile invariant (m): an open incident names CVE-2099-9999, which the VDR report fixture does not carry.", + "schema": "incidents/1", + "policy": { + "federal_incident_coordinator": "Test coordinator; contact through https://samaydlette.com/.well-known/security.txt", + "notification": "published-only", + "notification_text": "Published only (test fixture).", + "adopted_vulnerability_rules": [ + "VER-TFR-IRI" + ], + "federal_customer_data": "Test fixture.", + "decided_by": "Operator", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + "incidents": [ + { + "id": "INC-2026-101", + "title": "Fixture incident", + "exercise": false, + "started_at": "2026-11-02T09:00:00Z", + "detected_at": "2026-11-02T09:30:00Z", + "detection_source": "test", + "evaluation": { + "evaluated_at": "2026-11-02T10:00:00Z", + "reportable": true, + "basis": "VER-TFR-IRI", + "reason": "Fixture: an internet-reachable LEV at N4.", + "federal_customer_data_considered": "Fixture." + }, + "findings": [ + "CVE-2099-9999" + ], + "estimates": [], + "reports": [ + { + "type": "Initial", + "at": "2026-11-02T10:30:00Z", + "set": { + "description": "Fixture description." + } + } + ] + } + ] +} diff --git a/tests/test_evidence_watchdog.py b/tests/test_evidence_watchdog.py index 0bdd0e27..9ae0184d 100644 --- a/tests/test_evidence_watchdog.py +++ b/tests/test_evidence_watchdog.py @@ -55,6 +55,7 @@ def fresh_objects(): node[leaf] = FRESH objects[a["path"]] = doc objects[".well-known/vdr-status.json"] = status() + objects[".well-known/incident-reports.json"]["obligations_due"] = [] return objects @@ -287,3 +288,39 @@ def test_alarm_thresholds_and_reads_come_from_the_governed_config(): # No window is a literal in the watchdog any more. assert "MAX_BEACON_AGE_HOURS" not in logic assert not re.search(r"threshold\s*=\s*(24|26)\b", tf) + + +# ---- incident report deadlines (IEC-CSO-IIR/OIR/FIR) -------------------------------- + +def _incident_log(*due): + return {"emitted_at": FRESH, "obligations_due": [{"incident": "INC-2026-009", "report": "Ongoing", + "due_at": d} for d in due]} + + +def test_no_report_due_pages_nobody(): + out = compute(fresh_objects()) + assert out["metrics"]["IncidentReportsOverdue"] == 0 + + +def test_a_report_past_its_deadline_pages_even_while_the_log_is_fresh(): + objects = fresh_objects() + # NOW is 12:00. One report due at 11:00 has not been issued; one due at 13:00 is not late yet. + objects[".well-known/incident-reports.json"] = _incident_log("2026-09-25T11:00:00Z", "2026-09-25T13:00:00Z") + out = compute(objects) + assert out["metrics"]["IncidentReportsOverdue"] == 1 + assert out["metrics"]["StaleArtifacts"] == 0 + + +def test_a_missing_or_malformed_incident_log_is_a_breach_not_zero(): + objects = fresh_objects() + objects[".well-known/incident-reports.json"] = {"emitted_at": FRESH} + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + objects[".well-known/incident-reports.json"] = _incident_log("not a date") + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + del objects[".well-known/incident-reports.json"] + assert compute(objects)["metrics"]["IncidentReportsOverdue"] == 1 + + +def test_the_incident_alarm_pages_on_the_first_overdue_report(): + tf = (REPO / "infrastructure" / "watchdog.tf").read_text() + assert 'metric = "IncidentReportsOverdue"\n threshold = 0' in tf diff --git a/tests/test_incidents.py b/tests/test_incidents.py new file mode 100644 index 00000000..36cc70ba --- /dev/null +++ b/tests/test_incidents.py @@ -0,0 +1,562 @@ +"""Incident evaluation and reporting (IEC-CSO-EFR/DPR/EFI/IIR/OIR/FIR/AIR, +VER-TFR-IRI, VER-TFR-NRI). + +- the register (data/incidents.json) loads, matches its schema, and every + known-bad register fails closed for its own reason; +- the Class C report clocks and the Incident Rating scale are read from the + pinned FedRAMP rules, and a changed rule fails closed; +- the clocks: default N5 until estimated (DPR), the IIR/OIR/FIR deadlines, + business days, overdue detection; +- the exercise runs end to end, IIR -> OIR -> FIR, every report validates + against FedRAMP's schema, restates every earlier item and was on time; +- a VDR finding that VER-TFR-IRI/NRI makes reportable with no incident is due + an Initial report, and the clock check fails once it is late; +- reconciliation invariant (m) and the unattended reporting workflow. +""" + +import copy +import hashlib +import importlib.util +import json +import re +import shutil +import sys +from datetime import datetime, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO / "scripts")) +import _fedramp_schema as fs # noqa: E402 +import _incidents # noqa: E402 +import _rules # noqa: E402 + +FIX = REPO / "tests" / "fixtures" / "incidents" +REGISTER = REPO / "data" / "incidents.json" +SCHEMA = REPO / "infrastructure" / "schemas" / "incidents.schema.json" +RULES_DIR = REPO / "infrastructure" / "schemas" / "fedramp-rules" +WF = REPO / ".github" / "workflows" +NOW = datetime(2026, 11, 3, tzinfo=timezone.utc) + + +def _load(name, rel): + spec = importlib.util.spec_from_file_location(name, REPO / rel) + m = importlib.util.module_from_spec(spec) + spec.loader.exec_module(m) + return m + + +bir = _load("bir", "scripts/build-incident-report.py") +rec = _load("rec_incidents", "scripts/reconcile.py") + + +def ts(s): + return datetime.fromisoformat(s.replace("Z", "+00:00")) + + +def good(): + return json.loads((FIX / "good.json").read_text()) + + +# ---- the register ---------------------------------------------------------------- + +def test_the_committed_register_loads_and_matches_its_schema(): + _incidents.load(REGISTER, now=datetime.now(timezone.utc)) + jsonschema = pytest.importorskip("jsonschema") + jsonschema.validate(json.loads(REGISTER.read_text()), json.loads(SCHEMA.read_text())) + jsonschema.validate(good(), json.loads(SCHEMA.read_text())) + + +def test_the_committed_register_adopts_both_vulnerability_rules_and_publishes_only(): + """docs/policies/ir-policy.md adopts VER-TFR-NRI (a MAY) and IRI; nothing is sent.""" + p = json.loads(REGISTER.read_text())["policy"] + assert set(p["adopted_vulnerability_rules"]) == {"VER-TFR-IRI", "VER-TFR-NRI"} + assert p["notification"] == "published-only" + assert "not authorized" in p["notification_text"] + + +BAD = { + "not-evaluated": "evaluation must have exactly", + "empty-reason": "reason must be a non-empty string", + "rating-off-rubric": "is N3 under IEC-CSO-EFI", + "first-not-initial": "first report is the Initial Incident Report", + "initial-without-description": "must describe the incident", + "final-before-recovery": "needs resolved_at and recovery_complete_at", + "final-not-last": "nothing follows the Final Incident Report", + "not-reportable-with-report": "carries no rating or report", + "vuln-basis-not-adopted": "is not an adopted rule", + "vuln-basis-no-finding": "names no finding", + "evaluated-before-detected": "evaluated before it was detected", + "report-before-evaluation": "before the evaluation or the previous report", + "notification-sends": "no other delivery is built", + "personal-email": "names an email address outside", + "unknown-field": "unknown field", + "duplicate-id": "duplicate id", + "future-report": "records a time after now", +} + + +def test_every_known_bad_fixture_is_listed(): + assert {p.stem for p in (FIX / "bad").glob("*.json")} == set(BAD) + + +@pytest.mark.parametrize("name,why", sorted(BAD.items())) +def test_each_known_bad_register_fails_closed_for_its_reason(name, why): + _incidents.load(FIX / "good.json", now=NOW) # the base it was made from is valid + with pytest.raises(SystemExit) as exc: + _incidents.load(FIX / "bad" / f"{name}.json", now=NOW) + assert why in str(exc.value), str(exc.value) + + +@pytest.mark.parametrize("name", ["not-evaluated", "empty-reason", "notification-sends", "unknown-field"]) +def test_the_schema_refuses_the_structural_ones(name): + jsonschema = pytest.importorskip("jsonschema") + with pytest.raises(jsonschema.ValidationError): + jsonschema.validate(json.loads((FIX / "bad" / f"{name}.json").read_text()), json.loads(SCHEMA.read_text())) + + +def test_a_missing_or_unparseable_register_fails_closed(tmp_path): + with pytest.raises(SystemExit): + _incidents.load(tmp_path / "absent.json") + (tmp_path / "x.json").write_text("{") + with pytest.raises(SystemExit): + _incidents.load(tmp_path / "x.json") + + +# ---- rules as data -------------------------------------------------------------- + +def _corpus(): + return json.loads((RULES_DIR / "fedramp-consolidated-rules.json").read_text()) + + +def test_report_clocks_equal_the_pinned_rules(): + cso = _corpus()["FRR"]["IEC"]["data"]["all"]["CSO"] + got = _rules.incident_report_timeframes(RULES_DIR) + for kind, rid in (("iir", "IEC-CSO-IIR"), ("oir", "IEC-CSO-OIR"), ("fir", "IEC-CSO-FIR")): + table = cso[rid]["varies_by_class"]["c"]["pain_timeframes"] + assert got[kind] == {int(n): (c[kind]["timeframe_type"], c[kind]["timeframe_num"]) for n, c in table.items()} + # The Class C values the reports rely on, as published on 2026-06-24. + assert got["iir"][5] == ("hours", 1) and got["oir"][5] == ("hours", 6) and got["fir"][1] == ("bizdays", 1) + + +def test_rating_scale_and_default_come_from_the_rules(): + rubric = _rules.incident_rating_rubric(RULES_DIR) + assert rubric[("debilitating", "multiple")] == 5 and rubric[("disruptive", "multiple")] == 4 + assert rubric[("debilitating", "single")] == 4 and rubric[("minimal", "single")] == 1 + assert _rules.default_incident_rating(RULES_DIR) == 5 + + +def test_no_clock_is_typed_into_the_incident_code(): + for rel in ("scripts/_incidents.py", "scripts/build-incident-report.py"): + src = (REPO / rel).read_text() + assert not re.search(r"timedelta\(hours=(1|6|24)\)", src), rel + + +def _mutated_rules(tmp_path, mutate): + d = tmp_path / "rules" + d.mkdir() + corpus = _corpus() + mutate(corpus) + raw = json.dumps(corpus).encode() + (d / "fedramp-consolidated-rules.json").write_bytes(raw) + src = json.loads((RULES_DIR / "SOURCES.json").read_text()) + src["sha256"] = hashlib.sha256(raw).hexdigest() + (d / "SOURCES.json").write_text(json.dumps(src)) + return d + + +def test_a_changed_rating_scale_fails_closed(tmp_path): + def drop(c): + c["FRR"]["IEC"]["data"]["all"]["CSO"]["IEC-CSO-EFI"]["following_information_bullets"].pop() + with pytest.raises(SystemExit, match="does not rate every customer effect"): + _rules.incident_rating_rubric(_mutated_rules(tmp_path, drop)) + + +def test_a_missing_report_clock_fails_closed(tmp_path): + def drop(c): + c["FRR"]["IEC"]["data"]["all"]["CSO"]["IEC-CSO-OIR"]["varies_by_class"]["c"]["pain_timeframes"]["5"] = {} + with pytest.raises(SystemExit, match="IEC-CSO-OIR Class C N5 oir"): + _rules.incident_report_timeframes(_mutated_rules(tmp_path, drop)) + + +# ---- clocks (IEC-CSO-DPR, IIR, OIR, FIR) ------------------------------------------ + +TF = _rules.incident_report_timeframes(RULES_DIR) + + +def _open(evaluated="2026-11-02T10:00:00Z", reports=(), estimates=()): + inc = copy.deepcopy(good()["incidents"][0]) + inc["evaluation"]["evaluated_at"] = evaluated + inc["reports"] = list(reports) + inc["estimates"] = list(estimates) + return inc + + +def test_an_unrated_incident_is_n5_and_its_initial_report_is_due_in_an_hour(): + inc = _open() + assert _incidents.rating_at(inc, ts("2026-11-02T10:00:00Z"), 5) == (5, "default (IEC-CSO-DPR)") + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-02T10:30:00Z")) + assert o["report"] == "Initial" and o["due_at"] == "2026-11-02T11:00:00+00:00" and not o["overdue"] + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-02T11:01:00Z")) + assert o["overdue"] + + +def test_a_prompt_estimate_replaces_the_default_and_its_clock(): + est = {"estimated_at": "2026-11-06T10:00:00Z", "rating": 1, "customer_effect": "minimal", + "agencies": "single", "reason": "x"} + # Evaluated on a Friday, rated N1 at once: one business day, so Monday. + inc = _open(evaluated="2026-11-06T10:00:00Z", estimates=[est]) + (o,) = _incidents.obligations(inc, TF, 5, ts("2026-11-06T12:00:00Z")) + assert o["due_at"] == "2026-11-09T10:00:00+00:00" + + +def test_business_days_skip_the_weekend(): + assert _incidents.add_clock(ts("2026-11-06T23:00:00Z"), "bizdays", 1) == ts("2026-11-09T23:00:00Z") + assert _incidents.add_clock(ts("2026-11-04T08:00:00Z"), "bizdays", 1) == ts("2026-11-05T08:00:00Z") + + +def test_ongoing_reports_are_due_every_oir_period_until_resolved(): + reports = [{"type": "Initial", "at": "2026-11-02T10:30:00Z", "set": {"description": "d"}}] + obs = _incidents.obligations(_open(reports=reports), TF, 5, ts("2026-11-02T17:00:00Z")) + assert [o["report"] for o in obs] == ["Initial", "Ongoing"] + assert obs[1]["due_at"] == "2026-11-02T16:30:00+00:00" and obs[1]["overdue"] + + +def test_the_final_report_is_due_after_recovery_and_ongoing_reports_stop(): + inc = _open(reports=[{"type": "Initial", "at": "2026-11-02T10:30:00Z", "set": {"description": "d"}}]) + inc["resolved_at"], inc["recovery_complete_at"] = "2026-11-02T12:00:00Z", "2026-11-02T13:00:00Z" + obs = _incidents.obligations(inc, TF, 5, ts("2026-11-02T20:00:00Z")) + assert [o["report"] for o in obs] == ["Initial", "Final"] + assert obs[1]["due_at"] == "2026-11-02T19:00:00+00:00" and obs[1]["overdue"] + + +def test_a_not_reportable_incident_has_no_clock(): + inc = _open() + inc["evaluation"]["reportable"] = False + assert _incidents.obligations(inc, TF, 5, NOW) == [] + + +# ---- the exercise, end to end (IIR -> OIR -> FIR) --------------------------------- + +@pytest.fixture(scope="module") +def exercise(tmp_path_factory): + out = tmp_path_factory.mktemp("incident-reports") + reg = _incidents.load(REGISTER, now=ts("2026-11-05T19:00:00Z")) + log = bir.build(reg, None, ts("2026-11-05T19:00:00Z"), out) + return reg, log, out + + +def test_exercise_runs_initial_ongoing_final_all_on_time(exercise): + _, log, _ = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-001") + assert inc["exercise"] is True and inc["status"] == "closed" + assert [r["type"] for r in inc["reports"]] == ["Initial", "Ongoing", "Ongoing", "Final"] + assert [o["report"] for o in inc["obligations"]] == ["Initial", "Ongoing", "Ongoing", "Final"] + assert all(o["on_time"] for o in inc["obligations"]) + assert log["obligations_due"] == [] and log["clock_status"] == "ok" + + +def test_exercise_shows_the_default_rating_then_the_estimate(exercise): + _, log, out = exercise + initial = json.loads((out / "incident-INC-2026-001-01-initial.json").read_text()) + final = json.loads((out / "incident-INC-2026-001-04-final.json").read_text()) + assert initial["potentialImpact"]["currentRating"] == 5 + assert "IEC-CSO-DPR" in initial["potentialImpact"]["evaluationNotes"] + assert final["potentialImpact"]["historicalRating"] == [5, 3] and final["potentialImpact"]["currentRating"] == 3 + assert initial["incidentDescription"].startswith("EXERCISE") + + +def test_exercise_logs_a_not_reportable_evaluation_with_its_reason(exercise): + _, log, _ = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-002") + assert inc["status"] == "not-reportable" and inc["reports"] == [] and inc["rating"] is None + assert "not federal customer data" in inc["evaluation"]["reason"] + + +def test_every_report_validates_against_fedramps_schema_and_is_listed_with_its_hash(exercise): + _, log, out = exercise + files = sorted(p.name for p in out.glob("incident-INC-*.json")) + listed = [r for i in log["incidents"] for r in i["reports"]] + assert sorted(r["file"] for r in listed) == files + for r in listed: + doc = json.loads((out / r["file"]).read_text()) + assert fs.validate(doc, "incident") == [] + assert hashlib.sha256((out / r["file"]).read_bytes()).hexdigest() == r["sha256"] + + +def test_ongoing_and_final_reports_restate_every_earlier_item(exercise): + _, log, out = exercise + inc = next(i for i in log["incidents"] if i["id"] == "INC-2026-001") + first = json.loads((out / inc["reports"][0]["file"]).read_text()) + for r in inc["reports"][1:]: + doc = json.loads((out / r["file"]).read_text()) + assert set(first) <= set(doc), r["file"] + # Every item is either updated or explicitly "no update". + assert set(r["changes"].values()) <= {"updated", "no update"}, r["changes"] + assert inc["reports"][2]["changes"]["root_cause"] == "no update" + assert inc["reports"][2]["changes"]["response_and_recovery_activities"] == "updated" + final = json.loads((out / inc["reports"][-1]["file"]).read_text()) + assert final["reportType"] == "Final" and final["resolvedAt"] == "2026-11-05T17:00:00Z" + + +def test_reports_are_deterministic_and_say_they_are_published_only(exercise, tmp_path): + reg, log, out = exercise + again = bir.build(reg, None, ts("2026-11-05T19:30:00Z"), tmp_path) + for a, b in zip(log["incidents"], again["incidents"], strict=True): + assert [r["sha256"] for r in a["reports"]] == [r["sha256"] for r in b["reports"]] + md = (out / "incident-reports.md").read_text() + assert "published-only" in md and "not authorized" in md and "(no update)" in md + assert log["notification"]["mode"] == "published-only" + + +def test_the_cli_builds_and_checks(tmp_path): + assert bir.main(["--incidents", str(REGISTER), "--out-dir", str(tmp_path), + "--now", "2026-11-05T19:00:00Z"]) == 0 + assert bir.main(["--check", str(tmp_path / "incident-reports.json"), "--now", "2026-11-05T19:00:00Z"]) == 0 + + +# ---- vulnerabilities as incidents (VER-TFR-IRI / VER-TFR-NRI) ---------------------- + +pytestmark_opa = pytest.mark.skipif(shutil.which("opa") is None, reason="opa not available") + + +def _vdr(**patch): + f = {"tracking_id": "grype-CVE-2099-0777-api", "cve": "CVE-2099-0777", "pain": "N4", + "internet_reachable": True, "likely_exploitable": True, "fully_mitigated": False, + "final_disposition": "open", "first_evaluated": "2026-11-02T10:00:00+00:00"} + f.update(patch) + return {"emitted_at": "2026-11-02T12:00:00+00:00", "report_id": "r", "findings": [f]} + + +def _empty_register(adopted=("VER-TFR-IRI", "VER-TFR-NRI")): + reg = good() + reg["incidents"] = [] + reg["policy"]["adopted_vulnerability_rules"] = list(adopted) + return _incidents.validate(reg) + + +@pytestmark_opa +def test_an_irv_lev_n4_finding_with_no_incident_is_due_an_initial_report(tmp_path): + log = bir.build(_empty_register(), _vdr(), ts("2026-11-02T10:30:00Z"), tmp_path) + (t,) = log["vulnerability_triggers"] + assert t["rule"] == "VER-TFR-IRI" and t["adopted"] and t["incident"] is None + (d,) = log["obligations_due"] + assert d["report"] == "Initial" and d["due_at"] == "2026-11-02T11:00:00+00:00" and not d["overdue"] + assert bir.check(tmp_path / "incident-reports.json", ts("2026-11-02T10:59:00Z")) == 0 + assert bir.check(tmp_path / "incident-reports.json", ts("2026-11-02T11:01:00Z")) == 1 + + +@pytestmark_opa +def test_an_nirv_lev_n5_finding_opens_under_nri_and_n4_does_not(tmp_path): + log = bir.build(_empty_register(), _vdr(internet_reachable=False, pain="N5"), NOW, tmp_path) + assert log["vulnerability_triggers"][0]["rule"] == "VER-TFR-NRI" + log = bir.build(_empty_register(), _vdr(internet_reachable=False, pain="N4"), NOW, tmp_path) + assert log["vulnerability_triggers"] == [] + + +@pytestmark_opa +def test_a_partially_mitigated_finding_at_n3_is_no_longer_an_incident(tmp_path): + log = bir.build(_empty_register(), _vdr(pain="N3"), NOW, tmp_path) + assert log["vulnerability_triggers"] == [] and log["obligations_due"] == [] + + +@pytestmark_opa +def test_an_unadopted_rule_is_shown_but_starts_no_clock(tmp_path): + log = bir.build(_empty_register(adopted=("VER-TFR-IRI",)), _vdr(internet_reachable=False, pain="N5"), + NOW, tmp_path) + assert log["vulnerability_triggers"][0]["adopted"] is False and log["obligations_due"] == [] + + +@pytestmark_opa +def test_an_open_incident_naming_the_finding_covers_it(tmp_path): + reg = good() + reg["incidents"][0]["findings"] = ["CVE-2099-0777"] + log = bir.build(_incidents.validate(reg), _vdr(), ts("2026-11-02T10:40:00Z"), tmp_path) + assert log["vulnerability_triggers"][0]["incident"] == "INC-2026-101" + assert [d["incident"] for d in log["obligations_due"]] == ["INC-2026-101"] # its next Ongoing report + + +# ---- reconciliation (m) ---------------------------------------------------------- + +def _cr26_vdr(): + return json.loads((REPO / "tests" / "fixtures" / "cr26" / "vdr-report.json").read_text()) + + +def test_reconcile_m_passes_when_every_named_finding_is_in_the_vdr(): + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(good())) == [] + + +def test_reconcile_m_fails_the_known_bad_register(): + reg = _incidents.load(FIX / "reconcile-m-bad.json") + v = rec.check_m_incident_findings(_cr26_vdr(), reg) + assert v == ["(m) incident INC-2026-101 names 'CVE-2099-9999', which is not in the VDR report"] + + +def test_reconcile_m_exempts_exercises_and_resolved_incidents(): + reg = json.loads((FIX / "reconcile-m-bad.json").read_text()) + reg["incidents"][0]["exercise"] = True + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(reg)) == [] + reg["incidents"][0]["exercise"] = False + reg["incidents"][0]["resolved_at"] = "2026-11-02T11:00:00Z" + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.validate(reg)) == [] + + +def test_reconcile_m_holds_for_the_committed_register(): + assert rec.check_m_incident_findings(_cr26_vdr(), _incidents.load(REGISTER)) == [] + + +# ---- the unattended reporting workflow (IEC-CSO-AIR) -------------------------------- + +def _wf(): + return (WF / "incident-reports.yml").read_text() + + +def test_air_workflow_runs_on_register_change_by_hand_and_on_a_schedule(): + yaml = pytest.importorskip("yaml") + on = yaml.safe_load(_wf())[True] + assert on["push"]["paths"] == ["data/incidents.json"] and on["push"]["branches"] == ["main"] + assert "workflow_dispatch" in on and on["schedule"] + + +def test_air_workflow_validates_builds_signs_publishes_and_checks_the_clock_in_order(): + names = re.findall(r"^ - name: (.+)$", _wf(), re.M) + order = ["Fetch and verify the published VDR report", "Build incident reports (IIR, OIR, FIR)", + "Sign incident reports", "Publication redaction gate (no AWS account ID)", + "Publish incident reports to /.well-known/", + "Incident report clocks (fail when a report is due and missing)"] + assert [n for n in names if n in order] == order + + +def test_air_workflow_writes_only_incident_objects_and_sends_nothing(): + text = _wf() + keys = re.findall(r'--key "\.well-known/([^"]+)"', text) + assert keys == ["$1"] + puts = [p.strip('"') for p in re.findall(r"^\s*put (\S+) ", text, re.M)] + assert puts and all(p.startswith(("incident-", "$f", "${f")) for p in puts), puts + assert "for f in incident-INC-*.json; do" in text + assert "environment: incident-reports" in text and "AWS_INCIDENT_REPORTS_ROLE_ARN" in text + assert not re.search(r"\b(ses|sendmail|send-email|smtp)\b", text, re.I) + assert "aws s3 sync" not in text and "aws s3 rm" not in text and not re.search(r"^\s*terraform ", text, re.M) + + +def test_air_role_is_scoped_to_incident_objects(): + tf = (REPO / "infrastructure" / "bootstrap" / "incident-reports.tf").read_text() + assert '"arn:aws:s3:::${var.domain_name}/.well-known/incident-*"' in tf + actions = set(re.findall(r'"((?:s3|cloudfront):[A-Za-z*]+)"', tf)) + assert actions == {"s3:PutObject", "cloudfront:CreateInvalidation"} + assert 'environment:${var.incident_reports_environment}' in tf + + +def test_all_three_workflows_pin_the_same_opa(): + def pins(name): + text = (WF / name).read_text() + return {k: re.search(rf"^ {k}: (\S+)", text, re.M).group(1) for k in ("OPA_VERSION", "OPA_SHA256")} + assert pins("incident-reports.yml") == pins("deploy-with-opa.yml") == pins("evidence-nightly.yml") + + +# ---- deploy preflight and proof of the publisher (the records hold once deployed) ---- + +preflight = _load("preflight", "scripts/check-incident-publisher.py") +ENV_OK = {"name": "incident-reports", + "deployment_branch_policy": {"protected_branches": False, "custom_branch_policies": True}} +ARN_OK = "arn:aws:iam::000000000000:role/github-actions-incident-reports-oidc" + + +def test_preflight_role_name_is_the_bootstrap_role(): + tf = (REPO / "infrastructure" / "bootstrap" / "incident-reports.tf").read_text() + assert f'"{preflight.EXPECTED_ROLE_NAME}"' in tf + assert f"environment: {preflight.ENVIRONMENT}" in _wf() + + +def test_preflight_passes_a_set_variable_and_a_main_only_environment(): + assert preflight.evaluate(ARN_OK, "ok", ENV_OK, ["main"]) == ([], ["incident-reports deploys only from main"]) + assert preflight.main(["--fixture", str(FIX / "preflight-good.json")]) == 0 + + +def test_preflight_fails_the_known_bad_fixture_for_the_missing_variable(capsys): + fx = json.loads((FIX / "preflight-missing-variable.json").read_text()) + problems, _ = preflight.evaluate(fx["role_arn"], fx["env_state"], fx["environment"], fx["branch_policies"]) + assert len(problems) == 1 and "AWS_INCIDENT_REPORTS_ROLE_ARN is not set" in problems[0] + assert preflight.main(["--fixture", str(FIX / "preflight-missing-variable.json")]) == 1 + assert "::error::" in capsys.readouterr().out + + +@pytest.mark.parametrize("arn,why", [ + (None, "is not set"), + ("arn:aws:iam::000000000000:role/github-actions-oidc", "names a role other than"), + ("arn:aws:iam::000000000000:user/github-actions-incident-reports-oidc", "is not an IAM role ARN"), + ("github-actions-incident-reports-oidc", "is not an IAM role ARN"), +]) +def test_preflight_fails_a_variable_that_does_not_name_the_role(arn, why): + problems, _ = preflight.evaluate(arn, "ok", ENV_OK, ["main"]) + assert len(problems) == 1 and why in problems[0] + + +def test_preflight_never_prints_the_arn_or_account(capsys, tmp_path): + fx = tmp_path / "fx.json" + fx.write_text(json.dumps({"role_arn": "arn:aws:iam::123456789012:role/other", "env_state": "ok", + "environment": ENV_OK, "branch_policies": ["main"]})) + preflight.main(["--fixture", str(fx)]) + assert "123456789012" not in capsys.readouterr().out + + +@pytest.mark.parametrize("state,env,branches,why", [ + ("missing", None, None, "does not exist"), + ("ok", {"deployment_branch_policy": None}, None, "custom branch list"), + ("ok", {"deployment_branch_policy": {"protected_branches": True, "custom_branch_policies": False}}, None, + "custom branch list"), + ("ok", ENV_OK, ["main", "feat/*"], "not only main"), + ("ok", ENV_OK, [], "not only main"), +]) +def test_preflight_fails_a_missing_or_unrestricted_environment(state, env, branches, why): + problems, _ = preflight.evaluate(ARN_OK, state, env, branches) + assert len(problems) == 1 and why in problems[0] + + +def test_preflight_says_so_when_the_environment_cannot_be_read_and_checks_the_variable(): + problems, notes = preflight.evaluate(ARN_OK, "unreadable", None, None) + assert problems == [] and "not observed" in notes[0] + problems, _ = preflight.evaluate("", "unreadable", None, None) + assert problems and "is not set" in problems[0] + + +def _deploy(): + return (WF / "deploy-with-opa.yml").read_text() + + +def test_deploy_runs_the_preflight_before_anything_is_applied(): + yaml = pytest.importorskip("yaml") + steps = yaml.safe_load(_deploy())["jobs"]["deploy"]["steps"] + names = [st.get("name") for st in steps] + i = names.index("Incident report publisher preflight") + assert i < names.index("Configure AWS credentials") < names.index("Terraform Apply") + assert "INCIDENT_REPORTS_ROLE_ARN: ${{ vars.AWS_INCIDENT_REPORTS_ROLE_ARN }}" in _deploy() + assert "run: python3 scripts/check-incident-publisher.py" in _deploy() + + +def test_deploy_proves_the_publisher_by_calling_it_after_the_deploy(): + yaml = pytest.importorskip("yaml") + jobs = yaml.safe_load(_deploy())["jobs"] + job = jobs["incident-publisher"] + assert job["uses"] == "./.github/workflows/incident-reports.yml" and job["needs"] == ["deploy"] + assert job["permissions"]["id-token"] == "write" + assert job["secrets"] == {"CLOUDFRONT_DISTRIBUTION_ID": "${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}"} + assert list(yaml.safe_load(_wf())[True]["workflow_call"]["secrets"]) == ["CLOUDFRONT_DISTRIBUTION_ID"] + assert "incident-publisher" in jobs["notify"]["needs"] + assert "needs.incident-publisher.result == 'failure'" in jobs["notify"]["if"] + assert "workflow_call" in yaml.safe_load(_wf())[True] + +# ---- the Ongoing Certification Report's incident summary (CCM-OCR-AVL item 7) ------- + +def test_ocr_attests_none_when_only_exercises_are_recorded(): + ocr = _load("ocr_inc", "scripts/build-ocr.py") + text = ocr.incident_summary(_incidents.load(REGISTER), "2026-08-01") + assert text.startswith("No FedRAMP Reportable Incidents occurred") and "incident-reports.json" in text + + +def test_ocr_lists_a_real_reportable_incident_in_the_period(): + ocr = _load("ocr_inc2", "scripts/build-ocr.py") + text = ocr.incident_summary(_incidents.validate(good()), "2026-08-01") + assert text.startswith("1 FedRAMP Reportable Incident(s) this period: INC-2026-101 (open)") + assert ocr.incident_summary(_incidents.validate(good()), "2026-11-03").startswith("No FedRAMP") diff --git a/tests/test_published_redaction.py b/tests/test_published_redaction.py index 53fb8e84..c63752c0 100644 --- a/tests/test_published_redaction.py +++ b/tests/test_published_redaction.py @@ -198,6 +198,14 @@ def test_deploy_gates_exactly_what_it_publishes(tmp_path): optional = ("boundary-map", "reconcile-report", "trust-center", "conformance-results", "boundary-corroboration") for a in optional: (tmp_path / f"{a}.json").write_text("{}") + # The incident reports are named by incident, so the steps use globs; with + # the files the builder writes present, both expand to the same set. + incident_files = ("incident-reports.json", "incident-reports.md", "incident-INC-2026-001-01-initial.json") + for f in incident_files: + (tmp_path / f).write_text("{}") + assert "incident-INC-*.json" in publish + publish = {n for n in publish if "*" not in n} | {f for f in incident_files if f.startswith("incident-INC-")} + assert {"incident-reports.json", "incident-reports.md"} <= publish assert _gate_files(gate_step, tmp_path) == publish # One absent (the operator-run corroboration): it is neither uploaded nor scanned. (tmp_path / "boundary-corroboration.json").unlink()