regscale-cli 6.25.1.0__py3-none-any.whl → 6.26.0.0__py3-none-any.whl

regscale/integrations/control_matcher.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Control Matcher - A utility class for identifying and matching control implementations
+across different RegScale entities based on control ID strings.
+"""
+
+import logging
+import re
+from typing import Dict, List, Optional, Tuple, Union
+
+from regscale.core.app.api import Api
+from regscale.core.app.application import Application
+from regscale.models.regscale_models.control_implementation import ControlImplementation
+from regscale.models.regscale_models.security_control import SecurityControl
+
+logger = logging.getLogger("regscale")
+
+
+class ControlMatcher:
+    """
+    A class to identify control IDs and match them across different RegScale entities.
+
+    This class provides control matching capabilities:
+    - Parse control ID strings to extract NIST control identifiers
+    - Match controls from catalogs to security plans
+    - Find control implementations based on control IDs
+    - Support multiple control ID formats (e.g., AC-1, AC-1(1), AC-1.1)
+
+    Note: This class is focused on finding and matching existing controls only.
+    Control creation/modification should be handled by calling code.
+    """
+
+    def __init__(self, app: Optional[Application] = None):
+        """
+        Initialize the ControlMatcher.
+
+        :param Optional[Application] app: RegScale Application instance
+        """
+        self.app = app or Application()
+        self.api = Api()
+        self._catalog_cache: Dict[int, List[SecurityControl]] = {}
+        self._control_impl_cache: Dict[Tuple[int, str], Dict[str, ControlImplementation]] = {}
+
+    def parse_control_id(self, control_string: str) -> Optional[str]:
+        """
+        Parse a control ID string and extract the standardized control identifier.
+
+        Handles various formats:
+        - NIST format: AC-1, AC-1(1), AC-1.1
+        - With leading zeros: AC-01, AC-17(02)
+        - With text: "Access Control AC-1"
+        - Multiple controls: "AC-1, AC-2"
+
+        :param str control_string: Raw control ID string
+        :return: Standardized control ID or None if not found
+        :rtype: Optional[str]
+        """
+        if not control_string:
+            return None
+
+        # Clean the string
+        control_string = control_string.strip().upper()
+
+        # Common NIST control ID pattern
+        # Matches: AC-1, AC-01, AC-1(1), AC-1(01), AC-1.1, AC-1.01, etc.
+        pattern = r"([A-Z]{2,3}-\d+(?:\(\d+\)|\.\d+)?)"
+
+        matches = re.findall(pattern, control_string)
+        if matches:
+            # Normalize parentheses to dots for consistency
+            control_id = matches[0]
+            control_id = control_id.replace("(", ".").replace(")", "")
+            return control_id
+
+        return None
+
+    def find_control_in_catalog(self, control_id: str, catalog_id: int) -> Optional[SecurityControl]:
+        """
+        Find a security control in a specific catalog by control ID.
+
+        :param str control_id: The control ID to search for
+        :param int catalog_id: The catalog ID to search in
+        :return: SecurityControl object if found, None otherwise
+        :rtype: Optional[SecurityControl]
+        """
+        controls = self._get_catalog_controls(catalog_id)
+
+        # Generate all possible variations of the control ID
+        search_ids = self._get_control_id_variations(control_id)
+
+        # Try exact match with any variation
+        for control in controls:
+            if control.controlId in search_ids:
+                return control
+
+        # Try matching control variations against search variations
+        for control in controls:
+            control_variations = self._get_control_id_variations(control.controlId)
+            if control_variations & search_ids:  # Set intersection
+                return control
+
+        return None
+
+    def find_control_implementation(
+        self, control_id: str, parent_id: int, parent_module: str = "securityplans", catalog_id: Optional[int] = None
+    ) -> Optional[ControlImplementation]:
+        """
+        Find a control implementation based on control ID and parent context.
+
+        :param str control_id: The control ID to match
+        :param int parent_id: Parent entity ID (e.g., security plan ID)
+        :param str parent_module: Parent module type (default: securityplans)
+        :param Optional[int] catalog_id: Optional catalog ID for better matching
+        :return: ControlImplementation if found, None otherwise
+        :rtype: Optional[ControlImplementation]
+        """
+        # Get control implementations for the parent
+        implementations = self._get_control_implementations(parent_id, parent_module)
+
+        # Get all variations of the control ID for matching
+        search_variations = self._get_control_id_variations(control_id)
+        if not search_variations:
+            logger.warning(f"Could not parse control ID: {control_id}")
+            return None
+
+        # Try to find matching implementation with variation matching
+        for impl_key, impl in implementations.items():
+            impl_variations = self._get_control_id_variations(impl_key)
+            if impl_variations & search_variations:  # Set intersection
+                return impl
+
+        # If catalog ID provided, try to find via security control
+        if catalog_id:
+            control = self.find_control_in_catalog(control_id, catalog_id)
+            if control:
+                # Search implementations by control ID
+                for impl in implementations.values():
+                    if impl.controlID == control.id:
+                        return impl
+
+        return None
+
+    def match_controls_to_implementations(
+        self,
+        control_ids: List[str],
+        parent_id: int,
+        parent_module: str = "securityplans",
+        catalog_id: Optional[int] = None,
+    ) -> Dict[str, Optional[ControlImplementation]]:
+        """
+        Match multiple control IDs to their implementations.
+
+        :param List[str] control_ids: List of control ID strings
+        :param int parent_id: Parent entity ID
+        :param str parent_module: Parent module type
+        :param Optional[int] catalog_id: Optional catalog ID
+        :return: Dictionary mapping control IDs to implementations
+        :rtype: Dict[str, Optional[ControlImplementation]]
+        """
+        results = {}
+
+        for control_id in control_ids:
+            impl = self.find_control_implementation(control_id, parent_id, parent_module, catalog_id)
+            results[control_id] = impl
+
+        return results
+
+    def get_security_plan_controls(self, security_plan_id: int) -> Dict[str, ControlImplementation]:
+        """
+        Get all control implementations for a security plan.
+
+        :param int security_plan_id: The security plan ID
+        :return: Dictionary of control implementations keyed by control ID
+        :rtype: Dict[str, ControlImplementation]
+        """
+        return self._get_control_implementations(security_plan_id, "securityplans")
+
+    def find_controls_by_pattern(self, pattern: str, catalog_id: int) -> List[SecurityControl]:
+        """
+        Find all controls in a catalog matching a pattern.
+
+        :param str pattern: Regex pattern or substring to match
+        :param int catalog_id: Catalog ID to search in
+        :return: List of matching SecurityControl objects
+        :rtype: List[SecurityControl]
+        """
+        controls = self._get_catalog_controls(catalog_id)
+        matched = []
+
+        for control in controls:
+            if (re.search(pattern, control.controlId, re.IGNORECASE)) or (
+                control.title and re.search(pattern, control.title, re.IGNORECASE)
+            ):
+                matched.append(control)
+
+        return matched
+
+    def bulk_match_controls(
+        self,
+        control_mappings: Dict[str, str],
+        parent_id: int,
+        parent_module: str = "securityplans",
+        catalog_id: Optional[int] = None,
+    ) -> Dict[str, Optional[ControlImplementation]]:
+        """
+        Bulk match control IDs to their implementations.
+
+        :param Dict[str, str] control_mappings: Dict of {external_id: control_id}
+        :param int parent_id: Parent entity ID
+        :param str parent_module: Parent module type
+        :param Optional[int] catalog_id: Catalog ID for controls
+        :return: Dictionary mapping external IDs to ControlImplementations (None if not found)
+        :rtype: Dict[str, Optional[ControlImplementation]]
+        """
+        results = {}
+
+        for external_id, control_id in control_mappings.items():
+            impl = self.find_control_implementation(control_id, parent_id, parent_module, catalog_id)
+            results[external_id] = impl
+
+        return results
+
+    def _get_catalog_controls(self, catalog_id: int) -> List[SecurityControl]:
+        """
+        Get all controls for a catalog (with caching).
+
+        :param int catalog_id: Catalog ID
+        :return: List of SecurityControl objects
+        :rtype: List[SecurityControl]
+        """
+        if catalog_id not in self._catalog_cache:
+            try:
+                controls = SecurityControl.get_list_by_catalog(catalog_id)
+                self._catalog_cache[catalog_id] = controls
+            except Exception as e:
+                logger.error(f"Failed to get controls for catalog {catalog_id}: {e}")
+                return []
+
+        return self._catalog_cache.get(catalog_id, [])
+
+    def _normalize_control_id(self, control_id: str) -> Optional[str]:
+        """
+        Normalize a control ID by removing leading zeros from all numeric parts.
+
+        Examples:
+        - AC-01 -> AC-1
+        - AC-17(02) -> AC-17.2
+        - AC-1.01 -> AC-1.1
+
+        :param str control_id: The control ID to normalize
+        :return: Normalized control ID or None if invalid
+        :rtype: Optional[str]
+        """
+        parsed = self.parse_control_id(control_id)
+        if not parsed:
+            return None
+
+        # Split by '-' to get family and number parts
+        parts = parsed.split("-")
+        if len(parts) != 2:
+            return None
+
+        family = parts[0]
+        number_part = parts[1]
+
+        # Handle enhancement notation (both . and parentheses are normalized to .)
+        if "." in number_part:
+            main_num, enhancement = number_part.split(".", 1)
+            # Remove leading zeros from both parts
+            main_num = str(int(main_num))
+            enhancement = str(int(enhancement))
+            return f"{family}-{main_num}.{enhancement}"
+        else:
+            # Just main control number
+            main_num = str(int(number_part))
+            return f"{family}-{main_num}"
+
+    def _get_control_id_variations(self, control_id: str) -> set:
+        """
+        Generate all valid variations of a control ID (with and without leading zeros).
+
+        Examples:
+        - AC-1 -> {AC-1, AC-01}
+        - AC-17.2 -> {AC-17.2, AC-17.02, AC-17(2), AC-17(02)}
+
+        :param str control_id: The control ID to generate variations for
+        :return: Set of all valid variations
+        :rtype: set
+        """
+        parsed = self.parse_control_id(control_id)
+        if not parsed:
+            return set()
+
+        variations = set()
+
+        # Split by '-' to get family and number parts
+        parts = parsed.split("-")
+        if len(parts) != 2:
+            return set()
+
+        family = parts[0]
+        number_part = parts[1]
+
+        # Handle enhancement notation
+        if "." in number_part:
+            main_num, enhancement = number_part.split(".", 1)
+            main_int = int(main_num)
+            enh_int = int(enhancement)
+
+            # Generate all combinations: with/without leading zeros, dot/parenthesis notation
+            for main_fmt in [str(main_int), f"{main_int:02d}"]:
+                for enh_fmt in [str(enh_int), f"{enh_int:02d}"]:
+                    variations.add(f"{family}-{main_fmt}.{enh_fmt}")
+                    variations.add(f"{family}-{main_fmt}({enh_fmt})")
+        else:
+            # Just main control number
+            main_int = int(number_part)
+            variations.add(f"{family}-{main_int}")
+            variations.add(f"{family}-{main_int:02d}")
+
+        # Add uppercase versions to ensure consistency
+        return {v.upper() for v in variations}
+
+    def _get_control_implementations(self, parent_id: int, parent_module: str) -> Dict[str, ControlImplementation]:
+        """
+        Get control implementations for a parent (with caching).
+
+        :param int parent_id: Parent ID
+        :param str parent_module: Parent module
+        :return: Dict of implementations keyed by control ID
+        :rtype: Dict[str, ControlImplementation]
+        """
+        cache_key = (parent_id, parent_module)
+
+        if cache_key not in self._control_impl_cache:
+            try:
+                # Get the label map which maps control IDs to implementation IDs
+                label_map = ControlImplementation.get_control_label_map_by_parent(parent_id, parent_module)
+
+                implementations = {}
+                for control_label, impl_id in label_map.items():
+                    impl = ControlImplementation.get_object(impl_id)
+                    if impl:
+                        implementations[control_label] = impl
+
+                self._control_impl_cache[cache_key] = implementations
+            except Exception as e:
+                logger.error(f"Failed to get implementations for {parent_module}/{parent_id}: {e}")
+                return {}
+
+        return self._control_impl_cache.get(cache_key, {})
+
+    def clear_cache(self):
+        """Clear all cached data."""
+        self._catalog_cache.clear()
+        self._control_impl_cache.clear()
+        logger.info("Cleared control matcher cache")

regscale/integrations/milestone_manager.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Milestone Manager for Issue Tracking
+
+Handles creation of milestones for issues based on status transitions (created, reopened, closed).
+Also handles backfilling of missing milestones for existing issues.
+"""
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from regscale.core.app.utils.app_utils import get_current_datetime
+from regscale.integrations.variables import ScannerVariables
+from regscale.models import regscale_models
+
+if TYPE_CHECKING:
+    from regscale.integrations.scanner_integration import IntegrationFinding
+
+logger = logging.getLogger("regscale")
+
+
+class MilestoneManager:
+    """
+    Manages milestone creation for issues based on status transitions.
+
+    Milestones are created when:
+    - A new issue is created
+    - An existing issue is reopened (Closed -> Open)
+    - An existing issue is closed (Open -> Closed)
+    """
+
+    def __init__(self, integration_title: str, assessor_id: str, scan_date: str):
+        """
+        Initialize the milestone manager.
+
+        :param str integration_title: Name of the integration (used in milestone titles)
+        :param str assessor_id: ID of the assessor/responsible person for milestones
+        :param str scan_date: Date of the scan (used for new issue milestones)
+        """
+        self.integration_title = integration_title
+        self.assessor_id = assessor_id
+        self.scan_date = scan_date
+
+    def create_milestones_for_issue(
+        self,
+        issue: regscale_models.Issue,
+        finding: Optional["IntegrationFinding"] = None,
+        existing_issue: Optional[regscale_models.Issue] = None,
+    ) -> None:
+        """
+        Create appropriate milestones for an issue based on status transitions.
+
+        :param regscale_models.Issue issue: The issue to create milestones for
+        :param Optional[IntegrationFinding] finding: The finding data (for logging/context)
+        :param Optional[regscale_models.Issue] existing_issue: Previous state of issue for comparison
+        """
+        if not self._should_create_milestones(issue):
+            return
+
+        if self._should_create_reopened_milestone(existing_issue, issue):
+            self._create_reopened_milestone(issue, finding)
+        elif self._should_create_closed_milestone(existing_issue, issue):
+            self._create_closed_milestone(issue, finding)
+        elif not existing_issue:
+            self._create_new_issue_milestone(issue, finding)
+        else:
+            logger.debug(
+                "No milestone created for issue %s (no status transition detected)",
+                issue.id,
+            )
+
+    def _should_create_milestones(self, issue: regscale_models.Issue) -> bool:
+        """
+        Check if milestones should be created for this issue.
+
+        :param regscale_models.Issue issue: The issue to check
+        :return: True if milestones should be created
+        :rtype: bool
+        """
+        if not ScannerVariables.useMilestones:
+            logger.debug("Milestone creation disabled (useMilestones=False)")
+            return False
+
+        if not issue.id:
+            logger.debug("Cannot create milestone - issue has no ID")
+            return False
+
+        return True
+
+    def _should_create_reopened_milestone(
+        self, existing_issue: Optional[regscale_models.Issue], issue: regscale_models.Issue
+    ) -> bool:
+        """
+        Check if a reopened milestone should be created.
+
+        :param Optional[regscale_models.Issue] existing_issue: The existing issue
+        :param regscale_models.Issue issue: The current issue
+        :return: True if reopened milestone should be created
+        :rtype: bool
+        """
+        return (
+            existing_issue is not None
+            and existing_issue.status == regscale_models.IssueStatus.Closed
+            and issue.status == regscale_models.IssueStatus.Open
+        )
+
+    def _should_create_closed_milestone(
+        self, existing_issue: Optional[regscale_models.Issue], issue: regscale_models.Issue
+    ) -> bool:
+        """
+        Check if a closed milestone should be created.
+
+        :param Optional[regscale_models.Issue] existing_issue: The existing issue
+        :param regscale_models.Issue issue: The current issue
+        :return: True if closed milestone should be created
+        :rtype: bool
+        """
+        return (
+            existing_issue is not None
+            and existing_issue.status == regscale_models.IssueStatus.Open
+            and issue.status == regscale_models.IssueStatus.Closed
+        )
+
+    def _create_reopened_milestone(
+        self,
+        issue: regscale_models.Issue,
+        finding: Optional["IntegrationFinding"] = None,
+    ) -> None:
+        """
+        Create a milestone for a reopened issue.
+
+        :param regscale_models.Issue issue: The issue being reopened
+        :param Optional[IntegrationFinding] finding: The finding data (for logging)
+        """
+        milestone_date = get_current_datetime()
+        self._create_milestone(
+            issue=issue,
+            title=f"Issue reopened from {self.integration_title} scan",
+            milestone_date=milestone_date,
+            milestone_type="reopened",
+            finding=finding,
+        )
+
+    def _create_closed_milestone(
+        self,
+        issue: regscale_models.Issue,
+        finding: Optional["IntegrationFinding"] = None,
+    ) -> None:
+        """
+        Create a milestone for a closed issue.
+
+        :param regscale_models.Issue issue: The issue being closed
+        :param Optional[IntegrationFinding] finding: The finding data (for logging)
+        """
+        milestone_date = issue.dateCompleted or get_current_datetime()
+        self._create_milestone(
+            issue=issue,
+            title=f"Issue closed from {self.integration_title} scan",
+            milestone_date=milestone_date,
+            milestone_type="closed",
+            finding=finding,
+        )
+
+    def _create_new_issue_milestone(
+        self,
+        issue: regscale_models.Issue,
+        finding: Optional["IntegrationFinding"] = None,
+    ) -> None:
+        """
+        Create a milestone for a newly created issue.
+
+        :param regscale_models.Issue issue: The newly created issue
+        :param Optional[IntegrationFinding] finding: The finding data (for logging)
+        """
+        self._create_milestone(
+            issue=issue,
+            title=f"Issue created from {self.integration_title} scan",
+            milestone_date=self.scan_date,
+            milestone_type="new",
+            finding=finding,
+        )
+
+    def _create_milestone(
+        self,
+        issue: regscale_models.Issue,
+        title: str,
+        milestone_date: str,
+        milestone_type: str,
+        finding: Optional["IntegrationFinding"] = None,
+    ) -> None:
+        """
+        Create a milestone with error handling.
+
+        :param regscale_models.Issue issue: The issue to create milestone for
+        :param str title: Title of the milestone
+        :param str milestone_date: Date for the milestone
+        :param str milestone_type: Type of milestone (for logging: new, reopened, closed)
+        :param Optional[IntegrationFinding] finding: The finding data (for logging)
+        """
+        try:
+            regscale_models.Milestone(
+                title=title,
+                milestoneDate=milestone_date,
+                dateCompleted=get_current_datetime(),
+                responsiblePersonId=self.assessor_id,
+                parentID=issue.id,
+                parentModule="issues",
+            ).create_or_update()
+
+            logger.debug(f"Created {milestone_type} milestone for issue {issue.id}")
+
+        except Exception as e:
+            logger.warning(f"Failed to create {milestone_type} milestone for issue {issue.id}: {e}")
+
+    def get_existing_milestones(self, issue: regscale_models.Issue) -> List[regscale_models.Milestone]:
+        """
+        Get all existing milestones for an issue.
+
+        :param regscale_models.Issue issue: The issue to check
+        :return: List of existing milestones
+        :rtype: List[regscale_models.Milestone]
+        """
+        if not issue.id:
+            return []
+
+        try:
+            milestones = regscale_models.Milestone.get_by_parent(parent_id=issue.id, parent_module="issues")
+            return milestones if milestones else []
+        except Exception as e:
+            logger.debug(f"Could not retrieve milestones for issue {issue.id}: {e}")
+            return []
+
+    def has_creation_milestone(self, issue: regscale_models.Issue) -> bool:
+        """
+        Check if an issue has a creation milestone.
+
+        :param regscale_models.Issue issue: The issue to check
+        :return: True if creation milestone exists
+        :rtype: bool
+        """
+        milestones = self.get_existing_milestones(issue)
+
+        # Check for creation milestone patterns
+        creation_patterns = [
+            "Issue created from",
+            "created from",
+        ]
+
+        for milestone in milestones:
+            milestone_title = milestone.title.lower() if milestone.title else ""
+            if any(pattern.lower() in milestone_title for pattern in creation_patterns):
+                logger.debug(f"Found existing creation milestone for issue {issue.id}: {milestone.title}")
+                return True
+
+        return False
+
+    def ensure_creation_milestone_exists(
+        self,
+        issue: regscale_models.Issue,
+        finding: Optional["IntegrationFinding"] = None,
+    ) -> None:
+        """
+        Ensure an issue has a creation milestone, backfilling if necessary.
+
+        This method checks if an issue has a creation milestone. If not, it creates one
+        based on the issue's dateCreated field to backfill missing milestones.
+
+        :param regscale_models.Issue issue: The issue to check
+        :param Optional[IntegrationFinding] finding: The finding data (for logging)
+        """
+        if not self._should_create_milestones(issue):
+            return
+
+        # Check if creation milestone already exists
+        if self.has_creation_milestone(issue):
+            logger.debug(f"Issue {issue.id} already has creation milestone, skipping backfill")
+            return
+
+        # Backfill missing creation milestone
+        logger.debug(f"Backfilling missing creation milestone for issue {issue.id}")
+
+        # Use issue's dateCreated if available, otherwise use scan_date
+        milestone_date = issue.dateCreated if issue.dateCreated else self.scan_date
+
+        self._create_milestone(
+            issue=issue,
+            title=f"Issue created from {self.integration_title} scan",
+            milestone_date=milestone_date,
+            milestone_type="backfilled",
+            finding=finding,
+        )

regscale/integrations/public/__init__.py

@@ -17,6 +17,7 @@ from regscale.core.lazy_group import LazyGroup
         "import_poam": "regscale.integrations.public.fedramp.click.import_fedramp_poam_template",
         "import_drf": "regscale.integrations.public.fedramp.click.import_drf",
         "import_cis_crm": "regscale.integrations.public.fedramp.click.import_ciscrm",
+        "export_poam_v5": "regscale.integrations.public.fedramp.click.export_poam_v5",
     },
     name="fedramp",
 )