Getting Started

Decide which version to set up with, then follow the steps below.

mSCP 2.0

The newest version, runs in a container or locally (with dependencies), supports all macOS/iOS/visionOS versions in one place without switching branches.

mSCP 1.0

The stable release, runs locally (with dependencies), uses separate branches for each macOS/iOS/visionOS version and requires switching branches to change versions.

Setup

mSCP 2.0

Container (Recommended)

Requirements:

• A container solution is required:
  • Apple Container (Recommended)
  • Docker

1. Create Local Folders

   mkdir -p ~/Desktop/mscp/custom

   Anything placed in this custom folder overrides the project’s rules and is included in everything you generate. If you are reusing an existing folder, make sure its contents are customizations you intentionally added.

2. Run the Container

   Using Apple Container:

   container run -it \
     --volume ~/Desktop/mscp:/mscp/build \
     --volume ~/Desktop/mscp/custom:/mscp/custom \
     ghcr.io/usnistgov/mscp_2.0:latest

   Apple Container commands Click to expand

   Start the container service (required before first run):

   container system start

   Exit the container:

   exit

   Stop the container service:

   container system stop

   Check container service status:

   container system status

   Or Using Docker:

   # Note: Docker requires full paths for volume mounts
   docker run -it \
     --volume /Users/<username>/Desktop/mscp:/mscp/build \
     --volume /Users/<username>/Desktop/mscp/custom:/mscp/custom \
     ghcr.io/usnistgov/mscp_2.0:latest

3. Generate Content

   config/custom/baselines/cis_lvl1_macos_27.0.yaml

   # Create a baseline
   ./mscp.py baseline -k cis_lvl1
   # Generate guidance with all outputs
   ./mscp.py guidance custom/baselines/cis_lvl1_macos_27.0.yaml -A
   # Output: MSCP DOCUMENT GENERATION COMPLETE! All documents in: /build/cis_lvl1_macos_27.0/

Manual Method (Optional)

Manual setup with Python.

Requirements:

• Python >= 3.12
  • Recommended: Macadmins Python

No Ruby toolchain is required. Guidance documents are generated entirely in Python — PDF rendering uses typst, which installs as a regular Python dependency, so there is nothing extra to set up.

1. Clone the Repository

   git clone https://github.com/usnistgov/macos_security.git
   cd macos_security

   Verify your clone

   Confirm that what you have locally matches what the project is serving. The two hashes should be identical:

   # Your local commit
   git rev-parse HEAD
   
   # Current commit on the official repository
   git ls-remote https://github.com/usnistgov/macos_security refs/heads/main

   If they differ, your copy may be out of date or may have come from a fork or mirror. Run git pull, or re-clone from the URL above.

   Check your custom/ folder

   Anything in custom/ overrides the project’s rules and is included in everything you generate. A fresh clone contains no customizations, so if files are present, make sure they are ones you intentionally added.

2. Python Setup

   # Create virtual environment
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Update and install tools
   python3 -m pip install --upgrade pip setuptools wheel
   python3 -m pip install --upgrade -r requirements.txt

3. Generate Content

   # Create a baseline
   ./mscp.py baseline -k cis_lvl1
   
   # Generate guidance with all outputs
   ./mscp.py guidance custom/baselines/cis_lvl1_macos_27.0.yaml -A
   
   # When done, deactivate the virtual environment
   deactivate

mSCP 1.0

Always Use the Correct Branch

The main branch is now used for mSCP 2.0 and will generate content using the mSCP 2.0 methods. For mSCP 1.0, each macOS version has its own branch (sequoia, sonoma, ventura, etc.) — check out the branch that matches your target OS.

Requirements:

• Python >= 3.12.1 (3.14 is not supported)
  • Recommended: Macadmins Python
• Ruby (macOS built-in Ruby works — optional, for PDF output)

1. Clone the Repository

   git clone https://github.com/usnistgov/macos_security.git
   cd macos_security
   git checkout sequoia

   Replace sequoia with your target macOS version (sequoia, sonoma, ventura, etc.).

   Verify your clone

   Confirm that what you have locally matches what the project is serving. The two hashes should be identical:

   # Your local commit
   git rev-parse HEAD
   
   # Current commit on the official repository
   git ls-remote https://github.com/usnistgov/macos_security refs/heads/sequoia

   Replace sequoia with the branch you checked out. If they differ, your copy may be out of date or may have come from a fork or mirror. Run git pull, or re-clone from the URL above.

   Check your custom/ folder

   Anything in custom/ overrides the project’s rules and is included in everything you generate. A fresh clone contains no customizations, so if files are present, make sure they are ones you intentionally added.

   Prefer to download a ZIP? Click to expand

   1. Go to the GitHub repository
   2. Click the branch dropdown and select your macOS version
   3. Click Code → Download ZIP
   4. Extract and open the folder

   Note that a ZIP download cannot be verified with the git commands above. If you need to confirm your copy matches the project, use git clone instead.

2. Python Setup

   # Create virtual environment
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Install requirements
   pip3 install -r requirements.txt

   Having Python version issues? Click to expand

   Check your Python version:

   python3 --version

   Check version inside the venv:

   source .venv/bin/activate
   python --version

   List all installed Python versions:

   ls /opt/homebrew/bin/python3*
   ls /usr/local/bin/python3*

   Create venv with a specific version:

   # Remove old venv if needed
   rm -rf .venv
   
   # Use full path to the Python version you want
   /opt/homebrew/bin/python3.13 -m venv .venv
   source .venv/bin/activate

3. Ruby Setup (Optional — for PDF output)

   bundle install --binstubs --path mscp_gems

4. Verify Setup

   Run this command to confirm everything works:

   ./scripts/generate_baseline.py -l
   
   # When done, deactivate the virtual environment
   deactivate

   You should see a list of available baselines.

---

What You Can Do

With the project set up, you can:

• Generate baselines — Create YAML files for security frameworks (NIST, CIS, DISA STIG, etc.)
• Generate guidance — Produce HTML/PDF documentation for your baseline
• Create configuration profiles — Deploy settings via MDM
• Run compliance checks — Scan Macs against your baseline
• Customize rules — Tailor settings to your organization’s needs

---

Next Steps

Quick GuideStep-by-step workflow for generating security compliance files.

Or explore specific topics:

• How to Generate Baselines
• How to Generate Guidance
• How to Generate Configuration Profiles