Skip to content

Latest commit

 

History

History
257 lines (177 loc) · 7.84 KB

README.md

File metadata and controls

257 lines (177 loc) · 7.84 KB

ComplianceAsCode Builder

This project provides Docker-based tooling for working with the ComplianceAsCode/content project, enabling easy generation of SCAP content for various platforms.

Pre-built Containers

We provide ready-to-use container images on GitHub Container Registry:

# Pull the full version (with pre-built RHEL10 and Ubuntu 24.04)
docker pull ghcr.io/mitre/cac-builder:full

# Pull the minimal version (smaller size, build products on-demand)
docker pull ghcr.io/mitre/cac-builder:minimal

# Run the container
docker run -it --name compliance-as-code -v $(pwd)/output:/output ghcr.io/mitre/cac-builder:full bash

# Inside the container, the pre-built products are already available
ls /content/build/

Quick Start (Building Locally)

# Setup the environment
./setup.sh

# Build and start the container
docker-compose build
docker-compose up -d

# Connect to the container
docker exec -it compliance-as-code bash

# Build a specific product
build-product rhel10

For detailed setup instructions, see our documentation site.

Directory Structure

cac-builder/
├── certs/                    # Certificate directory
│   └── org/                  # Organization certificates
├── docs/                     # Documentation
│   ├── BUILD-TYPES.md        # Build type documentation
│   ├── CERTIFICATES.md       # Certificate documentation
│   └── workflow-options.md   # Workflow documentation
├── output/                   # Build output directory
├── scripts/                  # Setup and maintenance scripts
├── utils/                    # Container utility scripts
├── .github/workflows/        # CI/CD workflows
├── Dockerfile                # Full build Dockerfile
├── Dockerfile.optimized      # Minimal build Dockerfile
├── setup.sh                  # Setup script
└── docker-compose.yml        # Docker Compose configuration

For details on project structure, see PROJECT-STRUCTURE.md.

Build Types

The builder supports two different build configurations:

  1. Full Build

    • Pre-builds common products (RHEL10, Ubuntu 24.04)
    • Larger container size but faster access to common profiles
    • Best for regular use with standard platforms
    • Command: ./setup.sh --build-type full

  2. Minimal Build

    • Only prepares the build environment, no pre-built products
    • Smaller container size and faster build time
    • Products are built on-demand when you need them
    • Command: ./setup.sh --build-type minimal

For more details on build types, see docs/BUILD-TYPES.md.

Certificate Options

You can configure certificates for secure connections:

  1. Default Certificate

    • Automatically looked for in the project setup
    • Place certificate at ./certs/org/mitre-ca-bundle.pem

  2. Custom CA Certificate

    • Specify with --cert option
    • Example: ./setup.sh --cert /path/to/ca-bundle.pem

  3. Extra Organization Certificate

    • Additional certificate for special environments
    • Specify with --extra-cert option
    • Example: ./setup.sh --extra-cert /path/to/org-cert.pem

For more details on certificate options, see docs/CERTIFICATES.md.

SCAP Content Types

The ComplianceAsCode builder can generate various types of SCAP content:

  1. XCCDF (Extensible Configuration Checklist Description Format)

    • Primary compliance standard format
    • Contains benchmarks, rules, and profiles
    • Example: ssg-rhel10-xccdf.xml

  2. OVAL (Open Vulnerability and Assessment Language)

    • Technical checking mechanisms
    • Used by XCCDF for automated testing
    • Example: ssg-rhel10-oval.xml

  3. DataStreams

    • Collection format that bundles XCCDF, OVAL, and other content
    • Provides a single file for distribution
    • Example: ssg-rhel10-ds.xml

  4. Ansible Playbooks

    • Remediation scripts in Ansible format
    • Automatically fix non-compliant settings
    • Located in build/ansible

  5. Bash Scripts

    • Remediation scripts in Bash format
    • Fix non-compliant settings on Linux systems
    • Located in build/bash

For a complete list of generated content types, check the output/ directory after building a product.

Setup and Usage

Run the setup script to prepare the environment:

# Basic setup with defaults
./setup.sh

# Or with specific options
./setup.sh --build-type minimal --cert /path/to/ca-bundle.pem

You can also create a .env file for persistent configuration (see .env.example for available options).

For help with all available options:

./setup.sh --help

Build and Run Container

Build and start the Docker container:

docker-compose build
docker-compose up -d

Connect to the container:

docker exec -it compliance-as-code bash

Build a specific product:

# Inside the container
build-product rhel10  # or any other product

Find the generated files in the ./output/ directory on your host machine.

Workflow Options

This project supports different workflows depending on your needs:

  • Regular development and usage
  • CI/CD integration
  • Cross-platform compliance testing

For detailed workflow options, see docs/workflow-options.md.

CI/CD Capabilities

This project includes GitHub Actions workflows for:

  • Building and testing containers
  • Publishing images to GitHub Container Registry

For more details, see .github/workflows/README.md.

Updating Content

To update to the latest ComplianceAsCode content:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

For MITRE Team Members

When using this project within the MITRE network:

  1. Using Pre-built Containers:

    • The containers published to GitHub Container Registry are alreaady configured for MITRE.
    • You can pull and use them directly:
    docker pull ghcr.io/mitre/cac-builder:full

  2. Building Locally:

    • Clone the repository
    • Place your company CA bundle at ./certs/org/your-ca-bundle.pem if you are behind a corporate proxy or firewall.
    • Run ./setup.sh
    • Build with docker-compose build

For details on certificate management, see docs/CERTIFICATES.md.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details and review our Code of Conduct before participating.

Help Wanted / Future Improvements

We're looking for help with the following areas:

  • Additional product support beyond RHEL10 and Ubuntu 24.04
  • Performance improvements for build processes
  • Enhanced CI/CD integration examples
  • Additional documentation for advanced use cases
  • Multi-architecture container support
  • Creating downloadable build artifacts (zip/tar.gz of RHEL10 and Ubuntu 24.04 SCAP content) for the documentation site

If you're interested in working on these or other improvements, please check our open issues or create a new one to discuss your ideas.

Development

For developers looking to contribute or modify this project:

Notices

See NOTICE.md for attribution and copyright notices.

License

This project is licensed under the Apache-2.0 License - see LICENSE for details.