usnistgov/macos_security
1
0
Fork 0
mirror of https://github.com/usnistgov/macos_security.git synced 2026-02-03 05:53:24 +00:00
Code Issues 21 Actions Packages Projects Releases Wiki Activity

Merge pull request #625 from cocopuff2u/nist-pages-docs

Browse Source 
Updated Installation Documentation for mSCP 2.0 and Getting Started
This commit is contained in:
Bob Gendler
2026-01-15 15:32:50 -05:00
committed by GitHub
parent 045f7758f9 9a28b0d5eb
commit af43b1d47c
2 changed files with 230 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
src/content/docs/mscp-2/overview.mdx
View File

@@ -138,42 +138,192 @@ macos_security/
For testing only. Requirements may change before release.
</Aside>
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
<Steps>
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 .
```
<details>
<summary>**Want isolated installs?** Click to expand</summary>
<summary>**Having Python version issues?** Click to expand</summary>
**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
```
</details>
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
```
</Steps>
---
### 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/)
<Steps>
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
```
<details>
<summary>**Apple Container commands** Click to expand</summary>
**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
```
</details>
**Or Using Docker:**
```bash
# 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/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/
```
</Steps>
---
### 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
<Steps>
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
```
</Steps>
---

110
src/content/docs/welcome/getting-started.mdx
View File

@@ -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)
<Steps>
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
```
<details>
<summary>**Want isolated installs?** Click to expand</summary>
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
```
</details>
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.).
<details>
<summary>**Prefer to download a ZIP?** Click to expand</summary>
**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
</details>
2. ### Python Setup
```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install requirements
pip3 install -r requirements.txt
```
<details>
<summary>**Having Python version issues?** Click to expand</summary>
**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
```
</details>
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.