feat(attack-surfaces): add new endpoints to retrieve overview data (#9309)

Author: vicferpoy

api/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to the **Prowler API** are documented in this file.
 
 ## [1.16.0] (Unreleased)
 
+### Added
+- New endpoint to retrieve an overview of the attack surfaces [(#9309)](https://github.com/prowler-cloud/prowler/pull/9309)
+
 ### Changed
 - Restore the compliance overview endpoint's mandatory filters [(#9330)](https://github.com/prowler-cloud/prowler/pull/9330)
 

api/pyproject.toml

@@ -44,7 +44,7 @@ name = "prowler-api"
 package-mode = false
 # Needed for the SDK compatibility
 requires-python = ">=3.11,<3.13"
-version = "1.15.0"
+version = "1.16.0"
 
 [project.scripts]
 celery = "src.backend.config.settings.celery"

api/src/backend/api/apps.py

@@ -40,6 +40,7 @@ def ready(self):
             self._ensure_crypto_keys()
 
         load_prowler_compliance()
+        self._initialize_attack_surface_mapping()
 
     def _ensure_crypto_keys(self):
         """
@@ -167,3 +168,13 @@ def _generate_jwt_keys(self):
                 f"Error generating JWT keys: {e}. Please set '{SIGNING_KEY_ENV}' and '{VERIFYING_KEY_ENV}' manually."
             )
             raise e
+
+    def _initialize_attack_surface_mapping(self):
+        from tasks.jobs.scan import (  # noqa: F401
+            _get_attack_surface_mapping_from_provider,
+        )
+
+        from api.models import Provider  # noqa: F401
+
+        for provider_type, _label in Provider.ProviderChoices.choices:
+            _get_attack_surface_mapping_from_provider(provider_type)

api/src/backend/api/filters.py

@@ -23,6 +23,7 @@
     StatusEnumField,
 )
 from api.models import (
+    AttackSurfaceOverview,
     ComplianceRequirementOverview,
     Finding,
     Integration,
@@ -1013,3 +1014,22 @@ class Meta:
             "inserted_at": ["date", "gte", "lte"],
             "overall_score": ["exact", "gte", "lte"],
         }
+
+
+class AttackSurfaceOverviewFilter(FilterSet):
+    """Filter for attack surface overview aggregations by provider."""
+
+    provider_id = UUIDFilter(field_name="scan__provider__id", lookup_expr="exact")
+    provider_id__in = UUIDInFilter(field_name="scan__provider__id", lookup_expr="in")
+    provider_type = ChoiceFilter(
+        field_name="scan__provider__provider", choices=Provider.ProviderChoices.choices
+    )
+    provider_type__in = ChoiceInFilter(
+        field_name="scan__provider__provider",
+        choices=Provider.ProviderChoices.choices,
+        lookup_expr="in",
+    )
+
+    class Meta:
+        model = AttackSurfaceOverview
+        fields = {}

api/src/backend/api/migrations/0060_attack_surface_overview.py

@@ -0,0 +1,89 @@
+# Generated by Django 5.1.14 on 2025-11-19 13:03
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+import api.rls
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("api", "0059_compliance_overview_summary"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="AttackSurfaceOverview",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("inserted_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "attack_surface_type",
+                    models.CharField(
+                        choices=[
+                            ("internet-exposed", "Internet Exposed"),
+                            ("secrets", "Exposed Secrets"),
+                            ("privilege-escalation", "Privilege Escalation"),
+                            ("ec2-imdsv1", "EC2 IMDSv1 Enabled"),
+                        ],
+                        max_length=50,
+                    ),
+                ),
+                ("total_findings", models.IntegerField(default=0)),
+                ("failed_findings", models.IntegerField(default=0)),
+                ("muted_failed_findings", models.IntegerField(default=0)),
+            ],
+            options={
+                "db_table": "attack_surface_overviews",
+                "abstract": False,
+            },
+        ),
+        migrations.AddField(
+            model_name="attacksurfaceoverview",
+            name="scan",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="attack_surface_overviews",
+                related_query_name="attack_surface_overview",
+                to="api.scan",
+            ),
+        ),
+        migrations.AddField(
+            model_name="attacksurfaceoverview",
+            name="tenant",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE, to="api.tenant"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="attacksurfaceoverview",
+            index=models.Index(
+                fields=["tenant_id", "scan_id"], name="attack_surf_tenant_scan_idx"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="attacksurfaceoverview",
+            constraint=models.UniqueConstraint(
+                fields=("tenant_id", "scan_id", "attack_surface_type"),
+                name="unique_attack_surface_per_scan",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="attacksurfaceoverview",
+            constraint=api.rls.RowLevelSecurityConstraint(
+                "tenant_id",
+                name="rls_on_attacksurfaceoverview",
+                statements=["SELECT", "INSERT", "UPDATE", "DELETE"],
+            ),
+        ),
+    ]

api/src/backend/api/models.py

@@ -2405,3 +2405,63 @@ class Meta(RowLevelSecurityProtectedModel.Meta):
 
     class JSONAPIMeta:
         resource_name = "threatscore-snapshots"
+
+
+class AttackSurfaceOverview(RowLevelSecurityProtectedModel):
+    """
+    Pre-aggregated attack surface metrics per scan.
+
+    Stores counts for each attack surface type (internet-exposed, secrets,
+    privilege-escalation, ec2-imdsv1) to enable fast overview queries.
+    """
+
+    class AttackSurfaceTypeChoices(models.TextChoices):
+        INTERNET_EXPOSED = "internet-exposed", _("Internet Exposed")
+        SECRETS = "secrets", _("Exposed Secrets")
+        PRIVILEGE_ESCALATION = "privilege-escalation", _("Privilege Escalation")
+        EC2_IMDSV1 = "ec2-imdsv1", _("EC2 IMDSv1 Enabled")
+
+    id = models.UUIDField(primary_key=True, default=uuid4, editable=False)
+    inserted_at = models.DateTimeField(auto_now_add=True, editable=False)
+
+    scan = models.ForeignKey(
+        Scan,
+        on_delete=models.CASCADE,
+        related_name="attack_surface_overviews",
+        related_query_name="attack_surface_overview",
+    )
+
+    attack_surface_type = models.CharField(
+        max_length=50,
+        choices=AttackSurfaceTypeChoices.choices,
+    )
+
+    # Finding counts
+    total_findings = models.IntegerField(default=0)  # All findings (PASS + FAIL)
+    failed_findings = models.IntegerField(default=0)  # Non-muted failed findings
+    muted_failed_findings = models.IntegerField(default=0)  # Muted failed findings
+
+    class Meta(RowLevelSecurityProtectedModel.Meta):
+        db_table = "attack_surface_overviews"
+
+        constraints = [
+            models.UniqueConstraint(
+                fields=("tenant_id", "scan_id", "attack_surface_type"),
+                name="unique_attack_surface_per_scan",
+            ),
+            RowLevelSecurityConstraint(
+                field="tenant_id",
+                name="rls_on_%(class)s",
+                statements=["SELECT", "INSERT", "UPDATE", "DELETE"],
+            ),
+        ]
+
+        indexes = [
+            models.Index(
+                fields=["tenant_id", "scan_id"],
+                name="attack_surf_tenant_scan_idx",
+            ),
+        ]
+
+    class JSONAPIMeta:
+        resource_name = "attack-surface-overviews"

api/src/backend/api/rbac/permissions.py

@@ -65,11 +65,11 @@ def get_providers(role: Role) -> QuerySet[Provider]:
         A QuerySet of Provider objects filtered by the role's provider groups.
         If the role has no provider groups, returns an empty queryset.
     """
-    tenant = role.tenant
+    tenant_id = role.tenant_id
     provider_groups = role.provider_groups.all()
     if not provider_groups.exists():
         return Provider.objects.none()
 
     return Provider.objects.filter(
-        tenant=tenant, provider_groups__in=provider_groups
+        tenant_id=tenant_id, provider_groups__in=provider_groups
     ).distinct()

api/src/backend/api/specs/v1.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Prowler API
-  version: 1.15.0
+  version: 1.16.0
   description: |-
     Prowler API specification.
 
@@ -4497,6 +4497,60 @@ paths:
       responses:
         '204':
           description: No response body
+  /api/v1/overviews/attack-surfaces:
+    get:
+      operationId: overviews_attack_surfaces_retrieve
+      description: Retrieve aggregated attack surface metrics from latest completed
+        scans per provider.
+      summary: Get attack surface overview
+      parameters:
+      - in: query
+        name: fields[attack-surface-overviews]
+        schema:
+          type: array
+          items:
+            type: string
+            enum:
+            - id
+            - total_findings
+            - failed_findings
+            - muted_failed_findings
+            - check_ids
+        description: endpoint return only specific fields in the response on a per-type
+          basis by including a fields[TYPE] query parameter.
+        explode: false
+      - in: query
+        name: filter[provider_id.in]
+        schema:
+          type: string
+        description: Filter by multiple provider IDs (comma-separated UUIDs)
+      - in: query
+        name: filter[provider_id]
+        schema:
+          type: string
+          format: uuid
+        description: Filter by specific provider ID
+      - in: query
+        name: filter[provider_type.in]
+        schema:
+          type: string
+        description: Filter by multiple provider types (comma-separated)
+      - in: query
+        name: filter[provider_type]
+        schema:
+          type: string
+        description: Filter by provider type (aws, azure, gcp, etc.)
+      tags:
+      - Overview
+      security:
+      - JWT or API Key: []
+      responses:
+        '200':
+          content:
+            application/vnd.api+json:
+              schema:
+                $ref: '#/components/schemas/AttackSurfaceOverviewResponse'
+          description: ''
   /api/v1/overviews/findings:
     get:
       operationId: overviews_findings_retrieve
@@ -10618,6 +10672,49 @@ paths:
           description: ''
 components:
   schemas:
+    AttackSurfaceOverview:
+      type: object
+      required:
+      - type
+      - id
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          description: The [type](https://jsonapi.org/format/#document-resource-object-identification)
+            member is used to describe resource objects that share common attributes
+            and relationships.
+          enum:
+          - attack-surface-overviews
+        id: {}
+        attributes:
+          type: object
+          properties:
+            id:
+              type: string
+            total_findings:
+              type: integer
+            failed_findings:
+              type: integer
+            muted_failed_findings:
+              type: integer
+            check_ids:
+              type: array
+              items:
+                type: string
+              readOnly: true
+          required:
+          - id
+          - total_findings
+          - failed_findings
+          - muted_failed_findings
+    AttackSurfaceOverviewResponse:
+      type: object
+      properties:
+        data:
+          $ref: '#/components/schemas/AttackSurfaceOverview'
+      required:
+      - data
     ComplianceOverview:
       type: object
       required: