diff --git a/src/content/docs/mscp-2/overview.mdx b/src/content/docs/mscp-2/overview.mdx index 2ec2a1c9..746f7d31 100644 --- a/src/content/docs/mscp-2/overview.mdx +++ b/src/content/docs/mscp-2/overview.mdx @@ -138,42 +138,192 @@ macos_security/ For testing only. Requirements may change before release. +There are three ways to run mSCP 2.0. Choose the method that works best for your environment. + +### Option 1: Python + Ruby + +Manual setup with virtual environment. + +**Requirements:** +- Python >= 3.12.1 (3.14 is not supported) + - Recommended: [Macadmins Python](https://github.com/macadmins/python) +- Ruby >= 3.4.4 + -1. ### Clone the dev_2.0 Branch +1. ### Clone the Repository ```bash git clone -b dev_2.0 https://github.com/usnistgov/macos_security.git cd macos_security ``` -2. ### Install Prerequisites +2. ### Python Setup - Requires Python 3.12.1 or higher. - - **Python packages (required):** ```bash - pip3 install -r requirements.txt - ``` + # Create virtual environment + python3 -m venv .venv + source .venv/bin/activate - **Ruby gems (optional — only needed for PDF output):** - ```bash - gem install asciidoctor asciidoctor-pdf rouge --user-install + # Install requirements + python3 -m pip install . ```
- **Want isolated installs?** Click to expand + **Having Python version issues?** Click to expand - **Python virtual environment:** + **Check your Python version:** + ```bash + python3 --version + ``` + + **Check version inside the venv:** ```bash - python3 -m venv .venv source .venv/bin/activate - pip3 install -r requirements.txt - deactivate # when done + python --version + ``` + + **List all installed Python versions:** + ```bash + ls /opt/homebrew/bin/python3* + ls /usr/local/bin/python3* + ``` + + **Create venv with a specific version:** + ```bash + # 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 + + ```bash + bundle install --binstubs --path mscp_gems + ``` + +4. ### Generate Content + + ```bash + # Create a baseline + ./mscp.py baseline -k cis_lvl1 + + # Generate guidance with all outputs + ./mscp.py guidance custom/baselines/cis_lvl1_macos_26.0.yaml -A + + # When done, deactivate the virtual environment + deactivate + ``` + + + +--- + +### Option 2: Container + +The easiest way to get started — no local dependencies required. + +**Requirements:** +- [Apple Container](https://github.com/apple/container) or [Docker](https://www.docker.com/) + + + +1. ### Create Local Folders + + ```bash + mkdir -p ~/Desktop/mscp/custom + ``` + +2. ### Run the Container + + **Using Apple Container:** + ```bash + container run -it \ + --volume ~/Desktop/mscp:/mscp/build \ + --volume ~/Desktop/mscp/custom:/mscp/custom \ + ghcr.io/brodjieski/mscp_2.0:latest + ``` + +
+ **Apple Container commands** Click to expand + + **Start the container service (required before first run):** + ```bash + container system start + ``` + + **Exit the container:** + ```bash + exit + ``` + + **Stop the container service:** + ```bash + container system stop + ``` + + **Check container service status:** + ```bash + container system status + ``` + +
+ + **Or Using Docker:** + ```bash + # Note: Docker requires full paths for volume mounts + docker run -it \ + --volume /Users//Desktop/mscp:/mscp/build \ + --volume /Users//Desktop/mscp/custom:/mscp/custom \ + ghcr.io/brodjieski/mscp_2.0:latest + ``` + +3. ### Generate Content + + ```bash + # Create a baseline + ./mscp.py baseline -k cis_lvl1 + # Output: Generated new baseline file: config/custom/baselines/cis_lvl1_macos_26.0.yaml + + # Generate guidance with all outputs + ./mscp.py guidance custom/baselines/cis_lvl1_macos_26.0.yaml -A + # Output: MSCP DOCUMENT GENERATION COMPLETE! All documents in: /build/cis_lvl1_macos_26.0/ + ``` + + + +--- + +### Option 3: UV Workflow + +A fast, modern Python workflow using [uv](https://docs.astral.sh/uv/getting-started/installation/). + +**Requirements:** +- [uv](https://docs.astral.sh/uv/getting-started/installation/) +- Ruby + + + +1. ### Clone and Setup + + ```bash + git clone https://github.com/usnistgov/macos_security.git + cd macos_security + git checkout dev_2.0 + bundle install --binstubs --path mscp_gems + ``` + +2. ### Run Commands + + ```bash + uv run --python 3.13 mscp.py guidance config/default/baselines/macos/15/cis_lvl1.yaml + ``` + --- diff --git a/src/content/docs/welcome/getting-started.mdx b/src/content/docs/welcome/getting-started.mdx index bf34a305..734b4b23 100644 --- a/src/content/docs/welcome/getting-started.mdx +++ b/src/content/docs/welcome/getting-started.mdx @@ -20,69 +20,89 @@ Each macOS version has its own branch (`sequoia`, `sonoma`, `ventura`, etc.). ## Setup +**Requirements:** +- Python >= 3.12.1 (3.14 is not supported) + - Recommended: [Macadmins Python](https://github.com/macadmins/python) +- Ruby >= 3.4.4 (optional — for PDF output) + -1. ### Install Python Packages +1. ### Clone the Repository - macOS includes Python 3. Just install the required packages: - - ```bash - pip3 install pyyaml xlwt --user - ``` - - **Optional** — for PDF output, also install Ruby gems: - ```bash - gem install asciidoctor asciidoctor-pdf rouge --user-install - ``` - -
- **Want isolated installs?** Click to expand - - A **virtual environment** keeps packages separate from your system Python — useful if you don't want to install packages globally or need to avoid conflicts. - - **Python virtual environment:** - ```bash - # Create environment (once) - python3 -m venv venv - - # Activate before running scripts - source venv/bin/activate - - # Install packages inside the environment - pip3 install -r requirements.txt - - # When done, deactivate - deactivate - ``` - - **Ruby local bundle:** - ```bash - bundle install --path vendor/bundle - ``` - -
- -2. ### Get the Repository - - **Option A: Clone with Git** (recommended) ```bash git clone https://github.com/usnistgov/macos_security.git cd macos_security git checkout sequoia ``` - Replace `sequoia` with your target macOS version. + Replace `sequoia` with your target macOS version (`sequoia`, `sonoma`, `ventura`, etc.). + +
+ **Prefer to download a ZIP?** Click to expand - **Option B: Download ZIP** 1. Go to the [GitHub repository](https://github.com/usnistgov/macos_security) 2. Click the branch dropdown and select your macOS version 3. Click **Code** → **Download ZIP** 4. Extract and open the folder -3. ### Verify Setup +
+ +2. ### Python Setup + + ```bash + # 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:** + ```bash + python3 --version + ``` + + **Check version inside the venv:** + ```bash + source .venv/bin/activate + python --version + ``` + + **List all installed Python versions:** + ```bash + ls /opt/homebrew/bin/python3* + ls /usr/local/bin/python3* + ``` + + **Create venv with a specific version:** + ```bash + # 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) + + ```bash + bundle install --binstubs --path mscp_gems + ``` + +4. ### Verify Setup Run this command to confirm everything works: ```bash ./scripts/generate_baseline.py -l + + # When done, deactivate the virtual environment + deactivate ``` You should see a list of available baselines.