Support for control mapping

[david-waltermire]

Committer Notes

This PR provides OSCAL mapping support.

All Submissions:

• Have you selected the correct base branch per Contributing guidance?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you squashed any non-relevant commits and commit messages? [instructions]
• Do all automated CI/CD checks pass?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you included examples of how to use your new feature(s)?
• Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

[david-waltermire]

A draft XML Schema is available that incorporates the draft mapping model.

[iMichaela]

Current model defines relationship construct with the allowed values:
equal-to (suggested to change to equivalent-to)
subset-of
superset-of

I am suggeting to allow equal-to as well as equivalent-to
equal-to would apply to cases like a CCI that copied a statement of an 800-53 control statement or for a mapping of the ACSC’s catalog where some controls from 800-53 are adopted by Australian Gov.
A relationship of equivalent-to could probably be used for the example of mapping CIS 1.1 to CM-8 + CM-8(1).
Other fields of the relationship should allow for capturing:
• different degrees of equivalence in terms of the entropy of the information (granularity of the requirements),
• information coverage,
• directions: source-to-target, target-to-source and bi-directional (both) and
• even documenting multi-mapping of the same control.

the degree of coverage is not the same thing with subset-of and superset-of.

I will have a dummy example to seed the conversation.

[iMichaela]

here is the gist provided by @david-waltermire-nist : https://gist.github.com/david-waltermire-nist/ad5fba71ccfe4d5a07b6b8b07238b0d4

Note: this link is also provided above as "draft XML Schema".

[iMichaela]

NOTE: This example can be presented in OSCAL as well, but having it first here for discussion purpose might be more beneficial at this point.

If we assume two catalogs: Catalog A and Catalog B
And if we consider the following controls:
Catalog A-control1 (A1): Data in transit must be encrypted
Catalog B-control1 (B1): Transport Layer Security (TLS) 1.3 must be implemented for all transiting data
Catalog B-control2 (B2): All web must implement HTTPS

Assuming:
Catalog A=source
Catalog B=target

Since OSCAL is not prescriptive, and for different purposes, (e.g. B1 and B2 could be part of different profiles) mappers/users of the mapping model can describe the relation in any way they find suitable for them, depending on the mapper's (human) view, perspective or needs:

OPTION 1 (using current mapping model):
uuid=1001: A1 superset-of B1
uuid=1002: A1 superset-of B2
uuid=1003: A1 equivalent-to B1 + B2

I find the information provided by this mapping above insufficient to support transitivity and proper traceability for assessment data and purpose.

