# spolinovskiy/cis_ansible_alt architecture

> Architecture diagram of the GitHub repository spolinovskiy/cis_ansible_alt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spolinovskiy/cis_ansible_alt
- Repository: https://github.com/spolinovskiy/cis_ansible_alt

## Overview

#### Purpose and execution model
This is an Ansible automation project for CIS auditing and controlled remediation of ALT Linux hosts in offline industrial/OT environments. Audit-only is the default; remediation requires explicit enablement and chapter approval. Primary entry points are `playbooks/precheck.yml`, `playbooks/audit.yml`, `playbooks/remediate.yml`, and `playbooks/report.yml`; operator wrappers include `scripts/run_audit_lab.sh` and `scripts/generate_report.sh`.

#### Environment targeting and inputs
Ansible inventories separate lab and production targets: `inventories/lab/hosts.yml` and `inventories/prod/hosts.yml`. Control scope is data-driven from `data/cis_linux_scope/controls_from_excel.yml` (with JSON counterpart), while ALT Linux/version-specific command, package, service, path, and feature mappings are under `data/os_map/`. This boundary keeps benchmark scope and OS adaptations outside task implementation.

#### Pre-execution validation
The precheck stage is implemented by `roles/cis_precheck/tasks/main.yml` and invoked through `playbooks/precheck.yml`. It establishes whether a target/environment is suitable before audit or changes. Shared behavior is centralized in `roles/cis_common/tasks/main.yml`, providing a common role boundary for the operational playbooks.

#### CIS audit engine
`playbooks/audit.yml` runs `roles/cis_audit/tasks/main.yml`, which composes chapter-specific checks. Major CIS domains are independently organized, for example `roles/cis_audit/tasks/bootloader.yml`, `roles/cis_audit/tasks/sshd.yml`, and `roles/cis_audit/tasks/filesystem.yml`. This makes individual control areas addressable for evidence, review, and approved remediation rather than treating the benchmark as a monolithic run.

#### Controlled remediation and approvals
`playbooks/remediate.yml` delegates changes to `roles/cis_remediate/tasks/main.yml`. Approval artifacts are environment- and chapter-scoped, e.g. `approvals/lab/Bootloader/approval.md` and `approvals/lab/SUDO/approval.md`; production has a separate approval root at `approvals/prod/`. The intended control flow is audit findings → review/approval → explicitly enabled remediation, limiting unapproved configuration changes in OT systems.

#### Reporting, review, and evidence
`playbooks/report.yml` invokes `roles/cis_report/tasks/main.yml`, rendering structured outputs via `roles/cis_report/templates/run_summary.md.j2`, `roles/cis_report/templates/checklist.md.j2`, and `roles/cis_report/templates/summary_flat.csv.j2`. Generated chapter evidence is retained by environment under `reports/lab/`, while assessment results live separately in `reviews/lab/` (for example `reviews/lab/SSHD/review.md`). This separates raw/reportable findings from human quality or approval decisions.

#### Sensitive data and operating constraints
The repository intentionally excludes real OT-sensitive values. Templates and examples reside in `data/private_overlay/private_sensitive.example.yml` and `data/required_information/required_information_template.yml`; real values are supplied from an untracked external/private overlay, optionally through Ansible Vault and `CIS_PRIVATE_VARS_FILE`. The material runtime is Ansible operating over managed ALT Linux hosts, designed for offline assumptions documented in `docs/offline_assumptions.md`; no external SaaS or web application dependency is indicated.

