# gangadhariy/rhel9.0-l1-cis architecture

> Architecture diagram of the GitHub repository gangadhariy/rhel9.0-l1-cis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gangadhariy/rhel9.0-l1-cis
- Repository: https://github.com/gangadhariy/rhel9.0-l1-cis

## Overview

##### Project Type and Purpose
- This is an Ansible Role named “RHEL9-CIS” designed to enforce CIS Benchmark v1.0.0 controls on RHEL-9 and compatible distributions.
- It is not a typical client-server application but an automation “remediation” tool (not an audit-only tool) that applies OS configuration changes via Ansible.

##### High-Level Architecture Overview
- Control Plane (Ansible Control Node)
- Runs ansible-playbook, loads this role from a play or Tower.
- Parses inventory, loads defaults/vars/collections, runs tasks.
- Integrates with GitHub Actions for CI (main_pipeline_validation, devel_pipeline_validation).
- Runs Molecule for local testing against containers or WSL.
- Managed Nodes (Target Hosts)
- Systems running RHEL9, AlmaLinux9, Rocky9 or OracleLinux9.
- Ansible connects via SSH or WinRM, gathers facts, enforces configurations.
- May host the Goss binary for “live” auditing (if setup_audit is true).
- External Components
- GitHub (source repository, Actions CI).
- Ansible Galaxy (role distribution).
- Collection dependencies (defined in collections/requirements.yml).
- Goss (embedded Go binary + YAML checks for auditing).
- Molecule (Docker/Podman drivers for converge/verify).

