opencontrol/schemas

YAML schema, examples, and validators for OpenControl format.

schemas's Issues

Splitting properties for a single component across multiple component.yaml files

The component.yaml files tend to get quite large and more difficult to navigate when they satisfy a large number of controls. As such, it would be great to split content in to multiple component.yaml files for a single component and have compliance-masonry include the ability to aggregate them in to one

deprecate the OpenControl schemas?

OSCAL seems to have reached a point of maturity where the format has surpassed the expressiveness and completeness of the OpenControl schemas. I'm sure they're not perfect, but unlike the OpenControl ones, they are actively being worked on. Might be time to thank the OpenControl schemas for their service and indicate they are deprecated, recommending people use OSCAL instead.

Note this does not mean deprecating of the OpenControl brand or community. In fact, without having the baggage of the schemas to (not) maintain, more focus could be put towards tooling or documentation or whatever else.

Thoughts?

cc opencontrol/compliance-masonry#343

Docker example link in readme is broken

Fix: Update link to https://github.com/docker/compliance/tree/master/examples/opencontrol/DockerEE-Moderate-ATO

#68

Crosswalk to "OASIS Topology and Orchestration Specification for Cloud Applications" (TOSCA)

OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA)

TOSCA v1.0 Standard in YAML

Creating implementation_status: not applicable

Having implementation_status express that a control is not applicable would be valuable. What is the process to update the schema? Should a PR be opened with the new enum, or something more?

schemas/opencontrol-component-kwalify-schema.yaml

Line 91 in dada46a

- none

          implementation_status:
            type: str
            enum:
              - partial
              - complete
              - planned
              - none

`link` attribute not defined for narratives

It appears in the cloud.gov documentation:

https://github.com/18F/cg-compliance/blob/238c8f9324dde419f2ba5cfb01be35ddee2c323a/SC_Policy/component.yaml#L23

We may want to consider adding support in the schema.

create a Kwalify file for standards

Broken out from #52.

https://github.com/opencontrol/schemas#standards

/cc @jmacarthur #53

As a user, I would like to see a full standalone minimal example

This will probably live as its own repository, but we should consider making a small example standard, certification, and set of components on top of it to demonstrate how the tool works, without requiring that someone understand complex things like NIST 800-53, FedRAMP, etc. Could also be useful as an integration test.

Idea stolen from pburkholder/ato1day-compliance#1.

Number of missing controls

I tried my hand at building an opencontrol based SSP but am confused on the results. after running compliance-masonry get then compliance-masonry diff <name of my certification> all controls in my certificate are listed under Number of missing controls even though I include them in my component.yaml.

To see if I did something wrong, I cloned down the cg-compliance repo and repeated the two compliance-masonry commands and surprisingly got the same results of all controls missing when diff'ing against FedRAMP-moderate or FedRAMP-low. Finally, I repeated the process against freedonia-compliance for the FredRAMP-low certification but got the desired Number of missing controls: 0 result.

Should cg-compliance be reporting all controls as missing?

As a user, I want to know what inherited controls are still my responsibility

There was some discussion in the 18F Slack, which boils down to the following example:

Suppose you are building System X on top of cloud.gov. Let's take an arbitrary control family, like contingency planning. cloud.gov may have its own contingency plan, but that doesn't mean that System X does. We need a way to indicate what controls (or control family? or control implementation?) family can be inherited and thus take care of the requirement for System X, and which System X is required to fulfill on top of cloud.gov.

@cmc333333 ran into this problem when trying to do gap analysis, almost immediately after setting up an opencontrol.yml in 18F/epa-notice#424:

that leaves only

Number of missing controls: 1
NIST-800-53@SC-12 (1)

When diffing with LATO. does that seem right?

references/type seems to have no use

https://github.com/opencontrol/schemas/blob/master/opencontrol-component-kwalify-schema.yaml#L26-L28 has reference/type listed as required but it doesn't seem to be consumed in any useful way by masonry.

It seems to expect URL or Image as value, but those values don't seem to have any effect.

Could someone provide documentation on it's use? Could we remove the required flag if isn't actually required?

As a user, I want to validate all of my files

Currently, this repository only contains schema validations for components. Assuming we want to keep this repository around, we should have kwalify files for all different files: Standards, Certifications, and opencontrol.yaml.

update README Component Structure for v3.1.0

Follow-up to #42.

Address feedback from SIMP

Just found this issue after digging from the SIMP Security Control Mapping:

https://simp-project.atlassian.net/browse/SIMP-721

Granted, it's a couple years old, but we should figure how how/if to address those shortcomings. This issue will probably be broken out to smaller ones.

cc @trevor-vaughan

Trying to make a schema for specifications

I thought I'd try making a schema for standards files (e.g. https://github.com/opencontrol/NIST-800-53-Standards/blob/master/NIST-800-53.yaml)

However, it doesn't seem possible to specify a schema that accepts it; kwalify says that that file is neither a sequence nor a mapping. Upstream activity on Kwalify seems to have stopped. Has anyone tried making this schema before? I realise it's a trivial format and doesn't really need a schema; I'm just doing this an introductory exercise.

