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

regscale/dev/code_gen.py

@@ -7,9 +7,13 @@ if TYPE_CHECKING:
 
 from regscale.models.integration_models.synqly_models.connector_types import ConnectorType
 from regscale.models.integration_models.synqly_models.param import Param
+from regscale.models.integration_models.synqly_models.filter_parser import FilterParser
 
 SUPPORTED_CONNECTORS = [ConnectorType.Ticketing, ConnectorType.Vulnerabilities, ConnectorType.Assets, ConnectorType.Edr]
 
+# Initialize FilterParser once at module level
+filter_parser = FilterParser()
+
 
 def generate_dags() -> None:
     """Generate Airflow DAGs for the platform"""
@@ -189,6 +193,22 @@ def _build_op_kwargs_and_docstring(
                 ),
             }
             config[param_type] = {**config[param_type], **vuln_params}
+
+    # Add filter parameter for Assets and Vulnerabilities connectors
+    if (
+        ConnectorType.Assets.lower() in integration or ConnectorType.Vulnerabilities.lower() in integration
+    ) and param_type == "optional_params":
+        # Use 'asset_filter' for vulnerabilities, 'filter' for assets
+        param_name = "asset_filter" if ConnectorType.Vulnerabilities.lower() in integration else "filter"
+        filter_param = {
+            param_name: Param(
+                name=param_name,
+                type="string",
+                description="Semicolon separated filters of format filter[operator]value",
+                default=None,
+            )
+        }
+        config[param_type] = {**config.get(param_type, {}), **filter_param}
     if config.get(param_type):
         if proper_type not in doc_string:
             doc_string += f"{proper_type}:\n"
@@ -290,6 +310,7 @@ def add_connector_specific_params(
         sync_attachments_jinja = "'sync_attachments'"
         op_kwargs += f'\n        "sync_attachments": "{{{{ dag_run.conf[{sync_attachments_jinja}] if {sync_attachments_jinja} in dag_run.conf else False }}}}",'
         doc_string += "    sync_attachments: BOOLEAN Whether to sync attachments between integration and RegScale\n"
+
     return op_kwargs, doc_string
 
 
@@ -353,6 +374,44 @@ def {connector}() -> None:
     pass
 """
 
+    # Add build-query command for Assets and Vulnerabilities connectors
+    if connector in [ConnectorType.Assets, ConnectorType.Vulnerabilities]:
+        cli_code += f"""
+
+@{connector}.command(name="build-query")
+@click.option(
+    '--provider',
+    required=False,
+    help='Provider ID (e.g., {connector}_armis_centrix). If not specified, starts interactive mode.'
+)
+@click.option(
+    '--validate',
+    help='Validate a filter string against provider capabilities'
+)
+@click.option(
+    '--list-fields',
+    is_flag=True,
+    default=False,
+    help='List all available fields for the provider'
+)
+def build_query(provider, validate, list_fields):
+    \"\"\"
+    Build and validate filter queries for {connector.capitalize()} connectors.
+
+    Examples:
+        # Build a filter query
+        regscale {connector} build-query
+
+        # List all fields for a specific provider
+        regscale {connector} build-query --provider {connector}_armis_centrix --list-fields
+
+        # Validate a filter string
+        regscale {connector} build-query --provider {connector}_armis_centrix --validate "device.ip[eq]192.168.1.1"
+    \"\"\"
+    from regscale.integrations.commercial.synqly.query_builder import handle_build_query
+    handle_build_query('{connector}', provider, validate, list_fields)
+"""
+
     # replace the integration config with a flattened version
     for integration, config in integration_configs.items():
         capabilities = config.get("capabilities", [])
@@ -363,6 +422,7 @@ def {connector}() -> None:
             connector=connector,
             integration_name=integration_name,
             capabilities=capabilities,
+            provider_id=integration,  # Pass the full provider ID for filter support
         )
         cli_code += f"\n\n{click_options_and_command}"
         integrations_count += 1
@@ -374,12 +434,15 @@ def {connector}() -> None:
     print(f"Generated click commands for {integrations_count} {connector} connector(s).")
 
 
-def _build_all_params(integration_name: str, connector: str) -> tuple[list[str], list[str], list[str]]:
+def _build_all_params(
+    integration_name: str, connector: str, provider_id: str = None
+) -> tuple[list[str], list[str], list[str]]:
     """
     Function to build the click options, function params, and function kwargs for the integration
 
     :param str integration_name: The name of the integration
     :param str connector: The connector type
+    :param str provider_id: The provider ID for filter support (e.g., 'assets_armis_centrix')
     :return: The click options, function params, and function kwargs
     :rtype: tuple[list[str], list[str], list[str]]
     """
@@ -395,19 +458,36 @@ def _build_all_params(integration_name: str, connector: str) -> tuple[list[str],
             "scan_date=scan_date",
             "all_scans=all_scans",
         ]
+
+        # Add filter option if provider supports filtering
+        if provider_id and filter_parser.has_filters(provider_id):
+            filter_option = "@click.option(\n    '--asset_filter',\n    help='STRING: Apply filters to asset queries. Can be a single filter \"field[operator]value\" or semicolon-separated filters \"field1[op]value1;field2[op]value2\"',\n    required=False,\n    type=str,\n    default=None)\n"
+            click_options.append(filter_option)
+            function_params.append("asset_filter: str")
+            function_kwargs.append("filter=asset_filter.split(';') if asset_filter else []")
+
     elif connector == ConnectorType.Ticketing:
         click_options = ["@regscale_id()", "@regscale_module()"]
         function_params = ["regscale_id: int", "regscale_module: str"]
         function_kwargs = ["regscale_id=regscale_id", "regscale_module=regscale_module"]
     else:
+        # Assets and other connectors
         click_options = ["@regscale_ssp_id()"]
         function_params = ["regscale_ssp_id: int"]
         function_kwargs = ["regscale_ssp_id=regscale_ssp_id"]
+
+        # Add filter option for Assets if provider supports filtering
+        if connector == ConnectorType.Assets and provider_id and filter_parser.has_filters(provider_id):
+            filter_option = "@click.option(\n    '--filter',\n    help='STRING: Apply filters to the query. Can be a single filter \"field[operator]value\" or semicolon-separated filters \"field1[op]value1;field2[op]value2\"',\n    required=False,\n    type=str,\n    default=None)\n"
+            click_options.append(filter_option)
+            function_params.append("filter: str")
+            function_kwargs.append("filter=filter.split(';') if filter else []")
+
     return click_options, function_params, function_kwargs
 
 
 def _build_click_options_and_command(
-    config: dict, connector: str, integration_name: str, capabilities: list[str]
+    config: dict, connector: str, integration_name: str, capabilities: list[str], provider_id: str = None
 ) -> str:
     """
     Function to use the config to build the click options and command for the integration
@@ -416,12 +496,13 @@ def _build_click_options_and_command(
     :param str connector: The connector type
     :param str integration_name: The name of the integration
     :param list[str] capabilities: The capabilities of the integration
+    :param str provider_id: The provider ID for filter support (e.g., 'assets_armis_centrix')
     :return: The click options as a string
     :rtype: str
     """
     doc_string_name = integration_name.replace("_", " ").title()
     # add regscale_ssp_id as a default option
-    click_options, function_params, function_kwargs = _build_all_params(doc_string_name, connector)
+    click_options, function_params, function_kwargs = _build_all_params(doc_string_name, connector, provider_id)
     for param_type in ["expected_params", "optional_params"]:
         for param in config.get(param_type, []):
             param_data = config[param_type][param]

regscale/integrations/commercial/__init__.py

@@ -118,6 +118,8 @@ def crowdstrike():
         "sync_cloud_alerts": "regscale.integrations.commercial.microsoft_defender.defender.sync_cloud_alerts",
         "sync_cloud_recommendations": "regscale.integrations.commercial.microsoft_defender.defender.sync_cloud_recommendations",
         "import_alerts": "regscale.integrations.commercial.microsoft_defender.defender.import_alerts",
+        "collect_entra_evidence": "regscale.integrations.commercial.microsoft_defender.defender.collect_entra_evidence",
+        "show_entra_mappings": "regscale.integrations.commercial.microsoft_defender.defender.show_entra_mappings",
     },
     name="defender",
 )

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}")