Repository navigation
Resolve the capability asymmetry between Component Definition and SSP
#2
Replies: 11 comments 4 replies
|
I vote yes for adoption of Option A - capabilities pulled into SSP (should be SSS- Security system state). Plans don't matter. State is all that matters at any given interval in time. Brian Hierholzer |
|
I favor Option B, even though it is a breaking change to cDef. While Option A is a non-breaking change from a model perspective, the introduction of As @david-waltermire pointed out,
|
|
I'm not sure that Option B is a valid option. As I read it its saying, "If the SSP can't represent capabilities, then cDef shouldn't either." Perhaps the argument is that this would prevent bad usage patterns, but I am not convinced deletion is the best way to accomplish that. To me, option B is only valid if the idea of joint control satisfaction is out of scope for OSCAL, which i don't think it is. For sake of completeness, i think what @dfkunstler alluded in the summary should be included as Option C (which i suppose is effectively the status quo). However, a real Option scknowledges the gap and documents a compatable convention. While not ideal, it would at least establish a repeatable pattern consistant across content. That said, my preference is Option A. I see a near-term need for this in FedRAMP-directed OSCAL use cases. FedRAMP KSIs- if related back to NIST controls through mappings- might best be addressed through aggregate control satisfaction rather than attribution to a single component. Native SSP capability support would make that much easier. |
|
@Palladium-Innovations. I think you are saying (and if so, I agree) that an Option C would be option A without revising the cDef model. If that is what you are saying, I would favor Option C, and otherwise stand by my assertions that we should focus on I agree aggregation is likely critical for use cases like KSIs, but I view reality as being more than one level of aggregation.
The virtual machine might include:
The OS might include:
For AU controls, it makes sense to respond at the log capability level. How would you represent this with only one level of hierarchy? |
|
In today's cDef TFG, we agreed that: Option C is to do nothing with the models and shift to using Option D is to:
|
|
@dfkunstler - Please note that the latest OSCAL version is v1.2.2. |
|
@dfkunstler I would prefer going with Option D for a cleaner solution, or option C if the community decides on path of least changes. Even then in option C we should deprecate use of capabilities as there is no equivalent in SSP and the problem of inconsistent modelling between cDef and SSP would still remain. |
|
Asked fable about this +1 for Option D, with a concrete proposal for the part the draft explicitly leaves open (§3.4). Context: I'm working on mapping German BSI IT-Grundschutz modules to OSCAL component definitions. For us, joint satisfaction is the default case, not an edge case — a module like APP.4.4 (Kubernetes) is satisfied by cluster + policy engine + registry + logging together, never by a single component. So if the group confirms the draft's position that joint satisfaction is in scope — which I strongly support — D is the cleanest vehicle: capability-as-component is automatically recursive (a But as the draft notes, D relocates the construct without reconciling its control accounting. If a capability declares 1. A implemented-requirements:
- uuid: ir-au6-cap
control-id: au-6
description: >
Emergent: cross-service correlation of audit records that
no single member provides.
props:
- name: aggregation
value: authoritative # allowed values: authoritative | additive
contributions: # NEW, optional
- component-uuid: comp-cloudtrail
implemented-requirement-uuid: ir-au6-ct # optional, precise
role: contributes # allowed values: contributes | provides-emergent
description: "Provides the raw audit trail"
- component-uuid: comp-cloudwatch
role: contributes2. Defined
3. Validation constraints (Metaschema/Schematron — all machine-checkable, which is the decisive advantage over a pure
On §6.1's other branch: I'd advise against reusing Finally, +1 on adopting the §6.2 interim convention now — under D the |
Option D — Metaschema patchWarning The attached patch is an untested draft for review and feedback Implements Option D from the proposal: deprecate the standalone
# from a clean OSCAL checkout at v1.2.2
git apply /path/to/option-d-metaschema.patchWhat it changes
Because Deliberately left as follow‑on
|
|
The latest updates to option D are excellent. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Proposal: Resolve the
capabilityasymmetry between Component Definition and System Security PlanStatus: Technical Focus Group (TFG) recommendation — submitted to the Technical Advisory Group (TAG) for review and approval
Last update: 2026-07-07
Scope: OSCAL Implementation Layer (Component Definition + System Security Plan), v1.2.2
Source of facts: the official OSCAL v1.2.2 JSON schemas (
oscal_component_schema.json,oscal_ssp_schema.json), corroborated by the NIST OSCAL concept pages (cited below)1. Summary
The OSCAL Component Definition (cDef) model defines a
capabilityobject — a named grouping of components (and/or other capabilities) that carries its owncontrol-implementations, expressing that several components jointly satisfy a control no single component satisfies alone. The System Security Plan (SSP) model has no capability construct at all: itssystem-implementationholds a flat list ofcomponents, and control satisfaction is recorded per individualcomponent-uuid.This is a modeling discontinuity within a single layer. Capability — a first-class, control-bearing unit of design intent in the cDef — evaporates the moment that design is instantiated into the SSP that documents the real system. Authors are left guessing how (or whether) to carry the concept forward. The current state is ambiguous and should be resolved.
Community collaboration to date has produced four candidate directions.
capabilityto the SSP (make the layer symmetric).capabilityfrom the Component Definition (collapse to flat components).component+linksfor all grouping (convention only, no schema change). A modified Option B that deletes nothing.capabilitiesassembly, but move its one irreducible feature ontocomponent: addincorporates-componentstocomponentand a newtypevaluecapability. A capability becomes a control-bearing component that incorporates other components — which, becausecomponentalready exists in both the cDef and the SSP, dissolves the cross-model asymmetry without a new SSP-only construct.Of the four, Options A and D carry joint satisfaction end-to-end, by different means. The TFG recommends Option D (see §5) as the lighter path, with Option A as the non-breaking fallback. These are the TFG's recommendations; the OSCAL Foundation's TAG is the final decision maker. This document presents all four options — together with the TFG's recommendation — to the TAG for review and approval.
2. So what?
Is
capabilityactually needed, or wouldlinksdo? This is the decision that should drive everything else.A
link(orprop) only points one object at another, so plain components plus links already cover organizational grouping ("these three components belong together") and navigation ("see also"). What a link cannot carry is acontrol-implementation: links are typed pointers, not statements of how a control is met.Capability's one irreducible feature is that it owns
control-implementationsfor the group as a whole — it lets you assert that, e.g., {AWS CloudTrail + Amazon CloudWatch + AWS Config} together satisfy AU-6 when no single component does. Trying to express that with links alone forces a bad choice: attribute the joint result to one arbitrary member (false), or copy it onto every member (double-counts, and still never says "jointly").So the construct earns its keep only for emergent, group-level satisfaction — but that is a real and common need (defense-in-depth, layered controls). The decision therefore reduces to one question: is joint, group-level control satisfaction in scope for OSCAL? The 2026-06-03 cDef TFG meeting concluded that it is; this is the pivotal judgment now put to the TAG for ratification.
If out of scope, then inter-component links suffice and the dedicated
capabilityconstruct can be dropped or discouraged. If in scope, the capability concept — joint, group-level satisfaction — must be expressible everywhere control satisfaction lives, including the SSP, where it is currently absent; whether thecapabilityconstruct is the right vehicle is a separate question.3. Evidence: the schema asymmetry
3.1 Component Definition —
capabilityexists and carries control implementationsFrom the OSCAL v1.2.2 Component Definition JSON schema:
NIST states the design intent plainly:
So a capability is not mere annotation; it is a control-bearing aggregation. Its whole reason to exist is to express joint satisfaction.
3.2 SSP — no capability anywhere
From the OSCAL v1.2.2 SSP JSON schema:
The term "capability" does not appear as a definition anywhere in the SSP schema; the only grouping of components it offers is the flat
system-implementation/componentslist. The SSP'scontrol-implementationrecords satisfactionby-componentkeyed on acomponent-uuid. There is noby-capabilityand no field onsystem-componentthat points back to a source capability.3.3 The resulting gap
capabilityincorporates-componentscontrol-implementationsuuid)A cDef can assert "Capability Centralized Logging = {CloudTrail, CloudWatch, Config} jointly satisfy AU-6." When an SSP author leverages that cDef, the SSP can list the three components, but cannot state that the system implements the capability, nor attach control satisfaction at the capability level. The lineage from design intent to documented implementation is broken.
3.4 Capability vs. component
control-implementationswithin the cDefThe asymmetry above is the cross-model problem. There is also an intra-model one. Both
capabilityanddefined-componentcarry the identicalcontrol-implementations[]structure:The model defines no relationship between a capability's control implementations and those of the components it incorporates:
{ control-id, source, description, set-parameters, statements, responsible-roles, props, links, remarks, uuid }— nocomponent-uuid. They never reference the members.incorporates-components[]carries only{ component-uuid, description }— no control mapping.export/provided/responsibility/inherited/satisfied) that might bridge them; those exist only in the SSP.So if a capability declares an
implemented-requirementforAU-6and its member components also declareAU-6, nothing ties the two together. The relationship is not additive, not an override, not a roll-up, not a reference — they are independent assertions about the same control at two granularities, reconcilable only by reading prose. Consequences:AU-6and each member'sAU-6, or treat the capability as the authoritative aggregate.AU-6and relies on component X for the rest" — even though OSCAL already has exactly this vocabulary in the SSP (see §6).3.5
capabilityis structurally weaker thanlinksA separate objection (raised by @david-waltermire and developed by @brian-ruf in the discussion) is that, even within the cDef, the
capabilityassembly is a poor grouping primitive compared tolinks:capabilityis a rigid grouping. Itsincorporates-components[]is single-level and one-to-many — a parent just lists its member components. You cannot nest a capability inside a capability, and a component can sit under two capabilities only by repeating its UUID; there is no shared membership or graph edge.capabilityis described as "a grouping of other components and/or capabilities" (§3.1), yet the only containment field,incorporates-components, holds acomponent-uuiddocumented as "a reference to acomponent" — there is no field that references another capability. Capability-nesting is described but not expressible; the v1.2.2 metaschema even carries an open feature-request note to constrain the reference to acomponent. This gap between the prose and the schema is itself a symptom of an underspecified construct.linksare flexible. Alinkexpresses any relationship, in any direction, to any depth, including many-to-many. The one thing it cannot carry is acontrol-implementation.Brian Ruf's worked example makes this concrete: real systems nest several levels deep — a logging capability contains a virtual machine, which contains an OS, which contains cryptographic modules — and different control families are best answered at different depths (AU at the capability, AC at the OS, SI at the module). A single-level, one-to-many
capability → componentsrelation cannot represent that; an arbitrary-depthlinkgraph can.This weakness argues against the dedicated
capabilityassembly and for Options C/D, which lean oncomponent+linksinstead. But it does not settle the §1 scope question: links still cannot carry group-levelcontrol-implementations.3.6 Consequences
component, aprop, alinkto back-matter), none interoperable.4. Options
Option A — Add
capabilityto the SSPIntroduce a
capabilitiescollection insystem-implementation, mirroring the cDef construct but referencing implementedsystem-components:And allow control satisfaction to be attributed to a capability — either by adding a
by-capabilitysibling toby-component, or by permittingimplemented-requirement/statementto reference a capability UUID.Pros
Cons
capabilitiesassembly and aby-capabilityconstruct to the SSP model — new metaschema definitions, JSON/XML/YAML bindings, documentation, and validation constraints — whereas D reuses thecomponentandby-componentmachinery already present in both models.system-implementation/capabilitiesandby-capabilityconstructs would require substantial rework of SSP viewing and authoring tools — an OSCAL area where vendors and implementors have done significant work.Option B — Remove
capabilityfrom the Component DefinitionForce all grouping down to flat components; represent "capability" only as convention (e.g. a component with a
type/propmarker andlinks to members).Pros
Cons
Option C — Change nothing; standardize on
component+linksA modified Option B that deletes nothing: leave both schemas as they are, and publish a recommended convention that all component-to-component grouping be expressed with
links(e.g. a documentedrelvocabulary), steering authors away from thecapabilityassembly without removing it. This is roughly the status quo plus guidance — the "do nothing to the models" branch discussed in the TFG.Pros
links: many-to-many, arbitrary depth (resolves §3.5).component+linkssymmetrically, so there is no cross-model gap for the structural relationship.Cons
control-implementation, so the §1 capability — group-level satisfaction no single member provides — has no machine-checkable home. This is acceptable only if joint satisfaction is ruled out of OSCAL's scope.capabilityin the schema as a discouraged-but-valid construct, so the asymmetry and §3.4 ambiguity technically persist for anyone who still uses it.relvocabulary.Option D — Deprecate the assembly; make
capabilitya componenttypeDeprecate the standalone
capabilitiesassembly and relocate its essential behavior ontocomponent:Because a capability is now a kind of component, and
componentalready lives in both the cDef and the SSP, the capability survives the cDef→SSP hand-off with no new SSP-only assembly: an implemented capability is just asystem-componentwithtype="capability", referencedby-componentexactly like any other. Joint control satisfaction is preserved (the capability-typed component carries / is credited with thecontrol-implementation); and the weak single-level containment of the old assembly gives way to two complementary tools (resolving §3.5):incorporates-componentsmodels composition — a capability's members, which may themselves be capability-typed components, so composition nests to any depth — whilelinkscarry what composition cannot: a component shared across several capabilities (many-to-many), and typed cross-references anywhere in the graph.Pros
by-capability, nosystem-implementation/capabilities; reuses the existing component machinery in both models.by-componentresponses; they need a newtypevalue and anincorporates-componentsview, not a parallel capability subsystem.Cons
capabilitiesbreaks existing capability-bearing cDefs and the tooling that reads them. It is milder than B for two concrete reasons, not by assertion: a deprecation with a scheduled sunset keeps existing content valid through a transition window instead of invalidating it at once, and the migration is mechanical and lossless — eachcapabilitybecomes atype="capability"component with itscontrol-implementationsintact — whereas B leaves joint satisfaction with no faithful target. Milder is not free, and the sunset target (a future major version) still has to be set.component:incorporates-componentsand a structuraltypevalue add weight to an already central, heavily-used assembly.5. Recommendation
Preserve joint, group-level control satisfaction — and the lightest way to do that end-to-end is Option D.
The decision reduces to the §1 scope question. The TFG concluded joint satisfaction is in scope, and the discussion supports that: @Palladium-Innovations notes a near-term FedRAMP need — KSIs (Key Security Indicators), when mapped back to NIST controls, are often best discharged by aggregate satisfaction across several components rather than attributed to one, and native end-to-end capability support would make that materially easier. With joint satisfaction in scope, Options B and C are off the table: both surrender the one thing links cannot express.
That leaves A vs. D, which preserve the same semantics by different means:
system-implementation/capabilities,by-capability). It is non-breaking, but it (i) builds a second, capability-only subsystem in the SSP — the OSCAL area already considered the most cumbersome for tooling — and (ii) inherits the §3.5 single-level, one-to-many containment weakness.component(type="capability"+incorporates-components). Becausecomponentalready exists in both models, the asymmetry dissolves with no new SSP construct; existing component/by-componenttooling largely carries over; and structure rides onlinks/incorporates-components, which nest and go many-to-many (the §3.5 fix). Its cost is a scheduled deprecation ofcapabilitiesand some added weight oncomponent.On balance the TFG recommends Option D, with Option A as the fallback if the TAG prefers a strictly non-breaking path and is willing to pay the SSP-tooling cost. The earlier exclusive recommendation of Option A is superseded: D achieves the same end-to-end expressiveness at lower tooling cost and answers the hierarchy critique that A does not. Option C becomes the right answer only if the TAG determines joint satisfaction is out of scope — in which case nothing need change beyond published
linksguidance. Option B (hard removal) is hard to justify when joint satisfaction is in scope: D captures most of B's simplification while keeping the expressiveness B discards, and without B's unscheduled breakage.Why resolve this now. The TFG debated the cost of Option D's breaking change and concluded that ending the current ambiguity as quickly as possible is the top priority. The TFG treats
capabilityas a dead-end construct: leaving it valid-but-unguided invites continued adoption that later has to be unwound. Deprecating it under Option D therefore delivers value immediately and independently of the deferred §3.4 accounting decision — it signals implementers to stop building oncapability, preventing tech debt and wasted effort now — whereas every interval of delay adds more capability-bearing content that will eventually need migrating. The breakage is the mechanism that resolves the ambiguity, not a cost paid for a benefit still to come.Important
Whichever of A/D is chosen still leaves the intra-cDef gap (§3.4) open: the relationship between a capability's control implementation and its members' remains undefined (Option D relocates the construct but does not reconcile its control accounting). That gap is preexisting — it is not created by, and does not depend on, the A/D choice. The TFG's consensus is that the value of resolving the top-level asymmetry question is too great to justify further delay on account of it. The TFG therefore recommends that the TAG decide A vs. D now and defer the choice of how to close §3.4 to a follow-on decision — see §6 for the candidate approaches surfaced so far.
5.1 Interim guidance before any schema change
Any schema option will take time to land, so the TFG recommends adopting one interim convention now to keep content from diverging in the meantime. With Options C and D on the table, this is no longer a neutral stopgap — it is a head start on the most likely outcome, since it previews Option D:
system-componentwithtype="capability".links[]ofrel="incorporated-component"to each member component UUID.by-componentagainst that capability-typed component, with apropflagging it as an aggregate.Adopting this now is low-regret: under Option D it becomes native, under Option A it migrates cleanly, and under Option C you drop the aggregate component and keep only the
linksgrouping.6. Closing the intra-cDef gap (§3.4): candidate approaches
This section is out of scope for the immediate A/D decision (see the callout in §5). It collects the candidate approaches the working group has surfaced for closing the intra-cDef control-accounting gap, for discussion once the primary decision is settled. Neither is a settled recommendation.
6.1 Approach 1 — the
provided/responsibilitypatternOSCAL already models split control satisfaction between a provider and a consumer — in the SSP's
by-component/export, used for leveraged authorizations (the cloud "shared responsibility" split). It is a UUID-cross-referenced handshake:export.provided[]uuidexport.responsibilities[]uuid, optionalprovided-uuidinherited[]provided-uuid→ provider'sprovided.uuidsatisfied[]responsibility-uuid→ provider'sresponsibility.uuidNote the
providedelement's own description already says it "describes a capability which may be inherited" — the conceptual fit is latent in the existing vocabulary.Possible application to capability↔component. A cDef capability is arguably a provider: it provides the emergent, joint portion of a control and relies on its member components for the rest. If the pattern were reused inside the Component Definition — e.g. allowing a capability's
implemented-requirementto carryprovided/responsibilityentries that members reference byprovided-uuid/responsibility-uuid— today's prose-only, unlinked relationship (§3.4) would become formal and machine-checkable, letting a coverage tool see which part of a control the capability owns versus which parts roll up from members.Trade-offs to weigh. This pattern was designed for cross-system leveraging (two distinct authorization boundaries), so applying it to intra-document grouping is a conceptual stretch and may overload its meaning. A lighter alternative is a dedicated, narrower link — e.g. letting a capability's
implemented-requirementsimply cite the contributingcomponent-uuids for the samecontrol-id— which is simpler but less expressive (it shows who contributes but not who owns what). The choice between reuse, a new dedicated construct, or leaving the relationship as prose is left open for discussion.6.2 Approach 2 — explicit
contributionswith aggregation semanticsProposed by @Christoph-Puppe-Work, motivated by mapping German BSI (Federal Office for Information Security) IT-Grundschutz modules to OSCAL component definitions, where joint satisfaction is the default case rather than the edge case — e.g. a module like APP.4.4 (Kubernetes) is satisfied by {cluster, policy engine, registry, logging} together, never by a single component. This approach closes §3.4 with two small, optional schema additions plus machine-checkable validation constraints, as a narrower alternative to reusing the
provided/responsibilityhandshake (§6.1).contributionsarray onimplemented-requirement(fragment; the enclosingcontrol-implementationwith its requireduuid/source/descriptionomitted for brevity):Defined aggregation semantics to settle double-counting deterministically:
authoritative: the capability's statement is the countable satisfaction for that control-id; matching declarations on referenced members are inputs and MUST NOT be counted additionally by coverage tools.additive: capability and member statements are independent partial contributions.Validation constraints (Metaschema/Schematron — machine-checkable, which is the decisive advantage over a pure links/
relconvention):incorporates-componentsgraph MUST be acyclic;contributions/component-uuidMUST be a direct or transitive member of the capability;aggregationis REQUIRED whenevercontributionsis present;type="capability"component SHOULD have ≥ 2 members.Pros
type="capability"component can incorporate other capability-typed components, directly answering @brian-ruf's multi-level logging example — different control families answered at different depths.aggregation, who owns the count, without importing cross-system leveraging semantics into intra-document grouping.Cons
contributions,role,aggregation) beyond what §6.1 would require, even though it is optional.role(and theaggregationprop's values) should align with existing NIST terminology — likely NIST IR 8744 — rather than being coined ad hoc; this alignment hasn't been done yet.References
oscal_component_schema.jsonandoscal_ssp_schema.json.get_oscal_schema) and re-verified against the officialoscal_component_schema.jsonandoscal_ssp_schema.jsonfrom the v1.2.2 release.All reactions