Standard way to link to parts of my project

We've been reviewing OpenControl, apologies if I missed something, but is there a standard way to link to other parts of my project? For example, if I am describing my compliance with a control, sometimes I'd like to link part of my project's specification, or a test, or maybe some of the source code. I notice some yaml documents have verification fields with the type TEST; is that part of the standard? We would be happy to contribute some documentation once we have a better understanding.

Also, is there a better place to ask questions that aren't really issues? Do you have a mailing list for OpenControl, for example?

update example project organization

The information is no longer correct.

https://github.com/opencontrol/schemas#example-project-organizations

The component "satisfies" map type should accept a "references" property that accepts a sequence of URLs, etc

For each control map under the satifies property, there should be a property called references that takes a sequence of reference maps with name and url properties. This helps to clean up any reference documentation for each control rather than having to include URLs in each control's narrative(s).

For example

satisfies:
  - control_key: AC-1
    covered_by: []
    implementation_statuses:
      - implementation blah
    control_origins:
      - origin blah
    narrative:
      - key: a
        text: |
          Blah
    references:
      - name: 'My doc page'
        url: https://urltomydocpage
    standard_key: NIST-800-53

Be specific when using "certification"

FedRAMP has brought up that "certification" has a specific legal meaning and it doesn't actually apply to what they do. We should potentially restructure what we're calling these things to accommodate the difference.

FedRAMP calls itself a "verification" but since we use that word elsewhere, that could get confusing. A potential solution is aligning with what our NIST colleagues are calling a "profile". I'll be working on this next week.

As a user, I want to know the possible values for various fields

e.g. implementation_status. Right now the easiest way to check is pointing them to the schema file, but these should be listed in the README for convenience.

Close stale issues

There are many issues that are from over 4 years ago; suggest we close the issues that are stale and no longer relevant.

remove opencontrol-component-kwalify-schema.yaml

https://github.com/opencontrol/schemas/blob/master/opencontrol-component-kwalify-schema.yaml

See disclaimer at top, and #35.

As a user, I would like to see an example `opencontrol.yaml` file

We don't seem to document the top-level opencontrol.yaml file itself.

I'd propose pulling in the test YAML from https://github.com/opencontrol/compliance-masonry/blob/master/config/versions/1.0.0/schema_test.go#L27-L50 and saving that here as opencontrol-v1_0_0-example.yaml.

Define a BDD boundary in the schema

Per @mogul's comments in opencontrol/discuss#19.

implementation_status needs to allow for multiple values

For some implementations, implementation_status can contain multiple values. Example: FedRamp controls could be both partially implemented and planned.

• Schema should accept implementation_statuses as an array of string in version 3.0.0
• Schema should accept implementation_status as a string in versions 2.0.0 and 3.0.0

define the narrative sections as being Markdown?

For the cloud.gov compliance, we are putting Markdown formatting in the narrative sections (maybe more)...should we say in the schema that Markdown is supported in that field?

Add NIST Control Assignments and Minimum Requirements

Work in Progress: NIST Control Assignments and Minimum Requirements for Low, Moderate, High Systems (w/ NIST/FEDRAMP/DOD Requirements) from http://iasecontent.disa.mil/cloud/SRG/index.html

https://gist.github.com/JJediny/7820bd39c6a2221bbe893271e1d2f969

@gregelin I remember a related issue on OpenSCAP?

collect examples of various types

@afeld commented on Fri Jul 01 2016

We have some examples listed in the README, but there are more repositories of various kinds that should be linked to for reference. Will add to this list, then figure out where they should go later.

• https://github.com/opencontrol/compliance-masonry#examples (remove from here)
• https://github.com/pburkholder/freedonia-compliance
• https://github.com/pburkholder/freedonia-aws-compliance
• https://github.com/pburkholder/ato1day-compliance
• https://github.com/18F/GSA-Certifications
• https://github.com/eregs/notice-and-comment
• https://github.com/18F/epa-notice
• https://github.com/18F/calc

Ideas for how to version schemas

I'll try to put tother some schemas and examples for version 1 and 2 for now.

Any thoughts on how to version schemas?

update for Schema V3

README etc. needs an update to correspond to opencontrol/compliance-masonry#160.

control_origin needs to allow for multiple values

For some implementations (i.e. FedRamp), the control origination can contain multiple values.

Crosswalk to "Security Automation and Continuous Monitoring (sacm)"

https://datatracker.ietf.org/wg/sacm/documents/

Consider changing documentation_complete to status

status:
  - todo: 10
    doing: 0
    done: 90   
    issues:
    - issue: info #todo, doing, done
      text: 
      url: 

Question- use-case

My team is looking to deploy a library that will be used to tag nist controls to opa evaluation results for visualization in kibana. Came across open control and believe the functionality is there but was hoping someone might be able to spend 20 minutes walking us through the various use cases and determining if ours is in scope. We are hoping to source a library that is able to mutate based on the various compliance products such as fedramp mod, high, irs1075, gdpr etc and apply the correct parameters/impacts. If someone is able, willing to meet we would greatly appreciate it!

