regscale-cli 6.24.0.0__py3-none-any.whl → 6.25.0.0__py3-none-any.whl

regscale/integrations/commercial/microsoft_defender/defender.py

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 """RegScale Microsoft Defender recommendations and alerts integration"""
 # standard python imports
+
 import logging
 from datetime import datetime, timedelta
 from os import PathLike
@@ -10,6 +11,7 @@ from typing import Literal, Optional, Tuple, Union
 
 import click
 from rich.console import Console
+from rich.table import Table
 
 from regscale.core.app.api import Api
 from regscale.core.app.internal.login import is_valid
@@ -24,6 +26,7 @@ from regscale.core.app.utils.app_utils import (
     uncamel_case,
 )
 from regscale.integrations.commercial.microsoft_defender.defender_api import DefenderApi
+from regscale.integrations.commercial.microsoft_defender.defender_constants import EVIDENCE_TO_CONTROLS_MAPPING
 from regscale.models import File, Issue, regscale_id, regscale_module, ssp_or_component_id
 from regscale.models.app_models.click import NotRequiredIf
 from regscale.models.integration_models.defender_data import DefenderData
@@ -68,12 +71,12 @@ def defender():
 @defender.command(name="authenticate")
 @click.option(
     "--system",
-    type=click.Choice(["cloud", "365"], case_sensitive=False),
-    help="Pull recommendations from Microsoft Defender 365 or Microsoft Defender for Cloud.",
+    type=click.Choice(["cloud", "365", "entra"], case_sensitive=False),
+    help="Pull recommendations from Microsoft Defender 365, Microsoft Defender for Cloud, or Azure Entra.",
     prompt="Please choose a system",
     required=True,
 )
-def authenticate_in_defender(system: Literal["cloud", "365"]):
+def authenticate_in_defender(system: Literal["cloud", "365", "entra"]):
     """Obtains an access token using the credentials provided in init.yaml."""
     authenticate(system=system)
 
@@ -225,6 +228,85 @@ def import_alerts(
     )
 
 
