Lula - GitOps for Compliance

Important

This project is still in its early stages. Expect breaking changes.

Looking for the original Lula OSCAL compliance validator? Go to defenseunicorns-labs/lula1

Lula 1 is in maintenance mode and not receiving active updates or new features.

Bring GitOps principles to compliance management. Lula treats security controls as code, enabling teams to manage compliance frameworks (NIST 800-53, CIS, SOC2) through pull requests, code reviews, and automated workflows — just like your application code in a user-friendly web interface. Your data stays your data--Lula takes spreadsheet imports, lets you drag & drop the UI layout and version control the data as yaml automatically for you.

Quickstart

Run Lula directly with npx (no installation required):

npx lula2

Import an eMASS Spreadsheet

The first step is to import an eMASS spreadsheet into Lula. A sample file is provided at: samples/fake-controls.xlsx

Continue with Lula Workflow

Once the spreadsheet is imported, you can proceed with the standard Lula workflow creating mappings to controls.

Why GitOps for Compliance?

• Version Everything: Every control change, ui change, mapping is tracked, reviewable, and revertable
• Pull Request Workflows: Review compliance changes before they go live
• Branch Strategies: Test control changes in isolated branches
• Automated Validation: CI/CD pipelines can validate control completeness
• Audit Trail: Git history provides immutable audit logs
• Collaborative Review: Security, compliance, and engineering teams collaborate through PRs
• Automated Change Detection: Map controls to source code via generated UUIDs and track when code changes impact your compliance posture

Key Features

• Controls as Code: Each control stored as an individual YAML file
• Import/Export: Import any generic spreadsheet with column headers, including from tools like EMASS
• Smart Formatting: Automatic text processing for control descriptions and procedures
• Source Mappings: Link controls to actual code implementations
• Multi-Framework: Support NIST, CIS, SOC2, and custom frameworks in one repo
• Git Timeline: Visual history of all control changes

Interface Features

Once launched, you can:

• Browse Controls: Navigate through control families and individual controls
• Edit Controls: Update implementation narratives, status, and properties
• Track Changes: View Git history and timeline for each control
• Manage Mappings: Link controls to source code and documentation
• Import Data: Use the setup page to import OSCAL catalogs or existing control sets
• Export Reports: Generate compliance reports and assessments

Learning from Lula 1

We built Lula 2 after discovering key limitations with the OSCAL-based approach:

Challenges in Lula 1:

• OSCAL proved too complex for most teams to work with effectively
• Automated tests alone were insufficient for real compliance verification
• The format made collaboration and review difficult

Lula 2's Approach:

• Simple YAML + Spreadsheets: Import from any spreadsheet tool (including EMASS), no OSCAL knowledge required
• Human + AI Analysis: Recognizes that compliance requires human judgment augmented by AI reasoning, not just automated tests
• Git-native: Use standard diff tools and pull requests for review
• Web UI: Intuitive interface that anyone can use, not just CLI experts
• Change Impact Tracking: Maps controls to actual code and tracks when changes might affect compliance

This evolution reflects our learning that effective compliance management needs to be accessible to all stakeholders—not just those who can navigate complex standards or write validation code.

Commands

UI Command

By default, the web interface is launched as the root command, but if you need to provide configuration flags:

> npx lula2 ui

Crawl Command

Analyze pull requests for compliance impact:

> OWNER=defenseunicorns REPO=lula  PULL_NUMBER=126 GITHUB_TOKEN=$(gh auth token) npx lula2 crawl --post-mode=comment                   
Analyzing PR #126 in defenseunicorns/lula for compliance changes...
Commenting regarding `integration/test-files/ex.ts`.
Commenting regarding `integration/test-files/ex.yaml`.

Posted (comment)
----------------

<!-- LULA_SIGNATURE:v1 -->
## Lula Compliance Overview

Please review the changes to ensure they meet compliance standards.

### Reviewed Changes

Lula reviewed 2 files changed that affect compliance.



---
| File | Lines Changed |
| ---- | ------------- |
| `integration/test-files/ex.ts` | `20–31` |
| `integration/test-files/ex.ts` | `39–47` |

**UUID:** `123e4567-e89b-12d3-a456-426614174000`
**sha256:** `f889702fd3330d939fadb5f37087948e42a840d229646523989778e2b1586926`

**UUID:** `987e4567-e89b-12d3-a456-426614174777`
**sha256:** `72acd6ffeab63567b4fc38ffb1997d106d30c0cec4474d8046810dcbcbb1302b`



---
| File | Lines Changed |
| ---- | ------------- |
| `integration/test-files/ex.yaml` | `1–5` |
| `integration/test-files/ex.yaml` | `8–14` |

**UUID:** `123e4567-e89b-12d3-a456-426614174001`
**sha256:** `f6b6f51335248062b003696623bfe21cea977ca7f4e4163b182b0036fa699eb4`

**UUID:** `987e4567-e89b-12d3-a456-426614174777`
**sha256:** `ab0240ce74fa7aec548e671a24c5cdede388970a95eb1198b6eb7cb1c8635cef`



---

<sub>**Tip:** Customize your compliance reviews with <a href="https://github.com/defenseunicorns/lula.git" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Lula</a>.</sub>

