Document CEL Rules and its usage

Author: yuumasato

.claude/CLAUDE.md

@@ -158,6 +158,109 @@ template:
         pkgname@ubuntu2204: avahi-daemon    # Platform-specific overrides
 ```
 
+## CEL Rules (Kubernetes/OpenShift)
+
+CEL (Common Expression Language) rules provide native Kubernetes resource evaluation without requiring shell access or OVAL checks. CEL rules are used by the compliance-operator for Kubernetes and OpenShift compliance scanning.
+
+**Important:** CEL rules are **excluded** from XCCDF/OVAL DataStreams and are generated as a separate `${PRODUCT}-cel-content.yaml` file.
+
+### Required Fields for CEL Rules
+
+```yaml
+documentation_complete: true
+
+title: 'Rule Title'
+
+description: |-
+    Description of what the rule checks.
+
+rationale: |-
+    Why this rule matters.
+
+severity: medium
+
+scannerType: CEL           # REQUIRED: Marks this as a CEL rule
+
+checkType: Platform        # Usually Platform for K8s checks
+
+expression: |-             # REQUIRED: CEL expression (must evaluate to boolean)
+    resource.spec.enabled == true
+
+inputs:                    # REQUIRED: Kubernetes resources to evaluate
+  - name: resource
+    kubernetesInputSpec:
+      apiVersion: v1
+      resource: pods
+      resourceName: my-pod          # Optional: specific resource
+      resourceNamespace: default    # Optional: specific namespace
+
+ocil: |-                   # Optional: Manual check instructions
+    Run the following command:
+    <pre>$ oc get pods</pre>
+
+failureReason: |-          # Optional: Custom failure message
+    The resource is not properly configured.
+
+references:                # Optional: Same as regular rules
+    cis@ocp4: 1.2.3
+    nist: CM-6
+```
+
+### CEL Expression Examples
+
+Simple boolean check:
+```yaml
+expression: resource.spec.enabled == true
+```
+
+Check for field absence:
+```yaml
+expression: !has(resource.spec.insecureField)
+```
+
+Multiple conditions:
+```yaml
+expression: |-
+    resource.spec.replicas >= 3 &&
+    has(resource.spec.securityContext) &&
+    resource.spec.securityContext.runAsNonRoot == true
+```
+
+### CEL Profile Format
+
+Profiles that use CEL rules must have `scannerType: CEL`:
+
+```yaml
+documentation_complete: true
+
+title: 'CIS VM Extension Benchmark'
+
+description: |-
+    Profile description.
+
+scannerType: CEL    # REQUIRED: Marks this as a CEL profile
+
+selections:
+    - kubevirt-nonroot-feature-gate-is-enabled
+    - kubevirt-no-permitted-host-devices
+```
+
+**Note:** CEL profiles can only select CEL rules and are excluded from XCCDF generation.
+
+**Important:** Use hyphens rule IDs (Kubernetes naming convention), not underscores.
+
+### Enabling CEL Content for a Product
+
+In `products/${PRODUCT}/CMakeLists.txt`:
+
+```cmake
+set(PRODUCT "ocp4")
+set(PRODUCT_CEL_ENABLED TRUE)  # Enable CEL content generation
+ssg_build_product(${PRODUCT})
+```
+
+See `docs/manual/developer/12_cel_content.md` for complete CEL documentation.
+
 ## Common Jinja2 Macros
 
 Used in rule descriptions, OCIL, fixtext, and warnings fields:

README.md

@@ -41,6 +41,12 @@ profiles.  These are meant to be run on machines to put them into
 compliance.  We recommend using other formats but understand that for
 some deployment scenarios bash is the only option.
 
+*"CEL content"* refers to compliance content using the Common Expression Language (CEL)
+for Kubernetes and OpenShift platforms. CEL content is generated as YAML files and is
+designed for native Kubernetes resource evaluation through the compliance-operator,
+without requiring shell access to nodes. This format is used for platform-level
+compliance checks on container orchestration systems.
+
 ### Why?
 
 We want multiple organizations to be able to efficiently develop security

docs/manual/developer/07_understanding_build_system.md

@@ -83,6 +83,7 @@ of occurrence:
 - Load resolved rules, profiles, groups, collected remediations and the unlinked OVAL document and generate XCCDF, OVAL and OCIL documents from this data.
 - Generate CPE OVAL and CPE dictionary.
 - Combining the OVAL, OCIL, CPE and XCCDF documents into a single SCAP source data stream.
+- Generate CEL content YAML for Kubernetes/OpenShift compliance checks (if enabled for the product).
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.
 
@@ -93,6 +94,9 @@ refer to their help text for more information and usage:
 
 - `build_all_guides.py` -- generates separate HTML guides for every profile
   in an XCCDF document.
+- `build_cel_content.py` -- generates CEL (Common Expression Language) content
+  YAML for Kubernetes/OpenShift compliance checks. See [CEL Content](12_cel_content.md)
+  for detailed information about CEL rules and profiles.
 - `build_rule_playbooks.py` -- generates per-rule per-profile playbooks in
   Ansible content.
 - `build_sce.py` -- outputs SCE content and combined metadata.
@@ -167,3 +171,95 @@ Steps to link an OVAL document to an XCCDF document:
 8. The OVAL Document object is stored as an XML file `build/ssg-${PRODUCT}-oval.xml`.
 9. For each XCCDF rule, a minimal OVAL Documents document is generated as an artifact
 10. For each reference of OVAL check in XCCDF, a link to the `check-content` and a `check-export` element is added.
+
+## How CEL Content is Built
+
+CEL (Common Expression Language) content provides an alternative scanning mechanism to OVAL specifically designed for Kubernetes and OpenShift API resource evaluation. Unlike OVAL which requires shell access and evaluates system state, CEL rules evaluate Kubernetes resources directly through the API server.
+
+CEL content generation is optional and must be explicitly enabled for each product.
+
+### Enabling CEL Content
+
+CEL content generation is enabled by setting `PRODUCT_CEL_ENABLED` in the product's `CMakeLists.txt`:
+
+```cmake
+set(PRODUCT "ocp4")
+set(PRODUCT_REMEDIATION_LANGUAGES "ignition;kubernetes")
+set(PRODUCT_CEL_ENABLED TRUE)
+
+ssg_build_product(${PRODUCT})
+```
+
+### Build Process
+
+When CEL content is enabled for a product, the build system performs the following steps:
+
+1. **Rule and Profile Resolution** - All rules and profiles are compiled to their product-specific resolved form (same as for XCCDF/OVAL).
+
+2. **CEL Rule Loading** - The `build_cel_content.py` script loads all rules with `scannerType: CEL` from the `build/${PRODUCT}/rules/` directory.
+
+3. **CEL Profile Loading** - The script loads all profiles with `scannerType: CEL` from the `build/${PRODUCT}/profiles/` directory.
+
+4. **Validation** - The build system validates CEL content:
+   - Rules must have `expression` field (non-empty CEL expression)
+   - Rules must have `inputs` field (non-empty list of Kubernetes resources)
+   - Profiles must have `selected` field with at least one rule
+   - No duplicate rule names (after conversion to hyphenated format)
+   - All profile rule references must exist in the CEL rules
+
+5. **Content Generation** - The script generates a single CEL content YAML file at `build/${PRODUCT}-cel-content.yaml`.
+
+### CEL Content Structure
+
+The generated CEL content YAML has two main sections:
+
+```yaml
+profiles:
+  - id: cis_vm_extension              # Profile ID (with underscores)
+    name: cis-vm-extension            # Profile name (with hyphens)
+    title: Profile Title
+    description: Profile description
+    productType: Platform
+    rules:                            # List of rule names (hyphenated)
+      - rule-name-one
+      - rule-name-two
+
+rules:
+  - id: rule_name_one                 # Rule ID (with underscores)
+    name: rule-name-one               # Rule name (with hyphens)
+    title: Rule Title
+    description: Rule description
+    rationale: Rule rationale
+    severity: medium
+    checkType: Platform
+    expression: |                     # CEL expression
+      resource.spec.enabled == true
+    inputs:                           # Kubernetes resource inputs
+      - name: resource
+        kubernetesInputSpec:
+          apiVersion: v1
+          resource: pods
+    instructions: Manual check steps  # From ocil field
+    controls:                         # From references field
+      cis@ocp4:
+        - 1.2.3
+      nist:
+        - CM-6
+```
+
+### Differences from XCCDF/OVAL
+
+CEL content is processed differently from traditional XCCDF/OVAL content:
+
+| Aspect | XCCDF/OVAL | CEL Content |
+|--------|-----------|-------------|
+| **Rules Included** | All rules except CEL | Only CEL rules |
+| **Profiles Included** | All profiles except CEL | Only CEL profiles |
+| **Output Format** | XML (DataStream) | YAML |
+| **Output Location** | `build/ssg-${PRODUCT}-ds.xml` | `build/${PRODUCT}-cel-content.yaml` |
+| **Scanner** | OpenSCAP | compliance-operator |
+| **Evaluation** | Shell commands, file checks | Kubernetes API queries |
+
+Rules and profiles with `scannerType: CEL` are **excluded** from XCCDF/OVAL generation and **only** appear in the CEL content YAML.
+
+For detailed information about creating CEL rules and profiles, see [CEL Content](12_cel_content.md).