Merge pull request #692 from brodjieski/dev_2.0

Refactor with CLI enhancements and author templates

Author: robertgendler

schema/mscp_baseline.json

@@ -26,7 +26,8 @@
       "items": {
         "type": "object",
         "required": [
-          "name"
+          "name",
+          "organization"
         ],
         "additionalProperties": false,
         "properties": {
@@ -37,6 +38,10 @@
           "organization": {
             "type": "string",
             "description": "Organization the author is affiliated with"
+          },
+          "additional": {
+            "type": "boolean",
+            "description": "Author will be listed in addition to the primary MSCP contributors. Typically added as part of tailoring a baseline."
           }
         }
       }

schema/mscp_rule.json

@@ -421,7 +421,12 @@
                     "enum": [
                         "com.apple.configuration.services.configuration-files",
                         "com.apple.configuration.diskmanagement.settings",
-                        "com.apple.configuration.passcode.settings"
+                        "com.apple.configuration.passcode.settings",
+                        "com.apple.configuration.intelligence.settings",
+                        "com.apple.configuration.external-intelligence.settings",
+                        "com.apple.configuration.softwareupdate.settings",
+                        "com.apple.configuration.siri.settings",
+                        "com.apple.configuration.keyboard.settings"
                     ]
                 },
                 "service": {

src/mscp/classes/baseline.py

@@ -11,7 +11,7 @@
 # Standard python modules
 from collections import OrderedDict, defaultdict
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 # Additional python modules
 import pandas as pd
@@ -24,6 +24,7 @@
 
 __all__ = ["Author", "Profile", "Baseline"]
 
+
 class BaseModelWithAccessors(BaseModel):
     """Pydantic base class with dict-style accessors.
 
@@ -75,16 +76,30 @@ def __setitem__(self, key: str, value: Any) -> None:
 
 
 class Author(BaseModelWithAccessors):
-    """One author or owning organisation of a baseline.
+    """One author or owning organization of a baseline.
 
     Attributes:
         name (str | None): Personal name of the author, if available.
-        organization (str | None): Organisation the author represents, if
+        organization (str | None): Organization the author represents, if
             applicable.
     """
 
     name: str | None
     organization: str | None
+    additional: Optional[bool] = None
+
+    def is_additional(self) -> bool:
+        """Return true if this author is in addition to MSCP contributors.
+
+        This is a simple helper that checks the `additional` field, which
+        should be set to true for any author that is not a primary contributor
+        to MSCP. This allows generated guidance to flag such authors
+        and their contributions for special attention.
+
+        Returns:
+            bool: True when `additional` is true, false otherwise.
+        """
+        return self.additional is True
 
 
 class Profile(BaseModelWithAccessors):

src/mscp/cli.py

@@ -2,14 +2,15 @@
 """Command-line interface for mSCP.
 
 Defines `parse_cli`, the top-level entry point invoked from
-:mod:`mscp.__main__`. Builds an `argparse` tree with subcommands
-``baseline`` / ``guidance`` / ``mapping`` / ``scap`` / ``admin`` (the
+`mscp.__main__`. Builds an `argparse` tree with subcommands
+`baseline` / `guidance` / `mapping` / `scap` / `admin` (the
 last with its own nested utilities) and dispatches to the matching
 function in `mscp.generate` or `mscp.admin_utils`.
 """
 
 # Standard python modules
 import argparse
+import json
 import sys
 import platform
 from pathlib import Path
@@ -58,13 +59,61 @@ def error(self, message: str) -> None:
         sys.exit(2)
 
 
+class ListPlatformsAction(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        fmt = "human"
+        if "--format" in sys.argv:
+            idx = sys.argv.index("--format")
+            if idx + 1 < len(sys.argv):
+                fmt = sys.argv[idx + 1]
+
+        platforms = mscp_data.get("versions", {}).get("platforms", {})
+
+        if fmt == "json":
+            print(
+                json.dumps(
+                    {
+                        name: sorted((e["os_version"] for e in versions), reverse=True)
+                        for name, versions in platforms.items()
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            platform_versions = {
+                name: sorted((e["os_version"] for e in versions), reverse=True)
+                for name, versions in platforms.items()
+            }
+            col_width = max(len(name) for name in platform_versions) + 4
+            max_rows = max(len(v) for v in platform_versions.values())
+
+            print("Supported platforms (--os_name) and versions (--os_version):\n")
+            print("  " + "".join(name.ljust(col_width) for name in platform_versions))
+            print(
+                "  "
+                + "".join(
+                    ("-" * len(name)).ljust(col_width) for name in platform_versions
+                )
+            )
+            for i in range(max_rows):
+                print(
+                    "  "
+                    + "".join(
+                        (str(v[i]) if i < len(v) else "").ljust(col_width)
+                        for v in platform_versions.values()
+                    )
+                )
+            print()
+        parser.exit()
+
+
 class SmartFormatter(argparse.HelpFormatter):
     """Help formatter with two minor tweaks for the mSCP CLI.
 
     - Single-letter / single-form options are indented to align with the
       long-form options for readability.
-    - Help strings prefixed with ``"R|"`` are emitted with their original
-      newlines preserved (a common ``argparse`` recipe for raw text).
+    - Help strings prefixed with `"R|"` are emitted with their original
+      newlines preserved (a common `argparse` recipe for raw text).
     """
 
     def _format_action_invocation(self, action):
@@ -88,14 +137,13 @@ def _split_lines(self, text, width):
 def get_macos_version() -> float:
     """Return the running host's major macOS version as a float.
 
-    Used as the default for the ``--os_version`` flag so the CLI assumes
-    the current host's version unless overridden. Falls back to ``26.0``
+    Used as the default for the `--os_version` flag so the CLI assumes
+    the current host's version unless overridden. Falls back to `26.0`
     when `platform.mac_ver` returns an empty string (e.g. when run on a
     non-macOS host).
 
     Returns:
-        float: Major version (e.g. ``15.0``), or ``26.0`` on a non-macOS
-            host.
+        float: Major version (e.g. `15.0`), or `26.0` on a non-macOS host.
     """
     version_str, _, _ = platform.mac_ver()
     if version_str:
@@ -106,9 +154,9 @@ def get_macos_version() -> float:
 
 
 def validate_file(arg: str) -> Path | None:
-    """`argparse` type validator: ensure ``arg`` points at an existing file.
+    """`argparse` type validator: ensure `arg` points at an existing file.
 
-    Used as the ``type=`` argument on flags that take a path. Logs an
+    Used as the `type=` argument on flags that take a path. Logs an
     error and calls `sys.exit` if the path doesn't resolve to a file.
 
     Args:
@@ -128,16 +176,16 @@ def validate_file(arg: str) -> Path | None:
 def parse_cli() -> None:
     """Build the mSCP argument parser, parse `sys.argv`, and dispatch.
 
-    Constructs the top-level parser plus the ``baseline``, ``guidance``,
-    ``mapping``, ``scap``, and ``admin`` subcommands (each with its own
+    Constructs the top-level parser plus the `baseline`, `guidance`,
+    `mapping`, `scap`, and `admin` subcommands (each with its own
     flags), applies log-verbosity overrides, validates the platform/OS
     arguments (rejects unsupported macOS / iOS versions), and then calls
-    the subcommand's bound ``func`` with the parsed `argparse.Namespace`.
+    the subcommand's bound `func` with the parsed `argparse.Namespace`.
 
-    Side Effects:
-        Reads ``sys.argv``; configures the global mSCP logger;
-        mutates the global `config` dict for ``output_dir`` / ``rules_dir``;
-        may call `sys.exit` on validation failure.
+    Note:
+        Reads `sys.argv`; configures the global mSCP logger; mutates the
+        global `config` dict for `output_dir` / `rules_dir`; may call
+        `sys.exit` on validation failure.
     """
     parent_parser = Customparser()
     parent_parser.add_argument(
@@ -172,9 +220,23 @@ def parse_cli() -> None:
         version=f"%(prog)s {_v.get('version', 'unknown')} (build {_v.get('build', '?')}, {_v.get('build_date', 'unknown')})",
     )
 
+    parser.add_argument(
+        "--list_platforms",
+        nargs=0,
+        action=ListPlatformsAction,
+        help="list all supported platforms and versions",
+    )
+
+    parser.add_argument(
+        "--format",
+        choices=["human", "json"],
+        default="human",
+        help="output format for --list_platforms",
+    )
+
     parser.add_argument(
         "--os_name",
-        choices=["macos", "ios", "visionos"],
+        choices=mscp_data.get("versions", {}).get("platforms", {}),
         default="macos",
         help="operating system to be referenced when generating guidance",
         type=str,
@@ -187,6 +249,15 @@ def parse_cli() -> None:
         help="version of the operating system to be referenced when generating guidance (eg: 14.0, 15.0).",
     )
 
+    parser.add_argument(
+        "-C",
+        "--custom_dir",
+        default=config["custom_dir"],
+        type=Path,
+        metavar="PATH",
+        help="Path to custom directory.",
+    )
+
     parser.add_argument(
         "-R",
         "--rules_dir",
@@ -221,6 +292,15 @@ def parse_cli() -> None:
     )
     baseline_parser.set_defaults(func=generate_baseline)
 
+    baseline_parser.add_argument(
+        "-b",
+        "--baseline",
+        type=validate_file,
+        help=argparse.SUPPRESS,
+        # help="when tailoring, if you provide a baseline.yaml file, it will only prompt for rules not already included",
+        action="store",
+    )
+
     baseline_parser.add_argument(
         "-c",
         "--controls",
@@ -342,12 +422,14 @@ def parse_cli() -> None:
         help="generate the compliance script for the rules in the specified baseline",
         action="store_true",
     )
+
     guidance_parser.add_argument(
         "--audit_name",
         default=None,
         help="specify the name of audit plist and log (defaults to baseline name)",
         action="store",
     )
+
     guidance_parser.add_argument(
         "--reference",
         default=None,
@@ -610,6 +692,8 @@ def parse_cli() -> None:
 
         if args.output_dir:
             config["output_dir"] = str(args.output_dir.expanduser().resolve())
+        if args.custom_dir:
+            config["custom_dir"] = str(args.custom_dir.expanduser().resolve())
     except argparse.ArgumentError as e:
         logger.error("Argument Error: {}", e)
         parser.print_help()

src/mscp/common_utils/version_data.py

@@ -12,7 +12,16 @@
 # Local python modules
 from .logger_instance import logger
 
-# Additional python modules
+OS_NAME_MAP = {
+    "tahoe": "Tahoe",
+    "sequoia": "Sequoia",
+    "sonoma": "Sonoma",
+    "ventura": "Ventura",
+    "ios_26": "iOS 26",
+    "ios_18": "iOS 18",
+    "ios_17": "iOS 17",
+    "visionos_26": "VisionOS 26",
+}
 
 
 def get_version_data(
@@ -54,7 +63,11 @@ def get_version_data(
 
         valid_versions = [e.get("os_version") for e in platforms[os_name.lower()]]
         match = next(
-            (e for e in platforms[os_name.lower()] if e.get("os_version") == os_version),
+            (
+                e
+                for e in platforms[os_name.lower()]
+                if e.get("os_version") == os_version
+            ),
             None,
         )
 
@@ -63,6 +76,10 @@ def get_version_data(
                 f"Unknown os_version {os_version!r} for {os_name!r}. "
                 f"Valid versions: {valid_versions}"
             )
+        else:
+            match["compliance_version"] = (
+                f"{OS_NAME_MAP.get(match['os_name'].lower(), match['os_name'])} Guidance, Revision {match['revision']}"
+            )
 
         return match