.github/workflows/scan-codeql.yaml

@@ -42,7 +42,7 @@ jobs:
         uses: ./.github/actions/golang
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@2d790406f505036ef40ecba973cc774a50395aac # v3.25.13
+        uses: github/codeql-action/init@afb54ba388a7dca6ecae48f608c4ff05ff4cc77a # v3.25.15
         with:
           languages: ${{ matrix.language }}
           # config-file: ./.github/codeql.yaml #Uncomment once config file is needed.
@@ -52,7 +52,7 @@ jobs:
 
       - name: Perform CodeQL Analysis
         id: scan
-        uses: github/codeql-action/analyze@2d790406f505036ef40ecba973cc774a50395aac # v3.25.13
+        uses: github/codeql-action/analyze@afb54ba388a7dca6ecae48f608c4ff05ff4cc77a # v3.25.15
         with:
           category: "/language:${{matrix.language}}"
 

.github/workflows/scorecard.yaml

@@ -46,6 +46,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@2d790406f505036ef40ecba973cc774a50395aac # v3.25.13
+        uses: github/codeql-action/upload-sarif@afb54ba388a7dca6ecae48f608c4ff05ff4cc77a # v3.25.15
         with:
           sarif_file: results.sarif

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "0.4.3"
+    ".": "0.4.4"
 }

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.4.4](https://github.com/defenseunicorns/lula/compare/v0.4.3...v0.4.4) (2024-07-26)
+
+
+### Features
+
+* **evaluate:** add observation summary ([#540](https://github.com/defenseunicorns/lula/issues/540)) ([8a07833](https://github.com/defenseunicorns/lula/commit/8a07833c5a563d8e857515a083137785cade5eb5))
+
+
+### Bug Fixes
+
+* **oscal:** deterministic OSCAL model write ([#553](https://github.com/defenseunicorns/lula/issues/553)) ([5493df1](https://github.com/defenseunicorns/lula/commit/5493df122b803d11542f29cfe80dfa4d5aaa10a8))
+
+
+### Miscellaneous
+
+* **deps:** update github/codeql-action action to v3.25.14 ([#557](https://github.com/defenseunicorns/lula/issues/557)) ([5bfd94f](https://github.com/defenseunicorns/lula/commit/5bfd94febc467e5a455ed32d97ce2e82e20409c2))
+* **deps:** update github/codeql-action action to v3.25.15 ([#564](https://github.com/defenseunicorns/lula/issues/564)) ([60e128a](https://github.com/defenseunicorns/lula/commit/60e128a0a34ce8686c67e22ea2aebb61212b97fc))
+* **deps:** update golang to version 1.22.5 ([#562](https://github.com/defenseunicorns/lula/issues/562)) ([97ff760](https://github.com/defenseunicorns/lula/commit/97ff7602f30f0709bd2ca16b74e53008607c3a61))
+* **deps:** update module github.com/open-policy-agent/opa to v0.67.0 ([#561](https://github.com/defenseunicorns/lula/issues/561)) ([4378242](https://github.com/defenseunicorns/lula/commit/43782420b8b34362d03bcc965e00df2a850715c6))
+* **docs:** fix simple demo command for evaluate file ([33fb97c](https://github.com/defenseunicorns/lula/commit/33fb97cccc9d4a589da65c03cc433b4f05c79d5d))
+* **docs:** updated broken links ([#554](https://github.com/defenseunicorns/lula/issues/554)) ([8dd24b0](https://github.com/defenseunicorns/lula/commit/8dd24b083c86b12af8740fe788c4222f4c1c8718))
+* **docs:** updated README for docs badge ([#558](https://github.com/defenseunicorns/lula/issues/558)) ([72fd3fc](https://github.com/defenseunicorns/lula/commit/72fd3fc8137477a4f10507481f8464eb5685b781))
+
 ## [0.4.3](https://github.com/defenseunicorns/lula/compare/v0.4.2...v0.4.3) (2024-07-19)
 
 

README.md

@@ -1,9 +1,10 @@
 # Lula - The Cloud-Native Compliance Engine
 
+[![Lula Documentation](https://img.shields.io/badge/docs--d25ba1)](https://docs.lula.dev)
 [![Go version](https://img.shields.io/github/go-mod/go-version/defenseunicorns/lula?filename=go.mod)](https://go.dev/)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/lula/badge)](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/lula)
 
-<img align="right" alt="lula logo" src="lula.svg" height="256" />
+<img align="right" src="./images/lula.svg" alt="lula logo" style="width:25%; height:auto;">
 
 Lula is a tool designed to bridge the gap between expected configuration required for compliance and **_actual_** configuration.
 
@@ -24,7 +25,7 @@ Cloud-Native Infrastructure, Platforms, and Applications can establish [OSCAL do
 
 These controls can be well established and regulated standards such as NIST 800-53. They can also be best practices, Enterprise Standards, or simply team development standards that need to be continuously monitored and validated.
 
-Lula operates on a framework of proof by adding custom overlays mapped to the these controls, [`Lula Validations`](link), to measure system compliance. These `Validations` are constructed by establishing the collection of measurements about a system, given by the specified **Domain**, and the evaluation of adherence, performed by the **Provider**. 
+Lula operates on a framework of proof by adding custom overlays mapped to the these controls, [`Lula Validations`](./docs/reference/README.md), to measure system compliance. These `Validations` are constructed by establishing the collection of measurements about a system, given by the specified **Domain**, and the evaluation of adherence, performed by the **Provider**. 
 
 ### Providers and Domains
 
@@ -40,8 +41,8 @@ Lula operates on a framework of proof by adding custom overlays mapped to the th
 
 | Provider | Current | Roadmap |
 |----------|----------|----------|
-| [OPA](./docs/reference/provideres/opa-provider.md) | ✅ | - |
-| [Kyverno](./docs/reference/provideres/kyverno-provider.md) | ✅ | - |
+| [OPA](./docs/reference/providers/opa-provider.md) | ✅ | - |
+| [Kyverno](./docs/reference/providers/kyverno-provider.md) | ✅ | - |
 
 ## Getting Started
 

cspell.json

@@ -0,0 +1,11 @@
+{
+    "version": "0.2",
+    "ignorePaths": [],
+    "dictionaryDefinitions": [],
+    "dictionaries": [],
+    "words": [
+        "OSCAL"
+    ],
+    "ignoreWords": [],
+    "import": []
+}

docs/cli-commands/assessments/evaluate.md

@@ -2,6 +2,28 @@
 
 Evaluate serves as a method for verifying the compliance of a component/system against an established threshold to determine if it is more or less compliant than a previous assessment. 
 
+## Usage
+
+To evaluate two results (threshold and latest) in a single OSCAL file:
+```bash
+lula evaluate -f assessment-results.yaml
+```
+
+To evaluate the latest results in two assessment results files:
+```bash
+lula evaluate -f assessment-results-threshold.yaml -f assessment-results-new.yaml
+```
+
+To print a summary of the observation results:
+```bash
+lula evaluate -f assessment-results.yaml --summary
+```
+
+## Options
+
+- `-f, --file`: The path to the file(s) to be evaluated.
+- `-s, --summary`: [Optional] Prints a summary of the evaluation.
+
 ## Expected Process
 
 ### No Existing Data

docs/cli-commands/assessments/validate.md

@@ -19,4 +19,4 @@ lula validate -f /path/to/oscal-component.yaml
 
 This command is used both locally as an evaluation of the Component Definition to understand the component's compliance. It's also implemented in CI workflows to continually evaluate the evolution of a system during development. See the following relevant tutorials:
 
-- ...
+* [Simple Demo](../../getting-started/simple-demo.md)

docs/cli-commands/tools/lint.md

@@ -2,7 +2,7 @@
 
 The `lula tools lint` command is used to validate OSCAL files against the OSCAL schema. It can validate both composed and non-composed OSCAL models.
 > **Note**: the `lint` command does not compose the OSCAL model.
-> If you want to validate a composed OSCAL model, you should use the [`lula tools compose`](../compose/README.md) command first.
+> If you want to validate a composed OSCAL model, you should use the [`lula tools compose`](./compose/README.md) command first.
 
 ## Usage
 

docs/getting-started/develop-a-validation.md

@@ -1,6 +1,6 @@
 # Develop a Validation
 
-This document describes some best practices for developing and using a [Lula Validation](), the primary mechanism for evaluation of system's compliance against a specified control.
+This document describes some best practices for developing and using a [Lula Validation](../reference/README.md), the primary mechanism for evaluation of system's compliance against a specified control.
 
 ## About
 

docs/getting-started/simple-demo.md

@@ -177,7 +177,7 @@ The following simple demo will step through a process to validate and evaluate K
 
 7. Now that two assessment-results are established, the `threshold` can be evaluated. Perform an `evaluate` to compare the old and new state of the cluster:
     ```shell
-    lula evaluate -f oscal-component-opa.yaml
+    lula evaluate -f assessment-results.yaml
     ```
 
     The output will show that now the new threshold for the system assessment is the more _compliant_ evaluation of the control - i.e., the `satisfied` value of the Control ID-1 is the threshold.

docs/oscal/assessment-results.md

@@ -1,12 +1,12 @@
 # Assessment Results
 
-An [Assessment Result](https://pages.nist.gov/OSCAL/resources/concepts/layer/assessment/assessment-results/) is an OSCAL-specific model to report on the specific assessment outcomes of a system. In Lula, the `validate` function creates an `assessment-result` object to enumerate the asseement of the input controls provided by the `component-definition`. These are reported as finding that are `satisfied` or `not-satisfied` as a result of the observations performed by the Lula validations.
+An [Assessment Result](https://pages.nist.gov/OSCAL/resources/concepts/layer/assessment/assessment-results/) 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.
 ```mermaid
 flowchart TD
     A[Assessment Results]-->|compose|C[Finding 1]
     A[Assessment Results]-->|compose|G[Finding 2]
-    B(Control)-->|satsified by|C
-    B(Control)-->|satsified by|G
+    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]
@@ -19,13 +19,20 @@ flowchart TD
 ```
 
 ## Observation Results
-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-satisifed` then the associated finding is marked as `not-satisfied`.
+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-satisified` 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](#not-satisfied-conditions) then it will by default return a `not-satisfied` result.
+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](#not-satisfied-conditions) then it will by default return a `not-satisfied` result.
 
 ### Not-satisfied conditions
-The following conditions enumerate when the Lula Validation will result in a `not-satified` evaluation. These cases exclude the case where the Lula validation policy has been evaluated and returned a failure.
+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.
 - Malformed Lula validation -> bad validation structure
 - Missing resources -> No resources are found as input to the policy
 - Missing reference -> If a remote or local reference is invalid
-- Executable validations disallowed -> If a validation is executable but has not been allowed to run
+- Executable validations disallowed -> If a validation is executable but has not been allowed to run
+
+## Structure
+The primary structure for Lula production and operation of `assessment-results` for determinism is as follows:
+- Results are sorted by `start` time in descending order
+- Findings are sorted by `target.target-id` in ascending order
+- Observations are sorted by `collected` time in ascending order
+- Back Matter Resources are sorted by `title` in ascending order.

docs/oscal/component-definition.md

@@ -0,0 +1,16 @@
+# Component Definition
+
+A [Component Definition](https://pages.nist.gov/OSCAL/resources/concepts/layer/implementation/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`. 
+
+## Components/Capabilities and Control-Implementations
+
+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. 
+
+## Structure
+The primary structure for Lula production and operations of `component-definitions` for determinism is as follows:
+- Components/Capabilities are sorted by `title` in ascending order (Case Sensitive Sorting).
+- Control Implementations are sorted by `source` in ascending order.
+- Implemented Requirements are sorted by `control-id` in ascending order.
+- Back Matter Resources are sorted by `title` in ascending order (Case Sensitive Sorting).

docs/reference/README.md

@@ -70,7 +70,7 @@ Linting is done by Lula when a `Validation` object is converted to a `LulaValida
 The `common.Validation.Lint` method is a convenience method to lint a `Validation` object. It performs the following step:
 
 1. **Marshalling**: The method marshals the `Validation` object into a YAML byte array using the `common.Validation.MarshalYaml` function.
-2. **Linting**: The method runs linting against the marshalled `Validation` object. This is done using the `schemas.Validate` function, which ensures that the YAML data conforms to the expected [schema](../../src/pkg/common/schemas/validation.json).
+2. **Linting**: The method runs linting against the marshalled `Validation` object. This is done using the `schemas.Validate` function, which ensures that the YAML data conforms to the expected [schema](https://raw.githubusercontent.com/defenseunicorns/lula/main/src/pkg/common/schemas/validation.json).
 
 ___
 The `schemas.Validate` function is responsible for validating the provided data against a specified JSON schema using [github.com/santhosh-tekuri/jsonschema/v5](https://github.com/santhosh-tekuri/jsonschema). The process involves the following steps:

go.mod

@@ -1,12 +1,12 @@
 module github.com/defenseunicorns/lula
 
-go 1.22.3
+go 1.22.5
 
 require (
 	github.com/defenseunicorns/go-oscal v0.5.0
 	github.com/hashicorp/go-version v1.7.0
 	github.com/kyverno/kyverno-json v0.0.3
-	github.com/open-policy-agent/opa v0.66.0
+	github.com/open-policy-agent/opa v0.67.0
 	github.com/pterm/pterm v0.12.79
 	github.com/santhosh-tekuri/jsonschema/v5 v5.3.1
 	github.com/sergi/go-diff v1.3.1
@@ -33,7 +33,7 @@ require (
 	github.com/aquilax/truncate v1.0.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/blang/semver/v4 v4.0.0 // indirect
-	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/chai2010/gettext-go v1.0.2 // indirect
 	github.com/containerd/console v1.0.3 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
@@ -111,22 +111,22 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yashtewari/glob-intersection v0.2.0 // indirect
 	github.com/zach-klippenstein/goregen v0.0.0-20160303162051-795b5e3961ea // indirect
-	go.opentelemetry.io/otel v1.23.1 // indirect
-	go.opentelemetry.io/otel/metric v1.23.1 // indirect
-	go.opentelemetry.io/otel/sdk v1.23.1 // indirect
-	go.opentelemetry.io/otel/trace v1.23.1 // indirect
+	go.opentelemetry.io/otel v1.28.0 // indirect
+	go.opentelemetry.io/otel/metric v1.28.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.28.0 // indirect
+	go.opentelemetry.io/otel/trace v1.28.0 // indirect
 	go.starlark.net v0.0.0-20240123142251-f86470692795 // indirect
-	golang.org/x/crypto v0.24.0 // indirect
+	golang.org/x/crypto v0.25.0 // indirect
 	golang.org/x/exp v0.0.0-20240222234643-814bf88cf225 // indirect
-	golang.org/x/net v0.26.0 // indirect
+	golang.org/x/net v0.27.0 // indirect
 	golang.org/x/oauth2 v0.17.0 // indirect
 	golang.org/x/sync v0.7.0 // indirect
-	golang.org/x/sys v0.21.0 // indirect
-	golang.org/x/term v0.21.0 // indirect
+	golang.org/x/sys v0.22.0 // indirect
+	golang.org/x/term v0.22.0 // indirect
 	golang.org/x/text v0.16.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
 	google.golang.org/appengine v1.6.8 // indirect
-	google.golang.org/protobuf v1.34.1 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/evanphx/json-patch.v5 v5.9.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect