Customize Rules

Customizing lets you modify rule content (check commands, fixes, references) or add entirely new rules. This is different from tailoring, which selects which rules to include and sets ODV values.

Tip

Only include fields you want to change in your custom rule file. The project automatically merges your customizations with the original rule, keeping your changes compatible across OS updates.

Always Use the Correct Branch (mSCP 1.0)

Each macOS version has its own branch (sequoia, sonoma, ventura, etc.). Never use the main branch — it won’t work for generating content.

mSCP 2.0 (currently in beta) will remove the per-branch requirement and introduce easier installation methods.

---

How Merging Works

When you create a custom rule file, the project:

1. Loads your custom version from custom/rules/
2. Loads the original rule from rules/
3. Uses your custom values where they differ
4. Keeps original values for fields you didn’t customize
5. Merges tags and references (concatenates rather than replaces)

---

Modify an Existing Rule

1. Create your custom rule file

   Create a YAML file in custom/rules/ with the same filename as the original rule.

2. Include only fields to customize

   Add only the fields you want to change:

   references:
     custom:
       MSCP:
         - MSCP-OS-001
       URL:
         - https://example.com/policy

3. Generate your outputs

   ./scripts/generate_guidance.py baselines/YOUR_BASELINE.yaml

   The custom values merge with the original rule automatically.

---

Add a New Rule

1. Create your rule file

   Create a new YAML file in custom/rules/ with your rule ID as the filename (e.g., my_org_custom_rule.yaml).

2. Define the required fields

   Field	Description
   id	Unique rule identifier
   title	Human-readable name
   discussion	Why this rule matters
   check	Command to verify compliance
   result	Expected output format
   fix	Remediation instructions
   tags	Include your baseline tag

3. Add payload support (if needed)

   If your rule uses a configuration profile payload not in the project, add it to includes/supported_payloads.yaml.

4. Generate your baseline

   ./scripts/generate_baseline.py -k YOUR_TAG

5. Generate your outputs

   ./scripts/generate_guidance.py baselines/YOUR_BASELINE.yaml

---

Informational Rules (No Check/Fix)

For rules that explain a control but don’t require compliance checking, use the manual tag. These rules appear in guidance documents but not in compliance scripts.

id: my_org_policy_statement
title: Organization Security Policy
discussion: |
  This control documents the organization's security policy requirements.
check: |
result: |
fix: |
tags:
  - manual
  - my_org_baseline

---

File Structure

• Directorycustom/

  • Directoryrules/

    • os_authenticated_root_enable.yaml - Override existing rule
    • my_org_custom_rule.yaml - New custom rule

---

Next Steps

• Tailoring Rules - Select rules and set ODV values
• Exempting Rules - Exclude rules from compliance checks