This is the multi-page printable view of this section. Click here to print.
OSCAL, Open Security Controls Assessment Language, is a NIST-led, machine-readable representation of various control models. Find out more about OSCAL here.
The sub-pages describe the interaction between Lula and OSCAL, for detail on the specific OSCAL models see the OSCAL documentation.
An Assessment Result is an OSCAL model to report on the specific assessment outcomes of a system. In Lula, the validate command creates an assessment-result object to enumerate the assessment of the input controls provided by the component-definition. These are reported as findings that are satisfied or not-satisfied as a result of the observations performed by the Lula validations.
flowchart TD
A[Assessment Results]-->|compose|C[Finding 1]
A[Assessment Results]-->|compose|G[Finding 2]
B(Control)-->|satisfied by|C
B(Control)-->|satisfied by|G
C -->|compose|D[Observation 1]
C -->|compose|E[Observation 2]
C -->|compose|F[Observation 3]
G -->|compose|F[Observation 3]
G -->|compose|H[Observation 4]
D --> I(Lula Validation A)
E --> J(Lula Validation B)
F --> K(Lula Validation C)
H --> L(Lula Validation D)
Based on the structure outlined, the results of the observations impact the findings, which in turn result in the decision for the control as satisfied or not-satisfied. The observations are aggregated to the findings as and operations, such that if a single observation is not-satisfied then the associated finding is marked as not-satisfied.
The way Lula performs evaluations default to a conservative reporting of a not-satisfied observation. The only satisfied observations occur when a domain provides resources and those resources are evaluated by the policy such that the policy will pass. If a Lula Validation cannot be evaluated then it will by default return a not-satisfied result.
The following conditions enumerate when the Lula Validation will result in a not-satisfied evaluation. These cases exclude the case where the Lula validation policy has been evaluated and returned a failure.
The primary structure for Lula production and operation of assessment-results for determinism is as follows:
start time in descending ordertarget.target-id in ascending ordercollected time in ascending ordertitle in ascending order.Lula evaluate serves as a method for verifying the compliance of a component/system to determine if it is more or less compliant than a previous assessment. This enables OSCAL to serve as a quality gate for compliance evaluation - enabling automation and requiring governance of component or system updates.
The term threshold is used in Lula processes and workflows to delineate (optimally) a point-in-time where a component/system was most compliant. In identifying this state, a quality gate can be created to require meeting or exceeding said threshold.
The reason this is crucial is that the previous assessment may not always be the required state. Rather Lula allows capturing provenance for when that state was established and enabling teams to increment Automated Governance workflows. This may be allowing for failures until the assessments have a high level of fidelity in order to parallelize development.
When no previous assessment exists, the initial assessment is made and stored with lula validate. Lula will automatically apply the threshold prop to the assessment result when writing the assessment result to a file that does not contain an existing assessment results artifact. This initial assessment by itself will always pass lula evaluate as there is no threshold for evaluation, and the threshold prop with be set to true.
steps:
lula validate -f component.yaml -o assessment-results.yamllula evaluate -f assessment-results.yaml -> Passes with no Threshold -> Establishes ThresholdIn workflows run manually or with automation (such as CI/CD), there is an expectation that the threshold exists, and evaluate will perform an analysis of the compliance of the system/component against the established threshold.
steps:
lula validate -f component.yaml -o assessment-results.yamllula evaluate -f assessment-results.yaml -> Passes or Fails based on thresholdEvaluate will determine which result is the threshold based on the following property:
props:
- name: threshold
ns: https://docs.lula.dev/oscal/ns
value: "true/false"
When evaluate is ran with a single assessment results artifact, it is expected that a single threshold with a true value exists. This will be identified and ran against the latest result to determine if compliance is less-than-equal (fail), equal (pass), or greater-than-equal (pass). When the comparison results in greater-than-equal, Lula will update the threshold prop for the latest result to true and set the previous result threshold prop to false.
In the scenario where multiple assessment results artifacts are evaluated, there may be a multiple threshold results with a true value as Lula establishes a default true value when writing an assessment results artifact to a new file with no previous results present. In this case, Lula will use the older result as the threshold to determine compliance of the result.
A Component Definition is an OSCAL model for capturing control information that pertains to a specific component/capability of a potential system. It can largely be considered the modular and re-usable model for use across many systems. In Lula, the validate command will process a component-definition, iterate through all implemented-requirements to discover Lula validations, and execute those validations to produce observations.
The modularity of component-definitions allows for the specification of one to many components or capabilities that include one to many control-implementations.
By allowing for many control-implementations, a given component or capability can have information as to its compliance with many different regulatory standards.
The primary structure for Lula production and operations of component-definitions for determinism is as follows:
title in ascending order (Case Sensitive Sorting).source in ascending order.control-id in ascending order.title in ascending order (Case Sensitive Sorting).Lula can generate OSCAL templates to help with authoring OSCAL artifacts. These generation processes help with initial build and maintenance of OSCAL artifacts and keeps with the vision of modular compliance artifacts that live with the source code.
To generate a component definition, you need the following context:
-c or --catalog-source; IE https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.jsonimplemented-requirements / -r or --requirements; ac-1,ac-2,au-5The following command will generate a component definition with the above context:
lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-2,au-5
There are optional flags that can be added to the command to generate a component definition - see lula generate component for details.
The lula generate commands are meant to be reproducible and will auto-merge models based on filename. The intent for this generation is to make it easy to update a given model with automation and only inject human intervention as needed. An artifact generated with lula generate can be merged with a pre-existing artifact of the same model type.
For component-definitions, see each individual control-implementation props for the generation prop. It should look like the following:
props:
- name: generation
ns: https://docs.lula.dev/oscal/ns
value: lula generate component --catalog-source https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json --component 'Component Title' --requirements ac-1,ac-3,ac-3.2,ac-4 --remarks assessment-objective
This value should mirror any required inputs in order to reproduce a given control implementation in a component.
The ability to retain data that is put into OSCAL artifacts is of utmost importance to this generation process and also a large feature of continued maintenance of these artifacts. Lula supports the ability to merge newly generated component definition templates into existing component definitions automatically.
By specifying --output or -o and providing an existing file - Lula will perform a merge operation that only overwrites specific fields owned by automation.
Lula performs a match on the component title and the provided catalog source to determine placement and merge of the new implemented requirements. This can be used to updated exiting items or as a method to generation of a single artifacts that contains the data for many components or many control implementations.
lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-3,ac-3.2,ac-4 -o oscal-component.yaml --remarks assessment-objective
As indicated on the Extending OSCAL models page, Lula implements custom namespace props for enhancing the OSCAL experience with Assessment Automation and Automated Governance.
Component Definitions are built to be modular / re-usable components that can be applied against one-to-many systems. As such, it is expected that a single Component Definition can contain one-to-many Components with each Component containing one-to-many Control Implementations.
Each Control Implementation may reference a source to many disparate and connected or non-connected standards. As part of the Lula validate operation, the framework OSCAL prop exists for allowing a defined validation activity to include multiple Control Implementations into a single result for continued analysis.
This use of this prop is defined in control-implementation[_].props in the following format:
props:
- name: framework
ns: https://docs.lula.dev/oscal/ns
value: impact-level-x
This example would be for the specification of the “Impact Level X” collection of Control Implementations.
The generation prop is an identifier for the purposes of tracking imperative reproducibility of a given artifact or subset of an artifact. In the example below, the lula generate component command annotates how a given control-implementation - and associated component were generated.
props:
- name: generation
ns: https://docs.lula.dev/oscal/ns
value: lula generate component --catalog-source https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json --component 'Component Title' --requirements ac-1,ac-3,ac-3.2,ac-4 --remarks assessment-objective
The target prop is a prop used by Lula to automate identification of a result back to a given Control Implementation source or a collection of multiple sources when the framework prop is set.
This is used by Lula to allow for lula validate and lula evaluate operations to target a specific standard or collection of standards.
This prop can be identified when reviewing Assessment Results artifacts for each result[_].props as follows:
props:
- name: target
ns: https://docs.lula.dev/oscal/ns
value: https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/yaml/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.yaml
The Assessment Results OSCAL model supports the storage of many Result objects pertaining to the assessment of a component/system.
Each of these Results may establish a level of Compliance that indicates how compliant a component/system was at any point in time (typically during assessment). Lula leverages the Assessment Results model to store results of each validate operation while maintaining a threshold indicating when a component/system was most compliant.
This field is automatically maintained as Lula processes the identification of a threshold and updating it as required when a component/system becomes more compliant that a previous threshold.
After the initial validate operation - Lula will add a results[_].props entry to the result in the following format:
props:
- name: threshold
ns: https://docs.lula.dev/oscal/ns
value: "false"
As indicated in the evaluate section, it is expected that lula evaluate be executed with an Assessment Results artifact containing more than one comparable result. In the event a single result exists, Lula will automatically add a threshold property to the result and set the value to true.
The Assessment Results OSCAL model stores the observation list that relate to a specific finding (finding.related_observations). These findings are the control evaluations of the component/system, more detail can be found in Assessment Results. The observations are generated by Lula during the execution of a validate operation, which is underpinned by multiple executions of the Lula Validations.
To map these obserservations to the specific Lula Validation, the validation prop is used to identify the Lula Validation by unique identifier.
After the validate operation where observation are generated in the assessment-results - Lula will add a observation.props entry to the result in the following format:
props:
- name: validation
ns: https://docs.lula.dev/oscal/ns
value: "#8894c5cd-e27b-437e-a146-b6b4e9f2be78"
The value here is the Lula Validation’s UUID.
A Profile is an OSCAL model for capturing a baseline of selected controls from one or more catalogs or profiles. In lula, the profile model is available for generation and use as a source to other models that allow for specification of a profile or catalog which represents the source of truth for relevant security controls or other organizational policies.
The primary structure for the Lula production and operations of the profile model for determinism is as follows:
href in ascending ordertitle in ascending order (Case Sensitive Sorting).The lula generate commands are meant to be reproducible. The intent for this generation is to make it easy to update a given model with automation and only inject human intervention as needed.
For profiles, see the metadata props for the generation prop. It should look like the following:
props:
- name: generation
ns: https://docs.lula.dev/oscal/ns
value: lula generate profile --source catalog.yaml --include ac-1,ac-2,ac-3
[!NOTE] The controls specified for inclusion or exclusion during the generation command are not currently validated to exist in the source artifact.
lula generate profile -s catalog.yaml -i ac-1,ac-2,ac-3
A System Security Plan is an OSCAL-specific model to represent a system. In Lula, the generate system-security-plan command creates a representative system-security-plan object to describe the system as a whole. The only required input to the command is an OSCAL profile that defines the controls the system will implement. Optionally, one to many component-definitions can be provided to include the details of the components that make up the system and the respective implementation of the controls.
When defining the components for a particular system and profile combination, it’s important to note that the component-definitions will need to have a source field that equates to the profile source or any imported sources therein. Only components with implemented requirements that match the profile source (or imported sources) will be included in the system security plan.
The System Security Plan will detail each contributor and groups of contributors that play any part in the system’s lifecycle. It will also include every component that make up the system with each implemented-requirement that details the controls each tools helps to satisfy and how.
flowchart LR
P1[Child Profile]-->|imported by|P[Profile]
C[Catalog]-->|imported by|P
C1[Child Catalog]-->|imported by|P1
P-->|imported by|SSP[System Security Plan]
CD1[Component A]-->|sources|C1
CD2[Component B]-->|sources|C
CD1-->|defines|SSP
CD2-->|defines|SSP
Includes all responsible parties, parties, and roles that play a part in the system. Responsible parities are the collection of contributors who are responsible for the maintenance and development of the system. Parties includes any internal or external collection of contributors that contribute to the system or the lifecycle of the system. Roles are the designated positions contributors take within the system and system’s lifecycle.
Version is the specific revision of the document. Revision is a sequential list of revisions such as predecessor-version, successor-version, and version-history. These fields track the history of the document as changes are made.
Describes the system and the systems security requirements. This includes the security-sensitivity-level which is the overall system’s sensitivity categorization as defined by FIPS-199. The system’s overall level of expected impact resulting from unauthorized disclosure, modification, or loss of access to information through security-impact-level children items of security-objective-confidentiality, security-objective-integrity, and security-objective-availability.
The System Characteristics also outline the impacts to risk specifically based on confidentiality-impact, integrity-impact, and availability-impact with the supporting data.
The system characteristics also includes the authorization-boundary, network-architecture, and data-flow diagrams or links to the location of the diagrams. The authorization-boundary diagram outlines everything within the environment and is in scope for the system’s compliance framework. The network-architecture focuses on the network connections made within the system to include port and protocol. Lastly the data-flow diagram shows the flow of data within the system as it moves.
The system-information field contains all of the details about the type of data stored, processed, and transmitted by the system. The possible options are fips-199-low, fips-199-moderate, and fips-199-high. Consult NIST 800-60 for help defining the system.
Contains any leveraged-authorizations, if used, all components used to build the system, all users with their type and access levels listed, and inventory-items detailing how the overall system is configured. The inventory-items is a large collection of everything that lives within the system such as operating systems and infrastructure. In addition the responsible-parties are listed and connected to each piece they are responsible for.
Contains all of the compliance controls the system must adhere to as outlined within the profile. Each implemented-requirement is listed detailing the control and the information of how the system meets the control on a by-component instance. The component will outline all export, inherited, and satisfied indications for each control the component represents.
To generate a system security plan, you need the following context:
imports that include-all, include-controls.with-ids, and exclude-controls.with-ids. Support for matching and with-child-controls will be added in the future.source field that equates to the profile source or any imported sources therein.statement, assessment-objective, etc.)The following command generates a system security plan:
lula generate system-security-plan --profile profile.yaml --component oscal-component.yaml --remarks assessment-objective --output oscal-system-security-plan.yaml
In order to create a valid System Security Plan from information readily available, some fields are mocked and marked as TODO items. In other words, this command will not currently generate a fully ready to use System Security Plan without some additional work by the user. See System Security Plan Generate Context for more details.
[!NOTE] Additional work has been scoped to identify how to add additional context to the SSP that could be stored in a separate medium and injected upon generation.
The system-security-plan can be generated using the upstream profile in conjunction with the component-definition. There are net new fields that are apart of the system-security-plan that are not within the component-definition or catalog/profile that currently do not make sense to add as props. Those items are under the section Elements in SSP Not in Component Definition. There are items that are not in the system-security-plan but also not in the component-definition that currently do make sense to create as props. Those items are under the section Elements NOT in Component Definition that need added for SSP Generate. Lastly as a note there are items within the component-definition that are not used in the system-security-plan that can be found under the section Elements NOT in Component Definition that need added for SSP Generate.
For items that could not be derived from other sources, but were necessary to generating a valid SSP, the fields are marked as TODO in the output document and are marked below as Mocked. Note that the SystemImplementation.Components are only Mocked if no components have been provided which match the profile sources and controls (or have intersecting implemented requirements to profile controls).
The items in Elements in SSP Not in Component Definition need further context to fill in the missing elements as well as establish data across OSCAL models. Some examples of the data fields are within the metadata fields such as responsible-roles, responsible-parties, and parties that can be added to the system-security-plan that do not directly map from the component-definition field. Additional context can be added through common OSCAL fields such as props, links, and remarks.
The following fields need further research to further enhance generating an SSP.
inheritedexportimport-component-definitionscapabilitiesuuidnamedescriptionpropslinksincorporates-componentscomponent-uuiddescriptionsystem-characteristicssystem-idsidentifier-typeid - Mockedsystem-name - Mockedsystem-name-shortdescriptionsecurity-sensitivity-levelsystem-informationinformation-typesuuid - Mockedtitle - Mockeddescription - Mockedsecurity-objective-confidentialitysecurity-objective-integritysecurity-objective-availabilitysecurity-impact-levelsecurity-objective-confidentialitysecurity-objective-integritysecurity-objective-availabilitystatusstate - Mockedremarks - Mockedauthorized-boundarydescriptionpropslinksdiagramsuuiddescriptionpropslinkscaptionremarksremarksnetwork-architecturedescriptionpropslinksdiagramsuuiddescriptionpropslinkscaptionremarksremarksdata-flowdescriptionpropslinksdiagramsuuiddescriptionpropslinkscaptionremarksremarkspropslinksremarkssystem-implementationusersuuid - Mockedtitle - Mockedshort-namedescription - Mockedpropslinksrole-idsauthorized-privilegestitledescriptionfunctions-performedremarksleveraged-authorizationsuuidtitlepropslinksparty-uuiddate-authorizedremarksinventory-itemsuuiddescriptionpropslinksremarkscontrol-implementationimplemented-requirementsstatementssatisfieduuidresponsibilitydescriptionpropslinksresponsible-rolesrole-idpropslinksparty-uuidremarksrole-idsby-componentssatisfieduuidresponsibilitydescriptionpropslinksresponsible-rolesrole-idpropslinksparty-uuidremarksrole-idscontrol-implementationimplemented-requirementsby-componentsimplementation-statusstateremarksstatementsby-componentsimplementation-statusstateremarksmetadatatitlepublishedlast-modifiedversionoscal-versionrevisionsdocument-idspropslinksroleslocationsactionscontrol-implementationdescriptionset-parametersparam-idvaluesremarksimplemented-requirementsuuidcontrol-idpropslinksset-parametersparam-idvaluesremarksstatementsstatement-idpropsresponsible-roleslinksby-componentsby-componentscomponent-uuiddescriptionpropslinksset-parametersparam-idvaluesremarkssystem-implementation (Contains Fields from Component Definition)componentsuuid - Mockedtype - Mockedtitle - Mockeddescriptionpurposepropslinksstatus - Mockedprotocolsimplemented-componentscomponent-uuidpropslinksIn OSCAL - links contains the following fields:
links:
- href: https://www.example.com/
rel: reference
text: Example
media-type: text/html
resource-fragment: some-fragment
These links are a “reference to a local or remote resource, that has a specific relation to the containing object” - Component Definition Links.
As such, links are a native OSCAL attribute that Lula can use to map to Validations.
After identifying a control and writing a Lula Validation, we need to store that Lula Validation within the OSCAL artifact for referencing.
This is accomplished by adding a new resource to the back-matter as shown below:
back-matter:
resources:
- uuid: a7377430-2328-4dc4-a9e2-b3f31dc1dff9
description: >-
domain:
type: kubernetes
kubernetes-spec:
resources:
- name: podsvt
resource-rule:
group:
version: v1
resource: pods
namespaces: [validation-test]
provider:
type: opa
opa-spec:
rego: |
package validate
import future.keywords.every
validate {
every pod in input.podsvt {
podLabel := pod.metadata.labels.foo
podLabel == "bar"
}
}
Now we need to map an existing control (or Component-Definition Implemented-Requirement) to this Lula Validation.
The default workflow is to use the rel attribute to indicate that Lula has work to perform.
In the instance of a standard validation - A link to a Lula Validation might look like this:
links:
- href: '#a7377430-2328-4dc4-a9e2-b3f31dc1dff9'
rel: lula
Where href: '#a7377430-2328-4dc4-a9e2-b3f31dc1dff9' points to an OSCAL object with a UUID reference and rel: lula indicates that the link is to a Lula Validation.
UUID’s should always be unique per object in the OSCAL artifact.
[!TIP] You can generate a random UUID using
lula tools uuidgenor a deterministic UUID usinglula tools uuidgen <string>.
In addition to storing validaitons in the BackMatter, links may be used to fetch resources external to the component-definition.
file:file: must be a relative path to the component-definition or an absolute pathlinks:
- href: file:./validation.yaml
rel: lula
- href: file:/home/user/validations/validation.yaml
rel: lula
https: or http:https: or http: must be a valid URLlinks:
- href: https://example.com/validation.yaml
rel: lula
@<checksum>sha1, sha256, sha512, md5links:
- href: https://example.com/validation.yaml@0123456789abcdef
rel: lula
--- should be used to separate each validationresource-fragment: <UUID> will run the validation with the UUID specifiedresource-fragment: * will run all validations// Only runs the validation with the UUID of a7377430-2328-4dc4-a9e2-b3f31dc1dff9
links:
- href: https://example.com/multi-validations.yaml
rel: lula
resource-fragment: '#a7377430-2328-4dc4-a9e2-b3f31dc1dff9'
// All validations
- href: file:./multi-validations.yaml
rel: lula
resource-fragment: *
[!NOTE] An example
component-definitionwith remote validations can be found here.