Skip to content

FedRAMP Security Inbox: SES receiving, acknowledgement, paging, deadlines (AFC-CSO-INB/NOC/TFG/RCV/CRA/EMR/IMA/ACK) - #507

Closed
sam-aydlette wants to merge 1 commit into
feat/frr-recordsfrom
feat/fedramp-inbox
Closed

sam-aydlette wants to merge 1 commit into
feat/frr-recordsfrom
feat/fedramp-inbox

Conversation

@sam-aydlette

Copy link
Copy Markdown
Owner

Changed

Adds the FedRAMP Security Inbox (AFC-CSO-INB and the rest of the AFC provider rules).

  • One source for the address. The address is set in data/cds/offering.json under fedramp_security_inbox.address (fedramp-security@samaydlette.com), with an append-only change history. Terraform, the CPO and the change-notice check all read it from there. A test fails if the address appears anywhere else under infrastructure/, scripts/ or .github/.
  • Receiving (infrastructure/fedramp-inbox.tf).
    • SES receiving runs in us-east-2, next to the at-rest CMK, the alert topic, the DLQ and the watchdog. us-east-2 is an SES receiving region, so nothing goes in us-east-1.
    • DNS: an MX record at the apex, plus Easy DKIM, a custom MAIL FROM (mail. subdomain with SPF), apex SPF -all, and DMARC p=quarantine.
    • One receipt rule, for the inbox address only. It stores the message in the inbox bucket first, then invokes the inbox function. Spam/virus scanning is on, but the verdicts are only recorded. TLS is optional. There is no bounce, stop or drop action.
    • The inbox bucket uses SSE-KMS with the at-rest CMK and a bucket key, versioning, a public access block, ACLs disabled, a TLS-only policy, server access logs, and 400-day retention. Its bucket policy lets SES write only for this account's inbox rule.
    • Because the bucket uses the at-rest CMK, members of the read-only group cannot read FedRAMP mail: that group is already denied kms:Decrypt.
  • Function (infrastructure/fedramp-inbox/, Node 22, AWS SDK from the runtime, no dependencies).
    • Classification (TFG): mail counts as FedRAMP when the From address or the envelope sender is exactly @fedramp.gov or @gsa.gov. Spam and authentication verdicts never change this.
    • Designation and deadlines (CDS, CRA): the designation comes from the subject line. Emergency and Emergency Test messages get a register item with the Class C default deadline (3:00 p.m. ET on the 2nd business day). The operator replaces it with the message's own timeframe at triage.
    • Paging (EMR, IMA): Emergency and Important messages page the operator through the existing evidence-alert topic. The page includes sender, subject, designation and deadline, never the body.
    • Acknowledgement (ACK): sent once per message, even when SES retries. It is never sent to auto-replies, bulk mail, bounces, or mail that fails sender authentication. Inbound content cannot inject a header into it.
    • Hourly check (RCV, TFG validation): compares the live rule set, rule, identity, MX record and SES account status with the Terraform configuration, and counts overdue register items.
    • The function never reads the message body. Its logs carry message IDs and outcomes only.
  • Alarms. fsi-config, fsi-overdue and fsi-errors use the watchdog's alarm-name prefix. That prefix already scopes the topic policy, the CMK's CloudWatch grant, the deploy role's alarm grant and the operators' test/silence grant, so none of those grants needed to change.
  • NOC. scripts/check-fsi-notice.py runs as the unit-test job step "FedRAMP Security Inbox change notice (AFC-CSO-NOC)". It fails a change of address unless a new history entry carries a dated fedramp_notified marker that names the channel. Compared with the merge base, it also fails if the history was edited. Known-bad fixtures are in tests/fixtures/fsi/.
  • Operator tool. scripts/fsi.py (list, show, triage, close, exercise) uses the aws CLI. It prints messages as text only: HTML is reduced to text, attachments are listed but not opened, and control and bidi characters are stripped.
  • Inventory. There is a new component type, mail_receiver (AWS::SES::ReceiptRuleSet). The rule, the activation and the sending identity fold into it as attributes. Changes:
    • The function, bucket, role and schedule have per-resource text, categorization and classification, and these match their Terraform tags (reconciliation invariant (i)).
    • The boundary map has a new fsi group, a declared fedramp actor, flows L/M/N, and SES added to the leveraged services. SES is listed in scope for FedRAMP East/West on AWS's services-in-scope page, last updated 2026-10-15.
    • The service model has a new fsi service.
    • The runtime emitter can read the inbox bucket's configuration. It reads configuration only, never objects.
  • CPO. certification_data.fedramp_security_inbox publishes the address, the rule and the runbook.
  • Docs (AI-drafted, for review).
    • New runbook: docs/runbooks/fedramp-security-inbox.md.
    • The FSI lines in docs/incident-response.md and docs/policies/ir-policy.md no longer say FSI does not apply.
    • docs/cr26-applicability.md no longer lists AFC as N/A; the rule records already treat AFC as applicable.
  • Bootstrap (infrastructure/bootstrap/main.tf).
    • Deploy role: a new fedramp-inbox-management policy covers the inbox role and PassRole, the schedule, the bucket, the domain identity, and the receipt rules. The receipt-rule actions have no resource type, so they are region-conditioned. The inbox log group is added to compliance-logs-management.
    • Operators group: a new fedramp-inbox-operator policy allows reading messages and the register, triaging and closing register items, decrypting with the at-rest key (scoped by alias), reading the SES configuration, and sending as fsi-exercise@ only.

