feat(api): add GitHub integration for sending findings as issues

api/src/backend/api/filters.py

@@ -957,6 +957,26 @@ class ProcessorFilter(FilterSet):
     )
 
 
+class IntegrationGitHubFindingsFilter(FilterSet):
+    # To be expanded as needed
+    finding_id = UUIDFilter(field_name="id", lookup_expr="exact")
+    finding_id__in = UUIDInFilter(field_name="id", lookup_expr="in")
+
+    class Meta:
+        model = Finding
+        fields = {}
+
+    def filter_queryset(self, queryset):
+        # Validate that there is at least one filter provided
+        if not self.data:
+            raise ValidationError(
+                {
+                    "findings": "No finding filters provided. At least one filter is required."
+                }
+            )
+        return super().filter_queryset(queryset)
+
+
 class IntegrationJiraFindingsFilter(FilterSet):
     # To be expanded as needed
     finding_id = UUIDFilter(field_name="id", lookup_expr="exact")

api/src/backend/api/models.py

@@ -1586,6 +1586,7 @@ class Integration(RowLevelSecurityProtectedModel):
     class IntegrationChoices(models.TextChoices):
         AMAZON_S3 = "amazon_s3", _("Amazon S3")
         AWS_SECURITY_HUB = "aws_security_hub", _("AWS Security Hub")
+        GITHUB = "github", _("GitHub")
         JIRA = "jira", _("JIRA")
         SLACK = "slack", _("Slack")
 

api/src/backend/api/utils.py

@@ -287,6 +287,20 @@
             integration.save()
 
         return connection
+    elif integration.integration_type == Integration.IntegrationChoices.GITHUB:
+        from prowler.lib.outputs.github.github import GitHub
+
+        github_connection = GitHub.test_connection(
+            **integration.credentials,
+            raise_on_exception=False,
+        )
+        repositories = (
+            github_connection.repositories if github_connection.is_connected else {}
+        )
+        with rls_transaction(str(integration.tenant_id)):
+            integration.configuration["repositories"] = repositories
+            integration.save()
+        return github_connection
     elif integration.integration_type == Integration.IntegrationChoices.JIRA:
         jira_connection = Jira.test_connection(
             **integration.credentials,
@@ -406,9 +420,22 @@
     return serializer.data
 
 
-def initialize_prowler_integration(integration: Integration) -> Jira:
+def initialize_prowler_integration(integration: Integration):
     # TODO Refactor other integrations to use this function
-    if integration.integration_type == Integration.IntegrationChoices.JIRA:
+    if integration.integration_type == Integration.IntegrationChoices.GITHUB:
+        from prowler.lib.outputs.github.exceptions import GitHubAuthenticationError
+        from prowler.lib.outputs.github.github import GitHub
+
+        try:
+            return GitHub(**integration.credentials)
+        except GitHubAuthenticationError as github_auth_error:
+            with rls_transaction(str(integration.tenant_id)):
+                integration.configuration["repositories"] = {}
+                integration.connected = False
+                integration.connection_last_checked_at = datetime.now(tz=timezone.utc)
+                integration.save()
+            raise github_auth_error
+    elif integration.integration_type == Integration.IntegrationChoices.JIRA:
         try:
             return Jira(**integration.credentials)
         except JiraBasicAuthError as jira_auth_error:

api/src/backend/api/v1/serializer_utils/integrations.py

@@ -67,6 +67,14 @@ class Meta:
         resource_name = "integrations"
 
 
+class GitHubConfigSerializer(BaseValidateSerializer):
+    owner = serializers.CharField(read_only=True)
+    repositories = serializers.DictField(read_only=True)
+
+    class Meta:
+        resource_name = "integrations"
+
+
 class JiraConfigSerializer(BaseValidateSerializer):
     domain = serializers.CharField(read_only=True)
     issue_types = serializers.ListField(
@@ -93,6 +101,14 @@ class Meta:
         resource_name = "integrations"
 
 
+class GitHubCredentialSerializer(BaseValidateSerializer):
+    token = serializers.CharField(required=True)
+    owner = serializers.CharField(required=False)
+
+    class Meta:
+        resource_name = "integrations"
+
+
 class JiraCredentialSerializer(BaseValidateSerializer):
     user_mail = serializers.EmailField(required=True)
     api_token = serializers.CharField(required=True)
@@ -153,6 +169,23 @@ class Meta:
                     },
                 },
             },
