Merge branch 'main' into feature/reorder-base-class-mixins

# Conflicts:
#	src/ssvc/decision_points/base.py
#	src/test/test_mixins.py

Author: ahouseholder

.github/workflows/lint_md_changes.yml

@@ -16,7 +16,7 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: tj-actions/changed-files@v45
+    - uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32
       id: changed-files
       with:
         files: '**/*.md'

.github/workflows/python-app.yml

@@ -21,10 +21,10 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-tags: true
-    - name: Set up Python 3.10
+    - name: Set up Python 3.12
       uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.12"
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

data/schema/v1/Decision_Point-1-0-1.schema.json

@@ -47,9 +47,9 @@
 		},
 		"namespace": {
 		    "type": "string",
-		    "description": "Namespace (a short, unique string): For example, \"ssvc\" or \"cvss\" to indicate the source of the decision point. See SSVC Documentation for details.",
-		    "pattern": "^[a-z0-9-]{3,4}[a-z0-9/\\.-]*$",
-		    "examples": ["ssvc", "cvss", "ssvc-jp", "ssvc/acme", "ssvc/example.com"]
+		    "description": "Namespace (a short, unique string): The value must be one of the official namespaces, currenlty \"ssvc\", \"cvss\" OR can start with 'x_' for private namespaces. See SSVC Documentation for details.",
+		    "pattern": "^(?=.{3,25}$)(x_)?[a-z0-9]{3}([/.-]?[a-z0-9]+){0,22}$",
+		    "examples": ["ssvc", "cvss", "x_custom","x_custom/extension"]
 		},
 		"version": {
 		    "type": "string",

docs/reference/code/index.md

@@ -6,4 +6,5 @@ These include:
 - [CSV Analyzer](analyze_csv.md)
 - [Policy Generator](policy_generator.md)
 - [Outcomes](outcomes.md)
+- [Namespaces](namespaces.md)
 - [Doctools](doctools.md)

docs/reference/code/namespaces.md

@@ -0,0 +1,3 @@
+# SSVC Namespaces
+
+::: ssvc.namespaces

mkdocs.yml

@@ -112,6 +112,7 @@ nav:
         - CSV Analyzer: 'reference/code/analyze_csv.md'
         - Policy Generator: 'reference/code/policy_generator.md'
         - Outcomes: 'reference/code/outcomes.md'
+        - Namespaces: 'reference/code/namespaces.md'
         - Doctools: 'reference/code/doctools.md'
   - Calculator: 'ssvc-calc/index.md'
   - About:

src/ssvc/_mixins.py

@@ -17,9 +17,10 @@
 
 from typing import Optional
 
-from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 from semver import Version
 
+from ssvc.namespaces import NS_PATTERN, NameSpace
 from . import _schemaVersion
 
 
@@ -33,7 +34,7 @@ class _Versioned(BaseModel):
 
     @field_validator("version")
     @classmethod
-    def validate_version(cls, value):
+    def validate_version(cls, value: str) -> str:
         """
         Validate the version field.
         Args:
@@ -54,7 +55,29 @@ class _Namespaced(BaseModel):
     Mixin class for namespaced SSVC objects.
     """
 
-    namespace: str = "ssvc"
+    # the field definition enforces the pattern for namespaces
+    # additional validation is performed in the field_validator immediately after the pattern check
+    namespace: str = Field(pattern=NS_PATTERN, min_length=3, max_length=25)
+
+    @field_validator("namespace", mode="before")
+    @classmethod
+    def validate_namespace(cls, value: str) -> str:
+        """
+        Validate the namespace field.
+        The value will have already been checked against the pattern in the field definition.
+        The value must be one of the official namespaces or start with 'x_'.
+
+        Args:
+            value: a string representing a namespace
+
+        Returns:
+            the validated namespace value
+
+        Raises:
+            ValueError: if the value is not a valid namespace
+        """
+
+        return NameSpace.validate(value)
 
 
 class _Keyed(BaseModel):

src/ssvc/decision_points/base.py

@@ -21,6 +21,7 @@
 from pydantic import BaseModel
 
 from ssvc._mixins import _Base, _Keyed, _Namespaced, _Valued, _Versioned
+from ssvc.namespaces import NameSpace
 
 logger = logging.getLogger(__name__)
 
@@ -66,8 +67,15 @@ class SsvcDecisionPoint(_Valued, _Keyed, _Versioned, _Namespaced, _Base, BaseMod
     Models a single decision point as a list of values.
     """
 
+    namespace: str = NameSpace.SSVC
     values: tuple[SsvcDecisionPointValue, ...]
 
+    def __iter__(self):
+        """
+        Allow iteration over the decision points in the group.
+        """
+        return iter(self.values)
+
     def __init__(self, **data):
         super().__init__(**data)
         register(self)

src/ssvc/decision_points/cvss/base.py

@@ -18,11 +18,12 @@
 from pydantic import BaseModel
 
 from ssvc.decision_points.base import SsvcDecisionPoint
+from ssvc.namespaces import NameSpace
 
 
 class CvssDecisionPoint(SsvcDecisionPoint, BaseModel):
     """
     Models a single CVSS decision point as a list of values.
     """
 
-    namespace: str = "cvss"
+    namespace: NameSpace = NameSpace.CVSS

src/ssvc/namespaces.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python
+"""
+SSVC objects use namespaces to distinguish between objects that arise from different
+stakeholders or analytical category sources. This module defines the official namespaces
+for SSVC and provides a method to validate namespace values.
+"""
+#  Copyright (c) 2025 Carnegie Mellon University and Contributors.
+#  - see Contributors.md for a full list of Contributors
+#  - see ContributionInstructions.md for information on how you can Contribute to this project
+#  Stakeholder Specific Vulnerability Categorization (SSVC) is
+#  licensed under a MIT (SEI)-style license, please see LICENSE.md distributed
+#  with this Software or contact permission@sei.cmu.edu for full terms.
+#  Created, in part, with funding and support from the United States Government
+#  (see Acknowledgments file). This program may include and/or can make use of
+#  certain third party source code, object code, documentation and other files
+#  (“Third Party Software”). See LICENSE.md for more details.
+#  Carnegie Mellon®, CERT® and CERT Coordination Center® are registered in the
+#  U.S. Patent and Trademark Office by Carnegie Mellon University
+
+import re
+from enum import StrEnum, auto
+
+X_PFX = "x_"
+"""The prefix for extension namespaces. Extension namespaces must start with this prefix."""
+
+# pattern to match
+# `(?=.{3,25}$)`: 3-25 characters long
+# `^(x_)`: `x_` prefix is optional
+# `[a-z0-9]{3,4}`:  must start with 3-4 alphanumeric characters
+# `[/.-]?`: only one punctuation character is allowed between alphanumeric characters
+# `[a-z0-9]+`: at least one alphanumeric character is required after the punctuation character
+# `([/.-]?[a-z0-9]+){0,22}`: zero to 22 occurrences of the punctuation character followed by at least one alphanumeric character
+# (note that the total limit will kick in at or before this point)
+# `$`: end of the string
+NS_PATTERN = re.compile(r"^(?=.{3,25}$)(x_)?[a-z0-9]{3}([/.-]?[a-z0-9]+){0,22}$")
+"""The regular expression pattern for validating namespaces.
+
+Note: 
+    Namespace values must 
+    
+    - be 3-25 characters long
+    - contain only lowercase alphanumeric characters and limited punctuation characters (`/`,`.` and `-`)
+    - have only one punctuation character in a row
+    - start with 3-4 alphanumeric characters after the optional extension prefix
+    - end with an alphanumeric character
+    
+    See examples in the `NameSpace` enum.
+"""
+
+
+class NameSpace(StrEnum):
+    """
+    Defines the official namespaces for SSVC.
+
+    The namespace value must be one of the members of this enum or start with the prefix specified in X_PFX.
+    Namespaces must be 3-25 lowercase characters long and must start with 3-4 alphanumeric characters after the optional prefix.
+    Limited punctuation characters (/.-) are allowed between alphanumeric characters, but only one at a time.
+
+    Example:
+        Following are examples of valid and invalid namespace values:
+
+        - `ssvc` is *valid* because it is present in the enum
+        - `custom` is *invalid* because it does not start with the experimental prefix and is not in the enum
+        - `x_custom` is *valid* because it starts with the experimental prefix and meets the pattern requirements
+        - `x_custom/extension` is *valid* because it starts with the experimental prefix and meets the pattern requirements
+        - `x_custom/extension/with/multiple/segments` is *invalid* because it exceeds the maximum length
+        - `x_custom//extension` is *invalid* because it has multiple punctuation characters in a row
+        - `x_custom.extension.` is *invalid* because it does not end with an alphanumeric character
+        - `x_custom.extension.9` is *valid* because it meets the pattern requirements
+    """
+
+    # auto() is used to automatically assign values to the members.
+    # when used in a StrEnum, auto() assigns the lowercase name of the member as the value
+    SSVC = auto()
+    CVSS = auto()
+
+    @classmethod
+    def validate(cls, value: str) -> str:
+        """
+        Validate the namespace value. Valid values are members of the enum or start with the experimental prefix and
+        meet the specified pattern requirements.
+
+        Args:
+            value: the namespace value to validate
+
+        Returns:
+            the validated namespace value
+
+        Raises:
+            ValueError: if the value is not a valid namespace
+
+        """
+        if value in cls.__members__.values():
+            return value
+        if value.startswith(X_PFX) and NS_PATTERN.match(value):
+            return value
+        raise ValueError(
+            f"Invalid namespace: {value}. Must be one of {[ns.value for ns in cls]} or start with '{X_PFX}'."
+        )
+
+
+def main():
+    for ns in NameSpace:
+        print(ns)
+
+
+if __name__ == "__main__":
+    main()