Effect

After the bootstrap apply and a deploy:

  • The domain receives mail for the inbox address.
  • FedRAMP mail is acknowledged automatically and pages the operator.
  • The hourly check and three alarms watch the inbox.
  • The CPO publishes the inbox address.
  • The KSI signal, the SDR and the boundary map gain the inbox components.

Rule records (python3 scripts/_frr.py), before and after:

Implemented Partially Implemented Not Implemented
All applicable rules 6 → 7 93 → 100 42 → 34
MUST 0 → 1 58 → 63 26 → 20
SHOULD n/c 22 → 24 13 → 11
  • AFC-CSO-NOC: Not Implemented → Implemented. Evidence: three tests/test_fsi_notice.py tests, plus the step deploy-with-opa.yml#FedRAMP Security Inbox change notice (AFC-CSO-NOC).
  • AFC-CSO-INB, TFG, RCV, CRA, EMR, IMA, ACK: Not Implemented → Partially Implemented, with unit-test evidence. The remaining gap for each: built, but not yet live or exercised. They close after the bootstrap apply, a deploy and the dated exercise. ACK also needs SES production access.

Verified

  • make check passes (1068 passed, 1 skipped). The CI-only checks also pass: Regal, policy annotations, exceptions, wasm-safe, and the new NOC check.
  • The new tests do not exist on the base. They cover classification, look-alike domains, designators, Class C deadlines across weekends and the DST change, header injection in the acknowledgement, loop and unauthenticated-sender suppression, idempotent retry, sandbox rejection, page failure, the config-drift cases, the exercise path, the IAM statements, bucket encryption, the inventory classification against the Terraform tags, the boundary placement, and the CPO output.
  • terraform validate passes for the main and bootstrap stacks. terraform fmt is clean.
  • A read-only plan in a scratch copy, targeted at the inbox resources with empty local state, plans the new resources without error. The OPA gate passes on every inbox resource. The one violation in that targeted plan is the log bucket, whose sub-resources were outside the target.
  • Checkov passes on fedramp-inbox.tf (35 passed, 0 failed). Two inline skips carry their rationale: CKV2_AWS_62 for the bucket and CKV_AWS_355 for the account-level SES reads.
  • Live DNS: the apex had no MX, no TXT and no _dmarc record, so the new records conflict with nothing.
  • The deploy role's existing policies were read. They have no SES permissions, so the new bootstrap grants are required. The function itself is covered by the existing samaydlette-com-* Lambda grants.
  • CodeGuard ran over the diff. Its finding: a forged @gsa.gov sender could make the inbox mail attacker-chosen subject text to a government address. This is fixed: acknowledgements now require SPF/DKIM/DMARC to pass, and such mail is still registered and paged. No other findings: no secrets in env vars or code, no shell invocation, bounded regexes, validated IDs and addresses.

