From 0f5e4fb5ce5db991113a78fa0aa564725e467c6e Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 14:17:10 -0500 Subject: [PATCH 01/17] KSI catalog: FedRAMP's current KSI-to-control mappings, from the pinned rules The vendored ksi-catalog.json predated FedRAMP's 2026-10-13 mapping revision: 40 of 46 KSIs mapped fewer (or different) controls than the pinned Consolidated Rules. scripts/sync-ksi-catalog.py now derives the KSI block from the pinned rules (Class C statements where a KSI varies by class, titles from the NIST Rev5 catalog), and a test fails while they differ. Within the Moderate baseline no implementation status changes; SC-45 and SC-45.1 become shared. The projection reaches 59 controls beyond Moderate (was 10). s3.rego drops si-12, which no KSI maps any more. The SSP parity test runs on the catalog as it stood at the SSP's retirement. Co-Authored-By: Claude Opus 5.5 --- .venv | 1 + infrastructure/policy/s3.rego | 2 +- infrastructure/schemas/ksi-catalog.json | 1065 ++++++-- scripts/sync-ksi-catalog.py | 95 + .../migration/ksi-catalog-2026-11-05.json | 2206 +++++++++++++++++ tests/test_controls.py | 7 +- tests/test_inject_figures.py | 7 +- tests/test_ksi_catalog_corpus.py | 57 + 8 files changed, 3273 insertions(+), 167 deletions(-) create mode 120000 .venv create mode 100644 scripts/sync-ksi-catalog.py create mode 100644 tests/fixtures/migration/ksi-catalog-2026-11-05.json create mode 100644 tests/test_ksi_catalog_corpus.py diff --git a/.venv b/.venv new file mode 120000 index 00000000..7e6cd3e1 --- /dev/null +++ b/.venv @@ -0,0 +1 @@ +../wt-w3-frr/.venv \ No newline at end of file diff --git a/infrastructure/policy/s3.rego b/infrastructure/policy/s3.rego index 7808baef..0243ac65 100644 --- a/infrastructure/policy/s3.rego +++ b/infrastructure/policy/s3.rego @@ -25,7 +25,7 @@ import data.policy.gate # id: versioning_disabled # category: infrastructure # severity: MEDIUM -# nist_controls: [cp-9, cp-10, si-12] +# nist_controls: [cp-9, cp-10] # ksi_ids: [KSI-RPL-ABO] violations contains violation if { some r in gate.resources diff --git a/infrastructure/schemas/ksi-catalog.json b/infrastructure/schemas/ksi-catalog.json index 7353e477..4b8dc8a7 100644 --- a/infrastructure/schemas/ksi-catalog.json +++ b/infrastructure/schemas/ksi-catalog.json @@ -121,7 +121,7 @@ { "reference": "NIST SP 800-53B", "reference_url": "https://csrc.nist.gov/pubs/sp/800/53/b/upd1/final", - "description": "Section 2.5 states \"As the number of controls in [SP 800-53] grows in response to an increasingly sophisticated threat space, it is important for organizations to have the ability to describe key capabilities needed to protect organizational missions and business functions, and to subsequently select controls that\u2014if properly designed, developed, and implemented\u2014produce such capabilities. The use of capabilities simplifies how the protection problem is viewed conceptually. Using the construct of a capability provides a method of grouping controls that are employed for a common purpose or to achieve a common objective.\" This section later states \"Ultimately, authorization decisions (i.e., risk acceptance decisions) are made based on the degree to which the desired capabilities have been effectively achieved.\"" + "description": "Section 2.5 states \"As the number of controls in [SP 800-53] grows in response to an increasingly sophisticated threat space, it is important for organizations to have the ability to describe key capabilities needed to protect organizational missions and business functions, and to subsequently select controls that—if properly designed, developed, and implemented—produce such capabilities. The use of capabilities simplifies how the protection problem is viewed conceptually. Using the construct of a capability provides a method of grouping controls that are employed for a common purpose or to achieve a common objective.\" This section later states \"Ultimately, authorization decisions (i.e., risk acceptance decisions) are made based on the degree to which the desired capabilities have been effectively achieved.\"" }, { "reference": "NIST SP 800-53A", @@ -129,9 +129,9 @@ "description": "Section 3.5 states \"When organizations employ the concept of capabilities, automated and manual assessments account for all security and privacy controls that comprise the security and privacy capabilities. Assessors are aware of how the controls work together to provide such capabilities.\"" }, { - "reference": "FedRAMP Authorization Act (44 USC \u00a7 3609 (a) (1))", + "reference": "FedRAMP Authorization Act (44 USC § 3609 (a) (1))", "reference_url": "https://fedramp.gov/docs/authority/law/#a-roles-and-responsibilities", - "description": "requires that the Administrator of the General Services Administration shall \"in consultation with the [DHS] Secretary, develop, coordinate, and implement a process to support agency review, reuse, and standardization, where appropriate, of security assessments of cloud computing products and services...\" 44 USC \u00a7 3609 (c) (2) further states that \"the [GSA] Administrator shall establish a means for the automation of security assessments and reviews.\"", + "description": "requires that the Administrator of the General Services Administration shall \"in consultation with the [DHS] Secretary, develop, coordinate, and implement a process to support agency review, reuse, and standardization, where appropriate, of security assessments of cloud computing products and services...\" 44 USC § 3609 (c) (2) further states that \"the [GSA] Administrator shall establish a means for the automation of security assessments and reviews.\"", "delegation": "These responsibilities are delegated to the FedRAMP Director", "delegation_url": "https://www.gsa.gov/directives-library/gsa-delegations-of-authority-fedramp" } @@ -159,18 +159,6 @@ "moderate": true }, "controls": [ - { - "control_id": "cp-3", - "title": "Contingency Training" - }, - { - "control_id": "ir-2", - "title": "Incident Response Training" - }, - { - "control_id": "ps-6", - "title": "Access Agreements" - }, { "control_id": "at-2", "title": "Literacy Training and Awareness" @@ -183,6 +171,10 @@ "control_id": "at-2.3", "title": "Social Engineering and Mining" }, + { + "control_id": "at-3", + "title": "Role-based Training" + }, { "control_id": "at-3.5", "title": "Processing Personally Identifiable Information" @@ -191,13 +183,53 @@ "control_id": "at-4", "title": "Training Records" }, + { + "control_id": "cm-11", + "title": "User-installed Software" + }, + { + "control_id": "cp-3", + "title": "Contingency Training" + }, + { + "control_id": "cp-3.1", + "title": "Simulated Events" + }, + { + "control_id": "ir-2", + "title": "Incident Response Training" + }, + { + "control_id": "ir-2.1", + "title": "Simulated Events" + }, + { + "control_id": "ir-2.2", + "title": "Automated Training Environments" + }, { "control_id": "ir-2.3", "title": "Breach" }, { - "control_id": "at-3", - "title": "Role-based Training" + "control_id": "ir-9.2", + "title": "Training" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, + { + "control_id": "pl-4", + "title": "Rules of Behavior" + }, + { + "control_id": "pl-4.1", + "title": "Social Media and External Site/Application Usage Restrictions" + }, + { + "control_id": "ps-6", + "title": "Access Agreements" }, { "control_id": "sr-11.1", @@ -224,14 +256,26 @@ "control_id": "au-2", "title": "Event Logging" }, + { + "control_id": "ca-7.4", + "title": "Risk Monitoring" + }, { "control_id": "cm-3", "title": "Configuration Change Control" }, + { + "control_id": "cm-3.1", + "title": "Automated Documentation, Notification, and Prohibition of Changes" + }, { "control_id": "cm-3.2", "title": "Testing, Validation, and Documentation of Changes" }, + { + "control_id": "cm-3.6", + "title": "Cryptography Management" + }, { "control_id": "cm-4.2", "title": "Verification of Controls" @@ -243,10 +287,6 @@ { "control_id": "cm-8.3", "title": "Automated Unauthorized Component Detection" - }, - { - "control_id": "ma-2", - "title": "Controlled Maintenance" } ] }, @@ -345,6 +385,14 @@ "control_id": "cm-4.2", "title": "Verification of Controls" }, + { + "control_id": "cm-6.2", + "title": "Respond to Unauthorized Changes" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, { "control_id": "si-2", "title": "Flaw Remediation" @@ -370,6 +418,18 @@ "control_id": "cm-2", "title": "Baseline Configuration" }, + { + "control_id": "cm-8.4", + "title": "Accountability Information" + }, + { + "control_id": "cp-10.4", + "title": "Restore Within Time Period" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, { "control_id": "si-3", "title": "Malicious Code Protection" @@ -390,8 +450,48 @@ "title": "Independent Assessors" }, { - "control_id": "ca-7.1", - "title": "Independent Assessment" + "control_id": "cm-11", + "title": "User-installed Software" + }, + { + "control_id": "cm-6.2", + "title": "Respond to Unauthorized Changes" + }, + { + "control_id": "cp-10.4", + "title": "Restore Within Time Period" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, + { + "control_id": "sc-24", + "title": "Fail in Known State" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, + { + "control_id": "si-4.22", + "title": "Unauthorized Network Services" + }, + { + "control_id": "si-7", + "title": "Software, Firmware, and Information Integrity" + }, + { + "control_id": "si-7.1", + "title": "Integrity Checks" + }, + { + "control_id": "si-7.5", + "title": "Automated Response to Integrity Violations" + }, + { + "control_id": "si-7.7", + "title": "Integration of Detection and Response" } ] }, @@ -415,6 +515,10 @@ { "control_id": "pl-10", "title": "Baseline Selection" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" } ] }, @@ -447,6 +551,14 @@ "control_id": "ca-9", "title": "Internal System Connections" }, + { + "control_id": "sc-10", + "title": "Network Disconnect" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, { "control_id": "sc-7.3", "title": "Access Points" @@ -457,7 +569,7 @@ }, { "control_id": "sc-7.5", - "title": "Deny by Default \u2014 Allow by Exception" + "title": "Deny by Default — Allow by Exception" }, { "control_id": "sc-7.8", @@ -467,10 +579,6 @@ "control_id": "sc-8", "title": "Transmission Confidentiality and Integrity" }, - { - "control_id": "sc-10", - "title": "Network Disconnect" - }, { "control_id": "si-10", "title": "Information Input Validation" @@ -493,7 +601,16 @@ "low": true, "moderate": true }, - "controls": [] + "controls": [ + { + "control_id": "cp-2.5", + "title": "Continue Mission and Business Functions" + }, + { + "control_id": "sc-12.1", + "title": "Availability" + } + ] }, { "id": "KSI-CNA-RNT", @@ -516,9 +633,41 @@ "control_id": "cm-7.1", "title": "Periodic Review" }, + { + "control_id": "sc-7.10", + "title": "Prevent Exfiltration" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, + { + "control_id": "sc-7.20", + "title": "Dynamic Isolation and Segregation" + }, + { + "control_id": "sc-7.21", + "title": "Isolation of System Components" + }, { "control_id": "sc-7.5", - "title": "Deny by Default \u2014 Allow by Exception" + "title": "Deny by Default — Allow by Exception" + }, + { + "control_id": "si-10", + "title": "Information Input Validation" + }, + { + "control_id": "si-4.11", + "title": "Analyze Communications Traffic Anomalies" + }, + { + "control_id": "si-4.18", + "title": "Analyze Traffic and Covert Exfiltration" + }, + { + "control_id": "si-4.4", + "title": "Inbound and Outbound Communications Traffic" }, { "control_id": "si-8", @@ -535,10 +684,18 @@ "moderate": true }, "controls": [ + { + "control_id": "ir-4.2", + "title": "Dynamic Reconfiguration" + }, { "control_id": "sc-5", "title": "Denial-of-service Protection" }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, { "control_id": "si-8", "title": "Spam Protection" @@ -566,10 +723,22 @@ "control_id": "ac-17.3", "title": "Managed Access Control Points" }, + { + "control_id": "ac-4.21", + "title": "Physical or Logical Separation of Information Flows" + }, { "control_id": "ca-9", "title": "Internal System Connections" }, + { + "control_id": "cm-11", + "title": "User-installed Software" + }, + { + "control_id": "sc-10", + "title": "Network Disconnect" + }, { "control_id": "sc-4", "title": "Information in Shared System Resources" @@ -578,6 +747,14 @@ "control_id": "sc-7", "title": "Boundary Protection" }, + { + "control_id": "sc-7.20", + "title": "Dynamic Isolation and Segregation" + }, + { + "control_id": "sc-7.21", + "title": "Isolation of System Components" + }, { "control_id": "sc-7.7", "title": "Split Tunneling for Remote Devices" @@ -585,10 +762,6 @@ { "control_id": "sc-8", "title": "Transmission Confidentiality and Integrity" - }, - { - "control_id": "sc-10", - "title": "Network Disconnect" } ] } @@ -607,6 +780,10 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-2.13", + "title": "Disable Accounts for High-risk Individuals" + }, { "control_id": "ac-2.2", "title": "Automated Temporary and Emergency Account Management" @@ -615,18 +792,10 @@ "control_id": "ac-2.3", "title": "Disable Accounts" }, - { - "control_id": "ac-2.13", - "title": "Disable Accounts for High-risk Individuals" - }, { "control_id": "ac-6.7", "title": "Review of User Privileges" }, - { - "control_id": "ia-4.4", - "title": "Identify User Status" - }, { "control_id": "ia-12", "title": "Identity Proofing" @@ -642,6 +811,14 @@ { "control_id": "ia-12.5", "title": "Address Confirmation" + }, + { + "control_id": "ia-4.4", + "title": "Identify User Status" + }, + { + "control_id": "ia-8.4", + "title": "Use of Defined Profiles" } ] }, @@ -654,54 +831,70 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-2", + "title": "Account Management" + }, { "control_id": "ac-3", "title": "Access Enforcement" }, { - "control_id": "ia-5.1", - "title": "Password-based Authentication" + "control_id": "ia-2", + "title": "Identification and Authentication (Organizational Users)" }, { - "control_id": "ia-5.2", - "title": "Public Key-based Authentication" + "control_id": "ia-2.1", + "title": "Multi-factor Authentication to Privileged Accounts" }, { - "control_id": "ia-5.6", - "title": "Protection of Authenticators" + "control_id": "ia-2.2", + "title": "Multi-factor Authentication to Non-privileged Accounts" }, { - "control_id": "ia-6", - "title": "Authentication Feedback" + "control_id": "ia-2.6", + "title": "Access to Accounts —separate Device" }, { - "control_id": "ac-2", - "title": "Account Management" + "control_id": "ia-2.8", + "title": "Access to Accounts — Replay Resistant" }, { - "control_id": "ia-2", - "title": "Identification and Authentication (Organizational Users)" + "control_id": "ia-5", + "title": "Authenticator Management" }, { - "control_id": "ia-2.1", - "title": "Multi-factor Authentication to Privileged Accounts" + "control_id": "ia-5.1", + "title": "Password-based Authentication" }, { - "control_id": "ia-2.2", - "title": "Multi-factor Authentication to Non-privileged Accounts" + "control_id": "ia-5.2", + "title": "Public Key-based Authentication" }, { - "control_id": "ia-2.8", - "title": "Access to Accounts \u2014 Replay Resistant" + "control_id": "ia-5.6", + "title": "Protection of Authenticators" }, { - "control_id": "ia-5", - "title": "Authenticator Management" + "control_id": "ia-5.8", + "title": "Multiple System Accounts" + }, + { + "control_id": "ia-6", + "title": "Authentication Feedback" }, { "control_id": "ia-8", "title": "Identification and Authentication (Non-organizational Users)" }, + { + "control_id": "ia-8.2", + "title": "Acceptance of External Authenticators" + }, + { + "control_id": "ia-8.4", + "title": "Use of Defined Profiles" + }, { "control_id": "sc-23", "title": "Session Authenticity" @@ -717,26 +910,6 @@ "moderate": true }, "controls": [ - { - "control_id": "ac-2.5", - "title": "Inactivity Logout" - }, - { - "control_id": "ac-2.6", - "title": "Dynamic Privilege Management" - }, - { - "control_id": "ac-3", - "title": "Access Enforcement" - }, - { - "control_id": "ac-4", - "title": "Information Flow Enforcement" - }, - { - "control_id": "ac-6", - "title": "Least Privilege" - }, { "control_id": "ac-12", "title": "Session Termination" @@ -761,6 +934,30 @@ "control_id": "ac-17.3", "title": "Managed Access Control Points" }, + { + "control_id": "ac-18.4", + "title": "Restrict Configurations by Users" + }, + { + "control_id": "ac-2.11", + "title": "Usage Conditions" + }, + { + "control_id": "ac-2.5", + "title": "Inactivity Logout" + }, + { + "control_id": "ac-2.6", + "title": "Dynamic Privilege Management" + }, + { + "control_id": "ac-2.7", + "title": "Privileged User Accounts" + }, + { + "control_id": "ac-2.9", + "title": "Restrictions on Use of Shared and Group Accounts" + }, { "control_id": "ac-20", "title": "Use of External Systems" @@ -769,14 +966,62 @@ "control_id": "ac-20.1", "title": "Limits on Authorized Use" }, + { + "control_id": "ac-21", + "title": "Information Sharing" + }, + { + "control_id": "ac-3", + "title": "Access Enforcement" + }, + { + "control_id": "ac-4", + "title": "Information Flow Enforcement" + }, + { + "control_id": "ac-6", + "title": "Least Privilege" + }, + { + "control_id": "ac-6.3", + "title": "Network Access to Privileged Commands" + }, + { + "control_id": "ac-6.8", + "title": "Privilege Levels for Code Execution" + }, + { + "control_id": "au-12.3", + "title": "Changes by Authorized Individuals" + }, + { + "control_id": "au-6.7", + "title": "Permitted Actions" + }, { "control_id": "cm-2.7", "title": "Configure Systems and Components for High-risk Areas" }, + { + "control_id": "cm-5.1", + "title": "Automated Access Enforcement and Audit Records" + }, + { + "control_id": "cm-5.5", + "title": "Privilege Limitation for Production and Operation" + }, + { + "control_id": "cm-7.2", + "title": "Prevent Program Execution" + }, { "control_id": "cm-9", "title": "Configuration Management Plan" }, + { + "control_id": "ia-11", + "title": "Re-authentication" + }, { "control_id": "ia-2", "title": "Identification and Authentication (Organizational Users)" @@ -802,8 +1047,12 @@ "title": "Protection of Authenticators" }, { - "control_id": "ia-11", - "title": "Re-authentication" + "control_id": "ir-4.6", + "title": "Insider Threats" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" }, { "control_id": "ps-2", @@ -826,8 +1075,12 @@ "title": "Access Agreements" }, { - "control_id": "sc-4", - "title": "Information in Shared System Resources" + "control_id": "ra-5.5", + "title": "Privileged Access" + }, + { + "control_id": "sc-2", + "title": "Separation of System and User Functionality" }, { "control_id": "sc-20", @@ -845,13 +1098,25 @@ "control_id": "sc-23", "title": "Session Authenticity" }, + { + "control_id": "sc-3", + "title": "Security Function Isolation" + }, { "control_id": "sc-39", "title": "Process Isolation" }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, { "control_id": "si-3", "title": "Malicious Code Protection" + }, + { + "control_id": "si-4.19", + "title": "Risk for Individuals" } ] }, @@ -864,6 +1129,14 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-17", + "title": "Remote Access" + }, + { + "control_id": "ac-17.4", + "title": "Privileged Commands and Access" + }, { "control_id": "ac-2", "title": "Account Management" @@ -872,6 +1145,10 @@ "control_id": "ac-2.1", "title": "Automated System Account Management" }, + { + "control_id": "ac-2.11", + "title": "Usage Conditions" + }, { "control_id": "ac-2.2", "title": "Automated Temporary and Emergency Account Management" @@ -888,6 +1165,18 @@ "control_id": "ac-2.6", "title": "Dynamic Privilege Management" }, + { + "control_id": "ac-2.7", + "title": "Privileged User Accounts" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "ac-21", + "title": "Information Sharing" + }, { "control_id": "ac-3", "title": "Access Enforcement" @@ -908,10 +1197,18 @@ "control_id": "ac-6.1", "title": "Authorize Access to Security Functions" }, + { + "control_id": "ac-6.10", + "title": "Prohibit Non-privileged Users from Executing Privileged Functions" + }, { "control_id": "ac-6.2", "title": "Non-privileged Access for Nonsecurity Functions" }, + { + "control_id": "ac-6.3", + "title": "Network Access to Privileged Commands" + }, { "control_id": "ac-6.5", "title": "Privileged Accounts" @@ -921,33 +1218,45 @@ "title": "Review of User Privileges" }, { - "control_id": "ac-6.9", - "title": "Log Use of Privileged Functions" + "control_id": "ac-6.8", + "title": "Privilege Levels for Code Execution" }, { - "control_id": "ac-6.10", - "title": "Prohibit Non-privileged Users from Executing Privileged Functions" + "control_id": "ac-6.9", + "title": "Log Use of Privileged Functions" }, { "control_id": "ac-7", "title": "Unsuccessful Logon Attempts" }, { - "control_id": "ac-20.1", - "title": "Limits on Authorized Use" + "control_id": "au-10", + "title": "Non-repudiation" }, { - "control_id": "ac-17", - "title": "Remote Access" + "control_id": "au-12.3", + "title": "Changes by Authorized Individuals" }, { "control_id": "au-9.4", "title": "Access by Subset of Privileged Users" }, + { + "control_id": "ca-3.6", + "title": "Transfer Authorizations" + }, { "control_id": "cm-5", "title": "Access Restrictions for Change" }, + { + "control_id": "cm-5.1", + "title": "Automated Access Enforcement and Audit Records" + }, + { + "control_id": "cm-5.5", + "title": "Privilege Limitation for Production and Operation" + }, { "control_id": "cm-7", "title": "Least Functionality" @@ -958,7 +1267,7 @@ }, { "control_id": "cm-7.5", - "title": "Authorized Software \u2014 Allow-by-exception" + "title": "Authorized Software — Allow-by-exception" }, { "control_id": "cm-9", @@ -976,6 +1285,10 @@ "control_id": "ia-7", "title": "Cryptographic Module Authentication" }, + { + "control_id": "ir-4.6", + "title": "Insider Threats" + }, { "control_id": "ps-2", "title": "Position Risk Designation" @@ -1012,6 +1325,10 @@ "control_id": "sc-23", "title": "Session Authenticity" }, + { + "control_id": "sc-3", + "title": "Security Function Isolation" + }, { "control_id": "sc-39", "title": "Process Isolation" @@ -1035,6 +1352,10 @@ "control_id": "ac-2.2", "title": "Automated Temporary and Emergency Account Management" }, + { + "control_id": "ac-2.9", + "title": "Restrictions on Use of Shared and Group Accounts" + }, { "control_id": "ac-4", "title": "Information Flow Enforcement" @@ -1043,6 +1364,14 @@ "control_id": "ac-6.5", "title": "Privileged Accounts" }, + { + "control_id": "au-10", + "title": "Non-repudiation" + }, + { + "control_id": "ia-2.5", + "title": "Individual Authentication with Group Authentication" + }, { "control_id": "ia-3", "title": "Device Identification and Authentication" @@ -1075,17 +1404,45 @@ "title": "Automated System Account Management" }, { - "control_id": "ac-2.3", - "title": "Disable Accounts" + "control_id": "ac-2.11", + "title": "Usage Conditions" + }, + { + "control_id": "ac-2.12", + "title": "Account Monitoring for Atypical Usage" }, { "control_id": "ac-2.13", "title": "Disable Accounts for High-risk Individuals" }, + { + "control_id": "ac-2.3", + "title": "Disable Accounts" + }, { "control_id": "ac-7", "title": "Unsuccessful Logon Attempts" }, + { + "control_id": "au-6.5", + "title": "Integrated Analysis of Audit Records" + }, + { + "control_id": "cm-5.1", + "title": "Automated Access Enforcement and Audit Records" + }, + { + "control_id": "cm-6.2", + "title": "Respond to Unauthorized Changes" + }, + { + "control_id": "ir-4.2", + "title": "Dynamic Reconfiguration" + }, + { + "control_id": "ir-4.6", + "title": "Insider Threats" + }, { "control_id": "ps-4", "title": "Personnel Termination" @@ -1093,6 +1450,30 @@ { "control_id": "ps-8", "title": "Personnel Sanctions" + }, + { + "control_id": "si-4", + "title": "System Monitoring" + }, + { + "control_id": "si-4.1", + "title": "System-wide Intrusion Detection System" + }, + { + "control_id": "si-4.19", + "title": "Risk for Individuals" + }, + { + "control_id": "si-4.20", + "title": "Privileged Users" + }, + { + "control_id": "si-4.22", + "title": "Unauthorized Network Services" + }, + { + "control_id": "si-4.4", + "title": "Inbound and Outbound Communications Traffic" } ] } @@ -1123,9 +1504,17 @@ "control_id": "ir-4.1", "title": "Automated Incident Handling Processes" }, + { + "control_id": "ir-5.1", + "title": "Automated Tracking, Data Collection, and Analysis" + }, { "control_id": "ir-8", "title": "Incident Response Plan" + }, + { + "control_id": "ir-9.3", + "title": "Post-spill Operations" } ] }, @@ -1146,6 +1535,10 @@ "control_id": "ir-4.1", "title": "Automated Incident Handling Processes" }, + { + "control_id": "ir-4.11", + "title": "Integrated Incident Response Team" + }, { "control_id": "ir-6", "title": "Incident Reporting" @@ -1174,6 +1567,10 @@ "control_id": "ir-8.1", "title": "Breaches" }, + { + "control_id": "ir-9.3", + "title": "Post-spill Operations" + }, { "control_id": "si-4.5", "title": "System-generated Alerts" @@ -1201,13 +1598,29 @@ "control_id": "ir-4.1", "title": "Automated Incident Handling Processes" }, + { + "control_id": "ir-4.11", + "title": "Integrated Incident Response Team" + }, + { + "control_id": "ir-4.4", + "title": "Information Correlation" + }, { "control_id": "ir-5", "title": "Incident Monitoring" }, + { + "control_id": "ir-5.1", + "title": "Automated Tracking, Data Collection, and Analysis" + }, { "control_id": "ir-8", "title": "Incident Response Plan" + }, + { + "control_id": "ra-5.8", + "title": "Review Historic Audit Logs" } ] } @@ -1226,6 +1639,14 @@ "moderate": true }, "controls": [ + { + "control_id": "au-12.3", + "title": "Changes by Authorized Individuals" + }, + { + "control_id": "au-6.7", + "title": "Permitted Actions" + }, { "control_id": "si-11", "title": "Error Handling" @@ -1241,6 +1662,10 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, { "control_id": "ca-7", "title": "Continuous Monitoring" @@ -1253,6 +1678,14 @@ "control_id": "cm-6", "title": "Configuration Settings" }, + { + "control_id": "cm-6.1", + "title": "Automated Management, Application, and Verification" + }, + { + "control_id": "ra-3", + "title": "Risk Assessment" + }, { "control_id": "si-7.7", "title": "Integration of Detection and Response" @@ -1268,33 +1701,57 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-17.1", + "title": "Monitoring and Control" + }, { "control_id": "ac-2.4", "title": "Automated Audit Actions" }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, { "control_id": "ac-6.9", "title": "Log Use of Privileged Functions" }, { - "control_id": "ac-17.1", - "title": "Monitoring and Control" + "control_id": "au-10", + "title": "Non-repudiation" + }, + { + "control_id": "au-12", + "title": "Audit Record Generation" + }, + { + "control_id": "au-2", + "title": "Event Logging" + }, + { + "control_id": "au-7", + "title": "Audit Record Reduction and Report Generation" + }, + { + "control_id": "au-7.1", + "title": "Automatic Processing" }, { - "control_id": "ac-20.1", - "title": "Limits on Authorized Use" + "control_id": "cm-5.1", + "title": "Automated Access Enforcement and Audit Records" }, { - "control_id": "au-2", - "title": "Event Logging" + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" }, { - "control_id": "au-7.1", - "title": "Automatic Processing" + "control_id": "si-4.19", + "title": "Risk for Individuals" }, { - "control_id": "au-12", - "title": "Audit Record Generation" + "control_id": "si-4.20", + "title": "Privileged Users" }, { "control_id": "si-4.4", @@ -1327,6 +1784,14 @@ "control_id": "ac-20.1", "title": "Limits on Authorized Use" }, + { + "control_id": "au-11", + "title": "Audit Record Retention" + }, + { + "control_id": "au-12.1", + "title": "System-wide and Time-correlated Audit Trail" + }, { "control_id": "au-2", "title": "Event Logging" @@ -1347,6 +1812,10 @@ "control_id": "au-5", "title": "Response to Audit Logging Process Failures" }, + { + "control_id": "au-5.1", + "title": "Storage Capacity Warning" + }, { "control_id": "au-6.1", "title": "Automated Process Integration" @@ -1355,6 +1824,14 @@ "control_id": "au-6.3", "title": "Correlate Audit Record Repositories" }, + { + "control_id": "au-6.4", + "title": "Central Review and Analysis" + }, + { + "control_id": "au-6.5", + "title": "Integrated Analysis of Audit Records" + }, { "control_id": "au-7", "title": "Audit Record Reduction and Report Generation" @@ -1371,14 +1848,14 @@ "control_id": "au-9", "title": "Protection of Audit Information" }, - { - "control_id": "au-11", - "title": "Audit Record Retention" - }, { "control_id": "ir-4.1", "title": "Automated Incident Handling Processes" }, + { + "control_id": "si-4.16", + "title": "Correlate Monitoring Information" + }, { "control_id": "si-4.2", "title": "Automated Tools and Mechanisms for Real-time Analysis" @@ -1386,10 +1863,6 @@ { "control_id": "si-4.4", "title": "Inbound and Outbound Communications Traffic" - }, - { - "control_id": "si-7.7", - "title": "Integration of Detection and Response" } ] }, @@ -1422,10 +1895,22 @@ "control_id": "au-6.1", "title": "Automated Process Integration" }, + { + "control_id": "au-7", + "title": "Audit Record Reduction and Report Generation" + }, + { + "control_id": "ra-5.8", + "title": "Review Historic Audit Logs" + }, { "control_id": "si-4", "title": "System Monitoring" }, + { + "control_id": "si-4.19", + "title": "Risk for Individuals" + }, { "control_id": "si-4.4", "title": "Inbound and Outbound Communications Traffic" @@ -1447,13 +1932,21 @@ "moderate": true }, "controls": [ + { + "control_id": "cm-12", + "title": "Information Location" + }, + { + "control_id": "cm-12.1", + "title": "Automated Tools to Support Information Location" + }, { "control_id": "cm-2.2", "title": "Automation Support for Accuracy and Currency" }, { "control_id": "cm-7.5", - "title": "Authorized Software \u2014 Allow-by-exception" + "title": "Authorized Software — Allow-by-exception" }, { "control_id": "cm-8", @@ -1464,12 +1957,12 @@ "title": "Updates During Installation and Removal" }, { - "control_id": "cm-12", - "title": "Information Location" + "control_id": "cm-8.2", + "title": "Automated Maintenance" }, { - "control_id": "cm-12.1", - "title": "Automated Tools to Support Information Location" + "control_id": "cm-8.4", + "title": "Accountability Information" }, { "control_id": "cp-2.8", @@ -1504,6 +1997,10 @@ "control_id": "ca-2", "title": "Control Assessments" }, + { + "control_id": "ca-2.2", + "title": "Specialized Assessments" + }, { "control_id": "cp-2.1", "title": "Coordinate with Related Plans" @@ -1516,6 +2013,10 @@ "control_id": "ir-3.2", "title": "Coordination with Related Plans" }, + { + "control_id": "ir-4.11", + "title": "Integrated Incident Response Team" + }, { "control_id": "pm-3", "title": "Information Security and Privacy Resources" @@ -1555,6 +2056,10 @@ "control_id": "cm-3.4", "title": "Security and Privacy Representatives" }, + { + "control_id": "ia-5.7", + "title": "No Embedded Unencrypted Static Authenticators" + }, { "control_id": "pl-8", "title": "Security and Privacy Architectures" @@ -1563,6 +2068,10 @@ "control_id": "pm-7", "title": "Enterprise Architecture" }, + { + "control_id": "ra-9", + "title": "Criticality Analysis" + }, { "control_id": "sa-3", "title": "System Development Life Cycle" @@ -1571,14 +2080,14 @@ "control_id": "sa-8", "title": "Security and Privacy Engineering Principles" }, - { - "control_id": "sc-4", - "title": "Information in Shared System Resources" - }, { "control_id": "sc-18", "title": "Mobile Code" }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, { "control_id": "si-10", "title": "Information Input Validation" @@ -1642,10 +2151,6 @@ { "control_id": "cp-10.2", "title": "Transaction Recovery" - }, - { - "control_id": "si-12", - "title": "Information Management and Retention" } ] }, @@ -1752,6 +2257,10 @@ "moderate": true }, "controls": [ + { + "control_id": "cp-10", + "title": "System Recovery and Reconstitution" + }, { "control_id": "cp-2.1", "title": "Coordinate with Related Plans" @@ -1780,10 +2289,6 @@ "control_id": "cp-9.1", "title": "Testing for Reliability and Integrity" }, - { - "control_id": "cp-10", - "title": "System Recovery and Reconstitution" - }, { "control_id": "ir-3", "title": "Incident Response Testing" @@ -1791,6 +2296,14 @@ { "control_id": "ir-3.2", "title": "Coordination with Related Plans" + }, + { + "control_id": "ir-9.3", + "title": "Post-spill Operations" + }, + { + "control_id": "sc-12.1", + "title": "Availability" } ] } @@ -1803,23 +2316,31 @@ { "id": "KSI-SCR-MIT", "name": "Mitigating Supply Chain Risk", - "statement": "Persistently identify, review, and mitigate potential supply chain risks.", + "statement": "Potential supply chain risks are persistently identified, reviewed, and mitigated.", "impact": { "low": true, "moderate": true }, "controls": [ + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, { "control_id": "ac-20", "title": "Use of External Systems" }, { - "control_id": "ra-3.1", - "title": "Supply Chain Risk Assessment" + "control_id": "ca-7.4", + "title": "Risk Monitoring" }, { - "control_id": "sa-9", - "title": "External System Services" + "control_id": "ra-3", + "title": "Risk Assessment" + }, + { + "control_id": "ra-3.1", + "title": "Supply Chain Risk Assessment" }, { "control_id": "sa-10", @@ -1829,33 +2350,101 @@ "control_id": "sa-11", "title": "Developer Testing and Evaluation" }, + { + "control_id": "sa-11.1", + "title": "Static Code Analysis" + }, + { + "control_id": "sa-11.2", + "title": "Threat Modeling and Vulnerability Analyses" + }, + { + "control_id": "sa-15", + "title": "Development Process, Standards, and Tools" + }, { "control_id": "sa-15.3", "title": "Criticality Analysis" }, + { + "control_id": "sa-16", + "title": "Developer-provided Training" + }, + { + "control_id": "sa-17", + "title": "Developer Security and Privacy Architecture and Design" + }, + { + "control_id": "sa-21", + "title": "Developer Screening" + }, { "control_id": "sa-22", "title": "Unsupported System Components" }, { - "control_id": "si-7.1", - "title": "Integrity Checks" + "control_id": "sa-4", + "title": "Acquisition Process" }, { - "control_id": "sr-5", - "title": "Acquisition Strategies, Tools, and Methods" + "control_id": "sa-4.1", + "title": "Functional Properties of Controls" }, { - "control_id": "sr-6", - "title": "Supplier Assessments and Reviews" + "control_id": "sa-4.2", + "title": "Design and Implementation Information for Controls" }, { - "control_id": "ca-7.4", - "title": "Risk Monitoring" + "control_id": "sa-4.5", + "title": "System, Component, and Service Configurations" + }, + { + "control_id": "sa-4.9", + "title": "Functions, Ports, Protocols, and Services in Use" + }, + { + "control_id": "sa-9", + "title": "External System Services" + }, + { + "control_id": "sa-9.1", + "title": "Risk Assessments and Organizational Approvals" + }, + { + "control_id": "sa-9.2", + "title": "Identification of Functions, Ports, Protocols, and Services" + }, + { + "control_id": "sa-9.5", + "title": "Processing, Storage, and Service Location" }, { "control_id": "sc-18", "title": "Mobile Code" + }, + { + "control_id": "si-7.1", + "title": "Integrity Checks" + }, + { + "control_id": "si-7.15", + "title": "Code Authentication" + }, + { + "control_id": "sr-2", + "title": "Supply Chain Risk Management Plan" + }, + { + "control_id": "sr-3", + "title": "Supply Chain Controls and Processes" + }, + { + "control_id": "sr-5", + "title": "Acquisition Strategies, Tools, and Methods" + }, + { + "control_id": "sr-6", + "title": "Supplier Assessments and Reviews" } ] }, @@ -1868,10 +2457,18 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, { "control_id": "ac-20", "title": "Use of External Systems" }, + { + "control_id": "ca-2.3", + "title": "Leveraging Results from External Organizations" + }, { "control_id": "ca-3", "title": "Information Exchange" @@ -1884,6 +2481,10 @@ "control_id": "ps-7", "title": "External Personnel Security" }, + { + "control_id": "ra-3", + "title": "Risk Assessment" + }, { "control_id": "ra-5", "title": "Vulnerability Monitoring and Scanning" @@ -1896,6 +2497,10 @@ "control_id": "si-5", "title": "Security Alerts, Advisories, and Directives" }, + { + "control_id": "sr-3", + "title": "Supply Chain Controls and Processes" + }, { "control_id": "sr-5", "title": "Acquisition Strategies, Tools, and Methods" @@ -1929,6 +2534,10 @@ "control_id": "ac-2.4", "title": "Automated Audit Actions" }, + { + "control_id": "ac-6.8", + "title": "Privilege Levels for Code Execution" + }, { "control_id": "cm-2", "title": "Baseline Configuration" @@ -1949,18 +2558,30 @@ "control_id": "cm-7.1", "title": "Periodic Review" }, - { - "control_id": "pl-9", - "title": "Central Management" - }, { "control_id": "pl-10", "title": "Baseline Selection" }, + { + "control_id": "pl-9", + "title": "Central Management" + }, { "control_id": "sa-5", "title": "System Documentation" }, + { + "control_id": "sc-45", + "title": "System Time Synchronization" + }, + { + "control_id": "sc-45.1", + "title": "Synchronization with Authoritative Time Source" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, { "control_id": "si-5", "title": "Security Alerts, Advisories, and Directives" @@ -1996,6 +2617,10 @@ "control_id": "sc-12", "title": "Cryptographic Key Establishment and Management" }, + { + "control_id": "sc-12.1", + "title": "Availability" + }, { "control_id": "sc-17", "title": "Public Key Infrastructure Certificates" @@ -2012,29 +2637,41 @@ }, "controls": [ { - "control_id": "cm-7.1", - "title": "Periodic Review" + "control_id": "ca-7.4", + "title": "Risk Monitoring" }, { "control_id": "cm-12.1", "title": "Automated Tools to Support Information Location" }, { - "control_id": "ma-2", - "title": "Controlled Maintenance" + "control_id": "cm-5.5", + "title": "Privilege Limitation for Production and Operation" + }, + { + "control_id": "cm-7.1", + "title": "Periodic Review" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" }, { "control_id": "pl-8", "title": "Security and Privacy Architectures" }, { - "control_id": "sc-7", - "title": "Boundary Protection" + "control_id": "ra-3", + "title": "Risk Assessment" }, { "control_id": "sc-39", "title": "Process Isolation" }, + { + "control_id": "sc-7", + "title": "Boundary Protection" + }, { "control_id": "si-2.2", "title": "Automated Flaw Remediation Status" @@ -2058,9 +2695,25 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, + { + "control_id": "sc-12.1", + "title": "Availability" + }, { "control_id": "sc-4", "title": "Information in Shared System Resources" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" } ] }, @@ -2073,6 +2726,10 @@ "moderate": true }, "controls": [ + { + "control_id": "ir-9", + "title": "Information Spillage Response" + }, { "control_id": "si-12.3", "title": "Information Disposal" @@ -2080,6 +2737,14 @@ { "control_id": "si-18.4", "title": "Individual Requests" + }, + { + "control_id": "si-8", + "title": "Spam Protection" + }, + { + "control_id": "si-8.2", + "title": "Automatic Updates" } ] }, @@ -2093,25 +2758,33 @@ }, "controls": [ { - "control_id": "ac-1", - "title": "Policy and Procedures" + "control_id": "ac-11", + "title": "Device Lock" + }, + { + "control_id": "ac-11.1", + "title": "Pattern-hiding Displays" }, { "control_id": "ac-17.2", "title": "Protection of Confidentiality and Integrity Using Encryption" }, { - "control_id": "cp-9.8", - "title": "Cryptographic Protection" + "control_id": "ac-19.5", + "title": "Full Device or Container-based Encryption" }, { - "control_id": "sc-8", - "title": "Transmission Confidentiality and Integrity" + "control_id": "ac-21", + "title": "Information Sharing" }, { - "control_id": "sc-8.1", + "control_id": "cp-9.8", "title": "Cryptographic Protection" }, + { + "control_id": "ir-9.4", + "title": "Exposure to Unauthorized Personnel" + }, { "control_id": "sc-13", "title": "Cryptographic Protection" @@ -2139,6 +2812,26 @@ { "control_id": "sc-28.1", "title": "Cryptographic Protection" + }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, + { + "control_id": "sc-7.18", + "title": "Fail Secure" + }, + { + "control_id": "sc-8", + "title": "Transmission Confidentiality and Integrity" + }, + { + "control_id": "sc-8.1", + "title": "Cryptographic Protection" + }, + { + "control_id": "si-4.18", + "title": "Analyze Traffic and Covert Exfiltration" } ] }, @@ -2151,10 +2844,30 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-10", + "title": "Concurrent Session Control" + }, + { + "control_id": "ac-17.4", + "title": "Privileged Commands and Access" + }, + { + "control_id": "ac-18", + "title": "Wireless Access" + }, + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, { "control_id": "sc-23", "title": "Session Authenticity" }, + { + "control_id": "si-4.22", + "title": "Unauthorized Network Services" + }, { "control_id": "si-7.1", "title": "Integrity Checks" @@ -2170,6 +2883,26 @@ "moderate": true }, "controls": [ + { + "control_id": "ac-17.4", + "title": "Privileged Commands and Access" + }, + { + "control_id": "ac-18", + "title": "Wireless Access" + }, + { + "control_id": "ac-19", + "title": "Access Control for Mobile Devices" + }, + { + "control_id": "au-9.3", + "title": "Cryptographic Protection" + }, + { + "control_id": "cm-14", + "title": "Signed Components" + }, { "control_id": "cm-2.2", "title": "Automation Support for Accuracy and Currency" @@ -2194,9 +2927,17 @@ "control_id": "si-7.1", "title": "Integrity Checks" }, + { + "control_id": "si-7.15", + "title": "Code Authentication" + }, { "control_id": "sr-10", "title": "Inspection of Systems or Components" + }, + { + "control_id": "sr-11", + "title": "Component Authenticity" } ] } diff --git a/scripts/sync-ksi-catalog.py b/scripts/sync-ksi-catalog.py new file mode 100644 index 00000000..199c3a8d --- /dev/null +++ b/scripts/sync-ksi-catalog.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +"""Keep infrastructure/schemas/ksi-catalog.json equal to the pinned FedRAMP rules. + +The catalog's KSI block (IDs, names, statements and KSI->control mappings) is +FedRAMP's, so it is derived from the vendored, hash-checked Consolidated Rules +(scripts/_rules.py), never edited by hand. FedRAMP revises mappings between +releases (for example on 2026-10-13); re-pinning the rules and re-running this +script carries the change, and tests/test_ksi_catalog_corpus.py fails while +the two disagree. + +Control titles come from the vendored NIST SP 800-53 Rev5 catalog. The per-KSI impact flags are the catalog's +own (the corpus does not carry them) and are kept. + + sync-ksi-catalog.py rewrite the catalog + sync-ksi-catalog.py --check exit 1 if it differs from the corpus +""" + +import argparse +import json +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +CATALOG = REPO / "infrastructure" / "schemas" / "ksi-catalog.json" +NIST = REPO / "data" / "catalogs" / "NIST_SP-800-53_rev5_catalog.json" + + +def _fail(msg): + raise SystemExit(f"::error::KSI catalog: {msg} (fail-closed)") + + +def _titles(): + out = {} + + def walk(group): + for c in group.get("controls", []) or []: + out[c["id"]] = c["title"] + walk(c) + for g in group.get("groups", []) or []: + walk(g) + walk(json.loads(NIST.read_text())["catalog"]) + return out + + +def derive(catalog, rules_dir=_rules.RULES_DIR): + """The catalog with its KSI block rebuilt from the pinned corpus.""" + rules, _ = _rules.load_rules(rules_dir) + titles = _titles() + old_impact = {i["id"]: i.get("impact") for f in catalog.get("KSI", {}).values() + for i in f.get("indicators", [])} + ksi = {} + for fam_id, fam in rules["KSI"].items(): + indicators = [] + for kid, k in fam["indicators"].items(): + controls = [] + for c in k.get("controls", []) or []: + cid = str(c).lower() + if cid not in titles: + _fail(f"{kid} maps {cid}, which is not in the NIST SP 800-53 Rev5 catalog") + controls.append({"control_id": cid, "title": titles[cid]}) + if kid not in old_impact: + _fail(f"{kid} is new in the corpus; set its impact flags in the catalog first") + # Class C's statement where the KSI varies by class (five do). + statement = ((k.get("varies_by_class") or {}).get(_rules.CERT_CLASS) or k).get("statement") + if not isinstance(statement, str): + _fail(f"{kid} has no Class {_rules.CERT_CLASS.upper()} statement") + indicators.append({"id": kid, "name": k["name"], "statement": statement, + "impact": old_impact[kid], "controls": controls}) + ksi[fam_id] = {"id": fam["id"], "name": fam["name"], "indicators": indicators} + out = dict(catalog) + out["KSI"] = ksi + return out + + +def main(argv=None): + ap = argparse.ArgumentParser() + ap.add_argument("--check", action="store_true") + a = ap.parse_args(argv) + current = json.loads(CATALOG.read_text()) + want = derive(current) + if a.check: + if want != current: + print("::error::infrastructure/schemas/ksi-catalog.json differs from the pinned FedRAMP rules; " + "run scripts/sync-ksi-catalog.py and review the diff") + return 1 + return 0 + CATALOG.write_text(json.dumps(want, indent=2, ensure_ascii=False) + "\n") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/fixtures/migration/ksi-catalog-2026-11-05.json b/tests/fixtures/migration/ksi-catalog-2026-11-05.json new file mode 100644 index 00000000..7353e477 --- /dev/null +++ b/tests/fixtures/migration/ksi-catalog-2026-11-05.json @@ -0,0 +1,2206 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "FedRAMP.schema.json", + "info": { + "name": "Key Security Indicators", + "short_name": "KSI", + "effective": { + "rev5": { + "is": "no" + }, + "20x": { + "is": "required", + "signup_url": "https://www.fedramp.gov/20x/phase-two/participate/", + "current_status": "Phase 2 Pilot", + "start_date": "2025-11-18", + "end_date": "2026-03-31", + "comments": [ + "Phase 1 pilot authorizations have one year from authorization to fully address this process but must demonstrate continuous quarterly progress.", + "Phase 2 Pilot participants must demonstrate significant progress towards addressing this process prior to submission for authorization review." + ] + } + }, + "releases": [ + { + "id": "26.06", + "published_date": "2026-06-24", + "description": "Consolidated Rules for 2026 (official launch). Key Security Indicators renumbered to mnemonic IDs; the AFR (Authorization by FedRAMP) family was retired and TPR (Third-Party) was renamed SCR (Supply Chain Risk). Rebuilt from the published markdown corpus by scripts/staged/build-ksi-catalog.py." + }, + { + "id": "25.12A", + "published_date": "2025-12-29", + "description": "This release updates a significant number of KSIs to improve clarity and expectations; in general the measures required to meet each KSI remain unchanged but these updates should make it easier to address them. In additional, some KSIs have been retired.", + "public_comment": false + }, + { + "id": "25.11C", + "published_date": "2025-12-01", + "description": "No effective/material changes; adjusted some KSI-AFR indcators to reference \"process\" instead of \"standard\" and added a note to KSI-AFR-02 addressing the potential infinite loop.", + "public_comment": false, + "machine_readable_link": "https://raw.githubusercontent.com/FedRAMP/docs/ced2160b22455ed26a11bf697be8f0ae3e1e5dff/data/FRMR.KSI.key-security-indicators.json" + }, + { + "id": "25.11B", + "published_date": "2025-11-24", + "description": "No material changes to content; updated JSON structure with additional information about Rev5 application added.", + "public_comment": false, + "machine_readable_link": "https://raw.githubusercontent.com/FedRAMP/docs/a37618fccf49d6b3406d90edf2125dc6cfcba140/data/FRMR.KSI.key-security-indicators.json" + }, + { + "id": "25.11A", + "published_date": "2025-11-18", + "description": "Updates Key Security Indicators for the FedRAMP 20x Phase Two pilot, including underlying structural changes to machine-readable docs; Renamed KSI \"indicator\" property to \"theme\" and KSI \"requirements\" property to \"indicators\" to match current naming conventions..", + "public_comment": true, + "related_rfcs": [ + { + "start_date": "2025-09-10", + "end_date": "2025-11-17", + "id": "0015", + "url": "https://www.fedramp.gov/rfcs/0015/", + "discussion_url": "https://github.com/FedRAMP/community/discussions/84", + "short_name": "rfc-0015-recommended-secure-configuration", + "full_name": "FedRAMP RFC-0015: Recommended Secure Configuration Standard" + } + ], + "machine_readable_link": "https://raw.githubusercontent.com/FedRAMP/docs/3291fa1952f5b68eaf1a815a8ef1846ae8ca9e2f/data/FRMR.KSI.key-security-indicators.json" + }, + { + "id": "25.10A", + "published_date": "2025-10-17", + "description": "Minor updates to improve clarity; switch from federal information to federal customer data; add impact level metadata; no substantive changes.", + "public_comment": false, + "machine_readable_link": null + }, + { + "id": "25.05D", + "published_date": "2025-08-24", + "description": "Minor non-breaking updates to align term definitions and highlighted terms across updated materials (no changes to KSIs, definitions are now in FRD-ALL).", + "public_comment": false, + "machine_readable_link": null + }, + { + "id": "25.05C", + "published_date": "2025-06-28", + "description": "Key Security Indicators in this release are unchanged from previously releases. 25.05C adds references for each KSI to underlying SP 800-53 controls.", + "public_comment": false, + "machine_readable_link": null + }, + { + "id": "25.05B", + "published_date": "2025-06-18", + "description": "Initial release of Key Security Indicators from 25.05; the previous 25.05A release contained errors during conversion to JSON that are fixed in this release, the KSIs should now be identical to the original 25.05 paper release of the KSIs released on 2025-05-30. FRR-KSI-AY rules were converted to FRR-KSI rules, but otherwise unchanged.", + "public_comment": false, + "machine_readable_link": null + }, + { + "id": "25.05A", + "published_date": "2025-05-30", + "description": "Initial release of Key Security Indicators", + "public_comment": true, + "related_rfcs": [ + { + "start_date": "2025-04-24", + "end_date": "2025-05-24", + "id": "0006", + "url": "https://www.fedramp.gov/rfcs/0006/", + "discussion_url": "https://github.com/FedRAMP/community/discussions/3", + "short_name": "rfc-0006-key-security-indicators", + "full_name": "FedRAMP RFC-0006: 20x Phase One Key Security Indicators" + } + ], + "machine_readable_link": null + } + ], + "front_matter": { + "authority": [ + { + "reference": "OMB Circular A-130", + "reference_url": "https://whitehouse.gov/wp-content/uploads/legacy_drupal_files/omb/circulars/A130/a130revised.pdf", + "description": "Appendix I states \"Agencies may also develop overlays for specific types of information or communities of interest (e.g., all web-based applications, all health care-related systems) as part of the security control selection process. Overlays provide a specification of security or privacy controls, control enhancements, supplemental guidance, and other supporting information as part of the tailoring process, that is intended to complement (and further refine) security control baselines. The overlay may be more stringent or less stringent than the original security control baseline and can be applied to multiple information systems.\"" + }, + { + "reference": "NIST SP 800-53B", + "reference_url": "https://csrc.nist.gov/pubs/sp/800/53/b/upd1/final", + "description": "Section 2.5 states \"As the number of controls in [SP 800-53] grows in response to an increasingly sophisticated threat space, it is important for organizations to have the ability to describe key capabilities needed to protect organizational missions and business functions, and to subsequently select controls that\u2014if properly designed, developed, and implemented\u2014produce such capabilities. The use of capabilities simplifies how the protection problem is viewed conceptually. Using the construct of a capability provides a method of grouping controls that are employed for a common purpose or to achieve a common objective.\" This section later states \"Ultimately, authorization decisions (i.e., risk acceptance decisions) are made based on the degree to which the desired capabilities have been effectively achieved.\"" + }, + { + "reference": "NIST SP 800-53A", + "reference_url": "https://csrc.nist.gov/pubs/sp/800/53/a/r5/final", + "description": "Section 3.5 states \"When organizations employ the concept of capabilities, automated and manual assessments account for all security and privacy controls that comprise the security and privacy capabilities. Assessors are aware of how the controls work together to provide such capabilities.\"" + }, + { + "reference": "FedRAMP Authorization Act (44 USC \u00a7 3609 (a) (1))", + "reference_url": "https://fedramp.gov/docs/authority/law/#a-roles-and-responsibilities", + "description": "requires that the Administrator of the General Services Administration shall \"in consultation with the [DHS] Secretary, develop, coordinate, and implement a process to support agency review, reuse, and standardization, where appropriate, of security assessments of cloud computing products and services...\" 44 USC \u00a7 3609 (c) (2) further states that \"the [GSA] Administrator shall establish a means for the automation of security assessments and reviews.\"", + "delegation": "These responsibilities are delegated to the FedRAMP Director", + "delegation_url": "https://www.gsa.gov/directives-library/gsa-delegations-of-authority-fedramp" + } + ], + "purpose": "Modern cloud services use automated or code-driven configuration management and control planes to ensure predictable, repeatable, reliable, and secure outcomes during deployment and operation. The majority of a service security assessment can take place continuously via automated validation for simple cloud-native services if the need for a traditional control-by-control narrative approach is removed.", + "expected_outcomes": [ + "Cloud service providers following commercial security best practices will be able to meet and validate FedRAMP security requirements with the application of simple changes and automated capabilities", + "Third-party independent assessors will have a simpler framework to assess security and implementation decisions based on engineering decisions in context", + "Federal agencies will be able to easily, quickly, and effectively review and consume security information about the service to make informed risk-based authorization to operate decisions based on their planned use case" + ] + } + }, + "FRR.KSI": {}, + "KSI": { + "CED": { + "id": "KSI-CED", + "name": "Cybersecurity Education", + "indicators": [ + { + "id": "KSI-CED-RAT", + "name": "Reviewing All Training", + "statement": "The effectiveness of relevant cybersecurity education and training is persistently reviewed, including at least general training for all employees, role-specific training for employees in high risk roles, training for development and engineering staff on secure software delivery, and training for staff involved with incident response or disaster recovery.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cp-3", + "title": "Contingency Training" + }, + { + "control_id": "ir-2", + "title": "Incident Response Training" + }, + { + "control_id": "ps-6", + "title": "Access Agreements" + }, + { + "control_id": "at-2", + "title": "Literacy Training and Awareness" + }, + { + "control_id": "at-2.2", + "title": "Insider Threat" + }, + { + "control_id": "at-2.3", + "title": "Social Engineering and Mining" + }, + { + "control_id": "at-3.5", + "title": "Processing Personally Identifiable Information" + }, + { + "control_id": "at-4", + "title": "Training Records" + }, + { + "control_id": "ir-2.3", + "title": "Breach" + }, + { + "control_id": "at-3", + "title": "Role-based Training" + }, + { + "control_id": "sr-11.1", + "title": "Anti-counterfeit Training" + } + ] + } + ] + }, + "CMT": { + "id": "KSI-CMT", + "name": "Change Management", + "indicators": [ + { + "id": "KSI-CMT-LMC", + "name": "Logging Changes", + "statement": "Modifications to the cloud service offering are logged and monitored.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "au-2", + "title": "Event Logging" + }, + { + "control_id": "cm-3", + "title": "Configuration Change Control" + }, + { + "control_id": "cm-3.2", + "title": "Testing, Validation, and Documentation of Changes" + }, + { + "control_id": "cm-4.2", + "title": "Verification of Controls" + }, + { + "control_id": "cm-6", + "title": "Configuration Settings" + }, + { + "control_id": "cm-8.3", + "title": "Automated Unauthorized Component Detection" + }, + { + "control_id": "ma-2", + "title": "Controlled Maintenance" + } + ] + }, + { + "id": "KSI-CMT-RMV", + "name": "Redeploying vs Modifying", + "statement": "Changes to machine-based information resources are executed through the redeployment of version controlled resources rather than direct modification wherever reasonable.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-2", + "title": "Baseline Configuration" + }, + { + "control_id": "cm-3", + "title": "Configuration Change Control" + }, + { + "control_id": "cm-5", + "title": "Access Restrictions for Change" + }, + { + "control_id": "cm-6", + "title": "Configuration Settings" + }, + { + "control_id": "cm-7", + "title": "Least Functionality" + }, + { + "control_id": "cm-8.1", + "title": "Updates During Installation and Removal" + }, + { + "control_id": "si-3", + "title": "Malicious Code Protection" + } + ] + }, + { + "id": "KSI-CMT-RVP", + "name": "Reviewing Change Procedures", + "statement": "The effectiveness of documented change management procedures is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-3", + "title": "Configuration Change Control" + }, + { + "control_id": "cm-3.2", + "title": "Testing, Validation, and Documentation of Changes" + }, + { + "control_id": "cm-3.4", + "title": "Security and Privacy Representatives" + }, + { + "control_id": "cm-5", + "title": "Access Restrictions for Change" + }, + { + "control_id": "cm-7.1", + "title": "Periodic Review" + }, + { + "control_id": "cm-9", + "title": "Configuration Management Plan" + } + ] + }, + { + "id": "KSI-CMT-VTD", + "name": "Validating Throughout Deployment", + "statement": "Persistent testing and validation of changes throughout deployment is automated.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-3", + "title": "Configuration Change Control" + }, + { + "control_id": "cm-3.2", + "title": "Testing, Validation, and Documentation of Changes" + }, + { + "control_id": "cm-4.2", + "title": "Verification of Controls" + }, + { + "control_id": "si-2", + "title": "Flaw Remediation" + } + ] + } + ] + }, + "CNA": { + "id": "KSI-CNA", + "name": "Cloud Native Architecture", + "indicators": [ + { + "id": "KSI-CNA-DFP", + "name": "Defining Functionality and Privileges", + "statement": "The functionality and privileges for infrastructure and services are strictly defined.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-2", + "title": "Baseline Configuration" + }, + { + "control_id": "si-3", + "title": "Malicious Code Protection" + } + ] + }, + { + "id": "KSI-CNA-EIS", + "name": "Enforcing Intended State", + "statement": "Automated services are used to persistently assess the security of all machine-based information resources and automatically enforce their intended operational state.", + "impact": { + "low": false, + "moderate": true + }, + "controls": [ + { + "control_id": "ca-2.1", + "title": "Independent Assessors" + }, + { + "control_id": "ca-7.1", + "title": "Independent Assessment" + } + ] + }, + { + "id": "KSI-CNA-IBP", + "name": "Implementing Best Practices", + "statement": "The use and configuration of third-party machine-based information resources is persistently compared against the original provider's best practices and guidance.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-17.3", + "title": "Managed Access Control Points" + }, + { + "control_id": "cm-2", + "title": "Baseline Configuration" + }, + { + "control_id": "pl-10", + "title": "Baseline Selection" + } + ] + }, + { + "id": "KSI-CNA-MAT", + "name": "Minimizing Attack Surface", + "statement": "Machine-based information resources are persistently reviewed to ensure they have a minimal attack surface and that lateral movement is minimized if compromised.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-17.3", + "title": "Managed Access Control Points" + }, + { + "control_id": "ac-18.1", + "title": "Authentication and Encryption" + }, + { + "control_id": "ac-18.3", + "title": "Disable Wireless Networking" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "ca-9", + "title": "Internal System Connections" + }, + { + "control_id": "sc-7.3", + "title": "Access Points" + }, + { + "control_id": "sc-7.4", + "title": "External Telecommunications Services" + }, + { + "control_id": "sc-7.5", + "title": "Deny by Default \u2014 Allow by Exception" + }, + { + "control_id": "sc-7.8", + "title": "Route Traffic to Authenticated Proxy Servers" + }, + { + "control_id": "sc-8", + "title": "Transmission Confidentiality and Integrity" + }, + { + "control_id": "sc-10", + "title": "Network Disconnect" + }, + { + "control_id": "si-10", + "title": "Information Input Validation" + }, + { + "control_id": "si-11", + "title": "Error Handling" + }, + { + "control_id": "si-16", + "title": "Memory Protection" + } + ] + }, + { + "id": "KSI-CNA-OFA", + "name": "Optimizing for Availability", + "statement": "Machine-based information resources are persistently reviewed to ensure they are appropriately optimized for high availability and rapid recovery.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [] + }, + { + "id": "KSI-CNA-RNT", + "name": "Restricting Network Traffic", + "statement": "Machine-based information resources are persistently reviewed to ensure they are appropriately configured to limit inbound and outbound network traffic.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-17.3", + "title": "Managed Access Control Points" + }, + { + "control_id": "ca-9", + "title": "Internal System Connections" + }, + { + "control_id": "cm-7.1", + "title": "Periodic Review" + }, + { + "control_id": "sc-7.5", + "title": "Deny by Default \u2014 Allow by Exception" + }, + { + "control_id": "si-8", + "title": "Spam Protection" + } + ] + }, + { + "id": "KSI-CNA-RVP", + "name": "Reviewing Protections", + "statement": "The effectiveness of protection against denial of service attacks and other unwanted activity for machine-based information resources is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "sc-5", + "title": "Denial-of-service Protection" + }, + { + "control_id": "si-8", + "title": "Spam Protection" + }, + { + "control_id": "si-8.2", + "title": "Automatic Updates" + } + ] + }, + { + "id": "KSI-CNA-ULN", + "name": "Using Logical Networking", + "statement": "Logical networking and related capabilities are used and persistently reviewed to enforce traffic flow controls.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-12", + "title": "Session Termination" + }, + { + "control_id": "ac-17.3", + "title": "Managed Access Control Points" + }, + { + "control_id": "ca-9", + "title": "Internal System Connections" + }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, + { + "control_id": "sc-7", + "title": "Boundary Protection" + }, + { + "control_id": "sc-7.7", + "title": "Split Tunneling for Remote Devices" + }, + { + "control_id": "sc-8", + "title": "Transmission Confidentiality and Integrity" + }, + { + "control_id": "sc-10", + "title": "Network Disconnect" + } + ] + } + ] + }, + "IAM": { + "id": "KSI-IAM", + "name": "Identity and Access Management", + "indicators": [ + { + "id": "KSI-IAM-AAM", + "name": "Automating Account Management", + "statement": "The lifecycle and privileges of all accounts, roles, and groups are securely managed using automation.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2.2", + "title": "Automated Temporary and Emergency Account Management" + }, + { + "control_id": "ac-2.3", + "title": "Disable Accounts" + }, + { + "control_id": "ac-2.13", + "title": "Disable Accounts for High-risk Individuals" + }, + { + "control_id": "ac-6.7", + "title": "Review of User Privileges" + }, + { + "control_id": "ia-4.4", + "title": "Identify User Status" + }, + { + "control_id": "ia-12", + "title": "Identity Proofing" + }, + { + "control_id": "ia-12.2", + "title": "Identity Evidence" + }, + { + "control_id": "ia-12.3", + "title": "Identity Evidence Validation and Verification" + }, + { + "control_id": "ia-12.5", + "title": "Address Confirmation" + } + ] + }, + { + "id": "KSI-IAM-APM", + "name": "Adopting Passwordless Methods", + "statement": "Secure passwordless methods are used for user authentication and authorization when feasible, otherwise strong passwords with phishing-resistant MFA is used.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-3", + "title": "Access Enforcement" + }, + { + "control_id": "ia-5.1", + "title": "Password-based Authentication" + }, + { + "control_id": "ia-5.2", + "title": "Public Key-based Authentication" + }, + { + "control_id": "ia-5.6", + "title": "Protection of Authenticators" + }, + { + "control_id": "ia-6", + "title": "Authentication Feedback" + }, + { + "control_id": "ac-2", + "title": "Account Management" + }, + { + "control_id": "ia-2", + "title": "Identification and Authentication (Organizational Users)" + }, + { + "control_id": "ia-2.1", + "title": "Multi-factor Authentication to Privileged Accounts" + }, + { + "control_id": "ia-2.2", + "title": "Multi-factor Authentication to Non-privileged Accounts" + }, + { + "control_id": "ia-2.8", + "title": "Access to Accounts \u2014 Replay Resistant" + }, + { + "control_id": "ia-5", + "title": "Authenticator Management" + }, + { + "control_id": "ia-8", + "title": "Identification and Authentication (Non-organizational Users)" + }, + { + "control_id": "sc-23", + "title": "Session Authenticity" + } + ] + }, + { + "id": "KSI-IAM-ELP", + "name": "Ensuring Least Privilege", + "statement": "Identity and access management measures are used and persistently reviewed to ensure each user or device can only access the resources they need.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2.5", + "title": "Inactivity Logout" + }, + { + "control_id": "ac-2.6", + "title": "Dynamic Privilege Management" + }, + { + "control_id": "ac-3", + "title": "Access Enforcement" + }, + { + "control_id": "ac-4", + "title": "Information Flow Enforcement" + }, + { + "control_id": "ac-6", + "title": "Least Privilege" + }, + { + "control_id": "ac-12", + "title": "Session Termination" + }, + { + "control_id": "ac-14", + "title": "Permitted Actions Without Identification or Authentication" + }, + { + "control_id": "ac-17", + "title": "Remote Access" + }, + { + "control_id": "ac-17.1", + "title": "Monitoring and Control" + }, + { + "control_id": "ac-17.2", + "title": "Protection of Confidentiality and Integrity Using Encryption" + }, + { + "control_id": "ac-17.3", + "title": "Managed Access Control Points" + }, + { + "control_id": "ac-20", + "title": "Use of External Systems" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "cm-2.7", + "title": "Configure Systems and Components for High-risk Areas" + }, + { + "control_id": "cm-9", + "title": "Configuration Management Plan" + }, + { + "control_id": "ia-2", + "title": "Identification and Authentication (Organizational Users)" + }, + { + "control_id": "ia-3", + "title": "Device Identification and Authentication" + }, + { + "control_id": "ia-4", + "title": "Identifier Management" + }, + { + "control_id": "ia-4.4", + "title": "Identify User Status" + }, + { + "control_id": "ia-5.2", + "title": "Public Key-based Authentication" + }, + { + "control_id": "ia-5.6", + "title": "Protection of Authenticators" + }, + { + "control_id": "ia-11", + "title": "Re-authentication" + }, + { + "control_id": "ps-2", + "title": "Position Risk Designation" + }, + { + "control_id": "ps-3", + "title": "Personnel Screening" + }, + { + "control_id": "ps-4", + "title": "Personnel Termination" + }, + { + "control_id": "ps-5", + "title": "Personnel Transfer" + }, + { + "control_id": "ps-6", + "title": "Access Agreements" + }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, + { + "control_id": "sc-20", + "title": "Secure Name/Address Resolution Service (Authoritative Source)" + }, + { + "control_id": "sc-21", + "title": "Secure Name/Address Resolution Service (Recursive or Caching Resolver)" + }, + { + "control_id": "sc-22", + "title": "Architecture and Provisioning for Name/Address Resolution Service" + }, + { + "control_id": "sc-23", + "title": "Session Authenticity" + }, + { + "control_id": "sc-39", + "title": "Process Isolation" + }, + { + "control_id": "si-3", + "title": "Malicious Code Protection" + } + ] + }, + { + "id": "KSI-IAM-JIT", + "name": "Authorizing Just-in-Time", + "statement": "A least-privileged, role and attribute-based, and just-in-time security authorization model is used and persistently reviewed for all user and non-user accounts and services.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2", + "title": "Account Management" + }, + { + "control_id": "ac-2.1", + "title": "Automated System Account Management" + }, + { + "control_id": "ac-2.2", + "title": "Automated Temporary and Emergency Account Management" + }, + { + "control_id": "ac-2.3", + "title": "Disable Accounts" + }, + { + "control_id": "ac-2.4", + "title": "Automated Audit Actions" + }, + { + "control_id": "ac-2.6", + "title": "Dynamic Privilege Management" + }, + { + "control_id": "ac-3", + "title": "Access Enforcement" + }, + { + "control_id": "ac-4", + "title": "Information Flow Enforcement" + }, + { + "control_id": "ac-5", + "title": "Separation of Duties" + }, + { + "control_id": "ac-6", + "title": "Least Privilege" + }, + { + "control_id": "ac-6.1", + "title": "Authorize Access to Security Functions" + }, + { + "control_id": "ac-6.2", + "title": "Non-privileged Access for Nonsecurity Functions" + }, + { + "control_id": "ac-6.5", + "title": "Privileged Accounts" + }, + { + "control_id": "ac-6.7", + "title": "Review of User Privileges" + }, + { + "control_id": "ac-6.9", + "title": "Log Use of Privileged Functions" + }, + { + "control_id": "ac-6.10", + "title": "Prohibit Non-privileged Users from Executing Privileged Functions" + }, + { + "control_id": "ac-7", + "title": "Unsuccessful Logon Attempts" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "ac-17", + "title": "Remote Access" + }, + { + "control_id": "au-9.4", + "title": "Access by Subset of Privileged Users" + }, + { + "control_id": "cm-5", + "title": "Access Restrictions for Change" + }, + { + "control_id": "cm-7", + "title": "Least Functionality" + }, + { + "control_id": "cm-7.2", + "title": "Prevent Program Execution" + }, + { + "control_id": "cm-7.5", + "title": "Authorized Software \u2014 Allow-by-exception" + }, + { + "control_id": "cm-9", + "title": "Configuration Management Plan" + }, + { + "control_id": "ia-4", + "title": "Identifier Management" + }, + { + "control_id": "ia-4.4", + "title": "Identify User Status" + }, + { + "control_id": "ia-7", + "title": "Cryptographic Module Authentication" + }, + { + "control_id": "ps-2", + "title": "Position Risk Designation" + }, + { + "control_id": "ps-3", + "title": "Personnel Screening" + }, + { + "control_id": "ps-4", + "title": "Personnel Termination" + }, + { + "control_id": "ps-5", + "title": "Personnel Transfer" + }, + { + "control_id": "ps-6", + "title": "Access Agreements" + }, + { + "control_id": "ps-9", + "title": "Position Descriptions" + }, + { + "control_id": "ra-5.5", + "title": "Privileged Access" + }, + { + "control_id": "sc-2", + "title": "Separation of System and User Functionality" + }, + { + "control_id": "sc-23", + "title": "Session Authenticity" + }, + { + "control_id": "sc-39", + "title": "Process Isolation" + } + ] + }, + { + "id": "KSI-IAM-SNU", + "name": "Securing Non-User Authentication", + "statement": "Appropriately secure authentication methods are used and persistently reviewed for non-user accounts and services.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2", + "title": "Account Management" + }, + { + "control_id": "ac-2.2", + "title": "Automated Temporary and Emergency Account Management" + }, + { + "control_id": "ac-4", + "title": "Information Flow Enforcement" + }, + { + "control_id": "ac-6.5", + "title": "Privileged Accounts" + }, + { + "control_id": "ia-3", + "title": "Device Identification and Authentication" + }, + { + "control_id": "ia-5.2", + "title": "Public Key-based Authentication" + }, + { + "control_id": "ra-5.5", + "title": "Privileged Access" + } + ] + }, + { + "id": "KSI-IAM-SUS", + "name": "Responding to Suspicious Activity", + "statement": "Accounts with privileged access are disabled or otherwise secured in response to suspicious activity.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2", + "title": "Account Management" + }, + { + "control_id": "ac-2.1", + "title": "Automated System Account Management" + }, + { + "control_id": "ac-2.3", + "title": "Disable Accounts" + }, + { + "control_id": "ac-2.13", + "title": "Disable Accounts for High-risk Individuals" + }, + { + "control_id": "ac-7", + "title": "Unsuccessful Logon Attempts" + }, + { + "control_id": "ps-4", + "title": "Personnel Termination" + }, + { + "control_id": "ps-8", + "title": "Personnel Sanctions" + } + ] + } + ] + }, + "INR": { + "id": "KSI-INR", + "name": "Incident Response", + "indicators": [ + { + "id": "KSI-INR-AAR", + "name": "Generating After Action Reports", + "statement": "Incident after action reports are generated and lessons learned are persistently incorporated.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ir-3", + "title": "Incident Response Testing" + }, + { + "control_id": "ir-4", + "title": "Incident Handling" + }, + { + "control_id": "ir-4.1", + "title": "Automated Incident Handling Processes" + }, + { + "control_id": "ir-8", + "title": "Incident Response Plan" + } + ] + }, + { + "id": "KSI-INR-RIR", + "name": "Reviewing Incident Response Procedures", + "statement": "The effectiveness of documented incident response procedures is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ir-4", + "title": "Incident Handling" + }, + { + "control_id": "ir-4.1", + "title": "Automated Incident Handling Processes" + }, + { + "control_id": "ir-6", + "title": "Incident Reporting" + }, + { + "control_id": "ir-6.1", + "title": "Automated Reporting" + }, + { + "control_id": "ir-6.3", + "title": "Supply Chain Coordination" + }, + { + "control_id": "ir-7", + "title": "Incident Response Assistance" + }, + { + "control_id": "ir-7.1", + "title": "Automation Support for Availability of Information and Support" + }, + { + "control_id": "ir-8", + "title": "Incident Response Plan" + }, + { + "control_id": "ir-8.1", + "title": "Breaches" + }, + { + "control_id": "si-4.5", + "title": "System-generated Alerts" + } + ] + }, + { + "id": "KSI-INR-RPI", + "name": "Reviewing Past Incidents", + "statement": "Past incidents are persistently reviewed for patterns or vulnerabilities that were not previously apparent or identified.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ir-3", + "title": "Incident Response Testing" + }, + { + "control_id": "ir-4", + "title": "Incident Handling" + }, + { + "control_id": "ir-4.1", + "title": "Automated Incident Handling Processes" + }, + { + "control_id": "ir-5", + "title": "Incident Monitoring" + }, + { + "control_id": "ir-8", + "title": "Incident Response Plan" + } + ] + } + ] + }, + "MLA": { + "id": "KSI-MLA", + "name": "Monitoring, Logging, and Auditing", + "indicators": [ + { + "id": "KSI-MLA-ALA", + "name": "Authorizing Log Access", + "statement": "A least-privileged, role and attribute-based, and just-in-time access authorization model is used and persistently reviewed for access to log data based on organizationally defined data sensitivity.", + "impact": { + "low": false, + "moderate": true + }, + "controls": [ + { + "control_id": "si-11", + "title": "Error Handling" + } + ] + }, + { + "id": "KSI-MLA-EVC", + "name": "Evaluating Configurations", + "statement": "The configuration of machine-based information resources, especially infrastructure as code, is persistently evaluated and tested.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ca-7", + "title": "Continuous Monitoring" + }, + { + "control_id": "cm-2", + "title": "Baseline Configuration" + }, + { + "control_id": "cm-6", + "title": "Configuration Settings" + }, + { + "control_id": "si-7.7", + "title": "Integration of Detection and Response" + } + ] + }, + { + "id": "KSI-MLA-LET", + "name": "Logging Event Types", + "statement": "A list of information resources and event types that will be logged, monitored, and audited is maintained and persistently reviewed to ensure these activities occur.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2.4", + "title": "Automated Audit Actions" + }, + { + "control_id": "ac-6.9", + "title": "Log Use of Privileged Functions" + }, + { + "control_id": "ac-17.1", + "title": "Monitoring and Control" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "au-2", + "title": "Event Logging" + }, + { + "control_id": "au-7.1", + "title": "Automatic Processing" + }, + { + "control_id": "au-12", + "title": "Audit Record Generation" + }, + { + "control_id": "si-4.4", + "title": "Inbound and Outbound Communications Traffic" + }, + { + "control_id": "si-4.5", + "title": "System-generated Alerts" + }, + { + "control_id": "si-7.7", + "title": "Integration of Detection and Response" + } + ] + }, + { + "id": "KSI-MLA-OSM", + "name": "Operating SIEM Capability", + "statement": "A Security Information and Event Management (SIEM) or similar system(s) is used and persistently reviewed for centralized, tamper-resistant logging of events, activities, and changes.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-17.1", + "title": "Monitoring and Control" + }, + { + "control_id": "ac-20.1", + "title": "Limits on Authorized Use" + }, + { + "control_id": "au-2", + "title": "Event Logging" + }, + { + "control_id": "au-3", + "title": "Content of Audit Records" + }, + { + "control_id": "au-3.1", + "title": "Additional Audit Information" + }, + { + "control_id": "au-4", + "title": "Audit Log Storage Capacity" + }, + { + "control_id": "au-5", + "title": "Response to Audit Logging Process Failures" + }, + { + "control_id": "au-6.1", + "title": "Automated Process Integration" + }, + { + "control_id": "au-6.3", + "title": "Correlate Audit Record Repositories" + }, + { + "control_id": "au-7", + "title": "Audit Record Reduction and Report Generation" + }, + { + "control_id": "au-7.1", + "title": "Automatic Processing" + }, + { + "control_id": "au-8", + "title": "Time Stamps" + }, + { + "control_id": "au-9", + "title": "Protection of Audit Information" + }, + { + "control_id": "au-11", + "title": "Audit Record Retention" + }, + { + "control_id": "ir-4.1", + "title": "Automated Incident Handling Processes" + }, + { + "control_id": "si-4.2", + "title": "Automated Tools and Mechanisms for Real-time Analysis" + }, + { + "control_id": "si-4.4", + "title": "Inbound and Outbound Communications Traffic" + }, + { + "control_id": "si-7.7", + "title": "Integration of Detection and Response" + } + ] + }, + { + "id": "KSI-MLA-RVL", + "name": "Reviewing Logs", + "statement": "Logs are persistently reviewed and audited.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2.4", + "title": "Automated Audit Actions" + }, + { + "control_id": "ac-6.9", + "title": "Log Use of Privileged Functions" + }, + { + "control_id": "au-2", + "title": "Event Logging" + }, + { + "control_id": "au-6", + "title": "Audit Record Review, Analysis, and Reporting" + }, + { + "control_id": "au-6.1", + "title": "Automated Process Integration" + }, + { + "control_id": "si-4", + "title": "System Monitoring" + }, + { + "control_id": "si-4.4", + "title": "Inbound and Outbound Communications Traffic" + } + ] + } + ] + }, + "PIY": { + "id": "KSI-PIY", + "name": "Policy and Inventory", + "indicators": [ + { + "id": "KSI-PIY-GIV", + "name": "Generating Inventories", + "statement": "Authoritative sources are used to automatically generate real-time inventories of all information resources when needed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-2.2", + "title": "Automation Support for Accuracy and Currency" + }, + { + "control_id": "cm-7.5", + "title": "Authorized Software \u2014 Allow-by-exception" + }, + { + "control_id": "cm-8", + "title": "System Component Inventory" + }, + { + "control_id": "cm-8.1", + "title": "Updates During Installation and Removal" + }, + { + "control_id": "cm-12", + "title": "Information Location" + }, + { + "control_id": "cm-12.1", + "title": "Automated Tools to Support Information Location" + }, + { + "control_id": "cp-2.8", + "title": "Identify Critical Assets" + } + ] + }, + { + "id": "KSI-PIY-RES", + "name": "Reviewing Executive Support", + "statement": "Executive support for achieving the provider's security goals is persistently reviewed and demonstrated.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [] + }, + { + "id": "KSI-PIY-RIS", + "name": "Reviewing Investments in Security", + "statement": "The effectiveness of the provider's investments in achieving security goals is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-5", + "title": "Separation of Duties" + }, + { + "control_id": "ca-2", + "title": "Control Assessments" + }, + { + "control_id": "cp-2.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "cp-4.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "ir-3.2", + "title": "Coordination with Related Plans" + }, + { + "control_id": "pm-3", + "title": "Information Security and Privacy Resources" + }, + { + "control_id": "sa-2", + "title": "Allocation of Resources" + }, + { + "control_id": "sa-3", + "title": "System Development Life Cycle" + }, + { + "control_id": "sr-2.1", + "title": "Establish SCRM Team" + } + ] + }, + { + "id": "KSI-PIY-RSD", + "name": "Reviewing Security in the SDLC", + "statement": "The effectiveness of building security and privacy considerations into the Software Development Lifecycle and aligning with CISA Secure By Design principles is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-5", + "title": "Separation of Duties" + }, + { + "control_id": "au-3.3", + "title": "Limit Personally Identifiable Information Elements" + }, + { + "control_id": "cm-3.4", + "title": "Security and Privacy Representatives" + }, + { + "control_id": "pl-8", + "title": "Security and Privacy Architectures" + }, + { + "control_id": "pm-7", + "title": "Enterprise Architecture" + }, + { + "control_id": "sa-3", + "title": "System Development Life Cycle" + }, + { + "control_id": "sa-8", + "title": "Security and Privacy Engineering Principles" + }, + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + }, + { + "control_id": "sc-18", + "title": "Mobile Code" + }, + { + "control_id": "si-10", + "title": "Information Input Validation" + }, + { + "control_id": "si-11", + "title": "Error Handling" + }, + { + "control_id": "si-16", + "title": "Memory Protection" + } + ] + }, + { + "id": "KSI-PIY-RVD", + "name": "Reviewing Vulnerability Disclosures", + "statement": "The effectiveness of the provider's vulnerability disclosure program is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ra-5.11", + "title": "Public Disclosure Program" + } + ] + } + ] + }, + "RPL": { + "id": "KSI-RPL", + "name": "Recovery Planning", + "indicators": [ + { + "id": "KSI-RPL-ABO", + "name": "Aligning Backups with Objectives", + "statement": "The alignment of machine-based information resource backups with defined recovery objectives is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-2.3", + "title": "Retention of Previous Configurations" + }, + { + "control_id": "cp-6", + "title": "Alternate Storage Site" + }, + { + "control_id": "cp-9", + "title": "System Backup" + }, + { + "control_id": "cp-10", + "title": "System Recovery and Reconstitution" + }, + { + "control_id": "cp-10.2", + "title": "Transaction Recovery" + }, + { + "control_id": "si-12", + "title": "Information Management and Retention" + } + ] + }, + { + "id": "KSI-RPL-ARP", + "name": "Aligning Recovery Plan", + "statement": "The alignment of recovery plans with defined recovery objectives is persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cp-2", + "title": "Contingency Plan" + }, + { + "control_id": "cp-2.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "cp-2.3", + "title": "Resume Mission and Business Functions" + }, + { + "control_id": "cp-4.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "cp-6", + "title": "Alternate Storage Site" + }, + { + "control_id": "cp-6.1", + "title": "Separation from Primary Site" + }, + { + "control_id": "cp-6.3", + "title": "Accessibility" + }, + { + "control_id": "cp-7", + "title": "Alternate Processing Site" + }, + { + "control_id": "cp-7.1", + "title": "Separation from Primary Site" + }, + { + "control_id": "cp-7.2", + "title": "Accessibility" + }, + { + "control_id": "cp-7.3", + "title": "Priority of Service" + }, + { + "control_id": "cp-8", + "title": "Telecommunications Services" + }, + { + "control_id": "cp-8.1", + "title": "Priority of Service Provisions" + }, + { + "control_id": "cp-8.2", + "title": "Single Points of Failure" + }, + { + "control_id": "cp-10", + "title": "System Recovery and Reconstitution" + }, + { + "control_id": "cp-10.2", + "title": "Transaction Recovery" + } + ] + }, + { + "id": "KSI-RPL-RRO", + "name": "Reviewing Recovery Objectives", + "statement": "The desired Recovery Time Objectives (RTO) and Recovery Point Objectives (RPO) are defined and persistently reviewed for alignment with the provider's business needs and capabilities.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cp-2.3", + "title": "Resume Mission and Business Functions" + }, + { + "control_id": "cp-10", + "title": "System Recovery and Reconstitution" + } + ] + }, + { + "id": "KSI-RPL-TRC", + "name": "Testing Recovery Capabilities", + "statement": "The capability to recover from incidents and contingencies aligned with defined recovery objectives is persistently tested.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cp-2.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "cp-2.3", + "title": "Resume Mission and Business Functions" + }, + { + "control_id": "cp-4", + "title": "Contingency Plan Testing" + }, + { + "control_id": "cp-4.1", + "title": "Coordinate with Related Plans" + }, + { + "control_id": "cp-6", + "title": "Alternate Storage Site" + }, + { + "control_id": "cp-6.1", + "title": "Separation from Primary Site" + }, + { + "control_id": "cp-9.1", + "title": "Testing for Reliability and Integrity" + }, + { + "control_id": "cp-10", + "title": "System Recovery and Reconstitution" + }, + { + "control_id": "ir-3", + "title": "Incident Response Testing" + }, + { + "control_id": "ir-3.2", + "title": "Coordination with Related Plans" + } + ] + } + ] + }, + "SCR": { + "id": "KSI-SCR", + "name": "Supply Chain Risk", + "indicators": [ + { + "id": "KSI-SCR-MIT", + "name": "Mitigating Supply Chain Risk", + "statement": "Persistently identify, review, and mitigate potential supply chain risks.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-20", + "title": "Use of External Systems" + }, + { + "control_id": "ra-3.1", + "title": "Supply Chain Risk Assessment" + }, + { + "control_id": "sa-9", + "title": "External System Services" + }, + { + "control_id": "sa-10", + "title": "Developer Configuration Management" + }, + { + "control_id": "sa-11", + "title": "Developer Testing and Evaluation" + }, + { + "control_id": "sa-15.3", + "title": "Criticality Analysis" + }, + { + "control_id": "sa-22", + "title": "Unsupported System Components" + }, + { + "control_id": "si-7.1", + "title": "Integrity Checks" + }, + { + "control_id": "sr-5", + "title": "Acquisition Strategies, Tools, and Methods" + }, + { + "control_id": "sr-6", + "title": "Supplier Assessments and Reviews" + }, + { + "control_id": "ca-7.4", + "title": "Risk Monitoring" + }, + { + "control_id": "sc-18", + "title": "Mobile Code" + } + ] + }, + { + "id": "KSI-SCR-MON", + "name": "Monitoring Supply Chain Risk", + "statement": "Third party software information resources are automatically monitored for upstream vulnerabilities using mechanisms that may include contractual notification requirements or active monitoring services.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-20", + "title": "Use of External Systems" + }, + { + "control_id": "ca-3", + "title": "Information Exchange" + }, + { + "control_id": "ir-6.3", + "title": "Supply Chain Coordination" + }, + { + "control_id": "ps-7", + "title": "External Personnel Security" + }, + { + "control_id": "ra-5", + "title": "Vulnerability Monitoring and Scanning" + }, + { + "control_id": "sa-9", + "title": "External System Services" + }, + { + "control_id": "si-5", + "title": "Security Alerts, Advisories, and Directives" + }, + { + "control_id": "sr-5", + "title": "Acquisition Strategies, Tools, and Methods" + }, + { + "control_id": "sr-6", + "title": "Supplier Assessments and Reviews" + }, + { + "control_id": "sr-8", + "title": "Notification Agreements" + } + ] + } + ] + }, + "SVC": { + "id": "KSI-SVC", + "name": "Service Configuration", + "indicators": [ + { + "id": "KSI-SVC-ACM", + "name": "Automating Configuration Management", + "statement": "The configuration of machine-based information resources is managed using automation and persistently reviewed for drift.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-2.4", + "title": "Automated Audit Actions" + }, + { + "control_id": "cm-2", + "title": "Baseline Configuration" + }, + { + "control_id": "cm-2.2", + "title": "Automation Support for Accuracy and Currency" + }, + { + "control_id": "cm-2.3", + "title": "Retention of Previous Configurations" + }, + { + "control_id": "cm-6", + "title": "Configuration Settings" + }, + { + "control_id": "cm-7.1", + "title": "Periodic Review" + }, + { + "control_id": "pl-9", + "title": "Central Management" + }, + { + "control_id": "pl-10", + "title": "Baseline Selection" + }, + { + "control_id": "sa-5", + "title": "System Documentation" + }, + { + "control_id": "si-5", + "title": "Security Alerts, Advisories, and Directives" + }, + { + "control_id": "sr-10", + "title": "Inspection of Systems or Components" + } + ] + }, + { + "id": "KSI-SVC-ASM", + "name": "Automating Secret Management", + "statement": "Management, protection, and regular rotation of digital keys, certificates, and other secrets is automated and persistently reviewed.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-17.2", + "title": "Protection of Confidentiality and Integrity Using Encryption" + }, + { + "control_id": "ia-5.2", + "title": "Public Key-based Authentication" + }, + { + "control_id": "ia-5.6", + "title": "Protection of Authenticators" + }, + { + "control_id": "sc-12", + "title": "Cryptographic Key Establishment and Management" + }, + { + "control_id": "sc-17", + "title": "Public Key Infrastructure Certificates" + } + ] + }, + { + "id": "KSI-SVC-EIS", + "name": "Evaluating and Improving Security", + "statement": "Information resources are persistently evaluated for opportunities to improve security and those improvements are persistently made.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-7.1", + "title": "Periodic Review" + }, + { + "control_id": "cm-12.1", + "title": "Automated Tools to Support Information Location" + }, + { + "control_id": "ma-2", + "title": "Controlled Maintenance" + }, + { + "control_id": "pl-8", + "title": "Security and Privacy Architectures" + }, + { + "control_id": "sc-7", + "title": "Boundary Protection" + }, + { + "control_id": "sc-39", + "title": "Process Isolation" + }, + { + "control_id": "si-2.2", + "title": "Automated Flaw Remediation Status" + }, + { + "control_id": "si-4", + "title": "System Monitoring" + }, + { + "control_id": "sr-10", + "title": "Inspection of Systems or Components" + } + ] + }, + { + "id": "KSI-SVC-PRR", + "name": "Preventing Residual Risk", + "statement": "Plans, procedures, and the state of information resources are persistently reviewed after making changes to limit and remove unwanted residual elements that would likely negatively affect the confidentiality, integrity, or availability of federal customer data.", + "impact": { + "low": false, + "moderate": true + }, + "controls": [ + { + "control_id": "sc-4", + "title": "Information in Shared System Resources" + } + ] + }, + { + "id": "KSI-SVC-RUD", + "name": "Removing Unwanted Data", + "statement": "Unwanted federal customer data is removed promptly when requested by an agency in alignment with customer agreements, including from backups if appropriate; this typically applies when a customer spills information or when a customer seeks to remove information from a service due to a change in usage.", + "impact": { + "low": false, + "moderate": true + }, + "controls": [ + { + "control_id": "si-12.3", + "title": "Information Disposal" + }, + { + "control_id": "si-18.4", + "title": "Individual Requests" + } + ] + }, + { + "id": "KSI-SVC-SIN", + "name": "Securing Information", + "statement": "Information is encrypted or otherwise secured from unwanted access or modification.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "ac-1", + "title": "Policy and Procedures" + }, + { + "control_id": "ac-17.2", + "title": "Protection of Confidentiality and Integrity Using Encryption" + }, + { + "control_id": "cp-9.8", + "title": "Cryptographic Protection" + }, + { + "control_id": "sc-8", + "title": "Transmission Confidentiality and Integrity" + }, + { + "control_id": "sc-8.1", + "title": "Cryptographic Protection" + }, + { + "control_id": "sc-13", + "title": "Cryptographic Protection" + }, + { + "control_id": "sc-20", + "title": "Secure Name/Address Resolution Service (Authoritative Source)" + }, + { + "control_id": "sc-21", + "title": "Secure Name/Address Resolution Service (Recursive or Caching Resolver)" + }, + { + "control_id": "sc-22", + "title": "Architecture and Provisioning for Name/Address Resolution Service" + }, + { + "control_id": "sc-23", + "title": "Session Authenticity" + }, + { + "control_id": "sc-28", + "title": "Protection of Information at Rest" + }, + { + "control_id": "sc-28.1", + "title": "Cryptographic Protection" + } + ] + }, + { + "id": "KSI-SVC-VCM", + "name": "Validating Communications", + "statement": "The authenticity and integrity of communications between machine-based information resources is persistently validated using automation.", + "impact": { + "low": false, + "moderate": true + }, + "controls": [ + { + "control_id": "sc-23", + "title": "Session Authenticity" + }, + { + "control_id": "si-7.1", + "title": "Integrity Checks" + } + ] + }, + { + "id": "KSI-SVC-VRI", + "name": "Validating Resource Integrity", + "statement": "Use cryptographic methods to validate the integrity of machine-based information resources.", + "impact": { + "low": true, + "moderate": true + }, + "controls": [ + { + "control_id": "cm-2.2", + "title": "Automation Support for Accuracy and Currency" + }, + { + "control_id": "cm-8.3", + "title": "Automated Unauthorized Component Detection" + }, + { + "control_id": "sc-13", + "title": "Cryptographic Protection" + }, + { + "control_id": "sc-23", + "title": "Session Authenticity" + }, + { + "control_id": "si-7", + "title": "Software, Firmware, and Information Integrity" + }, + { + "control_id": "si-7.1", + "title": "Integrity Checks" + }, + { + "control_id": "sr-10", + "title": "Inspection of Systems or Components" + } + ] + } + ] + } + } +} diff --git a/tests/test_controls.py b/tests/test_controls.py index fa0aae40..75e0e53a 100644 --- a/tests/test_controls.py +++ b/tests/test_controls.py @@ -26,6 +26,11 @@ REPO = Path(__file__).resolve().parent.parent FIX_SIGNAL = REPO / "tests" / "fixtures" / "clean" / "ksi-signal.json" CATALOG = REPO / "infrastructure" / "schemas" / "ksi-catalog.json" +# The KSI catalog as it stood when the SSP was retired (FedRAMP's mappings before +# its 2026-10-13 revision). The parity test runs the projection on it, so the +# projection's code stays pinned to the SSP it replaced; the current catalog is +# FedRAMP's current mapping (tests/test_ksi_catalog_corpus.py). +CATALOG_AT_RETIREMENT = REPO / "tests" / "fixtures" / "migration" / "ksi-catalog-2026-11-05.json" FROZEN = REPO / "tests" / "fixtures" / "migration" / "ssp-control-status-2026-11-05.json" sys.path.insert(0, str(REPO / "scripts")) @@ -48,7 +53,7 @@ def _projection(): def test_the_projection_matches_the_last_ssp_control_for_control(): frozen = json.loads(FROZEN.read_text()) - irs = _projection() + irs = _controls.load(FIX_SIGNAL, CATALOG_AT_RETIREMENT) assert len(irs) == frozen["implemented_requirements"] == 333 got = {cid: list(v) for cid, v in _controls.status_map(irs).items()} assert got == frozen["controls"] diff --git a/tests/test_inject_figures.py b/tests/test_inject_figures.py index 2973c66d..76861df0 100644 --- a/tests/test_inject_figures.py +++ b/tests/test_inject_figures.py @@ -47,13 +47,14 @@ def test_figures_reproduce_published_numbers(): # hub split: hand-written + family-default = total assert int(f["hub_handwritten"]) + int(f["hub_generated"]) == int(f["hub_total"]) assert f["hub_handwritten"] == "116" - assert f["hub_total"] == "333" + assert f["hub_total"] == "382" # FedRAMP Moderate stack sums to the total assert int(f["moderate_implemented"]) + int(f["moderate_inherited"]) + int(f["moderate_na"]) == int(f["hub_total"]) # coverage is measured against the published baseline, not the hub total assert f["moderate_baseline"] == "323" assert f["moderate_coverage"] == "323/323" - assert f["moderate_beyond"] == "10" + # controls FedRAMP's KSI mappings reach beyond Moderate (2026-10-13 revision) + assert f["moderate_beyond"] == "59" assert int(f["moderate_baseline"]) + int(f["moderate_beyond"]) == int(f["hub_total"]) # spokes assert f["govramp_coverage"] == "339/339" @@ -126,7 +127,7 @@ def test_altered_projection_count_flows_to_html(monkeypatch): # hand-written count is unchanged (component def untouched), so generated grows assert f["hub_generated"] == str(baseline + 1 - int(f["hub_handwritten"])) assert f["moderate_coverage"] == "323/323" - assert f["moderate_beyond"] == "11" + assert f["moderate_beyond"] == "60" # and that new value actually lands in the marked HTML marked = '331' diff --git a/tests/test_ksi_catalog_corpus.py b/tests/test_ksi_catalog_corpus.py new file mode 100644 index 00000000..6fa3d396 --- /dev/null +++ b/tests/test_ksi_catalog_corpus.py @@ -0,0 +1,57 @@ +"""The KSI catalog is FedRAMP's: IDs, names, Class C statements and KSI->control +mappings equal the pinned Consolidated Rules (scripts/sync-ksi-catalog.py).""" + +import copy +import importlib.util +import json +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +spec = importlib.util.spec_from_file_location("sync_ksi", REPO / "scripts" / "sync-ksi-catalog.py") +sync = importlib.util.module_from_spec(spec) +spec.loader.exec_module(sync) +BEFORE = REPO / "tests" / "fixtures" / "migration" / "ksi-catalog-2026-11-05.json" + + +def _catalog(): + return json.loads(sync.CATALOG.read_text()) + + +def test_the_committed_catalog_equals_the_pinned_rules(): + assert sync.main(["--check"]) == 0 + + +def test_a_mapping_that_drifts_from_the_rules_fails(): + """Known-bad: the catalog as committed before FedRAMP's 2026-10-13 mapping + revision was carried (40 of 46 KSIs differ).""" + stale = json.loads(BEFORE.read_text()) + assert sync.derive(stale) != stale + + +def test_a_dropped_control_is_detected(): + cat = _catalog() + bad = copy.deepcopy(cat) + bad["KSI"]["CED"]["indicators"][0]["controls"].pop() + assert sync.derive(bad) != bad + + +def test_class_c_statements_are_used_where_a_ksi_varies_by_class(): + by_id = {i["id"]: i for f in _catalog()["KSI"].values() for i in f["indicators"]} + assert len(by_id) == 46 + assert not by_id["KSI-CNA-EIS"]["statement"].startswith("**Optional:**") + + +def test_a_control_outside_the_nist_catalog_fails_closed(monkeypatch): + monkeypatch.setattr(sync, "_titles", lambda: {}) + with pytest.raises(SystemExit, match="not in the NIST SP 800-53 Rev5 catalog"): + sync.derive(_catalog()) + + +def test_a_new_ksi_needs_its_impact_set_first(): + cat = _catalog() + for f in cat["KSI"].values(): + f["indicators"] = [i for i in f["indicators"] if i["id"] != "KSI-CED-RAT"] + with pytest.raises(SystemExit, match="KSI-CED-RAT is new in the corpus"): + sync.derive(cat) From f1896430471d8f6d5788e279f2b11dcab8a1aae3 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 14:28:10 -0500 Subject: [PATCH 02/17] feat(sdr): Security Decision Record in FedRAMP's SDR schema Every applicable 20x Class C rule, every KSI and every Rev5 Moderate control, each no stronger than what backs it; semver versioning; consumers moved to the schema shape. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 3 +- infrastructure/schemas/freshness-config.json | 2 +- scripts/_assessor.py | 6 + scripts/build-sdr.py | 725 ++++++++++++------- scripts/reconcile.py | 11 +- tests/test_assessor_records.py | 28 +- tests/test_controls.py | 29 +- tests/test_evidence_freshness.py | 4 +- tests/test_evidence_watchdog.py | 2 +- tests/test_reconcile.py | 21 +- tests/test_sdr.py | 221 ++++++ website/assets/js/trust.js | 2 +- 12 files changed, 765 insertions(+), 289 deletions(-) create mode 100644 tests/test_sdr.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index a327c2de..24a24847 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1590,11 +1590,12 @@ jobs: - name: Build Security Decision Record (SDR — 20x SSP replacement) working-directory: infrastructure run: | - echo "Building Security Decision Record (SDR-CSO-FRR per KSI, SDR-CSF-CTF per Rev5 control) from the control projection..." + echo "Building the Security Decision Record (FedRAMP schema): every applicable rule, KSI and Moderate control..." curl -sfL -o previous-sdr.json "https://samaydlette.com/.well-known/security-decision-record.json" \ || echo '{}' > previous-sdr.json python3 ../scripts/build-sdr.py \ --catalog schemas/ksi-catalog.json --ksi-signal ksi-signal.json \ + --runtime-signal ksi-signal-runtime.json \ --vdr vdr-report.json --profile ../data/system-profile.json --previous-sdr previous-sdr.json # REQ-ASR-1 / T74: re-read the written SDR and fail if any assessor text # differs from the assessor's signed record, or a signed record is missing. diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index 7d02d3de..888561ba 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -195,7 +195,7 @@ "max_age_hours": 720, "timestamp": { "source": "json", - "field": "metadata.last_updated" + "field": "metadata.lastUpdated" }, "signed": true, "signature": ".well-known/security-decision-record.bundle" diff --git a/scripts/_assessor.py b/scripts/_assessor.py index 60a4d720..52cc5092 100644 --- a/scripts/_assessor.py +++ b/scripts/_assessor.py @@ -155,6 +155,12 @@ def verify_output(sdr, records): signed record is carried. Fails the build otherwise.""" signed = {r["record_id"]: _carried(r) for r in records} carried = [] + pe = sdr.get("providerExtensions") + if isinstance(pe, dict): + # The SDR in FedRAMP's schema keeps them under providerExtensions. + for entries in (pe.get("assessorCommentResponses") or {}).values(): + carried += entries or [] + carried += (pe.get("assessorRecords") or {}).get("records", []) or [] for rr in sdr.get("rule_records", []): carried += rr.get("assessor_comment_responses", []) or [] carried += (sdr.get("assessor_records") or {}).get("records", []) or [] diff --git a/scripts/build-sdr.py b/scripts/build-sdr.py index 70dc500b..d209947a 100644 --- a/scripts/build-sdr.py +++ b/scripts/build-sdr.py @@ -1,272 +1,506 @@ #!/usr/bin/env python3 # ============================================================================= -# SECURITY DECISION RECORD BUILDER (CR26 SDR — the 20x SSP replacement) +# SECURITY DECISION RECORD BUILDER (CR26 SDR, FedRAMP's 2026-06-24 schema) # ============================================================================= -# CR26 replaces the traditional System Security Plan with a persistently -# maintained Security Decision Record (SDR-CSO-FRR): for each applicable FedRAMP -# rule, an explanation of how it is followed, plus verification, validation, -# independent verification, independent validation, responses to assessor -# comments, and rule-specific artifacts. SDR-CSO-MTD carries version + last -# update + source; the 20x extension SDR-CSX-KSI carries per-KSI summaries, and -# SDR-CSX-KMT (Class C) carries metric summaries over 30 days / up to a year / -# all daily metric data. +# The SDR says, for this 20x Class C offering: # -# It carries both views CR26 defines over the same rule families: per KSI -# (SDR-CSX-KSI, the 20x record) and per applicable Rev5 control (SDR-CSF-CTF, -# the Rev5 record, in rev5_controls). Both come from the control projection -# (scripts/_controls.py) computed from the canonical inventory and the KSI -# catalog, so they cannot disagree. The OSCAL SSP that used to carry the -# per-control statements is retired (CR26); this record replaces it. +# fedRampRequirements every applicable FedRAMP rule (SDR-CSO-FRR), from the +# governed records in data/frr-records.json, which +# scripts/_frr.py holds to the pinned rules and to +# evidence that resolves; +# keySecurityIndicators every KSI (SDR-CSX-KSI): its measures (the OPA rules +# annotated with it), the automated methods that verify +# it (the deploy-time plan gate and the signed runtime +# re-validation), tests and evidence; +# securityControls every NIST 800-53 Rev5 control in the FedRAMP Moderate +# baseline, plus the controls FedRAMP's KSIs map beyond +# it: how 20x meets each Rev5 objective. A control's +# status is no stronger than what backs it. +# +# The record is 20x. The control view explains how the Rev5 objectives are met +# by the 20x evidence; it is not a second certification claim. +# +# Status rules for a control (the honesty rule, applied to Rev5): +# Implemented inherited from AWS (its FedRAMP authorization), or +# backed by a KSI whose measures are checked +# automatically, or by an implemented FedRAMP rule, or, +# for a policy-and-procedure control (XX-1), the +# family's published policy; +# (no status) not applicable, with the reason; +# Partially Implemented everything else the projection calls implemented: +# the mechanism is described but nothing checks it yet. +# +# Validated against the vendored schema before it is written; nothing that +# fails is written. Site-specific data is under providerExtensions. # # build-sdr.py --catalog schemas/ksi-catalog.json --ksi-signal ksi-signal.json \ -# --vdr vdr-report.json --previous-sdr prev.json +# --runtime-signal ksi-signal-runtime.json --vdr vdr-report.json --previous-sdr prev.json # ============================================================================= import argparse +import hashlib +import importlib.util import json import os +import re +import subprocess import sys from datetime import datetime, timezone from pathlib import Path -# Shared generator helpers. The insert is __file__-relative, so this script stays -# runnable standalone from any working directory (see scripts/_common.py). sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from _common import prop # noqa: E402 import _assessor # noqa: E402 import _controls # noqa: E402 +import _fedramp_schema as fs # noqa: E402 +import _frr # noqa: E402 +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +MODERATE_PROFILE = REPO / "data" / "profiles" / "FedRAMP_rev5_MODERATE-baseline_profile.json" +POLICY_DIR = REPO / "infrastructure" / "policy" +POLICIES = REPO / "docs" / "policies" +SITE = "https://samaydlette.com" +REPO_URL = "https://github.com/sam-aydlette/samaydlette.com/blob/main" +HISTORY_DAYS = 366 # SDR-CSX-KMT: daily metric data up to the past year +SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)$") + +NO_ASSESSMENT = ("No independent assessment: no FedRAMP Recognized assessment service is engaged. " + "The provider-side verification and validation above is what an assessor would examine.") +WORKSTREAMS = { + "W2": "vulnerability report follow-ups", "W3": "certification package in FedRAMP's schemas", + "W4": "quarterly reporting cycle", "W5": "significant change notifications", + "W6": "incident reporting", "W7": "detection and evaluation", "W8": "trust center", + "W9": "FedRAMP Security Inbox", "W10": "scope, cryptography and secure configuration", + "sam": "an act of the operator (registration, assessor, application)", +} +EVIDENCE_WORDS = {"test": "test", "step": "pipeline step", "artifact": "published artifact", + "decision": "decision record"} + + +def _fail(msg): + raise SystemExit(f"::error::SDR: {msg} (fail-closed)") + + +# --- inputs --------------------------------------------------------------------------- + +def moderate_ids(path=MODERATE_PROFILE): + prof = json.loads(Path(path).read_text())["profile"] + return {i for imp in prof["imports"] for inc in imp.get("include-controls", []) for i in inc.get("with-ids", [])} + + +def policy_rules(policy_dir=POLICY_DIR): + """{KSI ID: [{"id", "title", "file"}]} from the OPA rule annotations + (custom.ksi_ids), read with `opa inspect` like check-policy-annotations.""" + out = subprocess.run(["opa", "inspect", "-a", str(policy_dir), "--format", "json"], + capture_output=True, text=True, check=True) + by_ksi = {} + for entry in json.loads(out.stdout).get("annotations", []) or []: + ann = entry.get("annotations") or {} + custom = ann.get("custom") or {} + if ann.get("scope") != "rule" or not custom.get("id"): + continue + f = Path((entry.get("location") or {}).get("file", "?")).name + for k in custom.get("ksi_ids") or []: + by_ksi.setdefault(k, []).append({"id": custom["id"], "title": ann.get("title", ""), "file": f}) + for rules in by_ksi.values(): + rules.sort(key=lambda r: (r["file"], r["id"])) + return by_ksi + + +def runtime_validations(path): + """Validations from the signed runtime signal, only when it verifies and is + fresh (the VDR builder's own loader); otherwise none, with the reason.""" + spec = importlib.util.spec_from_file_location("vdr_builder", REPO / "scripts" / "build-vdr-report.py") + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + rt = mod.load_runtime_signal(path) + if not (rt["verified"] and rt["fresh"]): + return [], rt["reason"] or "runtime signal not usable" + return rt["validations"], None + + +# --- FedRAMP rules -------------------------------------------------------------------- + +def _evidence_line(ev): + return f"{EVIDENCE_WORDS[ev['kind']]} `{ev['ref']}`" -HISTORY_DAYS = 366 # SDR-CSX-KMT: all daily metric data up to the past year - -NA = "N/A — self-attested proof of concept; no FedRAMP Recognized independent assessment service engaged (IVV is not applicable to an unsponsored system)." - - -def _control_map(irs): - """control_id -> {status, origination} from the control projection.""" - m = {} - for ir in irs: - m[ir["control-id"]] = {"status": prop(ir, "implementation-status"), - "origination": prop(ir, "control-origination")} - return m - - -def build_records(catalog, cmap): - """One SDR-CSO-FRR record per in-scope KSI, derived from its controls' projected state.""" - records = [] - for fam in catalog.get("KSI", {}).values(): - for ind in fam.get("indicators", []) or []: - if ind.get("retired"): - continue - controls = [] - impl = inh = na = 0 - for c in ind.get("controls", []) or []: - cid = c.get("control_id") - st = cmap.get(cid, {}) - controls.append({"control_id": cid, "status": st.get("status"), - "origination": st.get("origination")}) - o = st.get("origination") - if st.get("status") == "not-applicable": - na += 1 - elif o == "inherited" or o == "shared": - inh += 1 - else: - impl += 1 - if controls: - expl = (f"Satisfied through {len(controls)} NIST 800-53 control(s) " - f"({impl} system-implemented, {inh} inherited/shared, {na} not-applicable); " - f"see rev5_controls in this record for each control's implementation statement.") - else: - expl = ("Process/organizational indicator with no direct 800-53 control mapping; " - "satisfied at the operator level and documented in the linked policy.") - records.append({ - "rule_id": ind["id"], - "statement": ind.get("statement", ""), - "controls": controls, - "explanation": expl, - "verification": ("Automated: the deploy-time OPA gate and the per-deploy KSI signal " - "record the implementing controls; the daily runtime emitter " - "re-validates the live configuration against the same compiled policy."), - "validation": ("Effectiveness reviewed continuously by the daily runtime revalidation " - "(drift detector) and annually by the structural security review."), - "independent_verification": NA, - "independent_validation": NA, - "assessor_comment_responses": [], - "artifacts": ["/.well-known/ksi-signal.json", "/.well-known/security-decision-record.json"], - }) - return records - - -# CR26 implementation-status vocabulary (SDR-CSF-CTF) for the projection's -# OSCAL tokens. -REV5_STATUS = {"implemented": "Implemented", "partial": "Partially Implemented", "planned": "Planned", - "alternative": "Alternative Implementation", "not-applicable": "Not Applicable"} - - -def build_rev5_controls(irs, catalog): - """SDR-CSF-CTF: a summary for each applicable Rev5 control: parameter values, - implementation status, the mechanisms (the projection's statement, including - any inheritance), verification, validation, independent verification and - validation, and control-specific artifacts. Verification and validation - point at the records of the KSIs that claim the control rather than - restating them; a control no KSI claims says so.""" - ksis_by_control, _ = _controls.contributing_ksis(catalog) + +def _assessment(rule_id, assessor_by_rule): + entries = assessor_by_rule.get(rule_id) or [] + if not entries: + return [NO_ASSESSMENT] + return [f"Assessor record {e['record_id']} ({e['kind']}): {e['text']}" for e in entries] + + +def build_requirements(records, applicable, assessor_by_rule): out = [] - for ir in irs: - cid = ir["control-id"] - status = prop(ir, "implementation-status") - origination = prop(ir, "control-origination") - ksis = sorted(ksis_by_control.get(cid, ())) - if status == "not-applicable": - verification = validation = "Not applicable." - elif origination == "inherited": - verification = validation = ("Inherited from AWS under its FedRAMP certification " - "(leveraged authorization); verified and validated there.") - elif ksis: - verification = validation = ("See the rule records (rule_records) of the contributing KSIs: " - + ", ".join(ksis) + ".") - else: - verification = ("No KSI claims this control; the statement is maintained in the control " - "projection (scripts/_controls.py, data/component-definitions/) and " - "reviewed with it.") - validation = "No automated validation." - remarks = [ir["statements"][0]["remarks"]] if ir.get("statements") else [] - live = prop(ir, "implementation-status-remarks") + for r in records["records"]: + rid, status = r["frr_id"], r["status"] + impl = [r["implementation"]] + if status == "Not Applicable": + impl.append(f"Not applicable: {r['not_applicable']}") + if r.get("may_rationale"): + impl.append(f"Use of this permission: {r['may_rationale']}") + val = [] + if r.get("evidence"): + val.append("Evidence: " + "; ".join(_evidence_line(e) for e in r["evidence"]) + ".") + val.append("Checked on every build by scripts/_frr.py: the rule set matches the pinned FedRAMP " + "rules and every piece of evidence cited resolves.") + if r.get("gap"): + val.append(f"Gap: {r['gap']}") + val.append("Closes with: " + "; ".join(f"{c} ({WORKSTREAMS[c]})" for c in r["closes_with"]) + ".") + rec = {"frrID": rid} + if status != "Not Applicable": + rec["frrImplementationStatus"] = status + rec["frrImplementation"] = impl + rec["frrValidation"] = val + rec["frrAssessment"] = _assessment(rid, assessor_by_rule) + rec["providerExtensions"] = {"status": status, "force": applicable[rid]["force"], + "evidence": r.get("evidence", []), + "closesWith": r.get("closes_with", [])} + out.append(rec) + return out + + +# --- KSIs ----------------------------------------------------------------------------- + +def ksi_status(k): + """Implemented only when the KSI passes and its measures are checked + automatically against the plan; a pass by inventory or document alone is + partial.""" + if k.get("status") != "pass": + return "Not Implemented" + if k.get("method") == "policy-validation" and (k.get("evidence") or {}).get("validation_ids"): + return "Implemented" + return "Partially Implemented" + + +def build_ksis(catalog, signal, rules_by_ksi, runtime, runtime_reason, assessor_by_rule): + statements = {i["id"]: i for f in catalog["KSI"].values() for i in f["indicators"]} + sig = {k["id"]: k for k in signal.get("ksis", [])} + missing = sorted(set(statements) - set(sig)) + if missing: + _fail(f"the KSI signal carries no result for {', '.join(missing)}") + emitted = (signal.get("emitted_at") or "")[:10] or None + out, status = [], {} + for kid in sorted(statements): + k, cat = sig[kid], statements[kid] + st = ksi_status(k) + status[kid] = st + ev = k.get("evidence") or {} + comps = set(ev.get("component_refs") or []) + rt = [v for v in runtime if comps & set(v.get("component_refs") or [])] + plan_ok = bool(ev.get("validation_ids")) + methods = int(plan_ok) + int(bool(rt)) + rules = rules_by_ksi.get(kid, []) + impl = [cat["statement"]] + if rules: + impl.append("Measures: " + "; ".join(f"{r['title']} (`{r['file']}#{r['id']}`)" for r in rules) + ".") + impl.append(f"Measured by {k.get('method')}: {len(comps)} inventory component(s), " + f"{len(ev.get('validation_ids') or [])} deploy-time validation(s), " + f"{len(ev.get('failed_validation_ids') or [])} failing.") + val = [] + if plan_ok: + val.append("Verified on every deploy: OPA evaluates the Terraform plan against the measures above " + "before apply, and the deploy stops on a violation.") + if rt: + val.append(f"Re-validated daily at runtime: the signed runtime signal re-evaluates the same compiled " + f"policy against live configuration for {len(rt)} of these components.") + elif runtime_reason: + val.append(f"Runtime re-validation not counted for this build: {runtime_reason}.") + val.append(f"Automated methods in place: {methods} (FRC-CSX-VVK requires 2 for Class C).") + if st != "Implemented": + val.append("Status is not Implemented because " + + ("the KSI does not pass." if st == "Not Implemented" else + f"its evidence is {k.get('method')}, not an automated check of its measures.")) + evidence = [{"evidenceType": "Report", + "evidenceDescription": "Deploy-time KSI signal: inventory, validations and per-KSI results, " + "signed with cosign by the deploy workflow.", + "evidenceLocation": f"{SITE}/.well-known/ksi-signal.json", + **({"lastUpdated": emitted} if emitted else {})}] + if rt: + evidence.append({"evidenceType": "Report", + "evidenceDescription": "Runtime KSI signal: daily re-validation of live configuration, " + "signed with the runtime KMS key.", + "evidenceLocation": f"{SITE}/.well-known/ksi-signal-runtime.json"}) out.append({ - "control_id": cid, - "implementation_status": REV5_STATUS.get(status, status), - "origination": origination, - "parameters": [{"param_id": sp["param-id"], "values": sp.get("values", [])} - for sp in ir.get("set-parameters", [])], - "mechanisms": " ".join(remarks + ([live] if live else [])), - "contributing_ksis": ksis, - "verification": verification, - "validation": validation, - "independent_verification": NA, - "independent_validation": NA, - "assessor_comment_responses": [], - "artifacts": [lk["href"] for lk in ir.get("links", [])], + "ksiId": kid, + "ksiImplementationStatus": st, + "ksiImplementation": impl, + "ksiValidation": val, + "ksiAssessment": _assessment(kid, assessor_by_rule), + "ksiTests": [f"infrastructure/policy/{r['file']}#{r['id']}" for r in rules], + "ksiEvidence": evidence, + "providerExtensions": {"method": k.get("method"), "automatedMethods": methods, + "controls": [c["control_id"] for c in cat["controls"]]}, }) + return out, status + + +# --- controls ------------------------------------------------------------------------- + +def nist_id(cid): + """ac-2.1 -> AC-2(1).""" + base, _, enh = cid.partition(".") + return base.upper() + (f"({enh})" if enh else "") + + +def control_basis(ir, ksis_for, ksi_st, frrs_for, frr_st, policies): + """(status, or None when not applicable; the basis sentence).""" + cid = ir["control-id"] + st = _controls.prop(ir, "implementation-status") + orig = _controls.prop(ir, "control-origination") + if st == "not-applicable": + return None, "Not applicable." + if st == "partial": + return "Partially Implemented", "A contributing KSI is failing." + checked = sorted(k for k in ksis_for.get(cid, ()) if ksi_st.get(k) == "Implemented") + rules = sorted(r for r in frrs_for.get(cid, ()) if frr_st.get(r) == "Implemented") + fam = cid.split("-")[0] + if orig == "inherited": + return "Implemented", "Inherited from AWS under its FedRAMP authorization." + if checked: + return "Implemented", "Backed by automatically checked KSI(s): " + ", ".join(checked) + "." + if rules: + return "Implemented", "Backed by implemented FedRAMP rule(s): " + ", ".join(rules) + "." + if re.fullmatch(r"[a-z]{2}-1", cid) and fam in policies: + return "Implemented", f"Policy and procedures, published: {policies[fam]}" + return "Partially Implemented", ("The mechanism is described, but no automated check, implemented " + "FedRAMP rule or published policy shows it yet.") + + +def _find_rule(rules, rid): + for fam in rules["FRR"].values(): + for groups in fam["data"].values(): + for members in groups.values(): + if rid in members: + return members[rid] + _fail(f"{rid} is not in the pinned rules") + + +def _sort_key(cid): + fam, _, rest = cid.partition("-") + num, _, enh = rest.partition(".") + return (fam, int(num), int(enh or 0)) + + +def build_controls(irs, catalog, ksi_st, applicable, records, moderate, policies): + ksis_for, _ = _controls.contributing_ksis(catalog) + frr_st = {r["frr_id"]: r["status"] for r in records["records"]} + rules, _ = _rules.load_rules() + frrs_for = {} + for rid in applicable: + for c in _find_rule(rules, rid).get("controls", []) or []: + frrs_for.setdefault(str(c).lower(), set()).add(rid) + missing = sorted(moderate - {ir["control-id"] for ir in irs}) + if missing: + _fail(f"{len(missing)} Moderate control(s) have no implementation record: {', '.join(missing[:10])}") + out = [] + for ir in sorted(irs, key=lambda i: _sort_key(i["control-id"])): + cid = ir["control-id"] + status, basis = control_basis(ir, ksis_for, ksi_st, frrs_for, frr_st, policies) + statement = ir["statements"][0]["remarks"] if ir.get("statements") else "" + orig = _controls.prop(ir, "control-origination") + ks = sorted(ksis_for.get(cid, ())) + fr = sorted(frrs_for.get(cid, ())) + desc = [f"**Not applicable.** {statement}"] if status is None else [f"**Basis:** {basis}", statement] + desc.append(f"**Origination:** {orig}.") + desc.append("**20x coverage:** " + (", ".join(ks) if ks else "no KSI maps this control") + + ("; FedRAMP rules: " + ", ".join(fr) if fr else "") + ".") + if cid not in moderate: + desc.append("Beyond the FedRAMP Moderate baseline; included because a FedRAMP KSI maps it.") + rec = {"controlId": nist_id(cid)} + params = [{"parameterId": sp["param-id"], "parameterValue": ", ".join(sp["values"])} + for sp in ir.get("set-parameters", []) if sp.get("values")] + if params: + rec["parameterValues"] = params + if status: + rec["controlImplementationStatus"] = status + rec["controlImplementationDescription"] = "\n\n".join(d for d in desc if d) + rec["providerExtensions"] = {"basis": basis, "origination": orig, "ksis": ks, "fedrampRules": fr, + "inModerateBaseline": cid in moderate, + "status": status or "Not Applicable"} + out.append(rec) return out -def build_metrics(records, controls_in_scope, vdr, signal, history, now): - """SDR-CSX-KMT: metric snapshot + appended daily history (toward one year).""" +def policy_documents(policy_dir=POLICIES): + """{control family: URL of its published policy} for families with one.""" + return {p.stem.removesuffix("-policy"): f"{REPO_URL}/docs/policies/{p.name}" + for p in sorted(Path(policy_dir).glob("??-policy.md"))} + + +# --- metrics, version ----------------------------------------------------------------- + +def build_metrics(counts, vdr, signal, history, now): + """SDR-CSX-KMT: today's point and daily history toward one year.""" sig_vals = signal.get("validations", []) if signal else [] - failing = sum(1 for v in sig_vals if v.get("result") == "fail") vsum = (vdr or {}).get("summary", {}) today = now.date().isoformat() - point = { - "date": today, - "ksi_in_scope": len(records), - "controls_in_scope": controls_in_scope, - "signal_validations": len(sig_vals), - "signal_failing": failing, - "vdr_total": vsum.get("total_findings", 0), - "vdr_blocking": vsum.get("blocking", 0), - "vdr_accepted": vsum.get("risk_accepted", 0), - "vdr_kev": vsum.get("kev", 0), - } - history = [h for h in history if h.get("date") != today] - history.append(point) + point = {"date": today, **counts, + "signal_validations": len(sig_vals), + "signal_failing": sum(1 for v in sig_vals if v.get("result") == "fail"), + "vdr_total": vsum.get("total_findings", 0), "vdr_blocking": vsum.get("blocking", 0), + "vdr_accepted": vsum.get("risk_accepted", 0), "vdr_kev": vsum.get("kev", 0)} + history = [h for h in history if h.get("date") != today] + [point] history = sorted(history, key=lambda h: h.get("date", ""))[-HISTORY_DAYS:] - last30 = history[-30:] - def _summ(window): - if not window: - return {} + def summ(window): return {"days": len(window), "max_blocking": max(h.get("vdr_blocking", 0) for h in window), "max_failing_validations": max(h.get("signal_failing", 0) for h in window), "current_accepted": window[-1].get("vdr_accepted", 0)} + return {"current": point, "summary_30d": summ(history[-30:]), "summary_1y": summ(history), + "daily_metric_data": history} + + +def previous_history(prev): + pe = prev.get("providerExtensions") or {} + hist = (pe.get("metrics") or {}).get("daily_metric_data") + if hist is None: # the record before the schema reshape kept it at the top level + hist = (prev.get("metrics") or {}).get("daily_metric_data") + return [h for h in hist or [] if isinstance(h, dict)] + + +def content_hash(doc): + """What the version tracks: everything but the metadata, the daily + metrics and the hash itself.""" + body = {k: v for k, v in doc.items() if k not in ("metadata", "providerExtensions")} + pe = {k: v for k, v in (doc.get("providerExtensions") or {}).items() if k not in ("metrics", "contentSha256")} + raw = json.dumps({"body": body, "pe": pe}, sort_keys=True, separators=(",", ":")).encode() + return hashlib.sha256(raw).hexdigest() - return { - "current": point, - "summary_30d": _summ(last30), - "summary_1y": _summ(history), - "daily_metric_data": history, # all daily points up to a year (SDR-CSX-KMT) - "note": ("Daily metric history accumulates one point per deploy/day; the full " - "one-year window builds over time from the first published SDR."), + +def next_version(prev, digest): + """Semver: unchanged content keeps the previous version; changed content + bumps the patch; a previous record without a semver starts at 1.0.0.""" + v = (prev.get("metadata") or {}).get("version", "") + m = SEMVER.match(v or "") + if not m: + return "1.0.0" + if (prev.get("providerExtensions") or {}).get("contentSha256") == digest: + return v + return f"{m.group(1)}.{m.group(2)}.{int(m.group(3)) + 1}" + + +# --- build ---------------------------------------------------------------------------- + +def _tally(items, key): + out = {} + for it in items: + s = it["providerExtensions"][key] + out[s] = out.get(s, 0) + 1 + return dict(sorted(out.items())) + + +def build(catalog, signal, records, applicable, irs, moderate, rules_by_ksi, runtime, runtime_reason, + assessor_records, prof, prev, vdr, now, policies): + ids = [r["frr_id"] for r in records["records"]] + sorted( + i["id"] for f in catalog["KSI"].values() for i in f["indicators"]) + pseudo = [{"rule_id": i, "assessor_comment_responses": []} for i in ids] + block = _assessor.attach(pseudo, assessor_records) + by_rule = {p["rule_id"]: p["assessor_comment_responses"] for p in pseudo if p["assessor_comment_responses"]} + + reqs = build_requirements(records, applicable, by_rule) + ksis, ksi_st = build_ksis(catalog, signal, rules_by_ksi, runtime, runtime_reason, by_rule) + controls = build_controls(irs, catalog, ksi_st, applicable, records, moderate, policies) + in_mod = [c for c in controls if c["providerExtensions"]["inModerateBaseline"]] + beyond = [c for c in controls if not c["providerExtensions"]["inModerateBaseline"]] + ksi_counts = {} + for s in ksi_st.values(): + ksi_counts[s] = ksi_counts.get(s, 0) + 1 + counts = {"rules": len(reqs), "ksis": len(ksis), "controls_moderate": len(in_mod), + "controls_beyond_moderate": len(beyond)} + doc = { + "$schema": fs.stamp("sdr"), + "certificationPackageOverviewUri": fs.CPO_URI, + "metadata": {}, + "fedRampRequirements": reqs, + "keySecurityIndicators": ksis, + "securityControls": controls, + "providerExtensions": { + "certification": "FedRAMP 20x, Program path, Class C", + "class": prof.get("fedramp_class"), + "impact_level": prof.get("impact_level"), + "ksi_signal_id": signal.get("signal_id"), + "rules": _rules.pin(), + "summary": {"fedRampRequirements": _tally(reqs, "status"), + "keySecurityIndicators": dict(sorted(ksi_counts.items())), + "securityControlsModerate": _tally(in_mod, "status"), + "securityControlsBeyondModerate": _tally(beyond, "status")}, + "assessorRecords": block, + "assessorCommentResponses": by_rule, + "metrics": build_metrics(counts, vdr, signal, previous_history(prev), now), + }, } + digest = content_hash(doc) + doc["providerExtensions"]["contentSha256"] = digest + doc["metadata"] = {"version": next_version(prev, digest), "lastUpdated": now.isoformat(), + "updateSource": "Automated: scripts/build-sdr.py in the deploy workflow, from " + "data/frr-records.json, the KSI signal and the control projection"} + return doc -def main(): +def main(argv=None): ap = argparse.ArgumentParser() ap.add_argument("--catalog", default="schemas/ksi-catalog.json") ap.add_argument("--ksi-signal", default="ksi-signal.json") + ap.add_argument("--runtime-signal", default="ksi-signal-runtime.json") ap.add_argument("--vdr", default="vdr-report.json") ap.add_argument("--profile", default="../data/system-profile.json") + ap.add_argument("--frr-records", default=str(_frr.DEFAULT_PATH)) ap.add_argument("--previous-sdr", default=None) ap.add_argument("--output", default="security-decision-record.json") ap.add_argument("--md-output", default="security-decision-record.md") - ap.add_argument("--assessor-records", default=str(_assessor.RECORDS_DIR), - help="directory of signed assessor records (REQ-ASR-1); empty = no assessor record") - ap.add_argument("--assessor-identity", default=str(_assessor.IDENTITY_PATH), - help="pinned assessor identity the records must verify against") - a = ap.parse_args() + ap.add_argument("--assessor-records", default=str(_assessor.RECORDS_DIR)) + ap.add_argument("--assessor-identity", default=str(_assessor.IDENTITY_PATH)) + a = ap.parse_args(argv) now = datetime.now(timezone.utc) catalog = json.loads(Path(a.catalog).read_text()) - signal = json.loads(Path(a.ksi_signal).read_text()) if Path(a.ksi_signal).exists() else {} + if not Path(a.ksi_signal).exists(): + _fail(f"{a.ksi_signal} not found") + signal = json.loads(Path(a.ksi_signal).read_text()) vdr = json.loads(Path(a.vdr).read_text()) if Path(a.vdr).exists() else {} prof = json.loads(Path(a.profile).read_text()) if Path(a.profile).exists() else {} - history = [] + prev = {} if a.previous_sdr and Path(a.previous_sdr).exists(): try: - history = json.loads(Path(a.previous_sdr).read_text()).get("metrics", {}).get("daily_metric_data", []) or [] - except Exception: - history = [] - - # The projection needs the inventory: without it there is no control state - # to record, so a missing signal stops the build (fail-closed). + prev = json.loads(Path(a.previous_sdr).read_text()) + except json.JSONDecodeError: + prev = {} + records = _frr.load(a.frr_records) + applicable = _rules.applicable_provider_rules() irs = _controls.load(a.ksi_signal, a.catalog) - cmap = _control_map(irs) - records = build_records(catalog, cmap) - # REQ-ASR-1: assessor records enter only through the signed port; any record - # that does not verify fails the build. They are carried verbatim. + runtime, reason = runtime_validations(a.runtime_signal) assessor_records = _assessor.load_records(a.assessor_records, a.assessor_identity) - assessor_block = _assessor.attach(records, assessor_records) - metrics = build_metrics(records, len(cmap), vdr, signal, history, now) - - sdr = { - "record_type": "security-decision-record", - "schema": "fedramp-security-decision-record-schema-2026-06-24.json", - "note": "The CR26 replacement for the System Security Plan: per-KSI records (20x) and " - "per-Rev5-control records (rev5_controls), both from one control projection.", - # SDR-CSO-MTD - "metadata": { - "version": "live (regenerated each deploy)", - "last_updated": now.isoformat(), - "source_of_update": "scripts/build-sdr.py, derived from the canonical KSI inventory and the control projection", - }, - "class": prof.get("fedramp_class"), - "impact_level": prof.get("impact_level"), - "ksi_signal_id": (signal or {}).get("signal_id"), - "rule_records": records, # SDR-CSO-FRR + SDR-CSX-KSI - "rev5_controls": build_rev5_controls(irs, catalog), # SDR-CSF-CTF - "metrics": metrics, # SDR-CSX-KMT - # REQ-ASR-1: verified, signed assessor records not tied to one rule, and - # the status ("no assessor record" when none exist). - "assessor_records": assessor_block, - } - _assessor.verify_output(sdr, assessor_records) # T74: output text == signed text - Path(a.output).write_text(json.dumps(sdr, indent=2) + "\n") + doc = build(catalog, signal, records, applicable, irs, moderate_ids(), policy_rules(), runtime, reason, + assessor_records, prof, prev, vdr, now, policy_documents()) + _assessor.verify_output(doc, assessor_records) # T74 + fs.write_validated(doc, "sdr", a.output) if a.md_output: - Path(a.md_output).write_text(render_markdown(sdr) + "\n") - print(f"security-decision-record: {len(records)} per-KSI rule records; " - f"{metrics['current']['controls_in_scope']} controls in scope; " - f"{len(metrics['daily_metric_data'])} day(s) of metric history") + Path(a.md_output).write_text(render_markdown(doc) + "\n") + s = doc["providerExtensions"]["summary"] + print(f"security-decision-record {doc['metadata']['version']}: rules {s['fedRampRequirements']}; " + f"KSIs {s['keySecurityIndicators']}; Moderate controls {s['securityControlsModerate']}") return 0 -def _assessor_lines(sdr): - block = sdr.get("assessor_records") or {"status": _assessor.NO_RECORD, "records": []} - entries = list(block.get("records", [])) - for r in sdr["rule_records"]: - entries += [dict(e, rule_id=r["rule_id"]) for e in r.get("assessor_comment_responses", [])] +# --- human-readable view (CDS-CSO-CBF: same data as the JSON) ------------------------- + +def _cell(text): + return str(text).replace("|", "\\|").replace("\n", " ") + + +def _assessor_lines(doc): + pe = doc["providerExtensions"] + entries = list(pe["assessorRecords"].get("records", [])) + for rid, es in pe.get("assessorCommentResponses", {}).items(): + entries += [dict(e, rule_id=rid) for e in es] if not entries: return ["**Assessor records:** No assessor record. Nothing on this page was written " "or signed by an assessor."] - out = [f"**Assessor records:** {block['status']}. Each is quoted verbatim from the " + out = [f"**Assessor records:** {pe['assessorRecords']['status']}. Each is quoted verbatim from the " "assessor's signed record; the signature is in the JSON."] for e in sorted(entries, key=lambda e: e["record_id"]): rule = f" (`{e['rule_id']}`)" if e.get("rule_id") else "" @@ -275,42 +509,49 @@ def _assessor_lines(sdr): return out -def render_markdown(sdr): - m = sdr["metadata"] - cur = sdr["metrics"]["current"] +def _summary_line(d): + return ", ".join(f"{k} {v}" for k, v in d.items()) or "none" + + +def render_markdown(doc): + m, pe = doc["metadata"], doc["providerExtensions"] + s = pe["summary"] out = ["# Security Decision Record", "", - f"_{sdr['note']}_", "", - f"- **Class:** {sdr['class']} | **Impact:** {sdr['impact_level']}", - f"- **Version:** {m['version']} | **Last updated:** {m['last_updated']}", - f"- **Source:** {m['source_of_update']}", - f"- **Bound to inventory signal:** `{sdr['ksi_signal_id']}`", - "", - "## Metrics (SDR-CSX-KMT)", "", - f"- KSIs in scope: **{cur['ksi_in_scope']}** | Controls in scope: **{cur['controls_in_scope']}**", - f"- Signal validations: {cur['signal_validations']} ({cur['signal_failing']} failing)", - f"- Vulnerabilities: {cur['vdr_total']} total, {cur['vdr_blocking']} blocking, " - f"{cur['vdr_accepted']} accepted, {cur['vdr_kev']} KEV", - f"- Daily metric history: {len(sdr['metrics']['daily_metric_data'])} day(s) on record " - "(builds toward one year)", - "", - "## Per-rule records (SDR-CSO-FRR / SDR-CSX-KSI)", "", - "Independent verification and validation are N/A for this self-attested system " - "(no FedRAMP Recognized assessor). Verification and validation below are the " - "provider-side evidence an assessor would consume.", "", - *_assessor_lines(sdr), "", - "| KSI | Controls | Explanation |", "|---|---|---|"] - for r in sdr["rule_records"]: - cids = ", ".join(c["control_id"] for c in r["controls"]) or "—" - out.append("| `{rid}` | {cids} | {ex} |".format( - rid=r["rule_id"], cids=cids, ex=r["explanation"].replace("|", "\\|"))) - rc = sdr.get("rev5_controls", []) - by_status = {} - for c in rc: - by_status[c["implementation_status"]] = by_status.get(c["implementation_status"], 0) + 1 - out += ["", "## Rev5 controls (SDR-CSF-CTF)", "", - f"{len(rc)} controls, each with its parameter values, implementation status, mechanisms, " - "verification and validation in `rev5_controls` of the JSON record. By status: " - + (", ".join(f"{k} {v}" for k, v in sorted(by_status.items())) or "none") + "."] + f"_{pe['certification']}. Every applicable FedRAMP rule, every Key Security Indicator, and every " + "NIST 800-53 Rev5 control in the Moderate baseline, with how 20x evidence meets it._", "", + f"- **Version:** {m['version']} | **Last updated:** {m['lastUpdated']}", + f"- **Source:** {m['updateSource']}", + f"- **Bound to inventory signal:** `{pe['ksi_signal_id']}`", + f"- **FedRAMP rules (pinned):** {pe['rules']['version']} at `{pe['rules']['commit'][:12]}`", + "", "## Summary", "", + f"- FedRAMP rules ({len(doc['fedRampRequirements'])}): {_summary_line(s['fedRampRequirements'])}", + f"- Key Security Indicators ({len(doc['keySecurityIndicators'])}): " + f"{_summary_line(s['keySecurityIndicators'])}", + f"- Rev5 Moderate controls ({sum(s['securityControlsModerate'].values())}): " + f"{_summary_line(s['securityControlsModerate'])}", + f"- Controls beyond Moderate mapped by KSIs ({sum(s['securityControlsBeyondModerate'].values())}): " + f"{_summary_line(s['securityControlsBeyondModerate'])}", + "", *_assessor_lines(doc), "", + "## FedRAMP rules", "", "| Rule | Status | Implementation | Gap / closes with |", "|---|---|---|---|"] + for r in doc["fedRampRequirements"]: + x = r["providerExtensions"] + gap = next((v for v in r["frrValidation"] if v.startswith("Gap: ")), "") + closes = next((v for v in r["frrValidation"] if v.startswith("Closes with: ")), "") + out.append(f"| `{r['frrID']}` | {x['status']} | {_cell(' '.join(r['frrImplementation']))} | " + f"{_cell((gap + ' ' + closes).strip()) or '—'} |") + out += ["", "## Key Security Indicators", "", + "| KSI | Status | Automated methods | Measures |", "|---|---|---|---|"] + for k in doc["keySecurityIndicators"]: + x = k["providerExtensions"] + out.append(f"| `{k['ksiId']}` | {k['ksiImplementationStatus']} | {x['automatedMethods']} | " + f"{_cell('; '.join(k['ksiTests'])) or '—'} |") + out += ["", "## NIST 800-53 Rev5 controls", "", + "| Control | Status | Basis | 20x coverage |", "|---|---|---|---|"] + for c in doc["securityControls"]: + x = c["providerExtensions"] + cov = ", ".join(x["ksis"] + x["fedrampRules"]) or "—" + tag = "" if x["inModerateBaseline"] else " (beyond Moderate)" + out.append(f"| {c['controlId']}{tag} | {x['status']} | {_cell(x['basis'])} | {_cell(cov)} |") out += ["", "---", "_Source of truth: the signed `security-decision-record.json`._"] return "\n".join(out) diff --git a/scripts/reconcile.py b/scripts/reconcile.py index 5f187a81..c2231d30 100644 --- a/scripts/reconcile.py +++ b/scripts/reconcile.py @@ -369,11 +369,18 @@ def check_c_suppressions(checkov_skips, register, vdr): # ---------------------------------------------------------------------------- # (d) impact level identical; nothing asserts Low # ---------------------------------------------------------------------------- +def sdr_fields(sdr): + """Where the SDR keeps its site-specific fields: under providerExtensions + since it follows FedRAMP's schema (the top level is FedRAMP's).""" + pe = sdr.get("providerExtensions") + return pe if isinstance(pe, dict) else sdr + + def extract_impacts(signal, sdr, cpo, vdr, dashboard_html): impacts = {} impacts["signal"] = normalize_impact( signal.get("categorization", {}).get("impact_level")) - impacts["sdr"] = normalize_impact(sdr.get("impact_level")) + impacts["sdr"] = normalize_impact(sdr_fields(sdr).get("impact_level")) impacts["cpo"] = normalize_impact(cpo.get("impact_level")) impacts["vdr"] = normalize_impact(vdr.get("impact_level") or ("class " + vdr.get("class", "")).strip()) @@ -406,7 +413,7 @@ def check_e_binding(signal, sdr, cpo, vdr): sid = signal.get("signal_id") if not sid: return ["(e) signal has no signal_id"] - for art, doc in (("vdr", vdr), ("sdr", sdr), ("cpo", cpo)): + for art, doc in (("vdr", vdr), ("sdr", sdr_fields(sdr)), ("cpo", cpo)): got = doc.get("ksi_signal_id") if got != sid: violations.append(f"(e) {art} signal_id {got!r} != inventory signal_id {sid!r}") diff --git a/tests/test_assessor_records.py b/tests/test_assessor_records.py index 894b6bca..dc0a816e 100644 --- a/tests/test_assessor_records.py +++ b/tests/test_assessor_records.py @@ -153,11 +153,25 @@ def test_t74_output_dropping_a_signed_record_fails(tmp_path): def test_sdr_markdown_states_no_assessor_record(): - sdr = {"note": "n", "class": "C", "impact_level": "low", "ksi_signal_id": "s", - "metadata": {"version": "v", "last_updated": "t", "source_of_update": "s"}, - "metrics": {"current": {"ksi_in_scope": 0, "controls_in_scope": 0, "signal_validations": 0, - "signal_failing": 0, "vdr_total": 0, "vdr_blocking": 0, - "vdr_accepted": 0, "vdr_kev": 0}, - "daily_metric_data": []}, - "rule_records": [], "assessor_records": {"status": "no assessor record", "records": []}} + sdr = {"metadata": {"version": "1.0.0", "lastUpdated": "t", "updateSource": "s"}, + "fedRampRequirements": [], "keySecurityIndicators": [], "securityControls": [], + "providerExtensions": {"certification": "c", "ksi_signal_id": "s", + "rules": {"version": "v", "commit": "0" * 40}, + "summary": {"fedRampRequirements": {}, "keySecurityIndicators": {}, + "securityControlsModerate": {}, "securityControlsBeyondModerate": {}}, + "assessorRecords": {"status": "no assessor record", "records": []}, + "assessorCommentResponses": {}}} assert "No assessor record" in sdr_mod.render_markdown(sdr) + + +def test_t74_reads_the_schema_shaped_sdr(tmp_path): + recs = _assessor.load_records(_dir_with(tmp_path, "genuine.json"), PIN) + rules = _rules("KSI-TEST-01") + block = _assessor.attach(rules, recs) + by_rule = {r["rule_id"]: r["assessor_comment_responses"] for r in rules if r["assessor_comment_responses"]} + sdr = {"providerExtensions": {"assessorRecords": block, "assessorCommentResponses": by_rule}} + _assessor.verify_output(sdr, recs) + bad = copy.deepcopy(sdr) + next(iter(bad["providerExtensions"]["assessorCommentResponses"].values()))[0]["text"] = "Softened." + with pytest.raises(SystemExit): + _assessor.verify_output(bad, recs) diff --git a/tests/test_controls.py b/tests/test_controls.py index 75e0e53a..c9a67ba0 100644 --- a/tests/test_controls.py +++ b/tests/test_controls.py @@ -83,34 +83,7 @@ def test_a_failing_contributing_ksi_downgrades_its_controls(): assert status == "partial" -# --- the SDR carries the per-control record (SDR-CSF-CTF) --------------------------- - -def test_the_sdr_summarizes_every_projected_control(): - sdr = _load("build_sdr", "build-sdr.py") - irs = _projection() - rows = sdr.build_rev5_controls(irs, json.loads(CATALOG.read_text())) - assert [r["control_id"] for r in rows] == [ir["control-id"] for ir in irs] - vocab = {"Implemented", "Partially Implemented", "Planned", "Alternative Implementation", "Not Applicable"} - for r, ir in zip(rows, irs, strict=True): - assert r["implementation_status"] in vocab, r["control_id"] - assert r["mechanisms"].startswith(ir["statements"][0]["remarks"]) - assert r["parameters"] == [{"param_id": sp["param-id"], "values": sp.get("values", [])} - for sp in ir.get("set-parameters", [])] - for k in ("verification", "validation", "independent_verification", "independent_validation"): - assert r[k].strip(), (r["control_id"], k) - # Parameter values the FedRAMP profile sets are carried, not dropped. - assert sum(len(r["parameters"]) for r in rows) > 200 - - -def test_sdr_verification_points_at_the_contributing_ksis(): - sdr = _load("build_sdr2", "build-sdr.py") - rows = sdr.build_rev5_controls(_projection(), json.loads(CATALOG.read_text())) - claimed = [r for r in rows if r["contributing_ksis"] and r["implementation_status"] != "Not Applicable" - and r["origination"] != "inherited"] - assert claimed - for r in claimed: - assert all(k in r["verification"] for k in r["contributing_ksis"]), r["control_id"] - +# --- the SDR carries the per-control record: tests/test_sdr.py ---------------------- def test_the_sdr_builder_fails_closed_without_the_inventory(tmp_path): r = subprocess.run([sys.executable, str(REPO / "scripts" / "build-sdr.py"), diff --git a/tests/test_evidence_freshness.py b/tests/test_evidence_freshness.py index 1472f2e8..110d05d2 100644 --- a/tests/test_evidence_freshness.py +++ b/tests/test_evidence_freshness.py @@ -141,9 +141,9 @@ def test_each_artifact_is_measured_by_its_own_field_and_window(tmp_path): assert freshness.main(["--url", path.as_uri()]) == 0 path.write_text(json.dumps({"generated_at": hours_ago(800)})) assert freshness.main(["--url", path.as_uri()]) == 1 - # A nested field (the SDR's metadata.last_updated). + # A nested field (the SDR's metadata.lastUpdated, FedRAMP's schema). sdr = tmp_path / "security-decision-record.json" - sdr.write_text(json.dumps({"metadata": {"last_updated": hours_ago(5)}})) + sdr.write_text(json.dumps({"metadata": {"lastUpdated": hours_ago(5)}})) assert freshness.main(["--url", sdr.as_uri()]) == 0 diff --git a/tests/test_evidence_watchdog.py b/tests/test_evidence_watchdog.py index 0bdd0e27..6ce98c98 100644 --- a/tests/test_evidence_watchdog.py +++ b/tests/test_evidence_watchdog.py @@ -131,7 +131,7 @@ def test_each_listed_artifact_past_its_own_window_is_counted(): objects[".well-known/trust-center.json"] = {"generated_at": "2026-09-24T11:00:00Z"} objects[".well-known/vdr-trend.json"] = {"updated_at": "2026-09-24T11:00:00Z"} # 31 days: past the deploy window. - objects[".well-known/security-decision-record.json"] = {"metadata": {"last_updated": "2026-08-25T00:00:00Z"}} + objects[".well-known/security-decision-record.json"] = {"metadata": {"lastUpdated": "2026-08-25T00:00:00Z"}} out = compute(objects) assert sorted(out["stale"]) == [".well-known/security-decision-record.json", ".well-known/vdr-trend.json"] assert out["metrics"]["StaleArtifacts"] == 2 diff --git a/tests/test_reconcile.py b/tests/test_reconcile.py index 3abc7099..4dbe3634 100644 --- a/tests/test_reconcile.py +++ b/tests/test_reconcile.py @@ -54,7 +54,7 @@ def clean_set(): "resource_type": "AWS::S3::Bucket", "native_id": ARN_BUCKET}, ], } - sdr = {"record_type": "security-decision-record", "impact_level": "Moderate", "ksi_signal_id": SIGNAL_ID} + sdr = {"$schema": "x", "providerExtensions": {"impact_level": "Moderate", "ksi_signal_id": SIGNAL_ID}} cpo = {"package_type": "certification-package-overview", "impact_level": "Moderate", "ksi_signal_id": SIGNAL_ID} vdr = {"impact_level": "Moderate", "class": "C", "ksi_signal_id": SIGNAL_ID, @@ -152,10 +152,23 @@ def test_c_risk_accepted_needs_vdr_decision_id(): assert any("no non-null decision_id" in x for x in v) +def _fields(s, art): + """The dict an artifact keeps its impact level and signal binding in.""" + return rc.sdr_fields(s[art]) if art == "sdr" else s[art] + + +def test_d_reads_the_sdr_provider_extensions_not_its_top_level(): + s = clean_set() + s["sdr"]["impact_level"] = "Moderate" + s["sdr"]["providerExtensions"]["impact_level"] = "Low" + v = rc.check_d_impact(s["signal"], s["sdr"], s["cpo"], s["vdr"], s["dashboard_html"]) + assert v == ["(d) sdr impact level is 'low', expected 'moderate'"] + + @pytest.mark.parametrize("art", ["sdr", "cpo"]) def test_d_impact_catches_a_low_sdr_or_cpo(art): s = clean_set() - s[art]["impact_level"] = "Low" + _fields(s, art)["impact_level"] = "Low" v = rc.check_d_impact(s["signal"], s["sdr"], s["cpo"], s["vdr"], s["dashboard_html"]) assert v == [f"(d) {art} impact level is 'low', expected 'moderate'"] @@ -163,7 +176,7 @@ def test_d_impact_catches_a_low_sdr_or_cpo(art): @pytest.mark.parametrize("art", ["sdr", "cpo"]) def test_d_impact_catches_an_sdr_or_cpo_with_no_impact_level(art): s = clean_set() - del s[art]["impact_level"] + del _fields(s, art)["impact_level"] v = rc.check_d_impact(s["signal"], s["sdr"], s["cpo"], s["vdr"], s["dashboard_html"]) assert v == [f"(d) {art} carries no extractable impact level"] @@ -184,7 +197,7 @@ def test_d_impact_catches_low_dashboard(): @pytest.mark.parametrize("art", ["vdr", "sdr", "cpo"]) def test_e_binding_catches_mismatched_signal_id(art): s = clean_set() - s[art]["ksi_signal_id"] = "99999999-9999-4999-8999-999999999999" + _fields(s, art)["ksi_signal_id"] = "99999999-9999-4999-8999-999999999999" v = rc.check_e_binding(s["signal"], s["sdr"], s["cpo"], s["vdr"]) assert v == [f"(e) {art} signal_id '99999999-9999-4999-8999-999999999999' != inventory signal_id '{SIGNAL_ID}'"] diff --git a/tests/test_sdr.py b/tests/test_sdr.py new file mode 100644 index 00000000..39190cbf --- /dev/null +++ b/tests/test_sdr.py @@ -0,0 +1,221 @@ +"""The Security Decision Record in FedRAMP's schema: every applicable rule, +every KSI and every Moderate control, none stronger than what backs it.""" + +import copy +import importlib.util +import json +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 _controls # noqa: E402 +import _fedramp_schema as fs # noqa: E402 +import _frr # noqa: E402 +import _rules # noqa: E402 + +spec = importlib.util.spec_from_file_location("build_sdr", REPO / "scripts" / "build-sdr.py") +sdr = importlib.util.module_from_spec(spec) +spec.loader.exec_module(sdr) + +CATALOG = REPO / "infrastructure" / "schemas" / "ksi-catalog.json" +FIX_SIGNAL = REPO / "tests" / "fixtures" / "clean" / "ksi-signal.json" +NOW = datetime(2026, 11, 5, 12, tzinfo=timezone.utc) +POLICIES = {"ac": "https://example.invalid/ac-policy.md"} + + +def _catalog(): + return json.loads(CATALOG.read_text()) + + +def _signal(method="policy-validation", status="pass", overrides=None): + """The clean fixture inventory plus a result for every KSI.""" + s = json.loads(FIX_SIGNAL.read_text()) + s["ksis"] = [] + for f in _catalog()["KSI"].values(): + for i in f["indicators"]: + s["ksis"].append({"id": i["id"], "status": status, "method": method, + "evidence": {"validation_ids": ["v-1"], "failed_validation_ids": [], + "component_refs": ["aws::function::app"]}}) + for k in s["ksis"]: + k.update((overrides or {}).get(k["id"], {})) + return s + + +def _build(signal=None, prev=None, records=None, irs=None, runtime=(), rules_by_ksi=None): + signal = signal or _signal() + return sdr.build(_catalog(), signal, records or _frr.load(), _rules.applicable_provider_rules(), + irs if irs is not None else _controls.project(signal, _catalog()), + sdr.moderate_ids(), rules_by_ksi or {}, list(runtime), None if runtime else "none supplied", + [], {"fedramp_class": "C", "impact_level": "Moderate"}, prev or {}, {}, NOW, POLICIES) + + +@pytest.fixture(scope="module") +def doc(): + return _build() + + +# --- shape --------------------------------------------------------------------------- + +def test_it_validates_against_fedramps_schema(doc): + assert fs.validate(doc, "sdr") == [] + + +def test_every_applicable_rule_is_listed_once(doc): + ids = [r["frrID"] for r in doc["fedRampRequirements"]] + assert sorted(ids) == sorted(_rules.applicable_provider_rules()) and len(ids) == len(set(ids)) + + +def test_not_applicable_rules_carry_no_status_and_say_why(doc): + na = [r for r in doc["fedRampRequirements"] if r["providerExtensions"]["status"] == "Not Applicable"] + assert na + for r in na: + assert "frrImplementationStatus" not in r + assert any(line.startswith("Not applicable: ") for line in r["frrImplementation"]) + + +def test_every_ksi_is_listed_with_tests_and_evidence(doc): + assert len(doc["keySecurityIndicators"]) == 46 + for k in doc["keySecurityIndicators"]: + assert k["ksiEvidence"] and k["ksiValidation"] and k["ksiAssessment"] + + +def test_every_moderate_control_is_addressed(doc): + got = {c["controlId"] for c in doc["securityControls"] if c["providerExtensions"]["inModerateBaseline"]} + assert got == {sdr.nist_id(c) for c in sdr.moderate_ids()} and len(got) == 323 + + +def test_every_projected_control_is_carried_with_its_parameters(doc): + irs = _controls.project(_signal(), _catalog()) + assert len(doc["securityControls"]) == len(irs) + assert sum(len(c.get("parameterValues", [])) for c in doc["securityControls"]) > 200 + + +def test_every_control_names_its_20x_coverage(doc): + for c in doc["securityControls"]: + assert "**20x coverage:**" in c["controlImplementationDescription"], c["controlId"] + + +def test_nist_ids(): + assert sdr.nist_id("ac-2") == "AC-2" and sdr.nist_id("ac-2.12") == "AC-2(12)" + + +# --- honesty rules ------------------------------------------------------------------- + +def _ir(cid, status="implemented", origination="sp-system"): + return {"control-id": cid, "props": [{"name": "implementation-status", "value": status}, + {"name": "control-origination", "value": origination}]} + + +@pytest.mark.parametrize("ir,ksis,ksi_st,frrs,frr_st,want", [ + (_ir("sc-13", origination="inherited"), {}, {}, {}, {}, "Implemented"), + (_ir("sc-13"), {"sc-13": {"KSI-A"}}, {"KSI-A": "Implemented"}, {}, {}, "Implemented"), + (_ir("sc-13"), {"sc-13": {"KSI-A"}}, {"KSI-A": "Partially Implemented"}, {}, {}, "Partially Implemented"), + (_ir("sc-13"), {}, {}, {"sc-13": {"R-1"}}, {"R-1": "Implemented"}, "Implemented"), + (_ir("sc-13"), {}, {}, {"sc-13": {"R-1"}}, {"R-1": "Partially Implemented"}, "Partially Implemented"), + (_ir("ac-1"), {}, {}, {}, {}, "Implemented"), # policy control, policy published + (_ir("sc-1"), {}, {}, {}, {}, "Partially Implemented"), # no sc policy in POLICIES + (_ir("ac-2"), {}, {}, {}, {}, "Partially Implemented"), # nothing backs it + (_ir("ac-2", status="partial"), {}, {}, {}, {}, "Partially Implemented"), + (_ir("ac-2", status="not-applicable"), {}, {}, {}, {}, None), +]) +def test_a_control_is_no_stronger_than_what_backs_it(ir, ksis, ksi_st, frrs, frr_st, want): + assert sdr.control_basis(ir, ksis, ksi_st, frrs, frr_st, POLICIES)[0] == want + + +@pytest.mark.parametrize("k,want", [ + ({"status": "pass", "method": "policy-validation", "evidence": {"validation_ids": ["v"]}}, "Implemented"), + ({"status": "pass", "method": "policy-validation", "evidence": {"validation_ids": []}}, "Partially Implemented"), + ({"status": "pass", "method": "inventory-attestation", "evidence": {}}, "Partially Implemented"), + ({"status": "pass", "method": "documentation", "evidence": {}}, "Partially Implemented"), + ({"status": "fail", "method": "policy-validation", "evidence": {"validation_ids": ["v"]}}, "Not Implemented"), +]) +def test_a_ksi_is_implemented_only_when_its_measures_are_checked(k, want): + assert sdr.ksi_status(k) == want + + +def test_runtime_revalidation_counts_as_a_second_automated_method(): + rt = [{"validation_id": "r-1", "component_refs": ["aws::function::app"], "result": "pass"}] + d = _build(runtime=rt) + assert {k["providerExtensions"]["automatedMethods"] for k in d["keySecurityIndicators"]} == {2} + d = _build() + assert {k["providerExtensions"]["automatedMethods"] for k in d["keySecurityIndicators"]} == {1} + + +# --- known-bad: each fails closed for its own reason -------------------------------- + +def test_a_moderate_control_missing_from_the_projection_fails(): + irs = [ir for ir in _controls.project(_signal(), _catalog()) if ir["control-id"] != "ac-2"] + with pytest.raises(SystemExit, match="1 Moderate control.*ac-2"): + _build(irs=irs) + + +def test_a_signal_without_a_ksi_result_fails(): + s = _signal() + s["ksis"] = [k for k in s["ksis"] if k["id"] != "KSI-CED-RAT"] + with pytest.raises(SystemExit, match="no result for KSI-CED-RAT"): + _build(signal=s) + + +def test_an_invalid_record_set_never_reaches_the_sdr(tmp_path): + bad = json.loads(_frr.DEFAULT_PATH.read_text()) + bad["records"] = bad["records"][1:] + p = tmp_path / "frr.json" + p.write_text(json.dumps(bad)) + with pytest.raises(SystemExit, match="no record for 1 applicable rule"): + _frr.load(p) + + +def test_a_document_failing_the_schema_is_not_written(tmp_path, doc): + bad = copy.deepcopy(doc) + bad["keySecurityIndicators"][0].pop("ksiTests") + with pytest.raises(SystemExit, match="does not validate"): + fs.write_validated(bad, "sdr", tmp_path / "sdr.json") + assert not (tmp_path / "sdr.json").exists() + + +# --- version and history ------------------------------------------------------------- + +def test_version_starts_at_1_0_0_after_the_unversioned_record(doc): + assert _build(prev={"metadata": {"version": "live (regenerated each deploy)"}})["metadata"]["version"] == "1.0.0" + + +def test_unchanged_content_keeps_its_version_and_a_change_bumps_it(doc): + again = _build(prev=doc) + assert again["metadata"]["version"] == doc["metadata"]["version"] + prev = copy.deepcopy(doc) + prev["metadata"]["version"] = "1.0.7" + prev["providerExtensions"]["contentSha256"] = "0" * 64 + assert _build(prev=prev)["metadata"]["version"] == "1.0.8" + + +def test_daily_metrics_carry_over_from_the_record_before_the_reshape(): + old = {"metrics": {"daily_metric_data": [{"date": "2026-11-01", "vdr_blocking": 0, "signal_failing": 0}]}} + hist = _build(prev=old)["providerExtensions"]["metrics"]["daily_metric_data"] + assert [h["date"] for h in hist] == ["2026-11-01", "2026-11-05"] + + +# --- the human view says the same thing as the JSON --------------------------------- + +def test_markdown_counts_match_the_json(doc): + md = sdr.render_markdown(doc) + s = doc["providerExtensions"]["summary"] + assert f"- Rev5 Moderate controls (323): {sdr._summary_line(s['securityControlsModerate'])}" in md + assert md.count("\n| `") == len(doc["fedRampRequirements"]) + len(doc["keySecurityIndicators"]) + assert "No assessor record" in md + + +def test_the_builder_runs_end_to_end(tmp_path): + if not shutil.which("opa"): + pytest.skip("opa not available") + sig = tmp_path / "ksi-signal.json" + sig.write_text(json.dumps(_signal())) + out = tmp_path / "sdr.json" + assert sdr.main(["--catalog", str(CATALOG), "--ksi-signal", str(sig), "--runtime-signal", str(tmp_path / "none"), + "--vdr", str(tmp_path / "none"), "--profile", str(REPO / "data" / "system-profile.json"), + "--output", str(out), "--md-output", str(tmp_path / "sdr.md")]) == 0 + assert fs.validate(json.loads(out.read_text()), "sdr") == [] diff --git a/website/assets/js/trust.js b/website/assets/js/trust.js index 058d0425..dde882b2 100644 --- a/website/assets/js/trust.js +++ b/website/assets/js/trust.js @@ -23,7 +23,7 @@ const ARTIFACTS = [ ['boundary-map.json', 'The authorization boundary map'], ['reconcile-report.json', 'The reconciliation gate’s report for this deploy'], ['ksi-signal.json', 'The canonical inventory and KSI results'], - ['security-decision-record.json', 'Security Decision Record: how each KSI and each Rev5 control is met (replaces the SSP)'], + ['security-decision-record.json', 'Security Decision Record: every applicable FedRAMP rule, KSI and Rev5 Moderate control, with status and evidence'], ['certification-package-overview.json', 'Certification Package Overview'], ['vdr-report.json', 'Vulnerability Detection and Response report'], ['vdr-detail-report.json', 'Vulnerability Detail Report (CR26 VER-RPT-VDT): findings not accepted'], From 1db3a03e0dfad20f162900fc3220e0ca269da735 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 15:52:33 -0500 Subject: [PATCH 03/17] feat(frr): SDR records state what the schema-shaped SDR delivers on deploy SDR-CSO-MTD Implemented; SDR-CSO-FRR, SDR-CSX-KSI, FRC-CSX-VVK and FRC-CSX-VVR gaps restated for the post-deploy state. Co-Authored-By: Claude Opus 5.5 --- data/frr-records.json | 87 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 18 deletions(-) diff --git a/data/frr-records.json b/data/frr-records.json index d84c52f9..6a767bed 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -639,9 +639,9 @@ { "frr_id": "FRC-CSX-VVK", "status": "Partially Implemented", - "implementation": "Terraform plans are checked against the OPA policies on every deploy, and the runtime Lambda re-evaluates the same Rego against live configuration for object stores and the distribution daily (ksi-signal-runtime.json).", + "implementation": "Terraform plans are checked against the OPA policies on every deploy, and the runtime Lambda re-evaluates the same Rego against live configuration daily. The SDR counts the automated methods in place for each KSI (plan gate, plus runtime only when the signed runtime signal verifies and is fresh).", "evidence": [], - "gap": "Class C requires at least two automated methods for each KSI. The runtime check covers only some component types, and no record counts the automated methods per KSI to show two exist for each.", + "gap": "On the latest inputs 34 KSIs have two automated methods, 3 have one, and 9 have none (KSI-CED-RAT, KSI-IAM-AAM, KSI-IAM-APM, KSI-IAM-ELP, KSI-IAM-JIT, KSI-IAM-SNU, KSI-IAM-SUS, KSI-SCR-MIT, KSI-SCR-MON). To close: a second automated method for the 3, and two for the 9.", "closes_with": [ "W7" ] @@ -651,9 +651,9 @@ "status": "Partially Implemented", "implementation": "scripts/_frr.py checks the rule records automatically on every build: the set matches the pinned corpus, and every piece of evidence cited resolves to a test, workflow step, published artifact or decision.", "evidence": [], - "gap": "Resolution shows the evidence exists, not that it passed for the rule: the records are not yet tied to test results (conformance-results.json) or published in the SDR.", + "gap": "Resolution shows the evidence exists, not that it passed for the rule: the records published in the SDR are not tied to test results (conformance-results.json). To close: fail the build when a test cited as evidence fails, and publish the result per record.", "closes_with": [ - "W3" + "W10" ] }, { @@ -1132,22 +1132,55 @@ { "frr_id": "SDR-CSO-FRR", "status": "Partially Implemented", - "implementation": "data/frr-records.json holds one record per applicable rule (154, derived from the pinned corpus's applicability metadata), each with status, implementation, evidence, gap and the work that closes it; scripts/_frr.py fails the build on a missing or extra record, an Implemented record without evidence, or evidence that does not resolve.", - "evidence": [], - "gap": "The published SDR does not yet carry these records in fedRampRequirements (next W3 PR), and the independent verification and validation halves stay empty until an assessor is engaged (operator's decision of 2026-11-05). To close: Publish the records in the SDR's fedRampRequirements with rule-specific verification and validation drawn from the evidence each cites; flip each record as its workstream lands.", + "implementation": "data/frr-records.json holds one record per applicable rule (154, derived from the pinned corpus's applicability metadata); scripts/_frr.py fails the build on a missing or extra record, an Implemented record without evidence, or evidence that does not resolve. The published SDR carries every record in fedRampRequirements with its status, implementation, evidence and gap.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_sdr.py::test_every_applicable_rule_is_listed_once" + }, + { + "kind": "test", + "ref": "tests/test_sdr.py::test_an_invalid_record_set_never_reaches_the_sdr" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build Security Decision Record (SDR — 20x SSP replacement)" + }, + { + "kind": "artifact", + "ref": ".well-known/security-decision-record.json" + } + ], + "gap": "The independent verification and validation halves stay empty: no assessor is engaged (operator's decision of 2026-11-05). To close: engage an assessor.", "closes_with": [ - "W3", "sam" ] }, { "frr_id": "SDR-CSO-MTD", - "status": "Partially Implemented", - "implementation": "security-decision-record.json metadata: last_updated (timestamp), source_of_update (build-sdr.py).", - "evidence": [], - "gap": "Version is the constant 'live (regenerated each deploy)', not an identifier; field names do not match the schema (version/lastUpdated/updateSource). To close: Emit a real version (semver bumped on content change, or commit SHA) and the schema's field names.", - "closes_with": [ - "W3" + "status": "Implemented", + "implementation": "The SDR carries metadata.version, metadata.lastUpdated and metadata.updateSource in FedRAMP's schema. The version is semver: unchanged content keeps the previous version and a content change bumps it, judged by a sha256 of the content excluding metadata.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_sdr.py::test_version_starts_at_1_0_0_after_the_unversioned_record" + }, + { + "kind": "test", + "ref": "tests/test_sdr.py::test_unchanged_content_keeps_its_version_and_a_change_bumps_it" + }, + { + "kind": "test", + "ref": "tests/test_sdr.py::test_it_validates_against_fedramps_schema" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build Security Decision Record (SDR — 20x SSP replacement)" + }, + { + "kind": "artifact", + "ref": ".well-known/security-decision-record.json" + } ] }, { @@ -1163,11 +1196,29 @@ { "frr_id": "SDR-CSX-KSI", "status": "Partially Implemented", - "implementation": "security-decision-record.json under /.well-known/ carries a record per KSI with an explanation and artifacts, built from the KSI signal's checks.", - "evidence": [], - "gap": "Verification and validation are the same boilerplate for every KSI (build-sdr.py), not per-KSI statements of the measures, their cycle, and how their automation was verified and validated.", + "implementation": "The SDR carries every KSI with its tests (the OPA rules annotated to it), its evidence, its status rule, and the number of automated methods in place.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_sdr.py::test_every_ksi_is_listed_with_tests_and_evidence" + }, + { + "kind": "test", + "ref": "tests/test_sdr.py::test_a_ksi_is_implemented_only_when_its_measures_are_checked" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build Security Decision Record (SDR — 20x SSP replacement)" + }, + { + "kind": "artifact", + "ref": ".well-known/security-decision-record.json" + } + ], + "gap": "Validation text is generated per method, not written per KSI: 6 distinct statements across 46 KSIs, and the 9 KSIs with no automated method state no measures or cycle. To close: per-KSI statements of the measures, their cycle, and how their automation was verified and validated.", "closes_with": [ - "W3" + "W7", + "W10" ] }, { From 4c492c42faecd9121045c3a0416ba37e88a76e73 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:48:28 -0500 Subject: [PATCH 04/17] feat(assessor): simulated assessor signs a keyless set on every deploy; SDR carries it; cited tests must pass Totally Real Assessment Services, LLC (simulated) runs as a reusable workflow before the deploy job, works from the generated assessor guide, re-runs every cited check, and signs one set under its own workflow identity, which infrastructure/keys/assessor-identity.json pins. The SDR build requires and verifies the set. The unit-test job fails when a test cited as rule evidence did not pass (FRC-CSX-VVR). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 45 ++- .github/workflows/simulated-assessor.yml | 85 +++++ infrastructure/keys/assessor-identity.json | 10 + .../schemas/assessor-record.schema.json | 7 +- scripts/_assessor.py | 108 +++++- scripts/build-assessor-guide.py | 165 ++++++++ scripts/build-sdr.py | 9 +- scripts/check-frr-evidence.py | 119 ++++++ .../assessor/simulated-set-tampered.json | 103 +++++ tests/fixtures/assessor/simulated-set.json | 103 +++++ .../frr-evidence/failing-cited-test.xml | 6 + tests/fixtures/frr-evidence/passing.xml | 8 + tests/test_frr_evidence.py | 60 +++ tests/test_simulated_assessor.py | 296 +++++++++++++++ tools/simulated-assessor/assess.py | 352 ++++++++++++++++++ 15 files changed, 1464 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/simulated-assessor.yml create mode 100644 infrastructure/keys/assessor-identity.json create mode 100644 scripts/build-assessor-guide.py create mode 100644 scripts/check-frr-evidence.py create mode 100644 tests/fixtures/assessor/simulated-set-tampered.json create mode 100644 tests/fixtures/assessor/simulated-set.json create mode 100644 tests/fixtures/frr-evidence/failing-cited-test.xml create mode 100644 tests/fixtures/frr-evidence/passing.xml create mode 100644 tests/test_frr_evidence.py create mode 100644 tests/test_simulated_assessor.py create mode 100644 tools/simulated-assessor/assess.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 24a24847..0d7ab6fc 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -195,7 +195,13 @@ jobs: run: python3 scripts/_frr.py --complete - name: Python unit tests - run: python3 -m pytest tests/ -q + run: python3 -m pytest tests/ -q --junitxml=pytest-results.xml + + # FRC-CSX-VVR: every test a FedRAMP rule record cites as evidence ran and + # passed in the run above (a skipped or missing one fails too). The result + # per record is signed and published by the deploy as frr-evidence.json. + - name: FedRAMP rule evidence passed (cited tests) + run: python3 scripts/check-frr-evidence.py --junit pytest-results.xml --output frr-evidence.json --commit "${{ github.sha }}" # REQ-GOV-2: run the method's conformance tests (data/method-profile.json # maps Appendix B T1-T74 to the tests that implement them) and record the @@ -211,7 +217,9 @@ jobs: uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: conformance-results - path: conformance-results.json + path: | + conformance-results.json + frr-evidence.json if-no-files-found: error # The policy suite is an exhibit: format is enforced, strict compilation @@ -596,7 +604,7 @@ jobs: # appended here by scripts/_gates.py and published with this run's evidence. env: GATE_EVENTS_FILE: /tmp/gate-events.jsonl - needs: [test, compliance-check, security-scan] + needs: [test, compliance-check, security-scan, simulated-assessor] # IMPORTANT: Only deploy if on main branch AND security check passed if: github.ref == 'refs/heads/main' && needs.compliance-check.outputs.compliant == 'true' environment: ${{ github.event.inputs.environment || 'prod' }} @@ -695,6 +703,14 @@ jobs: name: conformance-results path: infrastructure/ + # The simulated assessor's signed set (simulated-assessment.json + .bundle), + # verified against the pinned assessor identity when the SDR is built. + - name: Download the simulated assessment + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: simulated-assessment + path: infrastructure/ + # ------------------------------------------------------------------------- # REBUILD MONITORING FUNCTION # ------------------------------------------------------------------------- @@ -1596,10 +1612,12 @@ jobs: python3 ../scripts/build-sdr.py \ --catalog schemas/ksi-catalog.json --ksi-signal ksi-signal.json \ --runtime-signal ksi-signal-runtime.json \ - --vdr vdr-report.json --profile ../data/system-profile.json --previous-sdr previous-sdr.json + --vdr vdr-report.json --profile ../data/system-profile.json --previous-sdr previous-sdr.json \ + --assessment simulated-assessment.json --assessment-bundle simulated-assessment.bundle # REQ-ASR-1 / T74: re-read the written SDR and fail if any assessor text # differs from the assessor's signed record, or a signed record is missing. - python3 ../scripts/_assessor.py --sdr security-decision-record.json + python3 ../scripts/_assessor.py --sdr security-decision-record.json \ + --assessment simulated-assessment.json --assessment-bundle simulated-assessment.bundle - name: Build Certification Package Overview (CPO) working-directory: infrastructure @@ -2070,6 +2088,23 @@ jobs: if: always() run: rm -f infrastructure/tfstate-bootstrap.json + # =========================================================================== + # SIMULATED ASSESSOR (not a FedRAMP Recognized assessment) + # =========================================================================== + # "Totally Real Assessment Services, LLC (simulated)" verifies and validates + # every rule and KSI from the assessor guide and signs its record under its + # own workflow identity (a reusable workflow, so the certificate names + # simulated-assessor.yml). Runs where the deploy runs; the deploy needs it, and + # the SDR build fails without its signed set. + simulated-assessor: + name: Simulated assessor + needs: [test, compliance-check] + if: github.ref == 'refs/heads/main' && needs.compliance-check.outputs.compliant == 'true' + permissions: + contents: read + id-token: write + uses: ./.github/workflows/simulated-assessor.yml + # =========================================================================== # JOB 3: EXTRA SECURITY SCANS # =========================================================================== diff --git a/.github/workflows/simulated-assessor.yml b/.github/workflows/simulated-assessor.yml new file mode 100644 index 00000000..c32778f4 --- /dev/null +++ b/.github/workflows/simulated-assessor.yml @@ -0,0 +1,85 @@ +# ============================================================================= +# SIMULATED ASSESSOR — "Totally Real Assessment Services, LLC (simulated)" +# ============================================================================= +# SIMULATED. Not independent of the provider, not a FedRAMP Recognized +# independent assessment service, no FedRAMP assessor ID. It stands in for an +# assessor so the assessor port (IVV-CSO-FIA/ICP, IVV-CSX-AIA, CPO-CSO-OSA, +# SDR-CSO-FRR) is exercised end to end on every deploy. +# +# The deploy calls this as a reusable workflow before its deploy job. Because it +# is a reusable workflow, the Sigstore certificate that signs its record names +# THIS file (job_workflow_ref), not deploy-with-opa.yml: the assessor signs +# under its own identity, which infrastructure/keys/assessor-identity.json pins. +# It holds no AWS credentials and reads only public URLs and the repository. +# +# It follows the provider's assessor guide (scripts/build-assessor-guide.py): +# re-runs every test a rule record cites, finds every cited workflow step and +# decision, fetches every cited published artifact and verifies its signature +# and age, and checks every KSI against the live, verified KSI signal. Then it +# writes one signed set: a result per rule, per KSI, and an overall summary. +# Any failure fails this job, and the deploy job needs it. +# ============================================================================= +name: Simulated assessor (not a FedRAMP assessment) + +on: + workflow_call: + +permissions: {} + +env: + # Kept equal to deploy-with-opa.yml's pins by tests/test_simulated_assessor.py. + OPA_VERSION: 1.18.2 + OPA_SHA256: 9903e5125ac281104f2c4b7371d10cc3b74a98933743fcbfc174f9bf0ab20de8 + +jobs: + assess: + name: Totally Real Assessment Services, LLC (simulated) + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + id-token: write # keyless signing under this workflow's own identity + steps: + - name: Checkout the commit under assessment + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Install the assessor's tools + run: | + python3 -m pip install --user pytest jsonschema pyyaml cryptography + curl -fL --retry 5 --retry-delay 5 --connect-timeout 10 --max-time 120 \ + -o opa "https://openpolicyagent.org/downloads/v${OPA_VERSION}/opa_linux_amd64_static" + echo "${OPA_SHA256} opa" | sha256sum -c - + chmod 755 ./opa + sudo mv opa /usr/local/bin + + - name: Install cosign + uses: sigstore/cosign-installer@7e8b541eb2e61bf99390e1afd4be13a184e9ebc5 # v3.10.1 + + # IVV-CSO-STE: the provider supplies the technical explanation (the guide); + # the assessor works from it. + - name: Receive the provider's assessor guide + run: python3 scripts/build-assessor-guide.py --commit "$GITHUB_SHA" --output assessor-guide.json --md-output assessor-guide.md + + - name: Assess every rule and KSI (verification and validation) + run: python3 tools/simulated-assessor/assess.py --guide assessor-guide.json --repo . --commit "$GITHUB_SHA" --output simulated-assessment.json + + - name: Sign the assessment (keyless, the assessor's own identity) + run: cosign sign-blob --yes --new-bundle-format --bundle simulated-assessment.bundle simulated-assessment.json + + - name: Verify the assessment signature against the pinned assessor identity + run: | + id=$(python3 -c 'import json; print(json.load(open("infrastructure/keys/assessor-identity.json"))["certificate_identity"])') + cosign verify-blob --bundle simulated-assessment.bundle \ + --certificate-identity "$id" \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com simulated-assessment.json + + - name: Hand the signed assessment to the provider + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: simulated-assessment + path: | + simulated-assessment.json + simulated-assessment.bundle + if-no-files-found: error diff --git a/infrastructure/keys/assessor-identity.json b/infrastructure/keys/assessor-identity.json new file mode 100644 index 00000000..831d1535 --- /dev/null +++ b/infrastructure/keys/assessor-identity.json @@ -0,0 +1,10 @@ +{ + "assessor": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml", + "algorithm": "SIGSTORE_KEYLESS", + "certificate_identity": "https://github.com/sam-aydlette/samaydlette.com/.github/workflows/simulated-assessor.yml@refs/heads/main", + "certificate_oidc_issuer": "https://token.actions.githubusercontent.com", + "pinned_on": "2026-11-05", + "simulated": true, + "note": "SIMULATED assessor. Its signing identity is the simulated-assessor.yml workflow in this repository (called by the deploy as a reusable workflow, so its Sigstore certificate names that workflow, not the deploy). It is not independent of the provider, not a FedRAMP Recognized independent assessment service, and has no FedRAMP assessor ID. Replacing it with a real assessor means pinning that assessor's own identity here in a reviewed change." +} diff --git a/infrastructure/schemas/assessor-record.schema.json b/infrastructure/schemas/assessor-record.schema.json index bd992c27..4b152eb7 100644 --- a/infrastructure/schemas/assessor-record.schema.json +++ b/infrastructure/schemas/assessor-record.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://samaydlette.com/schemas/assessor-record.schema.json", "title": "Assessor record (REQ-ASR-1)", - "description": "A finding, summary or comment written and signed by an assessor. The signature is ECDSA P-256 with SHA-256 over the canonical form of the record without its \"signature\" member: keys sorted, separators \",\" and \":\" with no whitespace, UTF-8, non-ASCII characters unescaped. The signer must be the assessor identity pinned at infrastructure/keys/assessor-identity.json. The provider never edits a record; outputs carry its text verbatim with the signature.", + "description": "A finding, summary or comment written and signed by an assessor. The signature is ECDSA P-256 with SHA-256 over the canonical form of the record without its \"signature\" member: keys sorted, separators \",\" and \":\" with no whitespace, UTF-8, non-ASCII characters unescaped. The signer must be the assessor identity pinned at infrastructure/keys/assessor-identity.json. The provider never edits a record; outputs carry its text verbatim with the signature. A keyless assessor (pinned identity algorithm SIGSTORE_KEYLESS) instead signs one set file holding all its records with Sigstore, and each record carries algorithm SIGSTORE_KEYLESS_SET.", "type": "object", "additionalProperties": false, "required": ["record_type", "schema_version", "record_id", "assessor", "issued_at", "kind", "text", "signature"], @@ -28,8 +28,9 @@ "additionalProperties": false, "required": ["algorithm", "value"], "properties": { - "algorithm": {"const": "ECDSA_P256_SHA256"}, - "value": {"type": "string", "minLength": 1, "description": "Base64 DER signature."} + "algorithm": {"enum": ["ECDSA_P256_SHA256", "SIGSTORE_KEYLESS_SET"]}, + "value": {"type": "string", "minLength": 1, "description": "Base64 DER signature (ECDSA_P256_SHA256), or the hex sha256 of the record's canonical form (SIGSTORE_KEYLESS_SET)."}, + "signed_set": {"type": "string", "minLength": 1, "description": "SIGSTORE_KEYLESS_SET only: the name of the Sigstore-signed set file holding this record."} } } } diff --git a/scripts/_assessor.py b/scripts/_assessor.py index 52cc5092..07967498 100644 --- a/scripts/_assessor.py +++ b/scripts/_assessor.py @@ -17,11 +17,23 @@ With no records there is nothing to verify and no identity is needed; the SDR states "no assessor record". + +Keyless set (load_assessment): an assessor that signs with Sigstore instead of a +key it holds signs one set file holding all its records. The pinned identity +then names the signing workflow's certificate identity and OIDC issuer +(algorithm SIGSTORE_KEYLESS). The set is accepted only when cosign verifies its +bundle against exactly that identity, and each record in it is accepted only +when it names the pinned assessor and its signature value is the sha256 of its +canonical form (algorithm SIGSTORE_KEYLESS_SET), so a record is bound to the +signed set and cannot be altered alone. The set and its bundle are published, +so anyone can repeat the check. This is how the simulated assessor +(tools/simulated-assessor/, .github/workflows/simulated-assessor.yml) signs. """ import base64 import copy import hashlib import json +import subprocess # nosec B404: runs cosign with a fixed argument list import sys from pathlib import Path @@ -30,6 +42,9 @@ IDENTITY_PATH = REPO / "infrastructure" / "keys" / "assessor-identity.json" ALGORITHM = "ECDSA_P256_SHA256" +KEYLESS = "SIGSTORE_KEYLESS" # the pinned identity of a keyless assessor +SET_ALGORITHM = "SIGSTORE_KEYLESS_SET" # a record bound to a keyless-signed set +SET_TYPE = "simulated-independent-assessment" KINDS = ("finding", "summary", "comment") REQUIRED = ("record_type", "schema_version", "record_id", "assessor", "issued_at", "kind", "text", "signature") # What an output carries for each record: the signed fields, verbatim, plus the signature. @@ -60,8 +75,8 @@ def _shape(rec, name): a, s = rec["assessor"], rec["signature"] if not isinstance(a, dict) or not a.get("organization") or not a.get("key_id"): _fail(f"{name} does not name its assessor (organization and key_id)") - if not isinstance(s, dict) or s.get("algorithm") != ALGORITHM or not s.get("value"): - _fail(f"{name} carries no {ALGORITHM} signature") + if not isinstance(s, dict) or s.get("algorithm") not in (ALGORITHM, SET_ALGORITHM) or not s.get("value"): + _fail(f"{name} carries no {ALGORITHM} or {SET_ALGORITHM} signature") for k in ("record_id", "issued_at", "text"): if not isinstance(rec[k], str) or not rec[k].strip(): _fail(f"{name} has an empty {k}") @@ -75,6 +90,9 @@ def _load_identity(path): _fail(f"records are present but no assessor identity is pinned at {p}") try: ident = json.loads(p.read_text()) + if ident.get("algorithm") == KEYLESS: + _fail(f"the pinned identity {p} is keyless: its records arrive only as a signed set " + "(load_assessment), never as loose files") pem = ident["public_key_pem"].encode("ascii") except (json.JSONDecodeError, KeyError, AttributeError, UnicodeEncodeError) as exc: _fail(f"pinned identity {p} is unreadable ({type(exc).__name__})") @@ -86,6 +104,8 @@ def _load_identity(path): def _verify(rec, name, ident, pem): + if rec["signature"]["algorithm"] != ALGORITHM: + _fail(f"{name} is not signed with {ALGORITHM}") try: from cryptography.exceptions import InvalidSignature from cryptography.hazmat.primitives import hashes, serialization @@ -127,6 +147,83 @@ def load_records(records_dir=RECORDS_DIR, identity_path=IDENTITY_PATH): return records +# --- keyless set ------------------------------------------------------------------------ + +def load_keyless_identity(path=IDENTITY_PATH): + p = Path(path) + try: + ident = json.loads(p.read_text()) + except (OSError, json.JSONDecodeError) as exc: + _fail(f"no readable keyless assessor identity at {p} ({type(exc).__name__})") + if not isinstance(ident, dict) or ident.get("algorithm") != KEYLESS: + _fail(f"the identity pinned at {p} is not a {KEYLESS} identity") + for k in ("assessor", "key_id", "certificate_identity", "certificate_oidc_issuer"): + if not isinstance(ident.get(k), str) or not ident[k]: + _fail(f"the identity pinned at {p} does not name its {k}") + return ident + + +def cosign_verify(set_path, bundle_path, ident): + """True when cosign verifies the bundle over the set file against exactly the + pinned certificate identity and issuer (no regular expression).""" + r = subprocess.run(["cosign", "verify-blob", "--bundle", str(bundle_path), + "--certificate-identity", ident["certificate_identity"], + "--certificate-oidc-issuer", ident["certificate_oidc_issuer"], str(set_path)], + capture_output=True, text=True, check=False) # nosec B603: fixed argv + return r.returncode == 0 + + +def load_assessment(set_path, bundle_path, identity_path=IDENTITY_PATH, verifier=cosign_verify): + """Every record in a keyless-signed assessment set, verified. Fails closed when + the set or its bundle is missing: the deploy depends on the assessment.""" + sp, bp = Path(set_path), Path(bundle_path) + for f, what in ((sp, "assessment set"), (bp, "assessment bundle")): + if not f.is_file() or f.stat().st_size == 0: + _fail(f"the {what} {f} is missing: the deploy depends on the assessor's signed record") + ident = load_keyless_identity(identity_path) + if not verifier(sp, bp, ident): + _fail(f"{sp.name} signature does not verify against the pinned assessor identity") + try: + doc = json.loads(sp.read_text()) + except json.JSONDecodeError: + _fail(f"{sp.name} is not valid JSON") + if not isinstance(doc, dict) or doc.get("assessment_type") != SET_TYPE or doc.get("schema_version") != "1": + _fail(f"{sp.name} is not a {SET_TYPE} set, schema version 1") + a = doc.get("assessor") or {} + if a.get("organization") != ident["assessor"] or a.get("key_id") != ident["key_id"]: + _fail(f"{sp.name} names {a.get('organization')!r}, not the pinned assessor identity") + recs = doc.get("records") + if not isinstance(recs, list) or not recs: + _fail(f"{sp.name} holds no records") + seen, out = set(), [] + for i, rec in enumerate(recs): + name = f"{sp.name} record {i}" + _shape(rec, name) + ra, sig = rec["assessor"], rec["signature"] + if ra["organization"] != ident["assessor"] or ra["key_id"] != ident["key_id"]: + _fail(f"{name} names {ra['organization']!r} / {ra['key_id']!r}, not the pinned assessor identity") + if sig["algorithm"] != SET_ALGORITHM or sig.get("signed_set") != sp.name: + _fail(f"{name} is not bound to the signed set {sp.name}") + if sig["value"] != hashlib.sha256(canonical(rec)).hexdigest(): + _fail(f"{name} ({rec['record_id']}) differs from the record the assessor signed") + if rec["record_id"] in seen: + _fail(f"record_id {rec['record_id']} appears twice") + seen.add(rec["record_id"]) + out.append(rec) + if not any(r["kind"] == "summary" and "rule_id" not in r for r in out): + _fail(f"{sp.name} has no overall summary (IVV-IAS-OSA)") + return out + + +def overall_summary(records): + """The assessor's overall summary record (IVV-IAS-OSA), carried verbatim, or + None. The CPO quotes it (CPO-CSO-OSA).""" + sums = [r for r in records if r["kind"] == "summary" and "rule_id" not in r] + if len(sums) > 1: + _fail("more than one overall summary record") + return _carried(sums[0]) if sums else None + + def _carried(rec): return {k: copy.deepcopy(rec[k]) for k in CARRIED} @@ -183,8 +280,13 @@ def main(argv=None): ap.add_argument("--records", default=str(RECORDS_DIR)) ap.add_argument("--identity", default=str(IDENTITY_PATH)) ap.add_argument("--sdr", default=None, help="a built security-decision-record.json to check") + ap.add_argument("--assessment", default=None, help="a keyless-signed assessment set") + ap.add_argument("--assessment-bundle", default=None) a = ap.parse_args(argv) - records = load_records(a.records, a.identity) + if a.assessment: + records = load_assessment(a.assessment, a.assessment_bundle or a.assessment[:-5] + ".bundle", a.identity) + else: + records = load_records(a.records, a.identity) if a.sdr: verify_output(json.loads(Path(a.sdr).read_text()), records) print(f"assessor records: {len(records)} verified" + ("; SDR carries them verbatim" if a.sdr else "")) diff --git a/scripts/build-assessor-guide.py b/scripts/build-assessor-guide.py new file mode 100644 index 00000000..b7cf5eba --- /dev/null +++ b/scripts/build-assessor-guide.py @@ -0,0 +1,165 @@ +#!/usr/bin/env python3 +"""The assessor guide: how to verify and validate each FedRAMP rule and KSI +here, by hand or by machine (IVV-CSO-STE, IVV-CSO-DUS). + +Generated from the rule records (data/frr-records.json) and the KSI catalog, so +it cannot describe a mechanism the records do not cite. For every rule it gives +the provider's explanation and, for every piece of evidence, the command that +reproduces the check and a machine-readable form of the same check. The +simulated assessor (tools/simulated-assessor/assess.py) executes exactly those +machine-readable checks on every deploy: the guide is the demonstration. + +It also states the sampling position (IVV-CSO-DUS): no check here uses a +representative sample. + + python3 scripts/build-assessor-guide.py --output assessor-guide.json --md-output assessor-guide.md +""" + +import argparse +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _freshness # noqa: E402 +import _frr # noqa: E402 +import _rules # noqa: E402 + +REPO = Path(__file__).resolve().parent.parent +SITE = "https://samaydlette.com" +REPO_URL = "https://github.com/sam-aydlette/samaydlette.com" +ISSUER = "https://token.actions.githubusercontent.com" +WF = f"{REPO_URL}/.github/workflows" +IDENTITIES = { + "deploy": f"{WF}/deploy-with-opa.yml@refs/heads/main", + "nightly": f"{WF}/evidence-nightly.yml@refs/heads/main", + # The simulated assessor signs its own record under its own workflow identity. + "assessor": f"{WF}/simulated-assessor.yml@refs/heads/main", +} +SCHEMA = "assessor-guide/1" +SAMPLING = ("No representative samples are used in verification or validation (IVV-CSO-DUS). Every check runs " + "over its full population: the OPA gate and the KSI signal evaluate every inventoried component; the " + "reconciliation gate compares every live in-boundary resource with the inventory; the vulnerability " + "scan covers every SBOM; every FedRAMP rule record is validated and every test it cites runs on every " + "build; and the simulated assessor re-checks every rule and every KSI rather than a selection.") +HOW_TO_USE = ("Read each rule's explanation, then run the command beside each piece of evidence. Tests run from a " + "clone of the repository after `make dev-setup`; published artifacts are fetched from the site and " + "their signatures verified with cosign against the publishing workflow's identity; workflow steps " + "are read in the workflow file and their run logs in the repository's Actions tab; decision records " + "are in data/decisions.json. The `check` beside each command is the same check in machine-readable " + "form. For a walkthrough of any mechanism, ask through the security contact in the Certification " + "Package Overview.") + + +def _artifact_check(ref, fresh): + entry = fresh[ref] + name = ref.split("/", 1)[1] + sig = entry.get("signature") + return {"url": f"{SITE}/{ref}", "bundle_url": f"{SITE}/{sig}" if sig else None, + "identities": (["assessor"] if name.startswith("simulated-assessment") + else ["deploy", "nightly"] if name.startswith("vdr-") else ["deploy"]), + "timestamp": entry["timestamp"], "max_age_hours": entry["max_age_hours"]} + + +def reproduce(ev, fresh): + kind, ref = ev["kind"], ev["ref"] + if kind == "test": + return f"python3 -m pytest '{ref}'", {"pytest": ref} + if kind == "step": + wf, step = ref.split("#", 1) + return (f"Read the step named {step!r} in .github/workflows/{wf}, and its log in the latest run of that " + "workflow on main", {"workflow": wf, "step": step}) + if kind == "artifact": + chk = _artifact_check(ref, fresh) + cmd = f"curl -fsSLO {chk['url']}" + if chk["bundle_url"]: + cmd += (f" && curl -fsSLO {chk['bundle_url']} && cosign verify-blob --bundle {chk['bundle_url'].rsplit('/', 1)[1]} " + f"--certificate-identity {IDENTITIES[chk['identities'][0]]} --certificate-oidc-issuer {ISSUER} " + f"{ref.rsplit('/', 1)[1]}") + return cmd, {"artifact": chk} + if kind == "decision": + return f"jq '.decisions[] | select(.id == \"{ref}\")' data/decisions.json", {"decision": ref} + raise SystemExit(f"::error::assessor guide: unknown evidence kind {kind!r}") + + +def build(records, applicable, catalog, fresh, now, commit=None): + rules = [] + for r in records["records"]: + rid = r["frr_id"] + evidence = [] + for ev in r.get("evidence", []): + cmd, chk = reproduce(ev, fresh) + evidence.append({"kind": ev["kind"], "ref": ev["ref"], "how_to_reproduce": cmd, "check": chk}) + entry = {"rule_id": rid, "name": applicable[rid]["name"], "force": applicable[rid]["force"], + "statement": applicable[rid]["statement"], "status": r["status"], + "explanation": r["implementation"], "evidence": evidence} + for k in ("not_applicable", "may_rationale", "simulated"): + if k in r: + entry[k] = r[k] + rules.append(entry) + ksis = [{"ksi_id": i["id"], "name": i.get("name", ""), + "how_to_reproduce": (f"curl -fsSL {SITE}/.well-known/ksi-signal.json | jq '.ksis[] | " + f"select(.id == \"{i['id']}\")' after verifying ksi-signal.bundle against the " + "deploy identity; the SDR's keySecurityIndicators entry gives its measures"), + "check": {"ksi_in_signal": i["id"]}} + for f in catalog["KSI"].values() for i in f["indicators"]] + return {"schema": SCHEMA, "generated_at": now.isoformat(), "commit": commit, "site": SITE, + "repository": REPO_URL, "how_to_use": HOW_TO_USE, "sampling": SAMPLING, + "identities": {**IDENTITIES, "oidc_issuer": ISSUER}, + "summary": {"rules": len(rules), "ksis": len(ksis), + "evidence_items": sum(len(r["evidence"]) for r in rules)}, + "rules": rules, "ksis": sorted(ksis, key=lambda k: k["ksi_id"])} + + +def render_markdown(g): + out = ["# Assessor guide", "", + "_How to verify and validate each FedRAMP rule and Key Security Indicator for this offering. Generated " + "from the rule records on every deploy; the simulated assessor runs these exact checks._", "", + f"- **Generated:** {g['generated_at']} | **Commit:** `{g['commit'] or 'local build'}`", + f"- **Rules:** {g['summary']['rules']} | **KSIs:** {g['summary']['ksis']} | " + f"**Evidence items:** {g['summary']['evidence_items']}", "", + "## How to use this guide", "", g["how_to_use"], "", + "## Sampling (IVV-CSO-DUS)", "", g["sampling"], "", + "## Signing identities", ""] + out += [f"- {k}: `{v}`" for k, v in g["identities"].items()] + out += ["", "## FedRAMP rules", ""] + for r in g["rules"]: + out += [f"### {r['rule_id']}: {r['name']} ({r['force']}, {r['status']})", "", r["explanation"], ""] + for k, label in (("not_applicable", "Not applicable"), ("may_rationale", "Use of this permission")): + if k in r: + out += [f"{label}: {r[k]}", ""] + if "simulated" in r: + out += [f"Simulated counterparty ({r['simulated']['counterparty']}): {r['simulated']['how']}", ""] + for ev in r["evidence"]: + out.append(f"- {ev['kind']} `{ev['ref']}`: `{ev['how_to_reproduce']}`") + if r["evidence"]: + out.append("") + out += ["## Key Security Indicators", ""] + out += [f"- `{k['ksi_id']}` {k['name']}: `{k['how_to_reproduce']}`" for k in g["ksis"]] + out += ["", "---", "_Source of truth: the signed `assessor-guide.json`._"] + return "\n".join(out) + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--records", default=str(_frr.DEFAULT_PATH)) + ap.add_argument("--catalog", default=str(REPO / "infrastructure" / "schemas" / "ksi-catalog.json")) + ap.add_argument("--freshness", default=str(REPO / "infrastructure" / "schemas" / "freshness-config.json")) + ap.add_argument("--commit", default=None) + ap.add_argument("--output", default="assessor-guide.json") + ap.add_argument("--md-output", default="assessor-guide.md") + a = ap.parse_args(argv) + records = _frr.load(a.records) + fresh = {x["path"]: x for x in _freshness.load_freshness_config(a.freshness)["artifacts"]} + guide = build(records, _rules.applicable_provider_rules(), json.loads(Path(a.catalog).read_text()), fresh, + datetime.now(timezone.utc), a.commit) + Path(a.output).write_text(json.dumps(guide, indent=2) + "\n") + if a.md_output: + Path(a.md_output).write_text(render_markdown(guide) + "\n") + print(f"assessor-guide: {guide['summary']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-sdr.py b/scripts/build-sdr.py index d209947a..d0e1f11d 100644 --- a/scripts/build-sdr.py +++ b/scripts/build-sdr.py @@ -454,6 +454,10 @@ def main(argv=None): ap.add_argument("--md-output", default="security-decision-record.md") ap.add_argument("--assessor-records", default=str(_assessor.RECORDS_DIR)) ap.add_argument("--assessor-identity", default=str(_assessor.IDENTITY_PATH)) + # A keyless-signed assessment set (the simulated assessor's, on every deploy): + # given, it is required to exist and verify; its records replace the loose ones. + ap.add_argument("--assessment", default=None) + ap.add_argument("--assessment-bundle", default=None) a = ap.parse_args(argv) now = datetime.now(timezone.utc) @@ -473,7 +477,10 @@ def main(argv=None): applicable = _rules.applicable_provider_rules() irs = _controls.load(a.ksi_signal, a.catalog) runtime, reason = runtime_validations(a.runtime_signal) - assessor_records = _assessor.load_records(a.assessor_records, a.assessor_identity) + if a.assessment: + assessor_records = _assessor.load_assessment(a.assessment, a.assessment_bundle, a.assessor_identity) + else: + assessor_records = _assessor.load_records(a.assessor_records, a.assessor_identity) doc = build(catalog, signal, records, applicable, irs, moderate_ids(), policy_rules(), runtime, reason, assessor_records, prof, prev, vdr, now, policy_documents()) _assessor.verify_output(doc, assessor_records) # T74 diff --git a/scripts/check-frr-evidence.py b/scripts/check-frr-evidence.py new file mode 100644 index 00000000..9f6ae293 --- /dev/null +++ b/scripts/check-frr-evidence.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python3 +"""Every test a FedRAMP rule record cites ran and passed (FRC-CSX-VVR). + +scripts/_frr.py shows that each piece of evidence a rule record cites exists. +This shows the cited tests passed in this build: it reads the JUnit XML that the +unit-test job's pytest run wrote and fails when a test cited as evidence failed, +errored, was skipped, or did not run at all. A parametrized test passes only +when every one of its cases ran and passed. + +It writes the result per record (frr-evidence.json), which the deploy signs and +publishes beside the Security Decision Record, so a reader can see that each +Implemented record's tests passed in the build that published it. + + python3 scripts/check-frr-evidence.py --junit pytest-results.xml --output frr-evidence.json +""" + +import argparse +import json +import sys +import xml.etree.ElementTree as ET # nosec B405: parses the JUnit file this job's own pytest wrote +from datetime import datetime, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _frr # noqa: E402 + +SCHEMA = "frr-evidence/1" + + +def _fail(msg): + raise SystemExit(f"::error::FRR evidence: {msg} (fail-closed)") + + +def junit_outcomes(path): + """{(module path, class or None, function): [outcome per case]} from a JUnit XML file.""" + try: + root = ET.parse(path).getroot() # nosec B314: trusted, locally generated file + except (OSError, ET.ParseError) as exc: + _fail(f"cannot read the test results {path}: {exc}") + out = {} + for case in root.iter("testcase"): + classname, name = case.get("classname", ""), case.get("name", "") + parts = classname.split(".") + # classname is "tests.test_x" or "tests.test_x.TestClass" + if len(parts) >= 2 and parts[-1][:1].isupper(): + module, cls = "/".join(parts[:-1]) + ".py", parts[-1] + else: + module, cls = "/".join(parts) + ".py", None + func = name.split("[", 1)[0] + if case.find("failure") is not None or case.find("error") is not None: + outcome = "failed" + elif case.find("skipped") is not None: + outcome = "skipped" + else: + outcome = "passed" + out.setdefault((module, cls, func), []).append(outcome) + if not out: + _fail(f"{path} records no test cases") + return out + + +def _key(ref): + m = _frr.TEST_RE.match(ref) + if not m: + _fail(f"{ref!r} is not a test reference") + rel, first, second = m.groups() + return (rel, first, second) if second else (rel, None, first) + + +def test_result(ref, outcomes): + cases = outcomes.get(_key(ref)) + if not cases: + return "not run" + if all(c == "passed" for c in cases): + return "passed" + return "failed" if "failed" in cases else "skipped" + + +def evaluate(records, outcomes): + """(per-record results, list of failures).""" + per, failures = {}, [] + for r in records["records"]: + tests = {e["ref"]: test_result(e["ref"], outcomes) for e in r.get("evidence", []) if e["kind"] == "test"} + for ref, res in tests.items(): + if res != "passed": + failures.append(f"{r['frr_id']}: cited test {ref} {res}") + per[r["frr_id"]] = {"status": r["status"], "tests": tests, + "result": "pass" if all(v == "passed" for v in tests.values()) else "fail"} + return per, failures + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--junit", required=True) + ap.add_argument("--records", default=str(_frr.DEFAULT_PATH)) + ap.add_argument("--output", default="frr-evidence.json") + ap.add_argument("--commit", default=None) + a = ap.parse_args(argv) + records = _frr.load(a.records) + per, failures = evaluate(records, junit_outcomes(a.junit)) + cited = sum(len(v["tests"]) for v in per.values()) + doc = {"schema": SCHEMA, "generated_at": datetime.now(timezone.utc).isoformat(), "commit": a.commit, + "explanation": "Each FedRAMP rule record's cited tests and whether they passed in the unit-test run " + "of the build that published this file (scripts/check-frr-evidence.py). The build " + "fails when any cited test fails, errors, is skipped or does not run.", + "summary": {"records": len(per), "cited_tests": cited, + "records_with_tests": sum(1 for v in per.values() if v["tests"])}, + "records": per} + if failures: + for f in failures: + print(f"::error::{f}") + _fail(f"{len(failures)} cited test(s) did not pass") + Path(a.output).write_text(json.dumps(doc, indent=2) + "\n") + print(f"frr-evidence: {cited} cited tests across {doc['summary']['records_with_tests']} records, all passed") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/assessor/simulated-set-tampered.json b/tests/fixtures/assessor/simulated-set-tampered.json new file mode 100644 index 00000000..f9483465 --- /dev/null +++ b/tests/fixtures/assessor/simulated-set-tampered.json @@ -0,0 +1,103 @@ +{ + "assessment_type": "simulated-independent-assessment", + "schema_version": "1", + "simulated": true, + "fedramp_recognized": false, + "assessor_id": "NOT-A-REAL-ASSESSOR-ID", + "disclaimer": "SIMULATED. Totally Real Assessment Services, LLC is a GitHub Actions workflow in the provider's own repository, wearing a lanyard. It is not independent, it is not a FedRAMP Recognized independent assessment service, its assessor ID is NOT-A-REAL-ASSESSOR-ID, and nothing here is a FedRAMP independent assessment. It exists to show the assessor port working end to end. Our rates are very competitive: free.", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "subject": { + "site": "https://samaydlette.com", + "commit": "0000000000000000000000000000000000000000", + "assessor_guide_sha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" + }, + "results": { + "rules": { + "pass": 1, + "observation": 1, + "fail": 0 + }, + "ksis": { + "pass": 1, + "observation": 0, + "fail": 0 + } + }, + "records": [ + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-SDR-CSO-FRR", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of rule SDR-CSO-FRR, not a FedRAMP Recognized assessment. Result: Pass with flying colours. Independent verification: test tests/test_sdr.py::test_every_applicable_rule_is_listed_once passed (re-run by the assessor). Independent validation: security-decision-record.json served; signature verified (deploy identity); 3h old (window 720h).", + "rule_id": "SDR-CSO-FRR", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "632106e406c8aed713dee1a91fc1b2c0053eeb8b280866b7fe72e3f6ba741358", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-CDS-CSO-RPS", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of rule CDS-CSO-RPS, not a FedRAMP Recognized assessment. Result: Pass with observation. Independent verification: Not Applicable (MAY): example. Independent validation: policy-index.json is not yet published; it is first published by the deploy under assessment, and validated at the next assessment.", + "rule_id": "CDS-CSO-RPS", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "7c82618e3c8f080db94cf5a0f9e77efa81b7276bf634add6294c121a72107dbd", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-KSI-CED-RAT", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of KSI KSI-CED-RAT, not a FedRAMP Recognized assessment. Result: Pass. Independent verification: in the published signal sig-1 with status pass by method documentation. Independent validation: KSI signal served and its signature verified (deploy identity).", + "rule_id": "KSI-CED-RAT", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "5f529cd3c3f006eac63f176f1e8baac1ce8cc23cae3dbd413ede1b76eb606fdd", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-SUMMARY", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "summary", + "text": "Overall summary (IVV-IAS-OSA), SIMULATED. Totally Real Assessment Services, LLC (simulated) verified and validated all 2 applicable FedRAMP rules and all 1 Key Security Indicators for commit 0000000000000000000000000000000000000000: rules 1 pass, 1 pass with observation, 0 fail; KSIs 1 pass, 0 pass with observation, 0 fail. Failures: none. Areas of dispute: none. Observations: CDS-CSO-RPS: policy-index.json is not yet published; it is first published by the deploy under assessment, and validated at the next assessment. SIMULATED. Totally Real Assessment Services, LLC is a GitHub Actions workflow in the provider's own repository, wearing a lanyard. It is not independent, it is not a FedRAMP Recognized independent assessment service, its assessor ID is NOT-A-REAL-ASSESSOR-ID, and nothing here is a FedRAMP independent assessment. It exists to show the assessor port working end to end. Our rates are very competitive: free.", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "807d840be4064f51bc9ab05e8d6814b0611981b42d1fb37b5ba86d78b927b136", + "signed_set": "simulated-assessment.json" + } + } + ] +} diff --git a/tests/fixtures/assessor/simulated-set.json b/tests/fixtures/assessor/simulated-set.json new file mode 100644 index 00000000..eb8372b1 --- /dev/null +++ b/tests/fixtures/assessor/simulated-set.json @@ -0,0 +1,103 @@ +{ + "assessment_type": "simulated-independent-assessment", + "schema_version": "1", + "simulated": true, + "fedramp_recognized": false, + "assessor_id": "NOT-A-REAL-ASSESSOR-ID", + "disclaimer": "SIMULATED. Totally Real Assessment Services, LLC is a GitHub Actions workflow in the provider's own repository, wearing a lanyard. It is not independent, it is not a FedRAMP Recognized independent assessment service, its assessor ID is NOT-A-REAL-ASSESSOR-ID, and nothing here is a FedRAMP independent assessment. It exists to show the assessor port working end to end. Our rates are very competitive: free.", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "subject": { + "site": "https://samaydlette.com", + "commit": "0000000000000000000000000000000000000000", + "assessor_guide_sha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" + }, + "results": { + "rules": { + "pass": 1, + "observation": 1, + "fail": 0 + }, + "ksis": { + "pass": 1, + "observation": 0, + "fail": 0 + } + }, + "records": [ + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-SDR-CSO-FRR", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of rule SDR-CSO-FRR, not a FedRAMP Recognized assessment. Result: Pass. Independent verification: test tests/test_sdr.py::test_every_applicable_rule_is_listed_once passed (re-run by the assessor). Independent validation: security-decision-record.json served; signature verified (deploy identity); 3h old (window 720h).", + "rule_id": "SDR-CSO-FRR", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "632106e406c8aed713dee1a91fc1b2c0053eeb8b280866b7fe72e3f6ba741358", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-CDS-CSO-RPS", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of rule CDS-CSO-RPS, not a FedRAMP Recognized assessment. Result: Pass with observation. Independent verification: Not Applicable (MAY): example. Independent validation: policy-index.json is not yet published; it is first published by the deploy under assessment, and validated at the next assessment.", + "rule_id": "CDS-CSO-RPS", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "7c82618e3c8f080db94cf5a0f9e77efa81b7276bf634add6294c121a72107dbd", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-KSI-CED-RAT", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "finding", + "text": "SIMULATED assessment of KSI KSI-CED-RAT, not a FedRAMP Recognized assessment. Result: Pass. Independent verification: in the published signal sig-1 with status pass by method documentation. Independent validation: KSI signal served and its signature verified (deploy identity).", + "rule_id": "KSI-CED-RAT", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "5f529cd3c3f006eac63f176f1e8baac1ce8cc23cae3dbd413ede1b76eb606fdd", + "signed_set": "simulated-assessment.json" + } + }, + { + "record_type": "assessor-record", + "schema_version": "1", + "record_id": "TRAS-20261105T120000Z-SUMMARY", + "assessor": { + "organization": "Totally Real Assessment Services, LLC (simulated)", + "key_id": "sigstore-keyless:simulated-assessor.yml" + }, + "issued_at": "2026-11-05T12:00:00+00:00", + "kind": "summary", + "text": "Overall summary (IVV-IAS-OSA), SIMULATED. Totally Real Assessment Services, LLC (simulated) verified and validated all 2 applicable FedRAMP rules and all 1 Key Security Indicators for commit 0000000000000000000000000000000000000000: rules 1 pass, 1 pass with observation, 0 fail; KSIs 1 pass, 0 pass with observation, 0 fail. Failures: none. Areas of dispute: none. Observations: CDS-CSO-RPS: policy-index.json is not yet published; it is first published by the deploy under assessment, and validated at the next assessment. SIMULATED. Totally Real Assessment Services, LLC is a GitHub Actions workflow in the provider's own repository, wearing a lanyard. It is not independent, it is not a FedRAMP Recognized independent assessment service, its assessor ID is NOT-A-REAL-ASSESSOR-ID, and nothing here is a FedRAMP independent assessment. It exists to show the assessor port working end to end. Our rates are very competitive: free.", + "signature": { + "algorithm": "SIGSTORE_KEYLESS_SET", + "value": "807d840be4064f51bc9ab05e8d6814b0611981b42d1fb37b5ba86d78b927b136", + "signed_set": "simulated-assessment.json" + } + } + ] +} diff --git a/tests/fixtures/frr-evidence/failing-cited-test.xml b/tests/fixtures/frr-evidence/failing-cited-test.xml new file mode 100644 index 00000000..16a82665 --- /dev/null +++ b/tests/fixtures/frr-evidence/failing-cited-test.xml @@ -0,0 +1,6 @@ + + + +known-bad: a cited test failed + + diff --git a/tests/fixtures/frr-evidence/passing.xml b/tests/fixtures/frr-evidence/passing.xml new file mode 100644 index 00000000..9bf0cf71 --- /dev/null +++ b/tests/fixtures/frr-evidence/passing.xml @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/tests/test_frr_evidence.py b/tests/test_frr_evidence.py new file mode 100644 index 00000000..0ad03834 --- /dev/null +++ b/tests/test_frr_evidence.py @@ -0,0 +1,60 @@ +"""FRC-CSX-VVR: the build fails when a test a rule record cites did not pass, +and the result is published per record.""" +import importlib.util +import re +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "frr-evidence" +spec = importlib.util.spec_from_file_location("frr_evidence", REPO / "scripts" / "check-frr-evidence.py") +mod = importlib.util.module_from_spec(spec) +spec.loader.exec_module(mod) + +SDR_A = "tests/test_sdr.py::test_every_applicable_rule_is_listed_once" +SDR_B = "tests/test_sdr.py::test_an_invalid_record_set_never_reaches_the_sdr" + + +def _records(*refs): + return {"records": [{"frr_id": "SDR-CSO-FRR", "status": "Implemented", + "evidence": [{"kind": "test", "ref": r} for r in refs]}]} + + +def test_all_cited_tests_passing_is_a_pass(): + per, failures = mod.evaluate(_records(SDR_A, SDR_B, "tests/test_other.py::TestThing::test_method"), + mod.junit_outcomes(FIX / "passing.xml")) + assert failures == [] + assert per["SDR-CSO-FRR"]["result"] == "pass" + assert set(per["SDR-CSO-FRR"]["tests"].values()) == {"passed"} + + +def test_known_bad_a_failing_cited_test_fails_the_build(): + per, failures = mod.evaluate(_records(SDR_A, SDR_B), mod.junit_outcomes(FIX / "failing-cited-test.xml")) + assert failures == [f"SDR-CSO-FRR: cited test {SDR_B} failed"] + assert per["SDR-CSO-FRR"]["result"] == "fail" + + +@pytest.mark.parametrize("ref,expected", [ + ("tests/test_other.py::test_skipped", "skipped"), + ("tests/test_other.py::test_never_ran", "not run"), +]) +def test_a_skipped_or_missing_cited_test_is_not_a_pass(ref, expected): + _, failures = mod.evaluate(_records(ref), mod.junit_outcomes(FIX / "passing.xml")) + assert failures == [f"SDR-CSO-FRR: cited test {ref} {expected}"] + + +def test_main_refuses_to_write_results_when_a_cited_test_failed(tmp_path, monkeypatch): + monkeypatch.setattr(mod._frr, "load", lambda _p: _records(SDR_B)) + out = tmp_path / "frr-evidence.json" + with pytest.raises(SystemExit): + mod.main(["--junit", str(FIX / "failing-cited-test.xml"), "--output", str(out)]) + assert not out.exists() + + +def test_the_unit_test_job_runs_the_check_on_its_own_results(): + wf = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() + test_job = wf.split("\n test:\n", 1)[1].split("\n compliance-check:\n", 1)[0] + assert re.search(r"pytest tests/ -q --junitxml=pytest-results\.xml", test_job) + assert "scripts/check-frr-evidence.py --junit pytest-results.xml" in test_job + assert test_job.index("--junitxml=pytest-results.xml") < test_job.index("check-frr-evidence.py") diff --git a/tests/test_simulated_assessor.py b/tests/test_simulated_assessor.py new file mode 100644 index 00000000..5d7738cd --- /dev/null +++ b/tests/test_simulated_assessor.py @@ -0,0 +1,296 @@ +"""The simulated assessor ("Totally Real Assessment Services, LLC (simulated)") +and the keyless assessor port (IVV-CSO-FIA, IVV-CSO-ICP, IVV-CSX-AIA, +CPO-CSO-OSA, SDR-CSO-FRR). + +The assessor re-runs every cited check from the provider's assessor guide and +writes one signed set; the provider accepts the set only when its Sigstore +bundle verifies against the pinned assessor identity and every record is bound +to it, and the SDR carries every record verbatim. It is plainly labelled as a +simulation and claims no FedRAMP recognition. +""" +import copy +import importlib.util +import json +import re +import sys +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "assessor" +WF = REPO / ".github" / "workflows" +IDENTITY = REPO / "infrastructure" / "keys" / "assessor-identity.json" +sys.path.insert(0, str(REPO / "scripts")) +import _assessor # noqa: E402 + +spec = importlib.util.spec_from_file_location("assess", REPO / "tools" / "simulated-assessor" / "assess.py") +assess = importlib.util.module_from_spec(spec) +spec.loader.exec_module(assess) + +NOW = datetime(2026, 11, 5, 12, 0, tzinfo=timezone.utc) +SITE = "https://samaydlette.com" + + +def ok(*_a): + return True + + +def _set(tmp_path, fixture="simulated-set.json"): + s = tmp_path / "simulated-assessment.json" + s.write_text((FIX / fixture).read_text()) + b = tmp_path / "simulated-assessment.bundle" + b.write_text("{}") + return s, b + + +# --- the provider accepts only the pinned assessor's signed set ------------------------ + +def test_genuine_set_loads_and_carries_an_overall_summary(tmp_path): + recs = _assessor.load_assessment(*_set(tmp_path), IDENTITY, verifier=ok) + assert len(recs) == 4 + summary = _assessor.overall_summary(recs) + assert summary["kind"] == "summary" and "IVV-IAS-OSA" in summary["text"] + + +def test_known_bad_tampered_record_fails(tmp_path): + with pytest.raises(SystemExit, match="differs from the record the assessor signed"): + _assessor.load_assessment(*_set(tmp_path, "simulated-set-tampered.json"), IDENTITY, verifier=ok) + + +def test_set_whose_signature_does_not_verify_fails(tmp_path): + with pytest.raises(SystemExit, match="does not verify"): + _assessor.load_assessment(*_set(tmp_path), IDENTITY, verifier=lambda *_a: False) + + +@pytest.mark.parametrize("missing", ["set", "bundle"]) +def test_missing_assessment_fails_the_build(tmp_path, missing): + s, b = _set(tmp_path) + (s if missing == "set" else b).unlink() + with pytest.raises(SystemExit, match="missing"): + _assessor.load_assessment(s, b, IDENTITY, verifier=ok) + + +def test_set_from_another_assessor_fails(tmp_path): + s, b = _set(tmp_path) + doc = json.loads(s.read_text()) + doc["assessor"]["organization"] = "Some Other Auditor" + s.write_text(json.dumps(doc)) + with pytest.raises(SystemExit, match="not the pinned assessor"): + _assessor.load_assessment(s, b, IDENTITY, verifier=ok) + + +def test_set_without_an_overall_summary_fails(tmp_path): + s, b = _set(tmp_path) + doc = json.loads(s.read_text()) + doc["records"] = [r for r in doc["records"] if r["kind"] != "summary"] + s.write_text(json.dumps(doc)) + with pytest.raises(SystemExit, match="overall summary"): + _assessor.load_assessment(s, b, IDENTITY, verifier=ok) + + +def test_cosign_is_asked_for_exactly_the_pinned_identity(tmp_path, monkeypatch): + seen = {} + + def fake_run(argv, **_kw): + seen["argv"] = argv + + class R: + returncode = 0 + return R() + monkeypatch.setattr(_assessor.subprocess, "run", fake_run) + ident = _assessor.load_keyless_identity(IDENTITY) + assert _assessor.cosign_verify("s.json", "s.bundle", ident) + argv = seen["argv"] + assert argv[argv.index("--certificate-identity") + 1] == ident["certificate_identity"] + assert "--certificate-identity-regexp" not in argv + + +def test_keyless_identity_refuses_loose_record_files(tmp_path): + d = tmp_path / "records" + d.mkdir() + (d / "genuine.json").write_text((FIX / "genuine.json").read_text()) + with pytest.raises(SystemExit, match="keyless"): + _assessor.load_records(d, IDENTITY) + + +def test_set_records_match_the_published_record_schema(): + jsonschema = pytest.importorskip("jsonschema") + schema = json.loads((REPO / "infrastructure" / "schemas" / "assessor-record.schema.json").read_text()) + for rec in json.loads((FIX / "simulated-set.json").read_text())["records"]: + jsonschema.validate(rec, schema) + + +# --- the SDR carries every rule's and KSI's independent result verbatim ---------------- + +def test_every_rule_and_ksi_gets_its_independent_result_and_t74_holds(tmp_path): + recs = _assessor.load_assessment(*_set(tmp_path), IDENTITY, verifier=ok) + pseudo = [{"rule_id": i, "assessor_comment_responses": []} for i in ("SDR-CSO-FRR", "CDS-CSO-RPS", "KSI-CED-RAT")] + block = _assessor.attach(pseudo, recs) + assert all(len(p["assessor_comment_responses"]) == 1 for p in pseudo) + assert [r["kind"] for r in block["records"]] == ["summary"] + by_rule = {p["rule_id"]: p["assessor_comment_responses"] for p in pseudo} + sdr = {"providerExtensions": {"assessorRecords": block, "assessorCommentResponses": by_rule}} + _assessor.verify_output(sdr, recs) + text = by_rule["SDR-CSO-FRR"][0]["text"] + assert "Independent verification:" in text and "Independent validation:" in text + bad = copy.deepcopy(sdr) + bad["providerExtensions"]["assessorCommentResponses"]["SDR-CSO-FRR"][0]["text"] = "Softened." + with pytest.raises(SystemExit): + _assessor.verify_output(bad, recs) + + +# --- the assessor's own checks --------------------------------------------------------- + +def _guide(**art): + chk = {"url": f"{SITE}/.well-known/security-decision-record.json", + "bundle_url": f"{SITE}/.well-known/security-decision-record.bundle", "identities": ["deploy"], + "timestamp": {"source": "json", "field": "emitted_at"}, "max_age_hours": 720, **art} + return {"site": SITE, + "identities": {"deploy": "D", "nightly": "N", "assessor": "A", "oidc_issuer": "I"}, + "rules": [{"rule_id": "SDR-CSO-FRR", "force": "MUST", "status": "Implemented", "evidence": [ + {"kind": "test", "ref": "tests/t.py::test_a", "check": {"pytest": "tests/t.py::test_a"}}, + {"kind": "artifact", "ref": ".well-known/security-decision-record.json", "check": {"artifact": chk}}]}, + {"rule_id": "CDS-CSO-RPS", "force": "MAY", "status": "Not Applicable", + "not_applicable": "not exercised", "evidence": []}], + "ksis": [{"ksi_id": "KSI-CED-RAT"}]} + + +def _get(age_hours=3, status=200, signal_has_ksi=True): + emitted = (NOW - timedelta(hours=age_hours)).isoformat() + + def get(url): + if url.endswith("ksi-signal.json"): + ks = [{"id": "KSI-CED-RAT", "status": "pass", "method": "documentation"}] if signal_has_ksi else [] + return 200, json.dumps({"signal_id": "sig-1", "ksis": ks}).encode(), {} + if url.endswith(".bundle"): + return 200, b"{}", {} + return status, json.dumps({"emitted_at": emitted}).encode(), {} + return get + + +def _run(guide, tests_result="passed", verify=ok, **get_kw): + a = assess.Assessor(guide, str(REPO), NOW, get=_get(**get_kw), verify=verify, + tests=lambda refs, _repo: {r: tests_result for r in refs}) + return a.assess() + + +def test_a_sound_package_passes_every_rule_and_ksi(): + rules, ksis = _run(_guide()) + assert [(r[0], r[1]) for r in rules] == [("SDR-CSO-FRR", "pass"), ("CDS-CSO-RPS", "pass")] + assert ksis[0][1] == "pass" + + +def test_a_cited_test_failing_on_the_assessor_rerun_is_a_failure(): + rules, _ = _run(_guide(), tests_result="failed") + assert rules[0][1] == "fail" + + +def test_a_published_artifact_whose_signature_fails_is_a_failure(): + rules, _ = _run(_guide(), verify=lambda *_a: False) + assert rules[0][1] == "fail" + _, ksis = _run(_guide(), verify=lambda *_a: False) + assert ksis[0][1] == "fail" + + +def test_dotted_timestamp_fields_are_read(): + body = json.dumps({"metadata": {"lastUpdated": (NOW - timedelta(hours=2)).isoformat()}}).encode() + age = assess._age_hours(body, {}, {"source": "json", "field": "metadata.lastUpdated"}, NOW) + assert round(age) == 2 + + +@pytest.mark.parametrize("kw,needle", [({"status": 404}, "not yet published"), ({"age_hours": 900}, "past its")]) +def test_unpublished_or_stale_artifacts_are_observations_not_failures(kw, needle): + rules, _ = _run(_guide(), **kw) + assert rules[0][1] == "observation" and needle in rules[0][3][0] + + +def test_status_short_of_complete_fails(): + g = _guide() + g["rules"][0]["status"] = "Partially Implemented" + rules, _ = _run(g) + assert rules[0][1] == "fail" + + +def test_main_exits_non_zero_on_any_failure(tmp_path, monkeypatch): + g = tmp_path / "guide.json" + g.write_text(json.dumps(_guide())) + monkeypatch.setattr(assess, "http_get", _get()) + monkeypatch.setattr(assess, "cosign_verify", ok) + monkeypatch.setattr(assess, "run_tests", lambda refs, _r: {r: "failed" for r in refs}) + out = tmp_path / "set.json" + assert assess.main(["--guide", str(g), "--output", str(out)]) == 1 + doc = json.loads(out.read_text()) + assert doc["results"]["rules"]["fail"] == 1 + + +def test_the_set_round_trips_through_the_provider_port(tmp_path): + rules, ksis = _run(_guide()) + doc = assess.build_set(_guide(), rules, ksis, NOW, "0" * 40, "f" * 64) + s = tmp_path / "simulated-assessment.json" + s.write_text(json.dumps(doc)) + b = tmp_path / "simulated-assessment.bundle" + b.write_text("{}") + recs = _assessor.load_assessment(s, b, IDENTITY, verifier=ok) + assert {r.get("rule_id") for r in recs} == {"SDR-CSO-FRR", "CDS-CSO-RPS", "KSI-CED-RAT", None} + + +def test_the_assessor_runs_cited_tests_itself(): + res = assess.run_tests({"tests/test_frr_evidence.py::test_all_cited_tests_passing_is_a_pass", + "tests/test_frr_evidence.py::test_no_such_test"}, str(REPO)) + assert res == {"tests/test_frr_evidence.py::test_all_cited_tests_passing_is_a_pass": "passed", + "tests/test_frr_evidence.py::test_no_such_test": "not run"} + + +# --- it is obviously a simulation and claims nothing ------------------------------------ + +def test_the_simulation_is_labelled_and_claims_no_fedramp_recognition(): + ident = json.loads(IDENTITY.read_text()) + doc = json.loads((FIX / "simulated-set.json").read_text()) + assert ident["simulated"] is True and "(simulated)" in ident["assessor"] + assert doc["simulated"] is True and doc["fedramp_recognized"] is False + assert doc["assessor_id"] == "NOT-A-REAL-ASSESSOR-ID" + assert not re.fullmatch(r"\d{6}", doc["assessor_id"]) # never shaped like a FedRAMP assessor ID + for rec in doc["records"]: + assert "SIMULATED" in rec["text"] + assert "not a FedRAMP Recognized" in rec["text"] or "not a FedRAMP Recognized" in assess.DISCLAIMER + + +def test_the_pinned_identity_is_the_assessor_workflow_not_the_deploy(): + ident = _assessor.load_keyless_identity(IDENTITY) + assert ident["certificate_identity"] == ( + "https://github.com/sam-aydlette/samaydlette.com/.github/workflows/simulated-assessor.yml@refs/heads/main") + assert ident["certificate_oidc_issuer"] == "https://token.actions.githubusercontent.com" + + +# --- wiring: runs on every deploy, before the SDR, and the deploy needs it -------------- + +def _deploy(): + return (WF / "deploy-with-opa.yml").read_text() + + +def test_the_deploy_needs_the_assessor_and_builds_the_sdr_from_its_set(): + wf = _deploy() + job = wf.split("\n simulated-assessor:\n", 1)[1].split("\n # ====", 1)[0] + assert "uses: ./.github/workflows/simulated-assessor.yml" in job + deploy_job = wf.split("\n deploy:\n", 1)[1] + assert re.search(r"needs: \[[^\]]*simulated-assessor[^\]]*\]", deploy_job) + sdr_step = deploy_job.split("- name: Build Security Decision Record", 1)[1].split("\n - name:", 1)[0] + assert sdr_step.count("--assessment simulated-assessment.json") == 2 # build and T74 re-check + assert deploy_job.index("- name: Download the simulated assessment") < deploy_job.index( + "- name: Build Security Decision Record") + + +def test_the_assessor_workflow_holds_no_cloud_credentials_and_signs_as_itself(): + wf = (WF / "simulated-assessor.yml").read_text() + assert "workflow_call" in wf + assert "configure-aws-credentials" not in wf and "secrets." not in wf + assert "id-token: write" in wf + assert "cosign sign-blob" in wf and "cosign verify-blob" in wf + + +def test_the_assessor_workflow_pins_the_same_opa_as_the_deploy(): + def pins(text): + return {k: re.search(rf"^\s*{k}: (\S+)", text, re.M).group(1) for k in ("OPA_VERSION", "OPA_SHA256")} + assert pins((WF / "simulated-assessor.yml").read_text()) == pins(_deploy()) diff --git a/tools/simulated-assessor/assess.py b/tools/simulated-assessor/assess.py new file mode 100644 index 00000000..0173dd96 --- /dev/null +++ b/tools/simulated-assessor/assess.py @@ -0,0 +1,352 @@ +#!/usr/bin/env python3 +"""Totally Real Assessment Services, LLC (simulated): the stand-in assessor. + +SIMULATED. This is a GitHub Actions workflow in the provider's own repository +playing the part of an independent assessor, so the assessor port can be +exercised end to end on every deploy. It is not independent of the provider, +it is not a FedRAMP Recognized independent assessment service, it has no +FedRAMP assessor ID, and nothing it writes is a FedRAMP independent assessment. + +What it does, on every deploy, before the Security Decision Record is built: + + verification for each FedRAMP rule in the provider's assessor guide, checks + the status is Implemented or Not Applicable and re-runs or + re-reads every piece of evidence the guide names: runs every + cited test itself (one pytest run), finds every cited workflow + step, and looks every cited decision up in the register; + validation fetches every cited published artifact from the live site, + verifies its Sigstore signature against the publishing + workflow's identity, and checks its age against the governed + window; and checks every KSI in the guide is in the live, + signature-verified KSI signal. + +It writes one result record per rule and per KSI and one overall summary +(IVV-IAS-OSA), in the provider's assessor-record format, into one set file. Its +workflow signs that file keylessly under the assessor's own workflow identity, +which the provider pins (infrastructure/keys/assessor-identity.json). It +imports nothing from the provider's scripts/. + +Exit status is non-zero, and the deploy does not proceed, when any cited test +fails or does not run, a cited step or decision is missing, a status is short +of Implemented or Not Applicable, or a published artifact's signature does not +verify. An artifact not yet published (first published by the deploy under +assessment) or past its window is an observation, recorded but not fatal: the +deploy is what refreshes it. +""" + +import argparse +import hashlib +import json +import re +import subprocess # nosec B404: runs pytest and cosign with fixed argument lists +import sys +import tempfile +import urllib.error +import urllib.request +import xml.etree.ElementTree as ET # nosec B405: parses the JUnit file this run's own pytest wrote +from datetime import datetime, timezone +from email.utils import parsedate_to_datetime +from pathlib import Path + +ORG = "Totally Real Assessment Services, LLC (simulated)" +KEY_ID = "sigstore-keyless:simulated-assessor.yml" +SET_NAME = "simulated-assessment.json" +DISCLAIMER = ( + "SIMULATED. Totally Real Assessment Services, LLC is a GitHub Actions workflow in the provider's own " + "repository, wearing a lanyard. It is not independent, it is not a FedRAMP Recognized independent " + "assessment service, its assessor ID is NOT-A-REAL-ASSESSOR-ID, and nothing here is a FedRAMP independent " + "assessment. It exists to show the assessor port working end to end. Our rates are very competitive: free.") +STEP_LINE = re.compile(r"^\s*-\s+name:\s*(.+?)\s*$") +ISSUER = "https://token.actions.githubusercontent.com" +COMPLETE = ("Implemented", "Not Applicable") + + +def canonical(record): + body = {k: v for k, v in record.items() if k != "signature"} + return json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8") + + +# --- checks --------------------------------------------------------------------------- + +def run_tests(refs, repo): + """{ref: "passed" | "failed" | "skipped" | "not run"} from one pytest run.""" + if not refs: + return {} + with tempfile.TemporaryDirectory() as d: + junit = Path(d) / "junit.xml" + # Whole files, not node IDs: pytest refuses the entire run when one node + # ID does not exist, and a missing cited test must read "not run" here. + files = sorted({r.split("::", 1)[0] for r in refs if (Path(repo) / r.split("::", 1)[0]).is_file()}) + if files: + subprocess.run([sys.executable, "-m", "pytest", "-q", "-p", "no:cacheprovider", f"--junitxml={junit}", + *files], cwd=repo, check=False) # nosec B603: fixed argv + cases = {} + if junit.exists(): + for case in ET.parse(junit).getroot().iter("testcase"): # nosec B314: own file + parts = case.get("classname", "").split(".") + func = case.get("name", "").split("[", 1)[0] + if len(parts) >= 2 and parts[-1][:1].isupper(): + key = "/".join(parts[:-1]) + f".py::{parts[-1]}::{func}" + else: + key = "/".join(parts) + f".py::{func}" + bad = case.find("failure") is not None or case.find("error") is not None + out = "failed" if bad else "skipped" if case.find("skipped") is not None else "passed" + cases.setdefault(key, []).append(out) + res = {} + for ref in refs: + got = cases.get(ref.split("[", 1)[0]) + res[ref] = ("not run" if not got else "passed" if all(c == "passed" for c in got) + else "failed" if "failed" in got else "skipped") + return res + + +def step_exists(repo, wf, step): + p = Path(repo) / ".github" / "workflows" / wf + if not p.is_file(): + return False + return any((m := STEP_LINE.match(line)) and m.group(1).strip().strip("'\"") == step + for line in p.read_text().splitlines()) + + +def decision_in_force(repo, dec_id): + doc = json.loads((Path(repo) / "data" / "decisions.json").read_text()) + return any(d.get("id") == dec_id and d.get("status") == "in-force" for d in doc.get("decisions", [])) + + +def http_get(url): + """(status, body bytes, headers). 404 is a status, not an exception.""" + req = urllib.request.Request(url, headers={"User-Agent": "totally-real-assessor/1 (simulated)"}) + try: + with urllib.request.urlopen(req, timeout=30) as r: # nosec B310: https URLs from the guide + return r.status, r.read(), dict(r.headers) + except urllib.error.HTTPError as e: + return e.code, b"", dict(e.headers or {}) + + +def cosign_verify(blob, bundle, identity): + with tempfile.TemporaryDirectory() as d: + b, s = Path(d) / "blob", Path(d) / "bundle" + b.write_bytes(blob) + s.write_bytes(bundle) + r = subprocess.run(["cosign", "verify-blob", "--bundle", str(s), "--certificate-identity", identity, + "--certificate-oidc-issuer", ISSUER, str(b)], + capture_output=True, check=False) # nosec B603: fixed argv + return r.returncode == 0 + + +def _age_hours(body, headers, ts, now): + raw = None + if ts.get("source") == "json": + try: + raw = json.loads(body) + for part in ts["field"].split("."): # dotted path, e.g. metadata.lastUpdated + raw = raw.get(part) if isinstance(raw, dict) else None + except ValueError: + return None + if not isinstance(raw, str): + return None + try: + t = datetime.fromisoformat(raw.replace("Z", "+00:00")) + except ValueError: + return None + else: + lm = headers.get("Last-Modified") or headers.get("last-modified") + if not lm: + return None + t = parsedate_to_datetime(lm) + if t.tzinfo is None: + t = t.replace(tzinfo=timezone.utc) + return (now - t).total_seconds() / 3600 + + +class Assessor: + def __init__(self, guide, repo, now, get=None, verify=None, tests=None): + self.guide, self.repo, self.now = guide, repo, now + self.get, self.verify, self.tests = get or http_get, verify or cosign_verify, tests or run_tests + self._artifacts = {} + + def artifact(self, chk): + """(outcome, note): outcome is pass | observation | fail.""" + url = chk["url"] + if url in self._artifacts: + return self._artifacts[url] + status, body, headers = self.get(url) + name = url.rsplit("/", 1)[1] + if status == 404: + res = ("observation", f"{name} is not yet published; it is first published by the deploy under " + "assessment, and validated at the next assessment") + elif status != 200: + res = ("fail", f"{name} returned HTTP {status}") + else: + notes = [f"{name} served"] + res = None + if chk.get("bundle_url"): + bstatus, bundle, _ = self.get(chk["bundle_url"]) + ids = [self.guide["identities"][i] for i in chk["identities"]] + if bstatus != 200 or not any(self.verify(body, bundle, i) for i in ids): + res = ("fail", f"{name}'s signature does not verify against " + f"{' or '.join(chk['identities'])} identity") + else: + notes.append(f"signature verified ({'/'.join(chk['identities'])} identity)") + if res is None: + age = _age_hours(body, headers, chk["timestamp"], self.now) + if age is None: + res = ("observation", "; ".join(notes) + "; its age could not be read") + elif age > chk["max_age_hours"]: + res = ("observation", "; ".join(notes) + f"; {age:.0f}h old, past its " + f"{chk['max_age_hours']}h window") + else: + res = ("pass", "; ".join(notes) + f"; {age:.0f}h old (window {chk['max_age_hours']}h)") + self._artifacts[url] = res + return res + + def assess(self): + rules = self.guide["rules"] + test_refs = {ev["check"]["pytest"] for r in rules for ev in r["evidence"] if "pytest" in ev["check"]} + test_res = self.tests(test_refs, self.repo) + results = [] + for r in rules: + ver, val, outcome = [], [], "pass" + + def worst(o): + nonlocal outcome + order = {"pass": 0, "observation": 1, "fail": 2} + outcome = o if order[o] > order[outcome] else outcome + + if r["status"] not in COMPLETE: + ver.append(f"status is {r['status']}, short of Implemented or Not Applicable") + worst("fail") + elif r["status"] == "Not Applicable": + ver.append(f"Not Applicable ({r['force']}): {r.get('not_applicable', 'no reason given')}") + if not r.get("not_applicable"): + worst("fail") + for ev in r["evidence"]: + chk = ev["check"] + if "pytest" in chk: + res = test_res.get(chk["pytest"], "not run") + ver.append(f"test {chk['pytest']} {res} (re-run by the assessor)") + if res != "passed": + worst("fail") + elif "workflow" in chk: + ok = step_exists(self.repo, chk["workflow"], chk["step"]) + ver.append(f"step {chk['step']!r} {'present' if ok else 'MISSING'} in {chk['workflow']}") + if not ok: + worst("fail") + elif "decision" in chk: + ok = decision_in_force(self.repo, chk["decision"]) + ver.append(f"decision {chk['decision']} {'in force' if ok else 'NOT in force'}") + if not ok: + worst("fail") + elif "artifact" in chk: + o, note = self.artifact(chk["artifact"]) + val.append(note) + worst(o) + if r["status"] == "Implemented" and not r["evidence"]: + ver.append("Implemented with no evidence") + worst("fail") + if "simulated" in r: + ver.append(f"relies on a simulated counterparty ({r['simulated']['counterparty']})") + results.append((r["rule_id"], outcome, ver, val)) + return results, self.assess_ksis() + + def assess_ksis(self): + guide = self.guide + url = f"{guide['site']}/.well-known/ksi-signal.json" + status, body, _ = self.get(url) + bstatus, bundle, _ = self.get(f"{guide['site']}/.well-known/ksi-signal.bundle") + if status != 200 or bstatus != 200 or not self.verify(body, bundle, guide["identities"]["deploy"]): + return [(k["ksi_id"], "fail", ["the live KSI signal could not be fetched or its signature did " + "not verify"], []) for k in guide["ksis"]] + sig = json.loads(body) + by_id = {k["id"]: k for k in sig.get("ksis", [])} + out = [] + for k in guide["ksis"]: + s = by_id.get(k["ksi_id"]) + if s is None: + out.append((k["ksi_id"], "observation", [f"not in the published signal {sig.get('signal_id')}"], + [])) + continue + out.append((k["ksi_id"], "pass", + [f"in the published signal {sig.get('signal_id')} with status {s.get('status')} by " + f"method {s.get('method')}"], + ["KSI signal served and its signature verified (deploy identity)"])) + return out + + +# --- the record set ------------------------------------------------------------------------ + +def _record(rid, kind, text, issued, subject_id=None): + rec = {"record_type": "assessor-record", "schema_version": "1", "record_id": rid, + "assessor": {"organization": ORG, "key_id": KEY_ID}, "issued_at": issued, "kind": kind, "text": text} + if subject_id: + rec["rule_id"] = subject_id + rec["signature"] = {"algorithm": "SIGSTORE_KEYLESS_SET", "value": hashlib.sha256(canonical(rec)).hexdigest(), + "signed_set": SET_NAME} + return rec + + +def _text(what, outcome, ver, val): + label = {"pass": "Pass", "observation": "Pass with observation", "fail": "FAIL"}[outcome] + parts = [f"SIMULATED assessment of {what}, not a FedRAMP Recognized assessment. Result: {label}."] + if ver: + parts.append("Independent verification: " + "; ".join(ver) + ".") + if val: + parts.append("Independent validation: " + "; ".join(val) + ".") + elif ver: + parts.append("Independent validation: no published artifact cited; validated through the verification " + "above.") + return " ".join(parts) + + +def build_set(guide, rule_results, ksi_results, now, commit, guide_sha): + issued = now.replace(microsecond=0).isoformat() + tag = now.strftime("%Y%m%dT%H%M%SZ") + records = [_record(f"TRAS-{tag}-{rid}", "finding", _text(f"rule {rid}", o, ver, val), issued, rid) + for rid, o, ver, val in rule_results] + records += [_record(f"TRAS-{tag}-{kid}", "finding", _text(f"KSI {kid}", o, ver, val), issued, kid) + for kid, o, ver, val in ksi_results] + + def count(res): + return {o: sum(1 for x in res if x[1] == o) for o in ("pass", "observation", "fail")} + + rc, kc = count(rule_results), count(ksi_results) + obs = [f"{x[0]}: {'; '.join(x[3] or x[2])}" for x in rule_results + ksi_results if x[1] == "observation"] + fails = [x[0] for x in rule_results + ksi_results if x[1] == "fail"] + summary = (f"Overall summary (IVV-IAS-OSA), SIMULATED. {ORG} verified and validated all " + f"{len(rule_results)} applicable FedRAMP rules and all {len(ksi_results)} Key Security Indicators " + f"for commit {commit or 'unknown'}: rules {rc['pass']} pass, {rc['observation']} pass with " + f"observation, {rc['fail']} fail; KSIs {kc['pass']} pass, {kc['observation']} pass with " + f"observation, {kc['fail']} fail. Failures: {', '.join(fails) or 'none'}. Areas of dispute: none. " + f"Observations: {' | '.join(sorted(set(obs))) or 'none'}. {DISCLAIMER}") + records.append(_record(f"TRAS-{tag}-SUMMARY", "summary", summary, issued)) + return {"assessment_type": "simulated-independent-assessment", "schema_version": "1", + "simulated": True, "fedramp_recognized": False, "assessor_id": "NOT-A-REAL-ASSESSOR-ID", + "disclaimer": DISCLAIMER, "assessor": {"organization": ORG, "key_id": KEY_ID}, + "issued_at": issued, + "subject": {"site": guide["site"], "commit": commit, "assessor_guide_sha256": guide_sha}, + "results": {"rules": rc, "ksis": kc}, + "records": records} + + +def main(argv=None): + ap = argparse.ArgumentParser(description="Simulated assessor (not a FedRAMP Recognized assessment).") + ap.add_argument("--guide", required=True, help="the provider's assessor-guide.json") + ap.add_argument("--repo", default=".") + ap.add_argument("--commit", default=None) + ap.add_argument("--output", default=SET_NAME) + a = ap.parse_args(argv) + raw = Path(a.guide).read_bytes() + guide = json.loads(raw) + now = datetime.now(timezone.utc) + rules, ksis = Assessor(guide, a.repo, now).assess() + doc = build_set(guide, rules, ksis, now, a.commit, hashlib.sha256(raw).hexdigest()) + Path(a.output).write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n") + fails = [x for x in rules + ksis if x[1] == "fail"] + for x in fails: + print(f"::error::simulated assessor: {x[0]} failed: {'; '.join(x[2] + x[3])}") + print(f"simulated assessment: rules {doc['results']['rules']}, KSIs {doc['results']['ksis']}") + return 1 if fails else 0 + + +if __name__ == "__main__": + sys.exit(main()) From 567109b322c1526bcae6c45165eee28f7df8b432 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:50:04 -0500 Subject: [PATCH 05/17] test(decisions): migration assertions cover DEC-001..099; later records in allocated blocks Co-Authored-By: Claude Opus 5.5 --- tests/test_decisions.py | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/tests/test_decisions.py b/tests/test_decisions.py index 56ab7059..5746cbad 100644 --- a/tests/test_decisions.py +++ b/tests/test_decisions.py @@ -46,7 +46,9 @@ def _env(): def test_the_committed_register_loads_and_matches_its_schema(): reg = _decisions.load() - assert len(reg["decisions"]) == 39 # 37 carried over from the POA&M, 2 new + # The migration range (DEC-001..099): 37 carried over from the POA&M, 2 new. + # Later records are added in the blocks below. + assert len([r for r in reg["decisions"] if _num(r) < 100]) == 39 jsonschema = pytest.importorskip("jsonschema") jsonschema.validate(json.loads(REGISTER.read_text()), json.loads(SCHEMA.read_text())) @@ -146,8 +148,25 @@ def test_the_check_maps_are_the_ones_the_poam_held(): assert false_pos == rename(frozen["false_positive"]) +def _num(r): + return int(r["id"][4:]) + + +# Blocks for records added after the migration, one per piece of work, so +# parallel branches never collide (2026-11-05). DEC-041..099 stay unused: the +# migration range is closed. +DEC_BLOCKS = {"certification reports": (100, 129), "notifications": (130, 149), + "trust center, scope and assessor": (150, 179), "detection and evaluation": (180, 209)} + + +def test_records_after_the_migration_sit_in_an_allocated_block(): + for r in _decisions.load()["decisions"]: + n = _num(r) + assert n <= 40 or any(lo <= n <= hi for lo, hi in DEC_BLOCKS.values()), r["id"] + + def test_the_only_new_records_are_the_two_dast_false_positives(): - new = [r for r in _decisions.load()["decisions"] if not r.get("former_id")] + new = [r for r in _decisions.load()["decisions"] if not r.get("former_id") and _num(r) < 100] assert [(r["id"], r["disposition"], r["applies_to"]["vuln_ids"]) for r in new] == [ ("DEC-039", "false-positive", ["zap-10099"]), ("DEC-040", "false-positive", ["zap-10036-2"])] assert all(r["decided_by"] == "Sam Aydlette" for r in new) From e390c0a6853ccc9eed9ec5507acaf6a9dea70690 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:51:47 -0500 Subject: [PATCH 06/17] feat(mas): Minimum Assessment Scope generated and gated on every deploy (MAS-CSO-IIR/FLO/MDI/TPR, FRC-CSX-MAS) - Inventory: the app's browser origins (jsDelivr, Google Cloud Storage) and the VDR's remaining feeds (FIRST EPSS, Grype database) become external services; the CloudTrail trail joins the logging KSIs' evidence domain. - scripts/build-mas.py publishes /.well-known/minimum-assessment-scope.json (+ .md, signed, freshness-governed): information resources, every CSP off-origin host placed or out of scope with a reason, flows with a high-water-mark security category, a metadata inventory, the third-party records with FedRAMP's four fields, and the KSI-to-scope application. It fails the deploy, before the SDR, on any gap. - Classification: 17 new flows covering every external service and data store; an app-delivery group (and its service in the service model). - Third-party records: the four MAS-CSO-TPR fields on all 11; decision fields AI-drafted for the operator to confirm; a decided record without them fails. - scripts/_tpr.py: the CPO's thirdPartyInformationResources, for the CPO hook. - Five rule records flip to Implemented with resolving evidence. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/deploy-with-opa.yml | 21 + data/frr-records.json | 153 +- data/minimum-assessment-scope.json | 36 + data/third-party-components.json | 209 +- docs/boundary/boundary-classification.json | 40 +- docs/portfolio/service-model.json | 8 + infrastructure/schemas/freshness-config.json | 11 + scripts/_tpr.py | 40 + scripts/build-ksi-signal.py | 59 +- scripts/build-mas.py | 424 ++++ tests/fixtures/mas/classification-gaps.json | 6 + tests/fixtures/mas/csp-unplaced.tf.fixture | 11 + tests/fixtures/mas/csp-unresolved.tf.fixture | 11 + tests/fixtures/mas/signal-gaps.json | 11 + tests/fixtures/mas/signal.json | 2254 +++++++++++++++++ .../decided-without-tpr-fields.json | 19 + tests/fixtures/third-party/decided.json | 28 +- tests/test_mas.py | 234 ++ 18 files changed, 3501 insertions(+), 74 deletions(-) create mode 100644 data/minimum-assessment-scope.json create mode 100644 scripts/_tpr.py create mode 100644 scripts/build-mas.py create mode 100644 tests/fixtures/mas/classification-gaps.json create mode 100644 tests/fixtures/mas/csp-unplaced.tf.fixture create mode 100644 tests/fixtures/mas/csp-unresolved.tf.fixture create mode 100644 tests/fixtures/mas/signal-gaps.json create mode 100644 tests/fixtures/mas/signal.json create mode 100644 tests/fixtures/third-party/decided-without-tpr-fields.json create mode 100644 tests/test_mas.py diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 24a24847..3faa6698 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1587,6 +1587,22 @@ jobs: --previous previous-availability.json --ksi-signal ksi-signal.json python3 ../scripts/build-policy-index.py --output policy-index.json --md-output policy-index.md + # The Minimum Assessment Scope (MAS-CSO-IIR/FLO/MDI/TPR, FRC-CSX-MAS), generated + # from this build's inventory, the boundary classification's flows, the CSPs + # the edge serves and the third-party records. Fails the deploy, before the + # SDR, on an unplaced off-origin host, an external service or data store in + # no flow, a data store without a metadata entry, an undecided third-party + # record, or a component type no KSI covers. Signed and published with the + # rest after the gates. + - name: Build the Minimum Assessment Scope + working-directory: infrastructure + env: + GITHUB_SHA: ${{ github.sha }} + run: | + python3 ../scripts/build-mas.py --ksi-signal ksi-signal.json --commit "$GITHUB_SHA" \ + --output minimum-assessment-scope.json --md-output minimum-assessment-scope.md + cosign sign-blob --yes --new-bundle-format --bundle minimum-assessment-scope.bundle minimum-assessment-scope.json + - name: Build Security Decision Record (SDR — 20x SSP replacement) working-directory: infrastructure run: | @@ -1733,6 +1749,7 @@ jobs: [ -f "$a.json" ] || continue files="$files $a.json" done + files="$files minimum-assessment-scope.json minimum-assessment-scope.md" # shellcheck disable=SC2086 # a word list by design python3 ../scripts/check-published-redaction.py $files @@ -1795,6 +1812,10 @@ 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 + # Minimum Assessment Scope (MAS-CSO-IIR/FLO/MDI/TPR) + bundle + human-readable + aws s3 cp minimum-assessment-scope.json "s3://$BUCKET_NAME/.well-known/minimum-assessment-scope.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp minimum-assessment-scope.bundle "s3://$BUCKET_NAME/.well-known/minimum-assessment-scope.bundle" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp minimum-assessment-scope.md "s3://$BUCKET_NAME/.well-known/minimum-assessment-scope.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" echo "✅ All signed artifacts published to /.well-known/ (post-gate)" # ------------------------------------------------------------------------- diff --git a/data/frr-records.json b/data/frr-records.json index 6a767bed..a8c73644 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -628,12 +628,29 @@ }, { "frr_id": "FRC-CSX-MAS", - "status": "Partially Implemented", - "implementation": "The KSI signal applies the KSIs to the inventoried components (ksi-signal.json), derived from Terraform state.", - "evidence": [], - "gap": "The inventory misses external services the site loads from (cdn.jsdelivr.net, storage.googleapis.com) and some flows, and human-process KSIs are not applied per component; MAS-CSO-IIR and MAS-CSO-FLO carry the detail.", - "closes_with": [ - "W10" + "status": "Implemented", + "implementation": "Every KSI is applied to the whole Minimum Assessment Scope. The inventory now includes the external services the app and the VDR depend on (MAS-CSO-IIR), and each KSI's evidence domain names the component types it covers. KSIs with a per-component domain apply to every component of those types; inventory and documentation KSIs (PIY, CED) apply over the whole set. scripts/build-mas.py publishes the application per KSI and per component type in .well-known/minimum-assessment-scope.json, and fails the deploy when a component type is in no KSI's per-component domain and has no stated whole-set reason (static pages and the state lock table carry one).", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_mas.py::test_every_ksi_applies_and_every_component_type_is_covered" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_component_type_in_no_ksi_domain_fails" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_audit_trail_is_in_the_logging_ksi_domain" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build the Minimum Assessment Scope" + }, + { + "kind": "artifact", + "ref": ".well-known/minimum-assessment-scope.json" + } ] }, { @@ -816,32 +833,87 @@ }, { "frr_id": "MAS-CSO-FLO", - "status": "Partially Implemented", - "implementation": "https://samaydlette.com/.well-known/boundary-map.json: 11 flows with protocol/auth/encryption/data, 137 edges derived from Terraform, per-node classification; flows declared in docs/boundary/boundary-classification.json and resolved against the inventory (unmatched endpoints check = 0); code scripts/build-boundary-graph.py; human view on /trust/ and authorization-boundary page.", - "evidence": [], - "gap": "Flows are not complete for ALL resources: missing user→Cognito Hosted UI authentication, browser→jsDelivr / storage.googleapis.com, Lambda/app→DynamoDB/SQS, CloudTrail/S3/CloudFront→log bucket, operator→AWS console (Duo/root MFA), nightly→GitHub Advisory DB / CISA KEV / detection feeds. Security categories are per component (classification) but flows carry no category. To close: Add the missing flows to the classification, and add a check that every inventoried external service and every data store appears in at least one flow; derive per-flow security category from its endpoints.", - "closes_with": [ - "W10" + "status": "Implemented", + "implementation": "The boundary classification's data-flow table (docs/boundary/boundary-classification.json) covers every external service and every data store or log in the inventory, including sign-in to the Cognito Hosted UI, the browser loads from jsDelivr and Google Cloud Storage, log delivery to the access-log and CloudTrail buckets and the log groups, the dead-letter queue, operator administration with MFA, Terraform state and lock, and the vulnerability feeds. scripts/build-mas.py resolves each flow against this build's inventory, gives each the high-water mark of its endpoints' FIPS 199 security categories, and fails the deploy when a flow names a component the inventory lacks or an external service or data store is in no flow. Published in .well-known/minimum-assessment-scope.json (flows with categories, protocol, authentication, encryption and data) and drawn on the boundary map.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_mas.py::test_flow_gaps_fail" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_every_external_service_and_data_store_in_the_inventory_is_in_a_flow" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_flow_category_is_the_high_water_mark_of_its_endpoints" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build the Minimum Assessment Scope" + }, + { + "kind": "artifact", + "ref": ".well-known/minimum-assessment-scope.json" + }, + { + "kind": "artifact", + "ref": ".well-known/boundary-map.json" + } ] }, { "frr_id": "MAS-CSO-IIR", - "status": "Partially Implemented", - "implementation": "Machine-readable: https://samaydlette.com/.well-known/ksi-signal.json components[] (214, from Terraform state + SBOMs) and iiw.csv; human-readable derivation: docs/ksi-signal.md and research/authorization-boundary.html; code: scripts/build-ksi-signal.py; reconcile invariant (a) 'every live in-boundary resource is in the inventory' held.", - "evidence": [], - "gap": "Incomplete: the Silk Reeling SPA loads MediaPipe code from cdn.jsdelivr.net and models from storage.googleapis.com and talks to Cognito Hosted UI (bootstrap/cloudfront.tf:185-186, 378-380); jsDelivr and Google Cloud Storage are not inventoried as information resources although they run code next to the camera feed. The npm package is listed, the delivery services are not. (Repo publicity for the 'code' artifact not verified from here.) To close: Derive external services from the CSP/connect-src allowlists and runtime egress as well as Terraform, so every origin the app loads code or data from becomes an inventoried component; or self-host MediaPipe assets and models.", - "closes_with": [ - "W10" + "status": "Implemented", + "implementation": "Every deploy publishes the set of information resources that make up the offering: the canonical inventory (.well-known/ksi-signal.json, derived from Terraform state, the SBOMs, the site's HTML and the declared external services; reconcile invariant (a) holds every live in-boundary resource to it) and its summary in .well-known/minimum-assessment-scope.json with a human-readable twin and the derivation. The external services include every origin the Silk Reeling app loads code or data from in the user's browser (jsDelivr for the MediaPipe runtime, Google Cloud Storage for the pose model) and every vulnerability feed the VDR reads (GitHub Advisory Database, CISA KEV, FIRST EPSS, the Grype database). scripts/build-mas.py parses the Content Security Policies the edge serves (infrastructure/bootstrap/cloudfront.tf) and fails the deploy, before the SDR is built, when an allowed off-origin host is neither an inventoried component nor out of scope with a stated reason; the podcast audio hosts (media only, no code or data from this system) are out of scope with that reason.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_mas.py::test_unplaced_csp_host_fails" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_unresolvable_csp_source_fails_closed" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_the_app_origins_are_inventoried_external_services" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build the Minimum Assessment Scope" + }, + { + "kind": "artifact", + "ref": ".well-known/minimum-assessment-scope.json" + }, + { + "kind": "artifact", + "ref": ".well-known/ksi-signal.json" + } ] }, { "frr_id": "MAS-CSO-MDI", - "status": "Not Implemented", - "implementation": "Checked: no metadata inventory; CPO says 'MAS-CSO-MDI N/A (no federal customer data)'.", - "evidence": [], - "gap": "No machine-readable output, explanation or code covering metadata the offering collects: Cognito user records (email, MFA), CloudFront/S3/API Gateway/Lambda logs (IP addresses, user agents), CloudTrail, DynamoDB items, SNS subscriptions. To close: Classify each data store/log as metadata in the inventory (type, contents, retention, location), emit a metadata section from build-ksi-signal.py, and document the derivation.", - "closes_with": [ - "W10" + "status": "Implemented", + "implementation": "The metadata the offering collects is in scope and inventoried: every data store and log in the inventory (buckets, log groups, the CloudTrail trail, the state lock table, the dead-letter queue, the Cognito user pool, the alert topic) and the request metadata third parties see when the app loads code or models (jsDelivr, Google Cloud Storage) has an entry stating what it holds, which personal data (for example IP addresses, user agents, the app users' email addresses), its retention and its location. scripts/build-mas.py joins data/minimum-assessment-scope.json with this build's inventory and fails the deploy when a data store or log has no entry; a test holds each stated retention equal to the Terraform. Published, with the explanation of its derivation, in .well-known/minimum-assessment-scope.json and its Markdown twin.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_mas.py::test_data_store_without_metadata_fails" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_metadata_retention_matches_the_terraform" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build the Minimum Assessment Scope" + }, + { + "kind": "artifact", + "ref": ".well-known/minimum-assessment-scope.json" + } ] }, { @@ -854,12 +926,33 @@ }, { "frr_id": "MAS-CSO-TPR", - "status": "Partially Implemented", - "implementation": "ksi-signal.json external_service components (7) carry purpose, cia_impact, verification_mechanism, baseline_configuration; data/third-party-components.json holds responsibility split records; build-ksi-signal.py:1322-1345.", - "evidence": [], - "gap": "All 7 third-party records are undecided (decided_by/decided_on null), so the published upstream_offering/responsibility_split read 'not recorded'. No explicit justification-for-use, mitigation-measures or compensating-controls fields per resource. jsDelivr and Google Cloud Storage (MediaPipe) are missing entirely. Not included in the CPO (schema thirdPartyInformationResources). To close: Add the four required fields (usage/configuration, justification, mitigations, compensating controls) to the record schema, have the operator decide all records, add the MediaPipe hosts, and emit them into the CPO's thirdPartyInformationResources.", - "closes_with": [ - "W10" + "status": "Implemented", + "implementation": "Each of the 11 third-party information resources (Sigstore Fulcio and Rekor, GitHub repository and Actions, GitHub OIDC, the operator's MFA authenticator, the GitHub Advisory Database, CISA KEV, FIRST EPSS, the Grype database, jsDelivr, Google Cloud Storage) has a decided record in data/third-party-components.json with its general usage and configuration, justification for use, mitigation measures and compensating controls. The inventory builder fails when a decided record lacks any of the four, and scripts/build-mas.py fails the deploy when an inventoried external service has no decided record. Machine-readable output: the external_service components in .well-known/ksi-signal.json and the third-party section of .well-known/minimum-assessment-scope.json; the human-readable derivation is in its Markdown twin; the code is scripts/build-ksi-signal.py and scripts/build-mas.py.", + "evidence": [ + { + "kind": "test", + "ref": "tests/test_mas.py::test_decided_third_party_record_without_the_four_fields_fails_the_inventory" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_every_third_party_resource_is_decided_with_the_four_fields" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_published_inventory_carries_the_four_fields" + }, + { + "kind": "test", + "ref": "tests/test_mas.py::test_cpo_helper_matches_the_cpo_schema" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Build the Minimum Assessment Scope" + }, + { + "kind": "artifact", + "ref": ".well-known/minimum-assessment-scope.json" + } ] }, { diff --git a/data/minimum-assessment-scope.json b/data/minimum-assessment-scope.json new file mode 100644 index 00000000..ca7f0d8b --- /dev/null +++ b/data/minimum-assessment-scope.json @@ -0,0 +1,36 @@ +{ + "schema": "mas-inputs/1", + "$comment": "Operator-owned inputs to scripts/build-mas.py, which joins them with the canonical inventory (ksi-signal.json), the boundary classification and the third-party records to produce /.well-known/minimum-assessment-scope.json (MAS-CSO-IIR, MAS-CSO-FLO, MAS-CSO-MDI, MAS-CSO-TPR, FRC-CSX-MAS). The builder fails the deploy when an off-origin host in a CSP is not placed here, when a data store or log in the inventory has no metadata entry, or when a component type is in no KSI evidence domain and has no whole-set reason. AI-drafted 2026-11-05 from the Terraform and the CSPs, for the operator's review.", + "off_origin_hosts": { + "cdn.jsdelivr.net": {"component": "ext::jsdelivr"}, + "storage.googleapis.com": {"component": "ext::google-cloud-storage"}, + "samaydlette-com-silk-reeling.auth.us-east-2.amazoncognito.com": {"component": "aws::identity_provider::silk_reeling"}, + "ochelli.com": {"out_of_scope": "Podcast audio on the activities page (CSP media-src only): the reader's browser streams a public episode directly from the host. Media cannot run code in the page, the host receives nothing from this system, and it is unrelated to the Silk Reeling app or the published evidence, so it neither handles nor affects federal customer data."}, + "traffic.libsyn.com": {"out_of_scope": "Podcast audio redirect host (CSP media-src only), as for ochelli.com: public episode audio streamed directly by the reader's browser; no code, no data from this system."}, + "content.libsyn.com": {"out_of_scope": "Podcast audio file host behind traffic.libsyn.com (CSP media-src only), as for ochelli.com."} + }, + "data_store_types": ["object_store", "log_group", "kv_table", "message_queue", "identity_provider", "notification_topic", "secrets_manager", "audit_log_trail"], + "metadata": { + "aws::object_store::website": {"holds": "Site content and the published /.well-known/ evidence", "personal_data": [], "retention": "Current objects kept; replaced versions expire after 90 days", "retention_days": 90}, + "aws::object_store::logs": {"holds": "S3 server access logs for the site bucket (origin reads)", "personal_data": ["requester IP address", "user agent"], "retention": "400 days, then expired", "retention_days": 400}, + "aws::object_store::cloudtrail": {"holds": "CloudTrail management-event log files", "personal_data": ["operator source IP address", "IAM principal names", "user agent"], "retention": "913 days (moved to infrequent access after 365)", "retention_days": 913}, + "aws::object_store::tfstate": {"holds": "Terraform state: resource configuration and attributes, including secret values", "personal_data": [], "retention": "Current state kept; replaced versions expire after 90 days", "retention_days": 90}, + "aws::kv_table::tflock": {"holds": "Terraform state lock: lock ID, holder and timestamp", "personal_data": [], "retention": "Deleted when the lock is released"}, + "aws::log_group::opa_compliance": {"holds": "Runtime KSI emitter run logs", "personal_data": [], "retention": "365 days", "retention_days": 365}, + "aws::log_group::evidence_watchdog": {"holds": "Evidence-freshness watchdog run logs (artifact ages)", "personal_data": [], "retention": "365 days", "retention_days": 365}, + "aws::log_group::silk_reeling": {"holds": "Silk Reeling app Lambda runtime logs: invocations, errors", "personal_data": [], "retention": "365 days", "retention_days": 365}, + "aws::log_group::silk_apigw": {"holds": "Silk Reeling API access log: request ID, source IP, time, method, route, status, response length", "personal_data": ["source IP address"], "retention": "365 days", "retention_days": 365}, + "aws::log_group::route53_query_log": {"holds": "Route 53 DNS query logs (created only when DNS query logging is enabled)", "personal_data": ["resolver IP address"], "retention": "365 days", "retention_days": 365}, + "aws::message_queue::compliance_dlq": {"holds": "Scheduled events whose emitter invocation failed", "personal_data": [], "retention": "14 days", "retention_days": 14}, + "aws::identity_provider::silk_reeling": {"holds": "App user records: email address, TOTP enrollment, sign-in events", "personal_data": ["email address", "sign-in IP address and device data"], "retention": "Until the operator deletes the user"}, + "aws::notification_topic::evidence_alerts": {"holds": "The operator's email subscription and in-flight alarm notifications", "personal_data": ["operator email address (subscription endpoint, set out of band; never in Terraform or published)"], "retention": "Until the subscription is removed"}, + "aws::audit_log_trail::management": {"holds": "Management events for the account, delivered to the CloudTrail bucket (flow P)", "personal_data": ["operator source IP address", "IAM principal names"], "retention": "As the CloudTrail bucket (913 days)", "retention_days": 913}, + "aws::secrets_manager::*": {"holds": "Application secrets (none today)", "personal_data": [], "retention": "Until deleted, then a 7 to 30 day recovery window"}, + "ext::jsdelivr": {"holds": "Third-party observation: jsDelivr's request logs when a user's browser fetches the MediaPipe runtime", "personal_data": ["user IP address", "user agent"], "retention": "Set by the third party; not controlled by this provider"}, + "ext::google-cloud-storage": {"holds": "Third-party observation: Google's request logs when a user's browser fetches the pose model", "personal_data": ["user IP address", "user agent"], "retention": "Set by the third party; not controlled by this provider"} + }, + "whole_set_types": { + "html_artifact": "Static pages are content of the website bucket: the whole-inventory KSIs (PIY) cover them, and every page is sha256-hashed into the inventory so any change is a recorded change.", + "kv_table": "The state lock table holds lock metadata only; it is covered by the whole-inventory KSIs (PIY) and by the trust-root review of the bootstrap stack." + } +} diff --git a/data/third-party-components.json b/data/third-party-components.json index ff41a57a..51b6dedf 100644 --- a/data/third-party-components.json +++ b/data/third-party-components.json @@ -1,86 +1,233 @@ { - "_note": "REQ-TPR-1 records for the external services the inventory declares (scripts/build-ksi-signal.py build_external_components). Each names the upstream offering, the upstream component's identifier, and the split between what the upstream runs and what this provider configures. A record is published only once it carries decided_by and decided_on; until then the inventory publishes every field as \"not recorded\". A record for a service the inventory does not declare fails the build. AI-drafted entries (drafted_by) are proposals from the evidence listed; none is in force until the operator records a decision. A null value is unknown and is published as \"not recorded\" even after a decision.", + "_note": "REQ-TPR-1 and MAS-CSO-TPR records for the external services the inventory declares (scripts/build-ksi-signal.py build_external_components). Each names the upstream offering, the upstream component's identifier, the split between what the upstream runs and what this provider configures, and the four things FedRAMP requires documented for each third-party information resource (MAS-CSO-TPR): general usage and configuration, justification for use, mitigation measures, and compensating controls. A record is published only once it carries decided_by and decided_on, and a decided record must carry all four MAS-CSO-TPR fields or the build fails; until a decision, the inventory publishes every field as \"not recorded\". A record for a service the inventory does not declare fails the build. AI-drafted entries (drafted_by) were proposed from the evidence listed; the decision fields on the 2026-11-05 drafts are for the operator to confirm. A null value is unknown and is published as \"not recorded\" even after a decision.", "components": { "ext::sigstore-fulcio": { + "provider": "OpenSSF Sigstore project (public-good instance)", + "website": "https://www.sigstore.dev/", "upstream_offering": "Sigstore public-good instance: Fulcio certificate authority", "upstream_component_id": "https://fulcio.sigstore.dev", "responsibility_split": { "upstream_runs": "The certificate authority that issues short-lived signing certificates bound to the CI run's OIDC identity.", "provider_configures": "Keyless signing in CI (cosign sign-blob), and the certificate identity and OIDC issuer every verification pins." }, - "evidence": [".github/workflows/evidence-nightly.yml (cosign sign-blob; --certificate-identity, --certificate-oidc-issuer)", "scripts/verify-published.sh (--certificate-identity, --certificate-oidc-issuer)"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "Every deploy and nightly signs each published artifact keylessly: cosign obtains a short-lived certificate from Fulcio bound to the workflow's GitHub OIDC identity. No account or configuration exists on Fulcio's side.", + "justification": "Keyless signing removes long-lived signing keys from the pipeline and binds every signature to the exact workflow and commit that produced it, which any reader can verify.", + "mitigations": "Every verification pins the certificate identity (the workflow path and ref) and the OIDC issuer, so a certificate issued to anyone else does not verify. Fulcio sees only the CSR and the OIDC token claims (repository, workflow, ref), never artifact content. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "The post-publish round-trip verify and scripts/verify-published.sh re-verify every signature from outside; a Fulcio outage stops the deploy (fail closed) rather than publishing unsigned evidence.", + "evidence": [ + ".github/workflows/evidence-nightly.yml (cosign sign-blob; --certificate-identity, --certificate-oidc-issuer)", + "scripts/verify-published.sh (--certificate-identity, --certificate-oidc-issuer)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::sigstore-rekor": { + "provider": "OpenSSF Sigstore project (public-good instance)", + "website": "https://www.sigstore.dev/", "upstream_offering": "Sigstore public-good instance: Rekor transparency log", "upstream_component_id": "https://rekor.sigstore.dev", "responsibility_split": { "upstream_runs": "The append-only transparency log and its inclusion proofs.", "provider_configures": "Signing with transparency-log upload (cosign defaults, not disabled) and verification that checks the inclusion proof in each bundle." }, - "evidence": [".github/workflows/evidence-nightly.yml (cosign sign-blob --new-bundle-format)", "scripts/verify-published.sh (cosign verify-blob)"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "Each keyless signature is recorded in Rekor (cosign default, not disabled); the bundle published next to each artifact carries the inclusion proof.", + "justification": "The transparency log makes every signature publicly auditable, so a signature made outside the pipeline would be visible.", + "mitigations": "Rekor receives only the signature, certificate and artifact digest, never artifact content. Verification checks the inclusion proof offline from the bundle. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "Signature verification against the pinned identity does not depend on Rekor being reachable later; the published bundles carry the proofs.", + "evidence": [ + ".github/workflows/evidence-nightly.yml (cosign sign-blob --new-bundle-format)", + "scripts/verify-published.sh (cosign verify-blob)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::github-oidc": { + "provider": "GitHub, Inc.", + "website": "https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect", "upstream_offering": "GitHub Actions OIDC token issuer", "upstream_component_id": "https://token.actions.githubusercontent.com", "responsibility_split": { "upstream_runs": "The token issuer and its signing keys (JWKS).", "provider_configures": "Which workflows may request a token (permissions: id-token: write), the AWS IAM OIDC trust conditions, and the issuer pinned in cosign verification." }, - "evidence": [".github/workflows/deploy-with-opa.yml:105 (id-token: write)", "infrastructure/bootstrap/plan-role.tf, evidence-nightly.tf, main.tf (OIDC trust)", ".github/workflows/evidence-nightly.yml:118 (COSIGN_OIDC_ISSUER)"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "Workflows granted id-token: write obtain per-run identity tokens, which AWS STS exchanges for the deploy, plan and nightly roles and which Fulcio binds into signing certificates.", + "justification": "Workload identity replaces static cloud credentials in CI: there is no long-lived access key to leak.", + "mitigations": "The AWS role trust policies pin the repository and, for the deploy role, the prod environment (reviewer-gated); only named workflows request tokens. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "The deploy needs a human approval in the prod environment before its token can assume the deploy role; role permissions are least-privilege and reviewed in the bootstrap stack.", + "evidence": [ + ".github/workflows/deploy-with-opa.yml:105 (id-token: write)", + "infrastructure/bootstrap/plan-role.tf, evidence-nightly.tf, main.tf (OIDC trust)", + ".github/workflows/evidence-nightly.yml:118 (COSIGN_OIDC_ISSUER)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::github-repo": { + "provider": "GitHub, Inc.", + "website": "https://github.com/sam-aydlette/samaydlette.com", "upstream_offering": "GitHub repository and GitHub Actions", "upstream_component_id": "https://github.com/sam-aydlette/samaydlette.com", "responsibility_split": { "upstream_runs": "Repository hosting, the Actions runners, Dependabot, and secret scanning.", "provider_configures": "Branch protection on main, the workflows and their permissions, the OPA gate, the SCN tag validator, and secret scanning with push protection." }, - "evidence": ["scripts/build-ksi-signal.py (ext::github-repo verification text)", ".github/workflows/"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "Hosts the source of record and runs the CI/CD workflows (deploy, nightly evidence, scans) on GitHub-hosted runners.", + "justification": "The repository is the system of record for infrastructure as code and evidence generation; hosted runners give an ephemeral, reproducible build environment.", + "mitigations": "Branch protection on main, required checks, a reviewer-gated prod environment for every deploy, secret scanning with push protection, and least-privilege workflow permissions. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "Every published artifact is signed under the deploy workflow's pinned identity and re-verified from outside; the hand-applied GitHub settings are checked live on every deploy (scripts/check-manual-settings.py).", + "evidence": [ + "scripts/build-ksi-signal.py (ext::github-repo verification text)", + ".github/workflows/" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::duo-mfa": { - "upstream_offering": null, + "provider": "Cisco Systems, Inc. (Duo)", + "website": "https://duo.com/", + "upstream_offering": "Duo Mobile authenticator app (inferred; see drafted_by)", "upstream_component_id": null, - "responsibility_split": null, - "evidence": ["scripts/build-ksi-signal.py (ext::duo-mfa: tenant identifier intentionally not published)"], - "drafted_by": "Claude (AI-drafted), 2026-11-03; the repository does not show the Duo edition, its identifier, or how it is configured, so nothing is drafted", - "decided_by": null, - "decided_on": null + "responsibility_split": { + "upstream_runs": "The authenticator app that generates the time-based one-time codes (inferred).", + "provider_configures": "Enrollment of the TOTP device as the MFA factor on the AWS root account, the operator IAM user and the GitHub account." + }, + "usage_and_configuration": "Generates the TOTP codes the operator enters as the second factor for the AWS root account, the operator IAM user and the GitHub account (inferred from DEC-025, which records virtual TOTP MFA on root and the operator user, and from the inventory's description of this service).", + "justification": "A second factor on every top-level administrative and privileged account, as IA-2(1) and IA-2(2) require.", + "mitigations": "TOTP seeds stay on the operator's device; no tenant identifier is published. MFA is enabled on every privileged human account. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "The weaker-than-phishing-resistant factor is a recorded decision (DEC-025); CloudTrail records every console sign-in and privileged API call.", + "evidence": [ + "scripts/build-ksi-signal.py (ext::duo-mfa: tenant identifier intentionally not published)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-05. INFERRED: the repository does not show the Duo edition or whether Duo is used only as a TOTP generator; the operator must confirm or correct every field.", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::github-advisory-db": { + "provider": "GitHub, Inc.", + "website": "https://github.com/advisories", "upstream_offering": "GitHub Advisory Database, read through Dependabot alerts", "upstream_component_id": "https://github.com/advisories", "responsibility_split": { "upstream_runs": "The advisory database and the matching of advisories to this repository's dependencies.", "provider_configures": "The fetch of open Dependabot alerts in the deploy and nightly workflows, and how a failed fetch is handled." }, - "evidence": [".github/workflows/evidence-nightly.yml:435 (dependabot/alerts)", ".github/workflows/deploy-with-opa.yml:1399"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "The deploy and the nightly read open Dependabot alerts for this repository, which GitHub matches from the Advisory Database.", + "justification": "An independent source of dependency vulnerabilities alongside the Grype scan.", + "mitigations": "A failed fetch fails the detection gate (G7) rather than reading as zero findings. Only public advisory data is read. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "Findings are corroborated with the Grype scan and CISA KEV; the VDR records each source.", + "evidence": [ + ".github/workflows/evidence-nightly.yml:435 (dependabot/alerts)", + ".github/workflows/deploy-with-opa.yml:1399" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" }, "ext::cisa-kev": { + "provider": "Cybersecurity and Infrastructure Security Agency (CISA)", + "website": "https://www.cisa.gov/known-exploited-vulnerabilities-catalog", "upstream_offering": "CISA Known Exploited Vulnerabilities catalog (JSON feed)", "upstream_component_id": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json", "responsibility_split": { "upstream_runs": "The catalog and its JSON feed.", "provider_configures": "The fetch in the deploy and nightly workflows, and how a failed fetch is handled." }, - "evidence": [".github/workflows/evidence-nightly.yml:447 (KEV_URL)", ".github/workflows/deploy-with-opa.yml:1415"], - "drafted_by": "Claude (AI-drafted), 2026-11-03", - "decided_by": null, - "decided_on": null + "usage_and_configuration": "The deploy and the nightly fetch the KEV JSON feed and mark each finding that appears in it.", + "justification": "The authoritative U.S. government list of vulnerabilities known to be exploited, which drives remediation priority.", + "mitigations": "A failed fetch fails the detection gate (G7). Only public data is read. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "EPSS and the Grype and Dependabot sources still rate findings; the VDR states which feeds it read.", + "evidence": [ + ".github/workflows/evidence-nightly.yml:447 (KEV_URL)", + ".github/workflows/deploy-with-opa.yml:1415" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-03; MAS-CSO-TPR fields and decision fields AI-drafted 2026-11-05 for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" + }, + "ext::first-epss": { + "provider": "FIRST (Forum of Incident Response and Security Teams); file served from epss.cyentia.com", + "website": "https://www.first.org/epss/", + "upstream_offering": "FIRST Exploit Prediction Scoring System, daily scores file", + "upstream_component_id": "https://epss.cyentia.com/epss_scores-current.csv.gz", + "responsibility_split": { + "upstream_runs": "The EPSS model and the daily scores file.", + "provider_configures": "The fetch in scripts/fetch-detection-feeds.sh and how a failed fetch is handled (the detection gate fails)." + }, + "usage_and_configuration": "The deploy and the nightly download the current scores file and attach each finding's exploit probability.", + "justification": "Exploit likelihood is one input to the finding's rating (likely exploitable), alongside KEV.", + "mitigations": "A failed fetch fails the detection gate (G7). Only public data is read. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "KEV membership still marks known exploitation; the rating method is recorded in the VDR.", + "evidence": [ + "scripts/fetch-detection-feeds.sh (EPSS_URL)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-05, for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" + }, + "ext::anchore-grype-db": { + "provider": "Anchore, Inc.", + "website": "https://github.com/anchore/grype", + "upstream_offering": "Grype vulnerability database, distributed by Anchore", + "upstream_component_id": "https://grype.anchore.io/databases", + "responsibility_split": { + "upstream_runs": "Building and publishing the vulnerability database from upstream advisory sources.", + "provider_configures": "The pinned Grype version (GRYPE_VERSION) and the scans of each SBOM in the deploy and the nightly." + }, + "usage_and_configuration": "Grype downloads the current database at scan time and matches every SBOM the pipeline builds against it.", + "justification": "The primary software-composition scan behind the VDR.", + "mitigations": "The Grype version is pinned; Grype checks the database download against the checksum in its published index. Only the SBOMs are scanned, locally; nothing is uploaded. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "Dependabot alerts and CISA KEV are independent sources the VDR corroborates against.", + "evidence": [ + ".github/workflows/evidence-nightly.yml (grype sbom:...)", + ".github/workflows/deploy-with-opa.yml (GRYPE_VERSION)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-05, for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" + }, + "ext::jsdelivr": { + "provider": "jsDelivr", + "website": "https://www.jsdelivr.com/", + "upstream_offering": "jsDelivr open-source CDN, npm endpoint", + "upstream_component_id": "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/", + "responsibility_split": { + "upstream_runs": "Serving the published npm package files over its CDN.", + "provider_configures": "The pinned MediaPipe Tasks Vision version in the app bundle and the CSP script-src and connect-src paths that allow only that package." + }, + "usage_and_configuration": "The Silk Reeling app's browser code loads the MediaPipe Tasks Vision JavaScript and WebAssembly from jsDelivr at the version the bundle pins.", + "justification": "MediaPipe runs pose estimation in the user's browser, so camera frames never leave the device; jsDelivr is the distribution MediaPipe documents.", + "mitigations": "The CSP allows only the pinned package path; camera frames stay in the browser and only pose landmarks reach the app's API. jsDelivr sees the user's IP address and user agent when the file is fetched. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "The app requires Cognito sign-in with TOTP MFA; the API accepts only landmark data and returns scores. Self-hosting the runtime is the further step if a stronger integrity guarantee is needed.", + "evidence": [ + "infrastructure/bootstrap/cloudfront.tf (silk_reeling_mediapipe, CSP script-src)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-05, for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" + }, + "ext::google-cloud-storage": { + "provider": "Google LLC", + "website": "https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker", + "upstream_offering": "Google Cloud Storage, MediaPipe public model bucket", + "upstream_component_id": "https://storage.googleapis.com/mediapipe-models/", + "responsibility_split": { + "upstream_runs": "Hosting and serving the published MediaPipe model files.", + "provider_configures": "The model path the app requests and the CSP connect-src path that allows only the mediapipe-models bucket." + }, + "usage_and_configuration": "The MediaPipe runtime in the user's browser downloads the pose-landmarker model file from Google's public model bucket.", + "justification": "The model Google publishes for MediaPipe pose landmarking; running it in the browser keeps camera frames on the device.", + "mitigations": "The CSP allows only the mediapipe-models path; the model is data loaded by the pinned runtime, not script. Google sees the user's IP address and user agent when the file is fetched. No federal customer data is in this offering; the resource never receives app-user data.", + "compensating_controls": "Pose scores are computed server-side from landmarks only; a tampered model could degrade scores but cannot read data beyond the camera frames already in the browser.", + "evidence": [ + "infrastructure/bootstrap/cloudfront.tf (CSP connect-src)" + ], + "drafted_by": "Claude (AI-drafted), 2026-11-05, for the operator to confirm", + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05" } } } diff --git a/docs/boundary/boundary-classification.json b/docs/boundary/boundary-classification.json index 69d1e17c..7840ed03 100644 --- a/docs/boundary/boundary-classification.json +++ b/docs/boundary/boundary-classification.json @@ -28,7 +28,9 @@ {"key": "operator-mfa", "zone": "external", "label": "Operator MFA", "match": ["ext::duo-mfa"]}, {"key": "vuln-feeds", "zone": "external", "label": "Vulnerability metadata sources", - "match": ["ext::github-advisory-db", "ext::cisa-kev"]} + "match": ["ext::github-advisory-db", "ext::cisa-kev", "ext::first-epss", "ext::anchore-grype-db"]}, + {"key": "app-delivery", "zone": "external", "label": "Code and models the app loads in the user's browser", + "match": ["ext::jsdelivr", "ext::google-cloud-storage"]} ], "declared": [ {"key": "operator", "label": "Operator (dev machine)", "zone": "outside", "kind": "actor", @@ -69,6 +71,40 @@ {"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": "App user → Cognito Hosted UI (sign-in)", "path": [{"declared": "app-users"}, {"component": "aws::identity_provider::silk_reeling"}], + "protocol": "HTTPS 443 (TLS 1.2+)", "auth": "Password + required TOTP MFA; OAuth2 authorization code with PKCE", "encryption": "In transit: TLS; user records at rest encrypted by Cognito", "data": "Sign-in credentials and MFA code in; ID and access tokens out (email address in the user record)"}, + {"id": "M", "label": "App user's browser → jsDelivr (MediaPipe runtime)", "path": [{"declared": "app-users"}, {"component": "ext::jsdelivr"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Anonymous public GET", "encryption": "In transit: TLS", "data": "Pinned MediaPipe JavaScript and WebAssembly in; the request carries the user's IP address and user agent only"}, + {"id": "N", "label": "App user's browser → Google Cloud Storage (pose model)", "path": [{"declared": "app-users"}, {"component": "ext::google-cloud-storage"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Anonymous public GET", "encryption": "In transit: TLS", "data": "Pose-landmarker model file in; the request carries the user's IP address and user agent only"}, + {"id": "O", "label": "Site bucket → access-log bucket (S3 server access logs)", "path": [{"component": "aws::object_store::website"}, {"component": "aws::object_store::logs"}], + "protocol": "AWS-internal (S3 log delivery)", "auth": "Log bucket policy admits only the S3 logging service", "encryption": "At rest: SSE-S3", "data": "Request records for origin reads: requester IP, user agent, key, status"}, + {"id": "P", "label": "CloudTrail → CloudTrail log bucket", "path": [{"component": "aws::audit_log_trail::management"}, {"component": "aws::object_store::cloudtrail"}], + "protocol": "AWS-internal (CloudTrail delivery)", "auth": "Bucket policy admits only CloudTrail for this trail", "encryption": "At rest: SSE-S3; log-file validation on", "data": "Management events: API caller identity, source IP, action, parameters"}, + {"id": "Q", "label": "KSI emitter → its log group", "path": [{"component": "aws::function::opa_compliance"}, {"component": "aws::log_group::opa_compliance"}], + "protocol": "AWS-internal", "auth": "Lambda execution role", "encryption": "At rest: CMK", "data": "Emitter run logs (no customer data)", "note": "Failed asynchronous invocations go to the dead-letter queue (flow R)."}, + {"id": "R", "label": "KSI emitter → dead-letter queue (failed invocations)", "path": [{"component": "aws::function::opa_compliance"}, {"component": "aws::message_queue::compliance_dlq"}], + "protocol": "AWS-internal", "auth": "Lambda execution role (sqs:SendMessage on the queue only)", "encryption": "At rest: SQS-managed server-side encryption", "data": "The failed scheduled event (no customer data); kept 14 days"}, + {"id": "S", "label": "App Lambda → its log group", "path": [{"component": "aws::function::silk_reeling"}, {"component": "aws::log_group::silk_reeling"}], + "protocol": "AWS-internal", "auth": "Lambda execution role", "encryption": "At rest: CMK", "data": "Application logs: request metadata, errors"}, + {"id": "T", "label": "API Gateway → access log group", "path": [{"component": "aws::api_gateway::silk_reeling"}, {"component": "aws::log_group::silk_apigw"}], + "protocol": "AWS-internal", "auth": "Log resource policy admits API Gateway delivery", "encryption": "At rest: CMK", "data": "API access records: request ID, source IP, time, method, route, status, response length"}, + {"id": "U", "label": "Watchdog → its log group", "path": [{"component": "aws::function::evidence_watchdog"}, {"component": "aws::log_group::evidence_watchdog"}], + "protocol": "AWS-internal", "auth": "Lambda execution role", "encryption": "At rest: CMK", "data": "Watchdog run logs (artifact ages; no customer data)"}, + {"id": "V", "label": "Operator → AWS console and APIs (with TOTP MFA)", "path": [{"declared": "operator"}, {"component": "ext::duo-mfa"}, {"component": "aws::iam_group::operators"}], + "protocol": "HTTPS 443 (TLS 1.2+)", "auth": "Password + TOTP MFA (root and the operator IAM user; privileged)", "encryption": "In transit: TLS", "data": "Administrative sign-in and AWS API calls (recorded by CloudTrail, flow P)"}, + {"id": "W", "label": "Deploy and plan → Terraform state bucket", "path": [{"component": "aws::iam_role::deploy"}, {"component": "aws::object_store::tfstate"}], + "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "Deploy and plan roles (GitHub OIDC)", "encryption": "In transit TLS; at rest SSE-S3", "data": "Terraform state (configuration and resource attributes, including secret values)"}, + {"id": "X", "label": "Deploy and plan → state lock table", "path": [{"component": "aws::iam_role::deploy"}, {"component": "aws::kv_table::tflock"}], + "protocol": "HTTPS 443 (TLS 1.2+, SigV4)", "auth": "Deploy and plan roles (GitHub OIDC)", "encryption": "In transit TLS; at rest AWS-owned key", "data": "Lock ID, holder and timestamp only"}, + {"id": "Y1", "label": "Deploy and nightly → GitHub Advisory Database (Dependabot alerts)", "path": [{"component": "ext::github-repo"}, {"component": "ext::github-advisory-db"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Repository token that can read Dependabot alerts", "encryption": "In transit: TLS", "data": "Open dependency alerts in (public advisory data)"}, + {"id": "Y2", "label": "Deploy and nightly → CISA KEV catalog", "path": [{"component": "ext::github-repo"}, {"component": "ext::cisa-kev"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Anonymous public GET", "encryption": "In transit: TLS", "data": "KEV catalog in (public)"}, + {"id": "Y3", "label": "Deploy and nightly → FIRST EPSS scores", "path": [{"component": "ext::github-repo"}, {"component": "ext::first-epss"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Anonymous public GET", "encryption": "In transit: TLS", "data": "EPSS scores file in (public)"}, + {"id": "Y4", "label": "Deploy and nightly → Grype vulnerability database", "path": [{"component": "ext::github-repo"}, {"component": "ext::anchore-grype-db"}], + "protocol": "HTTPS 443 (TLS)", "auth": "Anonymous public GET", "encryption": "In transit: TLS; checksum verified", "data": "Vulnerability database in (public)"} ] } diff --git a/docs/portfolio/service-model.json b/docs/portfolio/service-model.json index 4aeb5726..43412f19 100644 --- a/docs/portfolio/service-model.json +++ b/docs/portfolio/service-model.json @@ -136,6 +136,14 @@ "owner_domain": "silk-reeling", "consumed_by": ["silk-reeling"], "features": ["movement-feedback", "sign-in"] + }, + { + "key": "app-browser-delivery", + "name": "MediaPipe runtime and model the app loads in the browser", + "group": "app-delivery", + "owner_domain": "silk-reeling", + "consumed_by": ["silk-reeling"], + "features": ["movement-feedback"] } ] } diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index 888561ba..dbac1057 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -189,6 +189,17 @@ "signed": true, "signature": ".well-known/policy-index.bundle" }, + { + "path": ".well-known/minimum-assessment-scope.json", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "json", + "field": "generated_at" + }, + "signed": true, + "signature": ".well-known/minimum-assessment-scope.bundle" + }, { "path": ".well-known/security-decision-record.json", "cadence": "deploy", diff --git a/scripts/_tpr.py b/scripts/_tpr.py new file mode 100644 index 00000000..a82f19aa --- /dev/null +++ b/scripts/_tpr.py @@ -0,0 +1,40 @@ +"""Third-party information resources for the CPO (MAS-CSO-TPR). + +The CPO schema's `thirdPartyInformationResources` object, built from the +decided records in data/third-party-components.json. None of these resources is +recorded as FedRAMP certified, so every entry goes under `nonCertified`; this +module never asserts a resource's authorization status. A record without a +decision, or a decided record without a use case, fails closed: the CPO never +lists a resource the operator has not decided. +""" + +import json +from pathlib import Path + +THIRD_PARTY_PATH = Path(__file__).resolve().parent.parent / "data" / "third-party-components.json" + + +def _fail(msg): + raise SystemExit(f"::error::third-party records: {msg} (fail-closed)") + + +def cpo_third_party_information_resources(path=THIRD_PARTY_PATH): + """{"nonCertified": [{"name", "provider", "website"?, "useCase"}]}, one entry + per third-party record, sorted by component ID.""" + try: + recs = json.loads(Path(path).read_text())["components"] + except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc: + _fail(f"cannot read {path} ({type(exc).__name__})") + out = [] + for cid, rec in sorted(recs.items()): + if not (rec.get("decided_by") and rec.get("decided_on")): + _fail(f"{cid} has no decision (decided_by, decided_on)") + use = rec.get("usage_and_configuration") + name = rec.get("upstream_offering") or cid + if not (isinstance(use, str) and use.strip() and rec.get("provider")): + _fail(f"{cid} lacks provider or usage_and_configuration") + entry = {"name": name, "provider": rec["provider"], "useCase": use} + if isinstance(rec.get("website"), str) and rec["website"].startswith("https://"): + entry["website"] = rec["website"] + out.append(entry) + return {"nonCertified": out} diff --git a/scripts/build-ksi-signal.py b/scripts/build-ksi-signal.py index 1d570b1c..e3ff572c 100755 --- a/scripts/build-ksi-signal.py +++ b/scripts/build-ksi-signal.py @@ -1326,6 +1326,9 @@ def build_sbom_components(sbom_path, existing_components=None): THIRD_PARTY_PATH = Path(__file__).resolve().parent.parent / "data" / "third-party-components.json" NOT_RECORDED = "not recorded" TPR_FIELDS = ("upstream_offering", "upstream_component_id", "responsibility_split") +# MAS-CSO-TPR: what FedRAMP requires documented about each third-party +# information resource. A decided record must carry every one. +MAS_TPR_FIELDS = ("usage_and_configuration", "justification", "mitigations", "compensating_controls") def load_third_party_records(path, known_ids): @@ -1347,18 +1350,24 @@ def load_third_party_records(path, known_ids): split = rec.get("responsibility_split") if split is not None and not (isinstance(split, dict) and split.get("upstream_runs") and split.get("provider_configures")): raise SystemExit(f"::error::third-party record for {cid}: responsibility_split needs upstream_runs and provider_configures") + if rec.get("decided_by") and rec.get("decided_on"): + missing = [f for f in MAS_TPR_FIELDS if not (isinstance(rec.get(f), str) and rec[f].strip())] + if missing: + raise SystemExit(f"::error::third-party record for {cid} is decided but lacks {', '.join(missing)} " + "(MAS-CSO-TPR)") return recs def third_party_attributes(rec): """The TPR-1 fields for one component. A record without a decision (decided_by and decided_on) publishes every field as "not recorded".""" + fields = (*TPR_FIELDS, *MAS_TPR_FIELDS) if rec is None: - return {**{f: NOT_RECORDED for f in TPR_FIELDS}, "third_party_record": {"status": "no record"}} + return {**{f: NOT_RECORDED for f in fields}, "third_party_record": {"status": "no record"}} if not (rec.get("decided_by") and rec.get("decided_on")): - return {**{f: NOT_RECORDED for f in TPR_FIELDS}, + return {**{f: NOT_RECORDED for f in fields}, "third_party_record": {"status": "drafted; no decision recorded"}} - out = {f: rec.get(f) or NOT_RECORDED for f in TPR_FIELDS} + out = {f: rec.get(f) or NOT_RECORDED for f in fields} out["third_party_record"] = {"status": "decided", "decided_by": rec["decided_by"], "decided_on": rec["decided_on"]} return out @@ -1437,6 +1446,47 @@ def build_external_components(third_party_path=THIRD_PARTY_PATH): "verification": "U.S. federal government source", "fedramp_status": "external; U.S. federal government source", }, + # MAS-CSO-IIR: the vulnerability-data feeds the VDR build also reads + # (scripts/fetch-detection-feeds.sh, evidence-nightly.yml's grype scan). + { + "id": "ext::first-epss", + "native_id": "https://epss.cyentia.com/epss_scores-current.csv.gz", + "name": "FIRST Exploit Prediction Scoring System (EPSS) scores", + "purpose": "Daily exploit-likelihood scores the VDR uses to rate findings", + "cia_impact": "VDR ingest accuracy", + "verification": "Public feed; a failed fetch fails the detection gate (G7) rather than scoring with no data", + "fedramp_status": "external; no separate FedRAMP authorization", + }, + { + "id": "ext::anchore-grype-db", + "native_id": "https://grype.anchore.io/databases", + "name": "Grype vulnerability database (Anchore)", + "purpose": "The vulnerability database Grype matches the SBOMs against on every deploy and nightly scan", + "cia_impact": "VDR ingest accuracy", + "verification": "Grype verifies the database checksum on download; findings are corroborated against Dependabot and CISA KEV", + "fedramp_status": "external; no separate FedRAMP authorization", + }, + # MAS-CSO-IIR: origins the Silk Reeling app loads code or data from in the + # user's browser, next to the camera feed (the app's CSP in + # infrastructure/bootstrap/cloudfront.tf allows exactly these). + { + "id": "ext::jsdelivr", + "native_id": "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/", + "name": "jsDelivr CDN (MediaPipe Tasks Vision runtime)", + "purpose": "Serves the MediaPipe pose-estimation JavaScript and WebAssembly the app runs in the browser", + "cia_impact": "code executed next to the camera feed in the user's browser", + "verification": "Version pinned in the app bundle and in the CSP script-src path; the CSP allows no other jsDelivr path", + "fedramp_status": "external; no separate FedRAMP authorization", + }, + { + "id": "ext::google-cloud-storage", + "native_id": "https://storage.googleapis.com/mediapipe-models/", + "name": "Google Cloud Storage (MediaPipe model bucket)", + "purpose": "Serves the pose-landmarker model file the MediaPipe runtime loads in the browser", + "cia_impact": "model integrity for the pose scores the app computes", + "verification": "CSP connect-src limited to the mediapipe-models path; the model runs in the browser and returns landmarks only", + "fedramp_status": "external; no separate FedRAMP authorization", + }, ] tpr = load_third_party_records(third_party_path, {s["id"] for s in services}) components = [] @@ -1595,7 +1645,8 @@ def build_validations(validations_doc, components): "dns_zone", "tls_certificate", "secrets_manager", "identity_provider", "kms_key"}, "IAM": {"iam_role", "iam_policy", "iam_group", "oidc_provider", "identity_provider", "secrets_manager"}, "INR": {"log_group", "function", "notification_topic", "metric_alarm"}, - "MLA": {"log_group", "function", "cdn_distribution", "notification_topic", "metric_alarm", "message_queue"}, + "MLA": {"log_group", "function", "cdn_distribution", "notification_topic", "metric_alarm", "message_queue", + "audit_log_trail"}, "PIY": None, # policy & inventory — whole inventory is the evidence "RPL": {"object_store"}, "SCR": {"npm_package", "pypi_package", "external_service"}, diff --git a/scripts/build-mas.py b/scripts/build-mas.py new file mode 100644 index 00000000..b18f6b87 --- /dev/null +++ b/scripts/build-mas.py @@ -0,0 +1,424 @@ +#!/usr/bin/env python3 +"""The Minimum Assessment Scope, generated: /.well-known/minimum-assessment-scope.json. + +One machine-readable view of the cloud service offering's scope, joined from +what the pipeline already holds, so it cannot drift from it: + + MAS-CSO-IIR the information resources: the canonical inventory (ksi-signal.json), + plus every off-origin host the site's and app's Content Security + Policies allow (infrastructure/bootstrap/cloudfront.tf), each placed + on an inventoried component or put out of scope with a reason. + MAS-CSO-FLO the information flows (docs/boundary/boundary-classification.json) + resolved against the inventory, each with a security category + derived from its endpoints (the high-water mark of their FIPS 199 + categories); every external service and every data store is in at + least one flow. + MAS-CSO-MDI the metadata inventory: every data store and log in the inventory, + what it holds, which personal data, retention and location + (data/minimum-assessment-scope.json supplies the meaning). + MAS-CSO-TPR each third-party information resource with the four fields FedRAMP + requires (data/third-party-components.json, decided records only). + FRC-CSX-MAS how every KSI applies to the scope: per component through the KSI's + evidence domain, or over the whole set. + +Fails closed: any gap above stops the build, and so the deploy, before the SDR +is built. No ARN, account ID or address is published: components are named by +their inventory IDs. +""" + +import argparse +import fnmatch +import json +import re +import sys +from datetime import datetime, timezone +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent +INPUTS = REPO / "data" / "minimum-assessment-scope.json" +THIRD_PARTY = REPO / "data" / "third-party-components.json" +CLASSIFICATION = REPO / "docs" / "boundary" / "boundary-classification.json" +CLOUDFRONT_TF = REPO / "infrastructure" / "bootstrap" / "cloudfront.tf" +BOOTSTRAP_DIR = REPO / "infrastructure" / "bootstrap" +SCHEMA = "minimum-assessment-scope/1" +LEVELS = ("low", "moderate", "high") +OBJECTIVES = ("confidentiality", "integrity", "availability") +TPR_FIELDS = ("usage_and_configuration", "justification", "mitigations", "compensating_controls") +PACKAGE_TYPES = ("npm_package", "pypi_package") +CODE = { + "builder": "scripts/build-mas.py", + "inventory": "scripts/build-ksi-signal.py", + "inputs": "data/minimum-assessment-scope.json", + "flows": "docs/boundary/boundary-classification.json", + "third_party": "data/third-party-components.json", + "csp": "infrastructure/bootstrap/cloudfront.tf", +} +DERIVATION = ( + "Generated on every deploy by scripts/build-mas.py from this build's canonical inventory " + "(ksi-signal.json, itself derived from Terraform state, the SBOMs, the site's HTML and the declared " + "external services), the boundary classification's data-flow table, the operator's metadata and " + "off-origin placements (data/minimum-assessment-scope.json) and the third-party records " + "(data/third-party-components.json). Information resources are the inventory's components; the " + "Content Security Policies the edge serves are parsed for every off-origin host, and each must be an " + "inventoried component or out of scope with a stated reason. Each flow is resolved against the inventory " + "and given the high-water mark of its endpoints' security categories. Every data store and log in the " + "inventory must have a metadata entry, every external service and data store must be in a flow, every " + "third-party resource must carry a decided record with the four MAS-CSO-TPR fields, and every component " + "type must fall in at least one KSI's evidence domain or carry a whole-set reason. Any gap fails the " + "build, so the deploy never publishes a scope with one." +) + + +def _fail(msg): + raise SystemExit(f"::error::MAS: {msg} (fail-closed)") + + +# --- MAS-CSO-IIR: off-origin hosts from the CSPs --------------------------------------- + +_URL = re.compile(r"https://([A-Za-z0-9.${}_-]+)") +_LOCAL = re.compile(r"\$\{local\.([A-Za-z0-9_]+)\}") +_VAR = re.compile(r"\$\{var\.([A-Za-z0-9_]+)\}") + + +def _locals(text): + """{name: definition text} for every `name = ...` in a locals block (to the + next blank line, enough for this repository's style).""" + out = {} + for block in re.finditer(r"locals\s*\{(.*?)\n\}", text, re.S): + body = block.group(1) + for m in re.finditer(r"^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)(?=^\s*[A-Za-z0-9_]+\s*=|\Z)", body, re.S | re.M): + v = m.group(2).strip() + q = re.match(r'^"([^"\n]*)"', v) # a plain string local: its content, without the quotes + out[m.group(1)] = q.group(1) if q else v + return out + + +def _var_defaults(text): + return {m.group(1): m.group(2) for m in re.finditer( + r'variable\s+"([A-Za-z0-9_]+)"\s*\{[^}]*?default\s*=\s*"([^"]*)"', text, re.S)} + + +def _expand(s, locals_, vars_, depth=0): + if depth > 5: + _fail("CSP expansion does not terminate") + s = _VAR.sub(lambda m: vars_.get(m.group(1), m.group(0)), s) + if "domain_name" in vars_: + s = s.replace("${local.domain_dashed}", vars_["domain_name"].replace(".", "-")) + return _LOCAL.sub(lambda m: _expand(locals_.get(m.group(1), m.group(0)), locals_, vars_, depth + 1), s) + + +def csp_hosts(tf_text, context_text=""): + """Every host an https:// source in a content_security_policy names, with + ${local.*} and ${var.*} references expanded from the same configuration.""" + whole = tf_text + "\n" + context_text + locals_, vars_ = _locals(whole), _var_defaults(whole) + hosts = set() + for m in re.finditer(r"content_security_policy\s*=\s*join\(\s*\"; \",\s*\[(.*?)\]\s*\)", tf_text, re.S): + expanded = _expand(m.group(1), locals_, vars_) + # Every https:// source must yield a host: one that does not would be a + # host this check silently missed. + if expanded.count("https://") != len(_URL.findall(expanded)): + _fail("a CSP https:// source does not resolve to a host") + for h in _URL.findall(expanded): + if "$" in h or "{" in h or "}" in h: + _fail(f"cannot resolve the CSP source host {h!r}") + hosts.add(h.lower()) + return sorted(hosts) + + +def place_hosts(hosts, placements, component_ids): + """[(host, placement)] for every host; fails on a host placed nowhere, on a + placement naming a component the inventory lacks, or with no reason.""" + out, problems = [], [] + for h in hosts: + p = placements.get(h) + if not isinstance(p, dict): + problems.append(f"the CSP allows {h}, which is neither an inventoried information resource nor " + "out of scope with a reason (data/minimum-assessment-scope.json off_origin_hosts)") + continue + if p.get("component"): + if p["component"] not in component_ids: + problems.append(f"{h} is placed on {p['component']}, which is not in the inventory") + out.append({"host": h, "component": p["component"]}) + elif isinstance(p.get("out_of_scope"), str) and p["out_of_scope"].strip(): + out.append({"host": h, "out_of_scope": p["out_of_scope"]}) + else: + problems.append(f"{h} has neither a component nor an out_of_scope reason") + return out, problems + + +# --- MAS-CSO-FLO ------------------------------------------------------------------------- + +def _match(pattern, ids): + return sorted(i for i in ids if fnmatch.fnmatchcase(i, pattern)) + + +def _high_water(categories): + out = {} + for o in OBJECTIVES: + vals = [c.get(o) for c in categories if c.get(o) in LEVELS] + if vals: + out[o] = max(vals, key=LEVELS.index) + return out + + +def flows(classification, components, data_store_types): + by_id = {c["component_id"]: c for c in components} + ids = sorted(by_id) + declared = {d["key"] for d in classification.get("declared", [])} + out, problems, covered = [], [], set() + for f in classification.get("flows", []): + endpoints = [] + for ref in f["path"]: + if "declared" in ref: + if ref["declared"] not in declared: + problems.append(f"flow {f['id']} names an undeclared actor {ref['declared']}") + endpoints.append({"declared": ref["declared"]}) + continue + hit = _match(ref["component"], ids) + if not hit: + problems.append(f"flow {f['id']} endpoint {ref['component']} matches no inventoried component") + covered.update(hit) + endpoints.append({"components": hit}) + cats = [by_id[i].get("security_category") or {} for e in endpoints for i in e.get("components", [])] + category = _high_water(cats) + if len(category) != len(OBJECTIVES): + problems.append(f"flow {f['id']} has no endpoint with a security category") + out.append({"id": f["id"], "label": f["label"], "endpoints": endpoints, "security_category": category, + **{k: f[k] for k in ("protocol", "auth", "encryption", "data", "note") if f.get(k)}}) + must = sorted(i for i, c in by_id.items() if c.get("type") == "external_service" or c.get("type") in data_store_types) + for i in must: + if i not in covered: + problems.append(f"{i} ({by_id[i].get('type')}) is in no information flow") + return out, problems + + +# --- MAS-CSO-MDI ------------------------------------------------------------------------- + +def metadata_inventory(components, metadata, data_store_types): + out, problems = [], [] + keys = list(metadata) + for c in sorted(components, key=lambda c: c["component_id"]): + cid, ctype = c["component_id"], c.get("type") + third_party_observed = cid in metadata and ctype == "external_service" + if ctype not in data_store_types and not third_party_observed: + continue + key = cid if cid in metadata else next((k for k in keys if fnmatch.fnmatchcase(cid, k)), None) + if key is None: + problems.append(f"{cid} ({ctype}) holds data or logs but has no metadata entry " + "(data/minimum-assessment-scope.json metadata)") + continue + m = metadata[key] + if not (isinstance(m.get("holds"), str) and isinstance(m.get("personal_data"), list) + and isinstance(m.get("retention"), str)): + problems.append(f"metadata entry {key} needs holds, personal_data and retention") + continue + attrs = c.get("attributes") or {} + entry = {"component": cid, "type": ctype, "holds": m["holds"], "personal_data": m["personal_data"], + "retention": m["retention"], + "location": attrs.get("region") or ("third party" if ctype == "external_service" else "not recorded"), + "controlled_by": "third party" if ctype == "external_service" else "provider"} + if "retention_days" in m: + entry["retention_days"] = m["retention_days"] + out.append(entry) + return out, problems + + +# --- MAS-CSO-TPR ------------------------------------------------------------------------- + +def third_party(components, tpr_doc): + recs = (tpr_doc or {}).get("components") or {} + out, problems = [], [] + for c in sorted(components, key=lambda c: c["component_id"]): + if c.get("type") != "external_service": + continue + cid, rec = c["component_id"], recs.get(c["component_id"]) + if not rec: + problems.append(f"{cid} has no third-party record (data/third-party-components.json)") + continue + if not (rec.get("decided_by") and rec.get("decided_on")): + problems.append(f"{cid}'s third-party record has no decision (decided_by, decided_on)") + continue + missing = [f for f in TPR_FIELDS if not (isinstance(rec.get(f), str) and rec[f].strip())] + if missing: + problems.append(f"{cid}'s third-party record lacks {', '.join(missing)}") + continue + attrs = c.get("attributes") or {} + out.append({"component": cid, "name": attrs.get("name") or cid, "provider": rec.get("provider"), + "website": rec.get("website"), "upstream_offering": rec.get("upstream_offering"), + **{f: rec[f] for f in TPR_FIELDS}, + "decided_by": rec["decided_by"], "decided_on": rec["decided_on"]}) + return out, problems + + +# --- FRC-CSX-MAS ------------------------------------------------------------------------- + +def ksi_application(signal, whole_set_types): + """Per KSI: the components its evidence domain covers, or the whole set. + A KSI whose evidence is every component (or none, a documentation KSI) + applies over the whole set; the rest apply per component.""" + comps = [c for c in signal.get("components", [])] + all_ids = {c["component_id"] for c in comps} + type_of = {c["component_id"]: c.get("type") for c in comps} + out, domain_types = [], set() + for k in signal.get("ksis", []): + refs = set((k.get("evidence") or {}).get("component_refs") or []) + whole = not refs or refs >= all_ids + if not whole: + domain_types.update(type_of[r] for r in refs if r in type_of) + out.append({"ksi": k["id"], "method": k.get("method"), "status": k.get("status"), + "applies_to": "whole set" if whole else "per component", + "components": len(all_ids) if whole else len(refs & all_ids), + "component_types": sorted({type_of[r] for r in (all_ids if whole else refs & all_ids)})}) + problems = [] + if not out: + problems.append("the inventory carries no KSIs") + for t in sorted({type_of[i] for i in all_ids}): + if t not in domain_types and not (isinstance(whole_set_types.get(t), str) and whole_set_types[t].strip()): + problems.append(f"component type {t} is in no KSI's per-component evidence domain and has no whole-set " + "reason (data/minimum-assessment-scope.json whole_set_types)") + per_type = {t: ("per component" if t in domain_types else f"whole set only: {whole_set_types[t]}") + for t in sorted({type_of[i] for i in all_ids}) if t in domain_types or t in whole_set_types} + return out, per_type, problems + + +# --- build ------------------------------------------------------------------------------- + +def build(signal, inputs, classification, tpr_doc, cloudfront_tf, bootstrap_context, commit, now): + comps = signal.get("components", []) + ids = {c["component_id"] for c in comps} + dst = set(inputs.get("data_store_types") or []) + hosts, p1 = place_hosts(csp_hosts(cloudfront_tf, bootstrap_context), inputs.get("off_origin_hosts") or {}, ids) + fl, p2 = flows(classification, comps, dst) + md, p3 = metadata_inventory(comps, inputs.get("metadata") or {}, dst) + tp, p4 = third_party(comps, tpr_doc) + ka, per_type, p5 = ksi_application(signal, inputs.get("whole_set_types") or {}) + problems = p1 + p2 + p3 + p4 + p5 + by_type = {} + for c in comps: + by_type[c.get("type")] = by_type.get(c.get("type"), 0) + 1 + resources = [{"component": c["component_id"], "type": c.get("type"), + "security_category": c.get("security_category"), + "function": (c.get("attributes") or {}).get("function")} + for c in sorted(comps, key=lambda c: c["component_id"]) if c.get("type") not in PACKAGE_TYPES] + doc = { + "schema": SCHEMA, + "generated_at": now, + "commit": commit, + "ksi_signal_id": signal.get("signal_id"), + "derivation": DERIVATION, + "code": CODE, + "information_resources": { + "total": len(comps), + "by_type": dict(sorted(by_type.items())), + "software_packages": sum(by_type.get(t, 0) for t in PACKAGE_TYPES), + "resources": resources, + "off_origin_hosts": hosts, + }, + "flows": fl, + "metadata_inventory": md, + "third_party_information_resources": tp, + "ksi_application": {"ksis": ka, "component_types": per_type}, + "checks": { + "off_origin_hosts_placed": not p1, + "every_external_service_and_data_store_in_a_flow": not p2, + "every_data_store_and_log_has_metadata": not p3, + "every_third_party_resource_decided_with_all_fields": not p4, + "every_component_type_in_a_ksi_domain": not p5, + }, + } + return doc, problems + + +def render_markdown(d): + ir = d["information_resources"] + out = ["# Minimum Assessment Scope", "", + f"_Generated {d['generated_at']} from inventory `{d['ksi_signal_id']}` at commit `{(d['commit'] or '')[:12]}`._", + "", "## How this is derived", "", d["derivation"], "", + "Code: " + ", ".join(f"`{v}`" for v in d["code"].values()), "", + "## Information resources (MAS-CSO-IIR)", "", + f"{ir['total']} inventoried components, {ir['software_packages']} of them software packages.", "", + "| Type | Count |", "|---|---|", *[f"| {t} | {n} |" for t, n in ir["by_type"].items()], "", + "| Component | Type | C/I/A | Function |", "|---|---|---|---|"] + for r in ir["resources"]: + sc = r.get("security_category") or {} + out.append(f"| `{r['component']}` | {r['type']} | {'/'.join(sc.get(o, '?') for o in OBJECTIVES)} | " + f"{(r.get('function') or '').replace('|', '/')} |") + out += ["", "Off-origin hosts the Content Security Policies allow:", "", + "| Host | Placement |", "|---|---|"] + for h in ir["off_origin_hosts"]: + out.append(f"| {h['host']} | " + (f"`{h['component']}`" if h.get("component") else f"Out of scope: {h['out_of_scope']}") + " |") + out += ["", "## Information flows and security categories (MAS-CSO-FLO)", "", + "| Flow | Endpoints | C/I/A | Protocol | Auth | Encryption | Data |", "|---|---|---|---|---|---|---|"] + for f in d["flows"]: + ends = " → ".join(e.get("declared") or ", ".join(e["components"]) or "(none)" for e in f["endpoints"]) + sc = f["security_category"] + out.append(f"| {f['id']}: {f['label']} | {ends} | {'/'.join(sc.get(o, '?') for o in OBJECTIVES)} | " + f"{f.get('protocol', '')} | {f.get('auth', '')} | {f.get('encryption', '')} | {f.get('data', '')} |") + out += ["", "## Metadata inventory (MAS-CSO-MDI)", "", + "| Component | Holds | Personal data | Retention | Location |", "|---|---|---|---|---|"] + for m in d["metadata_inventory"]: + out.append(f"| `{m['component']}` | {m['holds']} | {', '.join(m['personal_data']) or 'none'} | " + f"{m['retention']} | {m['location']} ({m['controlled_by']}) |") + out += ["", "## Third-party information resources (MAS-CSO-TPR)", ""] + for t in d["third_party_information_resources"]: + out += [f"### {t['name']} (`{t['component']}`)", "", + f"- **Provider:** {t['provider']} ({t['website']})", + f"- **General usage and configuration:** {t['usage_and_configuration']}", + f"- **Justification for use:** {t['justification']}", + f"- **Mitigation measures:** {t['mitigations']}", + f"- **Compensating controls:** {t['compensating_controls']}", + f"- **Decided by:** {t['decided_by']}, {t['decided_on']}", ""] + out += ["## Key Security Indicators applied to the scope (FRC-CSX-MAS)", "", + "| KSI | Method | Applies | Components | Types |", "|---|---|---|---|---|"] + for k in d["ksi_application"]["ksis"]: + out.append(f"| {k['ksi']} | {k['method']} | {k['applies_to']} | {k['components']} | {', '.join(k['component_types'])} |") + out += ["", "| Component type | Coverage |", "|---|---|", + *[f"| {t} | {v} |" for t, v in d["ksi_application"]["component_types"].items()], + "", "## Checks", "", *[f"- {k}: {'pass' if v else 'FAIL'}" for k, v in d["checks"].items()], + "", "---", "_Source of truth: the signed `minimum-assessment-scope.json`._"] + return "\n".join(out) + + +def _read_json(path, what): + try: + return json.loads(Path(path).read_text()) + except (OSError, json.JSONDecodeError) as exc: + _fail(f"cannot read {what} {path} ({type(exc).__name__})") + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--ksi-signal", default="ksi-signal.json") + ap.add_argument("--inputs", default=str(INPUTS)) + ap.add_argument("--classification", default=str(CLASSIFICATION)) + ap.add_argument("--third-party", default=str(THIRD_PARTY)) + ap.add_argument("--cloudfront-tf", default=str(CLOUDFRONT_TF)) + ap.add_argument("--commit", default="") + ap.add_argument("--output", default="minimum-assessment-scope.json") + ap.add_argument("--md-output", default="minimum-assessment-scope.md") + a = ap.parse_args(argv) + signal = _read_json(a.ksi_signal, "the KSI signal") + inputs = _read_json(a.inputs, "the MAS inputs") + if inputs.get("schema") != "mas-inputs/1": + _fail(f"{a.inputs} is not a mas-inputs/1 document") + tf = Path(a.cloudfront_tf).read_text() + context = "\n".join(p.read_text() for p in sorted(Path(a.cloudfront_tf).parent.glob("*.tf"))) + doc, problems = build(signal, inputs, _read_json(a.classification, "the classification"), + _read_json(a.third_party, "the third-party records"), tf, context, a.commit, + datetime.now(timezone.utc).isoformat()) + if problems: + for p in problems: + print(f"::error::MAS: {p}") + _fail(f"{len(problems)} gap(s) in the Minimum Assessment Scope") + Path(a.output).write_text(json.dumps(doc, indent=2) + "\n") + if a.md_output: + Path(a.md_output).write_text(render_markdown(doc) + "\n") + print(f"minimum-assessment-scope: {doc['information_resources']['total']} components, {len(doc['flows'])} flows, " + f"{len(doc['metadata_inventory'])} metadata entries, {len(doc['third_party_information_resources'])} " + f"third-party records, {len(doc['ksi_application']['ksis'])} KSIs applied") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/mas/classification-gaps.json b/tests/fixtures/mas/classification-gaps.json new file mode 100644 index 00000000..88f5f34a --- /dev/null +++ b/tests/fixtures/mas/classification-gaps.json @@ -0,0 +1,6 @@ +{"_note": "Known-bad: flow X names a component the inventory does not have; the log group is in no flow.", + "declared": [{"key": "operator", "label": "Operator", "zone": "outside", "kind": "actor"}], + "flows": [ + {"id": "X", "label": "Operator → a ghost", "path": [{"declared": "operator"}, {"component": "aws::function::ghost"}]}, + {"id": "Y", "label": "Operator → app", "path": [{"declared": "operator"}, {"component": "aws::function::app"}]} + ]} diff --git a/tests/fixtures/mas/csp-unplaced.tf.fixture b/tests/fixtures/mas/csp-unplaced.tf.fixture new file mode 100644 index 00000000..cea2fdf6 --- /dev/null +++ b/tests/fixtures/mas/csp-unplaced.tf.fixture @@ -0,0 +1,11 @@ +# Known-bad: the CSP allows a host no placement covers (MAS-CSO-IIR). +resource "aws_cloudfront_response_headers_policy" "bad" { + security_headers_config { + content_security_policy { + content_security_policy = join("; ", [ + "default-src 'self'", + "script-src 'self' https://cdn.jsdelivr.net/npm/x/ https://unvetted-cdn.example.com/lib.js", + ]) + } + } +} diff --git a/tests/fixtures/mas/csp-unresolved.tf.fixture b/tests/fixtures/mas/csp-unresolved.tf.fixture new file mode 100644 index 00000000..9d2c987f --- /dev/null +++ b/tests/fixtures/mas/csp-unresolved.tf.fixture @@ -0,0 +1,11 @@ +# Known-bad: a CSP source names a local that is not defined, so its host cannot +# be known; the check must fail rather than skip it. +resource "aws_cloudfront_response_headers_policy" "bad" { + security_headers_config { + content_security_policy { + content_security_policy = join("; ", [ + "connect-src 'self' https://${local.not_defined_anywhere}", + ]) + } + } +} diff --git a/tests/fixtures/mas/signal-gaps.json b/tests/fixtures/mas/signal-gaps.json new file mode 100644 index 00000000..0fae7196 --- /dev/null +++ b/tests/fixtures/mas/signal-gaps.json @@ -0,0 +1,11 @@ +{"_note": "Known-bad: a log group with no metadata entry and in no flow, and a component type in no KSI's evidence domain with no whole-set reason.", + "signal_id": "fixture-gaps", + "components": [ + {"component_id": "aws::log_group::brand_new", "type": "log_group", "security_category": {"confidentiality": "low", "integrity": "moderate", "availability": "low"}, "attributes": {"region": "us-east-2"}}, + {"component_id": "aws::mystery::thing", "type": "mystery", "security_category": {"confidentiality": "low", "integrity": "low", "availability": "low"}, "attributes": {}}, + {"component_id": "aws::function::app", "type": "function", "security_category": {"confidentiality": "moderate", "integrity": "moderate", "availability": "low"}, "attributes": {}} + ], + "ksis": [ + {"id": "KSI-AAA-ONE", "method": "policy-validation", "status": "pass", "evidence": {"component_refs": ["aws::function::app", "aws::log_group::brand_new"]}}, + {"id": "KSI-PIY-ALL", "method": "inventory-attestation", "status": "pass", "evidence": {"component_refs": ["aws::function::app", "aws::log_group::brand_new", "aws::mystery::thing"]}} + ]} diff --git a/tests/fixtures/mas/signal.json b/tests/fixtures/mas/signal.json new file mode 100644 index 00000000..c591642d --- /dev/null +++ b/tests/fixtures/mas/signal.json @@ -0,0 +1,2254 @@ +{ + "_note": "test fixture: the non-package components of the 2026-11-05 inventory plus the external services this change adds, attributes trimmed; one package and one page keep their types represented", + "signal_id": "fixture", + "components": [ + { + "component_id": "aws::tls_certificate::website", + "type": "tls_certificate", + "security_category": { + "confidentiality": "not-applicable", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-1", + "function": "Public TLS certificate for the CDN" + } + }, + { + "component_id": "aws::cdn_distribution::website", + "type": "cdn_distribution", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Public content delivery (TLS 1.2+, OAC to origin)" + } + }, + { + "component_id": "aws::dns_zone::website", + "type": "dns_zone", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Authoritative DNS for the public domain" + } + }, + { + "component_id": "aws::object_store::website", + "type": "object_store", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Origin storage for static site content and /.well-known/ artifacts" + } + }, + { + "component_id": "aws::api_gateway::silk_reeling", + "type": "api_gateway", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "HTTP API fronting the Silk Reeling app Lambda (TLS termination, request routing, throttling)" + } + }, + { + "component_id": "aws::audit_log_trail::management", + "type": "audit_log_trail", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Account-wide management-event audit (CloudTrail)" + } + }, + { + "component_id": "aws::event_schedule::evidence_watchdog", + "type": "event_schedule", + "security_category": { + "confidentiality": "not-applicable", + "integrity": "low", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Hourly trigger for the evidence SLA watchdog Lambda" + } + }, + { + "component_id": "aws::event_schedule::opa_compliance", + "type": "event_schedule", + "security_category": { + "confidentiality": "not-applicable", + "integrity": "low", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Daily trigger for the runtime KSI emitter Lambda" + } + }, + { + "component_id": "aws::log_group::evidence_watchdog", + "type": "log_group", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "CloudWatch log group for Lambda execution / Route 53 query logs" + } + }, + { + "component_id": "aws::log_group::opa_compliance", + "type": "log_group", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "CloudWatch log group for Lambda execution / Route 53 query logs" + } + }, + { + "component_id": "aws::log_group::silk_apigw", + "type": "log_group", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "CloudWatch log group for the Silk Reeling API Gateway access logs" + } + }, + { + "component_id": "aws::log_group::silk_reeling", + "type": "log_group", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "CloudWatch log group for Lambda execution / Route 53 query logs" + } + }, + { + "component_id": "aws::metric_alarm::evidence[artifact-stale]", + "type": "metric_alarm", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Evidence SLA alarm on a watchdog metric (VDR age, runtime-signal age, nightly result)" + } + }, + { + "component_id": "aws::metric_alarm::evidence[nightly-failed]", + "type": "metric_alarm", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Evidence SLA alarm on a watchdog metric (VDR age, runtime-signal age, nightly result)" + } + }, + { + "component_id": "aws::metric_alarm::evidence[runtime-age]", + "type": "metric_alarm", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Evidence SLA alarm on a watchdog metric (VDR age, runtime-signal age, nightly result)" + } + }, + { + "component_id": "aws::metric_alarm::evidence[vdr-age]", + "type": "metric_alarm", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Evidence SLA alarm on a watchdog metric (VDR age, runtime-signal age, nightly result)" + } + }, + { + "component_id": "aws::identity_provider::silk_reeling", + "type": "identity_provider", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Cognito user pool gating the Silk Reeling app (admin-create users, required TOTP MFA, OAuth2 PKCE Hosted UI; issues the JWTs the API Gateway authorizer validates)" + } + }, + { + "component_id": "aws::iam_role::evidence_watchdog", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "IAM role assumed by the evidence SLA watchdog Lambda" + } + }, + { + "component_id": "aws::iam_role::lambda_opa", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "IAM role assumed by the runtime KSI emitter Lambda" + } + }, + { + "component_id": "aws::iam_role::silk_reeling", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "IAM role assumed by the Silk Reeling app Lambda" + } + }, + { + "component_id": "aws::iam_policy::evidence_watchdog", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role samaydlette-com-evidence-watchdog-role" + } + }, + { + "component_id": "aws::iam_policy::lambda_opa", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role samaydlette-com-lambda-opa-role" + } + }, + { + "component_id": "aws::iam_policy::silk_reeling", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role samaydlette-com-silk-reeling-role" + } + }, + { + "component_id": "aws::kms_key::at_rest", + "type": "kms_key", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Customer-managed KMS key for at-rest encryption / asymmetric signing" + } + }, + { + "component_id": "aws::kms_key::dnssec_ksk", + "type": "kms_key", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-1", + "function": "Customer-managed KMS key for at-rest encryption / asymmetric signing" + } + }, + { + "component_id": "aws::kms_key::runtime_signing", + "type": "kms_key", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Customer-managed KMS key for at-rest encryption / asymmetric signing" + } + }, + { + "component_id": "aws::kms_key::silk_reeling", + "type": "kms_key", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Customer-managed KMS key for at-rest encryption / asymmetric signing" + } + }, + { + "component_id": "aws::function::evidence_watchdog", + "type": "function", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Hourly evidence SLA watchdog; publishes evidence-age and nightly-result metrics for the alarms" + } + }, + { + "component_id": "aws::function::opa_compliance", + "type": "function", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Daily runtime KSI emitter; revalidates live AWS configuration" + } + }, + { + "component_id": "aws::function::silk_reeling", + "type": "function", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Silk Reeling Mirror application backend (Cognito-gated Tai Chi coaching API)" + } + }, + { + "component_id": "aws::object_store::cloudtrail", + "type": "object_store", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Delivery bucket for the account's CloudTrail management-event trail" + } + }, + { + "component_id": "aws::object_store::logs", + "type": "object_store", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Access-log bucket for the site bucket and CDN" + } + }, + { + "component_id": "aws::notification_topic::evidence_alerts", + "type": "notification_topic", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Evidence-alert topic: delivers CloudWatch alarm state changes to the operator by email" + } + }, + { + "component_id": "aws::message_queue::compliance_dlq", + "type": "message_queue", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Dead-letter queue for failed asynchronous invocations of the compliance and watchdog Lambdas" + } + }, + { + "component_id": "aws::kv_table::tflock", + "type": "kv_table", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Terraform state lock for the application and bootstrap stacks (one lock item per run; no state contents)" + } + }, + { + "component_id": "aws::iam_group::operators", + "type": "iam_group", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "IAM group for the human operator(s); holds IAM administration privileges (POAM-026)" + } + }, + { + "component_id": "aws::iam_group::read_only", + "type": "iam_group", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "IAM group granting read-only access (ReadOnlyAccess, with denies on secret values and CMK decryption)" + } + }, + { + "component_id": "aws::oidc_provider::github", + "type": "oidc_provider", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "GitHub Actions OIDC identity provider trusted by the CI/CD deploy role (workload identity; replaced long-lived keys per POAM-001)" + } + }, + { + "component_id": "aws::iam_role::deploy", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "CI deploy role (reviewer-gated prod environment)" + } + }, + { + "component_id": "aws::iam_role::evidence_nightly", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Nightly evidence workflow role" + } + }, + { + "component_id": "aws::iam_role::plan", + "type": "iam_role", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Read-only plan role for pull-request and main-branch checks" + } + }, + { + "component_id": "aws::iam_policy::cloudtrail_management", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::cognito_management", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::compliance_dlq", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::compliance_kms", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::compliance_logs", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::dnssec_management", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::evidence_nightly_cdn", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-evidence-nightly-oidc" + } + }, + { + "component_id": "aws::iam_policy::evidence_nightly_publish", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-evidence-nightly-oidc" + } + }, + { + "component_id": "aws::iam_policy::evidence_nightly_reconcile_reads", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-evidence-nightly-oidc" + } + }, + { + "component_id": "aws::iam_policy::evidence_watchdog_management", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::log_bucket_management", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::plan_access", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-plan-oidc" + } + }, + { + "component_id": "aws::iam_policy::reconcile_reads", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::iam_policy::tfstate_backend", + "type": "iam_policy", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Inline policy on role github-actions-deploy-oidc" + } + }, + { + "component_id": "aws::object_store::tfstate", + "type": "object_store", + "security_category": { + "confidentiality": "moderate", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "region": "us-east-2", + "function": "Remote Terraform state for the application and bootstrap stacks" + } + }, + { + "component_id": "ext::sigstore-fulcio", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "Sigstore Fulcio" + } + }, + { + "component_id": "ext::sigstore-rekor", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "Sigstore Rekor" + } + }, + { + "component_id": "ext::github-oidc", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "GitHub Actions OIDC token issuer" + } + }, + { + "component_id": "ext::github-repo", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "GitHub repository + Actions" + } + }, + { + "component_id": "ext::duo-mfa", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "Duo (operator MFA)" + } + }, + { + "component_id": "ext::github-advisory-db", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "GitHub Advisory Database" + } + }, + { + "component_id": "ext::cisa-kev", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "CISA Known Exploited Vulnerabilities catalog" + } + }, + { + "component_id": "ext::first-epss", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "FIRST Exploit Prediction Scoring System (EPSS) scores" + } + }, + { + "component_id": "ext::anchore-grype-db", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "Grype vulnerability database (Anchore)" + } + }, + { + "component_id": "ext::jsdelivr", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "jsDelivr CDN (MediaPipe Tasks Vision runtime)" + } + }, + { + "component_id": "ext::google-cloud-storage", + "type": "external_service", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "External service in boundary per ROT #2 (affects CIA without separate FedRAMP ATO)", + "name": "Google Cloud Storage (MediaPipe model bucket)" + } + }, + { + "component_id": "npm::@aws-sdk/checksums@3.1001.6", + "type": "npm_package", + "security_category": { + "confidentiality": "not-applicable", + "integrity": "moderate", + "availability": "not-applicable" + }, + "attributes": { + "function": "Runtime dependency of the compliance/KSI Lambda (npm)", + "name": "@aws-sdk/checksums" + } + }, + { + "component_id": "pypi::annotated-doc@0.0.5", + "type": "pypi_package", + "security_category": { + "confidentiality": "not-applicable", + "integrity": "moderate", + "availability": "not-applicable" + }, + "attributes": { + "function": "Dependency of the Silk Reeling application Lambda (PyPI)", + "name": "annotated-doc" + } + }, + { + "component_id": "html::404.html", + "type": "html_artifact", + "security_category": { + "confidentiality": "low", + "integrity": "moderate", + "availability": "low" + }, + "attributes": { + "function": "Public site content" + } + } + ], + "ksis": [ + { + "id": "KSI-CED-RAT", + "method": "documentation", + "status": "pass", + "evidence": { + "component_refs": [] + } + }, + { + "id": "KSI-CMT-LMC", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::cdn_distribution::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling" + ] + } + }, + { + "id": "KSI-CMT-RMV", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::cdn_distribution::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling" + ] + } + }, + { + "id": "KSI-CMT-RVP", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::cdn_distribution::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling" + ] + } + }, + { + "id": "KSI-CMT-VTD", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::cdn_distribution::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling" + ] + } + }, + { + "id": "KSI-CNA-DFP", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-EIS", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-IBP", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-MAT", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-OFA", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-RNT", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-RVP", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-CNA-ULN", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::identity_provider::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::dns_zone::website" + ] + } + }, + { + "id": "KSI-IAM-AAM", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-IAM-APM", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-IAM-ELP", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-IAM-JIT", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-IAM-SNU", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-IAM-SUS", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::identity_provider::silk_reeling", + "aws::oidc_provider::github", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::iam_group::operators", + "aws::iam_group::read_only" + ] + } + }, + { + "id": "KSI-INR-AAR", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::notification_topic::evidence_alerts" + ] + } + }, + { + "id": "KSI-INR-RIR", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::notification_topic::evidence_alerts" + ] + } + }, + { + "id": "KSI-INR-RPI", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::notification_topic::evidence_alerts" + ] + } + }, + { + "id": "KSI-MLA-ALA", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::message_queue::compliance_dlq", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::cdn_distribution::website", + "aws::notification_topic::evidence_alerts", + "aws::audit_log_trail::management" + ] + } + }, + { + "id": "KSI-MLA-EVC", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::message_queue::compliance_dlq", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::cdn_distribution::website", + "aws::notification_topic::evidence_alerts", + "aws::audit_log_trail::management" + ] + } + }, + { + "id": "KSI-MLA-LET", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::message_queue::compliance_dlq", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::cdn_distribution::website", + "aws::notification_topic::evidence_alerts", + "aws::audit_log_trail::management" + ] + } + }, + { + "id": "KSI-MLA-OSM", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::message_queue::compliance_dlq", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::cdn_distribution::website", + "aws::notification_topic::evidence_alerts", + "aws::audit_log_trail::management" + ] + } + }, + { + "id": "KSI-MLA-RVL", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::message_queue::compliance_dlq", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::cdn_distribution::website", + "aws::notification_topic::evidence_alerts", + "aws::audit_log_trail::management" + ] + } + }, + { + "id": "KSI-PIY-GIV", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::tls_certificate::website", + "aws::cdn_distribution::website", + "aws::dns_zone::website", + "aws::object_store::website", + "aws::api_gateway::silk_reeling", + "aws::audit_log_trail::management", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::identity_provider::silk_reeling", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::notification_topic::evidence_alerts", + "aws::message_queue::compliance_dlq", + "aws::kv_table::tflock", + "aws::iam_group::operators", + "aws::iam_group::read_only", + "aws::oidc_provider::github", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::object_store::tfstate", + "npm::@aws-sdk/checksums@3.1001.6", + "pypi::annotated-doc@0.0.5", + "html::404.html", + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage" + ] + } + }, + { + "id": "KSI-PIY-RES", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::tls_certificate::website", + "aws::cdn_distribution::website", + "aws::dns_zone::website", + "aws::object_store::website", + "aws::api_gateway::silk_reeling", + "aws::audit_log_trail::management", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::identity_provider::silk_reeling", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::notification_topic::evidence_alerts", + "aws::message_queue::compliance_dlq", + "aws::kv_table::tflock", + "aws::iam_group::operators", + "aws::iam_group::read_only", + "aws::oidc_provider::github", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::object_store::tfstate", + "npm::@aws-sdk/checksums@3.1001.6", + "pypi::annotated-doc@0.0.5", + "html::404.html", + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage" + ] + } + }, + { + "id": "KSI-PIY-RIS", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::tls_certificate::website", + "aws::cdn_distribution::website", + "aws::dns_zone::website", + "aws::object_store::website", + "aws::api_gateway::silk_reeling", + "aws::audit_log_trail::management", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::identity_provider::silk_reeling", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::notification_topic::evidence_alerts", + "aws::message_queue::compliance_dlq", + "aws::kv_table::tflock", + "aws::iam_group::operators", + "aws::iam_group::read_only", + "aws::oidc_provider::github", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::object_store::tfstate", + "npm::@aws-sdk/checksums@3.1001.6", + "pypi::annotated-doc@0.0.5", + "html::404.html", + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage" + ] + } + }, + { + "id": "KSI-PIY-RSD", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::tls_certificate::website", + "aws::cdn_distribution::website", + "aws::dns_zone::website", + "aws::object_store::website", + "aws::api_gateway::silk_reeling", + "aws::audit_log_trail::management", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::identity_provider::silk_reeling", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::notification_topic::evidence_alerts", + "aws::message_queue::compliance_dlq", + "aws::kv_table::tflock", + "aws::iam_group::operators", + "aws::iam_group::read_only", + "aws::oidc_provider::github", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::object_store::tfstate", + "npm::@aws-sdk/checksums@3.1001.6", + "pypi::annotated-doc@0.0.5", + "html::404.html", + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage" + ] + } + }, + { + "id": "KSI-PIY-RVD", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::tls_certificate::website", + "aws::cdn_distribution::website", + "aws::dns_zone::website", + "aws::object_store::website", + "aws::api_gateway::silk_reeling", + "aws::audit_log_trail::management", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::log_group::evidence_watchdog", + "aws::log_group::opa_compliance", + "aws::log_group::silk_apigw", + "aws::log_group::silk_reeling", + "aws::metric_alarm::evidence[artifact-stale]", + "aws::metric_alarm::evidence[nightly-failed]", + "aws::metric_alarm::evidence[runtime-age]", + "aws::metric_alarm::evidence[vdr-age]", + "aws::identity_provider::silk_reeling", + "aws::iam_role::evidence_watchdog", + "aws::iam_role::lambda_opa", + "aws::iam_role::silk_reeling", + "aws::iam_policy::evidence_watchdog", + "aws::iam_policy::lambda_opa", + "aws::iam_policy::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::notification_topic::evidence_alerts", + "aws::message_queue::compliance_dlq", + "aws::kv_table::tflock", + "aws::iam_group::operators", + "aws::iam_group::read_only", + "aws::oidc_provider::github", + "aws::iam_role::deploy", + "aws::iam_role::evidence_nightly", + "aws::iam_role::plan", + "aws::iam_policy::cloudtrail_management", + "aws::iam_policy::cognito_management", + "aws::iam_policy::compliance_dlq", + "aws::iam_policy::compliance_kms", + "aws::iam_policy::compliance_logs", + "aws::iam_policy::dnssec_management", + "aws::iam_policy::evidence_nightly_cdn", + "aws::iam_policy::evidence_nightly_publish", + "aws::iam_policy::evidence_nightly_reconcile_reads", + "aws::iam_policy::evidence_watchdog_management", + "aws::iam_policy::log_bucket_management", + "aws::iam_policy::plan_access", + "aws::iam_policy::reconcile_reads", + "aws::iam_policy::tfstate_backend", + "aws::object_store::tfstate", + "npm::@aws-sdk/checksums@3.1001.6", + "pypi::annotated-doc@0.0.5", + "html::404.html", + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage" + ] + } + }, + { + "id": "KSI-RPL-ABO", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate" + ] + } + }, + { + "id": "KSI-RPL-ARP", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate" + ] + } + }, + { + "id": "KSI-RPL-RRO", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate" + ] + } + }, + { + "id": "KSI-RPL-TRC", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate" + ] + } + }, + { + "id": "KSI-SCR-MIT", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage", + "pypi::annotated-doc@0.0.5", + "npm::@aws-sdk/checksums@3.1001.6" + ] + } + }, + { + "id": "KSI-SCR-MON", + "method": "inventory-attestation", + "status": "pass", + "evidence": { + "component_refs": [ + "ext::sigstore-fulcio", + "ext::sigstore-rekor", + "ext::github-oidc", + "ext::github-repo", + "ext::duo-mfa", + "ext::github-advisory-db", + "ext::cisa-kev", + "ext::first-epss", + "ext::anchore-grype-db", + "ext::jsdelivr", + "ext::google-cloud-storage", + "pypi::annotated-doc@0.0.5", + "npm::@aws-sdk/checksums@3.1001.6" + ] + } + }, + { + "id": "KSI-SVC-ACM", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-ASM", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-EIS", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-PRR", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-RUD", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-SIN", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-VCM", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + }, + { + "id": "KSI-SVC-VRI", + "method": "policy-validation", + "status": "pass", + "evidence": { + "component_refs": [ + "aws::api_gateway::silk_reeling", + "aws::cdn_distribution::website", + "aws::tls_certificate::website", + "aws::event_schedule::evidence_watchdog", + "aws::event_schedule::opa_compliance", + "aws::object_store::website", + "aws::object_store::cloudtrail", + "aws::object_store::logs", + "aws::object_store::tfstate", + "aws::function::evidence_watchdog", + "aws::function::opa_compliance", + "aws::function::silk_reeling", + "aws::kms_key::at_rest", + "aws::kms_key::dnssec_ksk", + "aws::kms_key::runtime_signing", + "aws::kms_key::silk_reeling" + ] + } + } + ] +} diff --git a/tests/fixtures/third-party/decided-without-tpr-fields.json b/tests/fixtures/third-party/decided-without-tpr-fields.json new file mode 100644 index 00000000..52e276b3 --- /dev/null +++ b/tests/fixtures/third-party/decided-without-tpr-fields.json @@ -0,0 +1,19 @@ +{ + "_note": "Known-bad (MAS-CSO-TPR): a decided record without the four fields FedRAMP requires.", + "components": { + "ext::cisa-kev": { + "upstream_offering": "CISA Known Exploited Vulnerabilities catalog (JSON feed)", + "upstream_component_id": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json", + "responsibility_split": { + "upstream_runs": "the catalog and its feed", + "provider_configures": "the fetch and its failure handling" + }, + "evidence": [ + "test fixture" + ], + "decided_by": "Operator", + "decided_on": "2026-11-03", + "usage_and_configuration": "fixture usage" + } + } +} diff --git a/tests/fixtures/third-party/decided.json b/tests/fixtures/third-party/decided.json index 73739eef..7e3162da 100644 --- a/tests/fixtures/third-party/decided.json +++ b/tests/fixtures/third-party/decided.json @@ -1,8 +1,22 @@ -{"_note": "test fixture", "components": { +{ + "_note": "test fixture", + "components": { "ext::cisa-kev": { - "upstream_offering": "CISA Known Exploited Vulnerabilities catalog (JSON feed)", - "upstream_component_id": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json", - "responsibility_split": {"upstream_runs": "the catalog and its feed", "provider_configures": "the fetch and its failure handling"}, - "evidence": ["test fixture"], - "decided_by": "Operator", "decided_on": "2026-11-03"} -}} + "upstream_offering": "CISA Known Exploited Vulnerabilities catalog (JSON feed)", + "upstream_component_id": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json", + "responsibility_split": { + "upstream_runs": "the catalog and its feed", + "provider_configures": "the fetch and its failure handling" + }, + "evidence": [ + "test fixture" + ], + "decided_by": "Operator", + "decided_on": "2026-11-03", + "usage_and_configuration": "fixture usage", + "justification": "fixture justification", + "mitigations": "fixture mitigations", + "compensating_controls": "fixture compensating controls" + } + } +} diff --git a/tests/test_mas.py b/tests/test_mas.py new file mode 100644 index 00000000..aba6a710 --- /dev/null +++ b/tests/test_mas.py @@ -0,0 +1,234 @@ +"""The Minimum Assessment Scope is generated, complete, and fails closed on a gap +(MAS-CSO-IIR, MAS-CSO-FLO, MAS-CSO-MDI, MAS-CSO-TPR, FRC-CSX-MAS). + +Each invariant scripts/build-mas.py enforces has a committed known-bad fixture +under tests/fixtures/mas/ (and tests/fixtures/third-party/) that fails for that +reason, and a test that the repository's own inputs pass it. +""" +import importlib.util +import json +import re +import sys +from pathlib import Path + +import jsonschema +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "mas" +sys.path.insert(0, str(REPO / "scripts")) +import _redact # noqa: E402 +import _tpr # noqa: E402 + + +def _load(name, path): + spec = importlib.util.spec_from_file_location(name, path) + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +mas = _load("build_mas", REPO / "scripts" / "build-mas.py") +bks = _load("bks_mas", REPO / "scripts" / "build-ksi-signal.py") + +INPUTS = json.loads(mas.INPUTS.read_text()) +CLASSIFICATION = json.loads(mas.CLASSIFICATION.read_text()) +TPR = json.loads(mas.THIRD_PARTY.read_text()) +SIGNAL = json.loads((FIX / "signal.json").read_text()) +CF_TF = mas.CLOUDFRONT_TF.read_text() +BOOT = "\n".join(p.read_text() for p in sorted(mas.BOOTSTRAP_DIR.glob("*.tf"))) +DST = set(INPUTS["data_store_types"]) + + +def _build(signal=SIGNAL, classification=CLASSIFICATION, tf=CF_TF): + return mas.build(signal, INPUTS, classification, TPR, tf, BOOT, "0" * 40, "2026-11-05T00:00:00+00:00") + + +# --- the repository's own scope passes, and publishes nothing it must not --------------- + +def test_the_repository_scope_builds_with_no_gap(): + doc, problems = _build() + assert problems == [] + assert all(doc["checks"].values()) + + +def test_fixture_signal_carries_every_declared_external_service(): + # The fixture must track the inventory builder, or the other tests prove nothing. + ext = {c["component_id"] for c in bks.build_external_components()} + assert ext <= {c["component_id"] for c in SIGNAL["components"]} + + +def test_the_published_scope_carries_no_account_id_or_arn(): + doc, _ = _build() + text = json.dumps(doc) + assert not _redact.find(text) + assert "arn:aws" not in text + assert "@" not in text.replace("@mediapipe", "") + + +def test_markdown_twin_states_every_section_and_the_derivation(): + doc, _ = _build() + md = mas.render_markdown(doc) + for heading in ("How this is derived", "MAS-CSO-IIR", "MAS-CSO-FLO", "MAS-CSO-MDI", "MAS-CSO-TPR", "FRC-CSX-MAS"): + assert heading in md + for t in doc["third_party_information_resources"]: + assert t["compensating_controls"] in md + + +# --- MAS-CSO-IIR: every off-origin host in the CSPs is placed --------------------------- + +def test_csp_hosts_include_the_app_origins(): + hosts = mas.csp_hosts(CF_TF, BOOT) + assert {"cdn.jsdelivr.net", "storage.googleapis.com"} <= set(hosts) + assert any(h.endswith(".amazoncognito.com") for h in hosts) + + +def test_the_app_origins_are_inventoried_external_services(): + ids = {c["component_id"] for c in bks.build_external_components()} + assert {"ext::jsdelivr", "ext::google-cloud-storage", "ext::first-epss", "ext::anchore-grype-db"} <= ids + + +def test_unplaced_csp_host_fails(): + _, problems = _build(tf=(FIX / "csp-unplaced.tf.fixture").read_text()) + assert any("unvetted-cdn.example.com" in p for p in problems) + + +def test_unresolvable_csp_source_fails_closed(): + with pytest.raises(SystemExit): + mas.csp_hosts((FIX / "csp-unresolved.tf.fixture").read_text(), "") + + +def test_out_of_scope_host_needs_a_reason(): + _, problems = mas.place_hosts(["ochelli.com"], {"ochelli.com": {"out_of_scope": " "}}, set()) + assert problems + + +# --- MAS-CSO-FLO: every external service and data store is in a flow -------------------- + +def test_flow_gaps_fail(): + _, problems = mas.flows(json.loads((FIX / "classification-gaps.json").read_text()), + json.loads((FIX / "signal-gaps.json").read_text())["components"], DST) + assert any("aws::function::ghost" in p for p in problems) + assert any("aws::log_group::brand_new" in p and "no information flow" in p for p in problems) + + +def test_flow_category_is_the_high_water_mark_of_its_endpoints(): + comps = [{"component_id": "a", "type": "x", "security_category": {"confidentiality": "low", "integrity": "high", "availability": "low"}}, + {"component_id": "b", "type": "x", "security_category": {"confidentiality": "moderate", "integrity": "low", "availability": "low"}}] + cls = {"declared": [], "flows": [{"id": "F", "label": "a to b", "path": [{"component": "a"}, {"component": "b"}]}]} + out, problems = mas.flows(cls, comps, set()) + assert problems == [] + assert out[0]["security_category"] == {"confidentiality": "moderate", "integrity": "high", "availability": "low"} + + +def test_every_external_service_and_data_store_in_the_inventory_is_in_a_flow(): + _, problems = mas.flows(CLASSIFICATION, SIGNAL["components"], DST) + assert problems == [] + + +# --- MAS-CSO-MDI: every data store and log has a metadata entry ------------------------- + +def test_data_store_without_metadata_fails(): + _, problems = mas.metadata_inventory(json.loads((FIX / "signal-gaps.json").read_text())["components"], + INPUTS["metadata"], DST) + assert any("aws::log_group::brand_new" in p for p in problems) + + +def _tf_block(text, rtype, name): + m = re.search(r'resource\s+"%s"\s+"%s"\s*\{(.*?)\n\}' % (re.escape(rtype), re.escape(name)), text, re.S) + assert m, (rtype, name) + return m.group(1) + + +def _num(block, key): + m = re.search(r"\b%s\s*=\s*(\d+)" % key, block) + assert m, key + return int(m.group(1)) + + +def test_metadata_retention_matches_the_terraform(): + infra = REPO / "infrastructure" + every = "\n".join(p.read_text() for p in sorted(infra.glob("*.tf")) + sorted((infra / "bootstrap").glob("*.tf"))) + lg = {"opa_compliance": "opa_compliance", "evidence_watchdog": "evidence_watchdog", + "silk_reeling": "silk_reeling", "silk_apigw": "silk_apigw", "route53_query_log": "route53_query_log"} + md = INPUTS["metadata"] + for comp, res in lg.items(): + assert md[f"aws::log_group::{comp}"]["retention_days"] == _num( + _tf_block(every, "aws_cloudwatch_log_group", res), "retention_in_days"), comp + assert md["aws::object_store::logs"]["retention_days"] == _num( + _tf_block(every, "aws_s3_bucket_lifecycle_configuration", "logs"), "days") + assert md["aws::object_store::cloudtrail"]["retention_days"] == int( + re.search(r"expiration\s*\{\s*days\s*=\s*(\d+)", _tf_block(every, "aws_s3_bucket_lifecycle_configuration", "cloudtrail")).group(1)) + assert md["aws::object_store::website"]["retention_days"] == _num( + _tf_block(every, "aws_s3_bucket_lifecycle_configuration", "website"), "noncurrent_days") + assert md["aws::object_store::tfstate"]["retention_days"] == _num( + _tf_block(every, "aws_s3_bucket_lifecycle_configuration", "tfstate"), "noncurrent_days") + assert md["aws::message_queue::compliance_dlq"]["retention_days"] * 86400 == _num( + _tf_block(every, "aws_sqs_queue", "compliance_dlq"), "message_retention_seconds") + + +# --- MAS-CSO-TPR ------------------------------------------------------------------------ + +def test_decided_third_party_record_without_the_four_fields_fails_the_inventory(): + with pytest.raises(SystemExit): + bks.build_external_components(REPO / "tests" / "fixtures" / "third-party" / "decided-without-tpr-fields.json") + + +def test_every_third_party_resource_is_decided_with_the_four_fields(): + _, problems = mas.third_party(SIGNAL["components"], TPR) + assert problems == [] + + +def test_undecided_third_party_record_fails_the_scope(): + undecided = json.loads(json.dumps(TPR)) + undecided["components"]["ext::jsdelivr"]["decided_by"] = None + _, problems = mas.third_party(SIGNAL["components"], undecided) + assert any("ext::jsdelivr" in p for p in problems) + + +def test_published_inventory_carries_the_four_fields(): + for c in bks.build_external_components(): + for f in bks.MAS_TPR_FIELDS: + assert c["attributes"][f] not in (None, "", "not recorded"), (c["component_id"], f) + + +def test_cpo_helper_matches_the_cpo_schema(): + schema = json.loads((REPO / "infrastructure" / "schemas" / "fedramp-2026-06-24" / + "fedramp-certification-package-overview-schema-2026-06-24.json").read_text()) + out = _tpr.cpo_third_party_information_resources() + jsonschema.validate(out, schema["properties"]["thirdPartyInformationResources"]) + assert len(out["nonCertified"]) == len(TPR["components"]) + + +# --- FRC-CSX-MAS: every KSI applies to the scope, every component type is covered ------- + +def test_component_type_in_no_ksi_domain_fails(): + _, _, problems = mas.ksi_application(json.loads((FIX / "signal-gaps.json").read_text()), {}) + assert any("mystery" in p for p in problems) + + +def test_every_ksi_applies_and_every_component_type_is_covered(): + ka, per_type, problems = mas.ksi_application(SIGNAL, INPUTS["whole_set_types"]) + assert problems == [] + assert {k["ksi"] for k in ka} == {k["id"] for k in SIGNAL["ksis"]} + assert all(k["components"] > 0 or k["applies_to"] == "whole set" for k in ka) + assert set(per_type) == {c["type"] for c in SIGNAL["components"]} + + +def test_audit_trail_is_in_the_logging_ksi_domain(): + assert "audit_log_trail" in bks.KSI_FAMILY_EVIDENCE_TYPES["MLA"] + + +# --- the deploy builds it before the SDR and publishes it signed ------------------------ + +WF = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() + + +def test_deploy_builds_the_scope_before_the_sdr_and_publishes_it(): + build = WF.index("- name: Build the Minimum Assessment Scope") + sdr = WF.index("- name: Build Security Decision Record (SDR") + assert build < sdr + gate = WF[WF.index("- name: Publication redaction gate (no AWS account ID)"):WF.index("- name: Publish all signed artifacts")] + publish = WF[WF.index("- name: Publish all signed artifacts"):WF.index("- name: Attest artifact provenance")] + assert "minimum-assessment-scope" in gate and "minimum-assessment-scope" in publish + assert "--bundle minimum-assessment-scope.bundle minimum-assessment-scope.json" in WF From 8fa18eebc2c900f19301bba2b017c49369a70617 Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:52:55 -0500 Subject: [PATCH 07/17] feat(trust): agency access register, denial clock and exercise; sharing standard; DEC-165..167 Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/agency-access.yml | 36 +++ data/agency-access-exercise.json | 23 ++ data/agency-access.json | 5 + data/decisions.json | 56 ++++ docs/procedures/agency-access.md | 19 ++ docs/procedures/information-sharing.md | 23 ++ scripts/agency-access.py | 293 ++++++++++++++++++ .../agency-access/overdue-denial.json | 7 + .../agency-access/person-in-register.json | 7 + tests/test_agency_access.py | 100 ++++++ 10 files changed, 569 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/agency-access.yml create mode 100644 data/agency-access-exercise.json create mode 100644 data/agency-access.json create mode 100644 docs/procedures/agency-access.md create mode 100644 docs/procedures/information-sharing.md create mode 100644 scripts/agency-access.py create mode 100644 tests/fixtures/agency-access/overdue-denial.json create mode 100644 tests/fixtures/agency-access/person-in-register.json create mode 100644 tests/test_agency_access.py diff --git a/.github/ISSUE_TEMPLATE/agency-access.yml b/.github/ISSUE_TEMPLATE/agency-access.yml new file mode 100644 index 00000000..7f84524d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/agency-access.yml @@ -0,0 +1,36 @@ +name: Agency access to the certification package +description: For a federal agency (or FedRAMP) to be put on record, to withdraw, or to ask for the access inventory. The package itself is public and needs no request. +title: "Agency access: " +labels: ["agency-access"] +body: + - type: markdown + attributes: + value: | + **Everything in the certification package is already public** at https://samaydlette.com/trust/ and https://samaydlette.com/.well-known/trust-manifest.json; you do not need to ask to read it. + File this form to put your agency or system **on record** (so you are counted in the access inventory and can be told about changes), to **withdraw** an earlier record, or, for FedRAMP, to **request the inventory**. + This repository is public, so this issue is public. **Name agencies and systems, never people**; do not include names, email addresses or phone numbers. For a private request, use the security contact in `/.well-known/security.txt` instead. + This is a proof of concept with no federal data and no agency sponsor. Procedure: docs/procedures/agency-access.md. + - type: dropdown + id: kind + attributes: + label: Request + options: + - Put my agency or system on record (access) + - Withdraw an earlier record (withdrawal) + - FedRAMP request for the access inventory (inventory-request) + validations: + required: true + - type: input + id: agency + attributes: + label: Agency (or FedRAMP) + validations: + required: true + - type: input + id: system + attributes: + label: System or service (optional) + - type: input + id: withdraws + attributes: + label: For a withdrawal, the earlier request (AAR-...) diff --git a/data/agency-access-exercise.json b/data/agency-access-exercise.json new file mode 100644 index 00000000..81969a6a --- /dev/null +++ b/data/agency-access-exercise.json @@ -0,0 +1,23 @@ +{ + "_note": "The agency-access exercise the deploy runs (scripts/agency-access.py exercise). Every agency here is fictional and every date is a business-day offset from the day it runs, so the 5-business-day denial clock is exercised against today's calendar. The exercise fails the deploy unless every outcome in `expected` is observed, including the late and overdue notices the processor must catch.", + "disclaimer": "SIMULATED. These agencies do not exist, no federal agency has requested access, and nothing is sent to FedRAMP or anyone: a denial notice is this log entry. Any resemblance to a real agency is the result of a very tired naming committee.", + "requests": [ + {"id": "AAR-X01", "agency": "Department of Hypothetical Affairs (simulated)", "system": "Hypothetical Records Portal", "kind": "access", "channel": "issue form", "received_on_offset": -10, "decision": "granted", "decided_on_offset": -9, "decided_by": "Operator (exercise)"}, + {"id": "AAR-X02", "agency": "Bureau of Made-Up Statistics (simulated)", "system": "Totally Average Dashboard", "kind": "access", "channel": "security contact", "received_on_offset": -9, "decision": "denied", "decided_on_offset": -8, "decided_by": "Operator (exercise)", "reason": "Asked for write access to a read-only website.", "fedramp_notified_on_offset": -4}, + {"id": "AAR-X03", "agency": "Office of Strictly Imaginary Procurement (simulated)", "kind": "access", "channel": "issue form", "received_on_offset": -3, "decision": "denied", "decided_on_offset": -2, "decided_by": "Operator (exercise)", "reason": "Requested the package by fax."}, + {"id": "AAR-X04", "agency": "Agency of Unverifiable Claims (simulated)", "kind": "access", "channel": "security contact", "received_on_offset": -13, "decision": "denied", "decided_on_offset": -12, "decided_by": "Operator (exercise)", "reason": "Could not verify the agency exists (it does not).", "fedramp_notified_on_offset": -5}, + {"id": "AAR-X05", "agency": "Department of Hypothetical Affairs (simulated)", "system": "Second Opinion Service", "kind": "access", "channel": "issue form", "received_on_offset": -8, "decision": "granted", "decided_on_offset": -7, "decided_by": "Operator (exercise)"}, + {"id": "AAR-X06", "agency": "Department of Hypothetical Affairs (simulated)", "system": "Second Opinion Service", "kind": "withdrawal", "channel": "issue form", "received_on_offset": -1, "withdraws": "AAR-X05"}, + {"id": "AAR-X07", "agency": "Commission on Rhetorical Questions (simulated)", "kind": "access", "channel": "issue form", "received_on_offset": -8, "decision": "denied", "decided_on_offset": -7, "decided_by": "Operator (exercise)", "reason": "Asked whether access was really necessary, and we agreed."}, + {"id": "AAR-X08", "agency": "FedRAMP (simulated)", "kind": "inventory-request", "channel": "security contact", "received_on_offset": -1} + ], + "expected": { + "AAR-X01": "in inventory", + "AAR-X02": "denial notice on time", + "AAR-X03": "denial notice pending", + "AAR-X04": "denial notice late", + "AAR-X05": "withdrawn", + "AAR-X07": "denial notice overdue", + "AAR-X08": "inventory supplied" + } +} diff --git a/data/agency-access.json b/data/agency-access.json new file mode 100644 index 00000000..04c78dc0 --- /dev/null +++ b/data/agency-access.json @@ -0,0 +1,5 @@ +{ + "schema": "agency-access/1", + "_note": "The register of agency access requests, decisions and withdrawals for the certification package (CDS-TRC-AAI, CDS-UTC-AAD); procedure in docs/procedures/agency-access.md, read by scripts/agency-access.py, which the deploy runs and which fails on a denial not notified to FedRAMP within 5 business days. Records name agencies and systems, never people. No federal agency has filed a request: the list is empty, and the mechanism is exercised on every deploy with plainly fictional agencies (data/agency-access-exercise.json).", + "requests": [] +} diff --git a/data/decisions.json b/data/decisions.json index 1b4d402f..02592f41 100644 --- a/data/decisions.json +++ b/data/decisions.json @@ -1155,6 +1155,62 @@ "source": { "detector": "OWASP ZAP baseline scan" } + }, + { + "id": "DEC-165", + "title": "Agency access to the certification package: decided by the operator, denials notified to FedRAMP within 5 business days, inventory supplied on request", + "disposition": "operational-requirement", + "status": "in-force", + "justification": "The operator decides every agency access request and records it in data/agency-access.json (agencies and systems, never people); notifies FedRAMP of every denial within 5 business days; and supplies the access inventory and its history to FedRAMP on request (docs/procedures/agency-access.md). The package itself is public, so access needs no provisioning. The deploy fails when a denial notice is late or overdue, and exercises the procedure with fictional agencies on every run. AI-drafted 2026-11-05 for the operator to confirm.", + "controls": [ + "ac-21", + "ca-6" + ], + "applies_to": { + "check_ids": [], + "vuln_ids": [], + "resources": [] + }, + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + { + "id": "DEC-166", + "title": "Public sharing of the certification package: disclosure standard and determination of no likely adverse effect", + "disposition": "operational-requirement", + "status": "in-force", + "justification": "The operator has determined that publishing the whole certification package is not likely to have an adverse effect on the offering, because it carries no account IDs, secrets, credentials, personal email addresses, IAM user names, run IDs, raw logs or access-request contacts (each refused by a build gate), and the detail published on purpose (role names and policy summaries, the API and CloudFront hostnames, configurations and findings) grants no access on its own (docs/procedures/information-sharing.md). Reviewed annually and when a new kind of artifact is published. AI-drafted 2026-11-05 for the operator to confirm.", + "controls": [ + "ac-22" + ], + "applies_to": { + "check_ids": [], + "vuln_ids": [], + "resources": [] + }, + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" + }, + { + "id": "DEC-167", + "title": "Verification and validation use full populations, never representative samples", + "disposition": "operational-requirement", + "status": "in-force", + "justification": "The operator does not use representative samples in verification or validation: every check runs over its full population (every inventoried component, every live in-boundary resource, every SBOM, every rule record and every test it cites), and the simulated assessor re-checks every rule and KSI. The assessor guide states this (IVV-CSO-DUS). Any future use of sampling would be documented there and this record revised. AI-drafted 2026-11-05 for the operator to confirm.", + "controls": [ + "ca-2", + "ca-7" + ], + "applies_to": { + "check_ids": [], + "vuln_ids": [], + "resources": [] + }, + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05", + "review_by": "2027-11-05" } ] } diff --git a/docs/procedures/agency-access.md b/docs/procedures/agency-access.md new file mode 100644 index 00000000..712f380b --- /dev/null +++ b/docs/procedures/agency-access.md @@ -0,0 +1,19 @@ +# Agency Access to the Certification Package + +This procedure covers how agencies obtain the FedRAMP certification package, how a request is decided, what happens when one is denied, and how the inventory of agencies with access is kept and supplied to FedRAMP. It implements CDS-UTC-AGA, CDS-UTC-AAD, CDS-TRC-AAI and CDS-TRC-SSM. Decision record: DEC-165. + +**The package is public.** Every piece of certification data is served without authentication from the trust center (https://samaydlette.com/trust/) and listed, with its URL, media type, signature and human-readable view, in the signed manifest https://samaydlette.com/.well-known/trust-manifest.json. An agency does not need to ask, register or hold an account to read or download any of it, so no request for the package itself is ever pending. + +**Self-service.** An agency that wants to be on record, so that it is counted in the access inventory and can be told about changes, files the "Agency access to the certification package" issue form in the public repository, or writes to the security contact in `/.well-known/security.txt` for a private request. The same form withdraws an earlier record. The register records agencies and systems, never people: no names, email addresses or phone numbers. + +**Decision.** The operator decides each access request and records it in `data/agency-access.json`: who decided, on what date, and, for a denial, why. Because everything is public, a denial can only concern something beyond the public package (for example, a request for write access or for data the system does not hold). + +**Denial notice.** FedRAMP is notified of every denial within 5 business days (US federal holidays excluded). The deploy runs `scripts/agency-access.py validate`, which computes each denial's deadline and fails the deploy when a notice is late or overdue. In this proof of concept nothing is sent to FedRAMP or anyone: the notice is the entry recorded in the register. + +**Inventory and history.** `scripts/agency-access.py inventory` prints the agencies and systems on record today and the full history of requests, decisions, withdrawals and notices. It is supplied to FedRAMP on request, through the same form or the security contact, and is not otherwise published. + +**Exercise.** No federal agency has filed a request. On every deploy, `scripts/agency-access.py exercise` runs the same code over a scenario of plainly fictional agencies (`data/agency-access-exercise.json`) dated relative to that day, including a late and an overdue denial notice that it must catch, and fails the deploy unless every outcome is the expected one. The signed log is published at https://samaydlette.com/.well-known/agency-access-exercise.json. + +**Access records.** A party that asks for the access records that concern it receives the trust center's access summaries for the artifacts it names (CDS-TRC-ACL). Individual viewers are never identified in those records. + +**Review cadence.** Annually with the [security review](../security-review.md). diff --git a/docs/procedures/information-sharing.md b/docs/procedures/information-sharing.md new file mode 100644 index 00000000..0d17faad --- /dev/null +++ b/docs/procedures/information-sharing.md @@ -0,0 +1,23 @@ +# Information Sharing and Disclosure Standard + +This standard says what certification data is published, what is never published, and why publishing it is not likely to harm the offering. It implements CDS-CSO-RIS and records the determination CDS-CSO-RPS permits. Decision record: DEC-166. + +**What is public.** The whole FedRAMP certification package: every artifact the signed manifest (https://samaydlette.com/.well-known/trust-manifest.json) lists, the policies and procedures it links, and the repository that builds them. It is public because the offering has no federal data and no agency sponsor, and because showing the evidence openly is the purpose of this proof of concept. Anyone may read, download and verify it. + +**What is never published.** The deploy refuses to publish, and the gates named here fail the build on: + +- AWS account IDs, and ARNs that carry one (publication redaction gate, `scripts/check-published-redaction.py`; ARNs are published with the account replaced by `ACCOUNT`); +- secret values, keys, tokens and credentials of any kind (never placed in the inventory; Terraform state is read owner-only and deleted after use); +- personal email addresses and IAM user names (the rule records, trust center and boundary map refuse them); +- GitHub run IDs and raw logs, including CloudFront access logs: only aggregate counts are published (CDS-TRC-ACL); +- the contacts behind an agency access request: the register names agencies and systems, never people. + +**What is public on purpose, after consideration.** Some published detail could look sensitive. Each is published because an authorizing official needs it to judge the system, and none grants access by itself: + +- IAM role names and summaries of their least-privilege policies: they show who can change what; assuming a role needs the GitHub OIDC trust bound to this repository's reviewed environment; +- the API Gateway endpoint host and the CloudFront domain: both are already discoverable through DNS and every page load; +- component configuration, scanner findings with their dispositions, and vulnerability reports: they show how the system is built and how each finding was decided, which an authorizing official cannot judge without. + +**Determination.** The operator has determined that sharing the package publicly in this form is not likely to have an adverse effect on the offering, because it carries none of the items listed above and the items published on purpose give no access on their own. The determination is reviewed annually, and whenever a new kind of artifact is published. + +**Review cadence.** Annually with the [security review](../security-review.md). diff --git a/scripts/agency-access.py b/scripts/agency-access.py new file mode 100644 index 00000000..e99a02aa --- /dev/null +++ b/scripts/agency-access.py @@ -0,0 +1,293 @@ +#!/usr/bin/env python3 +"""Agency access to the certification package: the inventory, its history, and +the five-business-day denial clock (CDS-TRC-AAI, CDS-TRC-SSM, CDS-UTC-AAD, +CDS-UTC-AGA). + +The package is public, so access needs no provisioning; an agency that wants +to be on record (for notices, or to request anything not published) files a +request, and may withdraw it the same way (docs/procedures/agency-access.md). +Every request and decision is a record in data/agency-access.json, the +register. From it this computes: + + inventory the agencies and systems with access on record today; + history every request, decision and withdrawal, in date order; + denial notices FedRAMP must be told within 5 business days of a denial + (US federal holidays excluded); each notice is on time, + pending (inside the window), late, or overdue. + +`validate` fails the deploy on an invalid record, a late notice, or an overdue +one. `inventory` prints what goes to FedRAMP on request. `exercise` runs the +same code over data/agency-access-exercise.json, a scenario of plainly +fictional agencies dated relative to today, and fails unless every outcome is +the expected one, including the late and overdue cases it must catch. Nothing +is ever sent to FedRAMP or anyone: a notice is a log entry. +""" + +import argparse +import json +import re +import sys +from datetime import date, datetime, timedelta, timezone +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent +REGISTER = REPO / "data" / "agency-access.json" +SCENARIO = REPO / "data" / "agency-access-exercise.json" +NOTICE_DAYS = 5 +KINDS = ("access", "withdrawal", "inventory-request") +DECISIONS = ("granted", "denied") +ID_RE = re.compile(r"^AAR-[A-Z0-9]{2,8}$") +EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+") +RECORD_KEYS = {"id", "agency", "system", "kind", "channel", "received_on", "decision", "decided_on", "decided_by", + "reason", "fedramp_notified_on", "withdraws"} + + +def _fail(msg): + raise SystemExit(f"::error::agency access: {msg} (fail-closed)") + + +# --- business days ------------------------------------------------------------------------ + +def _nth_weekday(year, month, weekday, n): + d = date(year, month, 1) + d += timedelta(days=(weekday - d.weekday()) % 7) + return d + timedelta(weeks=n - 1) + + +def _last_weekday(year, month, weekday): + d = date(year, month + 1, 1) - timedelta(days=1) if month < 12 else date(year, 12, 31) + return d - timedelta(days=(d.weekday() - weekday) % 7) + + +def _observed(d): + return d - timedelta(days=1) if d.weekday() == 5 else d + timedelta(days=1) if d.weekday() == 6 else d + + +def federal_holidays(year): + """US federal holidays (5 U.S.C. 6103), observed dates.""" + fixed = [date(year, 1, 1), date(year, 6, 19), date(year, 7, 4), date(year, 11, 11), date(year, 12, 25)] + floating = [_nth_weekday(year, 1, 0, 3), _nth_weekday(year, 2, 0, 3), _last_weekday(year, 5, 0), + _nth_weekday(year, 9, 0, 1), _nth_weekday(year, 10, 0, 2), _nth_weekday(year, 11, 3, 4)] + return {_observed(d) for d in fixed} | set(floating) + + +def is_business_day(d): + return d.weekday() < 5 and d not in federal_holidays(d.year) + + +def add_business_days(d, n): + step = 1 if n >= 0 else -1 + while n: + d += timedelta(days=step) + if is_business_day(d): + n -= step + return d + + +# --- the register ------------------------------------------------------------------------------ + +def _date(v, where): + try: + return date.fromisoformat(v) + except (TypeError, ValueError): + _fail(f"{where} is not a YYYY-MM-DD date: {v!r}") + + +def validate(doc, where): + if not isinstance(doc, dict) or doc.get("schema") != "agency-access/1" or not isinstance(doc.get("requests"), list): + _fail(f"{where} is not an agency-access/1 document") + seen = {} + for r in doc["requests"]: + rid = r.get("id") if isinstance(r, dict) else None + if not isinstance(rid, str) or not ID_RE.match(rid) or rid in seen: + _fail(f"{where}: request id {rid!r} is not a unique AAR-XXX") + if set(r) - RECORD_KEYS: + _fail(f"{rid}: unknown field(s) {sorted(set(r) - RECORD_KEYS)}") + for k in ("agency", "channel"): + if not isinstance(r.get(k), str) or not r[k].strip(): + _fail(f"{rid}: {k} must be a non-empty string") + # The register records agencies and systems, never people. + if any(isinstance(v, str) and EMAIL_RE.search(v) for v in r.values()): + _fail(f"{rid}: carries an email address; the register names agencies and systems, not people") + if r.get("kind") not in KINDS: + _fail(f"{rid}: kind must be one of {list(KINDS)}") + received = _date(r.get("received_on"), f"{rid} received_on") + if r["kind"] == "withdrawal": + if r.get("withdraws") not in seen or seen[r["withdraws"]].get("decision") != "granted": + _fail(f"{rid}: withdraws must name an earlier granted request") + if r.get("decision") is not None: + if r["decision"] not in DECISIONS or r["kind"] != "access": + _fail(f"{rid}: only an access request is decided, granted or denied") + if _date(r.get("decided_on"), f"{rid} decided_on") < received: + _fail(f"{rid}: decided before it was received") + if not isinstance(r.get("decided_by"), str) or not r["decided_by"].strip(): + _fail(f"{rid}: a decision names who made it (decided_by)") + if r["decision"] == "denied" and not (isinstance(r.get("reason"), str) and r["reason"].strip()): + _fail(f"{rid}: a denial states its reason") + if r.get("fedramp_notified_on") is not None: + if r.get("decision") != "denied": + _fail(f"{rid}: only a denial is notified to FedRAMP") + if _date(r["fedramp_notified_on"], f"{rid} fedramp_notified_on") < date.fromisoformat(r["decided_on"]): + _fail(f"{rid}: FedRAMP notified before the denial") + seen[rid] = r + return doc + + +def process(doc, today): + reqs = sorted(doc["requests"], key=lambda r: (r["received_on"], r["id"])) + withdrawn = {r["withdraws"]: r for r in reqs if r["kind"] == "withdrawal"} + inventory, history, notices = [], [], [] + for r in reqs: + history.append({"date": r["received_on"], "request": r["id"], "event": f"{r['kind']} received", + "agency": r["agency"], "system": r.get("system")}) + if r.get("decision"): + history.append({"date": r["decided_on"], "request": r["id"], "event": r["decision"], + "agency": r["agency"], "system": r.get("system")}) + if r.get("decision") == "granted": + w = withdrawn.get(r["id"]) + if w is None: + inventory.append({"request": r["id"], "agency": r["agency"], "system": r.get("system"), + "since": r["decided_on"]}) + else: + history.append({"date": w["received_on"], "request": r["id"], "event": "access withdrawn", + "agency": r["agency"], "system": r.get("system")}) + if r.get("decision") == "denied": + decided = date.fromisoformat(r["decided_on"]) + deadline = add_business_days(decided, NOTICE_DAYS) + sent = r.get("fedramp_notified_on") + if sent: + state = "on time" if date.fromisoformat(sent) <= deadline else "late" + history.append({"date": sent, "request": r["id"], "event": "denial notified to FedRAMP", + "agency": r["agency"], "system": r.get("system")}) + else: + state = "pending" if today <= deadline else "overdue" + notices.append({"request": r["id"], "agency": r["agency"], "denied_on": r["decided_on"], + "reason": r["reason"], "deadline": deadline.isoformat(), "notified_on": sent, + "state": state, + "to": "FedRAMP (simulated recipient: nothing is sent; this entry is the notice)"}) + history.sort(key=lambda h: (h["date"], h["request"])) + problems = [f"{n['request']}: FedRAMP denial notice {n['state']} (deadline {n['deadline']})" + for n in notices if n["state"] in ("late", "overdue")] + return {"as_of": today.isoformat(), "inventory": inventory, "history": history, "denial_notices": notices, + "inventory_requests": [r["id"] for r in reqs if r["kind"] == "inventory-request"], + "problems": problems} + + +def load(path): + p = Path(path) + try: + return validate(json.loads(p.read_text()), str(p)) + except (OSError, json.JSONDecodeError) as exc: + _fail(f"cannot read {p}: {exc}") + + +# --- the exercise --------------------------------------------------------------------------------- + +def materialize(scenario, today): + """Turn the scenario's business-day offsets (relative to today) into dates.""" + out = [] + for r in scenario["requests"]: + r = dict(r) + for k in ("received_on", "decided_on", "fedramp_notified_on"): + off = r.pop(f"{k}_offset", None) + if off is not None: + r[k] = add_business_days(today, off).isoformat() + out.append(r) + return {"schema": "agency-access/1", "requests": out} + + +def observe(result): + obs = {f"{i['request']}": "in inventory" for i in result["inventory"]} + for h in result["history"]: + if h["event"] == "access withdrawn": + obs[h["request"]] = "withdrawn" + for n in result["denial_notices"]: + obs[n["request"]] = f"denial notice {n['state']}" + for rid in result["inventory_requests"]: + obs[rid] = "inventory supplied" + return obs + + +def exercise(scenario, today): + doc = validate(materialize(scenario, today), "exercise scenario") + result = process(doc, today) + observed = observe(result) + expected = scenario["expected"] + mismatches = [f"{k}: expected {v!r}, observed {observed.get(k)!r}" for k, v in sorted(expected.items()) + if observed.get(k) != v] + mismatches += [f"{k}: observed {v!r} with no expectation" for k, v in sorted(observed.items()) + if k not in expected] + return doc, result, mismatches + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + sub = ap.add_subparsers(dest="cmd", required=True) + v = sub.add_parser("validate") + v.add_argument("--register", default=str(REGISTER)) + i = sub.add_parser("inventory") + i.add_argument("--register", default=str(REGISTER)) + e = sub.add_parser("exercise") + e.add_argument("--scenario", default=str(SCENARIO)) + e.add_argument("--output", default="agency-access-exercise.json") + e.add_argument("--md-output", default="agency-access-exercise.md") + for p in (v, i, e): + p.add_argument("--today", default=None, help="YYYY-MM-DD (default: today, UTC)") + a = ap.parse_args(argv) + today = date.fromisoformat(a.today) if a.today else datetime.now(timezone.utc).date() + + if a.cmd in ("validate", "inventory"): + result = process(load(a.register), today) + if a.cmd == "inventory": + print(json.dumps({"as_of": result["as_of"], "inventory": result["inventory"], + "history": result["history"]}, indent=2)) + return 0 + for p in result["problems"]: + print(f"::error::{p}") + if result["problems"]: + _fail(f"{len(result['problems'])} denial notice(s) to FedRAMP late or overdue") + print(f"agency access: {len(result['inventory'])} on record; {len(result['denial_notices'])} denial " + f"notice(s), none late or overdue") + return 0 + + scenario = json.loads(Path(a.scenario).read_text()) + doc, result, mismatches = exercise(scenario, today) + for m in mismatches: + print(f"::error::agency access exercise: {m}") + if mismatches: + _fail("the exercise did not produce the expected outcomes") + log = {"log_type": "agency-access-exercise", "simulated": True, "counterparty": "agency", + "generated_at": datetime.now(timezone.utc).isoformat(), "as_of": today.isoformat(), + "disclaimer": scenario["disclaimer"], "procedure": "docs/procedures/agency-access.md", + "notice_window_business_days": NOTICE_DAYS, + "outcome": "every expected outcome observed", "expected": scenario["expected"], + "requests": doc["requests"], **{k: result[k] for k in ("inventory", "history", "denial_notices")}} + Path(a.output).write_text(json.dumps(log, indent=2) + "\n") + if a.md_output: + Path(a.md_output).write_text(render_markdown(log) + "\n") + print(f"agency access exercise: {len(scenario['expected'])} expected outcomes observed") + return 0 + + +def render_markdown(log): + out = ["# Agency access exercise (simulated)", "", f"_{log['disclaimer']}_", "", + f"- **As of:** {log['as_of']} | **Generated:** {log['generated_at']}", + f"- **Procedure:** `{log['procedure']}` | **Denial notice window:** " + f"{log['notice_window_business_days']} business days", f"- **Outcome:** {log['outcome']}", "", + "## Expected and observed", "", "| Request | Outcome |", "|---|---|"] + out += [f"| {k} | {v} |" for k, v in sorted(log["expected"].items())] + out += ["", "## Inventory on record", "", "| Request | Agency | System | Since |", "|---|---|---|---|"] + out += [f"| {i['request']} | {i['agency']} | {i.get('system') or '—'} | {i['since']} |" for i in log["inventory"]] + out += ["", "## Denial notices to FedRAMP (simulated; nothing is sent)", "", + "| Request | Agency | Denied | Deadline | Notified | State |", "|---|---|---|---|---|---|"] + out += [f"| {n['request']} | {n['agency']} | {n['denied_on']} | {n['deadline']} | {n['notified_on'] or '—'} | " + f"{n['state']} |" for n in log["denial_notices"]] + out += ["", "## History", "", "| Date | Request | Event | Agency |", "|---|---|---|---|"] + out += [f"| {h['date']} | {h['request']} | {h['event']} | {h['agency']} |" for h in log["history"]] + out += ["", "## Requests", "", "```json", json.dumps(log["requests"], indent=2), "```", + "", "---", "_Source of truth: the signed `agency-access-exercise.json`._"] + return "\n".join(out) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/agency-access/overdue-denial.json b/tests/fixtures/agency-access/overdue-denial.json new file mode 100644 index 00000000..28252a43 --- /dev/null +++ b/tests/fixtures/agency-access/overdue-denial.json @@ -0,0 +1,7 @@ +{ + "schema": "agency-access/1", + "_note": "Known-bad: a denial on 2026-11-02 with no FedRAMP notice; the 5-business-day window closed on 2026-11-09. Validation as of 2026-11-10 must fail.", + "requests": [ + {"id": "AAR-B01", "agency": "Bureau of Known-Bad Fixtures (simulated)", "kind": "access", "channel": "issue form", "received_on": "2026-11-02", "decision": "denied", "decided_on": "2026-11-02", "decided_by": "Operator", "reason": "Fixture."} + ] +} diff --git a/tests/fixtures/agency-access/person-in-register.json b/tests/fixtures/agency-access/person-in-register.json new file mode 100644 index 00000000..24a7e322 --- /dev/null +++ b/tests/fixtures/agency-access/person-in-register.json @@ -0,0 +1,7 @@ +{ + "schema": "agency-access/1", + "_note": "Known-bad: the register names a person's email address; it records agencies and systems only.", + "requests": [ + {"id": "AAR-B02", "agency": "Bureau of Known-Bad Fixtures (simulated)", "kind": "access", "channel": "jane.doe@example.gov", "received_on": "2026-11-02"} + ] +} diff --git a/tests/test_agency_access.py b/tests/test_agency_access.py new file mode 100644 index 00000000..a564b1f8 --- /dev/null +++ b/tests/test_agency_access.py @@ -0,0 +1,100 @@ +"""Agency access: inventory and history (CDS-TRC-AAI), self-service request and +withdrawal (CDS-TRC-SSM), access on request (CDS-UTC-AGA), and the +five-business-day denial notice to FedRAMP (CDS-UTC-AAD), exercised with +plainly fictional agencies.""" +import copy +import importlib.util +import json +from datetime import date +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "agency-access" +spec = importlib.util.spec_from_file_location("agency_access", REPO / "scripts" / "agency-access.py") +aa = importlib.util.module_from_spec(spec) +spec.loader.exec_module(aa) + + +@pytest.mark.parametrize("start,n,expected", [ + (date(2026, 11, 25), 5, date(2026, 12, 3)), # Thanksgiving (Thu 26 Nov) is skipped + (date(2026, 12, 23), 5, date(2026, 12, 31)), # Christmas (Fri 25 Dec) + (date(2027, 7, 1), 2, date(2027, 7, 6)), # 4 July 2027 is a Sunday, observed Monday 5 July + (date(2026, 11, 6), 1, date(2026, 11, 9)), # Friday to Monday +]) +def test_business_days_skip_weekends_and_federal_holidays(start, n, expected): + assert aa.add_business_days(start, n) == expected + + +def test_known_bad_an_unnotified_denial_past_five_business_days_fails(): + doc = aa.load(FIX / "overdue-denial.json") + assert aa.process(doc, date(2026, 11, 9))["problems"] == [] # last day of the window + assert aa.process(doc, date(2026, 11, 10))["problems"] == [ + "AAR-B01: FedRAMP denial notice overdue (deadline 2026-11-09)"] + with pytest.raises(SystemExit): + aa.main(["validate", "--register", str(FIX / "overdue-denial.json"), "--today", "2026-11-10"]) + + +def test_known_bad_the_register_never_names_a_person(): + with pytest.raises(SystemExit, match="not people"): + aa.load(FIX / "person-in-register.json") + + +def test_inventory_and_history_follow_grants_and_withdrawals(): + doc = aa.validate({"schema": "agency-access/1", "requests": [ + {"id": "AAR-T1", "agency": "A (simulated)", "system": "S1", "kind": "access", "channel": "form", + "received_on": "2026-11-02", "decision": "granted", "decided_on": "2026-11-03", "decided_by": "Operator"}, + {"id": "AAR-T2", "agency": "A (simulated)", "kind": "withdrawal", "channel": "form", + "received_on": "2026-11-04", "withdraws": "AAR-T1"}]}, "t") + r = aa.process(doc, date(2026, 11, 5)) + assert r["inventory"] == [] + assert [h["event"] for h in r["history"]] == ["access received", "granted", "access withdrawn", + "withdrawal received"] + + +@pytest.mark.parametrize("bad", [ + {"decision": "denied"}, # a denial with no reason or date + {"decision": "granted", "decided_on": "2026-11-01"}, # decided before received + {"fedramp_notified_on": "2026-11-03"}, # notice with no denial +]) +def test_invalid_records_fail(bad): + rec = {"id": "AAR-T1", "agency": "A (simulated)", "kind": "access", "channel": "form", + "received_on": "2026-11-02", "decided_by": "Operator", **bad} + with pytest.raises(SystemExit): + aa.validate({"schema": "agency-access/1", "requests": [rec]}, "t") + + +@pytest.mark.parametrize("today", ["2026-11-05", "2026-11-27", "2026-12-28", "2027-01-04", "2027-07-06"]) +def test_the_exercise_observes_every_expected_outcome_on_any_day(today): + scenario = json.loads(aa.SCENARIO.read_text()) + _, _, mismatches = aa.exercise(scenario, date.fromisoformat(today)) + assert mismatches == [] + + +def test_the_exercise_fails_when_an_outcome_is_not_the_expected_one(): + scenario = copy.deepcopy(json.loads(aa.SCENARIO.read_text())) + scenario["expected"]["AAR-X07"] = "denial notice on time" # the clock must catch it + _, _, mismatches = aa.exercise(scenario, date(2026, 11, 5)) + assert mismatches == ["AAR-X07: expected 'denial notice on time', observed 'denial notice overdue'"] + + +def test_the_exercise_agencies_are_obviously_fictional(): + scenario = json.loads(aa.SCENARIO.read_text()) + assert all(r["agency"].endswith("(simulated)") for r in scenario["requests"]) + assert "SIMULATED" in scenario["disclaimer"] and "nothing is sent" in scenario["disclaimer"] + + +def test_the_committed_register_is_valid_and_has_nothing_overdue(): + doc = aa.load(aa.REGISTER) + assert aa.process(doc, date(2026, 11, 5))["problems"] == [] + + +def test_the_exercise_writes_a_log_that_says_it_is_simulated(tmp_path): + out, md = tmp_path / "log.json", tmp_path / "log.md" + assert aa.main(["exercise", "--output", str(out), "--md-output", str(md), "--today", "2026-11-05"]) == 0 + log = json.loads(out.read_text()) + assert log["simulated"] is True and log["counterparty"] == "agency" + assert {n["state"] for n in log["denial_notices"]} == {"on time", "pending", "late", "overdue"} + assert all("nothing is sent" in n["to"] for n in log["denial_notices"]) + assert "Agency access exercise (simulated)" in md.read_text() From 6de6236c98a542e815ec08b4e032554507c2e76c Mon Sep 17 00:00:00 2001 From: sam-aydlette Date: Thu, 5 Nov 2026 16:53:26 -0500 Subject: [PATCH 08/17] feat(trust): independent availability monitor, private access logging, CORS on /.well-known/ - availability-probe.yml + scripts/availability-probe.py: a monitor on GitHub Actions (outside AWS) probes the site, trust center, /.well-known/, the Silk Reeling app and its sign-in every 15 minutes, keeps 35 days, derives incidents, and publishes JSON + Markdown to the availability-status branch; an ongoing incident fails the run. The deploy fails when that feed is missing or stale, and availability.json is now built from it, never from deploys. - CloudFront standard logging v2 (bootstrap/trust-access-logs.tf) with a field allowlist that drops IP, cookies, query string, user agent and referrer; raw records expire after 90 days (logging.tf). The deploy fails unless the delivery exists within the allowlist, and publishes monthly aggregates for /.well-known/ and /trust/ only (access-summary.json, 13 months). - /.well-known/* gets its own response-headers policy with read-only CORS; the deploy checks CORS, JSON Content-Type and nosniff live. - DEC-160 (AI-drafted for the operator): what is logged, and a party's own records on request. - CDS-CSO-AVR, CDS-TRC-USH, CDS-TRC-ACL flip to Implemented. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/availability-probe.yml | 88 +++++++ .github/workflows/deploy-with-opa.yml | 58 +++- data/decisions.json | 24 ++ data/frr-records.json | 107 ++++++-- docs/trust/access-logging-privacy-notice.html | 29 ++ infrastructure/bootstrap/cloudfront.tf | 103 ++++++++ infrastructure/bootstrap/trust-access-logs.tf | 128 +++++++++ infrastructure/logging.tf | 28 +- infrastructure/schemas/freshness-config.json | 12 + scripts/availability-probe.py | 248 ++++++++++++++++++ scripts/build-access-summary.py | 203 ++++++++++++++ scripts/build-availability.py | 178 ++++++++----- scripts/check-edge-access-logging.py | 92 +++++++ scripts/check-wellknown-headers.py | 83 ++++++ .../availability/known-bad-stale-feed.json | 2 + .../edge-access-logging/delivery-source.json | 2 + .../edge-access-logging/good-deliveries.json | 3 + .../known-bad-deliveries.json | 3 + .../fixtures/wellknown-headers/known-bad.json | 4 + .../wellknown-headers/known-good.json | 4 + tests/test_availability_probe.py | 126 +++++++++ tests/test_edge_access_logging.py | 154 +++++++++++ tests/test_site_headers.py | 3 +- tests/test_wellknown_headers.py | 77 ++++++ 24 files changed, 1673 insertions(+), 86 deletions(-) create mode 100644 .github/workflows/availability-probe.yml create mode 100644 docs/trust/access-logging-privacy-notice.html create mode 100644 infrastructure/bootstrap/trust-access-logs.tf create mode 100644 scripts/availability-probe.py create mode 100644 scripts/build-access-summary.py create mode 100644 scripts/check-edge-access-logging.py create mode 100644 scripts/check-wellknown-headers.py create mode 100644 tests/fixtures/availability/known-bad-stale-feed.json create mode 100644 tests/fixtures/edge-access-logging/delivery-source.json create mode 100644 tests/fixtures/edge-access-logging/good-deliveries.json create mode 100644 tests/fixtures/edge-access-logging/known-bad-deliveries.json create mode 100644 tests/fixtures/wellknown-headers/known-bad.json create mode 100644 tests/fixtures/wellknown-headers/known-good.json create mode 100644 tests/test_availability_probe.py create mode 100644 tests/test_edge_access_logging.py create mode 100644 tests/test_wellknown_headers.py diff --git a/.github/workflows/availability-probe.yml b/.github/workflows/availability-probe.yml new file mode 100644 index 00000000..602a17b6 --- /dev/null +++ b/.github/workflows/availability-probe.yml @@ -0,0 +1,88 @@ +# ============================================================================= +# Availability probe (CDS-CSO-AVR, CDS-TRC-USH) +# ============================================================================= +# An availability monitor on infrastructure independent of the offering: it +# runs on GitHub Actions, not AWS, probes the core services over HTTPS every 15 +# minutes (scripts/availability-probe.py), keeps 35 days of history, derives +# availability incidents, and publishes JSON + Markdown to the repository's +# `availability-status` branch. GitHub serves that branch, so the status stays +# readable when the offering's CloudFront or S3 is down: +# https://raw.githubusercontent.com/sam-aydlette/samaydlette.com/availability-status/availability-status.json +# https://github.com/sam-aydlette/samaydlette.com/blob/availability-status/availability-status.md +# +# The branch holds one commit, replaced on every run (history lives in the +# JSON), so the repository does not grow by a commit every 15 minutes. The +# workflow's token can write contents (no narrower scope exists); the job only +# ever pushes refs/heads/availability-status, and main is protected by its own +# branch rules. The deploy reads this feed and fails when it is missing or more +# than 2 hours old, so the published package never cites a monitor that has +# stopped (scripts/availability-probe.py --check-fresh). +# +# Caveats stated in the feed: history begins at the first run; GitHub may delay +# a scheduled run under load, and disables schedules on a repository with no +# activity for 60 days (the deploy's freshness check then fails). +# ============================================================================= +name: Availability probe + +on: + schedule: + - cron: '*/15 * * * *' + push: + branches: [main] + workflow_dispatch: + +permissions: {} + +concurrency: + group: availability-probe + cancel-in-progress: false + +jobs: + probe: + name: Probe the core services from outside AWS + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write # push the status branch; nothing else + steps: + - name: Checkout the probe + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + persist-credentials: false + + - name: Read the previous status feed + run: | + set -euo pipefail + # Public repository: an anonymous fetch. No branch yet means a first run. + if git fetch --depth 1 --quiet origin availability-status 2>/dev/null; then + git show FETCH_HEAD:availability-status.json > previous-status.json || echo '{}' > previous-status.json + else + echo '{}' > previous-status.json + fi + + - name: Probe the core services + run: python3 scripts/availability-probe.py --previous previous-status.json --out-dir status-out + + - name: Publish the status feed to the availability-status branch + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail + cd status-out + git init --quiet + git checkout --quiet --orphan availability-status + git add availability-status.json availability-status.md + git -c user.name="availability-probe" -c user.email="availability-probe@users.noreply.github.com" \ + commit --quiet -m "Availability status $(jq -r .generated_at availability-status.json)" + auth=$(printf 'x-access-token:%s' "$GH_TOKEN" | base64 -w0) + echo "::add-mask::$auth" + git -c http.extraheader="AUTHORIZATION: basic $auth" \ + push --quiet --force "https://github.com/${REPO}.git" HEAD:refs/heads/availability-status + + # After publishing: an ongoing incident fails the run, and GitHub notifies + # the operator of the failed scheduled run (email). The status is already + # published either way. + - name: Alert on an ongoing availability incident + run: python3 scripts/availability-probe.py --fail-on-incident status-out/availability-status.json diff --git a/.github/workflows/deploy-with-opa.yml b/.github/workflows/deploy-with-opa.yml index 24a24847..9ec89825 100644 --- a/.github/workflows/deploy-with-opa.yml +++ b/.github/workflows/deploy-with-opa.yml @@ -1574,17 +1574,59 @@ jobs: --md-output ongoing-certification-report.md jq '{next_ongoing_certification_report_date, next_quarterly_review_date}' ongoing-certification-report.json + # W8 edge checks (FRC-CSO-JSN, CDS-CSO-AVR, CDS-TRC-USH, CDS-TRC-ACL). Each + # depends on something outside this deploy (the operator-applied bootstrap + # stack, or the independent monitor on GitHub Actions) and fails the deploy + # when it is missing, before the SDR says the rule is met. + - name: Check /.well-known/ JSON response headers (CORS, Content-Type, nosniff) + env: + DOMAIN: ${{ vars.DOMAIN_NAME || 'samaydlette.com' }} + run: python3 scripts/check-wellknown-headers.py --site "https://$DOMAIN" + + - name: Read the independent availability feed (fails when missing or stale) + working-directory: infrastructure + env: + REPO: ${{ github.repository }} + run: | + set -euo pipefail + curl -fsS --max-time 30 -o availability-probe.json \ + "https://raw.githubusercontent.com/$REPO/availability-status/availability-status.json" + python3 ../scripts/availability-probe.py --check-fresh availability-probe.json --max-age-hours 2 + + # The CloudFront access records carry no IP, cookie, query string or user + # agent (the delivery's field allowlist, checked here); only /.well-known/ + # and /trust/ requests are counted, and only monthly aggregates published. + - name: Check edge access logging and build the access summary + working-directory: infrastructure + env: + DOMAIN: ${{ vars.DOMAIN_NAME || 'samaydlette.com' }} + run: | + set -euo pipefail + umask 077 + trap 'rm -rf edge-access-records edge-deliveries.json edge-delivery-source.json' EXIT + name="${DOMAIN//./-}-edge-access" + aws logs describe-deliveries --region us-east-1 --output json > edge-deliveries.json + aws logs get-delivery-source --name "$name" --region us-east-1 --output json > edge-delivery-source.json || true + python3 ../scripts/check-edge-access-logging.py \ + --deliveries edge-deliveries.json --source edge-delivery-source.json --name "$name" + bucket="${DOMAIN//./-}-logs" + account=$(aws sts get-caller-identity --query Account --output text) + aws s3 sync "s3://$bucket/cloudfront/" edge-access-records/cloudfront/ --only-show-errors + aws s3 sync "s3://$bucket/AWSLogs/$account/CloudFront/" edge-access-records/default/ --only-show-errors + curl -fsS --max-time 20 -o previous-access-summary.json "https://$DOMAIN/.well-known/access-summary.json" \ + || echo '{}' > previous-access-summary.json + python3 ../scripts/build-access-summary.py \ + --records edge-access-records --previous previous-access-summary.json + - name: Build CDS certification-data artifacts (overview, availability, policy index) working-directory: infrastructure run: | echo "Building CDS certification-overview package, availability feed, policy index..." - # availability history: fetch the previously-published feed (best-effort) - curl -sfL -o previous-availability.json "https://samaydlette.com/.well-known/availability.json" \ - || echo '{"history":[]}' > previous-availability.json python3 ../scripts/build-cds-overview.py \ --offering ../data/cds/offering.json --profile ../data/system-profile.json --ksi-signal ksi-signal.json + # Availability as measured by the independent monitor (read and checked above). python3 ../scripts/build-availability.py \ - --previous previous-availability.json --ksi-signal ksi-signal.json + --probe-feed availability-probe.json --ksi-signal ksi-signal.json python3 ../scripts/build-policy-index.py --output policy-index.json --md-output policy-index.md - name: Build Security Decision Record (SDR — 20x SSP replacement) @@ -1701,6 +1743,7 @@ jobs: cosign sign-blob --yes --new-bundle-format --bundle policy-index.bundle policy-index.json cosign sign-blob --yes --new-bundle-format --bundle security-decision-record.bundle security-decision-record.json cosign sign-blob --yes --new-bundle-format --bundle certification-package-overview.bundle certification-package-overview.json + cosign sign-blob --yes --new-bundle-format --bundle access-summary.bundle access-summary.json - name: Sign trust-center artifacts (boundary map, gate report, trust center) working-directory: infrastructure @@ -1729,6 +1772,7 @@ jobs: for a in vdr-detail-report vdr-accepted-vulnerabilities; do files="$files $a.md"; done files="$files ongoing-certification-report.json ongoing-certification-report.md" for a in certification-overview-package availability policy-index security-decision-record certification-package-overview; do files="$files $a.json $a.md"; done + for a in access-summary; do files="$files $a.json $a.md"; done for a in boundary-map reconcile-report trust-center conformance-results boundary-corroboration; do [ -f "$a.json" ] || continue files="$files $a.json" @@ -1788,6 +1832,12 @@ jobs: aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" aws s3 cp "$a.md" "s3://$BUCKET_NAME/.well-known/$a.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" done + # Trust-center access summary (CDS-TRC-ACL): aggregate counts only. + for a in access-summary; do + aws s3 cp "$a.json" "s3://$BUCKET_NAME/.well-known/$a.json" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "$a.bundle" "s3://$BUCKET_NAME/.well-known/$a.bundle" --content-type application/json --cache-control "public, max-age=300" + aws s3 cp "$a.md" "s3://$BUCKET_NAME/.well-known/$a.md" --content-type "text/markdown; charset=utf-8" --cache-control "public, max-age=300" + done # Trust center: the generated boundary map, the gate's own report (it exists # only because the gate above passed) and the trust center's data. for a in boundary-map reconcile-report trust-center conformance-results boundary-corroboration; do diff --git a/data/decisions.json b/data/decisions.json index 1b4d402f..cc864646 100644 --- a/data/decisions.json +++ b/data/decisions.json @@ -1155,6 +1155,30 @@ "source": { "detector": "OWASP ZAP baseline scan" } + }, + { + "id": "DEC-160", + "title": "Trust-center access records: what is logged, and a party's own records on request", + "disposition": "operational-requirement", + "status": "in-force", + "justification": "AI-drafted for the operator to confirm. Access to the certification data is logged by CloudFront standard logging with a field allowlist that excludes IP address, forwarded-for, port, cookies, query string, user agent and referrer (infrastructure/bootstrap/trust-access-logs.tf); raw records expire after 90 days and only monthly aggregate counts for /.well-known/ and /trust/ are published, kept 13 months (scripts/build-access-summary.py). Because no requester identity is logged, the operator provides a party, on request to the security contact, the published summaries and any records matching the times and paths the party identifies, within 10 business days. Agencies are identified only by what they state in their own access request, never inferred from network data. This trades per-party attribution (CDS-TRC-ACL's SHOULD) for privacy, at the operator's direction of 2026-11-05.", + "controls": [ + "au-2", + "au-3", + "au-11", + "pt-2" + ], + "applies_to": { + "check_ids": [], + "vuln_ids": [], + "resources": [ + "aws-cloudfront-distribution" + ] + }, + "decided_by": "Sam Aydlette", + "decided_on": "2026-11-05", + "review_by": "2027-11-05", + "point_of_contact": "Sam Aydlette (operator)" } ] } diff --git a/data/frr-records.json b/data/frr-records.json index 6a767bed..c19a25d4 100644 --- a/data/frr-records.json +++ b/data/frr-records.json @@ -258,12 +258,37 @@ }, { "frr_id": "CDS-CSO-AVR", - "status": "Partially Implemented", - "implementation": "https://samaydlette.com/.well-known/availability.json + availability.md, scripts/build-availability.py (appends one point per deploy, L47-53; WINDOW_DAYS=45 L27).", - "evidence": [], - "gap": "Not an availability measurement: a point is written only when a deploy succeeds ('A deploy that produces this feed is, by definition, a successful one', L10-11), so an outage can never be recorded and there are no incidents field/records. Days without deploys are simply missing (27 points spanning 2026-08-06..11-05; ~10 in the last 30 days). Trim keeps the last 45 points, not 45 days, so history older than the window persists. Core services are not probed (Silk Reeling API/Cognito not checked at all). Served from the same CloudFront/S3 as the offering, so it is unavailable when the offering is (self-stated residual). To close: Run an external synthetic monitor on independent infrastructure (different provider/region/account and DNS name, e.g. a status subdomain on separate hosting) that probes the site, /.well-known/, and the Silk Reeling API/Cognito every few minutes; record incidents (start, end, affected service, cause); publish JSON + HTML status page from that independent host with 30+ days of continuous history.", - "closes_with": [ - "W8" + "status": "Implemented", + "implementation": "An availability monitor on GitHub Actions, independent of AWS (.github/workflows/availability-probe.yml, scripts/availability-probe.py), probes the website, the trust center, the certification data under /.well-known/, the Silk Reeling application and its Cognito sign-in every 15 minutes, keeps 35 days of history, and derives availability incidents (two or more consecutive failed probes of a service: start, end, failing check). It publishes JSON and a human-readable page to the repository's availability-status branch, served by GitHub, so the status stays readable when the offering is down; an ongoing incident fails the run, which notifies the operator. The deploy fails when that feed is missing or more than 2 hours old, and republishes it signed as /.well-known/availability.json with a Markdown twin (scripts/build-availability.py), which no longer records deploys as availability. History begins at the monitor's first run.", + "evidence": [ + { + "kind": "step", + "ref": "availability-probe.yml#Probe the core services" + }, + { + "kind": "step", + "ref": "availability-probe.yml#Publish the status feed to the availability-status branch" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Read the independent availability feed (fails when missing or stale)" + }, + { + "kind": "artifact", + "ref": ".well-known/availability.json" + }, + { + "kind": "test", + "ref": "tests/test_availability_probe.py::test_consecutive_failures_make_an_incident_and_a_single_one_is_transient" + }, + { + "kind": "test", + "ref": "tests/test_availability_probe.py::test_the_known_bad_stale_feed_fails_the_deploy_guard" + }, + { + "kind": "test", + "ref": "tests/test_availability_probe.py::test_the_monitor_runs_outside_aws_on_a_schedule_and_pushes_only_its_branch" + } ] }, { @@ -391,12 +416,37 @@ }, { "frr_id": "CDS-TRC-ACL", - "status": "Partially Implemented", - "implementation": "S3 server access logging on the website bucket (infrastructure/logging.tf:114) to a log bucket retained 400 days (logging.tf:59).", - "evidence": [], - "gap": "S3 server access logs only see origin fetches; CloudFront edge hits are not logged (no logging_config on the distribution, bootstrap/cloudfront.tf:233-311), so most access to certification data is invisible. No access summaries are produced or stored; no explanation of how parties obtain their log information. To close: Enable CloudFront standard (or real-time) logging for /.well-known/ and /trust/, build a scheduled job that writes monthly access summaries (per artifact, per requester/agency once authenticated) retained >= 6 months, and document how a party requests its records.", - "closes_with": [ - "W8" + "status": "Implemented", + "implementation": "CloudFront standard logging (v2) records every request to the site with a field allowlist that excludes IP address, forwarded-for, port, cookies, query string, user agent and referrer (infrastructure/bootstrap/trust-access-logs.tf). Records go to the encrypted, non-public access-log bucket and expire after 90 days (infrastructure/logging.tf). On every deploy, scripts/check-edge-access-logging.py fails the deploy unless that delivery exists and logs only allowlisted fields, and scripts/build-access-summary.py counts the requests to /.well-known/ and /trust/ (CloudFront cannot limit logging by path, so the limit is applied here and every other record is discarded) into monthly summaries per artifact, response class and country, published signed at /.well-known/access-summary.json with a Markdown twin and carried forward for 13 months. A party can ask for the summaries and for the records of its own requests, identified by the times and paths it gives, since no requester identity is logged (DEC-160); the trust page's privacy notice says so.", + "evidence": [ + { + "kind": "step", + "ref": "deploy-with-opa.yml#Check edge access logging and build the access summary" + }, + { + "kind": "artifact", + "ref": ".well-known/access-summary.json" + }, + { + "kind": "test", + "ref": "tests/test_edge_access_logging.py::test_the_known_bad_fixture_fails_for_identifying_fields" + }, + { + "kind": "test", + "ref": "tests/test_edge_access_logging.py::test_only_trust_paths_are_counted_and_nothing_identifying_survives" + }, + { + "kind": "test", + "ref": "tests/test_edge_access_logging.py::test_a_month_younger_than_six_is_never_dropped" + }, + { + "kind": "test", + "ref": "tests/test_edge_access_logging.py::test_raw_edge_records_expire_after_90_days" + }, + { + "kind": "decision", + "ref": "DEC-160" + } ] }, { @@ -431,12 +481,33 @@ }, { "frr_id": "CDS-TRC-USH", - "status": "Partially Implemented", - "implementation": "The trust center is a static public site on CloudFront; /trust/ and every directory URL serve their index through a CloudFront Function (W1), and /.well-known/*.json are served directly.", - "evidence": [], - "gap": "Availability of the trust center is not measured independently (CDS-CSO-AVR), there is a single origin with no failover (DEC-009), and the page's content needs JavaScript.", - "closes_with": [ - "W8" + "status": "Implemented", + "implementation": "The certification data is static, signed files under /.well-known/ served from the CloudFront edge (cached, with AWS Shield Standard), readable as plain JSON and Markdown without JavaScript and, since the deploy checks it, with CORS for programs on any origin. Interruptions are measured from outside AWS every 15 minutes, and an ongoing one fails the monitor's run, which notifies the operator (CDS-CSO-AVR); the status itself is served by GitHub, so it stays available during an outage. The single origin without failover is an accepted risk (DEC-009).", + "evidence": [ + { + "kind": "step", + "ref": "availability-probe.yml#Alert on an ongoing availability incident" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Read the independent availability feed (fails when missing or stale)" + }, + { + "kind": "step", + "ref": "deploy-with-opa.yml#Check /.well-known/ JSON response headers (CORS, Content-Type, nosniff)" + }, + { + "kind": "artifact", + "ref": ".well-known/availability.json" + }, + { + "kind": "test", + "ref": "tests/test_availability_probe.py::test_an_ongoing_incident_fails_the_monitor_run_after_publishing" + }, + { + "kind": "decision", + "ref": "DEC-009" + } ] }, { diff --git a/docs/trust/access-logging-privacy-notice.html b/docs/trust/access-logging-privacy-notice.html new file mode 100644 index 00000000..9a91c1b2 --- /dev/null +++ b/docs/trust/access-logging-privacy-notice.html @@ -0,0 +1,29 @@ + +
+

Access logging and your privacy

+

FedRAMP asks trust centers to log access to certification data and keep summaries of it + (CDS-TRC-ACL). This is what this site logs, and what it does not.

+
    +
  • What is logged. For each request to the site, the CDN records the date and time, + the edge location and country it was served from, the method, the path, the response status, the + bytes sent and whether it came from cache. It does not record your IP address, user agent, + referrer, cookies or query string: those fields are switched off at the edge, so they are never stored.
  • +
  • Why. To show, in aggregate, how the certification data under + /.well-known/ and this trust center are used, as FedRAMP requires.
  • +
  • How long. The raw records are deleted after 90 days. Only monthly counts + (per artifact, per response class, per country) are kept, for 13 months, and published at + /.well-known/access-summary.json + (readable version). Requests to other pages of + the site are not counted.
  • +
  • Who can see the raw records. Only the operator and the deploy pipeline's + read-only role, in an encrypted bucket that is not public.
  • +
  • Agencies. An agency is identified only by what it states in its own access + request. Nothing is inferred from network addresses, which are not logged.
  • +
  • Your own records. You can ask for the summaries and for the records of your own + requests, identified by the times and paths you give us (the records hold nothing that identifies + a requester). Write to the security contact listed in the certification package.
  • +
+
diff --git a/infrastructure/bootstrap/cloudfront.tf b/infrastructure/bootstrap/cloudfront.tf index da368e29..4242dfc7 100644 --- a/infrastructure/bootstrap/cloudfront.tf +++ b/infrastructure/bootstrap/cloudfront.tf @@ -241,6 +241,85 @@ resource "aws_cloudfront_response_headers_policy" "silk_reeling" { } } +# The published certification data under /.well-known/ (FRC-CSO-JSN, CDS-TRC-PAC): +# the static site's security headers, plus CORS so a browser application on +# another origin can read the JSON. Read-only (GET/HEAD/OPTIONS), any origin, no +# credentials: the data is public. CORP is cross-origin here, not same-origin, +# for the same reason. X-Content-Type-Options: nosniff is sent; the Content-Type +# is the object's own (set at upload). The deploy checks all three live and +# fails without them (scripts/check-wellknown-headers.py). +resource "aws_cloudfront_response_headers_policy" "well_known" { + name = "${local.domain_dashed}-well-known-headers" + comment = "Security headers and read-only CORS for ${var.domain_name}/.well-known/" + + cors_config { + access_control_allow_credentials = false + access_control_allow_headers { + items = ["*"] + } + access_control_allow_methods { + items = ["GET", "HEAD", "OPTIONS"] + } + access_control_allow_origins { + items = ["*"] + } + access_control_max_age_sec = 3600 + origin_override = true + } + + security_headers_config { + strict_transport_security { + access_control_max_age_sec = 31536000 + include_subdomains = true + preload = true + override = true + } + content_type_options { + override = true + } + frame_options { + frame_option = "DENY" + override = true + } + referrer_policy { + referrer_policy = "strict-origin-when-cross-origin" + override = true + } + content_security_policy { + content_security_policy = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'" + override = true + } + xss_protection { + mode_block = true + protection = true + override = true + } + } + + custom_headers_config { + items { + header = "Permissions-Policy" + value = "camera=(), microphone=(), geolocation=(), payment=(), usb=()" + override = true + } + items { + header = "Cross-Origin-Opener-Policy" + value = "same-origin" + override = true + } + items { + header = "Cross-Origin-Resource-Policy" + value = "cross-origin" + override = true + } + items { + header = "Cross-Origin-Embedder-Policy" + value = "credentialless" + override = true + } + } +} + resource "aws_cloudfront_distribution" "website" { # Scanner findings that describe this distribution's deliberate posture, each # classified here at scan-time (not silently dropped) and tracked in the POA&M @@ -306,6 +385,30 @@ resource "aws_cloudfront_distribution" "website" { } } + # Certification data: cached and forwarded like the static site, with the + # /.well-known/ headers policy (CORS) above. Read-only methods: nothing is + # written through the edge. The CORS headers come from the policy, so the + # Origin header is not forwarded and the cache is not split by it. No + # viewer-request function: every path here names a file. + ordered_cache_behavior { + path_pattern = "/.well-known/*" + target_origin_id = "S3-${var.domain_name}" + response_headers_policy_id = aws_cloudfront_response_headers_policy.well_known.id + viewer_protocol_policy = "redirect-to-https" + allowed_methods = ["HEAD", "GET", "OPTIONS"] + cached_methods = ["HEAD", "GET"] + compress = true + min_ttl = 0 + default_ttl = 3600 + max_ttl = 86400 + forwarded_values { + query_string = false + cookies { + forward = "none" + } + } + } + # App path: no caching, forward everything except Host (so the JWT authorizer # sees the Authorization header), strip the prefix at the edge, and add the # app's security headers. diff --git a/infrastructure/bootstrap/trust-access-logs.tf b/infrastructure/bootstrap/trust-access-logs.tf new file mode 100644 index 00000000..1315f10a --- /dev/null +++ b/infrastructure/bootstrap/trust-access-logs.tf @@ -0,0 +1,128 @@ +# ============================================================================= +# Trust-center access logging (CDS-TRC-ACL), with the operator's privacy limits +# ============================================================================= +# CloudFront standard logging (v2: CloudWatch vended-log delivery) for the +# distribution in cloudfront.tf, written to the existing access-log bucket that +# the per-deploy stack owns (../logging.tf: "-logs", SSE-S3, public +# access blocked, owner-enforced, a 90-day expiry on the CloudFront prefixes). +# +# Privacy limits (operator's condition, 2026-11-05): +# - The record carries only the fields below. No client IP, X-Forwarded-For, +# client port, cookies, query string, user agent or referrer is ever logged: +# CloudFront v2 field selection drops them at the edge, so they never reach +# storage. Country (c-country) is the finest location kept. +# - CloudFront cannot limit logging to a path, so every request is logged with +# those fields; the deploy's summarizer (scripts/build-access-summary.py) +# counts only /.well-known/ and /trust/ and discards the rest, and only +# aggregate counts are ever published. +# - Raw records expire after 90 days (../logging.tf). Monthly aggregate +# summaries are kept for 13 months in the published access summary. +# +# The deploy fails when this delivery is absent or logs a field outside the +# allowlist (scripts/check-edge-access-logging.py, step "Check edge access +# logging and build the access summary"), so the trust center never claims +# logging that is not configured. Operator-applied, like the rest of bootstrap. +# The delivery's record_fields list and ALLOWED_FIELDS in that script are the +# same list; tests/test_edge_access_logging.py holds them equal. +# ============================================================================= + +locals { + edge_access_log_name = "${local.domain_dashed}-edge-access" + # The existing access-log bucket, owned by the per-deploy stack (../logging.tf + # aws_s3_bucket.logs, already inventoried there); named, not read, here. + access_log_bucket_arn = "arn:aws:s3:::${local.domain_dashed}-logs" + edge_access_log_fields = [ + "date", + "time", + "x-edge-location", + "c-country", + "cs-method", + "cs-uri-stem", + "sc-status", + "sc-bytes", + "x-edge-result-type", + ] +} + + +resource "aws_cloudwatch_log_delivery_source" "edge_access" { + provider = aws.us_east_1 + name = local.edge_access_log_name + log_type = "ACCESS_LOGS" + resource_arn = aws_cloudfront_distribution.website.arn +} + +resource "aws_cloudwatch_log_delivery_destination" "edge_access" { + provider = aws.us_east_1 + name = local.edge_access_log_name + output_format = "json" + + delivery_destination_configuration { + destination_resource_arn = "${local.access_log_bucket_arn}/cloudfront" + } +} + +resource "aws_cloudwatch_log_delivery" "edge_access" { + provider = aws.us_east_1 + delivery_source_name = aws_cloudwatch_log_delivery_source.edge_access.name + delivery_destination_arn = aws_cloudwatch_log_delivery_destination.edge_access.arn + record_fields = local.edge_access_log_fields + + s3_delivery_configuration { + suffix_path = "{DistributionId}/{yyyy}/{MM}/{dd}/{HH}" + enable_hive_compatible_path = false + } +} + +# The deploy reads the delivery's configuration (to fail when it is absent or +# logs a forbidden field) and the CloudFront records (to build the aggregate +# summary). Read-only. Describe/Get on deliveries are account-level calls with +# no resource-level scoping for DescribeDeliveries; the Get* calls are scoped +# to this delivery's resources. The object read is limited to the two prefixes +# CloudFront delivery may write under. +data "aws_iam_policy_document" "edge_access_logs_read" { + # checkov:skip=CKV_AWS_356:logs:DescribeDeliveries is an account-level enumeration action that cannot be resource-scoped; read-only. Documented exception. + statement { + sid = "DescribeDeliveries" + actions = ["logs:DescribeDeliveries"] + resources = ["*"] + } + statement { + sid = "ReadEdgeAccessDelivery" + actions = [ + "logs:GetDelivery", + "logs:GetDeliverySource", + "logs:GetDeliveryDestination", + ] + resources = [ + "arn:aws:logs:us-east-1:${data.aws_caller_identity.current.account_id}:delivery:*", + aws_cloudwatch_log_delivery_source.edge_access.arn, + aws_cloudwatch_log_delivery_destination.edge_access.arn, + ] + } + statement { + sid = "ListEdgeAccessRecords" + actions = ["s3:ListBucket"] + resources = [local.access_log_bucket_arn] + condition { + test = "StringLike" + variable = "s3:prefix" + values = ["cloudfront/*", "AWSLogs/${data.aws_caller_identity.current.account_id}/CloudFront/*"] + } + } + statement { + sid = "ReadEdgeAccessRecords" + actions = ["s3:GetObject"] + resources = [ + "${local.access_log_bucket_arn}/cloudfront/*", + "${local.access_log_bucket_arn}/AWSLogs/${data.aws_caller_identity.current.account_id}/CloudFront/*", + ] + } +} + +resource "aws_iam_role_policy" "edge_access_logs_read" { + # checkov:skip=CKV_AWS_356:logs:DescribeDeliveries cannot be resource-scoped; read-only. Documented exception. + name = "edge-access-logs-read" + role = aws_iam_role.deploy.id + policy = data.aws_iam_policy_document.edge_access_logs_read.json +} diff --git a/infrastructure/logging.tf b/infrastructure/logging.tf index ed5decd5..fd2f518e 100644 --- a/infrastructure/logging.tf +++ b/infrastructure/logging.tf @@ -60,6 +60,26 @@ resource "aws_s3_bucket_lifecycle_configuration" "logs" { noncurrent_version_expiration { noncurrent_days = 30 } abort_incomplete_multipart_upload { days_after_initiation = 7 } } + # CloudFront access records (CDS-TRC-ACL) are kept 90 days, not 400: the + # operator's privacy limit. S3 applies the earliest expiration when rules + # overlap, so these prefixes expire at 90 days. Only aggregate monthly + # summaries outlive them (/.well-known/access-summary.json, 13 months). + rule { + id = "expire-edge-access-records" + status = "Enabled" + filter { prefix = "cloudfront/" } + expiration { days = 90 } + noncurrent_version_expiration { noncurrent_days = 1 } + abort_incomplete_multipart_upload { days_after_initiation = 7 } + } + rule { + id = "expire-edge-access-records-default-prefix" + status = "Enabled" + filter { prefix = "AWSLogs/${data.aws_caller_identity.current.account_id}/CloudFront/" } + expiration { days = 90 } + noncurrent_version_expiration { noncurrent_days = 1 } + abort_incomplete_multipart_upload { days_after_initiation = 7 } + } } # Allow the AWS log-delivery services to write to their respective prefixes, @@ -86,7 +106,13 @@ resource "aws_s3_bucket_policy" "logs" { Effect = "Allow" Principal = { Service = "delivery.logs.amazonaws.com" } Action = "s3:PutObject" - Resource = "${aws_s3_bucket.logs.arn}/cloudfront/*" + # cloudfront/ is the configured prefix (bootstrap/trust-access-logs.tf); + # AWSLogs//CloudFront/ is the service's default, kept so a + # delivery that ignores the prefix still lands under the 90-day expiry. + Resource = [ + "${aws_s3_bucket.logs.arn}/cloudfront/*", + "${aws_s3_bucket.logs.arn}/AWSLogs/${data.aws_caller_identity.current.account_id}/CloudFront/*", + ] Condition = { StringEquals = { "aws:SourceAccount" = data.aws_caller_identity.current.account_id } } diff --git a/infrastructure/schemas/freshness-config.json b/infrastructure/schemas/freshness-config.json index 888561ba..046d604b 100644 --- a/infrastructure/schemas/freshness-config.json +++ b/infrastructure/schemas/freshness-config.json @@ -189,6 +189,18 @@ "signed": true, "signature": ".well-known/policy-index.bundle" }, + { + "path": ".well-known/access-summary.json", + "cadence": "deploy", + "max_age_hours": 720, + "timestamp": { + "source": "json", + "field": "emitted_at" + }, + "signed": true, + "signature": ".well-known/access-summary.bundle", + "note": "Monthly aggregate counts of access to the certification data (CDS-TRC-ACL), rebuilt from the CloudFront access records on every deploy." + }, { "path": ".well-known/security-decision-record.json", "cadence": "deploy", diff --git a/scripts/availability-probe.py b/scripts/availability-probe.py new file mode 100644 index 00000000..454fa5f0 --- /dev/null +++ b/scripts/availability-probe.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 +"""Independent availability monitor (CDS-CSO-AVR, CDS-TRC-USH). + +Runs on GitHub Actions (.github/workflows/availability-probe.yml), outside AWS, +so it keeps reporting when the offering is down. Each run probes the core +services once over HTTPS, appends the result to the rolling history carried in +the previous feed, derives availability incidents, and writes: + + availability-status.json machine-readable: current status, 30-day + availability per service, incidents, samples + availability-status.md the same for people + +The workflow publishes both to the repository's `availability-status` branch, +served by GitHub (raw.githubusercontent.com and the github.com file view), not +by the offering's own CloudFront or S3. + +An incident is a service failing on INCIDENT_MIN_SAMPLES or more consecutive +probes; it starts at the first failing probe and ends at the next passing one. +A single failed probe is counted as transient, not an incident, since one probe +from one runner can fail for reasons on the runner's side. + + availability-probe.py --previous prev.json --out-dir status (probe) + availability-probe.py --check-fresh feed.json --max-age-hours 2 (deploy guard) +""" +import argparse +import json +import sys +import time +import urllib.error +import urllib.request +from datetime import datetime, timedelta, timezone +from pathlib import Path + +SITE = "https://samaydlette.com" +COGNITO_UI = "https://samaydlette-com-silk-reeling.auth.us-east-2.amazoncognito.com/" +# (key, service, url, statuses that mean "up") +TARGETS = ( + ("site", "Website", f"{SITE}/", (200,)), + ("trust-center", "Trust center", f"{SITE}/trust/", (200,)), + ("certification-data", "Certification data (/.well-known/)", f"{SITE}/.well-known/ksi-signal.json", (200,)), + ("silk-reeling", "Silk Reeling application", f"{SITE}/silk-reeling/", (200,)), + ("silk-reeling-sign-in", "Silk Reeling sign-in (Cognito hosted UI)", COGNITO_UI, (200,)), +) +HISTORY_DAYS = 35 +WINDOW_DAYS = 30 +INCIDENT_MIN_SAMPLES = 2 +TIMEOUT_S = 20 +FEED_URL = ("https://raw.githubusercontent.com/sam-aydlette/samaydlette.com/" + "availability-status/availability-status.json") +PAGE_URL = ("https://github.com/sam-aydlette/samaydlette.com/blob/" + "availability-status/availability-status.md") + + +def _iso(dt): + return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z") + + +def _parse(s): + return datetime.fromisoformat(str(s).replace("Z", "+00:00")) + + +def fetch(url): + """(up-or-status reason, HTTP status or None). No redirects followed.""" + class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, *a, **k): + return None + opener = urllib.request.build_opener(NoRedirect) + req = urllib.request.Request(url, headers={"User-Agent": "samaydlette-availability-probe"}) + try: + with opener.open(req, timeout=TIMEOUT_S) as resp: # nosec B310: fixed https URLs + resp.read(4096) + return resp.status + except urllib.error.HTTPError as exc: + return exc.code + except (urllib.error.URLError, OSError) as exc: + return f"no response ({type(getattr(exc, 'reason', exc)).__name__})" + + +def probe_once(fetcher, now): + sample = {"t": _iso(now), "probed": [k for k, *_ in TARGETS], "fail": {}} + for key, _service, url, ok in TARGETS: + got = fetcher(url) + if got not in ok: + sample["fail"][key] = f"HTTP {got}" if isinstance(got, int) else str(got) + return sample + + +def incidents(samples): + """Incidents (>= INCIDENT_MIN_SAMPLES consecutive failures) and transient counts per service.""" + out, transient = [], {} + services = {k: s for k, s, *_ in TARGETS} + for key in services: + run = [] + seq = [s for s in samples if key in s.get("probed", [])] + for i, s in enumerate(seq + [None]): + failed = s is not None and key in s.get("fail", {}) + if failed: + run.append(s) + continue + if len(run) >= INCIDENT_MIN_SAMPLES: + out.append({"service": key, "service_name": services[key], "start": run[0]["t"], + "end": s["t"] if s is not None else None, "failed_probes": len(run), + "failing_check": run[-1]["fail"][key]}) + elif run: + transient[key] = transient.get(key, 0) + len(run) + run = [] + return sorted(out, key=lambda x: (x["start"], x["service"])), transient + + +def availability(samples, now): + since = now - timedelta(days=WINDOW_DAYS) + out = {} + for key, service, url, _ok in TARGETS: + seq = [s for s in samples if key in s.get("probed", []) and _parse(s["t"]) >= since] + up = sum(1 for s in seq if key not in s.get("fail", {})) + out[key] = {"service": service, "url": url, "probes": len(seq), "up": up, + "availability_percent": round(100.0 * up / len(seq), 3) if seq else None} + return out + + +def build(previous, sample, now): + prev_samples = [s for s in (previous or {}).get("samples", []) if isinstance(s, dict) and "t" in s] + cutoff = now - timedelta(days=HISTORY_DAYS) + samples = [s for s in prev_samples if _parse(s["t"]) >= cutoff] + [sample] + began = (previous or {}).get("history_began") or sample["t"] + incs, transient = incidents(samples) + window_start = _iso(now - timedelta(days=WINDOW_DAYS)) + return { + "feed_type": "availability-status", + "rules": ["CDS-CSO-AVR", "CDS-TRC-USH"], + "generated_at": sample["t"], + "monitor": "GitHub Actions (.github/workflows/availability-probe.yml), outside AWS: it keeps " + "reporting when the offering is unavailable.", + "published_at": {"json": FEED_URL, "human": PAGE_URL}, + "history_began": began, + "history_note": "History begins at the monitor's first run; before that no independent " + "measurement exists. Scheduled runs are every 15 minutes, and GitHub may delay one.", + "incident_rule": f"{INCIDENT_MIN_SAMPLES} or more consecutive failed probes of one service; a single " + "failed probe is counted as transient.", + "current": {k: ("down" if k in sample["fail"] else "up") for k, *_ in TARGETS}, + "current_failures": sample["fail"], + "window_days": WINDOW_DAYS, + "availability": availability(samples, now), + "incidents": [i for i in incs if (i["end"] or "9999") >= window_start], + "transient_failures": transient, + "samples": samples, + } + + +def render_markdown(doc): + cur = doc["current"] + out = ["# Service availability (independent monitor)", "", + f"_{doc['monitor']}_", "", + f"- **Last probe:** {doc['generated_at']}", + f"- **History began:** {doc['history_began']}. {doc['history_note']}", + f"- **Incident rule:** {doc['incident_rule']}", + f"- **Machine-readable:** {doc['published_at']['json']}", "", + "## Now and over the past 30 days", "", + "| Service | Now | Availability (30 days) | Probes |", "|---|---|---|---|"] + for key, a in doc["availability"].items(): + pct = "n/a" if a["availability_percent"] is None else f"{a['availability_percent']}%" + out.append(f"| {a['service']} | {cur.get(key, 'n/a')} | {pct} | {a['probes']} |") + out += ["", "## Availability incidents (past 30 days)", ""] + if not doc["incidents"]: + out.append("None.") + else: + out += ["| Service | Start | End | Failed probes | Failing check |", "|---|---|---|---|---|"] + for i in reversed(doc["incidents"]): + out.append(f"| {i['service_name']} | {i['start']} | {i['end'] or 'ongoing'} | " + f"{i['failed_probes']} | {i['failing_check']} |") + if doc["transient_failures"]: + out += ["", "Transient (single) failed probes: " + + ", ".join(f"{k} {v}" for k, v in sorted(doc["transient_failures"].items()))] + out += ["", "---", "_Source of truth: `availability-status.json` on this branch._"] + return "\n".join(out) + + +def ongoing_incidents(doc): + return [i for i in doc.get("incidents", []) if i.get("end") is None] + + +def check_fresh(path, max_age_hours, now=None): + """Problems with a fetched feed: [] when it is ours, well formed and fresh.""" + now = now or datetime.now(timezone.utc) + try: + doc = json.loads(Path(path).read_text()) + except (OSError, json.JSONDecodeError): + return ["the independent availability feed is missing or not JSON"] + if doc.get("feed_type") != "availability-status": + return ["the independent availability feed is not an availability-status document"] + try: + age = now - _parse(doc["generated_at"]) + except (KeyError, ValueError): + return ["the independent availability feed has no generated_at"] + if age > timedelta(hours=max_age_hours): + return [f"the independent availability feed is {age} old (limit {max_age_hours} h): the monitor " + "on GitHub Actions is not running"] + if not doc.get("samples"): + return ["the independent availability feed carries no probes"] + return [] + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--previous", default=None) + ap.add_argument("--out-dir", default=".") + ap.add_argument("--check-fresh", default=None, metavar="FEED") + ap.add_argument("--max-age-hours", type=float, default=2.0) + ap.add_argument("--fail-on-incident", default=None, metavar="FEED", + help="exit 1 when FEED shows an ongoing incident (the workflow's alert)") + a = ap.parse_args(argv) + if a.fail_on_incident: + doc = json.loads(Path(a.fail_on_incident).read_text()) + ongoing = ongoing_incidents(doc) + for i in ongoing: + print(f"::error::availability incident: {i['service_name']} down since {i['start']} " + f"({i['failing_check']})", file=sys.stderr) + return 1 if ongoing else 0 + if a.check_fresh: + why = check_fresh(a.check_fresh, a.max_age_hours) + for w in why: + print(f"::error::availability: {w}", file=sys.stderr) + if not why: + print("ok: the independent availability feed is present and fresh") + return 1 if why else 0 + previous = {} + if a.previous and Path(a.previous).exists(): + try: + previous = json.loads(Path(a.previous).read_text()) + except json.JSONDecodeError: + previous = {} + if previous.get("feed_type") != "availability-status": + previous = {} + started = time.monotonic() + now = datetime.now(timezone.utc) + doc = build(previous, probe_once(fetch, now), now) + out = Path(a.out_dir) + out.mkdir(parents=True, exist_ok=True) + (out / "availability-status.json").write_text(json.dumps(doc, indent=1) + "\n") + (out / "availability-status.md").write_text(render_markdown(doc) + "\n") + down = sorted(doc["current_failures"]) + print(f"probed {len(TARGETS)} services in {time.monotonic() - started:.1f}s; down: {down or 'none'}; " + f"{len(doc['samples'])} samples kept") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-access-summary.py b/scripts/build-access-summary.py new file mode 100644 index 00000000..581b4b70 --- /dev/null +++ b/scripts/build-access-summary.py @@ -0,0 +1,203 @@ +#!/usr/bin/env python3 +"""Monthly access summaries for the certification data (CDS-TRC-ACL). + +Reads the CloudFront access records the deploy synced from the log bucket (JSON +lines, gzipped or plain, one object per request with the fields the delivery +keeps: see scripts/check-edge-access-logging.py ALLOWED_FIELDS) and writes +access-summary.json (+ .md): per month, how many requests reached each +certification artifact under /.well-known/ and the trust center under /trust/, +by response class and by country. Nothing else. + +Privacy (operator's condition, 2026-11-05): +- Only /.well-known/ and /trust/ requests are counted; every other record is + discarded unread beyond its path. CloudFront cannot limit logging by path, so + this is where the limit is applied. +- A path is published by name only when it served an object (2xx or 304). + Requests for anything else (probes for files that do not exist, errors) are + counted under "other", so a requester cannot write a string into this file. +- No IP, user agent, referrer, cookie or query string exists in the records; + the summary carries counts only. + +Retention: raw records expire after 90 days (infrastructure/logging.tf). Each +month's summary is carried forward from the previously published file, so +summaries are kept for MONTHS_KEPT months (FedRAMP asks for at least six). A +month is recomputed from the records only when they cover at least as much of it +as the published summary did, so a month whose early days have expired keeps its +fuller earlier count. +""" +import argparse +import gzip +import json +import re +import sys +from collections import Counter +from datetime import date, datetime, timezone +from pathlib import Path + +MONTHS_KEPT = 13 +MIN_MONTHS_KEPT = 6 +PREFIXES = ("/.well-known/", "/trust/") +SAFE_PATH = re.compile(r"^/[A-Za-z0-9._/-]{0,200}$") +SERVED = re.compile(r"^(2\d\d|304)$") +COUNTRY = re.compile(r"^[A-Z]{2}$") +OTHER = "other (not found, error, or not an object)" + + +def _fail(msg): + raise SystemExit(f"::error::access summary: {msg} (fail-closed)") + + +def read_records(root): + """Yield one dict per access record under root (*.gz or plain JSON lines).""" + for p in sorted(Path(root).rglob("*")) if Path(root).is_dir() else []: + if not p.is_file(): + continue + opener = gzip.open if p.suffix == ".gz" else open + try: + with opener(p, "rt", encoding="utf-8") as fh: + for line in fh: + line = line.strip() + if not line: + continue + try: + rec = json.loads(line) + except json.JSONDecodeError: + _fail(f"{p.name} holds a line that is not JSON") + if isinstance(rec, dict): + yield rec + except (OSError, EOFError) as exc: + _fail(f"{p.name} could not be read ({type(exc).__name__})") + + +def _artifact(stem, status): + if not SERVED.match(str(status)) or not SAFE_PATH.match(stem or ""): + return OTHER + if stem.startswith("/trust/"): + return "/trust/" if stem in ("/trust/", "/trust/index.html") else stem + return stem + + +def summarize(records): + """{month: {"requests", "artifacts", "countries", "status_classes", "first", "last"}}""" + months = {} + for r in records: + stem = r.get("cs-uri-stem") or "" + if not stem.startswith(PREFIXES): + continue + day = str(r.get("date") or "") + try: + d = date.fromisoformat(day) + except ValueError: + continue + m = months.setdefault(d.strftime("%Y-%m"), {"requests": 0, "artifacts": Counter(), "countries": Counter(), + "status_classes": Counter(), "first": day, "last": day}) + status = str(r.get("sc-status") or "") + m["requests"] += 1 + m["artifacts"][_artifact(stem, status)] += 1 + cc = str(r.get("c-country") or "") + m["countries"][cc if COUNTRY.match(cc) else "unknown"] += 1 + m["status_classes"][(status[:1] + "xx") if status[:1].isdigit() else "unknown"] += 1 + m["first"], m["last"] = min(m["first"], day), max(m["last"], day) + return months + + +def _month_entry(month, m, now): + return {"month": month, "coverage_from": m["first"], "coverage_to": m["last"], + "requests": m["requests"], + "artifacts": dict(sorted(m["artifacts"].items())), + "countries": dict(sorted(m["countries"].items())), + "status_classes": dict(sorted(m["status_classes"].items())), + "computed_at": now.isoformat()} + + +def merge(previous, computed, now): + """Carry earlier months forward; recompute a month only when the records cover + at least as much of it as the published entry did.""" + by_month = {e["month"]: e for e in (previous or {}).get("months", []) if isinstance(e, dict) and "month" in e} + for month, m in computed.items(): + old = by_month.get(month) + if old is None or m["first"] <= old.get("coverage_from", "9999"): + by_month[month] = _month_entry(month, m, now) + kept = sorted(by_month.values(), key=lambda e: e["month"])[-MONTHS_KEPT:] + return kept + + +def build(previous, records, now): + months = merge(previous, summarize(records), now) + started = (previous or {}).get("logging_records_since") + firsts = [e["coverage_from"] for e in months] + if firsts: + started = min([started] + firsts) if started else min(firsts) + return { + "artifact": "access-summary", + "rule": "CDS-TRC-ACL", + "emitted_at": now.isoformat(), + "scope": "Requests to the certification data under /.well-known/ and to the trust center under /trust/.", + "logged_fields": "date, time, edge location, country, method, path, status, bytes, cache result. " + "No IP address, user agent, referrer, cookie or query string is logged.", + "raw_record_retention_days": 90, + "summary_retention_months": MONTHS_KEPT, + "logging_records_since": started, + "party_records": "A party can ask for the summaries and for the records of its own requests, " + "identified by the times and paths it gives (no requester identity is logged); " + "see the trust center's privacy notice and DEC-160.", + "months": months, + } + + +def render_markdown(doc): + out = ["# Trust center access summary", "", + f"_{doc['scope']}_", "", + f"- **Emitted:** {doc['emitted_at']}", + f"- **Logged fields:** {doc['logged_fields']}", + f"- **Raw records kept:** {doc['raw_record_retention_days']} days; " + f"**summaries kept:** {doc['summary_retention_months']} months", + f"- **Records since:** {doc['logging_records_since'] or 'none yet'}", + f"- **Your own records:** {doc['party_records']}", ""] + if not doc["months"]: + out += ["No access records yet.", ""] + for m in reversed(doc["months"]): + out += [f"## {m['month']}", "", + f"{m['requests']} requests, {m['coverage_from']} to {m['coverage_to']}. " + f"By status: {', '.join(f'{k} {v}' for k, v in m['status_classes'].items())}. " + f"By country: {', '.join(f'{k} {v}' for k, v in m['countries'].items())}.", "", + "| Artifact | Requests |", "|---|---|"] + for path, n in sorted(m["artifacts"].items(), key=lambda kv: (-kv[1], kv[0])): + out.append(f"| `{path}` | {n} |") + out.append("") + out += ["---", "_Source of truth: the signed `access-summary.json` (CDS-TRC-ACL)._"] + return "\n".join(out) + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--records", required=True, help="directory of synced CloudFront access records") + ap.add_argument("--previous", default=None, help="the previously published access-summary.json") + ap.add_argument("--output", default="access-summary.json") + ap.add_argument("--md-output", default="access-summary.md") + a = ap.parse_args(argv) + previous = {} + if a.previous and Path(a.previous).exists(): + try: + previous = json.loads(Path(a.previous).read_text()) + except json.JSONDecodeError: + previous = {} + if previous and previous.get("artifact") != "access-summary": + previous = {} + now = datetime.now(timezone.utc) + doc = build(previous, read_records(a.records), now) + prev_months = {e["month"] for e in previous.get("months", [])} if previous else set() + # Never drop a month younger than the six FedRAMP requires. + newest = sorted(prev_months | {e["month"] for e in doc["months"]})[-MIN_MONTHS_KEPT:] + lost = sorted(set(newest) - {e["month"] for e in doc["months"]}) + if lost: + _fail(f"would drop month(s) {lost} younger than {MIN_MONTHS_KEPT} months") + Path(a.output).write_text(json.dumps(doc, indent=2) + "\n") + if a.md_output: + Path(a.md_output).write_text(render_markdown(doc) + "\n") + print(f"access-summary: {len(doc['months'])} month(s); records since {doc['logging_records_since']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-availability.py b/scripts/build-availability.py index d020e9c8..1aa71850 100644 --- a/scripts/build-availability.py +++ b/scripts/build-availability.py @@ -1,89 +1,143 @@ #!/usr/bin/env python3 # ============================================================================= -# AVAILABILITY FEED BUILDER (CR26 CDS-CSO-AVR) +# AVAILABILITY FEED BUILDER (CR26 CDS-CSO-AVR, CDS-TRC-USH) # ============================================================================= -# CR26 CDS-CSO-AVR (Class C MUST) requires a web service indicating current and -# historical availability of core services over at least the past 30 days, in -# both human-readable and machine-readable formats, available even if the primary -# offering is unavailable. This builds the machine + human feed as an append-only -# history: each deploy appends a datapoint to the previous published feed and -# trims to a rolling window. A deploy that produces this feed is, by definition, -# a successful one, so the current datapoint is "available". +# CDS-CSO-AVR (Class C MUST): a web service showing current and historical +# availability of core services over at least the past 30 days, including +# availability incidents, human- and machine-readable, and available even when +# the offering is not. # -# HONEST RESIDUAL: this feed is served from the same CloudFront/S3 path as the -# offering, so the "available even if the primary offering is unavailable" clause -# is only partially met — full conformance needs an independent monitor on -# separate infrastructure. That gap is stated in the feed itself, not hidden. +# The measurement is made outside AWS: scripts/availability-probe.py runs on +# GitHub Actions every 15 minutes and publishes its feed on GitHub (the +# repository's availability-status branch), which stays reachable when the +# offering's CloudFront or S3 is down. That is the service the rule asks for. # -# build-availability.py --previous previous-availability.json +# This builder republishes the same measurements on the site, signed with the +# rest of the certification data, so the package carries them: the deploy reads +# the independent feed (and fails when it is missing or stale), and this writes +# availability.json + availability.md from it: current status, 30-day +# availability and incidents per service, and a daily roll-up. It never records +# a deploy as availability. +# +# build-availability.py --probe-feed availability-probe.json --ksi-signal ksi-signal.json # ============================================================================= import argparse +import importlib.util import json import sys -from datetime import datetime, timezone +from collections import defaultdict +from datetime import datetime, timedelta, timezone from pathlib import Path -WINDOW_DAYS = 45 # keep >= 30 days of history per CDS-CSO-AVR +_spec = importlib.util.spec_from_file_location( + "availability_probe", Path(__file__).resolve().parent / "availability-probe.py") +assert _spec is not None and _spec.loader is not None +probe = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(probe) + +MAX_FEED_AGE_HOURS = 2.0 + + +def _fail(msg): + raise SystemExit(f"::error::availability: {msg} (fail-closed)") + + +def daily(samples, now, days=probe.WINDOW_DAYS): + """[{date, services: {key: {probes, up}}}] for the past `days` days.""" + since = (now - timedelta(days=days)).date() + by_day = defaultdict(lambda: defaultdict(lambda: {"probes": 0, "up": 0})) + for s in samples: + d = probe._parse(s["t"]).date() + if d < since: + continue + for key in s.get("probed", []): + cell = by_day[d.isoformat()][key] + cell["probes"] += 1 + cell["up"] += 0 if key in s.get("fail", {}) else 1 + return [{"date": d, "services": {k: dict(v) for k, v in sorted(svcs.items())}} + for d, svcs in sorted(by_day.items())] + + +def build(feed, signal_id, now): + return { + "feed_type": "availability", + "rules": ["CDS-CSO-AVR", "CDS-TRC-USH"], + "emitted_at": now.isoformat(), + "ksi_signal_id": signal_id, + "measured_by": feed["monitor"], + "independent_service": feed["published_at"], + "independent_note": "This file is a signed copy carried in the certification package. The service " + "that stays available when the offering is down is the independent one above, " + "served by GitHub.", + "measured_at": feed["generated_at"], + "history_began": feed["history_began"], + "history_note": feed["history_note"], + "incident_rule": feed["incident_rule"], + "current": feed["current"], + "current_failures": feed["current_failures"], + "window_days": feed["window_days"], + "availability": feed["availability"], + "incidents": feed["incidents"], + "transient_failures": feed["transient_failures"], + "daily": daily(feed["samples"], now), + } + +def render_markdown(doc): + out = ["# Service availability", "", + f"_Measured independently: {doc['measured_by']}_", "", + f"- **Last probe:** {doc['measured_at']} | **Emitted:** {doc['emitted_at']}", + f"- **Independent status page (available when this site is not):** {doc['independent_service']['human']}", + f"- **History began:** {doc['history_began']}. {doc['history_note']}", + f"- **Incident rule:** {doc['incident_rule']}", "", + "| Service | Now | Availability (30 days) | Probes |", "|---|---|---|---|"] + for key, a in doc["availability"].items(): + pct = "n/a" if a["availability_percent"] is None else f"{a['availability_percent']}%" + out.append(f"| {a['service']} | {doc['current'].get(key, 'n/a')} | {pct} | {a['probes']} |") + out += ["", "## Availability incidents (past 30 days)", ""] + if not doc["incidents"]: + out.append("None.") + else: + out += ["| Service | Start | End | Failed probes | Failing check |", "|---|---|---|---|---|"] + for i in reversed(doc["incidents"]): + out.append(f"| {i['service_name']} | {i['start']} | {i['end'] or 'ongoing'} | " + f"{i['failed_probes']} | {i['failing_check']} |") + out += ["", "## Daily (passing probes / probes)", "", "| Date | " + " | ".join(doc["availability"]) + " |", + "|---|" + "---|" * len(doc["availability"])] + for day in reversed(doc["daily"]): + cells = [] + for key in doc["availability"]: + c = day["services"].get(key) + cells.append(f"{c['up']}/{c['probes']}" if c else "—") + out.append(f"| {day['date']} | " + " | ".join(cells) + " |") + out += ["", "---", "_Source of truth: the signed `availability.json` (CDS-CSO-AVR)._"] + return "\n".join(out) -def main(): + +def main(argv=None): ap = argparse.ArgumentParser() - ap.add_argument("--previous", default=None, help="Previous published availability.json (for history)") + ap.add_argument("--probe-feed", required=True, + help="the independent monitor's availability-status.json, fetched from GitHub") ap.add_argument("--ksi-signal", default="ksi-signal.json") ap.add_argument("--output", default="availability.json") ap.add_argument("--md-output", default="availability.md") - a = ap.parse_args() + a = ap.parse_args(argv) now = datetime.now(timezone.utc) - today = now.date().isoformat() - - history = [] - if a.previous and Path(a.previous).exists(): - try: - history = json.loads(Path(a.previous).read_text()).get("history", []) or [] - except Exception: - history = [] - # Append today (idempotent: one datapoint per day). - history = [h for h in history if h.get("date") != today] - history.append({"date": today, "status": "available", - "detail": "deploy succeeded; core services served via CloudFront"}) - # Trim to the rolling window (keep the most recent WINDOW_DAYS dated points). - history = sorted(history, key=lambda h: h.get("date", ""))[-WINDOW_DAYS:] - + why = probe.check_fresh(a.probe_feed, MAX_FEED_AGE_HOURS, now) + if why: + _fail("; ".join(why)) + feed = json.loads(Path(a.probe_feed).read_text()) signal_id = None if Path(a.ksi_signal).exists(): signal_id = json.loads(Path(a.ksi_signal).read_text()).get("signal_id") - - up = sum(1 for h in history if h.get("status") == "available") - feed = { - "feed_type": "availability", - "rule": "CDS-CSO-AVR", - "emitted_at": now.isoformat(), - "ksi_signal_id": signal_id, - "current_status": "available", - "window_days": WINDOW_DAYS, - "history_points": len(history), - "uptime_observed": f"{up}/{len(history)} observed days available", - "residual": ("This feed is served from the same CloudFront/S3 path as the offering; " - "the CDS-CSO-AVR clause requiring availability reporting even when the " - "primary offering is unavailable is only partially met. Full conformance " - "requires an independent monitor on separate infrastructure."), - "history": history, - } - Path(a.output).write_text(json.dumps(feed, indent=2) + "\n") + doc = build(feed, signal_id, now) + Path(a.output).write_text(json.dumps(doc, indent=2) + "\n") if a.md_output: - out = ["# Service Availability", "", - f"- **Current status:** {feed['current_status']}", - f"- **Observed window:** {feed['uptime_observed']} (rolling {WINDOW_DAYS} days)", - f"- **Emitted:** {feed['emitted_at']}", "", - f"> {feed['residual']}", "", - "| Date | Status |", "|---|---|"] - for h in reversed(history): - out.append(f"| {h['date']} | {h['status']} |") - out += ["", "---", "_Source of truth: the machine-readable `availability.json` (CDS-CSO-AVR)._"] - Path(a.md_output).write_text("\n".join(out) + "\n") - print(f"availability: {len(history)} day(s) of history; current=available") + Path(a.md_output).write_text(render_markdown(doc) + "\n") + down = sorted(k for k, v in doc["current"].items() if v != "up") + print(f"availability: {len(doc['incidents'])} incident(s) in {doc['window_days']} days; down now: {down or 'none'}") return 0 diff --git a/scripts/check-edge-access-logging.py b/scripts/check-edge-access-logging.py new file mode 100644 index 00000000..92fc97d9 --- /dev/null +++ b/scripts/check-edge-access-logging.py @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 +"""Access to the certification data is logged, within the privacy limits (CDS-TRC-ACL). + +Reads the CloudFront standard-logging (v2) configuration the deploy role can see +and fails unless: + + * a delivery from the source named for this site exists; + * that source is the CloudFront distribution's ACCESS_LOGS; + * the delivery goes to S3; and + * its record fields are exactly within ALLOWED_FIELDS and include REQUIRED_FIELDS. + +ALLOWED_FIELDS is the operator's privacy condition: no client IP, forwarded-for, +port, cookies, query string, user agent or referrer is ever logged. It must equal +the delivery's record_fields in infrastructure/bootstrap/trust-access-logs.tf +(tests/test_edge_access_logging.py holds them equal). The configuration is +operator-applied (bootstrap), so this check is what fails the deploy when it is +missing, before the trust center or the SDR say access is logged. + +Inputs are the AWS CLI's JSON (aws logs describe-deliveries, aws logs +get-delivery-source), so the check runs the same on fixtures. Prints no ARN. +""" +import argparse +import json +import sys +from pathlib import Path + +ALLOWED_FIELDS = ("date", "time", "x-edge-location", "c-country", "cs-method", "cs-uri-stem", + "sc-status", "sc-bytes", "x-edge-result-type") +REQUIRED_FIELDS = ("date", "time", "cs-uri-stem", "sc-status") +# Named so the failure message says what was found; any field outside +# ALLOWED_FIELDS fails, whether or not it is listed here. +IDENTIFYING = ("c-ip", "x-forwarded-for", "c-port", "cs(Cookie)", "cs-uri-query", "cs(User-Agent)", + "cs(Referer)") + + +def problems(deliveries, source, name): + out = [] + mine = [d for d in (deliveries or {}).get("deliveries", []) if d.get("deliverySourceName") == name] + if not mine: + return [f"no CloudFront access-log delivery from source {name!r} (bootstrap not applied?)"] + if len(mine) > 1: + out.append(f"{len(mine)} deliveries from {name!r}; expected one") + src = (source or {}).get("deliverySource") or {} + if src.get("name") != name: + out.append(f"delivery source {name!r} could not be read") + if src.get("logType") != "ACCESS_LOGS": + out.append(f"delivery source log type is {src.get('logType')!r}, not ACCESS_LOGS") + if not any(":distribution/" in a and a.startswith("arn:aws:cloudfront::") for a in src.get("resourceArns") or []): + out.append("delivery source is not a CloudFront distribution") + for d in mine: + if d.get("deliveryDestinationType") != "S3": + out.append(f"delivery destination type is {d.get('deliveryDestinationType')!r}, not S3") + fields = d.get("recordFields") or [] + extra = sorted(set(fields) - set(ALLOWED_FIELDS)) + bad = sorted(f for f in extra if f in IDENTIFYING) + if bad: + out.append(f"delivery logs identifying field(s) {bad}") + if sorted(set(extra) - set(bad)): + out.append(f"delivery logs field(s) outside the privacy allowlist: {sorted(set(extra) - set(bad))}") + missing = sorted(set(REQUIRED_FIELDS) - set(fields)) + if missing: + out.append(f"delivery omits required field(s) {missing}") + return out + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--deliveries", required=True, help="aws logs describe-deliveries output") + ap.add_argument("--source", required=True, help="aws logs get-delivery-source output (may be empty)") + ap.add_argument("--name", required=True, help="the delivery source's name") + a = ap.parse_args(argv) + + def read(p): + t = Path(p).read_text() if Path(p).exists() else "" + try: + return json.loads(t) if t.strip() else {} + except json.JSONDecodeError: + return {} + why = problems(read(a.deliveries), read(a.source), a.name) + for w in why: + print(f"::error::edge access logging: {w}", file=sys.stderr) + if why: + print("Access to the certification data is not logged as the trust center states; " + "the deploy does not proceed.", file=sys.stderr) + return 1 + print(f"ok: CloudFront access logging to S3, fields {', '.join(ALLOWED_FIELDS)} " + "(no IP, cookies, query string or user agent)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check-wellknown-headers.py b/scripts/check-wellknown-headers.py new file mode 100644 index 00000000..4ea01002 --- /dev/null +++ b/scripts/check-wellknown-headers.py @@ -0,0 +1,83 @@ +#!/usr/bin/env python3 +"""The public JSON under /.well-known/ is servable to any program (FRC-CSO-JSN). + +Fetches each named artifact over HTTPS from the live site, as a browser on +another origin would (an Origin header), and fails unless the response carries: + + * Access-Control-Allow-Origin: * (CORS: a page on any origin can read it) + * a JSON Content-Type (application/json or application/*+json) + * X-Content-Type-Options: nosniff (the browser keeps that type) + +The headers come from the CloudFront response-headers policy for /.well-known/* +(infrastructure/bootstrap/cloudfront.tf), which the operator applies; this step +is what makes the deploy fail when that apply is missing. Read-only; stdlib only. + + check-wellknown-headers.py --site https://samaydlette.com ksi-signal.json ... + check-wellknown-headers.py --fixture headers.json (tests: {name: {header: value}}) +""" +import argparse +import json +import sys +import urllib.error +import urllib.request + +ORIGIN = "https://example.org" +DEFAULT_ARTIFACTS = ("ksi-signal.json", "security-decision-record.json", "trust-center.json", + "vdr-report.json", "certification-package-overview.json") + + +def problems(headers): + """[reason, ...] for one response's headers (names case-insensitive).""" + h = {k.lower(): (v or "").strip() for k, v in headers.items()} + out = [] + if h.get("access-control-allow-origin") != "*": + out.append(f"Access-Control-Allow-Origin is {h.get('access-control-allow-origin')!r}, not '*'") + ctype = h.get("content-type", "").split(";")[0].strip().lower() + if not (ctype == "application/json" or (ctype.startswith("application/") and ctype.endswith("+json"))): + out.append(f"Content-Type is {ctype or 'absent'!r}, not JSON") + if h.get("x-content-type-options", "").lower() != "nosniff": + out.append("X-Content-Type-Options: nosniff is absent") + return out + + +def fetch(url, timeout=20): + req = urllib.request.Request(url, method="GET", headers={"Origin": ORIGIN, "User-Agent": "samaydlette-header-check"}) + with urllib.request.urlopen(req, timeout=timeout) as resp: # nosec B310: fixed https URL + return dict(resp.headers.items()) + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--site", default="https://samaydlette.com") + ap.add_argument("--fixture", default=None, help="JSON {artifact: {header: value}} instead of the network") + ap.add_argument("artifacts", nargs="*", default=None) + a = ap.parse_args(argv) + if not a.site.startswith("https://"): + print("::error::--site must be an https:// URL", file=sys.stderr) + return 2 + fixture = json.loads(open(a.fixture).read()) if a.fixture else None + names = a.artifacts or (sorted(fixture) if fixture is not None else list(DEFAULT_ARTIFACTS)) + failed = 0 + for name in names: + url = f"{a.site.rstrip('/')}/.well-known/{name}" + try: + headers = fixture[name] if fixture is not None else fetch(url) + except (urllib.error.URLError, OSError, KeyError) as exc: + print(f"::error::{url}: could not be read ({type(exc).__name__})", file=sys.stderr) + failed += 1 + continue + why = problems(headers) + for w in why: + print(f"::error::{url}: {w}", file=sys.stderr) + failed += bool(why) + if not why: + print(f"ok: {url} (CORS *, JSON, nosniff)") + if failed: + print(f"{failed} artifact(s) under /.well-known/ lack the required headers; the deploy does not proceed.", + file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/availability/known-bad-stale-feed.json b/tests/fixtures/availability/known-bad-stale-feed.json new file mode 100644 index 00000000..14961cf8 --- /dev/null +++ b/tests/fixtures/availability/known-bad-stale-feed.json @@ -0,0 +1,2 @@ +{"feed_type": "availability-status", "generated_at": "2026-10-01T00:00:00Z", + "samples": [{"t": "2026-10-01T00:00:00Z", "probed": ["site"], "fail": {}}]} diff --git a/tests/fixtures/edge-access-logging/delivery-source.json b/tests/fixtures/edge-access-logging/delivery-source.json new file mode 100644 index 00000000..887662fc --- /dev/null +++ b/tests/fixtures/edge-access-logging/delivery-source.json @@ -0,0 +1,2 @@ +{"deliverySource": {"name": "samaydlette-com-edge-access", "logType": "ACCESS_LOGS", "service": "cloudfront", + "resourceArns": ["arn:aws:cloudfront::ACCOUNT:distribution/EXAMPLE"]}} diff --git a/tests/fixtures/edge-access-logging/good-deliveries.json b/tests/fixtures/edge-access-logging/good-deliveries.json new file mode 100644 index 00000000..4fa9b6d8 --- /dev/null +++ b/tests/fixtures/edge-access-logging/good-deliveries.json @@ -0,0 +1,3 @@ +{"deliveries": [{"id": "fixture", "deliverySourceName": "samaydlette-com-edge-access", + "deliveryDestinationType": "S3", + "recordFields": ["date", "time", "x-edge-location", "c-country", "cs-method", "cs-uri-stem", "sc-status", "sc-bytes", "x-edge-result-type"]}]} diff --git a/tests/fixtures/edge-access-logging/known-bad-deliveries.json b/tests/fixtures/edge-access-logging/known-bad-deliveries.json new file mode 100644 index 00000000..3381be4a --- /dev/null +++ b/tests/fixtures/edge-access-logging/known-bad-deliveries.json @@ -0,0 +1,3 @@ +{"deliveries": [{"id": "fixture", "deliverySourceName": "samaydlette-com-edge-access", + "deliveryDestinationType": "S3", + "recordFields": ["date", "time", "c-ip", "cs-uri-stem", "cs-uri-query", "cs(User-Agent)", "sc-status"]}]} diff --git a/tests/fixtures/wellknown-headers/known-bad.json b/tests/fixtures/wellknown-headers/known-bad.json new file mode 100644 index 00000000..f5e93822 --- /dev/null +++ b/tests/fixtures/wellknown-headers/known-bad.json @@ -0,0 +1,4 @@ +{ + "ksi-signal.json": {"Content-Type": "application/json", "X-Content-Type-Options": "nosniff"}, + "security-decision-record.json": {"Content-Type": "application/json", "Access-Control-Allow-Origin": "*", "X-Content-Type-Options": "nosniff"} +} diff --git a/tests/fixtures/wellknown-headers/known-good.json b/tests/fixtures/wellknown-headers/known-good.json new file mode 100644 index 00000000..19a9e4f3 --- /dev/null +++ b/tests/fixtures/wellknown-headers/known-good.json @@ -0,0 +1,4 @@ +{ + "ksi-signal.json": {"content-type": "application/json", "access-control-allow-origin": "*", "x-content-type-options": "nosniff"}, + "ksi-signal.schema.json": {"Content-Type": "application/schema+json", "Access-Control-Allow-Origin": "*", "X-Content-Type-Options": "nosniff"} +} diff --git a/tests/test_availability_probe.py b/tests/test_availability_probe.py new file mode 100644 index 00000000..32a1c4af --- /dev/null +++ b/tests/test_availability_probe.py @@ -0,0 +1,126 @@ +"""CDS-CSO-AVR / CDS-TRC-USH: availability is measured outside AWS, with +incidents, and the deploy refuses a missing or stale independent feed.""" +import importlib.util +import json +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent + + +def _load(name, file): + spec = importlib.util.spec_from_file_location(name, REPO / "scripts" / file) + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +probe = _load("availability_probe_t", "availability-probe.py") +avail = _load("build_availability_t", "build-availability.py") +NOW = datetime(2026, 11, 5, 12, tzinfo=timezone.utc) +KEYS = [k for k, *_ in probe.TARGETS] + + +def _sample(t, fail=None): + return {"t": probe._iso(t), "probed": KEYS, "fail": fail or {}} + + +def test_core_services_are_probed_including_the_app_and_its_sign_in(): + urls = {u for _k, _s, u, _ok in probe.TARGETS} + assert any(u.endswith("/silk-reeling/") for u in urls) + assert any("amazoncognito.com" in u for u in urls) + assert any("/.well-known/" in u for u in urls) and any(u.endswith("/trust/") for u in urls) + assert all(u.startswith("https://") for u in urls) + + +def test_a_failed_probe_records_the_status(): + s = probe.probe_once(lambda url: 503 if "trust" in url else 200, NOW) + assert s["fail"] == {"trust-center": "HTTP 503"} + + +def test_consecutive_failures_make_an_incident_and_a_single_one_is_transient(): + t = [NOW - timedelta(minutes=15 * i) for i in range(6, 0, -1)] + samples = [_sample(t[0]), _sample(t[1], {"site": "HTTP 503"}), _sample(t[2], {"site": "HTTP 503"}), + _sample(t[3]), _sample(t[4], {"trust-center": "no response (timeout)"}), _sample(t[5])] + incs, transient = probe.incidents(samples) + assert incs == [{"service": "site", "service_name": "Website", "start": probe._iso(t[1]), + "end": probe._iso(t[3]), "failed_probes": 2, "failing_check": "HTTP 503"}] + assert transient == {"trust-center": 1} + + +def test_an_ongoing_incident_has_no_end(): + samples = [_sample(NOW - timedelta(minutes=30), {"site": "HTTP 500"}), _sample(NOW, {"site": "HTTP 500"})] + (inc,), _ = probe.incidents(samples) + assert inc["end"] is None + + +def test_history_is_kept_35_days_and_its_start_is_carried(): + old = [_sample(NOW - timedelta(days=d)) for d in (40, 34, 1)] + prev = {"feed_type": "availability-status", "history_began": "2026-09-01T00:00:00Z", "samples": old} + doc = probe.build(prev, _sample(NOW), NOW) + assert len(doc["samples"]) == 3 and doc["history_began"] == "2026-09-01T00:00:00Z" + assert doc["availability"]["site"]["probes"] == 2 # 30-day window: day 1 and now + + +def test_availability_percent_counts_failures(): + prev = {"feed_type": "availability-status", "samples": [_sample(NOW - timedelta(hours=1), {"site": "HTTP 502"})]} + doc = probe.build(prev, _sample(NOW), NOW) + assert doc["availability"]["site"]["availability_percent"] == 50.0 + assert doc["current"]["site"] == "up" + + +def test_the_known_bad_stale_feed_fails_the_deploy_guard(): + why = probe.check_fresh(REPO / "tests" / "fixtures" / "availability" / "known-bad-stale-feed.json", 2, NOW) + assert why and "not running" in why[0] + + +def test_a_missing_feed_fails_the_deploy_guard(tmp_path): + assert probe.check_fresh(tmp_path / "absent.json", 2, NOW) + + +def test_the_onsite_feed_is_built_from_the_independent_one_never_from_a_deploy(tmp_path): + feed = probe.build({}, _sample(datetime.now(timezone.utc)), datetime.now(timezone.utc)) + (tmp_path / "f.json").write_text(json.dumps(feed)) + assert avail.main(["--probe-feed", str(tmp_path / "f.json"), "--ksi-signal", str(tmp_path / "none.json"), + "--output", str(tmp_path / "a.json"), "--md-output", str(tmp_path / "a.md")]) == 0 + doc = json.loads((tmp_path / "a.json").read_text()) + assert doc["independent_service"]["json"].startswith("https://raw.githubusercontent.com/") + assert "deploy" not in json.dumps(doc["daily"]) and doc["measured_at"] == feed["generated_at"] + assert "Independent status page" in (tmp_path / "a.md").read_text() + + +def test_the_onsite_builder_refuses_a_stale_feed(tmp_path): + with pytest.raises(SystemExit): + avail.main(["--probe-feed", str(REPO / "tests" / "fixtures" / "availability" / "known-bad-stale-feed.json"), + "--output", str(tmp_path / "a.json"), "--md-output", str(tmp_path / "a.md")]) + + +def test_the_monitor_runs_outside_aws_on_a_schedule_and_pushes_only_its_branch(): + wf = (REPO / ".github" / "workflows" / "availability-probe.yml").read_text() + assert "cron: '*/15 * * * *'" in wf + assert "permissions: {}" in wf and "contents: write" in wf + assert "aws-actions" not in wf and "id-token" not in wf + assert "HEAD:refs/heads/availability-status" in wf + assert wf.count("git -c http.extraheader") == 1 and "push --quiet --force" in wf + + +def test_the_deploy_reads_the_independent_feed_before_the_sdr(): + wf = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() + step = wf.index("- name: Read the independent availability feed (fails when missing or stale)") + assert step < wf.index("- name: Build Security Decision Record") + assert "--check-fresh availability-probe.json --max-age-hours 2" in wf[step:step + 600] + assert "--probe-feed availability-probe.json" in wf + + +def test_an_ongoing_incident_fails_the_monitor_run_after_publishing(tmp_path): + samples = [_sample(NOW - timedelta(minutes=15), {"site": "HTTP 500"})] + doc = probe.build({"feed_type": "availability-status", "samples": samples}, _sample(NOW, {"site": "HTTP 500"}), NOW) + (tmp_path / "f.json").write_text(json.dumps(doc)) + assert probe.main(["--fail-on-incident", str(tmp_path / "f.json")]) == 1 + ok = probe.build({}, _sample(NOW), NOW) + (tmp_path / "g.json").write_text(json.dumps(ok)) + assert probe.main(["--fail-on-incident", str(tmp_path / "g.json")]) == 0 + wf = (REPO / ".github" / "workflows" / "availability-probe.yml").read_text() + assert wf.index("Publish the status feed") < wf.index("--fail-on-incident") diff --git a/tests/test_edge_access_logging.py b/tests/test_edge_access_logging.py new file mode 100644 index 00000000..77efb2d7 --- /dev/null +++ b/tests/test_edge_access_logging.py @@ -0,0 +1,154 @@ +"""CDS-TRC-ACL: access to the certification data is logged, within the +operator's privacy limits, and only monthly aggregates are published.""" +import gzip +import importlib.util +import json +import re +from datetime import datetime, timezone +from pathlib import Path + +import pytest + +REPO = Path(__file__).resolve().parent.parent +FIX = REPO / "tests" / "fixtures" / "edge-access-logging" + + +def _load(name, file): + spec = importlib.util.spec_from_file_location(name, REPO / "scripts" / file) + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +chk = _load("edge_check", "check-edge-access-logging.py") +summ = _load("access_summary", "build-access-summary.py") +NAME = "samaydlette-com-edge-access" +NOW = datetime(2026, 11, 5, 12, tzinfo=timezone.utc) + + +def _j(p): + return json.loads((FIX / p).read_text()) + + +# --- the configuration check -------------------------------------------------------- + +def test_the_allowlist_equals_the_bootstrap_delivery_fields(): + tf = (REPO / "infrastructure" / "bootstrap" / "trust-access-logs.tf").read_text() + block = re.search(r"edge_access_log_fields = \[(.*?)\]", tf, re.S).group(1) + assert tuple(re.findall(r'"([^"]+)"', block)) == chk.ALLOWED_FIELDS + assert "local.edge_access_log_fields" in tf + + +def test_no_identifying_field_is_allowed(): + assert not set(chk.ALLOWED_FIELDS) & set(chk.IDENTIFYING) + + +def test_the_good_configuration_passes(): + assert chk.problems(_j("good-deliveries.json"), _j("delivery-source.json"), NAME) == [] + + +def test_the_known_bad_fixture_fails_for_identifying_fields(capsys): + rc = chk.main(["--deliveries", str(FIX / "known-bad-deliveries.json"), + "--source", str(FIX / "delivery-source.json"), "--name", NAME]) + assert rc == 1 + err = capsys.readouterr().err + assert "c-ip" in err and "cs-uri-query" in err and "cs(User-Agent)" in err + + +def test_no_delivery_fails_the_deploy(tmp_path): + (tmp_path / "d.json").write_text('{"deliveries": []}') + rc = chk.main(["--deliveries", str(tmp_path / "d.json"), "--source", str(tmp_path / "absent.json"), + "--name", NAME]) + assert rc == 1 + + +def test_a_source_that_is_not_the_distribution_fails(): + src = {"deliverySource": {"name": NAME, "logType": "ACCESS_LOGS", "resourceArns": ["arn:aws:s3:::x"]}} + assert any("not a CloudFront" in p for p in chk.problems(_j("good-deliveries.json"), src, NAME)) + + +def test_a_field_outside_the_allowlist_fails_even_if_not_named_identifying(): + d = _j("good-deliveries.json") + d["deliveries"][0]["recordFields"].append("x-edge-request-id") + assert any("outside the privacy allowlist" in p for p in chk.problems(d, _j("delivery-source.json"), NAME)) + + +def test_the_deploy_checks_logging_before_the_sdr_and_publishes_the_summary(): + wf = (REPO / ".github" / "workflows" / "deploy-with-opa.yml").read_text() + step = wf.index("- name: Check edge access logging and build the access summary") + assert step < wf.index("- name: Build Security Decision Record") + body = wf[step:wf.index("\n - name:", step + 10)] + assert "check-edge-access-logging.py" in body and "build-access-summary.py" in body + assert "access-summary.bundle access-summary.json" in wf + + +def test_raw_edge_records_expire_after_90_days(): + tf = (REPO / "infrastructure" / "logging.tf").read_text() + for prefix in ('prefix = "cloudfront/"', 'CloudFront/" }'): + i = tf.index(prefix) + assert "expiration { days = 90 }" in tf[i:i + 200] + + +# --- the summary ---------------------------------------------------------------------- + +def _rec(day, stem, status=200, cc="US", **extra): + return {"date": day, "time": "10:00:00", "cs-uri-stem": stem, "sc-status": str(status), "c-country": cc, **extra} + + +def test_only_trust_paths_are_counted_and_nothing_identifying_survives(): + recs = [_rec("2026-11-02", "/.well-known/ksi-signal.json"), + _rec("2026-11-02", "/trust/index.html", cc="DE"), + _rec("2026-11-03", "/index.html"), + _rec("2026-11-03", "/.well-known/wp-login.php", status=404), + _rec("2026-11-03", "/.well-known/