Here is a workflow example for GitHub Actions:

# This workflow runs a Lula scan against the PR to see if compliance has changed

name: Lula Scan
on:
  pull_request:
    branches: ["main"]
    types: [opened, reopened, synchronize]
permissions:
  contents: read
  pull-requests: write

jobs:
  scan-pr:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493
      - name: Use Node.js 22
        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
        with:
          node-version: 22

      - name: Run Lula Scan
        run: |
          npx --yes lula2 crawl
        shell: bash
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Version Command

> npx lula2 --version

Project Structure

Lula organizes controls in a Git-friendly structure:

my-compliance-project/
├── lula.yaml                    # Control set metadata
├── controls/                    # Individual control files
│   ├── AC/                      # Access Control family
│   │   ├── AC-1.yaml
│   │   ├── AC-2.yaml
│   │   └── AC-2_1.yaml         # Control enhancements
│   ├── AU/                      # Audit family
│   │   └── ...
│   └── ...
└── mappings/                    # Source code mappings
    ├── AC/
    │   └── AC-1-mappings.yaml
    └── ...

Control File Format

Each control is stored as a YAML file with a consistent schema based on the imported spreadsheet:

id: AC-1
title: Access Control Policy and Procedures
family: AC
description: |
  The organization develops, documents, and disseminates...
implementation_status: Implemented
security_control_designation: Hybrid
control_implementation_narrative: |
  Our organization implements AC-1 through...
implementation_guidance: |
  Step-by-step guidance for implementing this control...
assessment_procedures: |
  Methods for assessing control effectiveness...
test_results: |
  Results from the latest assessment...
properties:
  priority: P1
  responsible_role: CISO
  last_reviewed: 2024-01-15

Features in Detail

GitOps Workflow

Manage compliance like code with GitOps practices:

# Create feature branch for control updates
git checkout -b update-ac-controls

# Make changes through Lula UI
npx lula2

# Commit changes
git add controls/
git commit -m "Updated AC family implementation narratives"

# Push and create PR
git push origin update-ac-controls
# → Team reviews changes in PR
# → CI validates control completeness
# → Merge when approved

Smart Text Processing

Lula automatically formats complex text fields:

• Detects and styles headers (Description:, Guidance:, etc.)
• Converts CSV data into formatted tables
• Properly formats lists and bullet points
• Highlights control IDs and CCI references

Control Mappings

Link controls to actual implementations using a UUID:

- control_id: AC-10_3
  justification: 'This is my reason this is compliant'
  status: implemented
  source_entries: [source: src/auth/policies.ts]
  uuid: 439489d2-c1db-4ab4-a4dd-d0a6f4a0dd24
  last_validated: 2024-01-15

GitOps Benefits for Compliance

For Compliance Teams

• Review Process: Control changes go through pull request reviews
• Rollback: Instantly revert problematic control updates
• Branching: Test control changes without affecting production
• History: Complete audit trail in Git log
• Protection: Leverage CODEOWNERS to limit who can edit controls/mappings or change the UI
• Monitoring: Leverage SCM tools to track key changes/issues

For Security Engineers

• Infrastructure as Code: Compliance configurations alongside IaC
• Automation: Trigger compliance checks on control changes
• Integration: Controls in the same repo as security policies
• Validation: Pre-commit hooks for control completeness

For Auditors

• Immutable History: Git provides tamper-evident audit logs when combined with SCM tooling
• Change Attribution: Every change linked to a person and reason
• Point-in-Time: View controls as they were at any date
• Evidence Chain: PRs document review and approval process

Configuration

lula.yaml

Managed by the UI for you, each control set includes a configuration file:

name: NIST 800-53 Rev 4 Moderate
version: 4.0.0
description: NIST Special Publication 800-53 Security Controls
source: https://csrc.nist.gov/publications/detail/sp/800-53/rev-4/final
families:
  - id: AC
    name: Access Control
  - id: AU
    name: Audit and Accountability
  # ... more families

Troubleshooting

Common Issues

No control sets found:

• Ensure you have a lula.yaml file in your control set directory
• Check that control files are in the correct structure

WebSocket connection failed:

• Verify the port is not in use
• Check firewall settings
• Ensure both frontend and backend are running

Git history not showing:

• Verify the directory is a Git repository
• Ensure Git is installed and accessible
• Check file permissions

Development

Prerequisites

• Node.js 22.20.x or >= 24.x
• Git (for version history features)
• pnpm (recommended) or npm

Local Development

# Clone the repository
git clone https://github.com/defenseunicorns/lula.git
cd lula

# Install dependencies
pnpm install

# Run development servers
pnpm run dev:full  # Runs both frontend and backend

Build

pnpm run build

Architecture

• Frontend: SvelteKit 5 with Tailwind CSS
• Backend: Express + WebSocket server
• Storage: YAML files with Git integration
• State Management: Svelte 5 runes
• CLI: Commander.js with TypeScript

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Apache-2.0 - See LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Related Projects

• Lula 1 (Original CLI) - OSCAL-based compliance validator CLI
• OSCAL - Open Security Controls Assessment Language

Credits

Developed by The Lula Authors

Part of the Defense Unicorns ecosystem for secure, compliant software delivery.