OPTION 2 (per the comment I left earlier)
uuid=2001: A1 superset-of B1
-Unidirectional relation: target -> source (meaning if target=true then source could be true and infer that easily in the context of specific systems based on the system's functionality or architecture, and a simple check of B1, in this context, is transitive to A1, BUT if source =true I cannot infer anything about target being true based on the simple check of A1. Concrete implementation details are needed and a check of TLS and version number. )
-information entropy/richness A1<B1 (meaning A1 provides less guidance or fewer requirements than B1)
-Multiple mappings exist (related-to uuid_2002)

uuid=2002: A1 superset-of B2
-Unidirectional relation: target->source (if target=true then source could be inferred true with the caveates described above, BUT if source=trueI cannot infer anything about target being true or not)
-information entropy/richness A1<B2 (meaning A1 provides less information or fewer requirements than B2)
-Multiple mappings exist (related-to uuid_2001)

uuid=2003: A1 equivalent-to B1
-Unidirectional relation: target -> source (meaning if target=true then source could be true and infer that easily in the context of specific systems based on the system's functionality or architecture, and a simple check of B1, in this context, is transitive to A1, BUT if source =true I cannot infer anything about target being true based on the simple check of A1. Concrete implementation details are needed and a check of TLS and version number. )
-information entropy/richness A1<B1 (meaning A1 provides less guidance or fewer requirements than B1)
-information coverage A1>B1 (because B1 is specific to the transport layer while A1 is generic and is
applicable to web applications and to the transport layer security)
-Multiple mappings exist (related to uuid_2004)

uuid=2004: A1 equivalent-to B2
-Unidirectional relation: target->source (if target=true then source=true for the data layer transport only,
but if source=true cannot say anything about target being true or not without additional information and checks)
-information entropy/richness A1<B2 (meaning A1 provides less information or fewer requirements than B2)
-information coverage A1>B2 (because B2 is specific to web application (hypertext transfer) while A1 is generic and is applicable to web applications and transport layer)
-Multiple mappings exist (related to uuid_0001)

uuid=2005: A1 equivalent-to B1 U B2 (union/addition of requirements)
-Unidirectional relation: target->source (if target=true then source could be true, but if source=true cannot say anything about target being true or not)
-information entropy/richness A1<B1UB2 (meaning A1 provides less information or fewer requirements than B1 and B2 together)
-information coverage A1 <=> B1UB2 (equivalent-to not equal-to since semantic interpretation are possible )

I am also thinking that to use the mapping for the implemented controls in SSPs or CDEFs, it is important to allow the mapper to provide more information related to the relationship and some flexibility in tailoring the relationship at different levels in the stack (profile, implementation, assessment)

[iMichaela]

@jason-callaway - Your review is greatly appreciated. Could you please also provide the types of relations you identified in your extensive mappings between different control catalogs? Thank you.

[jason-callaway]

Hi, @iMichaela! I like your relationships of superset-of and equivalent-to. If I understand correctly, superset-of would imply a directed relationship between controls like A → B, whereas equivalent-to would imply a bidirectional mapping. But in order for that to work, wouldn't you'll have to define set theory operators like ≡, <, >, ∪, ∩, etc.?

sckg has the following relationship types:

• REQUIRES
• DEFINES
• IMPLEMENTS
• HAS
• REFERENCES

Here's the schema from call db.schema.visualization():

I'd love to also capture those relationships, particularly A1 ≡ B1 U B2, but I'm unaware of any datasets (aside from CSF) that provide those qualitative mappings. If you know of any that do, please share!

[david-waltermire]

@jason-callaway

Hi, @iMichaela! I like your relationships of superset-of and equivalent-to. If I understand correctly, superset-of would imply a directed relationship between controls like A → B, whereas equivalent-to would imply a bidirectional mapping. But in order for that to work, wouldn't you'll have to define set theory operators like ≡, <, >, ∪, ∩, etc.?

The mappings superset-of and subset-of can be reversed according to set theory.

A superset-of B can be notated as A ⊃ B. This relationship can be reversed as B ⊂ A (which is B subset-of A).
Similarly, A subset-of B, notated as A ⊂ B, which can be reversed as B ⊃ A (B superset-of A).

I'd love to also capture those relationships, particularly A1 ≡ B1 U B2, but I'm unaware of any datasets (aside from CSF) that provide those qualitative mappings. If you know of any that do, please share!

Part of why we want to create a more formal, mathmatically sound model is to allow for more automated inferencing around mappings. The difficulty part about the current state of mapping is that most mappings are created through opinion and rough consensus, but are not always mathmatically sound. We are trying to strike a good balence in defining relationships that can be easily understood and applied, that lead to mathmatically sound results.

sckg has the following relationship types:

• REQUIRES
• DEFINES
• IMPLEMENTS
• HAS
• REFERENCES

Can you provide definitions for and/or some short examples of use of your relationships?

[iMichaela]

The 'union' and 'intersect' were introduced also in issue #1221 . The discussion should be merged. And @david-waltermire-nist is accurate - we want a precise but flexible-enough mathematical model that allows experts like you, @jason-callaway, to use it with ease.
I am also curious to get a better understanding, maybe through an some examples, of the relationships you listed:

• REQUIRES
• DEFINES
• IMPLEMENTS
• HAS
• REFERENCES
  To me, just from their names, they are providing relationships not between independent controls for the purpose of mapping them, allowing to say "I did CatalogA:c1, end because it is a superset-of CatalogB:c5 and has same entropy/richness of information and information coverage, now I can infer that I implemented and assessed also CatalogB:c5 because of their mapping". The relationships you listed appear to identify dependabilities among controls and the types of relationship that could be encountered.

This can also be useful information... so maybe we should consider including a field that identifies if the controls are independent or or not. Because the dependability relationship are also very important for the controls satisfaction and assessments.

[jason-callaway]

Thanks, @david-waltermire-nist and @iMichaela for your responses!

Here are some examples of sckg's relationship types:

HAS

Regimes, families, baselines, and controls themselves can all "have" a child control. Like in the example below, the NIST 800-53 regime has a family, AC, which in turn has controls.

MATCH p=((r:regime {name: 'NIST 800-53'})-[:HAS*]->(f:family {name: 'AC'})-[:HAS*]->(c:control)) 
WHERE c.name IN ['AC-1', 'AC-2', 'AC-3'] 
RETURN p

DEFINES

Sometimes a regime has a control that's defined in some other place, like the 800-53r4's Appendix J.

MATCH p=((b:baseline {name: 'Appendix J'})-[:DEFINES]->(c:control)) 
WHERE c.name IN ['AR-1', 'AR-2', 'AR-3'] 
RETURN p

IMPLEMENTS

In the ComplianceAsCode project, controls are broken into Rules that define what a given regime requires, whereas the Steps define (typically in bash) steps to implement that rule. In this example we're looking at a bash step that sets passwords to be non-empty on RHEL 7, which IMPLEMENTS the associated rule.

MATCH (r:regime {name: 'ComplianceAsCode'})-[:HAS]->(b:baseline) 
WHERE b.name in ['rhel7-script-stig.sh', 'Rules']
WITH r, b
MATCH (b)-[:HAS]->(c:control {name: 'no_empty_passwords'})
RETURN r, b, c

REFERENCES

Regimes like DoD CCI (for which the label "regime" isn't completely right but I haven't thought of a better one yet) define their own things -- in this case CCIs -- that reference more traditional regime controls like those from NIST 800-53.

MATCH (r:regime {name: 'DoD CCI'})-[:HAS]->(b:baseline)
WITH r, b
MATCH (b)-[:HAS]->(rc:control {name: 'CCI-001234'})
WITH r, b, rc
MATCH p=((n:regime {name: 'NIST 800-53'})-[:HAS*]->(nc:control {name: 'SI-2 (2)'}))
RETURN r, b, rc, n, p

REQUIRES

Some regimes like CNSSI 1253 rely on controls from other regimes like NIST 800-53. In this example, the National Security Systems (NSS) baseline requires AC controls from NIST 800-53.

MATCH (r:regime {name: 'CNSSI 1253'})-[:HAS*]->(b:baseline {name: 'NSS'}) 
WITH r, b
MATCH (b)-[:REQUIRES]->(c:control)
WHERE c.name in ['AC-1', 'AC-2', 'AC-3']
RETURN r, b, c

[iMichaela]

@jason-callaway Thank you for all the examples. As I assumed, you are mainly capturing dependencies as opposed to possible relations among independent frameworks (with the CCI exception that could be perceived as independent when actually is not.
OSCAL can already take care of the parent-child control relationships and of families of controls. As for the CCIs relationships to SP 800-53, when a CCI is a word-by-word a statement of a control, then that can be represented in the mapping model as equal-to at the statement of control level or, at minimum map them as shown below

For example, if:

Control1:
-stm_1
-stm_2
-stm_3

and

CCI_1 is exactly the same stm_1
CCI_4 is exactly the same sum_3

Then

Control1 ⊃ CCI_1  ∪ CCI_4

**I will need to know what is left out (e.g. stm_2) because it is a MAJOR difference between the case shown above when parts of the control can be mapped as equal-to or ≡ to subsets, versus having the example used in the example on top of the page: uuid=1002: A1 superset-of B2 that can be re-written as uuid=1002: A1 ⊃ B2

And If I have another CCI

CCI_6 is the same as `stm_2`

Then

Control1  ≡ CCI_1  ∪ CCI_6 ∪ CCI_4

However, in such cases it would be more useful to actually be able to do the mapping at the statement level.

Control1.stm_1 ≡ CCI_1  
Control1.stm_2 ≡ CCI_6
Control1.stm_3 ≡ CCI_4

[jason-callaway]

You are quite correct, @iMichaela! The closest thing I have to inter-regime mappings comes from NIST CSF. It lets me do things like map 800-53 controls from the FedRAMP High baseline to PCI DSS requirements.

MATCH (:regime {name: 'FedRAMP'})-[:HAS]->(high:baseline {name: 'High'})
WITH high
MATCH (csf:regime {name: 'NIST CSF'})-[:HAS*]-(b:baseline)
WITH high, b
MATCH (nist:regime {name: 'NIST 800-53'})-[:HAS*]->(nc:control)
WITH high, b, nc
MATCH (pci:regime {name: 'PCI DSS'})-[:HAS*]->(pc:control)
WITH high, b, nc, pc
MATCH (high)-[:REQUIRES]->(nc), (b)-[:REQUIRES]->(nc), (b)-[:REQUIRES]->(pc)
RETURN nc.name AS FedRAMP_High, collect(distinct pc.name) AS PCI ORDER BY FedRAMP_High

The issue here is that CSF provides little data in terms of equivalency. For example, the first result suggests:

AC-1 ≡ [8.2.2, 7.2, 7.1, 6.4.2, 12.3.10, 12.3.9, 12.3.8, 8.5.1, 8.3, 8.1.5, 12.3, 8.2, 8.1]

Is this actually true? I haven't analyzed it -- partly due to a lack of cycles, but also because everything in the graph so far is a un-opinionated transformation of data formats. I think I'm getting away from what's applicable to this PR, so I'll stop now; I just wanted to be clear on the limitations of my data.

[iMichaela]

@jason-callaway As for frameworks that requires controls from other frameworks... there si a clear relation that needs to be represented, but part of that requirements needs to be FIRST properly captured in OSCAL catalog and I am not sure yet what is the best practice in this case.

For control D1: " All OWASP controls must be implemented"

and the OWASP controls are

O1, O2, O3, O4

Then the OSCAL Catalog will have to FIRST represent it.
Using a mapping approach, it will be simple,

D1 ≡ O1 ∪ O2 ∪ O3 ∪ O4 

but will not be super accurate from the OSCAL Catalog D perspective which would need to first represent control D1 properly/completely, and not just state it in pure English statement. Not sure how to do that yet. Such control exists in one catalog that is currently being formatted in OSCAL. But this is a different issue.

[iMichaela]

[...]

The issue here is that CSF provides little data in terms of equivalency. For example, the first result suggests:

AC-1 ≡ [8.2.2, 7.2, 7.1, 6.4.2, 12.3.10, 12.3.9, 12.3.8, 8.5.1, 8.3, 8.1.5, 12.3, 8.2, 8.1]

Is this actually true? I haven't analyzed it -- partly due to a lack of cycles, but also because everything in the graph so far is a un-opinionated transformation of data formats. I think I'm getting away from what's applicable to this PR, so I'll stop now; I just wanted to be clear on the limitations of my data.

This kind of mapping we are trying to support while allowing the mapper to be more precise so the mapping can be used for traceability and mutual recognition of assessments.

[vikas-agarwal76]

@david-waltermire-nist I looked at the example mapping and the schema. Here are some comments based on my understanding. Not sure if you already addressed those.

I believe there are 4 possible relationship types between source control and target controls (one or more) -

1. Equivalent - the source control and target controls are equivalent in requirements
2. subset - the target controls represent a strict subset of the requirements of source control
3. superset - target controls represent a superset of source control requirements
4. overlaps - source and target controls have overlapping requirements, but some source control requirements are not met by target controls and there are some additional requirements in target controls not specified by source control

In the example the source and target types are "control". Can we have other types also say "part" - for example "AC-1.a", if I want to specify mapping for a specific part of a source control to a specific part of a target control.

I believe the schema allows more than one source control to be specified as part of a mapping, but generally one source will be mapped to one or more targets.

[david-waltermire]

@vikas-agarwal76 Thank you for the feedback.

@david-waltermire-nist I looked at the example mapping and the schema. Here are some comments based on my understanding. Not sure if you already addressed those.

I believe there are 4 possible relationship types between source control and target controls (one or more) -
1. Equivalent - the source control and target controls are equivalent in requirements
2. subset - the target controls represent a strict subset of the requirements of source control
3. superset - target controls represent a superset of source control requirements
4. overlaps - source and target controls have overlapping requirements, but some source control requirements are not met by target controls and there are some additional requirements in target controls not specified by source control

For number 4, I would call this "intersects-with".

In the example the source and target types are "control". Can we have other types also say "part" - for example "AC-1.a", if I want to specify mapping for a specific part of a source control to a specific part of a target control.

Yes. This mapping model is intended to support mapping at the part/statement level.

I believe the schema allows more than one source control to be specified as part of a mapping, but generally one source will be mapped to one or more targets.

While I agree that one source to one or more targets will be a common case, we are trying to be flexible here to support many-to-many mapping cases as well. The model can handle all these mapping pattern variants.

[vikas-agarwal76]

@david-waltermire-nist Thanks for the clarifications.

I believe a 5th relationship that may be good to capture would be "None" or "Null". This is to explicitly capture cases where no mapping (not even partial) exists for a source control in the target catalog. In this case the target controls will be empty.

This will help distinguish cases where no mapping has been specified till now versus no mapping exists at all. One may want to explicitly state that fact for completeness to avoid any ambiguity.

[aj-stein-nist]

@david-waltermire-nist I got a few things I would like to sync up on issues that came up when prepping @degenaro to build a copy of the docs locally. I assume these are docs pipeline issues, but 1/2 I cannot tell require finalized Metaschema changes to get "picked up" but I was scratching my head on where the WIP mapping-collection model "went."

1. This is a minor nit: but when you build off a branch for development, the webpage generates incorrect branch references presuming the branches are from origin repo (github.com/usnistgov/OSCAL/tree/{{branch}} or the like). This is wrong in some or many cases, is this worth fixing?
2. More significant and I need to look through generate-model-documentation.sh is the mapping-collection model is not indexed on the reference landing page, only findable in the complete all models collection page in JSON and XML outline form. This should work as-is now, right?

Let me know or we can discuss during triage, and I can make 1 or 2 separate issues to track, but 2 is the more urgent one obviously.

[aj-stein-nist]

1. This is a minor nit: but when you build off a branch for development, the webpage generates incorrect branch references presuming the branches are from origin repo (`github.com/usnistgov/OSCAL/tree/{{branch}}` or the like). This is wrong in some or many cases, is this worth fixing?

Per conversation, I made #1286.

2. More significant and I need to look through `generate-model-documentation.sh` is the `mapping-collection` model is not indexed on the reference landing page, only findable in the complete all models collection page in JSON and XML outline form. This should work as-is now, right?

Dave pointed out this requires in branch modifications of the Metaschema and docs pipeline, no separate issue or development branch is need for item 2.

[david-waltermire]

After meeting on 6/29, we decided that this PR can be merged. As follow on work we identified the need to create two issues:

1. Add new relationships that roughly relate to "more specific" and "less specific".
2. Explore more concrete scenarios based on use of this model to identify cases that may not be supported.

[david-waltermire]

@iMichaela As we discussed on 6/30/2022, please update your review by CoB 7/1/2022.

[iMichaela]

I am approving the PR with the strong recommendation to review and consider the comments when deemed reasonable and accurate.

[iMichaela]

@david-waltermire-nist PR review was completed.

The issue raised earlier by @vikas-agarwal76 intersects-with my second from the bottom comment (see above) and is not supported in the current version, but we might need to give a second thought to it.

@david-waltermire-nist Thanks for the clarifications.

I believe a 5th relationship that may be good to capture would be "None" or "Null". This is to explicitly capture cases where no mapping (not even partial) exists for a source control in the target catalog. In this case the target controls will be empty.

This will help distinguish cases where no mapping has been specified till now versus no mapping exists at all. One may want to explicitly state that fact for completeness to avoid any ambiguity.

[david-waltermire]

@david-waltermire-nist Thanks for the clarifications.
I believe a 5th relationship that may be good to capture would be "None" or "Null". This is to explicitly capture cases where no mapping (not even partial) exists for a source control in the target catalog. In this case the target controls will be empty.
This will help distinguish cases where no mapping has been specified till now versus no mapping exists at all. One may want to explicitly state that fact for completeness to avoid any ambiguity.

This would require making the cardinalities on the target items min-occurs="0", which would affect all mapping entries. This means that schema validation of cardinalities for these items for all other relationship types would not be possible, but would require constraints instead. I'd rather keep the cardinalities as-is if possible.

It would be better to support this using a different construction that would follow the existing mappings to define unmapped particles (i.e., controls, or control statements). A new issue should be created for this. This will allow for more discussion with the community around if this feature is needed and how to support it. @iMichaela Would you please make a new issue for this?

[iMichaela]

Thank you.

[flickerfly]

I just want to take a moment to celebrate those who worked on this. You all rock! Thank you!

[sunstonesecure-robert]

Have you thought about using NIST 800-53A (A for assessment) keywords and doing some fuzzy match, with (or without) ontology matching? (NLP ML based mapping left as a challenge problem for the reader.)

…

On Thu, May 5, 2022 at 12:10 PM Jason Callaway ***@***.***> wrote: You are quite correct, @iMichaela <https://github.com/iMichaela>! The closest thing I have to inter-regime mappings comes from NIST CSF. It lets me do things like map 800-53 controls from the FedRAMP High baseline to PCI DSS requirements. MATCH (:regime {name: 'FedRAMP'})-[:HAS]->(high:baseline {name: 'High'}) WITH high MATCH (csf:regime {name: 'NIST CSF'})-[:HAS*]-(b:baseline) WITH high, b MATCH (nist:regime {name: 'NIST 800-53'})-[:HAS*]->(nc:control) WITH high, b, nc MATCH (pci:regime {name: 'PCI DSS'})-[:HAS*]->(pc:control) WITH high, b, nc, pc MATCH (high)-[:REQUIRES]->(nc), (b)-[:REQUIRES]->(nc), (b)-[:REQUIRES]->(pc) RETURN nc.name AS FedRAMP_High, collect(distinct pc.name) AS PCI ORDER BY FedRAMP_High [image: Screen Shot 2022-05-05 at 3 04 58 PM] <https://user-images.githubusercontent.com/3760617/167006193-1e95bec1-db87-4409-aa26-3735b69c2d70.png> The issue here is that CSF provides little data in terms of equivalency. For example, the first result suggests: AC-1 ≡ [8.2.2, 7.2, 7.1, 6.4.2, 12.3.10, 12.3.9, 12.3.8, 8.5.1, 8.3, 8.1.5, 12.3, 8.2, 8.1] Is this actually true? I haven't analyzed it -- partly due to a lack of cycles, but also because everything in the graph so far is a un-opinionated transformation of data formats. I think I'm getting away from what's applicable to this PR, so I'll stop now; I just wanted to be clear on the limitations of my data. — Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQWTGFDFEHRMROGVVTR6NJLVIQMLZANCNFSM5PH6DXUA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>