# usnistgov/macos_security architecture

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

- Interactive diagram: https://gitdiagram.com/usnistgov/macos_security
- Repository: https://github.com/usnistgov/macos_security

## Overview

##### Project Type and Purpose
- This is an open-source, programmatic compliance-tool project (“macOS Security Compliance Project”) that generates security baselines, guidance, SCAP content, and documentation for macOS.
- It consumes a library of atomic compliance rules (YAML files) and baseline definitions, applies generation logic (Python scripts + Asciidoctor/Ruby), and publishes both static documentation (via a static-site generator) and compliance artifacts (SCAP XML, checklists, guidance PDF).

##### High-Level File/Directory Analysis
- Data Layer
- baselines/ (YAML definitions of baseline collections)
- includes/, rules/, sections/ (YAML fragments of controls, payloads, sections)
- Engine / Generation Layer
- scripts/ (Python modules: generate_baseline.py, generate_scap.py, generate_guidance.py, etc.)
- scripts/util/ (helper functions)
- Gemfile & Asciidoctor depends (Ruby-based doc assembler using templates)
- Template Layer
- templates/ (Asciidoc templates, CSS, theme YAML, images)
- Documentation Portal
- docs/ (Astro-based static site: docs/src, docs/public, package.json, pnpm-lock)
- Build & CI
- build/ (output artifacts)
- .github/workflows/build_documentation.yml (CI pipeline)

##### Key README Insights
- Primary goal: produce NIST SP 800-53-mapped macOS secure configuration guidance.
- Provides both programmatic baseline generation and a docs site for human consumption.
- Encourages extension via custom/rules and custom/sections.

##### Components
A. Data Components (Inputs)
- “Rule Repository” node: YAML files in includes/, rules/, sections/.
- “Baseline Definitions” node: YAML under baselines/.
- “Custom Extensions” node: custom/rules, custom/sections.
B. Generation Engine (Processing)
- “Python Generation Service”: scripts/generate_*.py
- “Template Processor”: Asciidoctor (Ruby) + templates/
C. Output Artifacts (Outputs)
- “Compliance Artifacts”: SCAP XML, mapping spreadsheets, checklists under build/
- “Guidance Documents”: PDF, HTML (via Asciidoctor) under build/
D. Documentation Portal
- “Static Site Generator”: Astro (docs/src) → docs/public → GitHub Pages
E. CI/CD Pipeline
- “GitHub Actions”: build documentation & site, publish artifacts

##### Relationships & Data Flows
1. Rule Repository + Baseline Definitions feed into → Python Generation Service
2. Python Generation Service uses → Templates (via Asciidoctor)
3. Python Generation Service outputs → Compliance Artifacts & Guidance Documents into build/
4. In parallel, docs/src content + build artifacts feed into → Static Site Generator → docs/public
5. CI/CD orchestrates: on push → run Python scripts → run Asciidoctor → run Astro build → publish

##### Architectural Patterns & Principles
- Separation of Concerns: data definitions vs. generation logic vs. presentation templates vs. docs portal.
- Extensibility Points: custom/rules and custom/sections allow new controls.
- Toolchain Isolation: Python for compliance logic, Ruby/Asciidoctor for doc assembly, Node/Astro for site.
- Declarative Data Driven: YAML-first approach for all controls & baselines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        includes["includes/"]:::data
        rules["rules/"]:::data
        sections["sections/"]:::data
        customrules["custom/rules/"]:::data
        customsections["custom/sections/"]:::data
        baselines["baselines/"]:::data
        docs_src["docs/src/"]:::data
    end

    %% Generation Layer
    subgraph "Generation Layer"
        direction TB
        PGS["Python Generation Service\n(scripts/*.py, Python 3)"]:::process
        TP["Asciidoctor Template Processor\n(Gemfile, templates/)"]:::process
        SSG["Static Site Generator\n(Astro, Node.js)"]:::process
    end

    %% Output Layer
    subgraph "Outputs"
        direction TB
        build["build/"]:::output
        docs_public["docs/public/"]:::output
    end

    %% CI/CD
    CI["CI/CD Pipeline\n(.github/workflows/build_documentation.yml)"]:::ci

    %% Flows
    includes --> PGS
    rules --> PGS
    sections --> PGS
    customrules --> PGS
    customsections --> PGS
    baselines --> PGS

    PGS --> build
    PGS --> TP
    TP --> build

    build --> SSG
    docs_src --> SSG
    SSG --> docs_public

    %% CI Orchestration
    CI --> PGS
    CI --> TP
    CI --> SSG

    %% Click Events
    click includes "https://github.com/usnistgov/macos_security/tree/main/includes/"
    click rules "https://github.com/usnistgov/macos_security/tree/main/rules/"
    click sections "https://github.com/usnistgov/macos_security/tree/main/sections/"
    click customrules "https://github.com/usnistgov/macos_security/tree/main/custom/rules/"
    click customsections "https://github.com/usnistgov/macos_security/tree/main/custom/sections/"
    click baselines "https://github.com/usnistgov/macos_security/tree/main/baselines/"
    click PGS "https://github.com/usnistgov/macos_security/blob/main/scripts/generate_baseline.py"
    click PGS "https://github.com/usnistgov/macos_security/blob/main/scripts/generate_scap.py"
    click PGS "https://github.com/usnistgov/macos_security/blob/main/scripts/generate_guidance.py"
    click PGS "https://github.com/usnistgov/macos_security/blob/main/scripts/generate_mapping.py"
    click PGS "https://github.com/usnistgov/macos_security/tree/main/scripts/util/"
    click TP "https://github.com/usnistgov/macos_security/tree/main/Gemfile"
    click TP "https://github.com/usnistgov/macos_security/tree/main/templates/"
    click build "https://github.com/usnistgov/macos_security/tree/main/build/"
    click docs_src "https://github.com/usnistgov/macos_security/tree/main/docs/src/"
    click docs_public "https://github.com/usnistgov/macos_security/tree/main/docs/public/"
    click SSG "https://github.com/usnistgov/macos_security/blob/main/docs/astro.config.mjs"
    click SSG "https://github.com/usnistgov/macos_security/blob/main/docs/package.json"
    click SSG "https://github.com/usnistgov/macos_security/blob/main/docs/pnpm-lock.yaml"
    click CI "https://github.com/usnistgov/macos_security/blob/main/.github/workflows/build_documentation.yml"

    %% Styles
    classDef data fill:#cce5ff,stroke:#00529B,color:#00529B
    classDef process fill:#d4edda,stroke:#2F6627,color:#2F6627
    classDef output fill:#fff3cd,stroke:#8A6D1B,color:#8A6D1B
    classDef ci fill:#f8d7da,stroke:#A94442,color:#A94442
```
