| name | scap_compliance |
| description | Maintains the ansible/roles/scap_compliance Ansible role that runs oscap against a chosen OpenSCAP profile (default cis) and can auto-remediate findings, as part of the Linux SOE. Use when checking or fixing OpenSCAP/SCAP compliance. |
scap_compliance
Maintains ansible/roles/scap_compliance/. See docs/ARCHITECTURE.md for the shared
conventions (role layout, audit vs. remediate via --check --diff, safety
rules, branch + PR contribution workflow).
ansible/roles/scap_compliance/README.md documents this role's full
configuration surface (every defaults/main.yml variable, with its
original inline comments, rendered as a single reference). Read it
before proposing or explaining how to configure this role — it
reflects the role's actual current defaults even if a variable summary
elsewhere in this file has drifted out of sync with the role.
What the role actually does
Encoded in ansible/roles/scap_compliance/defaults/main.yml:
scap_compliance_profile (default cis) selects the
xccdf_org.ssgproject.content_profile_<profile> profile from the RPM-provided
scap-security-guide datastream (or scap_compliance_content_file_path if
overridden); the role's own comment warns switching profiles later is
unsupported.scap_compliance_remediate (default false) — with it false the role
runs oscap xccdf eval as an audit-only report; only with it true does the
underlying command run --remediate and actually change the system. This is
the one role in the repo where audit vs. remediate is a role variable, not
the --check/no---check Ansible flag — passing --check --diff alone does
not make this role read-only if scap_compliance_remediate: true.scap_compliance_remediate_reboot (default true) — reboots after a
remediation that changed something.scap_compliance_check_fail_role_pass (default false) — by default a
failed compliance check fails the Ansible run; set true to let the role
complete regardless and rely on the report file instead.- Results land in
scap_compliance_report_dir (default /root/oscap/results)
— only the most recent run's results are kept.
This role is sourced from the myllynen/rhel-ansible-roles import
(see git log -- ansible/roles/scap_compliance) rather than hand-authored for this
repo. Unlike the original reference domains (e.g. timesync, usbguard_setup),
it applies state declaratively via standard Ansible modules and does not
add its own assert-based drift checks on top — an audit here is exactly
what --check --diff reports from the underlying modules, nothing more.
What to do
This role is off by default in ansible/configure_rhel.yml — every
role there (active or not) is gated by a single configure_rhel_domains
list variable (when: "'<name>' in configure_rhel_domains"), and scap_compliance
isn't in the default value of that list. Nothing needs editing in the
playbook itself to turn it on: pass the full desired domain list via
-e, e.g.
-e '{"configure_rhel_domains": [...the default 20..., "scap_compliance"]}'
(see .claude/skills/configure_rhel/SKILL.md for the current default list
to extend, and why it has to be the full list, not just the addition —
-e replaces the variable's value, it doesn't merge into it). --tags scap_compliance
alone is not enough — the domains list and --tags/--skip-tags are
separate, ANDed gates, both verified independently: a role only runs if
it's in configure_rhel_domains and matches the requested tags. Some
roles (this one — check its defaults/main.yml and task file) also have
their own internal enable flag or required variable on top of that, which
still needs setting the same as before. Flag all of this to the user before
assuming the commands below will do anything.
Audit (read-only, safe to run any time):
ansible-playbook ansible/configure_rhel.yml --tags scap_compliance --check --diff
Summarize the diff output and any failed tasks in plain language.
Remediate (modifies the system — only after the user explicitly asks):
first summarize what will change from the --check --diff output, then run
the same command without --check:
ansible-playbook ansible/configure_rhel.yml --tags scap_compliance
Propose a change to the role itself: never edit and commit directly. On a
branch named soe/scap_compliance/<short-desc>, edit ansible/roles/scap_compliance/, validate
locally (--syntax-check, ansible-lint roles/scap_compliance/, and
--check --diff against a real/test host if available), then push and open a
PR titled [scap_compliance] <what changed> with the --check --diff output in the
body. Then stop — a human reviews and merges; see docs/ARCHITECTURE.md's
"Contribution workflow".
Notes
- Because
scap_compliance_remediate (not --check) gates whether the
system is actually changed, treat any request to "check compliance" as
requiring scap_compliance_remediate: false explicitly (the default) unless
the user has asked to remediate — running --check --diff against this role
with scap_compliance_remediate: true set will still remediate the host.
The role's own comment also states reverting SCAP remediation is not
supported — there's no automatic undo.
Wiring into the SOE
This role has a row in .claude/skills/soe/SKILL.md's domain table. It's
present (not commented out) in ansible/configure_rhel.yml's roles: list,
gated by configure_rhel_domains — off by default, on via -e — see the
caveat at the top of "What to do" above and
.claude/skills/configure_rhel/SKILL.md. It is not referenced by any of the
other playbooks (load_balancer_setup.yml, nfs_client_setup.yml,
nfs_server_setup.yml, update_rhel.yml, connect_linux.yml) either. This
repo no longer uses ansible/site.yml; see docs/ARCHITECTURE.md.
