ComplianceAsCode Content Documentation

The ssg package provides a suite of modules for building, parsing, and managing security content and compliance data. Key functional areas include:

• Content Building: Modules like ssg.build_ovals, ssg.build_profile, ssg.build_remediations, ssg.build_stig, ssg.build_cpe, and ssg.build_yaml are used to generate specific security content formats.
• Parsing and Data Handling: Modules such as ssg.parse_oval, ssg.xml, ssg.yaml, and ssg.boolean_expression handle the ingestion and processing of structured data.
• Automation and Integration: ssg.ansible and ssg.playbook_builder facilitate the creation of automation playbooks.
• Core Logic: Modules like ssg.rules, ssg.profiles, ssg.checks, and ssg.controls manage the underlying compliance logic and definitions.

The tests package contains various modules used for validating security content, Ansible playbooks, OVAL definitions, and SCAP compliance results. Key functional areas include:

• Ansible Validation: tests.ansible_playbooks_generated_for_all_rules, tests.assert_ansible_schema.
• Compliance & SCAP Testing: tests.analyze_results, tests.oval_tester, tests.run_scapval.
• Content Integrity: tests.ensure_paths_are_short, tests.missing_cces, tests.stable_profile_ids, tests.test_profile_stability.
• Environment & Rule Testing: tests.install_vm, tests.test_machine_only_rules, tests.test_macros_oval.

ComplianceAsCode generates security policy content in several formats to meet different automation and implementation needs:

• SCAP content: Documents in XCCDF, OVAL, and SCAP source data stream formats. SCAP source data streams are recommended for general use as they contain all data needed to evaluate and achieve compliance.
• Ansible content: Playbooks generated from security profiles. These can be used in check-mode for evaluation or run-mode to remediate (put machines into compliance).
• Bash fix files: Bash scripts generated from security profiles intended to be run on machines to achieve compliance.
• CEL content: Common Expression Language (CEL) YAML files for Kubernetes and OpenShift. Designed for native Kubernetes resource evaluation via the compliance-operator without requiring shell access to nodes.

The ComplianceAsCode build system transforms format-agnostic content into standardized artifacts (XCCDF, OVAL, OCIL, and SCAP source data streams) used by security auditing tools. The system relies on:

• CMake: Drives the build process and manages product-specific targets.
• Python Utilities: Located in /build-scripts, these transform input files and apply Jinja macros.
• XML Tools: Uses xmllint and xsltproc for extensive XSLT processing.
• OpenSCAP: Uses the oscap CLI to combine and reference files into finished artifacts.

ComplianceAsCode supports three types of check content. Choose based on your target:

• OVAL (Open Vulnerability and Assessment Language): Preferred for Linux/OS-level compliance checks (file systems, processes, packages). It has the best cross-scanner support.
• CEL (Common Expression Language): Used for Kubernetes and OpenShift platform compliance checks. Evaluates Kubernetes API resources without requiring shell access to nodes.
• SCE (Script Check Engine): Use for general-purpose checks using any language (Bash, Python, etc.). Use this only when OVAL lacks necessary support, as it has less cross-scanner support.

CEL rules are used by the compliance-operator to perform compliance checks on Kubernetes and OpenShift resources (like Pods, Deployments, and ConfigMaps) without requiring shell access or OVAL evaluation.

Use CEL when:

• Checking Kubernetes or OpenShift API resources.
• Evaluating Custom Resource Definitions (CRDs).
• Performing platform-level compliance checks for container orchestration systems.

Continue using OVAL for:

• File system, process, or package installation checks.
• Traditional operating system compliance.

The workshop consists of several structured lab exercises designed to familiarize you with OpenSCAP and ComplianceAsCode:

• Lab 1: Say Hello to ComplianceAsCode - Introduction to the project.
• Lab 2: Automated Security Scanning Using ComplianceAsCode - Using ComplianceAsCode for automated scans.
• Lab 3: Create Your Own Security Policy From Scratch - Building custom security policies.
• Lab 4: Using Ansible in ComplianceAsCode - Integrating Ansible for compliance tasks.
• Lab 5: The Art of OVAL Checks - Working with OVAL (Open Vulnerability and Assessment Language) checks.
• Next Steps with ComplianceAsCode - Further learning paths.

The controls folder contains security control definitions. Each control is defined in a control_name.yml file. These YAML files follow this structure:

• control_name.yml: The primary definition file for a control.
• rules: A control may include one or more rules defined within the YAML file.
• variables: A control may include variables that override default values.

NIST 800-53 controls are organized by product (e.g., rhel8, rhel9, rhel10). Each product contains a metadata file and a directory of family files. This structure ensures that only rules applicable to a specific product are included, avoiding Jinja2 conditional logic and keeping files lean.

Directory Structure Example:

products/rhel9/controls/
├── nist_800_53.yml              # RHEL9-specific metadata
└── nist_800_53/                 # RHEL9-specific family files
    ├── ac.yml                   # Access Control family
    ├── au.yml                   # Audit and Accountability family
    └── ... (21 family files)

The products folder in the repository follows a hierarchical structure for defining security content. A product is identified by a product_name and its core definition is located in product.yml.

Key components of a product include:

• Product Properties: Defined in product.yml or within the product_properties/ directory.
• Profiles: Defined in <profile_name>.profile files. Profiles can refer to rules, override variables, and use controls.
• Overlays: Contained within the product structure.
• Kickstart: Optional kickstart files may be present.
• Checks: Defined using OVAL + XCCDF formats, typically written in <check_name>.xml files.