regscale-cli 6.21.2.0__py3-none-any.whl → 6.28.2.1__py3-none-any.whl

regscale/integrations/commercial/aws/evidence_generator.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""AWS Evidence Generator for SSP compliance documentation"""
+
+import gzip
+import json
+import logging
+from datetime import datetime, timedelta
+from io import BytesIO
+from typing import List, Optional
+
+from regscale.core.app.api import Api
+from regscale.models.regscale_models.evidence import Evidence
+from regscale.models.regscale_models.evidence_mapping import EvidenceMapping
+from regscale.models.regscale_models.file import File
+
+logger = logging.getLogger("regscale")
+
+
+class AWSEvidenceGenerator:
+    """Generate compliance evidence from AWS security findings"""
+
+    def __init__(self, api: Api, ssp_id: Optional[int] = None):
+        """
+        Initialize evidence generator
+
+        :param Api api: RegScale API instance
+        :param Optional[int] ssp_id: Security Plan ID to link evidence
+        """
+        self.api = api
+        self.ssp_id = ssp_id
+
+    def create_evidence_from_scan(
+        self,
+        service_name: str,
+        findings: List[dict],
+        ocsf_data: Optional[List[dict]] = None,
+        update_frequency: int = 30,
+        control_ids: Optional[List[int]] = None,
+    ) -> Optional[Evidence]:
+        """
+        Create evidence record from AWS service scan
+
+        :param str service_name: AWS service name (GuardDuty, SecurityHub, etc.)
+        :param List[dict] findings: List of AWS findings (native format)
+        :param Optional[List[dict]] ocsf_data: OCSF-formatted findings
+        :param int update_frequency: Evidence update frequency in days (default: 30)
+        :param Optional[List[int]] control_ids: Control IDs to link evidence
+        :return: Created Evidence object or None
+        :rtype: Optional[Evidence]
+        """
+        if not findings:
+            logger.warning("No findings provided, skipping evidence creation")
+            return None
+
+        # Generate evidence title with timestamp
+        scan_date = datetime.now().strftime("%Y-%m-%d")
+        title = f"{service_name} Findings Scan - {scan_date}"
+
+        # Create description with finding summary
+        total_findings = len(findings)
+        severity_counts = self._count_severities(findings, service_name)
+        description = self._build_evidence_description(service_name, total_findings, severity_counts, ocsf_data)
+
+        # Calculate due date based on update frequency
+        due_date = (datetime.now() + timedelta(days=update_frequency)).isoformat()
+
+        try:
+            # Create evidence record
+            evidence = Evidence(
+                title=title,
+                description=description,
+                status="Collected",
+                updateFrequency=update_frequency,
+                dueDate=due_date,
+            )
+
+            # Create evidence in RegScale
+            created_evidence = evidence.create()
+            if not created_evidence or not created_evidence.id:
+                logger.error("Failed to create evidence record")
+                return None
+
+            logger.info("Created evidence record %s: %s", created_evidence.id, title)
+
+            # Upload findings as file attachments
+            self._attach_findings_files(
+                created_evidence.id,
+                findings,
+                ocsf_data,
+                service_name,
+            )
+
+            # Link evidence to SSP if provided
+            if self.ssp_id:
+                self._link_to_ssp(created_evidence.id)
+
+            # Link evidence to specific controls if provided
+            if control_ids:
+                self._link_to_controls(created_evidence.id, control_ids)
+
+            return created_evidence
+
+        except Exception as ex:
+            logger.error("Failed to create evidence: %s", ex)
+            return None
+
+    def _count_severities(self, findings: List[dict], service_name: str) -> dict:
+        """
+        Count findings by severity level
+
+        :param List[dict] findings: AWS findings
+        :param str service_name: AWS service name for severity field mapping
+        :return: Dictionary with severity counts
+        :rtype: dict
+        """
+        severity_counts = {"CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0, "INFO": 0}
+
+        for finding in findings:
+            # Map service-specific severity fields
+            if service_name == "GuardDuty":
+                severity = finding.get("Severity", 0)
+                # GuardDuty uses numeric severity (1.0-8.9)
+                if severity >= 7.0:
+                    severity_counts["HIGH"] += 1
+                elif severity >= 4.0:
+                    severity_counts["MEDIUM"] += 1
+                else:
+                    severity_counts["LOW"] += 1
+
+            elif service_name == "SecurityHub":
+                # Security Hub uses normalized severity
+                severity_label = finding.get("Severity", {}).get("Label", "INFO")
+                severity_counts[severity_label] = severity_counts.get(severity_label, 0) + 1
+
+            elif service_name == "CloudTrail":
+                # CloudTrail events don't have severity, count as INFO
+                severity_counts["INFO"] += 1
+
+        return severity_counts
+
+    def _build_evidence_description(
+        self,
+        service_name: str,
+        total_findings: int,
+        severity_counts: dict,
+        ocsf_data: Optional[List[dict]],
+    ) -> str:
+        """
+        Build evidence description with finding summary
+
+        :param str service_name: AWS service name
+        :param int total_findings: Total number of findings
+        :param dict severity_counts: Severity breakdown
+        :param Optional[List[dict]] ocsf_data: OCSF-formatted findings
+        :return: Evidence description text
+        :rtype: str
+        """
+        description_parts = [
+            f"Automated evidence collection from AWS {service_name}.",
+            f"Total findings: {total_findings}",
+            "",
+            "Severity Breakdown:",
+        ]
+
+        for severity, count in severity_counts.items():
+            if count > 0:
+                description_parts.append(f"  - {severity}: {count}")
+
+        description_parts.extend(["", "Files attached:"])
+        description_parts.append(f"  - {service_name.lower()}_findings_native.jsonl.gz (AWS native format, compressed)")
+
+        if ocsf_data:
+            description_parts.append(
+                f"  - {service_name.lower()}_findings_ocsf.jsonl.gz (OCSF normalized format, compressed)"
+            )
+
+        return "\n".join(description_parts)
+
+    def _attach_findings_files(
+        self,
+        evidence_id: int,
+        findings: List[dict],
+        ocsf_data: Optional[List[dict]],
+        service_name: str,
+    ) -> None:
+        """
+        Upload findings as file attachments to evidence
+
+        :param int evidence_id: Evidence record ID
+        :param List[dict] findings: Native AWS findings
+        :param Optional[List[dict]] ocsf_data: OCSF-formatted findings
+        :param str service_name: AWS service name
+        """
+        # Upload native findings as compressed JSONL
+        native_jsonl = "\n".join([json.dumps(f) for f in findings])
+
+        # Compress the JSONL data
+        compressed_buffer = BytesIO()
+        with gzip.open(compressed_buffer, "wt", encoding="utf-8", compresslevel=9) as gz_file:
+            gz_file.write(native_jsonl)
+
+        compressed_data = compressed_buffer.getvalue()
+
+        success = File.upload_file_to_regscale(
+            file_name=f"{service_name.lower()}_findings_native.jsonl.gz",
+            parent_id=evidence_id,
+            parent_module="evidence",
+            api=self.api,
+            file_data=compressed_data,
+            tags=f"aws,{service_name.lower()},native,compressed",
+        )
+
+        if success:
+            logger.info("Uploaded compressed native findings file for evidence %s", evidence_id)
+        else:
+            logger.warning("Failed to upload compressed native findings file for evidence %s", evidence_id)
+
+        # Upload OCSF findings if available
+        if ocsf_data:
+            ocsf_jsonl = "\n".join([json.dumps(f) for f in ocsf_data])
+
+            # Compress the OCSF JSONL data
+            compressed_buffer = BytesIO()
+            with gzip.open(compressed_buffer, "wt", encoding="utf-8", compresslevel=9) as gz_file:
+                gz_file.write(ocsf_jsonl)
+
+            compressed_data = compressed_buffer.getvalue()
+
+            success = File.upload_file_to_regscale(
+                file_name=f"{service_name.lower()}_findings_ocsf.jsonl.gz",
+                parent_id=evidence_id,
+                parent_module="evidence",
+                api=self.api,
+                file_data=compressed_data,
+                tags=f"aws,{service_name.lower()},ocsf,compressed",
+            )
+
+            if success:
+                logger.info("Uploaded compressed OCSF findings file for evidence %s", evidence_id)
+            else:
+                logger.warning("Failed to upload compressed OCSF findings file for evidence %s", evidence_id)
+
+    def _link_to_ssp(self, evidence_id: int) -> None:
+        """
+        Link evidence to Security Plan
+
+        :param int evidence_id: Evidence record ID
+        """
+        if not self.ssp_id:
+            return
+
+        mapping = EvidenceMapping(
+            evidenceID=evidence_id,
+            mappedID=self.ssp_id,
+            mappingType="securityplans",
+        )
+
+        try:
+            mapping.create()
+            logger.info("Linked evidence %s to SSP %s", evidence_id, self.ssp_id)
+        except Exception as ex:
+            logger.warning("Failed to link evidence to SSP: %s", ex)
+
+    def _link_to_controls(self, evidence_id: int, control_ids: List[int]) -> None:
+        """
+        Link evidence to specific security controls
+
+        :param int evidence_id: Evidence record ID
+        :param List[int] control_ids: List of control IDs
+        """
+        for control_id in control_ids:
+            mapping = EvidenceMapping(
+                evidenceID=evidence_id,
+                mappedID=control_id,
+                mappingType="securityControlAssessments",
+            )
+
+            try:
+                mapping.create()
+                logger.info("Linked evidence %s to control %s", evidence_id, control_id)
+            except Exception as ex:
+                logger.warning("Failed to link evidence to control %s: %s", control_id, ex)

regscale/integrations/commercial/aws/guardduty_control_mappings.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""AWS GuardDuty Control Mappings for RegScale Compliance Integration."""
+
+import logging
+from typing import Dict, List, Optional
+
+logger = logging.getLogger("regscale")
+
+# NIST 800-53 R5 Control Mappings for AWS GuardDuty
+GUARDDUTY_CONTROL_MAPPINGS = {
+    "SI-4": {
+        "name": "System Monitoring",
+        "description": "Monitor the system to detect attacks and indicators of potential attacks",
+        "checks": {
+            "detector_enabled": {
+                "weight": 100,
+                "pass_criteria": "GuardDuty detector is enabled and actively monitoring",
+                "fail_criteria": "GuardDuty detector is disabled or suspended",
+            },
+            "findings_processed": {
+                "weight": 90,
+                "pass_criteria": "Active findings are reviewed and remediated",
+                "fail_criteria": "High severity findings remain unaddressed",
+            },
+        },
+    },
+    "IR-4": {
+        "name": "Incident Handling",
+        "description": "Implement incident handling capability for security incidents",
+        "checks": {
+            "high_severity_findings": {
+                "weight": 100,
+                "pass_criteria": "No unaddressed high severity findings",
+                "fail_criteria": "High severity findings detected and not remediated",
+            },
+            "incident_response": {
+                "weight": 90,
+                "pass_criteria": "Findings integrated with incident response workflow",
+                "fail_criteria": "Findings not tracked in incident management system",
+            },
+        },
+    },
+    "IR-5": {
+        "name": "Incident Monitoring",
+        "description": "Track and document system security incidents",
+        "checks": {
+            "finding_tracking": {
+                "weight": 100,
+                "pass_criteria": "All findings tracked and documented",
+                "fail_criteria": "Findings not systematically tracked",
+            },
+        },
+    },
+    "SI-3": {
+        "name": "Malicious Code Protection",
+        "description": "Implement malicious code protection mechanisms",
+        "checks": {
+            "malware_detection": {
+                "weight": 100,
+                "pass_criteria": "GuardDuty detecting and alerting on malware activities",
+                "fail_criteria": "Malware protection findings not enabled or monitored",
+            },
+        },
+    },
+    "RA-5": {
+        "name": "Vulnerability Monitoring and Scanning",
+        "description": "Monitor and scan for vulnerabilities in the system",
+        "checks": {
+            "threat_intelligence": {
+                "weight": 100,
+                "pass_criteria": "GuardDuty threat intelligence enabled and current",
+                "fail_criteria": "Threat intelligence feeds not enabled or outdated",
+            },
+        },
+    },
+}
+
+# Severity mapping (GuardDuty uses 0-10 scale)
+SEVERITY_MAPPING = {
+    "LOW": (0.1, 3.9),
+    "MEDIUM": (4.0, 6.9),
+    "HIGH": (7.0, 8.9),
+    "CRITICAL": (9.0, 10.0),
+}
+
+# Finding types that may contain CVEs
+CVE_RELATED_FINDING_TYPES = [
+    "UnauthorizedAccess:EC2/MaliciousIPCaller",
+    "CryptoCurrency:EC2/BitcoinTool",
+    "Trojan:EC2/",
+    "Backdoor:EC2/",
+    "Behavior:EC2/NetworkPortUnusual",
+    "Recon:EC2/",
+]
+
+
+class GuardDutyControlMapper:
+    """Map AWS GuardDuty findings to compliance control status."""
+
+    def __init__(self, framework: str = "NIST800-53R5"):
+        """
+        Initialize GuardDuty control mapper.
+
+        :param str framework: Compliance framework
+        """
+        self.framework = framework
+        self.mappings = GUARDDUTY_CONTROL_MAPPINGS
+
+    def assess_guardduty_compliance(self, guardduty_data: Dict) -> Dict[str, str]:
+        """
+        Assess GuardDuty compliance against all mapped controls.
+
+        :param Dict guardduty_data: GuardDuty detectors and findings
+        :return: Dictionary mapping control IDs to compliance results (PASS/FAIL)
+        :rtype: Dict[str, str]
+        """
+        results = {}
+
+        if self.framework == "NIST800-53R5":
+            results["SI-4"] = self._assess_si4(guardduty_data)
+            results["IR-4"] = self._assess_ir4(guardduty_data)
+            results["IR-5"] = self._assess_ir5(guardduty_data)
+            results["SI-3"] = self._assess_si3(guardduty_data)
+            results["RA-5"] = self._assess_ra5(guardduty_data)
+
+        return results
+
+    def _assess_si4(self, guardduty_data: Dict) -> str:
+        """
+        Assess SI-4 (System Monitoring) compliance.
+
+        :param Dict guardduty_data: GuardDuty data
+        :return: Compliance result (PASS/FAIL)
+        :rtype: str
+        """
+        detectors = guardduty_data.get("Detectors", [])
+
+        if not detectors:
+            logger.debug("GuardDuty FAILS SI-4: No detectors configured")
+            return "FAIL"
+
+        # Check if any detector is disabled
+        disabled_detectors = [d for d in detectors if d.get("Status") != "ENABLED"]
+        if disabled_detectors:
+            logger.debug(f"GuardDuty FAILS SI-4: {len(disabled_detectors)} detector(s) disabled")
+            return "FAIL"
+
+        logger.debug(f"GuardDuty PASSES SI-4: {len(detectors)} detector(s) enabled and monitoring")
+        return "PASS"
+
+    def _assess_ir4(self, guardduty_data: Dict) -> str:
+        """
+        Assess IR-4 (Incident Handling) compliance.
+
+        :param Dict guardduty_data: GuardDuty data
+        :return: Compliance result (PASS/FAIL)
+        :rtype: str
+        """
+        findings = guardduty_data.get("Findings", [])
+
+        # Check for high/critical severity unaddressed findings
+        high_severity_findings = [
+            f for f in findings if self._get_severity_level(f.get("Severity", 0)) in ["HIGH", "CRITICAL"]
+        ]
+
+        if high_severity_findings:
+            logger.debug(
+                f"GuardDuty FAILS IR-4: {len(high_severity_findings)} high/critical severity "
+                "findings requiring incident response"
+            )
+            return "FAIL"
+
+        logger.debug("GuardDuty PASSES IR-4: No high severity findings requiring immediate attention")
+        return "PASS"
+
+    def _assess_ir5(self, guardduty_data: Dict) -> str:
+        """
+        Assess IR-5 (Incident Monitoring) compliance.
+
+        GuardDuty's active monitoring satisfies IR-5 requirements by providing continuous
+        security monitoring and incident detection capabilities. The presence of GuardDuty
+        itself, along with this integration's tracking of findings, fulfills the control.
+
+        :param Dict guardduty_data: GuardDuty data
+        :return: Compliance result (always PASS when GuardDuty is enabled)
+        :rtype: str
+        """
+        findings = guardduty_data.get("Findings", [])
+
+        # GuardDuty being active satisfies IR-5 (Incident Monitoring)
+        if findings:
+            logger.debug(f"GuardDuty PASSES IR-5: {len(findings)} findings tracked for incident monitoring")
+        else:
+            logger.debug("GuardDuty PASSES IR-5: GuardDuty monitoring active, no incidents detected")
+
+        return "PASS"
+
+    def _assess_si3(self, guardduty_data: Dict) -> str:
+        """
+        Assess SI-3 (Malicious Code Protection) compliance.
+
+        :param Dict guardduty_data: GuardDuty data
+        :return: Compliance result (PASS/FAIL)
+        :rtype: str
+        """
+        detectors = guardduty_data.get("Detectors", [])
+        findings = guardduty_data.get("Findings", [])
+
+        # Check if GuardDuty is enabled (provides malware detection)
+        if not detectors or all(d.get("Status") != "ENABLED" for d in detectors):
+            logger.debug("GuardDuty FAILS SI-3: No enabled detectors for malware protection")
+            return "FAIL"
+
+        # Check for malware-related findings
+        malware_findings = [f for f in findings if self._is_malware_finding(f)]
+
+        if malware_findings:
+            logger.warning(
+                f"GuardDuty malware findings detected: {len(malware_findings)} "
+                "potential malware activities (requires remediation)"
+            )
+
+        logger.debug("GuardDuty PASSES SI-3: Malware protection monitoring enabled")
+        return "PASS"
+
+    def _assess_ra5(self, guardduty_data: Dict) -> str:
+        """
+        Assess RA-5 (Vulnerability Monitoring) compliance.
+
+        :param Dict guardduty_data: GuardDuty data
+        :return: Compliance result (PASS/FAIL)
+        :rtype: str
+        """
+        detectors = guardduty_data.get("Detectors", [])
+
+        # Check if threat intelligence is enabled
+        threat_intel_enabled = any(
+            d.get("DataSources", {}).get("S3Logs", {}).get("Status") == "ENABLED" for d in detectors
+        )
+
+        if not threat_intel_enabled:
+            logger.debug("GuardDuty FAILS RA-5: Threat intelligence data sources not fully enabled")
+            return "FAIL"
+
+        logger.debug("GuardDuty PASSES RA-5: Threat intelligence and vulnerability monitoring active")
+        return "PASS"
+
+    def _get_severity_level(self, severity_score: float) -> str:
+        """
+        Map GuardDuty severity score to severity level.
+
+        :param float severity_score: Severity score (0-10)
+        :return: Severity level (LOW, MEDIUM, HIGH, CRITICAL)
+        :rtype: str
+        """
+        for level, (min_score, max_score) in SEVERITY_MAPPING.items():
+            if min_score <= severity_score <= max_score:
+                return level
+        return "LOW"
+
+    def _is_malware_finding(self, finding: Dict) -> bool:
+        """
+        Check if finding is related to malware.
+
+        :param Dict finding: GuardDuty finding
+        :return: True if malware-related
+        :rtype: bool
+        """
+        finding_type = finding.get("Type", "")
+        malware_indicators = [
+            "Trojan",
+            "Backdoor",
+            "CryptoCurrency",
+            "Malware",
+            "Bitcoin",
+            "CryptoCoin",
+        ]
+        return any(indicator in finding_type for indicator in malware_indicators)
+
+    def has_cve_reference(self, finding: Dict) -> bool:
+        """
+        Check if GuardDuty finding references a CVE.
+
+        :param Dict finding: GuardDuty finding
+        :return: True if CVE referenced
+        :rtype: bool
+        """
+        # Check finding description and title for CVE patterns
+        description = finding.get("Description", "")
+        title = finding.get("Title", "")
+        service = finding.get("Service", {})
+        additional_info = service.get("AdditionalInfo", {})
+
+        # CVE pattern: CVE-YYYY-NNNNN
+        text_to_search = f"{description} {title} {str(additional_info)}"
+        return "CVE-" in text_to_search.upper()
+
+    def extract_cves_from_finding(self, finding: Dict) -> List[str]:
+        """
+        Extract CVE IDs from GuardDuty finding.
+
+        :param Dict finding: GuardDuty finding
+        :return: List of CVE IDs
+        :rtype: List[str]
+        """
+        import re
+
+        cves = []
+        description = finding.get("Description", "")
+        title = finding.get("Title", "")
+        service = finding.get("Service", {})
+        additional_info = str(service.get("AdditionalInfo", {}))
+
+        text_to_search = f"{description} {title} {additional_info}"
+
+        # CVE pattern: CVE-YYYY-NNNNN
+        cve_pattern = r"CVE-\d{4}-\d{4,7}"
+        matches = re.findall(cve_pattern, text_to_search, re.IGNORECASE)
+
+        cves = list({match.upper() for match in matches})
+        return cves
+
+    def get_control_description(self, control_id: str) -> Optional[str]:
+        """Get human-readable description for a control."""
+        control_data = self.mappings.get(control_id)
+        if control_data:
+            return f"{control_data.get('name')}: {control_data.get('description', '')}"
+        return None
+
+    def get_mapped_controls(self) -> List[str]:
+        """Get list of all control IDs mapped for this framework."""
+        return list(self.mappings.keys())
+
+    def get_check_details(self, control_id: str) -> Optional[Dict]:
+        """Get detailed check criteria for a control."""
+        control_data = self.mappings.get(control_id)
+        if control_data:
+            return control_data.get("checks", {})
+        return None