How To Generate Guidance

To generate guidance files (AsciiDoc, HTML, and PDF) from an existing baseline, use the generate_guidance.py script in the macos_security repository.

Note

The guidance information is generated directly from the baseline YAML file you created or selected. All recommendations, control details, and configuration steps in the guidance output are based on the contents of your chosen baseline.

• Directorymacos_security/

  • Directoryscripts/

    • generate_guidance.py ---> Script to generate guidance files
  • Directorybuild/

    • Directorybaselines/

      • BASELINENAME.yaml ---> Your generated or customized baseline file

Caution

Always use the branch matching your target OS version. Do not use the main branch for workflow or development.

1. Ensure You Are Using the Correct Baseline File

   • Use either a baseline you generated (custom baseline) or one of the built-in baselines provided by the project.

2. Run the Guidance Generation Script

   • Point the script to your baseline YAML file:

     ./scripts/generate_guidance.py build/baselines/BASELINENAME.yaml

     Replace BASELINENAME.yaml with your actual baseline file.

   • The script will generate AsciiDoc, HTML, and PDF guidance documents.

3. Locate the Generated Guidance Files

   • The output files will be created in a directory under build/ matching your baseline name, for example:

     • Directorymacos_security/

       • Directorybuild/

         • Directory800-53r5_moderate/

           • 800-53r5_moderate.adoc
           • 800-53r5_moderate.html
           • 800-53r5_moderate.pdf

Built-in Baseline vs Custom Baseline

When generating guidance, you can use either a built-in baseline or a custom baseline:

• Built-in Baseline:
  These are standard baseline YAML files provided by the project and located in the baselines/ directory. They represent default security configurations such as NIST 800-53, CIS, or STIG profiles.

  • Directorymacos_security/

    • Directorybaselines/

      • 800-53r5_moderate.yaml

  Example usage:

  ./scripts/generate_guidance.py baselines/800-53r5_moderate.yaml

  The output files will be generated in a directory under build/ matching the baseline name.

• Custom Baseline:
  These are baselines you have tailored for your organization, typically created using the baseline generation and tailoring scripts. Custom baseline files are usually found in build/baselines/.

  • Directorymacos_security/

    • Directorybuild/

      • Directorybaselines/

        • 800-53r5_moderate.yaml

  Example usage:

  ./scripts/generate_guidance.py build/baselines/800-53r5_moderate.yaml

  The output files will be generated in a directory under build/ matching your custom baseline.

Both approaches produce guidance files in AsciiDoc, HTML, and PDF formats, but custom baselines allow you to reflect organization-specific requirements and tailoring.

Example output files:

• Directorymacos_security/

  • Directorybuild/

    • Directory800-53r5_moderate/

      • 800-53r5_moderate.adoc
      • 800-53r5_moderate.html
      • 800-53r5_moderate.pdf