Main entry points: [`roles/cis_audit/tasks/main.yml`](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_audit/tasks/main.yml) (CIS audit engine), [`roles/cis_remediate/tasks/main.yml`](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_remediate/tasks/main.yml) (Controlled remediation), [`inventories/lab/hosts.yml`](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/inventories/lab/hosts.yml) (Lab / prod inventory), [`scripts/run_audit_lab.sh`](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/scripts/run_audit_lab.sh) (Operator wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Targeting & policy"]
  node_inventory["Lab / prod inventory<br/>Ansible inventory<br/>[hosts.yml]"]
  node_scope["CIS control scope<br/>control data"]
  node_os_map["ALT Linux mappings<br/>OS adaptation data"]
  node_private_overlay["Private overlay<br/>external vars"]
end

subgraph group_execution["Ansible execution"]
  node_wrappers["Operator wrappers<br/>shell scripts<br/>[run_audit_lab.sh]"]
  node_precheck_playbook["Precheck<br/>playbook<br/>[precheck.yml]"]
  node_precheck_role["Suitability validation<br/>cis_precheck role<br/>[main.yml]"]
  node_common_role["Shared operations<br/>cis_common role<br/>[main.yml]"]
end

subgraph group_controls["Audit &amp; remediation"]
  node_audit_playbook["Audit<br/>playbook<br/>[audit.yml]"]
  node_audit_engine["CIS audit engine<br/>cis_audit role<br/>[main.yml]"]
  node_chapter_checks["Chapter checks<br/>CIS task sets<br/>[bootloader.yml]"]
  node_approvals["Chapter approvals<br/>approval artifacts<br/>[approval.md]"]
  node_remediate_playbook["Remediate<br/>playbook<br/>[remediate.yml]"]
  node_remediate_role["Controlled remediation<br/>cis_remediate role<br/>[main.yml]"]
end

subgraph group_evidence["Evidence &amp; review"]
  node_report_playbook["Report<br/>playbook<br/>[report.yml]"]
  node_report_role["Report renderer<br/>cis_report role<br/>[main.yml]"]
  node_evidence["Chapter evidence<br/>generated reports"]
  node_reviews["Assessment reviews<br/>human review<br/>[review.md]"]
end

node_operators(("Operators<br/>user"))
node_managed_hosts{{"ALT Linux hosts<br/>managed hosts"}}

node_operators -->|"runs"| node_wrappers
node_wrappers -->|"starts"| node_precheck_playbook
node_wrappers -->|"starts"| node_audit_playbook
node_inventory -->|"targets"| node_precheck_playbook
node_inventory -->|"targets"| node_audit_playbook
node_inventory -->|"targets"| node_remediate_playbook
node_precheck_playbook -->|"invokes"| node_precheck_role
node_precheck_role -->|"uses"| node_common_role
node_precheck_role -->|"validates"| node_managed_hosts
node_audit_playbook -->|"invokes"| node_audit_engine
node_audit_engine -->|"composes"| node_chapter_checks
node_scope -->|"selects controls"| node_audit_engine
node_os_map -->|"adapts checks"| node_audit_engine
node_private_overlay -.->|"supplies protected vars"| node_common_role
node_chapter_checks -->|"audits"| node_managed_hosts
node_audit_engine -->|"produces findings"| node_evidence
node_evidence -->|"supports review"| node_reviews
node_reviews -->|"authorizes chapters"| node_approvals
node_approvals -->|"gates"| node_remediate_playbook
node_remediate_playbook -->|"delegates"| node_remediate_role
node_scope -->|"bounds changes"| node_remediate_role
node_os_map -->|"adapts changes"| node_remediate_role
node_remediate_role -->|"changes approved controls"| node_managed_hosts
node_report_playbook -->|"invokes"| node_report_role
node_evidence -->|"renders"| node_report_role
node_report_role -->|"writes summaries"| node_evidence

click node_wrappers "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/scripts/run_audit_lab.sh"
click node_inventory "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/inventories/lab/hosts.yml"
click node_scope "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/data/cis_linux_scope/controls_from_excel.yml"
click node_private_overlay "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/data/private_overlay/private_sensitive.example.yml"
click node_precheck_playbook "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/precheck.yml"
click node_precheck_role "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_precheck/tasks/main.yml"
click node_common_role "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_common/tasks/main.yml"
click node_audit_playbook "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/audit.yml"
click node_audit_engine "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_audit/tasks/main.yml"
click node_chapter_checks "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_audit/tasks/bootloader.yml"
click node_approvals "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/approvals/lab/Bootloader/approval.md"
click node_remediate_playbook "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/remediate.yml"
click node_remediate_role "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_remediate/tasks/main.yml"
click node_report_playbook "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/report.yml"
click node_report_role "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_report/tasks/main.yml"
click node_reviews "https://github.com/spolinovskiy/cis_ansible_alt/blob/main/reviews/lab/SSHD/review.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inventory,node_scope,node_os_map,node_private_overlay toneBlue
class node_wrappers,node_precheck_playbook,node_precheck_role,node_common_role toneAmber
class node_audit_playbook,node_audit_engine,node_chapter_checks,node_approvals,node_remediate_playbook,node_remediate_role toneMint
class node_report_playbook,node_report_role,node_evidence,node_reviews toneRose
class node_operators,node_managed_hosts toneNeutral
```

## Components

### Targeting & policy

Data-driven scope and ALT Linux adaptations.

- [Lab / prod inventory](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/inventories/lab/hosts.yml): Ansible inventory · `inventories/lab/hosts.yml`
- [CIS control scope](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/data/cis_linux_scope/controls_from_excel.yml): control data · `data/cis_linux_scope/controls_from_excel.yml`
- **ALT Linux mappings**: OS adaptation data
- [Private overlay](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/data/private_overlay/private_sensitive.example.yml): external vars · Untracked sensitive values, optionally Vault-backed. · `data/private_overlay/private_sensitive.example.yml`

### Ansible execution

Operational playbooks and shared role behavior.

- [Operator wrappers](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/scripts/run_audit_lab.sh): shell scripts · `scripts/run_audit_lab.sh`
- [Precheck](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/precheck.yml): playbook · `playbooks/precheck.yml`
- [Suitability validation](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_precheck/tasks/main.yml): cis_precheck role · `roles/cis_precheck/tasks/main.yml`
- [Shared operations](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_common/tasks/main.yml): cis_common role · `roles/cis_common/tasks/main.yml`

### Audit & remediation

Chapter-level controls and approval-gated changes.

- [Audit](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/audit.yml): playbook · Default audit-only execution. · `playbooks/audit.yml`
- [CIS audit engine](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_audit/tasks/main.yml): cis_audit role · `roles/cis_audit/tasks/main.yml`
- [Chapter checks](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_audit/tasks/bootloader.yml): CIS task sets · Bootloader, SSHD, filesystem, and other domains. · `roles/cis_audit/tasks/bootloader.yml`
- [Chapter approvals](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/approvals/lab/Bootloader/approval.md): approval artifacts · Environment- and chapter-scoped change authorization. · `approvals/lab/Bootloader/approval.md`
- [Remediate](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/remediate.yml): playbook · Requires explicit enablement and approval. · `playbooks/remediate.yml`
- [Controlled remediation](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_remediate/tasks/main.yml): cis_remediate role · `roles/cis_remediate/tasks/main.yml`

### Evidence & review

Rendered evidence and human decisions.

- [Report](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/playbooks/report.yml): playbook · `playbooks/report.yml`
- [Report renderer](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/roles/cis_report/tasks/main.yml): cis_report role · Renders Markdown checklists and flat CSV summaries. · `roles/cis_report/tasks/main.yml`
- **Chapter evidence**: generated reports
- [Assessment reviews](https://github.com/spolinovskiy/cis_ansible_alt/blob/main/reviews/lab/SSHD/review.md): human review · Separate quality and approval decisions. · `reviews/lab/SSHD/review.md`

### Other components

- **Operators**: user
- **ALT Linux hosts**: managed hosts · Offline industrial and OT targets.

## Connections

- Operators → Operator wrappers: runs
- Operator wrappers → Precheck: starts
- Operator wrappers → Audit: starts
- Lab / prod inventory → Precheck: targets
- Lab / prod inventory → Audit: targets
- Lab / prod inventory → Remediate: targets
- Precheck → Suitability validation: invokes
- Suitability validation → Shared operations: uses
- Suitability validation → ALT Linux hosts: validates
- Audit → CIS audit engine: invokes
- CIS audit engine → Chapter checks: composes
- CIS control scope → CIS audit engine: selects controls
- ALT Linux mappings → CIS audit engine: adapts checks
- Private overlay → Shared operations: supplies protected vars
- Chapter checks → ALT Linux hosts: audits
- CIS audit engine → Chapter evidence: produces findings
- Chapter evidence → Assessment reviews: supports review
- Assessment reviews → Chapter approvals: authorizes chapters
- Chapter approvals → Remediate: gates
- Remediate → Controlled remediation: delegates
- CIS control scope → Controlled remediation: bounds changes
- ALT Linux mappings → Controlled remediation: adapts changes
- Controlled remediation → ALT Linux hosts: changes approved controls
- Report → Report renderer: invokes
- Chapter evidence → Report renderer: renders
- Report renderer → Chapter evidence: writes summaries