How usnistgov/macos_security works
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.