Component and System descriptions

@geramirez commented on Wed Feb 10 2016

In addition to references, component and system should also have a section for descriptions.

enforce that Masonry matches the schema

Right now, (I think) there is nothing tying the Masonry code to the content in this repository, other than us being careful. Would be helpful to have Masonry tests that validate the schema is still being followed, or maybe better yet, generate the schema from code+comments.

/cc opencontrol/compliance-masonry#143 (comment)

decide on canonical schema validation file

Right now, this repository contains files for Kwalify and JSON Schema, which adds maintenance burden—it's easy for them to get out of sync. We should pick one and drop the other, or make a way to generate one from the other. Relevant:

http://rx.codesimply.com/faq.html#why-not-use

/cc @jcscottiii @joshuamckenty @geramirez

Component files does not exist

$ rpm -qa '*masonry*'
compliance-masonry-1.1.5-1.x86_64
$ masonry docs gitbook NIST-SP-800-171r1_all
An error occurred: Component files does not exist

The error message does not help. Which of the yaml files is missing the "files" component? Or am I misreading the error and there are missing "component files".

create a Kwalify file for certifications

https://github.com/opencontrol/schemas#certifications

/cc #53

Consider alternative schema validator to kwalify

In order to ensure opencontrol schema validation is flexible and adapted to newer tooling, consider an alternative schema validation from kwalify.

Not that there's anything inherently wrong with kwalify, but it's ~11+ years old since it's last release (https://github.com/kvs/kwalify + http://www.kuwata-lab.com/kwalify/), and there may be alternative schema descriptors and validations which are a bit more widely-used nowadays than kwalify (maybe*. and it doesn't mean others would be any 'easier' or 'better' anyway).

some considerations:

• openapiv3, which most folks would probably be familiar with from Kubernetes CRD resource definitions? https://openapi.tools/#data-validators unsure if there are straightforward standalone clis for validating a document against a schema document
• jsonschema (https://json-schema.org/implementations.html) which I'm familiar with from jsonresume (https://github.com/jsonresume/resume-schema/blob/v1.0.0/schema.json) but not sure if that's really what we want + provides happy interop with golang tooling. I just genuinely don't know, and, of course, I haven't done research on it, so I'm talking out of my butt.

---

I crossed out my initial issue comment body because I don't think this is super pressing issue-- and I don't have a strong contender for an alternative, let alone if it should be considered at all-- but still, putting it here for issue-tracking purposes. There doesn't seem to be anything broken with the current setup, so it might be just as well to leave it be.

Thanks! 👍

k8s-style metadata on resources

I find myself wanting to add metadata to controls with labels like "myorg.io/team: platform-engineering", "myteam.io/tier: networking", "myteam.io/contacts: [email protected],'beep bop'", `myteam.io/last-reviewed: '-or-github-issue'-- information which could be comments or shoved into the "implementation-statuses" field, but also feels like there's a place for them as structured data.

It might be worth considering having a field for "metadata" e.g. "metadata.labels" akin to k8s resource definitions. That way adhoc metadata can be added on a user-need basis for multiple purposes without having to worry about modifying the schema itself with top-level keys.

Another potential(?) use of this could be for integrating with output generators depending on the needs of the rendering target; for example, having metadata.annotations[open-control.io/frontmatter-keywords]: 'comma separated', 'list-of', 'keywords' could be used by output renderers (see opencontrol/compliance-masonry#346) to include (again, just for example) frontmatter keywords in the generated output of a markdown document for a control/entire component/etc., or control whether frontmatter is included in the output at all, etc.;

So if there were hugo-specific rendering directives, it would just be a metadata annotation. If there were jekyl-specific rendering directives, it would just be a metadata annotation, etc.

(this should be a separate issue, I apologize, but-- In the general case I feel the kubernetes schema is pretty dang powerful, and there are bits and pieces of ideas that could be pulled from it. It wouldn't be that out of the realm of possibility to me that, even though this isn't a k8s resource itself, the structure could be used; e.g., "metadata.name", apiVersion (schema_version), kind (control, component, policy, etc.); the details aren't fully thought through, but it's worth considering the generalized mapping)

Just wanted to put it down for consideration. thanks for the time 👍

Standard control type should include a "Description" field

@anweiss commented on Fri Dec 02 2016

The Control type should parse a field called "Description" that includes a short description of the control/customer responsibility.

e.g.

type Control struct {
	Family      string `yaml:"family" json:"family"`
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description" json:"description"`
}

This relates to #54

README has wrong schema for certification and standard

The README sections for certification and standard are really outdated.

Example of standard:
https://github.com/opencontrol/NIST-800-53-Standards/blob/master/NIST-800-53.yaml

Example of certification:
https://github.com/opencontrol/FedRAMP-Certifications/blob/master/FedRAMP-moderate.yaml