##### Directory-to-Component Mapping
- defaults/main.yml
- Default variables controlling audit, CIS level, os_check, etc.
- vars/*.yml
- OS-specific variables per distribution.
- tasks/
- Entry point main.yml → includes check_prereqs, auditd, sections 1–6, post_remediation, handlers.
- Section subdirectories model CIS domains (1=Initial Setup, 2=Services, …).
- handlers/main.yml
- Notifications, service restarts (e.g., systemd unit reload after template changes).
- templates/
- Jinja2 templates for configuration files (sysctl.d, audit rules, dconf, chrony, tmp.mount).
- files/
- Static files (e.g., systemd tmp.mount unit) to copy.
- meta/main.yml
- Role metadata, Galaxy dependencies.
- molecule/
- Scenarios for default, localhost, wsl: converge.yml + verify.yml + molecule.yml.
- .github/workflows/
- CI pipelines invoking linting, molecule testing, pre-commit.

##### Relationships and Data Flow
1. Developer commits code → GitHub Actions triggers pipelines.
2. In CI:
- ansible-lint, yamllint, pre-commit checks.
- Molecule spins up ephemeral VM/container → runs converge, then verify.
3. End user runs ansible-playbook:
- Control node reads defaults & vars → composes task list.
- SSH to each managed host → gather_facts.
- Execute tasks in order: parse_etc_password, check_prereqs, auditd setup, section tasks, post.
- Each template copy triggers handler events (service reloads).
- If setup_audit & run_audit true → push Goss binary + configs, run goss tests.
4. Managed hosts report status; playbook returns success/failure.

##### Architectural Patterns & Design Principles
- Layered modularization by CIS sections to keep tasks granular.
- Divide default configuration vs. override vars per OS.
- Idempotent task design (Ansible best practice).
- Use of tagging for selective runs (level1-server, scored, services, rule_X.Y.Z).
- Test-driven infrastructure via Molecule.
- CI gating to ensure role quality before merge.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    GH["GitHub Repo & Actions"]:::codeCI
    GALAXY(("Ansible Galaxy")):::external
    COLL_REQ(("collections/requirements.yml")):::ansible
    GOSS["Goss Testing"]:::tooling
    MOLECULE["Molecule"]:::codeCI

    %% Control Node and Role Code
    subgraph "Control Node" 
        direction TB
        PLAYBOOK["ansible-playbook"]:::ansible

        subgraph "Role: RHEL9-CIS"
            direction TB
            subgraph "Defaults & Vars"
                direction TB
                DEF["defaults/main.yml"]:::ansible
                VAR_GLOBAL["vars/main.yml & vars/audit.yml"]:::ansible
                VAR_OS["vars/*.yml (OS-specific)"]:::ansible
            end

            subgraph "Tasks"
                direction TB
                ENTRY["tasks/main.yml"]:::ansible
                PREREQ["tasks/check_prereqs.yml"]:::ansible
                PARSE_PASS["tasks/parse_etc_password.yml"]:::ansible
                AUDITD["tasks/auditd.yml"]:::ansible
                LE_AUDIT_SETUP["tasks/LE_audit_setup.yml & tasks/audit_only.yml"]:::ansible
                PRE_AUDIT["tasks/pre_remediation_audit.yml"]:::ansible
                SECTION_PRELIM["tasks/prelim.yml"]:::ansible
                WARNING["tasks/warning_facts.yml"]:::ansible
                subgraph "CIS Sections"
                    direction TB
                    SEC1["tasks/section_1/main.yml + cis_1.*.yml"]:::ansible
                    SEC2["tasks/section_2/main.yml + cis_2.*.yml"]:::ansible
                    SEC3["tasks/section_3/main.yml + cis_3.*.yml"]:::ansible
                    SEC4["tasks/section_4/main.yml + cis_4.*.yml"]:::ansible
                    SEC5["tasks/section_5/main.yml + cis_5.*.yml"]:::ansible
                    SEC6["tasks/section_6/main.yml + cis_6.*.yml"]:::ansible
                end
                POST_REMED["tasks/post_remediation_audit.yml"]:::ansible
                POST_CLEAN["tasks/post.yml"]:::ansible
            end

            subgraph "Handlers & Templates"
                direction TB
                HANDLERS["handlers/main.yml"]:::ansible
                subgraph "Templates"
                    direction TB
                    TGOSS["templates/ansible_vars_goss.yml.j2"]:::ansible
                    TAUDIT1["templates/audit/98_auditd_exception.rules.j2"]:::ansible
                    TAUDIT2["templates/audit/99_auditd.rules.j2"]:::ansible
                    TAIDE["templates/etc/aide.conf.d/*.j2"]:::ansible
                    TCHRONY["templates/etc/chrony.conf.j2"]:::ansible
                    TCRON["templates/etc/cron.d/aide.cron.j2"]:::ansible
                    TDCONF["templates/etc/dconf/db/**/*.j2 & gdm.d/01-banner-message.j2"]:::ansible
                    TSYSCTL["templates/etc/sysctl.d/60-*.j2"]:::ansible
                    TTMPMOUNT["templates/etc/systemd/system/tmp.mount.j2"]:::ansible
                    TOTHER["templates/etc/{issue,issue.net,motd,modprobe.conf}.j2"]:::ansible
                end
                FILE_TMP["files/etc/systemd/system/tmp.mount"]:::ansible
            end

            META["meta/main.yml"]:::ansible
        end
    end

    %% CI Flow
    GH -->|push triggers| MOLECULE
    GH -->|CI pipelines| PLAYBOOK
    MOLECULE -->|molecule converge & verify| PLAYBOOK
    PLAYBOOK -->|loads role| DEF
    PLAYBOOK --> VAR_GLOBAL
    PLAYBOOK --> VAR_OS
    PLAYBOOK --> ENTRY

    %% Task flow
    ENTRY --> SECTION_PRELIM --> PREREQ --> WARNING --> PARSE_PASS --> AUDITD --> PRE_AUDIT
    PRE_AUDIT --> SECTION_PRELIM
    SECTION_PRELIM --> SEC1 --> SEC2 --> SEC3 --> SEC4 --> SEC5 --> SEC6
    SEC6 --> POST_REMED --> POST_CLEAN
    POST_CLEAN --> HANDLERS

    %% Control to Managed Hosts
    PLAYBOOK -->|"SSH/WinRM"| HOSTS["Managed Hosts (RHEL9 variants)"]:::external
    HOSTS -->|gather_facts & enforce| PLAYBOOK
    HOSTS -->|optional Goss audit| GOSS

    %% External distribution
    PLAYBOOK --> GALAXY
    PLAYBOOK --> COLL_REQ

    %% Click events
    click DEF "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/defaults/main.yml"
    click VAR_GLOBAL "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/vars/main.yml"
    click VAR_OS "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/vars/RedHat.yml"
    click ENTRY "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/main.yml"
    click PREREQ "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/check_prereqs.yml"
    click PARSE_PASS "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/parse_etc_password.yml"
    click AUDITD "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/auditd.yml"
    click LE_AUDIT_SETUP "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/LE_audit_setup.yml"
    click PRE_AUDIT "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/pre_remediation_audit.yml"
    click POST_REMED "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/post_remediation_audit.yml"
    click POST_CLEAN "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/post.yml"
    click SECTION_PRELIM "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/prelim.yml"
    click WARNING "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/warning_facts.yml"
    click SEC1 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_1/main.yml"
    click SEC2 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_2/main.yml"
    click SEC3 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_3/main.yml"
    click SEC4 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_4/main.yml"
    click SEC5 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_5/main.yml"
    click SEC6 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/tasks/section_6/main.yml"
    click HANDLERS "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/handlers/main.yml"
    click TGOSS "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/ansible_vars_goss.yml.j2"
    click TAUDIT1 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/audit/98_auditd_exception.rules.j2"
    click TAUDIT2 "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/audit/99_auditd.rules.j2"
    click TAIDE "https://github.com/gangadhariy/rhel9.0-l1-cis/tree/devel/templates/etc/aide.conf.d/"
    click TCHRONY "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/etc/chrony.conf.j2"
    click TCRON "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/etc/cron.d/aide.cron.j2"
    click TDCONF "https://github.com/gangadhariy/rhel9.0-l1-cis/tree/devel/templates/etc/dconf/db/"
    click TSYSCTL "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/etc/sysctl.d/60-*.j2"
    click TTMPMOUNT "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/templates/etc/systemd/system/tmp.mount.j2"
    click TOTHER "https://github.com/gangadhariy/rhel9.0-l1-cis/tree/devel/templates/etc/"
    click FILE_TMP "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/files/etc/systemd/system/tmp.mount"
    click META "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/meta/main.yml"
    click COLL_REQ "https://github.com/gangadhariy/rhel9.0-l1-cis/blob/devel/collections/requirements.yml"

    %% Styles
    classDef codeCI fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ansible fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef tooling fill:#fff3cd,stroke:#333,stroke-width:1px
```