Residual

  • One operator and no backup reader. Pages wait while the operator is away, and the repeating overdue alarm makes that visible. The runbook names this.
  • TLS for inbound mail is optional, not required. RCV forbids refusing a sender, so in-transit encryption depends on the sender.
  • No metric covers an S3-action failure at SES itself. The hourly configuration check covers the setup, and the exercise's --smtp leg covers the path end to end.
  • The default deadline does not skip federal holidays. That can only make it earlier than the true deadline.
  • DEC-010 (no Lambda VPC) says the Lambda holds "no sensitive data". The inbox function handles FedRAMP message metadata, which is internal, so DEC-010's rationale needs review to cover it. The function still has no internet egress beyond AWS APIs. data/decisions.json was not edited.
  • tools/boundary-map/corroborate.py and website/assets/js/boundary-map.js have no mapping for mail_receiver. Both were left alone: the first is local-only and the second is website code.

Needs human

  1. Bootstrap apply, before merging. The deploy role cannot create SES, bucket or role resources without the new fedramp-inbox-management policy. Sync infrastructure/bootstrap/ to origin/main first. The plan should show only aws_iam_role_policy.fedramp_inbox_management (new), aws_iam_group_policy.operators_fedramp_inbox (new) and aws_iam_role_policy.compliance_logs (one log-group ARN added). Do not apply while a deploy is in flight.
  2. Main-stack apply, through the deploy after merge. It creates the resources listed above and updates the at-rest key policy, the log bucket policy and the runtime emitter's policy.
  3. Existing SES state in us-east-2. The operator user has no SES read, so this could not be checked. The apply activates this rule set and replaces any rule set already active in the region.
  4. SES production access. Request it in us-east-2. In the sandbox, acknowledgements to FedRAMP fail; each failure is recorded and pages through fsi-overdue, and fsi-config reports the sandbox. Receiving is not affected.
  5. The exercise, after deploy. Run python3 scripts/fsi.py exercise --reply-to <verified address> --smtp --record docs/exercises. While SES is in the sandbox, the reply-to address must be verified in SES. Commit the record it writes, then close the exercise item. This is the remaining evidence for the seven Partially Implemented records.
  6. Decisions to confirm:
    • The address name.
    • DMARC p=quarantine with no aggregate reports.
    • Apex SPF -all.
    • Triage windows: 2 h for Emergency, 24 h for Important, 72 h for general.
    • "Senior security official" means the accountable official, who is the operator.
    • Whether the CDS/CPO security_contact should become the inbox address. FedRAMP uses the Marketplace Security Email unless told otherwise.

Couldn't verify

  • SES account state in us-east-2: sandbox status, existing identities, and an active rule set. The operator credentials have no SES read.
  • That SES can write to an SSE-KMS bucket under the key-policy grant as written. The grant is scoped by kms:ViaService = S3 in the region and by the bucket's encryption context, following the documented pattern. Only a live message or the exercise's --smtp leg shows it works.
  • Whether a full (untargeted) plan in CI's compliance-check job passes. The PR run of that job shows it.
  • That FedRAMP's real mail passes SPF/DKIM/DMARC as AFC-FRP-VRE requires. The acknowledgement depends on it.

🤖 Generated with Claude Code

…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 <noreply@anthropic.com>
@sam-aydlette

Copy link
Copy Markdown
Owner Author

Reworked as a simulation and consolidated into #508.

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