Repository navigation
Clarification requested: Is Content-Type: application/json a normative MUST for all FedRAMP-required JSON artifacts?
#175
Replies: 3 comments 11 replies
|
We plan to update the rules shortly to make it explicitly clear that sharing machine-readable JSON documents also means ensuring those documents can be consumed directly by commonly used web applications such as SaaS GRC tools. A setup that expects a human (or program) to download a file then upload it to another application is somewhat archaic and not at all considerate of modernization. You're correct that the original rules were written in a way that someone could expect customers to treat a JSON data file just like a Word doc that they had to download and copy to their SharePoint or whatever. A small number of folks have done this and we have been asking them to consider feedback from us to do it in a way that FR can actually automate using that data with the tools we have. Regardless, you're correct that we need to close that loophole in the rules because we can't allow an approach that makes data available in a way that FedRAMP itself can't consume. |
|
Thank you, Pete. I appreciate the response, and I agree with the broader goal of making Certification Data practically consumable by FedRAMP and agencies. I think the remaining concern for us is less about this particular HTTP header and more about how a CSP is expected to make an engineering decision today based on the published rules. We are actively expending engineering resources implementing CR26. In our case, that includes significant automation around Box as our Trust Center. We selected that architecture based in part on FedRAMP's published position that a FedRAMP-compatible Trust Center can be any secure repository or service that satisfies the CDS-TRC requirements, with the current guidance even describing a WordPress-hosted Trust Center as a possible implementation. If the actual acceptance criterion is broader than the explicit rules and is instead whether an implementation is ultimately “FedRAMP-consumable,” then I think CSPs need a concrete definition of that interface before building against it. We are not asking FedRAMP to guarantee that Box, or any particular vendor, will be supported indefinitely. We are asking whether an implementation that satisfies the current explicit Consolidated Rules can reasonably be relied upon as compliant today. If FedRAMP requires additional characteristics for automated consumption, specific HTTP headers, authentication flows, API behavior, credential types, URL behavior, or other interface characteristics, those requirements materially influence architecture and vendor selection and should be part of the published interoperability contract. Otherwise, a CSP can spend substantial engineering time and money implementing automation that satisfies the published requirements, only to later discover that a technically conforming implementation is not considered usable because of an unstated interface expectation. That is the situation we are trying to avoid. Authentication illustrates the broader problemThe Trust Center model also raises a related machine-access question. The rules require documented programmatic access to Certification Data while also contemplating controlled access, agency-user/system inventories, access logging, and mechanisms such as JIT access. For non-public Certification Data, FedRAMP will therefore ultimately need some method of authenticating programmatically to each CSP's Trust Center, whether through service accounts, OAuth client credentials, federation, or another mechanism. We actually raised this issue with the PMO in September 2025. At that time, we specifically asked whether Login.gov could support agency access to CSP Trust Centers, whether FedRAMP could facilitate a common federation pattern, or alternatively what authentication approach CSPs should implement. Our question was specifically about federal agency users accessing Trust Center information, not authentication to our commercial service. That distinction was explained in the follow-up exchange. Our original questions also explicitly asked about a PMO-sponsored federation pattern and recommended authentication mechanisms for Trust Centers. That architectural question remains important. If every CSP independently selects a different Trust Center and authentication mechanism, FedRAMP may eventually need to establish and maintain a different machine identity or credential relationship with each CSP. If the intended future state is centralized federation, a standard service identity, an OAuth/OIDC profile, or some other common mechanism, CSPs need to know that before committing significant engineering resources to another pattern. Changes to the technical contract also have schedule implicationsThere is a second issue that I think is becoming increasingly important as CSPs move from reading CR26 to actually implementing it. CR26 is not simply a documentation exercise. For CSPs attempting to implement the machine-readable and programmatic-access portions as intended, it requires real software engineering: schemas, exporters, APIs, authentication flows, validation pipelines, Trust Center integrations, automated evidence generation, and changes to existing GRC processes. Our experience has been that the amount of engineering required is materially greater than may be apparent from a high-level discussion of “automation.” We have evaluated this in the context of actual implementation, and there is not currently a broad set of off-the-shelf GRC products that simply makes all of these requirements work without integration and development effort. That matters when requirements change after implementation work has already begun. We certainly understand that CR26 will continue to evolve. But when an interpretation introduces a new technical requirement that changes architecture, invalidates an existing implementation, or requires CSPs to modify code, we believe it should be handled as a versioned change to the technical contract, rather than simply becoming an immediately applicable interpretation of an existing rule. FedRAMP's own public repository maintenance guidance uses essentially this software-engineering concept when describing breaking changes: changes that cause existing parsers, validators, exporters, queries, or integrations to fail, reject previously valid data, or require code changes to continue processing the machine-readable contract. That is a useful model for CR26 generally. If a new requirement meets that threshold, we believe the change-management process should include:
The Consolidated Rules data model already distinguishes obtain, maintain, optional-adoption, and grace dates, so there is already a mechanism available to manage this kind of transition. This last point is important. The implementation clock and the requirements baseline cannot reasonably move independently of one another. If CSPs are being held to fixed CR26 implementation dates while the technical interface they are expected to build against remains subject to material changes or new interoperability requirements, CSPs absorb the entire schedule risk created by those changes. That is especially difficult when engineering work completed in good faith against the published rules may need to be redesigned because a later interpretation establishes a technical constraint that was not previously documented. We are not suggesting that FedRAMP freeze CR26. We are suggesting that when FedRAMP changes the engineering contract, the implementation schedule should move with it in a manner proportionate to the impact of that change. What would help us move forwardI think four concrete clarifications would help considerably:
I recognize that this area is evolving, and I don't expect FedRAMP to predict every future technical decision. What CSPs do need is a stable and testable baseline for the requirements effective today, together with normal software change-management practices when that baseline changes. We would be very happy to spend 30 minutes with you and the appropriate technical stakeholders to walk through the Box implementation, the authentication issue, and the automation we have already built. I think a short technical discussion could help distinguish between the outcomes FedRAMP is trying to achieve and the implementation assumptions CSPs are currently having to infer. Thanks again for engaging on this. |
|
Thanks, Pete. I appreciate the response. I think the discussion may have drifted a little from the specific issue that caused us to raise this in the first place, so I want to reconnect the architectural questions to the original implementation problem. This started because we attempted to update our FedRAMP Marketplace listing by providing the PMO with our public CPO JSON hosted in our Box Trust Center. The underlying artifact is valid JSON and validates successfully against the applicable FedRAMP schema. However, the submission was rejected because Box serves the file using: rather than: We were subsequently told that the CPO could only be provided if the HTTP response used We have already implemented a workaround for the public CPO, so I am not asking FedRAMP to change the Marketplace validator. What concerns me is what that experience tells us about the broader CR26 implementation model: we implemented against the written requirement that the document be valid, machine-readable, schema-conformant JSON, but discovered an additional transport-level acceptance criterion only when we attempted to submit it. That distinction matters because we are actively spending engineering resources implementing the rest of CR26. I completely agree that agencies obtaining controlled security documentation from CSPs is not new. CSPs and agencies have exchanged authorization packages through portals, secure repositories, file shares, and similar mechanisms for many years. What seems materially different now is the expectation for machine-readable Certification Data to be programmatically consumed across independently operated Trust Centers. CDS-TRC-PAC requires programmatic access to Certification Data, while the broader Trust Center model also contemplates controlled information, agency users or systems with access, access inventories, access logging, and mechanisms such as JIT provisioning. For non-public Certification Data, a machine therefore needs some way to authenticate. We can solve this with Box todayTo make this concrete, we can provide FedRAMP programmatic access to our Box Trust Center using Box's native server-to-server capabilities. We can establish an OAuth 2.0 Client Credentials Grant application, authorize it to the appropriate Trust Center resources, and provide FedRAMP with a dedicated machine identity. FedRAMP could then obtain short-lived access tokens and retrieve Certification Data through the Box API without human interaction. From our perspective, that appears to meet the intent of programmatic access. We are not asking FedRAMP to bless Box as a product or guarantee that Box will always be acceptable. The question is more fundamental: If we implement programmatic access using the native capabilities of our selected Trust Center and satisfy the explicit CDS-TRC requirements, can we rely on that implementation as compliant today? If yes, we can continue engineering against that contract. If no because FedRAMP ultimately expects some different transport, authentication, API, credential, URL, or retrieval behavior, then those expectations materially affect architecture and need to be known before CSPs invest in implementations. The The scaling question is what I still do not understandA Box Client Credentials Grant would establish a machine-to-machine trust relationship between our Trust Center and FedRAMP. If an agency also requires programmatic access to protected Certification Data, we would need to establish an appropriate identity or integration for that agency as well, particularly if access must be attributable for inventory and logging purposes. Now multiply that across the ecosystem. One CSP may use Box. Another may use SharePoint/Graph. Another may use Vanta or Paramify. Another may expose a custom OAuth API. Without some common interoperability model, the resulting architecture appears to be something like: I may be missing an intended mechanism, but I do not understand how authenticated programmatic access scales across hundreds of CSPs and federal agencies without at least one of the following:
The Trust Centers themselves do not need to be centralized. But it seems that some portion of the trust and interoperability layer has to be standardized if the objective is automated consumption across the FedRAMP ecosystem. This is what we were trying to get at when we previously asked the PMO about Login.gov. Login.gov itself was only one possible implementation. The broader question was whether FedRAMP intended to provide or define a common identity/federation mechanism for federal users and systems accessing independently operated CSP Trust Centers. This is why the “20 years” point does not completely resolve the concern for meHuman users obtaining authorization documentation from controlled CSP repositories has been done for many years. But having machines automatically authenticate to, retrieve, validate, and continuously consume structured Certification Data from independently operated repositories is a different engineering model. That model may absolutely be the right direction, and we support the move toward automation. But CSPs are already investing engineering resources to implement it, which means the interface contract needs to be stable enough to build against. The questions I am ultimately trying to answer are:
|
Uh oh!
There was an error while loading. Please reload this page.
We have been working through a question with the FedRAMP PMO regarding the delivery of JSON artifacts through a FedRAMP-compatible Trust Center, and after reviewing both the Consolidated Rules and prior discussions in this forum, we believe the question has broader implications for the ecosystem.
To be clear up front: we fully support the requirement that FedRAMP machine-readable artifacts actually be valid JSON and validate against the applicable FedRAMP JSON schema. That is not the issue we are raising. The question is whether FedRAMP is establishing an additional normative requirement that every FedRAMP-required JSON artifact must also be delivered over HTTP with:
even when the underlying artifact is valid JSON, successfully validates against the applicable FedRAMP schema, and is programmatically retrievable.
Background
Our Trust Center is currently hosted on Box. We published our Certification Package Overview as a JSON file. The artifact itself is valid JSON and, when downloaded and submitted directly to the FedRAMP validator, validates successfully against the applicable schema. The issue is that Box serves downloaded file content using:
rather than
application/json.The CPO URL validator rejected the resource based on the HTTP response header.
We raised this with the PMO because FRC-CSO-JSN currently states:
That is the normative requirement we expected to be assessed against. Our understanding of the PMO's responses to us so far is that
Content-Type: application/jsonis expected not only for the public CPO, but for all FedRAMP requirements that require submission of JSON documents. The PMO has also clarified that only the CPO has the additional requirement to be anonymously/publicly accessible.We have already implemented a workaround for the public CPO and are not asking FedRAMP to change the CPO validator. We understand the CPO's role in Marketplace automation and are comfortable accommodating that interface requirement. Our concern is what this interpretation means for the remaining authenticated Trust Center artifacts and for the Trust Center ecosystem more generally.
Is this a recommendation or a rule?
The new FedRAMP FAQ provided to us introduces the relevant headers as:
and identifies
Content-Type: application/json,X-Content-Type-Options: nosniff, andContent-Disposition: attachment. The same FAQ later discusses “requiring these headers from all CSPs.” That creates an important ambiguity.We agree that
application/jsonis the appropriate and preferred media type for JSON and should be used when a hosting platform allows it. What we cannot currently identify is the Consolidated Rule that makes that HTTP header a MUST.FRC-CSO-JSN requires the document to be machine-readable JSON and valid against the applicable schema. It does not currently specify HTTP transport behavior, MIME types, response headers, or a particular method by which a Trust Center must serve those bytes. That distinction seems especially important in light of guidance FedRAMP has already provided in this forum.
In Discussion #146, when a schema and the written rules did not perfectly align, FedRAMP explained that the schemas were intentionally kept minimal to preserve provider flexibility and specifically cautioned against treating implementation artifacts as a “ghost rule,” saying providers should “follow the actual written rules, not templates or schemas.”
More recently, in Discussion #147, a CSP identified a difference between narrative Trust Center guidance and the actual applicable rules. FedRAMP clarified that “the key thing is that the explicit rules are followed, not the narrative.” FedRAMP then evaluated the requirement based on the actual applicable rules rather than treating the narrative statement as an additional obligation. We believe the same question arises here.
If
Content-Type: application/jsonis an absolute FedRAMP requirement, it seems that requirement should be explicit in FRC-CSO-JSN, CDS-TRC, or another applicable rule rather than arising from validator behavior or narrative FAQ guidance.The header does not establish that the artifact is valid JSON
There is also a distinction between transport metadata and artifact validity. A server can return:
while the response body contains malformed JSON, HTML from an upstream error page, XML, or other arbitrary content.
Conversely, a server can return:
while the response body contains perfectly valid JSON that parses successfully and validates against the applicable FedRAMP schema. So while
application/jsonis useful metadata, schema validation provides the substantive assurance that the document actually satisfies FedRAMP's machine-readable JSON requirement.This is especially relevant for authenticated Trust Center artifacts. A consumer retrieving those artifacts programmatically is already deliberately requesting a known resource through an authenticated interface and can validate and parse the returned document.
This may have significant Trust Center interoperability consequences
This concern was actually raised by the community during the original RFC-0011 discussion. RFC-0011 proposed that Trust Centers provide documented APIs or similar machine access and make authorization data available in machine-readable formats. A community comment specifically raised the implementation concern of whether platforms such as O365, Box, and Google Docs would be capable of supporting the standard and warned that open-ended API requirements could create significant interoperability complexity. The
Content-Typeinterpretation appears to make that earlier concern concrete.For example, Box's standard file-content delivery mechanism returns file downloads as
application/octet-stream. Microsoft's standard Graph file-content mechanism used with OneDrive and SharePoint similarly delivers file content through a download interface that can returnapplication/octet-stream. Google Drive/Workspace MIME handling depends on how MIME metadata is established and how the content is retrieved, creating another platform-specific implementation consideration.Accordingly, a CSP could potentially use an enterprise repository that provides authentication, authorization, API access, access logging, valid machine-readable JSON, and successful FedRAMP schema validation, yet still fail this interpretation because the CSP does not control the HTTP
Content-Typeemitted by the repository.That could effectively require CSPs using otherwise capable platforms such as Box or SharePoint/OneDrive to introduce an additional static hosting service, reverse proxy, custom API, CDN, or other intermediary simply to change the HTTP response header. Other platforms may require vendor-specific MIME configuration or similar workarounds. That seems materially different from the solution-agnostic Trust Center model originally discussed in RFC-0011, where the focus was on using CSPs' existing commercial processes and Trust Centers rather than prescribing a particular hosting architecture.
Security objective
We agree with the security objective described in the FAQ. FedRAMP should protect downstream agency systems consuming machine-readable Certification Data. What is less clear is whether requiring
Content-Type: application/jsonis necessary to accomplish that objective.The FAQ also recommends:
Those headers directly address browser MIME-sniffing and inline-content handling concerns. More fundamentally, an agency system automatically ingesting FedRAMP Certification Data should presumably validate and safely parse the JSON rather than rely on the HTTP media type as proof that the response body contains trustworthy JSON.
What we are asking FedRAMP to clarify
We are trying to determine which of these two interpretations is intended.
Content-Type: application/jsonis the strongly preferred way to deliver FedRAMP JSON, but the normative requirement remains that the artifact be valid machine-readable JSON, conform to the applicable FedRAMP schema, and satisfy the applicable access and sharing requirements.Content-Type: application/json.If Interpretation 2 is intended, we respectfully suggest that the requirement should be incorporated explicitly into the Consolidated Rules, with the same force, applicability, effective-date, and change-management treatment as other normative requirements. That would allow CSPs, assessors, Trust Center vendors, and enterprise repository providers to evaluate their platforms against a clear and machine-readable requirement rather than discovering the constraint through validator behavior or implementation guidance.
We would also appreciate clarification on whether an authenticated FedRAMP JSON artifact delivered as
application/octet-streamcan satisfy FRC-CSO-JSN when the response body is valid JSON, successfully validates against the applicable FedRAMP schema, is programmatically retrievable, and is protected by the applicable authentication and authorization controls.This feels larger than our individual CPO implementation. It potentially affects the architecture and vendor choices available to every CSP implementing a FedRAMP-compatible Trust Center. Our goal is not to weaken the machine-readable requirement or the underlying security objective. We want to make sure the requirement is explicit, testable, solution-agnostic, and represented in the Consolidated Rules if it is intended to be mandatory.
All reactions