Skip to content

Notifications: SCN, incidents and the (simulated) FedRAMP Security Inbox - #508

Merged
sam-aydlette merged 7 commits into
feat/frr-recordsfrom
feat/notifications
Nov 6, 2026
Merged

sam-aydlette merged 7 commits into
feat/frr-recordsfrom
feat/notifications

Conversation

@sam-aydlette

Copy link
Copy Markdown
Owner

SCN-Type: not-significant
SCN-Rationale: PROVISIONAL, Sam to confirm the type: notification processes, simulated counterparties and a scoped incident-reporting IAM role and workflow; no change to the system's components, boundary or data flows otherwise.

This PR consolidates #504 (SCN), #506 (incident reports) and #507 (FedRAMP Security Inbox) into one notifications PR. It also finishes the incident rules against simulated recipients.

Changed

SCN (from #504, unchanged)

  • Strict SCN gate. scripts/scn-evaluate.py and scripts/_scn.py, run by scn-tag.yml. Every PR body, or direct-push commit, carries SCN-Type: and SCN-Rationale:. Adaptive, transformative and emergency changes also carry SCN-Record:. class-change always fails, and transformative plan lead times are enforced.
  • Published evaluation log. /.well-known/scn-evaluations.json is append-only against the previously published copy.
  • Published notifications. Notifications are published in FedRAMP's SCN schema as significant-change-notifications.json with an Atom feed. They are never pruned, and each carries its deadlines. Deadlines are computed in business days, excluding federal holidays (scripts/_bizdays.py).
  • Overdue checks. A weekday scn-deadlines.yml check raises an issue when a notice is overdue.
  • Register. The register columns are backfilled. The docs and templates are AI-drafted.

Incident reports (from #506)

  • Register. The incident register is data/incidents.json, with a fail-closed loader. The IEC-CSO-EFR evaluation, the IEC-CSO-EFI/DPR rating, and the Initial, Ongoing and Final reports in FedRAMP's incident report schema all come from it. Class C clocks are read from the pinned rules.
  • Vulnerabilities as incidents. VER-TFR-IRI/NRI triggers are added in policies/triage.rego. Reconciliation invariant (m) is added.
  • Unattended publisher. incident-reports.yml runs on a bootstrap role scoped to .well-known/incident-*. It also runs after each deploy (job incident-publisher).
  • Alarms. The watchdog metric and alarm are IncidentReportsOverdue.
  • Exercise. A dated exercise (2026-11-05) is marked exercise: true.

Incident reports: new in this PR

  • Simulated delivery. scripts/deliver-incident-reports.py runs on every deploy, inside "Build incident reports", before signing and before the SDR. It also runs in every unattended publish, as the step "Deliver incident reports (simulated recipients; nothing sent)".
    • It reads back each report the incident log lists.
    • It checks each report against the sha256 the log publishes and against FedRAMP's incident report schema.
    • It "delivers" each report to two simulated recipients: "FedRAMP Incident Desk (simulated): accepts every report, replies to none, and has never heard of this system", and each affected agency, also simulated (default "Department of Hypothetical Affairs (simulated)").
    • The result is the signed delivery log /.well-known/incident-deliveries.json. It is labelled as a simulation and shows messages_actually_sent: 0.
    • The step fails, and writes nothing, when a listed report is missing, when a report's hash or schema does not match, when a report file is not listed, or when an incident evaluated not reportable has reports.
    • Known-bad fixtures: tests/fixtures/incidents/delivery-*.json.
  • Publisher role proved before the SDR. A new deploy-job step, "Incident report publisher role can be assumed" (scripts/check-incident-role.py), runs before the SDR build.
    • It takes the job's OIDC token and calls STS AssumeRoleWithWebIdentity for AWS_INCIDENT_REPORTS_ROLE_ARN.
    • It requires the assumed role to be github-actions-incident-reports-oidc, then discards the credentials.
    • When the role cannot be assumed, the deploy stops before anything is published. Known-bad STS fixtures: tests/fixtures/incidents/sts-*.xml.
    • The region is validated, so it cannot redirect the token to another host.
    • The incident-publisher job after the deploy stays as a second proof.
  • Bootstrap. The incident role's trust gains the reviewer-gated deploy environment subject (environment:${var.deploy_environment}), so the deploy job can assume the role. This adds no privilege beyond what the deploy role already has: the incident role's permissions are only PutObject on .well-known/incident-* and one CDN invalidation.
  • Notification text. The register's notification text, the IR docs and the CR26 applicability text now describe the simulated delivery.

FedRAMP Security Inbox (from #507, reworked: simulated)

  • No real mail infrastructure. There is no SES, DNS, mail bucket or Lambda. This PR contains no inbox bootstrap.
  • Inbox logic. scripts/_fsi.py is the inbox logic, written as pure functions:
    • exact @fedramp.gov / @gsa.gov classification, never filtered;
    • designators and the Class C default deadline;
    • the register (triage, close, overdue);
    • a header-injection-safe acknowledgement, sent once, never to auto-replies, bulk mail or bounces, and never to mail failing SPF/DKIM/DMARC;
    • paging.
  • Simulation on every deploy. The step "FedRAMP Security Inbox simulation (synthetic messages; nothing received or sent)" runs before the SDR build.
    • It runs the logic over 12 committed synthetic messages (data/fsi-simulation/messages.json): Emergency Test, Important with an injection attempt, general, forged @gsa.gov, auto-reply, bulk, bounce, envelope-only, a non-designated Emergency sender, a look-alike domain, a display-name spoof, and a failed first send.
    • It also runs a retry pass and 11 register checks.
    • It fails the deploy on any outcome that differs from the expected one.
    • It publishes the signed, dated /.well-known/fedramp-inbox-simulation.json, labelled as a simulation, with sender domains only. The file has a freshness entry and is covered by the redaction gate, the publish step and the round-trip check.
    • Known-bad fixture: tests/fixtures/fsi/simulation-wrong-expectation.json.
  • Published contact. data/cds/offering.json (fedramp_security_inbox.contact, published in the CPO) reads: "Simulated for this proof of concept: there is no FedRAMP Security Inbox, no mail is received or sent, and the inbox is permanently at zero because it does not exist. Hit me up on LinkedIn: https://www.linkedin.com/in/sa2/".
    • The CPO schema's contactEmail must be an email address, and the schema has no providerExtensions.
    • build-cpo.py publishes its own certification_data shape. The statement goes there and is never put in an email field.
  • AFC-CSO-NOC. scripts/check-fsi-notice.py runs in the unit-test job. A change to the contact must append a history entry with a dated fedramp_notified marker.

Shared

Effect

After deploy, the live site publishes:

  • fedramp-inbox-simulation.json and incident-deliveries.json (both simulations, both signed);
  • the SCN notifications, the evaluation log and the feed;
  • the incident log and reports;
  • the CPO's simulated-inbox contact.

Every deploy fails before the SDR is built if any of the following fails: the inbox simulation, the incident delivery, or the incident role assumption.

Records (python3 scripts/_frr.py, 154 rules):

Implemented Partially Not Implemented Not Applicable
Before (feat/frr-records) 6 93 42 13
After 39 78 24 13

Simulated: mail 7, incident-recipient 4.

33 records flip to Implemented:

  • AFC-CSO-ACK/CRA/EMR/IMA/INB/NOC/RCV/TFG
  • IEC-CSO-AIR/DPR/EFI/EFR/FIR/IIR/OIR
  • SCN-ADP-NTF, SCN-CSO-ARI/EMG/EVA/HIS/HRM/INF/MAR/NOM, SCN-RTR-NNR, SCN-TRF-NAF/NAV/NFP/NIP/TPR/UPD
  • VER-TFR-IRI/NRI

--complete still lists 102 open records, none of them AFC, SCN or IEC. They belong to the other workstreams.

Verified

  • make check passes: ruff, mypy, 1208 tests, and OPA 49/49.
  • These pass locally: Regal (infrastructure/policy), check-policy-annotations, check-exceptions, check-wasm-safe and check-fsi-notice.
  • The new tests import scripts that do not exist on the base, so they fail there.
  • The inbox simulation and the incident delivery were run locally over the committed data. The incident reports were built locally from the committed register.
  • Both workflow files parse as YAML.
  • CodeGuard was run over the diff. Its one finding is fixed: the AWS region is now validated before it is used in the STS host name.

Residual

  • The simulations prove the mechanisms, not real counterparties. No mail is received, and no report reaches FedRAMP or an agency.
  • The incident role check proves that the role can be assumed. Publishing with that role is proved by the incident-publisher job after the deploy.

Needs human

  • Change type is provisional. not-significant is proposed. The change adds a scoped IAM role, an unattended publishing workflow and a deploy dependency on them, so Sam may treat it as adaptive.
  • Before merging, do these, or every deploy of main fails:
    1. Bootstrap apply of infrastructure/bootstrap/incident-reports.tf (now including the deploy-environment trust) from a tree synced to main.
    2. Set the repo variable AWS_INCIDENT_REPORTS_ROLE_ARN from the incident_reports_role_arn output.
    3. Create the GitHub Environment incident-reports: no reviewer; deployment branches custom, exactly main.
  • Main stack. The watchdog alarm and metric are applied by the deploy after merge. Nothing else needs an apply. There is no inbox bootstrap.
  • SCN tags on open PRs. Add the SCN lines to FedRAMP 20x Class C: every applicable rule Implemented or Not Applicable #501's description and to open Dependabot PR descriptions, or scn-tag fails.
  • Decisions to confirm:
    • AFC and IEC records say Implemented on simulated counterparties, disclosed in their text and in simulated.
    • The wording of the published contact and of the simulated recipients.
    • Widening the incident role's trust to the deploy environment.
    • Keeping the post-deploy incident-publisher job as a second proof.
    • NRI adoption.
    • The federal incident coordinator text.
    • The incident register policy's decided_by: Operator.
    • reconcile.m mode (block).
    • The AI-authored exercise content.
    • The 24-hour freshness window for the incident log and the delivery log.
    • This PR's own SCN type.
    • Counting the emergency 5 business days from the merge.
    • SCN-2026-001's adaptive categorization.
    • Whether to tell FedRAMP that the SCN feed exists. Nothing is sent today.
  • Review the AI-drafted prose listed above.

Couldn't verify

  • The deploy-time steps that need GitHub OIDC or AWS: the STS assumption, signing and publishing. These are covered by unit tests with fake STS responses.
  • scripts/build-conformance.py fails locally on a missing junit.xml, and also fails on the base.

🤖 Generated with Claude Code

sam-aydlette and others added 7 commits November 5, 2026 16:36
…notifications and deadline checks

Every change now carries an explicit significant-change evaluation (SCN-Type,
SCN-Rationale, and SCN-Record for adaptive/transformative/emergency); a
missing tag fails instead of defaulting to routine-recurring, and class-change
blocks. The deploy appends every merged evaluation to a signed, append-only
log and publishes every register row in FedRAMP's SCN schema with a Markdown
view and an Atom feed, listed in the CPO. Business-day deadlines (US federal
holidays) are read from the vendored rules; a scheduled workflow fails on
anything overdue. Notification is publication only; nothing is sent.

SCN-Type: not-significant
SCN-Rationale: change-management process and compliance reporting only; no component, boundary, data flow or access change to the system.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ard)

SCN-Type: not-significant
SCN-Rationale: input validation in the new SCN log builder; no system component, boundary or access change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…torical notices

The record describes the system after a successful deploy of this commit: the
deploy builds and publishes every notice (any failure fails the deploy; the
round-trip check compares the served index and feed), so the mechanism is in
force. SCN-2026-001..005 were published after their deadlines and are named.

SCN-Type: not-significant
SCN-Rationale: rule-record text and a test only; no component, boundary, data flow or access change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…/NRI triggers

- data/incidents.json + schema + fail-closed loader (scripts/_incidents.py):
  every incident carries its FedRAMP reportability evaluation and reason;
  default N5 until an IEC-CSO-EFI estimate (checked against the rule's rubric).
- scripts/build-incident-report.py renders Initial/Ongoing/Final reports in
  FedRAMP's incident report schema (validated before write) and the incident
  log; Class C clocks and the rating scale are read from the pinned rules.
- policies/triage.rego incident_triggers: VER-TFR-IRI and VER-TFR-NRI, with
  thresholds parsed from the rule text (fail closed on a changed text).
- Reconciliation invariant (m): an open incident's findings are in the VDR.
- incident-reports.yml publishes unattended (publish-only; nothing is sent);
  bootstrap role scoped to .well-known/incident-*; the deploy also publishes;
  watchdog metric and alarm for overdue reports; freshness entry.
- Dated exercise (2026-11-05, exercise: true): IIR -> 2x OIR -> FIR, plus a
  not-reportable evaluation; run end to end in tests.
- FRR records: EFR, DPR, EFI, VER-TFR-IRI, VER-TFR-NRI Implemented; IIR, OIR,
  FIR, AIR Partially Implemented (publish-only; bootstrap apply pending).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s state the deployed system

The deploy fails before applying anything unless AWS_INCIDENT_REPORTS_ROLE_ARN
names the bootstrap incident-reports role and the incident-reports environment
deploys only from main (scripts/check-incident-publisher.py; known-bad fixture
with the variable missing). After the deploy job, the deploy calls
incident-reports.yml (now also workflow_call) on its own role, passing only the
CloudFront secret, so a green deploy proves the publisher publishes.

IEC-CSO-IIR/OIR/FIR/AIR gaps now state only what holds after a successful
deploy: published, not delivered to FedRAMP or agencies, by the operator's
decision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The inbox is simulated for this proof of concept by the operator's decision:
nothing is received or sent. scripts/_fsi.py is the inbox logic
(classification, designators, Class C deadline, register, header-safe
acknowledgement sent once, paging). Every deploy runs it over committed
synthetic messages before the SDR build, fails on any unexpected outcome, and
publishes the signed, dated result as fedramp-inbox-simulation.json, labelled
as a simulation. The published contact says so and points to LinkedIn; the
AFC-CSO-NOC check applies to that contact. AFC records are Implemented with
simulated {counterparty: mail}.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e SDR

Every deploy and every unattended publish now "delivers" each incident report
the log lists to a simulated FedRAMP and agency recipient
(scripts/deliver-incident-reports.py): read back, checked against the
published sha256 and FedRAMP's schema, and recorded in the signed delivery log
/.well-known/incident-deliveries.json. Nothing is sent. A failed delivery
stops publication.

The deploy job assumes the incident publisher's role before it builds the SDR
(scripts/check-incident-role.py), so a deploy whose publisher role does not
work stops before publishing records that claim it. The role's trust gains the
reviewer-gated deploy environment (bootstrap apply).

IEC-CSO-IIR/OIR/FIR/AIR are Implemented with simulated {incident-recipient}.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant