Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(docs): initial docs structure/changes for feedback #524

Merged
merged 5 commits into from
Jul 16, 2024
Merged

chore(docs): initial docs structure/changes for feedback #524

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cad58a4
initial docs structure/changes for feedback
meganwolf0 Jul 8, 2024
74632c3
chore(docs): updated demos, docs organization
meganwolf0 Jul 11, 2024
201c036
Merge branch 'main' into 521_doc-clean-up
CloudBeard Jul 12, 2024
56ec6ca
Merge branch 'main' into 521_doc-clean-up
CloudBeard Jul 12, 2024
712386e
Merge branch 'main' into 521_doc-clean-up
meganwolf0 Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 32 additions & 160 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,176 +1,48 @@
# Lula - The Kubernetes Compliance Engine
# Lula - The Cloud-Native Compliance Engine

[![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)

Lula is a tool written to bridge the gap between expected configuration required for compliance and **_actual_** configuration.
<img align="right" alt="lula logo" src="lula.svg" height="256" />

Cloud Native Infrastructure, Platforms, and applications can establish OSCAL documents that live beside source-of-truth code bases. Providing an inheritance model for when a control that the technology can satisfy _IS_ satisfied in a live-environment.
Lula is a tool designed to bridge the gap between expected configuration required for compliance and **_actual_** configuration.

This can be well established and regulated standards such as NIST 800-53. It can also be best practices, Enterprise Standards, or simply team development standards that need to be continuously monitored and validated.
### Key Features
* **Assess** compliance of a system against user-defined controls
* **Evaluate** an evolving system for compliance _over time_
* **Generate** machine-readible OSCAL artifacts
* **Accelerate** the compliance and accreditation process

## Why this approach vs a policy engine?
### Why Lula is different than a standard policy engine
* Lula is not meant to compete with policy engines - rather augment the auditing and alerting process
* Often admission control processes have a difficult time establishing `big picture` global context control satisfaction, Lula fills this gap
* Lula is meant to allow modularity and inheritance of controls based upon the components of the system you build

- Lula is not meant to compete with policy engines - rather augment the auditing and alerting process
- Often admission control processes have a difficult time establishing `big picture` global context control satisfaction
- Lula is meant to allow modularity and inheritance of controls based upon the components of the system you build
## Overview

## How does it work?
Cloud-Native Infrastructure, Platforms, and Applications can establish [OSCAL documents](https://pages.nist.gov/OSCAL/about/) that are maintained alongside source-of-truth code bases. These documents provide an inheritance model to prove when a control that the technology can satisfy _IS_ satisfied in a live-environment.

Under the hood, Lula has two primary capabilities; Provider and Domains.
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.

- A Domain is an identifier for where to collect data to be validated
- A Provider is the "engine" performing the validation using policy and the data collected.
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**.

In the standard CLI workflow:
### Providers and Domains

- Target a `Component-Definition` OSCAL file for validation
- `lula validate oscal-component.yaml`
- This creates an object in memory for the OSCAL content
- Lula then traverses as required to identify `implemented-requirements` that contain a Lula Validation Payload
- When the payload has been identified:
- Lula processes provider to understand which provider to use for validation
- More than one provider can be used in an OSCAL document
- Lula processes the domain to understand how data is collected (and which data to collect)
- Lula collects the data for validation as specified in the payload
- Lula performs validation of the data collected as specified as policy in the payload
**Domain** is the identifier for where and which data to collect as "evidence". Below are the active and planned domains:

| Domain | Current | Roadmap |
|----------|----------|----------|
| [Kubernetes](./docs/reference/domains/kubernetes-domain.md) | ✅ | - |
| [API](./docs/reference/domains/api-domain.md) | ✅ | - |
| Cloud Infrastructure | ❌ | ✅ |

**Provider** is the "engine" performing the validation using policy and the data collected. Below are the active providers:

| Provider | Current | Roadmap |
|----------|----------|----------|
| [OPA](./docs/reference/provideres/opa-provider.md) | ✅ | - |
| [Kyverno](./docs/reference/provideres/kyverno-provider.md) | ✅ | - |

## Getting Started

### Try it out

#### Dependencies

- A running Kubernetes cluster
- Kind
- `kind create cluster -n lula-test`
- K3d
- `k3d cluster create lula-test`
- kubectl
- GoLang version 1.22.x

#### Steps

1. Clone the repository to your local machine and change into the `lula` directory

```shell
git clone https://github.com/defenseunicorns/lula.git && cd lula
```

2. While in the `lula` directory, compile the tool into an executable binary. This outputs the `lula` binary to the `bin` directory.

```shell
make build
```

3. Apply the `./demo/namespace.yaml` file to create a namespace for the demo

```shell
kubectl apply -f ./demo/namespace.yaml
```

4. Apply the `./demo/pod.fail.yaml` to create a pod in your cluster

```shell
kubectl apply -f ./demo/pod.fail.yaml
```

5. Run the following command in the `lula` directory:

```shell
./bin/lula validate -f ./demo/oscal-component.yaml
```

The output in your terminal should inform you that the control validated is `not-satisfied`:

```shell
NOTE Saving log file to
/var/folders/f7/8csz3jj97lb8nqp_zv9kh07m0000gn/T/lula-2024-01-24-13-51-58-2247835644.log
• UUID: c759a19b-d408-424c-8342-298f45e18b68
• Status: not-satisfied
✔ Validating Implemented Requirement - 42C2FFDC-5F05-44DF-A67F-EEC8660AEFFD
• Writing Security Assessment Results to: assessment-results-01-24-2024-13:51:58.yaml
```

This will also produce an assessment-results file with timestamp - review the findings and observations:

```yaml
findings:
- description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
related-observations:
- observation-uuid: ef12a3bb-fd86-4336-9d28-98d00c7dc26d
target:
status:
state: not-satisfied
target-id: ID-1
type: objective-id
title: 'Validation Result - Component:A9D5204C-7E5B-4C43-BD49-34DF759B9F04 / Control Implementation: A584FEDC-8CEA-4B0C-9F07-85C2C4AE751A / Control: ID-1'
uuid: c759a19b-d408-424c-8342-298f45e18b68
observations:
- collected: "2024-01-24T13:51:58-08:00"
description: |
[TEST] ID-1 - a7377430-2328-4dc4-a9e2-b3f31dc1dff9
methods:
- TEST
relevant-evidence:
- description: |
Result: not-satisfied - Passing Resources: 0 - Failing Resources 1
uuid: ef12a3bb-fd86-4336-9d28-98d00c7dc26d
```

6. Now, apply the `./demo/pod.pass.yaml` file to your cluster to configure the pod to pass compliance validation:

```shell
kubectl apply -f ./demo/pod.pass.yaml
```

7. Run the following command in the `lula` directory:

```shell
./bin/lula validate -f ./demo/oscal-component.yaml
```

The output should now show the pod as passing the compliance requirement:

```shell
NOTE Saving log file to
/var/folders/f7/8csz3jj97lb8nqp_zv9kh07m0000gn/T/lula-2024-01-24-13-54-19-2423960428.log
• UUID: c3e4ccb2-6843-4ec2-a500-559cdd7918d5
• Status: satisfied
✔ Validating Implemented Requirement - 42C2FFDC-5F05-44DF-A67F-EEC8660AEFFD
• Writing Security Assessment Results to: assessment-results-01-24-2024-13:54:19.yaml
```

This will produce a new assessment-results file with timestamp - review the findings and observations:

```yaml
findings:
- description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
related-observations:
- observation-uuid: 84a169a1-74d6-4e26-bbfb-4dfc474c7790
target:
status:
state: satisfied
target-id: ID-1
type: objective-id
title: 'Validation Result - Component:A9D5204C-7E5B-4C43-BD49-34DF759B9F04 / Control Implementation: A584FEDC-8CEA-4B0C-9F07-85C2C4AE751A / Control: ID-1'
uuid: c3e4ccb2-6843-4ec2-a500-559cdd7918d5
observations:
- collected: "2024-01-24T13:54:19-08:00"
description: |
[TEST] ID-1 - a7377430-2328-4dc4-a9e2-b3f31dc1dff9
methods:
- TEST
relevant-evidence:
- description: |
Result: satisfied - Passing Resources: 1 - Failing Resources 0
uuid: 84a169a1-74d6-4e26-bbfb-4dfc474c7790
```

## Future Extensibility

- Support for cloud infrastructure state queries

## Developing

- Go 1.22.x
[Install Lula](./docs/getting-started/README.md) and check out the [Simple Demo](./docs/getting-started/simple-demo.md) to get familiar with Lula's `validate` and `evaluate` workflow to assess system compliance and establish thresholds. See the other tutorials for more advanced Lula use cases and information on how to develop your own `Lula Validations`!
29 changes: 29 additions & 0 deletions demo/develop-validation/oscal-component.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
component-definition:
uuid: a506014d-cb8a-4db9-ac48-ef72f7209a60
metadata:
last-modified: 2024-07-11T13:38:09.633174-04:00
oscal-version: 1.1.2
published: 2024-07-11T13:38:09.633174-04:00
remarks: Lula Generated Component Definition
title: Component Title
version: 0.0.1
components:
- uuid: 75859c1e-30f5-4fde-9ad4-c79f863b049f
type: software
title: podinfo
description: Sample application
control-implementations:
- uuid: a3039927-839c-5745-ac4e-a9993bcd60ed
source: https://github.com/defenseunicorns/lula
description: Control Implementation Description
implemented-requirements:
- uuid: 257d2b2a-fda7-49c5-9a2b-acdc995bc8e5
control-id: ID-1
description: >-
Podinfo, a sample application, is deployed into the cluster and exposed for testing purposes.
remarks: >-
System implements test application as target for development purposes.
links:
- href: 'file:./validation.yaml'
rel: lula
text: Check that Podinfo is healthy
Loading