OpenSCAP

OpenSCAP evaluates the host against a chosen compliance profile — CIS, STIG, and others — using the SSG content bundled into the agent image.

• Tool — oscap xccdf eval against an SCAP Security Guide (SSG) datastream.
• Detection only. Reef never runs --remediate.

How it actually reaches the host

oscap’s environment detection (mount table, kernel modules, running services, /.dockerenv) reflects wherever the process runs, so running it naively inside the agent container makes it think it’s scanning a container and mark most CIS rules “not applicable”. The runner walks a fallback chain, most-faithful first, falling through when a mode can’t provide the profile or can’t run:

1. host — the host has its own oscap + SSG; run it there via nsenter -t 1.
2. bundled-host — no host oscap: stage the agent’s own oscap + libraries into the host’s /tmp and run that in the host namespaces. Full fidelity (real mount table, kernel modules, services, package DB) with nothing installed on the host — needs the host’s glibc to be at least the agent image’s (~2.36, i.e. Fedora 36+ / RHEL 9+ / Ubuntu 22.04+).
3. probe-root — last resort: the container’s oscap + baked-in SSG with OSCAP_PROBE_ROOT=/host. Only file-based checks are trustworthy here.
4. local — for a bare-metal agent.

params.mode forces one of these explicitly.

Prefer installing openscap on the host

host mode is the recommended setup — install openscap-scanner (or your distro’s equivalent) and the SCAP Security Guide content directly on every monitored host, rather than relying on bundled-host. Both modes actually run oscap on the host via nsenter -t 1 (same real mount table, kernel modules, services, and package DB either way) — bundled-host just gets there by staging the agent’s own oscap binary and its ldd libraries into the host’s /tmp first, since no oscap is installed there. A real host install:

• doesn’t depend on host/agent glibc compatibility (the ~2.36 floor the staged binary needs to run against the host’s ld.so),
• gets you the distro’s own SSG package, which stays current with dnf/apt/ zypper updates instead of whatever SSG version shipped in the agent image — though note Debian’s ssg-* apt packages lag upstream ComplianceAsCode by around three years, and Fedora’s datastream ships with no CIS profile at all, so double-check the installed content actually has the profile you need before switching away from the agent’s bundled (pinned, current) content,
• and lets you run oscap yourself outside of Reef for spot checks.

Once oscap and its SSG content are on the host and discoverable, the runner picks host mode automatically — no params.mode override needed.

Fedora / RHEL / CentOS / Rocky / AlmaLinux

sudo dnf install -y openscap-scanner scap-security-guide

Debian / Ubuntu

sudo apt update
sudo apt install -y libopenscap8 ssg-debderived ssg-debian ssg-applications

Ubuntu ships its own SSG package instead:

sudo apt update
sudo apt install -y libopenscap8 ssg-debderived ssg-nondebian ssg-applications

(Package names vary by release — apt search ssg- on the host to see what’s available if one of these isn’t found.)

openSUSE / SLES

sudo zypper install -y openscap openscap-utils scap-security-guide

Arch Linux

sudo pacman -S openscap scap-security-guide

Confirm the install and that content is discoverable:

oscap -V
ls /usr/share/xml/scap/ssg/content/

Profile selection

The agent picks the datastream matching the host’s distro/version, or the closest family if there’s no exact match (flagged inexact so the checklist carries the caveat), then resolves the profile short name — cis_server_l1, stig, pci-dss, etc. Every rule’s title, rationale, fix text, CIS/NIST 800-53/CCI references, and CCE come straight from the datastream that was actually evaluated.

If a profile isn’t in the chosen content, or nothing evaluated (wrong-OS content, failed probe), the job fails loudly instead of recording a misleading “done”.

Summary fields

mode, compliance_pct, score, and pass/fail/manual/n-a counts.

Exporting a checklist

GET /api/scans/<id>/checklist/ exports the profile’s rules as a STIG Viewer 3 .cklb file, ready for eMASS ingestion: pass → NotAFinding, fail → Open, notapplicable → Not_Applicable (with a “confirm and justify” comment). In probe-root mode, oscap can’t see the host’s mount table, kernel modules, or services, so its notapplicable verdicts on those rules aren’t trustworthy and are downgraded to Not_Reviewed instead (the scan surfaces how many, and recommends installing openscap-scanner on the host). Anything the scanner didn’t actually assess is Not_Reviewed; rules not in the profile (notselected) are excluded entirely.

Params