From 63171f1c70bc40974f2777c6c8e3651264d12a43 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 15:44:09 -0500 Subject: [PATCH] FedRAMP Security Inbox: SES receiving, auto-acknowledgement, paging, deadlines (AFC-CSO-*) Adds a FedRAMP Security Inbox on the system's own domain. The address is one value in data/cds/offering.json; Terraform, the CPO and the change-notice check read it from there. - infrastructure/fedramp-inbox.tf: SES receiving in us-east-2 (MX, one receipt rule that stores then hands off and cannot bounce, stop or drop), Easy DKIM, custom MAIL FROM with SPF, DMARC, a CMK-encrypted inbox bucket, the inbox function, an hourly check, three alarms on the watchdog's alert path. - infrastructure/fedramp-inbox/: classifies @fedramp.gov / @gsa.gov mail as FedRAMP whatever its spam verdict (TFG), designates from the subject, registers Emergency deadlines at the Class C default (CRA), pages Emergency and Important mail (EMR, IMA), acknowledges authenticated FedRAMP mail once (ACK), checks the live configuration hourly (RCV). Message bodies are never read by the function or published. - scripts/check-fsi-notice.py + a unit-test job step: an address change fails without a dated FedRAMP notification record (NOC). - scripts/fsi.py: operator list/show/triage/close and the dated exercise. - Inventory, boundary map, service model, CPO, IR docs and a runbook. - Bootstrap: deploy-role and operator grants for the inbox. - Rule records: NOC Implemented; INB, TFG, RCV, CRA, EMR, IMA, ACK Partially Implemented until deployed and exercised. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 18 + data/cds/offering.json | 13 + data/frr-records.json | 206 ++++-- docs/boundary/boundary-classification.json | 16 +- docs/cr26-applicability.md | 3 +- docs/incident-response.md | 4 +- docs/policies/ir-policy.md | 2 +- docs/portfolio/service-model.json | 8 + docs/runbooks/fedramp-security-inbox.md | 72 ++ infrastructure/bootstrap/main.tf | 147 ++++ infrastructure/fedramp-inbox.tf | 572 +++++++++++++++ infrastructure/fedramp-inbox/index.mjs | 260 +++++++ infrastructure/fedramp-inbox/logic.mjs | 407 +++++++++++ infrastructure/logging.tf | 13 + infrastructure/main.tf | 24 +- infrastructure/schemas/ksi-signal.schema.json | 3 +- infrastructure/variables.tf | 10 + scripts/build-cpo.py | 13 + scripts/build-ksi-signal.py | 70 ++ scripts/check-fsi-notice.py | 122 ++++ scripts/fsi.py | 316 +++++++++ .../fsi/offering-changed-with-notice.json | 21 + .../fsi/offering-changed-without-history.json | 13 + .../fsi/offering-changed-without-notice.json | 18 + tests/test_fedramp_inbox.py | 652 ++++++++++++++++++ tests/test_fsi_cli.py | 74 ++ tests/test_fsi_notice.py | 86 +++ tests/test_runtime_bucket_reads.py | 8 +- 28 files changed, 3119 insertions(+), 52 deletions(-) create mode 100644 docs/runbooks/fedramp-security-inbox.md create mode 100644 infrastructure/fedramp-inbox.tf create mode 100644 infrastructure/fedramp-inbox/index.mjs create mode 100644 infrastructure/fedramp-inbox/logic.mjs create mode 100644 scripts/check-fsi-notice.py create mode 100644 scripts/fsi.py create mode 100644 tests/fixtures/fsi/offering-changed-with-notice.json create mode 100644 tests/fixtures/fsi/offering-changed-without-history.json create mode 100644 tests/fixtures/fsi/offering-changed-without-notice.json create mode 100644 tests/test_fedramp_inbox.py create mode 100644 tests/test_fsi_cli.py create mode 100644 tests/test_fsi_notice.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 933f590b..1caf4ef7 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -243,6 +243,24 @@ jobs: - name: Exception register expiry check run: python3 scripts/check-exceptions.py + # AFC-CSO-NOC: the FedRAMP Security Inbox address (data/cds/offering.json) + # cannot change without a history entry recording that FedRAMP was + # notified. Compared with the merge base on a pull request and with the + # previous commit on a push, so the history is also append-only. + - name: FedRAMP Security Inbox change notice (AFC-CSO-NOC) + env: + BASE_REF: ${{ github.event_name == 'pull_request' && github.base_ref || '' }} + BEFORE_SHA: ${{ github.event_name == 'push' && github.event.before || '' }} + run: | + base="" + if [ -n "$BASE_REF" ] && git fetch --no-tags --depth=1 origin "$BASE_REF"; then + git show FETCH_HEAD:data/cds/offering.json > fsi-base.json 2>/dev/null && base="--base fsi-base.json" + elif [ -n "$BEFORE_SHA" ] && git fetch --no-tags --depth=1 origin "$BEFORE_SHA"; then + git show "$BEFORE_SHA":data/cds/offering.json > fsi-base.json 2>/dev/null && base="--base fsi-base.json" + fi + # shellcheck disable=SC2086 # $base is an optional flag pair + python3 scripts/check-fsi-notice.py $base + # Known Go-vs-Wasm builtin divergences (%q, %v-on-sets, host time) are # banned at lint time; the parity test catches what the corpus exercises, # this catches the rest before it exists. It also requires every sprintf diff --git a/data/cds/offering.json b/data/cds/offering.json index 27be34e5..9cf9f9d8 100644 --- a/data/cds/offering.json +++ b/data/cds/offering.json @@ -7,6 +7,19 @@ "uei": "", "sales_contact": { "name": "Sam Aydlette", "url": "https://samaydlette.com/pages/contact.html" }, "security_contact": { "name": "Sam Aydlette", "email": "sam.aydlette@gmail.com", "source": "/.well-known/security.txt" }, + "fedramp_security_inbox": { + "_note": "The FedRAMP Security Inbox (AFC-CSO-INB): the one place this address is written. infrastructure/fedramp-inbox.tf receives mail for it, the CPO publishes it, and scripts/check-fsi-notice.py fails any change to it that does not record notifying FedRAMP (AFC-CSO-NOC). To change it: add a history entry with fedramp_notified, then change address.", + "address": "fedramp-security@samaydlette.com", + "runbook": "https://github.com/sam-aydlette/samaydlette.com/blob/main/docs/runbooks/fedramp-security-inbox.md", + "history": [ + { + "address": "fedramp-security@samaydlette.com", + "since": "2026-11-05", + "fedramp_notified": null, + "basis": "Established. No earlier FedRAMP Security Inbox or Marketplace Security Email is on file with FedRAMP for this unsponsored system, so there was no prior address to change from." + } + ] + }, "product_website": "https://samaydlette.com", "logo_url": "https://samaydlette.com/assets/images/brand/logo.png", "service_description": "A static personal website on AWS that doubles as a working continuous-compliance pipeline: every deploy derives signed, machine-readable compliance artifacts from one canonical inventory and publishes them under /.well-known/. Includes the Silk Reeling Mirror application, a Cognito-gated Tai Chi coaching API.", diff --git a/data/frr-records.json b/data/frr-records.json index c7d069f9..28801edb 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -5,82 +5,206 @@ "records": [ { "frr_id": "AFC-CSO-ACK", - "status": "Not Implemented", - "implementation": "No FSI; no auto-responder.", - "evidence": [], - "gap": "No prompt automatic acknowledgment of FedRAMP messages. To close: Configure an auto-acknowledgment for mail from @fedramp.gov/@gsa.gov (e.g. SES receipt rule -> Lambda reply, or provider auto-reply rule) and include it in the nightly configuration check.", + "status": "Partially Implemented", + "implementation": "The inbox function acknowledges every message from @fedramp.gov or @gsa.gov automatically on receipt, through SES from the inbox address (Easy DKIM, custom MAIL FROM with SPF, DMARC; infrastructure/fedramp-inbox.tf), once per message even when SES retries, never to auto-replies, bulk mail, bounces, or mail failing SPF/DKIM/DMARC (FedRAMP's own mail passes them, AFC-FRP-VRE; this keeps a forged sender from using the inbox as a reflector; such mail is still registered and paged), with headers inbound content cannot inject. A failed acknowledgement is recorded and pages through fsi-overdue; the SES sandbox is reported by the hourly check.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_acknowledgement_marks_itself_automatic_and_threads_to_the_message" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_nothing_from_the_inbound_message_can_inject_a_header" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_retry_does_not_acknowledge_twice" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_sandbox_rejection_of_the_acknowledgement_is_recorded_not_hidden" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy, and SES production access in us-east-2 (the account is presumed to be in the SES sandbox, where SES sends only to verified addresses).", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-CRA", - "status": "Not Implemented", - "implementation": "No FSI, no Emergency/Emergency Test handling runbook in docs/incident-response.md or ir-policy.md.", - "evidence": [], - "gap": "No procedure to recognize Emergency / Emergency Test designated messages, extract the required actions and timeframe, and complete them; no record of completion. To close: Write an FSI runbook (classify by designation, open a tracked item with the message's deadline, complete, reply with completion) and wire Emergency-designated mail to page the operator; keep a completion log. Rehearse with a self-generated Emergency Test.", + "status": "Partially Implemented", + "implementation": "Emergency and Emergency Test messages (subject designator, AFC-FRP-CDS) get a register item with a deadline: by default 3:00 p.m. ET on the 2nd business day (AFC-FRP-ERT, Class C; receipt day counts, holidays not skipped, both erring earlier), replaced at triage by the timeframe the message states (scripts/fsi.py triage). The fsi-overdue alarm pages while an item is past its deadline and not closed; scripts/fsi.py close records the outcome and whether it was late. Procedure: docs/runbooks/fedramp-security-inbox.md.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_class_c_default_deadline_is_3pm_eastern_on_the_second_business_day" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_emergency_records_carry_a_deadline_and_important_ones_ask_for_the_messages_own" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_overdue_counts_untriaged_unclosed_unacknowledged_and_unpaged_items" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_emergency_is_registered_acknowledged_and_pages_the_security_official" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy; completing a real message's required actions is an operator act that only a received message can show.", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-EMR", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No routing of Emergency-designated messages to a senior security official; no mailbox configuration or automated validation (both artifacts missing). To close: Add a mail rule that routes subject-designated 'Emergency' FedRAMP messages to the senior security official (the accountable official in the CPO, plus SNS page), and include it in the nightly mailbox-configuration check.", + "status": "Partially Implemented", + "implementation": "Emergency-designated messages page the senior security official, the accountable official named in the CPO (the operator), through the evidence-alert SNS topic on receipt, with sender, subject, designation and deadline (never the body); an Emergency from an address other than fedramp_security@ (AFC-FRP-UFS) is flagged, not demoted. Configuration settings: infrastructure/fedramp-inbox.tf; automated validation: the hourly check (fsi-config alarm).", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_emergency_is_registered_acknowledged_and_pages_the_security_official" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_emergency_from_an_address_other_than_fedramp_security_is_flagged_not_demoted" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_each_drift_that_could_lose_or_delay_fedramp_mail_is_a_problem" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy; the page reaches the official only through the alert topic's email subscription, which is created out of band.", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-IMA", - "status": "Not Implemented", - "implementation": "No FSI; no handling procedure for Important-designated messages.", - "evidence": [], - "gap": "No procedure to complete actions in Important messages within their stated timeframe. To close: Extend the FSI runbook to Important messages with tracked deadlines (same tracker as CRA).", + "status": "Partially Implemented", + "implementation": "Important-designated messages page the operator and open a register item that cannot be triaged without recording the timeframe the message states (scripts/fsi.py triage --respond-by); fsi-overdue pages while it is untriaged after 24 hours, triaged without a timeframe, or past that timeframe and not closed.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_an_important_message_pages_and_opens_a_tracked_item" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_overdue_counts_untriaged_unclosed_unacknowledged_and_unpaged_items" + }, + { + "kind": "test", + "ref": "tests/test_fsi_cli.py::test_important_messages_cannot_be_triaged_without_their_timeframe" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy.", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-INB", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No dedicated FedRAMP Security Inbox address exists or is designated; the required artifact (an email address to receive messages from FedRAMP) cannot be produced. To close: Create a dedicated address on the system's domain (e.g. fedramp-security@samaydlette.com: MX record in dns.tf plus SES inbound or a mail provider, with SPF/DKIM/DMARC), document it as the FSI in the CPO certification_data (security_contact block) and trust center, and monitor it (alarm on delivery failure).", + "status": "Partially Implemented", + "implementation": "The FedRAMP Security Inbox is fedramp-security@samaydlette.com, a role address on the system's own domain (not a personal mailbox), declared once in data/cds/offering.json (fedramp_security_inbox) and published in the CPO's certification_data. infrastructure/fedramp-inbox.tf receives it: MX to SES receiving in us-east-2, one receipt rule for the address, messages stored CMK-encrypted in the inbox bucket and handed to the inbox function; the hourly check and three alarms page through the evidence-alert topic. Handling: docs/runbooks/fedramp-security-inbox.md.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_inbox_address_has_one_source_of_truth" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_cpo_publishes_the_inbox_address_from_its_one_source" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_receipt_rule_stores_then_hands_off_and_has_nothing_that_drops_mail" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_mail_bucket_is_cmk_encrypted_private_and_tls_only" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy.", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-NOC", - "status": "Not Implemented", - "implementation": "No FSI exists, so no change-notification process exists; nothing in docs/incident-response.md or docs/policies/ir-policy.md covers notifying FedRAMP of an inbox change.", - "evidence": [], - "gap": "No process (manual or automated) to notify FedRAMP when the FSI address changes. To close: Make the FSI address a single value in the canonical inventory and add a CI check that fails a change to it unless the commit carries a 'FedRAMP notified on via ' record; document the runbook step (email FedRAMP from the old and new address) in ir-policy.md.", - "closes_with": [ - "W9" + "status": "Implemented", + "implementation": "The inbox address has one source (data/cds/offering.json, fedramp_security_inbox) with an append-only history. scripts/check-fsi-notice.py, run in the unit-test job on every pull request and push, fails a change to the address unless a new history entry carries a dated fedramp_notified marker naming the channel (FedRAMP's '[CSP] Notification of Changes' form), and fails a rewritten history against the merge base. Known-bad fixtures in tests/fixtures/fsi/. The procedure (notify before changing, then re-run the exercise) is in docs/runbooks/fedramp-security-inbox.md. The inbox was established 2026-11-05 with no earlier address on file with FedRAMP, so there has been no change to notify.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_an_address_change_without_the_fedramp_notified_marker_fails" + }, + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_an_address_change_without_a_history_entry_fails" + }, + { + "kind": "test", + "ref": "tests/test_fsi_notice.py::test_rewriting_history_fails_against_the_base" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#FedRAMP Security Inbox change notice (AFC-CSO-NOC)" + } ] }, { "frr_id": "AFC-CSO-RCV", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "Nothing receives FedRAMP mail without disruption (no inbox, no anti-spam allowlisting, no monitoring, no backup reader for a one-person operation). To close: After INB/TFG: allowlist FedRAMP senders, add delivery-failure and unread-age alarms (SNS to operator, reusing the watchdog path), and name a backup reader or an out-of-office auto-forward so a single absent operator does not disrupt receipt. Provider half is fully buildable; only an actual FedRAMP message demonstrates it end-to-end.", + "status": "Partially Implemented", + "implementation": "Nothing is asked of FedRAMP: no CAPTCHA, portal or challenge; TLS is accepted, not required; the receipt rule stores every message before anything else runs and has no bounce, stop or drop action; spam and virus verdicts are recorded only. Disruption pages: fsi-config (live configuration differs from Terraform, including the SES sandbox, or the hourly check stopped reporting), fsi-overdue (an item untriaged or past its deadline, or an acknowledgement or page failed) and fsi-errors (the function failed; SES retries and failed events reach the DLQ), all through the evidence-alert topic.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_receipt_rule_stores_then_hands_off_and_has_nothing_that_drops_mail" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_rule_ahead_of_the_inbox_rule_that_matches_every_address_is_a_problem" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_hourly_check_counts_overdue_register_items" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_a_page_that_fails_is_recorded_and_raised_so_ses_retries" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy. Residual for a one-person operation: no backup reader; an absent operator's pages wait, visible through the repeating overdue alarm (named in the runbook).", "closes_with": [ - "W9" + "sam" ] }, { "frr_id": "AFC-CSO-TFG", - "status": "Not Implemented", - "implementation": "No inbox exists: no MX record in infrastructure/dns.tf, no mail infrastructure in infrastructure/*.tf; live /.well-known/security.txt Contact is a personal gmail address with no FSI designation; docs/incident-response.md:120 and docs/policies/ir-policy.md:9 declare FSI does not apply; docs/cr26-applicability.md:27 records AFC as N/A.", - "evidence": [], - "gap": "No mailbox configuration treating @fedramp.gov / @gsa.gov senders as FedRAMP, and no automated validation of that configuration (both listed artifacts missing). To close: In the FSI mail rules, tag/route all mail from @fedramp.gov and @gsa.gov as FedRAMP (never spam-filtered/quarantined); export the rule set as code and add a nightly check (evidence-nightly.yml) that reads the live rules and compares them with the expected configuration, published to the trust center like check-manual-settings.py does for GitHub settings.", + "status": "Partially Implemented", + "implementation": "Mailbox configuration as code: the inbox function (infrastructure/fedramp-inbox/logic.mjs, classify) treats mail whose From address or envelope sender is exactly @fedramp.gov or @gsa.gov as FedRAMP, whatever its spam or virus verdict or SPF/DKIM/DMARC result; failed authentication is shown in the page so the operator can confirm the sender, and the operator closes a message confirmed not to be from FedRAMP as not-fedramp. The receipt rule has no action that can bounce, stop or drop mail. Automated validation: the function's hourly check compares the live active rule set, rule, identity and MX record with the declared configuration and pages through the fsi-config alarm on any difference.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_fedramp_senders_are_fedramp_even_when_flagged_as_spam_or_unauthenticated" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_look_alike_domains_and_display_name_spoofs_are_not_fedramp" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_each_drift_that_could_lose_or_delay_fedramp_mail_is_a_problem" + }, + { + "kind": "test", + "ref": "tests/test_fedramp_inbox.py::test_the_hourly_check_counts_drift_and_unreadable_settings" + } + ], + "gap": "Built, not yet live or exercised: needs the bootstrap apply (the deploy role's SES, inbox-bucket and inbox-role grants), a deploy, and the dated end-to-end exercise (scripts/fsi.py exercise, docs/runbooks/fedramp-security-inbox.md) run by the operator after deploy.", "closes_with": [ - "W9" + "sam" ] }, { diff --git a/docs/boundary/boundary-classification.json b/docs/boundary/boundary-classification.json index 69d1e17c..0d36ebc2 100644 --- a/docs/boundary/boundary-classification.json +++ b/docs/boundary/boundary-classification.json @@ -15,6 +15,8 @@ "match": ["aws::event_schedule::opa_compliance", "aws::function::opa_compliance", "aws::log_group::opa_compliance", "aws::iam_role::lambda_opa", "aws::iam_policy::lambda_opa", "aws::message_queue::compliance_dlq", "aws::kms_key::runtime_signing"]}, {"key": "watchdog", "zone": "system", "label": "Evidence-freshness watchdog and alerting", "match": ["aws::*::evidence_watchdog", "aws::metric_alarm::evidence*", "aws::notification_topic::evidence_alerts"]}, + {"key": "fsi", "zone": "system", "label": "FedRAMP Security Inbox (AFC-CSO-INB)", + "match": ["aws::mail_receiver::*", "aws::*::fedramp_inbox", "aws::object_store::fsi_mail", "aws::metric_alarm::fsi*"]}, {"key": "app", "zone": "system", "label": "Application sub-system (Silk Reeling)", "match": ["aws::api_gateway::silk_reeling", "aws::identity_provider::silk_reeling", "aws::function::silk_reeling", "aws::iam_role::silk_reeling", "aws::iam_policy::silk_reeling", "aws::log_group::silk_*", "aws::secrets_manager::silk_*", "aws::kms_key::silk_reeling"]}, {"key": "audit", "zone": "system", "label": "Audit and shared keys", @@ -34,7 +36,9 @@ {"key": "operator", "label": "Operator (dev machine)", "zone": "outside", "kind": "actor", "why": "Out per Rule of Thumb #4: development environment, no federal information."}, {"key": "operator-email", "label": "Operator email and SaaS", "zone": "outside", "kind": "actor", - "why": "Out per Rule of Thumb #3; receives the evidence-alarm email (flow I), which carries alarm metadata only."}, + "why": "Out per Rule of Thumb #3; receives the evidence-alarm email (flow I), which carries alarm metadata only, and the FedRAMP Security Inbox page (flow M), which carries a FedRAMP message's sender, subject, designation and deadline, never its body."}, + {"key": "fedramp", "label": "FedRAMP (@fedramp.gov, @gsa.gov senders)", "zone": "outside", "kind": "actor", + "why": "The program office writing to the FedRAMP Security Inbox (AFC-CSO-INB); its mail is treated as FedRAMP by default (AFC-CSO-TFG)."}, {"key": "public", "label": "Public Internet (readers, verifiers)", "zone": "outside", "kind": "actor", "why": "Anonymous consumers of the site and the /.well-known/ evidence."}, {"key": "app-users", "label": "App users (Silk Reeling)", "zone": "outside", "kind": "actor", @@ -44,7 +48,7 @@ "package_id": "AGENCYAMAZONEW", "name": "AWS East/West", "status": "FedRAMP Certified Class C", - "services": ["VPC networking", "KMS HSM", "IAM control plane", "S3", "CloudFront edge", "Lambda", "API Gateway", "Cognito", "Secrets Manager", "EventBridge", "ACM", "CloudTrail", "CloudWatch", "SNS", "SQS", "Route 53"], + "services": ["VPC networking", "KMS HSM", "IAM control plane", "S3", "CloudFront edge", "Lambda", "API Gateway", "Cognito", "Secrets Manager", "EventBridge", "ACM", "CloudTrail", "CloudWatch", "SNS", "SQS", "Route 53", "SES"], "why": "Per Key Concept #6: the underlying infrastructure is inherited from the AWS package under the customer responsibility matrix." }, "flows": [ @@ -69,6 +73,12 @@ {"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": "FedRAMP → SES receiving → inbox bucket", "path": [{"declared": "fedramp"}, {"component": "aws::mail_receiver::fsi"}, {"component": "aws::object_store::fsi_mail"}], + "protocol": "SMTP 25 (STARTTLS when the sender offers it; not required, AFC-CSO-RCV)", "auth": "None required of the sender; SPF, DKIM and DMARC verdicts recorded and shown to the operator", "encryption": "In transit: opportunistic TLS; at rest: SSE-KMS (at-rest CMK)", "data": "FedRAMP messages, full content"}, + {"id": "M", "label": "Inbox function → SNS topic → operator email (out)", "path": [{"component": "aws::mail_receiver::fsi"}, {"component": "aws::function::fedramp_inbox"}, {"component": "aws::notification_topic::evidence_alerts"}, {"declared": "operator-email"}], + "protocol": "AWS-internal (SES async invoke, SNS publish); then email (SMTP)", "auth": "Inbox Lambda role: sns:Publish on the alert topic only", "encryption": "At rest: CMK · email not end-to-end encrypted", "data": "Message metadata only (sender, subject, designation, deadline); never the body"}, + {"id": "N", "label": "Inbox function → SES → FedRAMP (acknowledgement)", "path": [{"component": "aws::function::fedramp_inbox"}, {"component": "aws::mail_receiver::fsi"}, {"declared": "fedramp"}], + "protocol": "SES send (DKIM-signed, custom MAIL FROM); SMTP with TLS", "auth": "Inbox Lambda role: ses:SendRawEmail as the inbox address only", "encryption": "In transit: TLS", "data": "Automatic acknowledgement naming the received subject and a reference"} ] } diff --git a/docs/cr26-applicability.md b/docs/cr26-applicability.md index 0d20e28d..9b4cfa33 100644 --- a/docs/cr26-applicability.md +++ b/docs/cr26-applicability.md @@ -24,7 +24,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. -These four are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. +These three are N/A because of *what this system is*, not because of an engineering gap. If the system were ever sponsored, listed, assessed, or handling federal data, each would activate, and the mechanisms above (the SDR's V&V evidence, the CDS overview package, the PAIN evaluation) are the inputs those activated obligations would consume. diff --git a/docs/incident-response.md b/docs/incident-response.md index 6a3f8f34..ae79ec72 100644 --- a/docs/incident-response.md +++ b/docs/incident-response.md @@ -117,5 +117,7 @@ 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. +- **FedRAMP Security Inbox (FSI)** — the address in `data/cds/offering.json` (`fedramp_security_inbox`) receives FedRAMP's messages (AFC-CSO-INB). Mail from @fedramp.gov or @gsa.gov is acknowledged automatically and pages the operator; Emergency and Emergency Test messages carry a tracked deadline. Handling is in [`runbooks/fedramp-security-inbox.md`](runbooks/fedramp-security-inbox.md). + +There is no actual FedRAMP authorization in scope, so the Incident Communications Procedures (ICP) do not apply. diff --git a/docs/policies/ir-policy.md b/docs/policies/ir-policy.md index 81be6cb0..fffa06bc 100644 --- a/docs/policies/ir-policy.md +++ b/docs/policies/ir-policy.md @@ -6,7 +6,7 @@ External communication paths: - **Public reporter:** [`/.well-known/security.txt`](../../website/.well-known/security.txt) is the published vulnerability-reporting mailbox. - **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 Security Inbox (FSI, 20x):** the system is not FedRAMP-certified; no actual FSI obligation applies. Notification path is documented in the runbook for reference. +- **FedRAMP Security Inbox (FSI, 20x AFC):** the address in `data/cds/offering.json` (`fedramp_security_inbox`), received by SES and handled by `infrastructure/fedramp-inbox.tf`. FedRAMP mail is acknowledged automatically; Emergency and Important messages page the operator, the senior security official, and carry a tracked deadline; the hourly configuration check and the overdue check page through the evidence-alert topic. A change of address is blocked in CI until the change records that FedRAMP was notified (AFC-CSO-NOC). Procedure: [`fedramp-security-inbox.md`](../runbooks/fedramp-security-inbox.md). **20x rule integration.** KSI-INR (Incident Response), ICP (Incident Communications Procedures), FSI (FedRAMP Security Inbox). diff --git a/docs/portfolio/service-model.json b/docs/portfolio/service-model.json index 4aeb5726..1b8b5b4f 100644 --- a/docs/portfolio/service-model.json +++ b/docs/portfolio/service-model.json @@ -77,6 +77,14 @@ "consumed_by": ["website", "silk-reeling"], "features": [] }, + { + "key": "fsi", + "name": "FedRAMP Security Inbox", + "group": "fsi", + "owner_domain": "observability", + "consumed_by": ["website", "silk-reeling"], + "features": [] + }, { "key": "audit", "name": "Audit trail and shared keys", diff --git a/docs/runbooks/fedramp-security-inbox.md b/docs/runbooks/fedramp-security-inbox.md new file mode 100644 index 00000000..bc6f28aa --- /dev/null +++ b/docs/runbooks/fedramp-security-inbox.md @@ -0,0 +1,72 @@ +# Runbook: the FedRAMP Security Inbox + +The FedRAMP Security Inbox (FSI) is the address FedRAMP writes to (AFC-CSO-INB). The address is in `data/cds/offering.json` under `fedramp_security_inbox.address`, and nowhere else. The CPO publishes it, and the infrastructure reads it from that file. + +**Senior security official** (AFC-CSO-EMR): the accountable official named in the CPO (`accountable_official` in `data/cds/offering.json`), who is the operator. Pages go to the operator's subscription on the evidence-alert SNS topic (`samaydlette-com-evidence-alerts`). The runbook [`evidence-sla-alarm.md`](evidence-sla-alarm.md) explains how to set up that subscription. + +## How it works + +| Step | What happens | Rule | +|---|---|---| +| Receive | The domain's MX record points to SES receiving in us-east-2. One receipt rule accepts mail for the inbox address only. TLS is optional, so a sender without TLS is not refused. Spam and virus verdicts are recorded and never used to drop mail. | RCV | +| Store | SES writes the raw message to `s3://samaydlette-com-fsi-mail/inbound/`, encrypted with the at-rest CMK. | INB | +| Classify | The `samaydlette-com-fedramp-inbox` function treats mail as FedRAMP when the From address or the envelope sender is exactly `@fedramp.gov` or `@gsa.gov`. A failed SPF, DKIM or DMARC check is shown in the page, but the message is still treated as FedRAMP. | TFG | +| Designate | The function reads the designator from the subject line: Emergency Test, Emergency, Important, or none (a general message). It matches broadly, so an occasional false Emergency is possible; a missed one is not. | CDS | +| Track | The function writes a register item to `register/open/.json`. The item has a triage deadline and, for Emergency and Emergency Test messages, a due date for the required actions. The default due date is 3:00 p.m. ET on the 2nd business day, which is the AFC-FRP-ERT default for Class C. | CRA, IMA | +| Acknowledge | SES sends an automatic reply to the sender from the inbox address. The reply is DKIM-signed, and it is not sent to auto-replies, bulk mail, bounces, or mail that fails sender authentication (genuine FedRAMP mail passes SPF, DKIM and DMARC under AFC-FRP-VRE; a forged sender must not be able to make the inbox mail a government address). Unauthenticated mail is still registered and paged. | ACK | +| Page | The function publishes to the alert topic with the sender, subject, designation and due dates. It never includes the message body. | EMR, IMA | +| Check hourly | The function compares the live receipt rule, domain identity, MX record and SES account status with the Terraform configuration. It also counts overdue register items. Each result is a metric with its own alarm. | RCV, TFG | + +The triage windows are 2 hours for Emergency and Emergency Test, 24 hours for Important and 72 hours for general messages. They are set in `infrastructure/fedramp-inbox/logic.mjs` (`TRIAGE_HOURS`) and pinned by `tests/test_fedramp_inbox.py`. + +## When a page arrives + +Run the commands below from a checkout, using the operator's AWS credentials. The operators group policy `fedramp-inbox-operator` grants the access they need. + +1. **Read the message.** `python3 scripts/fsi.py show ` prints the register item and the message as plain text. HTML is reduced to its text and is not rendered. Attachments are listed but not opened. If you need to open an attachment, do it in a disposable environment, never on the workstation that holds the deploy credentials. +2. **Confirm the sender if the page says NOT AUTHENTICATED,** or if an Emergency did not come from `fedramp_security@`. Do this through a channel you already trust, such as `help.fedramp.gov` or a known FedRAMP contact. Do not use contact details from the message itself. If the sender turns out not to be FedRAMP, close the item with `--outcome not-fedramp`. Under AFC-CSO-TFG, the inbox rules then no longer apply to that message. +3. **Triage the item.** Record the timeframe the message states, which takes precedence over the default due date: `python3 scripts/fsi.py triage --respond-by 2026-11-10T15:00-05:00 --note "…"`. Important messages cannot be triaged without `--respond-by` (AFC-CSO-IMA). For Emergency messages, `--respond-by` replaces the Class C default. +4. **Complete the required actions** that the message lists (AFC-FRP-RQA). Reply to FedRAMP from your mail client, and copy the inbox address so the reply is on record. Then close the item: `python3 scripts/fsi.py close --outcome completed --note "what was done, when, reply sent"`. The `close` command reports it when the item was closed after its due date. + +`python3 scripts/fsi.py list` shows the open items, and `list --all` also shows the closed ones. + +## Alarms + +All three alarms page through the evidence-alert topic. + +| Alarm (`samaydlette-com-evidence-watchdog-…`) | Fires when | Do this | +|---|---|---| +| `fsi-config` | The live receiving setup differs from Terraform in 2 of 3 hourly checks, or the check stopped reporting. Differences include an inactive or edited rule, a rule ahead of the inbox rule, a failed DKIM or MAIL FROM setup, the SES sandbox, or a changed MX record. | Read the latest `inbox check` line in the function's log; it names each problem. Fix the setup through Terraform and the reviewed deploy. Never fix it by hand in the console: the next deploy would undo the change, or this check would page about it. | +| `fsi-overdue` | An open item is past its triage window, an item is past its due date and not closed, an Important item was triaged without a timeframe, or an acknowledgement or page failed. | Run `python3 scripts/fsi.py list`. A failed acknowledgement while the account is in the SES sandbox is expected; see below. | +| `fsi-errors` | The function failed. Usually this means a page did not go out. | The message is already in the bucket. SES retries the function twice, and failed events go to `samaydlette-com-opa-compliance-dlq`. Check the function's log, fix the cause, and run `fsi.py list` to find the item that was missed. | + +## The SES sandbox + +A new SES account is in the sandbox. In the sandbox, SES sends only to verified addresses, so acknowledgements to FedRAMP fail. Each failure is recorded and counted by `fsi-overdue`, and the hourly check reports the sandbox in `fsi-config`. Receiving is not affected. To fix this, request production access in the SES console for us-east-2 (**Account dashboard → Request production access**), describing the use case as an automatic acknowledgement to a single government sender domain at very low volume. + +## Changing the address (AFC-CSO-NOC) + +1. Notify FedRAMP **before** you change the address. Use the "[CSP] Notification of Changes" form at `https://help.fedramp.gov/hc/en-us/requests/new?ticket_form_id=51829466938011`, and send from the old inbox if it still works. +2. In `data/cds/offering.json`, add a history entry: `{"address": "", "since": "YYYY-MM-DD", "fedramp_notified": {"on": "YYYY-MM-DD", "channel": "help.fedramp.gov Notification of Changes form, ticket "}}`. Then change `address` to the new value. +3. Open a PR. The unit-test job step **FedRAMP Security Inbox change notice (AFC-CSO-NOC)** fails if the address changed without a history entry, without the `fedramp_notified` marker, or with an edited history. +4. After the deploy, run the exercise below against the new address. + +## The exercise + +Run the exercise after the first deploy, after any address change, and once a year. It takes about five minutes. + +``` +python3 scripts/fsi.py exercise --reply-to --smtp --record docs/exercises +``` + +The exercise invokes the inbox function with a synthetic Emergency Test from a FedRAMP address. This runs the real classifier with nothing bypassed. The exercise then checks that the register item exists, that the acknowledgement was sent (to your address, never to FedRAMP), and that the page was published. With `--smtp`, it also sends one real message to the inbox address from `fsi-exercise@samaydlette.com` and waits up to 3 minutes for SES to store it. The exercise writes an outcomes-only record (no addresses, no subjects) to `docs/exercises/fsi-exercise-.json`. Commit that file. + +When the page email and the acknowledgement arrive, close the item: `python3 scripts/fsi.py close exercise- --outcome exercise-complete --note "page and ack received