Customizing 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.

---

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 (concatenates), references (updates), and platforms (merges) rather than replacing

---

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:

   discussion: Customized discussion
   references:
     custom:
       CIO_Policy: refID-123
   tags:
     - CIO_Policy

3. Generate your outputs (see command below)

   mSCP 2.0

   ./mscp.py guidance custom/baselines/YOUR_BASELINE.yaml

   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.

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

   The custom values merge with the original rule automatically.

---

Add a New Rule

mSCP 2.0

1. Create your rule file

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

   New rule files must be placed in a section subfolder in order for mSCP to see them correctly.

2. Define the required fields

   There are a number of required fields in order for mSCP to recognize a valid rule file.

   Field	Description
   id	Unique rule identifier
   title	Human-readable name
   discussion	Why this rule matters
   references	References to policy documents
   references.nise.cce	This field is required, but can be a blank dictionary ‘{}’
   platforms	Platform specific information
   platforms.<OS>	OS can be macOS, iOS, visionOS
   platforms.<OS>.<VERSION>	Version should be in the form of ‘27.0’, this can be a blank dictionary ‘{}’
   tags	Include your baseline tag

3. Validate the rule files

   This command will review all of the rule yaml files in the mSCP library and any found in the custom folders.

   # Validate Rules
   ./mscp.py admin validate

4. Generate your baseline and outputs

   # Generate baseline
   ./mscp.py baseline -k YOUR_TAG
   
   # Generate outputs
   ./mscp.py guidance custom/baselines/YOUR_BASELINE.yaml

Basic rule file structure

id: my_org_policy_statement
title: Organization Security Policy
discussion: |
  This control documents the organization's security policy requirements.
references:
  nist:
    cce: {}
platforms:
  macOS:
    '27.0': {}
tags:
  - my_org_baseline

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.

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 your rule uses a configuration profile payload not in the project, add it to includes/supported_payloads.yaml.

4. Generate your baseline and outputs

   # Generate baseline
   ./scripts/generate_baseline.py -k YOUR_TAG
   
   # Generate 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 do not get evaluated in compliance scripts.

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

---

File Structure

• Directorycustom/

  • Directoryrules/

    • Directoryos/ - Section folder for new custom rule

      • os_my_org_custom_rule.yaml - New custom rule
    • Directorysystemsettings/ - Section folder for new custom rule

      • system_settings_org_custom_rule.yaml - New custom rule
    • icloud_drive_disable.yaml - Override existing rule
    • os_authenticated_root_enable.yaml - Override existing rule

---

Next Steps

• Tailoring Rules - Select rules and set ODV values