+@defender.command(name="collect_entra_evidence")
+@ssp_or_component_id()
+@click.option(
+    "--days_back",
+    "-d",
+    type=click.INT,
+    help="Number of days back to collect audit logs",
+    default=30,
+)
+@click.option(
+    "--evidence_type",
+    "-t",
+    type=click.Choice(
+        ["all", "users_groups", "rbac_pim", "conditional_access", "authentication", "audit_logs", "access_reviews"],
+        case_sensitive=False,
+    ),
+    help="Type of evidence to collect",
+    default="all",
+)
+def collect_entra_evidence(regscale_ssp_id: int, component_id: int, days_back: int, evidence_type: str):
+    """
+    Collect Azure Entra evidence for FedRAMP compliance controls and upload to RegScale
+    """
+    # Validate parent module for evidence collection
+    from regscale.validation.record import validate_component_or_ssp
+
+    validate_component_or_ssp(ssp_id=regscale_ssp_id, component_id=component_id)
+    parent_id = regscale_ssp_id or component_id
+    parent_module = "securityplans" if regscale_ssp_id else "components"
+
+    collect_and_upload_entra_evidence(
+        parent_id=parent_id, parent_module=parent_module, days_back=days_back, evidence_type=evidence_type
+    )
+
+
+@defender.command(name="show_entra_mappings")
+@click.option(
+    "--evidence_type",
+    "-t",
+    type=click.Choice(
+        ["all", "users_groups", "rbac_pim", "conditional_access", "authentication", "audit_logs", "access_reviews"],
+        case_sensitive=False,
+    ),
+    help="Show mappings for specific evidence type",
+    default="all",
+)
+def show_entra_mappings(evidence_type: str):
+    """
+    Show which FedRAMP controls are mapped to each Azure Entra evidence type
+    """
+    if evidence_type == "all":
+        evidence_types_to_show = EVIDENCE_TO_CONTROLS_MAPPING.keys()
+    else:
+        # Map category to specific evidence types
+        category_to_evidence = {
+            "users_groups": ["users", "guest_users", "security_groups"],
+            "rbac_pim": ["role_assignments", "role_definitions", "pim_assignments", "pim_eligibility"],
+            "conditional_access": ["conditional_access"],
+            "authentication": ["auth_methods_policy", "user_mfa_registration", "mfa_registered_users"],
+            "audit_logs": ["sign_in_logs", "directory_audits", "provisioning_logs"],
+            "access_reviews": ["access_review_definitions"],
+        }
+        evidence_types_to_show = category_to_evidence.get(evidence_type, [evidence_type])
+    # create a table using rich and add a row for each evidence type
+    table = Table(title="Azure Entra Evidence to FedRAMP Controls Mapping", show_lines=True)
+    table.add_column("Evidence Type", style="#10c4d3")
+    table.add_column("Controls", style="#18a8e9")
+    table.add_column("Total Controls", style="#ff9d20")
+    for evidence_key in evidence_types_to_show:
+        if evidence_key in EVIDENCE_TO_CONTROLS_MAPPING:
+            controls = EVIDENCE_TO_CONTROLS_MAPPING[evidence_key]
+            table.add_row(evidence_key.replace("_", " ").title(), ", ".join(controls), str(len(controls)))
+    console.print(table)
+
+    console.print(
+        "[dim]Use 'regscale defender collect_entra_evidence' to collect and upload evidence to these controls[/dim]"
+    )
+
+
 def import_defender_alerts(
     folder_path: PathLike[str],
     regscale_ssp_id: int,
@@ -268,11 +350,11 @@ def import_defender_alerts(
     )
 
 
-def authenticate(system: Literal["cloud", "365"]) -> None:
+def authenticate(system: Literal["cloud", "365", "entra"]) -> None:
     """
     Obtains an access token using the credentials provided in init.yaml
 
-    :param Literal["cloud", "365"] system: The system to authenticate for, either Defender 365 or Defender for Cloud
+    :param Literal["cloud", "365", "entra"] system: The system to authenticate for, either Defender 365, Defender for Cloud, or Azure Entra
     :rtype: None
     """
     _ = check_license()
@@ -947,3 +1029,242 @@ def fetch_save_and_upload_query(
         api=defender_api.api,
     ):
         logger.info(f"Successfully uploaded {file_path.name} to {parent_module} #{parent_id} in RegScale.")
+
+
+def collect_and_upload_entra_evidence(
+    parent_id: int, parent_module: str, days_back: int = 30, evidence_type: str = "all"
+) -> None:
+    """
+    Collect Azure Entra evidence for FedRAMP compliance controls and upload to RegScale
+
+    :param int parent_id: The RegScale ID to upload evidence to
+    :param str parent_module: The RegScale module to upload evidence to
+    :param int days_back: Number of days back to collect audit logs
+    :param str evidence_type: Type of evidence to collect
+    :rtype: None
+    """
+    app = check_license()
+    api = Api()
+
+    if not is_valid(app=app):
+        error_and_exit(LOGIN_ERROR)
+
+    logger.info(f"Starting Azure Entra evidence collection for {evidence_type}...")
+
+    defender_api = DefenderApi(system="entra")
+
+    try:
+        if evidence_type == "all":
+            evidence_data = defender_api.collect_all_entra_evidence(days_back=days_back)
+        else:
+            evidence_data = collect_specific_evidence_type(defender_api, evidence_type, days_back)
+
+        upload_evidence_files(evidence_data, parent_id, parent_module, api, evidence_type)
+
+    except Exception as e:
+        error_and_exit(f"Error collecting Azure Entra evidence: {e}")
+
+
+def collect_specific_evidence_type(
+    defender_api: DefenderApi, evidence_type: str, days_back: int
+) -> dict[str, list[Path]]:
+    """
+    Collect specific type of Azure Entra evidence
+
+    :param DefenderApi defender_api: The Defender API instance
+    :param str evidence_type: Type of evidence to collect
+    :param int days_back: Number of days back for audit logs
+    :return: Dictionary containing evidence data and file paths to saved csv evidence files
+    :rtype: dict[str, list[Path]]
+    """
+    evidence_data = {}
+    start_date = (datetime.now() - timedelta(days=days_back)).strftime("%Y-%m-%dT00:00:00Z")
+
+    if evidence_type == "users_groups":
+        evidence_data["users"] = defender_api.get_and_save_entra_evidence("users")
+        evidence_data["guest_users"] = defender_api.get_and_save_entra_evidence("guest_users")
+        evidence_data["groups_and_members"] = defender_api.get_and_save_entra_evidence("groups_and_members")
+        evidence_data["security_groups"] = defender_api.get_and_save_entra_evidence("security_groups")
+
+    elif evidence_type == "rbac_pim":
+        evidence_data["role_assignments"] = defender_api.get_and_save_entra_evidence("role_assignments")
+        evidence_data["role_definitions"] = defender_api.get_and_save_entra_evidence("role_definitions")
+        evidence_data["pim_assignments"] = defender_api.get_and_save_entra_evidence("pim_assignments")
+        evidence_data["pim_eligibility"] = defender_api.get_and_save_entra_evidence("pim_eligibility")
+
+    elif evidence_type == "conditional_access":
+        evidence_data["conditional_access"] = defender_api.get_and_save_entra_evidence("conditional_access")
+
+    elif evidence_type == "authentication":
+        evidence_data["auth_methods_policy"] = defender_api.get_and_save_entra_evidence("auth_methods_policy")
+        evidence_data["user_mfa_registration"] = defender_api.get_and_save_entra_evidence("user_mfa_registration")
+        evidence_data["mfa_registered_users"] = defender_api.get_and_save_entra_evidence("mfa_registered_users")
+
+    elif evidence_type == "audit_logs":
+        evidence_data["sign_in_logs"] = defender_api.get_and_save_entra_evidence("sign_in_logs", start_date=start_date)
+        evidence_data["directory_audits"] = defender_api.get_and_save_entra_evidence(
+            "directory_audits", start_date=start_date
+        )
+        evidence_data["provisioning_logs"] = defender_api.get_and_save_entra_evidence(
+            "provisioning_logs", start_date=start_date
+        )
+
+    elif evidence_type == "access_reviews":
+        evidence_data["access_review_definitions"] = defender_api.collect_entra_access_reviews()
+
+    return evidence_data
+
+
+def get_control_implementations_map(parent_id: int, parent_module: str) -> dict[str, int]:
+    """
+    Get a mapping of control identifiers to control implementation IDs
+
+    :param int parent_id: RegScale parent ID
+    :param str parent_module: RegScale parent module
+    :return: Dictionary mapping control identifiers (e.g., "AC-2") to control implementation IDs
+    :rtype: dict[str, int]
+    """
+    from regscale.models import ControlImplementation
+
+    try:
+        control_implementations = ControlImplementation.get_list_by_parent(parent_id, parent_module)
+        if not control_implementations:
+            logger.warning(f"No control implementations found for {parent_module} #{parent_id}")
+            return {}
+
+        control_map = {}
+        for control_impl in control_implementations:
+            # Try to get control identifier from the control object
+            control_id = control_impl.get("controlId") if isinstance(control_impl, dict) else control_impl.controlId
+            id_number = control_impl.get("id") if isinstance(control_impl, dict) else control_impl.id
+            control_map[control_id] = id_number
+            logger.debug(f"Mapped control #{id_number}: {control_id} to implementation.")
+
+        logger.info(f"Found {len(control_map)} control implementations for evidence mapping")
+        return control_map
+
+    except Exception as e:
+        logger.error(f"Error fetching control implementations: {e}")
+        return {}
+
+
+def upload_evidence_to_controls(
+    evidence_key: str,
+    evidence_file_list: list[Path],
+    control_implementations_map: dict[str, int],
+    api: Api,
+) -> int:
+    """
+    Upload evidence file to specific control implementations
+
+    :param str evidence_key: Type of evidence (e.g., "users", "sign_in_logs")
+    :param list evidence_file_list: List of evidence files
+    :param dict control_implementations_map: Map of control identifiers to implementation IDs
+    :param Api api: API instance
+    :return: Number of successful uploads
+    :rtype: int
+    """
+    # Get the controls this evidence type maps to
+    mapped_controls = EVIDENCE_TO_CONTROLS_MAPPING.get(evidence_key, [])
+    if not mapped_controls:
+        logger.warning(f"No control mapping found for evidence type: {evidence_key}")
+        return 0
+
+    # Write evidence data to CSV file
+    successful_uploads = 0
+    for file_path in evidence_file_list:
+        controls_uploaded_to = []
+        file_name = file_path.name
+
+        for control_identifier in mapped_controls:
+            if control_identifier in control_implementations_map:
+                control_impl_id = control_implementations_map[control_identifier]
+
+                # Upload file to specific control implementation
+                if File.upload_file_to_regscale(
+                    file_name=file_path.absolute(),  # type: ignore
+                    parent_id=control_impl_id,
+                    parent_module="controls",
+                    api=api,
+                ):
+                    successful_uploads += 1
+                    controls_uploaded_to.append(control_identifier)
+                    logger.debug(
+                        f"Successfully uploaded {file_name} to control {control_identifier} (ID: {control_impl_id})"
+                    )
+                else:
+                    logger.error(
+                        f"Failed to upload {file_name} to control {control_identifier} (ID: {control_impl_id})"
+                    )
+
+        if controls_uploaded_to:
+            logger.info(
+                f"Successfully uploaded {file_name} to {len(controls_uploaded_to)} controls: {', '.join(controls_uploaded_to)}"
+            )
+        else:
+            logger.warning(f"No matching control implementations found for {evidence_key} evidence")
+
+    return successful_uploads
+
+
+def upload_evidence_files(
+    evidence_data: dict[str, list[Path]], parent_id: int, parent_module: str, api: Api, evidence_type: str
+) -> None:
+    """
+    Upload evidence files to specific RegScale control implementations
+
+    :param dict[str, list[Path]] evidence_data: Dictionary containing evidence data
+    :param int parent_id: RegScale parent ID
+    :param str parent_module: RegScale parent module
+    :param Api api: API instance
+    :param str evidence_type: Type of evidence collected
+    :rtype: None
+    """
+    from regscale.integrations.commercial.microsoft_defender.defender_constants import EVIDENCE_CATEGORIES
+
+    artifacts_dir = Path("./artifacts")
+    artifacts_dir.mkdir(exist_ok=True)
+
+    # Get control implementations mapping for evidence targeting
+    control_implementations_map = get_control_implementations_map(parent_id, parent_module)
+
+    if not control_implementations_map:
+        logger.error(
+            f"No control implementations found for {parent_module} #{parent_id}. Cannot map evidence to controls."
+        )
+        return
+
+    total_successful_uploads = 0
+    total_evidence_items = 0
+    evidence_summary = []
+
+    for evidence_key, evidence_list in evidence_data.items():
+        if not evidence_list:
+            logger.warning(f"No data found for {evidence_key}")
+            continue
+
+        total_evidence_items += len(evidence_list)
+
+        # Upload evidence to specific control implementations
+        uploads_for_evidence = upload_evidence_to_controls(
+            evidence_key=evidence_key,
+            evidence_file_list=evidence_list,
+            control_implementations_map=control_implementations_map,
+            api=api,
+        )
+
+        total_successful_uploads += uploads_for_evidence
+        evidence_summary.append(f"{evidence_key}: {len(evidence_list)} items → {uploads_for_evidence} control uploads")
+
+    # Summary
+    category_name = EVIDENCE_CATEGORIES.get(evidence_type, f"Azure Entra {evidence_type.replace('_', ' ').title()}")
+    logger.info(
+        f"Azure Entra evidence collection complete for {category_name}. "
+        f"Collected {total_evidence_items} total items across {total_successful_uploads} control-specific uploads."
+    )
+
+    # Detailed summary
+    if evidence_summary:
+        logger.info("Evidence upload summary:")
+        for summary in evidence_summary:
+            logger.info(f"  - {summary}")