+            {
+                "type": "object",
+                "title": "GitHub Credentials",
+                "properties": {
+                    "token": {
+                        "type": "string",
+                        "description": "GitHub Personal Access Token (PAT) with repo scope. Can be generated from "
+                        "GitHub Settings > Developer settings > Personal access tokens.",
+                    },
+                    "owner": {
+                        "type": "string",
+                        "description": "Repository owner (username or organization name). Optional - if not provided, "
+                        "all accessible repositories will be available.",
+                    },
+                },
+                "required": ["token"],
+            },
             {
                 "type": "object",
                 "title": "JIRA Credentials",
@@ -221,6 +254,14 @@ class IntegrationCredentialField(serializers.JSONField):
                     },
                 },
             },
+            {
+                "type": "object",
+                "title": "GitHub",
+                "description": "GitHub integration does not accept any configuration in the payload. Leave it as an "
+                "empty JSON object (`{}`).",
+                "properties": {},
+                "additionalProperties": False,
+            },
             {
                 "type": "object",
                 "title": "JIRA",

api/src/backend/api/v1/serializers.py

@@ -54,6 +54,8 @@
 from api.rls import Tenant
 from api.v1.serializer_utils.integrations import (
     AWSCredentialSerializer,
+    GitHubConfigSerializer,
+    GitHubCredentialSerializer,
     IntegrationConfigField,
     IntegrationCredentialField,
     JiraConfigSerializer,
@@ -2432,6 +2434,28 @@ def validate_integration_data(
                     )
             config_serializer = SecurityHubConfigSerializer
             credentials_serializers = [AWSCredentialSerializer]
+        elif integration_type == Integration.IntegrationChoices.GITHUB:
+            if providers:
+                raise serializers.ValidationError(
+                    {
+                        "providers": "Relationship field is not accepted. This integration applies to all providers."
+                    }
+                )
+            if configuration:
+                raise serializers.ValidationError(
+                    {
+                        "configuration": "This integration does not support custom configuration."
+                    }
+                )
+            config_serializer = GitHubConfigSerializer
+            # Create non-editable configuration for GitHub integration
+            configuration.update(
+                {
+                    "repositories": {},
+                    "owner": credentials.get("owner", ""),
+                }
+            )
+            credentials_serializers = [GitHubCredentialSerializer]
         elif integration_type == Integration.IntegrationChoices.JIRA:
             if providers:
                 raise serializers.ValidationError(
@@ -2519,7 +2543,11 @@ def to_representation(self, instance):
                 for provider in representation["providers"]
                 if provider["id"] in allowed_provider_ids
             ]
-        if instance.integration_type == Integration.IntegrationChoices.JIRA:
+        if instance.integration_type == Integration.IntegrationChoices.GITHUB:
+            representation["configuration"].update(
+                {"owner": instance.credentials.get("owner", "")}
+            )
+        elif instance.integration_type == Integration.IntegrationChoices.JIRA:
             representation["configuration"].update(
                 {"domain": instance.credentials.get("domain")}
             )
@@ -2666,6 +2694,51 @@ def to_representation(self, instance):
         return representation
 
 
+class IntegrationGitHubDispatchSerializer(BaseSerializerV1):
+    """
+    Serializer for dispatching findings to GitHub integration.
+    """
+
+    repository = serializers.CharField(required=True)
+    labels = serializers.ListField(
+        child=serializers.CharField(), required=False, default=list
+    )
+
+    class JSONAPIMeta:
+        resource_name = "integrations-github-dispatches"
+
+    def validate(self, attrs):
+        validated_attrs = super().validate(attrs)
+        integration_instance = Integration.objects.get(
+            id=self.context.get("integration_id")
+        )
+        if (
+            integration_instance.integration_type
+            != Integration.IntegrationChoices.GITHUB
+        ):
+            raise ValidationError(
+                {
+                    "integration_type": "The given integration is not a GitHub integration"
+                }
+            )
+
+        if not integration_instance.enabled:
+            raise ValidationError(
+                {"integration": "The given integration is not enabled"}
+            )
+
+        repository = attrs.get("repository")
+        if repository not in integration_instance.configuration.get("repositories", {}):
+            raise ValidationError(
+                {
+                    "repository": "The given repository is not available for this GitHub integration. Refresh the "
+                    "connection if this is an error."
+                }
+            )
+
+        return validated_attrs
+
+
 class IntegrationJiraDispatchSerializer(BaseSerializerV1):
     """
     Serializer for dispatching findings to JIRA integration.

api/src/backend/api/v1/urls.py

@@ -12,6 +12,7 @@
     FindingViewSet,
     GithubSocialLoginView,
     GoogleSocialLoginView,
+    IntegrationGitHubViewSet,
     IntegrationJiraViewSet,
     IntegrationViewSet,
     InvitationAcceptViewSet,
@@ -94,6 +95,9 @@
 integrations_router = routers.NestedSimpleRouter(
     router, r"integrations", lookup="integration"
 )
+integrations_router.register(
+    r"github", IntegrationGitHubViewSet, basename="integration-github"
+)
 integrations_router.register(
     r"jira", IntegrationJiraViewSet, basename="integration-jira"
 )

api/src/backend/api/v1/views.py

@@ -83,6 +83,7 @@
     check_provider_connection_task,
     delete_provider_task,
     delete_tenant_task,
+    github_integration_task,
     jira_integration_task,
     mute_historical_findings_task,
     perform_scan_task,
@@ -105,6 +106,7 @@
     DailySeveritySummaryFilter,
     FindingFilter,
     IntegrationFilter,
+    IntegrationGitHubFindingsFilter,
     IntegrationJiraFindingsFilter,
     InvitationFilter,
     LatestFindingFilter,
@@ -190,6 +192,7 @@
     FindingSerializer,
     FindingsSeverityOverTimeSerializer,
     IntegrationCreateSerializer,
+    IntegrationGitHubDispatchSerializer,
     IntegrationJiraDispatchSerializer,
     IntegrationSerializer,
     IntegrationUpdateSerializer,
@@ -5131,6 +5134,86 @@ def connection(self, request, pk=None):
         )
 
 
+@extend_schema_view(
+    dispatches=extend_schema(
+        tags=["Integration"],
+        summary="Send findings to a GitHub integration",
+        description="Send a set of filtered findings to the given GitHub integration as issues. At least one finding "
+        "filter must be provided.",
+        responses={202: OpenApiResponse(response=TaskSerializer)},
+        filters=True,
+    )
+)
+class IntegrationGitHubViewSet(BaseRLSViewSet):
+    queryset = Finding.all_objects.all()
+    serializer_class = IntegrationGitHubDispatchSerializer
+    http_method_names = ["post"]
+    filter_backends = [CustomDjangoFilterBackend]
+    filterset_class = IntegrationGitHubFindingsFilter
+    # RBAC required permissions
+    required_permissions = [Permissions.MANAGE_INTEGRATIONS]
+
+    @extend_schema(exclude=True)
+    def create(self, request, *args, **kwargs):
+        raise MethodNotAllowed(method="POST")
+
+    def get_queryset(self):
+        tenant_id = self.request.tenant_id
+        user_roles = get_role(self.request.user)
+        if user_roles.unlimited_visibility:
+            # User has unlimited visibility, return all findings
+            queryset = Finding.all_objects.filter(tenant_id=tenant_id)
+        else:
+            # User lacks permission, filter findings based on provider groups associated with the role
+            queryset = Finding.all_objects.filter(
+                scan__provider__in=get_providers(user_roles)
+            )
+
+        return queryset
+
+    @action(detail=False, methods=["post"], url_name="dispatches")
+    def dispatches(self, request, integration_pk=None):
+        get_object_or_404(Integration, pk=integration_pk)
+        serializer = self.get_serializer(
+            data=request.data, context={"integration_id": integration_pk}
+        )
+        serializer.is_valid(raise_exception=True)
+
+        if self.filter_queryset(self.get_queryset()).count() == 0:
+            raise ValidationError(
+                {"findings": "No findings match the provided filters"}
+            )
+
+        finding_ids = [
+            str(finding_id)
+            for finding_id in self.filter_queryset(self.get_queryset()).values_list(
+                "id", flat=True
+            )
+        ]
+        repository = serializer.validated_data["repository"]
+        labels = serializer.validated_data.get("labels", [])
+
+        with transaction.atomic():
+            task = github_integration_task.delay(
+                tenant_id=self.request.tenant_id,
+                integration_id=integration_pk,
+                repository=repository,
+                labels=labels,
+                finding_ids=finding_ids,
+            )
+        prowler_task = Task.objects.get(id=task.id)
+        serializer = TaskSerializer(prowler_task)
+        return Response(
+            data=serializer.data,
+            status=status.HTTP_202_ACCEPTED,
+            headers={
+                "Content-Location": reverse(
+                    "task-detail", kwargs={"pk": prowler_task.id}
+                )
+            },
+        )
+
+
 @extend_schema_view(
     dispatches=extend_schema(
         tags=["Integration"],