feat(threatscore): implement ThreatScoreSnapshot model, filter, serializer, and view for ThreatScore metrics retrieval (#9148)

api/src/backend/tasks/jobs/report.py

@@ -7,7 +7,6 @@ from shutil import rmtree
 import matplotlib.pyplot as plt
 from celery.utils.log import get_task_logger
 from config.django.base import DJANGO_FINDINGS_BATCH_SIZE, DJANGO_TMP_OUTPUT_DIRECTORY
-from django.db.models import Count, Q
 from reportlab.lib import colors
 from reportlab.lib.enums import TA_CENTER
 from reportlab.lib.pagesizes import letter
@@ -26,11 +25,22 @@ from reportlab.platypus import (
     TableStyle,
 )
 from tasks.jobs.export import _generate_output_directory, _upload_to_s3
+from tasks.jobs.threatscore import compute_threatscore_metrics
+from tasks.jobs.threatscore_utils import (
+    _aggregate_requirement_statistics_from_database,
+    _calculate_requirements_data_from_statistics,
+)
 from tasks.utils import batched
 
 from api.db_router import READ_REPLICA_ALIAS
 from api.db_utils import rls_transaction
-from api.models import Finding, Provider, ScanSummary, StatusChoices
+from api.models import (
+    Finding,
+    Provider,
+    ScanSummary,
+    StatusChoices,
+    ThreatScoreSnapshot,
+)
 from api.utils import initialize_prowler_provider
 from prowler.lib.check.compliance_models import Compliance
 from prowler.lib.outputs.finding import Finding as FindingOutput
@@ -434,56 +444,6 @@ def _add_pdf_footer(canvas_obj: canvas.Canvas, doc: SimpleDocTemplate) -> None:
     canvas_obj.drawString(width - text_width - 30, 20, powered_text)
 
 
-def _aggregate_requirement_statistics_from_database(
-    tenant_id: str, scan_id: str
-) -> dict[str, dict[str, int]]:
-    """
-    Aggregate finding statistics by check_id using database aggregation.
-
-    This function uses Django ORM aggregation to calculate pass/fail statistics
-    entirely in the database, avoiding the need to load findings into memory.
-
-    Args:
-        tenant_id (str): The tenant ID for Row-Level Security context.
-        scan_id (str): The ID of the scan to retrieve findings for.
-
-    Returns:
-        dict[str, dict[str, int]]: Dictionary mapping check_id to statistics:
-            - 'passed' (int): Number of passed findings for this check
-            - 'total' (int): Total number of findings for this check
-
-    Example:
-        {
-            'aws_iam_user_mfa_enabled': {'passed': 10, 'total': 15},
-            'aws_s3_bucket_public_access': {'passed': 0, 'total': 5}
-        }
-    """
-    requirement_statistics_by_check_id = {}
-
-    with rls_transaction(tenant_id, using=READ_REPLICA_ALIAS):
-        # Use database aggregation to calculate stats without loading findings into memory
-        aggregated_statistics_queryset = (
-            Finding.all_objects.filter(tenant_id=tenant_id, scan_id=scan_id)
-            .values("check_id")
-            .annotate(
-                total_findings=Count("id"),
-                passed_findings=Count("id", filter=Q(status=StatusChoices.PASS)),
-            )
-        )
-
-        for aggregated_stat in aggregated_statistics_queryset:
-            check_id = aggregated_stat["check_id"]
-            requirement_statistics_by_check_id[check_id] = {
-                "passed": aggregated_stat["passed_findings"],
-                "total": aggregated_stat["total_findings"],
-            }
-
-    logger.info(
-        f"Aggregated statistics for {len(requirement_statistics_by_check_id)} unique checks"
-    )
-    return requirement_statistics_by_check_id
-
-
 def _load_findings_for_requirement_checks(
     tenant_id: str, scan_id: str, check_ids: list[str], prowler_provider
 ) -> dict[str, list[FindingOutput]]:
@@ -544,84 +504,6 @@ def _load_findings_for_requirement_checks(
     return dict(findings_by_check_id)
 
 
-def _calculate_requirements_data_from_statistics(
-    compliance_obj, requirement_statistics_by_check_id: dict[str, dict[str, int]]
-) -> tuple[dict[str, dict], list[dict]]:
-    """
-    Calculate requirement status and statistics using pre-aggregated database statistics.
-
-    This function uses O(n) lookups with pre-aggregated statistics from the database,
-    avoiding the need to iterate over all findings for each requirement.
-
-    Args:
-        compliance_obj: The compliance framework object containing requirements.
-        requirement_statistics_by_check_id (dict[str, dict[str, int]]): Pre-aggregated statistics
-            mapping check_id to {'passed': int, 'total': int} counts.
-
-    Returns:
-        tuple[dict[str, dict], list[dict]]: A tuple containing:
-            - attributes_by_requirement_id: Dictionary mapping requirement IDs to their attributes.
-            - requirements_list: List of requirement dictionaries with status and statistics.
-    """
-    attributes_by_requirement_id = {}
-    requirements_list = []
-
-    compliance_framework = getattr(compliance_obj, "Framework", "N/A")
-    compliance_version = getattr(compliance_obj, "Version", "N/A")
-
-    for requirement in compliance_obj.Requirements:
-        requirement_id = requirement.Id
-        requirement_description = getattr(requirement, "Description", "")
-        requirement_checks = getattr(requirement, "Checks", [])
-        requirement_attributes = getattr(requirement, "Attributes", [])
-
-        # Store requirement metadata for later use
-        attributes_by_requirement_id[requirement_id] = {
-            "attributes": {
-                "req_attributes": requirement_attributes,
-                "checks": requirement_checks,
-            },
-            "description": requirement_description,
-        }
-
-        # Calculate aggregated passed and total findings for this requirement
-        total_passed_findings = 0
-        total_findings_count = 0
-
-        for check_id in requirement_checks:
-            if check_id in requirement_statistics_by_check_id:
-                check_statistics = requirement_statistics_by_check_id[check_id]
-                total_findings_count += check_statistics["total"]
-                total_passed_findings += check_statistics["passed"]
-
-        # Determine overall requirement status based on findings
-        if total_findings_count > 0:
-            if total_passed_findings == total_findings_count:
-                requirement_status = StatusChoices.PASS
-            else:
-                # Partial pass or complete fail both count as FAIL
-                requirement_status = StatusChoices.FAIL
-        else:
-            # No findings means manual review required
-            requirement_status = StatusChoices.MANUAL
-
-        requirements_list.append(
-            {
-                "id": requirement_id,
-                "attributes": {
-                    "framework": compliance_framework,
-                    "version": compliance_version,
-                    "status": requirement_status,
-                    "description": requirement_description,
-                    "passed_findings": total_passed_findings,
-                    "total_findings": total_findings_count,
-                },
-            }
-        )
-
-    return attributes_by_requirement_id, requirements_list
-
-
 def generate_threatscore_report(
     tenant_id: str,
     scan_id: str,
@@ -1262,8 +1144,9 @@ def generate_threatscore_report_job(
     2. Checks provider type compatibility
     3. Generates the output directory
     4. Calls generate_threatscore_report to create the PDF
-    5. Uploads the PDF to S3
-    6. Cleans up temporary files
+    5. Computes and stores ThreatScore metrics snapshot
+    6. Uploads the PDF to S3
+    7. Cleans up temporary files
 
     Args:
         tenant_id (str): The tenant ID for Row-Level Security context.
@@ -1317,6 +1200,66 @@ def generate_threatscore_report_job(
         min_risk_level=4,
     )
 
+    # Compute and store ThreatScore metrics snapshot
+    logger.info(f"Computing ThreatScore metrics for scan {scan_id}")
+    try:
+        metrics = compute_threatscore_metrics(
+            tenant_id=tenant_id,
+            scan_id=scan_id,
+            provider_id=provider_id,
+            compliance_id=compliance_id,
+            min_risk_level=4,
+        )
+
+        # Create snapshot in database
+        with rls_transaction(tenant_id):
+            # Get previous snapshot for the same provider to calculate delta
+            previous_snapshot = (
+                ThreatScoreSnapshot.objects.filter(
+                    tenant_id=tenant_id,
+                    provider_id=provider_id,
+                    compliance_id=compliance_id,
+                )
+                .order_by("-inserted_at")
+                .first()
+            )
+
+            # Calculate score delta (improvement)
+            score_delta = None
+            if previous_snapshot:
+                score_delta = metrics["overall_score"] - float(
+                    previous_snapshot.overall_score
+                )
+
+            snapshot = ThreatScoreSnapshot.objects.create(
+                tenant_id=tenant_id,
+                scan_id=scan_id,
+                provider_id=provider_id,
+                compliance_id=compliance_id,
+                overall_score=metrics["overall_score"],
+                score_delta=score_delta,
+                section_scores=metrics["section_scores"],
+                critical_requirements=metrics["critical_requirements"],
+                total_requirements=metrics["total_requirements"],
+                passed_requirements=metrics["passed_requirements"],
+                failed_requirements=metrics["failed_requirements"],
+                manual_requirements=metrics["manual_requirements"],
+                total_findings=metrics["total_findings"],
+                passed_findings=metrics["passed_findings"],
+                failed_findings=metrics["failed_findings"],
+            )
+
+            delta_msg = (
+                f" (delta: {score_delta:+.2f}%)" if score_delta is not None else ""
+            )
+            logger.info(
+                f"ThreatScore snapshot created with ID {snapshot.id} "
+                f"(score: {snapshot.overall_score}%{delta_msg})"
+            )
+    except Exception as e:
+        # Log error but don't fail the job if snapshot creation fails
+        logger.error(f"Error creating ThreatScore snapshot: {e}")
+
     upload_uri = _upload_to_s3(
         tenant_id,
         scan_id,

api/src/backend/tasks/jobs/threatscore.py

@@ -0,0 +1,214 @@
+from celery.utils.log import get_task_logger
+from tasks.jobs.threatscore_utils import (
+    _aggregate_requirement_statistics_from_database,
+    _calculate_requirements_data_from_statistics,
+)
+
+from api.db_router import READ_REPLICA_ALIAS
+from api.db_utils import rls_transaction
+from api.models import Provider, StatusChoices
+from prowler.lib.check.compliance_models import Compliance
+
+logger = get_task_logger(__name__)
+
+
+def compute_threatscore_metrics(
+    tenant_id: str,
+    scan_id: str,
+    provider_id: str,
+    compliance_id: str,
+    min_risk_level: int = 4,
+) -> dict:
+    """
+    Compute ThreatScore metrics for a given scan.
+
+    This function calculates all the metrics needed for a ThreatScore snapshot:
+    - Overall ThreatScore percentage
+    - Section-by-section scores
+    - Critical failed requirements (risk >= min_risk_level)
+    - Summary statistics (requirements and findings counts)
+
+    Args:
+        tenant_id (str): The tenant ID for Row-Level Security context.
+        scan_id (str): The ID of the scan to analyze.
+        provider_id (str): The ID of the provider used in the scan.
+        compliance_id (str): Compliance framework ID (e.g., "prowler_threatscore_aws").
+        min_risk_level (int): Minimum risk level for critical requirements. Defaults to 4.
+
+    Returns:
+        dict: A dictionary containing:
+            - overall_score (float): Overall ThreatScore percentage (0-100)
+            - section_scores (dict): Section name -> score percentage mapping
+            - critical_requirements (list): List of critical failed requirement dicts
+            - total_requirements (int): Total number of requirements
+            - passed_requirements (int): Number of PASS requirements
+            - failed_requirements (int): Number of FAIL requirements
+            - manual_requirements (int): Number of MANUAL requirements
+            - total_findings (int): Total findings count
+            - passed_findings (int): Passed findings count
+            - failed_findings (int): Failed findings count
+
+    Example:
+        >>> metrics = compute_threatscore_metrics(
+        ...     tenant_id="tenant-123",
+        ...     scan_id="scan-456",
+        ...     provider_id="provider-789",
+        ...     compliance_id="prowler_threatscore_aws"
+        ... )
+        >>> print(f"Overall ThreatScore: {metrics['overall_score']:.2f}%")
+    """
+    # Get provider and compliance information
+    with rls_transaction(tenant_id, using=READ_REPLICA_ALIAS):
+        provider_obj = Provider.objects.get(id=provider_id)
+        provider_type = provider_obj.provider
+
+        frameworks_bulk = Compliance.get_bulk(provider_type)
+        compliance_obj = frameworks_bulk[compliance_id]
+
+    # Aggregate requirement statistics from database
+    requirement_statistics_by_check_id = (
+        _aggregate_requirement_statistics_from_database(tenant_id, scan_id)
+    )
+
+    # Calculate requirements data using aggregated statistics
+    attributes_by_requirement_id, requirements_list = (
+        _calculate_requirements_data_from_statistics(
+            compliance_obj, requirement_statistics_by_check_id
+        )
+    )
+
+    # Initialize metrics
+    overall_numerator = 0
+    overall_denominator = 0
+    overall_has_findings = False
+
+    sections_data = {}
+
+    total_requirements = len(requirements_list)
+    passed_requirements = 0
+    failed_requirements = 0
+    manual_requirements = 0
+    total_findings = 0
+    passed_findings = 0
+    failed_findings = 0
+
+    critical_requirements_list = []
+
+    # Process each requirement
+    for requirement in requirements_list:
+        requirement_id = requirement["id"]
+        requirement_status = requirement["attributes"]["status"]
+        requirement_attributes = attributes_by_requirement_id.get(requirement_id, {})
+
+        # Count requirements by status
+        if requirement_status == StatusChoices.PASS:
+            passed_requirements += 1
+        elif requirement_status == StatusChoices.FAIL:
+            failed_requirements += 1
+        elif requirement_status == StatusChoices.MANUAL:
+            manual_requirements += 1
+
+        # Get findings data
+        req_passed_findings = requirement["attributes"].get("passed_findings", 0)
+        req_total_findings = requirement["attributes"].get("total_findings", 0)
+
+        # Accumulate findings counts
+        total_findings += req_total_findings
+        passed_findings += req_passed_findings
+        failed_findings += req_total_findings - req_passed_findings
+
+        # Skip requirements with no findings
+        if req_total_findings == 0:
+            continue
+
+        overall_has_findings = True
+
+        # Get requirement metadata
+        metadata = requirement_attributes.get("attributes", {}).get(
+            "req_attributes", []
+        )
+        if not metadata or len(metadata) == 0:
+            continue
+
+        m = metadata[0]
+        risk_level = getattr(m, "LevelOfRisk", 0)
+        weight = getattr(m, "Weight", 0)
+        section = getattr(m, "Section", "Unknown")
+
+        # Calculate ThreatScore components using formula from UI
+        rate_i = req_passed_findings / req_total_findings
+        rfac_i = 1 + 0.25 * risk_level
+
+        # Update overall score
+        overall_numerator += rate_i * req_total_findings * weight * rfac_i
+        overall_denominator += req_total_findings * weight * rfac_i
+
+        # Update section scores
+        if section not in sections_data:
+            sections_data[section] = {
+                "numerator": 0,
+                "denominator": 0,
+                "has_findings": False,
+            }
+
+        sections_data[section]["has_findings"] = True
+        sections_data[section]["numerator"] += (
+            rate_i * req_total_findings * weight * rfac_i
+        )
+        sections_data[section]["denominator"] += req_total_findings * weight * rfac_i
+
+        # Identify critical failed requirements
+        if requirement_status == StatusChoices.FAIL and risk_level >= min_risk_level:
+            critical_requirements_list.append(
+                {
+                    "requirement_id": requirement_id,
+                    "title": getattr(m, "Title", "N/A"),
+                    "section": section,
+                    "subsection": getattr(m, "SubSection", "N/A"),
+                    "risk_level": risk_level,
+                    "weight": weight,
+                    "passed_findings": req_passed_findings,
+                    "total_findings": req_total_findings,
+                    "description": getattr(m, "AttributeDescription", "N/A"),
+                }
+            )
+
+    # Calculate overall ThreatScore
+    if not overall_has_findings:
+        overall_score = 100.0
+    elif overall_denominator > 0:
+        overall_score = (overall_numerator / overall_denominator) * 100
+    else:
+        overall_score = 0.0
+
+    # Calculate section scores
+    section_scores = {}
+    for section, data in sections_data.items():
+        if data["has_findings"] and data["denominator"] > 0:
+            section_scores[section] = (data["numerator"] / data["denominator"]) * 100
+        else:
+            section_scores[section] = 100.0
+
+    # Sort critical requirements by risk level (desc) and weight (desc)
+    critical_requirements_list.sort(
+        key=lambda x: (x["risk_level"], x["weight"]), reverse=True
+    )
+
+    logger.info(
+        f"ThreatScore computed: {overall_score:.2f}% "
+        f"({passed_requirements}/{total_requirements} requirements passed, "
+        f"{len(critical_requirements_list)} critical failures)"
+    )
+
+    return {
+        "overall_score": round(overall_score, 2),
+        "section_scores": {k: round(v, 2) for k, v in section_scores.items()},
+        "critical_requirements": critical_requirements_list,
+        "total_requirements": total_requirements,
+        "passed_requirements": passed_requirements,
+        "failed_requirements": failed_requirements,
+        "manual_requirements": manual_requirements,
+        "total_findings": total_findings,
+        "passed_findings": passed_findings,
+        "failed_findings": failed_findings,
+    }

api/src/backend/tasks/jobs/threatscore_utils.py

@@ -0,0 +1,127 @@
+from celery.utils.log import get_task_logger
+from django.db.models import Count, Q
+
+from api.db_router import READ_REPLICA_ALIAS
+from api.db_utils import rls_transaction
+from api.models import Finding, StatusChoices
+
+logger = get_task_logger(__name__)
+
+
+def _aggregate_requirement_statistics_from_database(
+    tenant_id: str, scan_id: str
+) -> dict[str, dict[str, int]]:
+    """
+    Aggregate finding statistics by check_id using database aggregation.
+
+    This function uses Django ORM aggregation to calculate pass/fail statistics
+    entirely in the database, avoiding the need to load findings into memory.
+
+    Args:
+        tenant_id (str): The tenant ID for Row-Level Security context.
+        scan_id (str): The ID of the scan to retrieve findings for.
+
+    Returns:
+        dict[str, dict[str, int]]: Dictionary mapping check_id to statistics:
+            - 'passed' (int): Number of passed findings for this check
+            - 'total' (int): Total number of findings for this check
+
+    Example:
+        {
+            'aws_iam_user_mfa_enabled': {'passed': 10, 'total': 15},
+            'aws_s3_bucket_public_access': {'passed': 0, 'total': 5}
+        }
+    """
+    requirement_statistics_by_check_id = {}
+
+    with rls_transaction(tenant_id, using=READ_REPLICA_ALIAS):
+        aggregated_statistics_queryset = (
+            Finding.all_objects.filter(tenant_id=tenant_id, scan_id=scan_id)
+            .values("check_id")
+            .annotate(
+                total_findings=Count("id"),
+                passed_findings=Count("id", filter=Q(status=StatusChoices.PASS)),
+            )
+        )
+
+        for aggregated_stat in aggregated_statistics_queryset:
+            check_id = aggregated_stat["check_id"]
+            requirement_statistics_by_check_id[check_id] = {
+                "passed": aggregated_stat["passed_findings"],
+                "total": aggregated_stat["total_findings"],
+            }
+
+    logger.info(
+        f"Aggregated statistics for {len(requirement_statistics_by_check_id)} unique checks"
+    )
+    return requirement_statistics_by_check_id
+
+
+def _calculate_requirements_data_from_statistics(
+    compliance_obj, requirement_statistics_by_check_id: dict[str, dict[str, int]]
+) -> tuple[dict[str, dict], list[dict]]:
+    """
+    Calculate requirement status and statistics using pre-aggregated database statistics.
+
+    Args:
+        compliance_obj: The compliance framework object containing requirements.
+        requirement_statistics_by_check_id (dict[str, dict[str, int]]): Pre-aggregated statistics
+            mapping check_id to {'passed': int, 'total': int} counts.
+
+    Returns:
+        tuple[dict[str, dict], list[dict]]: A tuple containing:
+            - attributes_by_requirement_id: Dictionary mapping requirement IDs to their attributes.
+            - requirements_list: List of requirement dictionaries with status and statistics.
+    """
+    attributes_by_requirement_id = {}
+    requirements_list = []
+
+    compliance_framework = getattr(compliance_obj, "Framework", "N/A")
+    compliance_version = getattr(compliance_obj, "Version", "N/A")
+
+    for requirement in compliance_obj.Requirements:
+        requirement_id = requirement.Id
+        requirement_description = getattr(requirement, "Description", "")
+        requirement_checks = getattr(requirement, "Checks", [])
+        requirement_attributes = getattr(requirement, "Attributes", [])
+
+        attributes_by_requirement_id[requirement_id] = {
+            "attributes": {
+                "req_attributes": requirement_attributes,
+                "checks": requirement_checks,
+            },
+            "description": requirement_description,
+        }
+
+        total_passed_findings = 0
+        total_findings_count = 0
+
+        for check_id in requirement_checks:
+            if check_id in requirement_statistics_by_check_id:
+                check_statistics = requirement_statistics_by_check_id[check_id]
+                total_findings_count += check_statistics["total"]
+                total_passed_findings += check_statistics["passed"]
+
+        if total_findings_count > 0:
+            if total_passed_findings == total_findings_count:
+                requirement_status = StatusChoices.PASS
+            else:
+                requirement_status = StatusChoices.FAIL
+        else:
+            requirement_status = StatusChoices.MANUAL
+
+        requirements_list.append(
+            {
+                "id": requirement_id,
+                "attributes": {
+                    "framework": compliance_framework,
+                    "version": compliance_version,
+                    "status": requirement_status,
+                    "description": requirement_description,
+                    "passed_findings": total_passed_findings,
+                    "total_findings": total_findings_count,
+                },
+            }
+        )
+
+    return attributes_by_requirement_id, requirements_list

api/src/backend/tasks/tests/test_report.py

@@ -1,19 +1,25 @@
 import uuid
+from datetime import timedelta
+from decimal import Decimal
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import matplotlib
 import pytest
+from django.utils import timezone
+from freezegun import freeze_time
 from tasks.jobs.report import (
-    _aggregate_requirement_statistics_from_database,
-    _calculate_requirements_data_from_statistics,
     _load_findings_for_requirement_checks,
     generate_threatscore_report,
     generate_threatscore_report_job,
 )
+from tasks.jobs.threatscore_utils import (
+    _aggregate_requirement_statistics_from_database,
+    _calculate_requirements_data_from_statistics,
+)
 from tasks.tasks import generate_threatscore_report_task
 
-from api.models import Finding, StatusChoices
+from api.models import Finding, Scan, StateChoices, StatusChoices, ThreatScoreSnapshot
 from prowler.lib.check.models import Severity
 
 matplotlib.use("Agg")  # Use non-interactive backend for tests
@@ -39,6 +45,7 @@ class TestGenerateThreatscoreReport:
             assert result == {"upload": False}
             mock_filter.assert_called_once_with(scan_id=self.scan_id)
 
+    @patch("tasks.jobs.report.ThreatScoreSnapshot.objects.create")
     @patch("tasks.jobs.report.rmtree")
     @patch("tasks.jobs.report._upload_to_s3")
     @patch("tasks.jobs.report.generate_threatscore_report")
@@ -53,6 +60,7 @@ class TestGenerateThreatscoreReport:
         mock_generate_report,
         mock_upload,
         mock_rmtree,
+        mock_snapshot_create,
     ):
         mock_scan_summary_filter.return_value.exists.return_value = True
 
@@ -95,8 +103,10 @@ class TestGenerateThreatscoreReport:
             Path("/tmp/threatscore_path_threatscore_report.pdf").parent,
             ignore_errors=True,
         )
+        mock_snapshot_create.assert_called_once()
 
-    def test_generate_threatscore_report_fails_upload(self):
+    @patch("tasks.jobs.report.ThreatScoreSnapshot.objects.create")
+    def test_generate_threatscore_report_fails_upload(self, mock_snapshot_create):
         with (
             patch("tasks.jobs.report.ScanSummary.objects.filter") as mock_filter,
             patch("tasks.jobs.report.Provider.objects.get") as mock_provider_get,
@@ -125,8 +135,12 @@ class TestGenerateThreatscoreReport:
             )
 
             assert result == {"upload": False}
+            mock_snapshot_create.assert_called_once()
 
-    def test_generate_threatscore_report_logs_rmtree_exception(self, caplog):
+    @patch("tasks.jobs.report.ThreatScoreSnapshot.objects.create")
+    def test_generate_threatscore_report_logs_rmtree_exception(
+        self, mock_snapshot_create, caplog
+    ):
         with (
             patch("tasks.jobs.report.ScanSummary.objects.filter") as mock_filter,
             patch("tasks.jobs.report.Provider.objects.get") as mock_provider_get,
@@ -160,8 +174,10 @@ class TestGenerateThreatscoreReport:
                     provider_id=self.provider_id,
                 )
                 assert "Error deleting output files" in caplog.text
+                mock_snapshot_create.assert_called_once()
 
-    def test_generate_threatscore_report_azure_provider(self):
+    @patch("tasks.jobs.report.ThreatScoreSnapshot.objects.create")
+    def test_generate_threatscore_report_azure_provider(self, mock_snapshot_create):
         with (
             patch("tasks.jobs.report.ScanSummary.objects.filter") as mock_filter,
             patch("tasks.jobs.report.Provider.objects.get") as mock_provider_get,
@@ -200,6 +216,135 @@ class TestGenerateThreatscoreReport:
                 only_failed=True,
                 min_risk_level=4,
             )
+            mock_snapshot_create.assert_called_once()
+
+    @patch("tasks.jobs.report.rmtree")
+    @patch(
+        "tasks.jobs.report._upload_to_s3",
+        return_value="s3://bucket/threatscore/threatscore_report.pdf",
+    )
+    @patch("tasks.jobs.report.generate_threatscore_report")
+    @patch("tasks.jobs.report._generate_output_directory")
+    @patch("tasks.jobs.report.ScanSummary.objects.filter")
+    @patch("tasks.jobs.report.compute_threatscore_metrics")
+    @pytest.mark.django_db
+    @freeze_time("2025-01-10T12:00:00Z")
+    def test_generate_threatscore_report_persists_snapshot_and_delta(
+        self,
+        mock_compute_metrics,
+        mock_scan_summary_filter,
+        mock_generate_output_directory,
+        mock_generate_report,
+        mock_upload,
+        mock_rmtree,
+        tenants_fixture,
+        providers_fixture,
+    ):
+        tenant = tenants_fixture[0]
+        provider = providers_fixture[0]
+
+        scan_previous = Scan.objects.create(
+            tenant=tenant,
+            provider=provider,
+            name="previous-threatscore-scan",
+            trigger=Scan.TriggerChoices.MANUAL,
+            state=StateChoices.COMPLETED,
+            started_at=timezone.now() - timedelta(hours=4),
+            completed_at=timezone.now() - timedelta(hours=3),
+        )
+        ThreatScoreSnapshot.objects.create(
+            tenant=tenant,
+            scan=scan_previous,
+            provider=provider,
+            compliance_id="prowler_threatscore_aws",
+            overall_score=Decimal("70.00"),
+            score_delta=None,
+            section_scores={"1. IAM": "65.00"},
+            critical_requirements=[],
+            total_requirements=50,
+            passed_requirements=35,
+            failed_requirements=15,
+            manual_requirements=0,
+            total_findings=40,
+            passed_findings=25,
+            failed_findings=15,
+        )
+
+        scan_current = Scan.objects.create(
+            tenant=tenant,
+            provider=provider,
+            name="current-threatscore-scan",
+            trigger=Scan.TriggerChoices.MANUAL,
+            state=StateChoices.COMPLETED,
+            started_at=timezone.now() - timedelta(hours=2),
+            completed_at=timezone.now() - timedelta(hours=1),
+        )
+
+        mock_scan_summary_filter.return_value.exists.return_value = True
+        mock_generate_output_directory.return_value = (
+            "/tmp/output",
+            "/tmp/compressed",
+            "/tmp/threatscore_path",
+        )
+
+        metrics = {
+            "overall_score": 85.5,
+            "score_delta": 10.0,
+            "section_scores": {"1. IAM": 82.3, "2. Attack Surface": 60.0},
+            "critical_requirements": [
+                {
+                    "requirement_id": "req_new",
+                    "title": "New high-risk requirement",
+                    "section": "1. IAM",
+                    "subsection": "Root Account",
+                    "risk_level": 5,
+                    "weight": 150,
+                    "passed_findings": 7,
+                    "total_findings": 10,
+                    "description": "Critical requirement description",
+                }
+            ],
+            "total_requirements": 140,
+            "passed_requirements": 100,
+            "failed_requirements": 40,
+            "manual_requirements": 0,
+            "total_findings": 200,
+            "passed_findings": 150,
+            "failed_findings": 50,
+        }
+        mock_compute_metrics.return_value = metrics
+
+        result = generate_threatscore_report_job(
+            tenant_id=str(tenant.id),
+            scan_id=str(scan_current.id),
+            provider_id=str(provider.id),
+        )
+
+        assert result == {"upload": True}
+        mock_compute_metrics.assert_called_once_with(
+            tenant_id=str(tenant.id),
+            scan_id=str(scan_current.id),
+            provider_id=str(provider.id),
+            compliance_id="prowler_threatscore_aws",
+            min_risk_level=4,
+        )
+        mock_generate_report.assert_called_once()
+        mock_upload.assert_called_once()
+        mock_rmtree.assert_called_once()
+
+        snapshots = ThreatScoreSnapshot.objects.filter(
+            tenant=tenant, provider=provider
+        ).order_by("inserted_at")
+        assert snapshots.count() == 2
+
+        new_snapshot = ThreatScoreSnapshot.objects.get(scan=scan_current)
+        assert new_snapshot.compliance_id == "prowler_threatscore_aws"
+        assert Decimal(new_snapshot.overall_score) == Decimal("85.50")
+        assert Decimal(new_snapshot.score_delta) == Decimal("15.50")
+        assert new_snapshot.section_scores == metrics["section_scores"]
+        assert new_snapshot.critical_requirements == metrics["critical_requirements"]
+        assert new_snapshot.total_requirements == metrics["total_requirements"]
+        assert new_snapshot.total_findings == metrics["total_findings"]
 
 
 @pytest.mark.django_db