Add the vulnerability report

closes: #6773

Author: git-hyagi

CHANGES/6773.feature

@@ -0,0 +1 @@
+Added the vulnerability report data model.

docs/admin/reference/tech-preview.md

@@ -5,4 +5,5 @@ The following features are currently being released as part of tech preview:
 - [Support for Open Telemetry](site:pulpcore/docs/admin/learn/architecture/#telemetry-support)
 - Upstream replicas
 - Domains - Multi-Tenancy
-- [Checkpoint](site:pulpcore/docs/user/guides/checkpoint/)
+- [Checkpoint](site:pulpcore/docs/user/guides/checkpoint/)
+- [Vulnerability Report](site:pulpcore/docs/dev/learn/other/vulnerability-report/)

docs/dev/learn/other/vulnerability-report.md

@@ -0,0 +1,98 @@
+# Adding vulnerability report for plugins
+
+
+!!! warning
+    This feature is provided as a tech preview and could change in backwards incompatible
+    ways in the future.
+
+
+Pulp provides a way to verify the `content units` against the [osv.dev](https://osv.dev) database.
+Each plugin will need to implement a function to construct the [package payload](https://google.github.io/osv.dev/post-v1-query/#parameters)
+that will be used to query osv.dev database.
+
+!!! note
+    As of now, querying by osv.dev `commit` is not supported (use `package` instead).
+
+The first step in writing a vulnerability report for a Pulp `content unit` is to identify the
+package [`ecosystem`](https://google.github.io/osv.dev/post-v1-query/#parameters) by checking
+[https://ossf.github.io/osv-schema/#defined-ecosystems](https://ossf.github.io/osv-schema/#defined-ecosystems).
+
+After identifying the `ecosystem`, run the `pulpcore.app.tasks.vulnerability_report.build_osv_data`
+function that will return a dictionary with the expected osv.dev payload format.
+
+The next step is to create a function that will be run as a Pulp task. This function should add the
+dictionary, created in the previous step, to the `pulpcore.app.tasks.vulnerability_report.content_queue`
+queue.
+
+Here is an example of a function that, based on a `RepositoryVersion pk`, adds each content found
+in the Repository in `content_queue` after identifying the `ecosystem` and creating a dictionary
+with the osv.dev expected format:
+
+!!! note
+    For the following example, we are using the `pulpcore.app.tasks.vulnerability_report.identify_package_ecosystem`
+    helper function, but plugin writers are encouraged to write their own function to better identify
+    the ecosystem.
+
+```python
+from pulpcore.app.tasks.vulnerability_report import build_osv_data, content_queue, identify_package_ecosystem
+
+def get_content_from_repo_version(repo_version_pk: str):
+    """
+    Populate content_queue Queue with the content_units found in RepositoryVersion
+    """
+    repo_version = RepositoryVersion.objects.get(pk=repo_version_pk)
+    for content_unit in repo_version.content:
+        content = content_unit.cast()
+        ecosystems = identify_package_ecosystem(content, repo_version.repository)
+        for ecosystem in ecosystems:
+            osv_data = build_osv_data(content.name, ecosystem, content.version)
+            content_queue.put(osv_data)
+    content_queue.put(None)  # signal that there are no more content_units
+```
+
+
+Now that we have the function to populate the `content_queue` queue, we need to create a `ViewSet`
+to dispatch a task with it:
+
+```python
+from pulpcore.plugin.models import VulnerabilityReport
+from pulpcore.app.serializers.vulnerability_report import VulnerabilityReportSerializer
+from pulpcore.app.tasks.vulnerability_report import check_content
+from pulpcore.app.viewsets.vulnerability_report import VulnerabilityReport as VulnerabilityReportView
+
+class MyPluginVulnerabilityReport(VulnerabilityReportView):
+
+    endpoint_name = "vuln_report"
+    queryset = VulnerabilityReport.objects.all()
+    serializer_class = VulnerabilityReportSerializer
+
+    @extend_schema(
+        request=MyPluginContentVulnerabilityReportSerializer,
+        description="Trigger a task to generate the package vulnerability report",
+        summary="Generate vulnerability report",
+        responses={202: AsyncOperationResponseSerializer},
+    )
+    def create(self, request):
+        serializer = MyPluginContentVulnerabilityReportSerializer(data=request.data, context={"request": request})
+        serializer.is_valid(raise_exception=True)
+        shared_resources = [repo_version.repository]
+        dispatch_task, kwargs = check_content, {"repo_version_pk": repo_version.pk}
+        task = dispatch(dispatch_task, shared_resources=shared_resources, kwargs=kwargs)
+        return OperationPostponedResponse(task, request)
+```
+
+Here is a sample for the `MyPluginContentVulnerabilityReportSerializer` where we serialize the
+`RepositoryVersion` string into a `RepositoryVersionRelatedField` object:
+
+```python
+from rest_framework import serializers
+from pulpcore.plugin.serializers import ValidateFieldsMixin, RepositoryVersionRelatedField
+
+class MyPluginContentVulnerabilityReportSerializer(serializers.Serializer, ValidateFieldsMixin):
+
+    repo_version = RepositoryVersionRelatedField(
+        required=False,
+        allow_null=True,
+        help_text=_("RepositoryVersion HREF with the packages to be checked."),
+    )
+```

pulpcore/app/migrations/0134_vulnerabilityreport.py

@@ -0,0 +1,31 @@
+# Generated by Django 4.2.19 on 2025-07-14 19:37
+
+from django.db import migrations, models
+import django.db.models.deletion
+import django_lifecycle.mixins
+import pulpcore.app.models.base
+import pulpcore.app.util
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0133_repositoryversion_content_ids'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='VulnerabilityReport',
+            fields=[
+                ('pulp_id', models.UUIDField(default=pulpcore.app.models.base.pulp_uuid, editable=False, primary_key=True, serialize=False)),
+                ('pulp_created', models.DateTimeField(auto_now_add=True)),
+                ('pulp_last_updated', models.DateTimeField(auto_now=True, null=True)),
+                ('vulns', models.JSONField()),
+                ('pulp_domain', models.ForeignKey(default=pulpcore.app.util.get_domain_pk, on_delete=django.db.models.deletion.CASCADE, to='core.domain')),
+            ],
+            options={
+                'default_related_name': '%(app_label)s_%(model_name)s',
+            },
+            bases=(django_lifecycle.mixins.LifecycleModelMixin, models.Model),
+        ),
+    ]

pulpcore/app/models/__init__.py

@@ -87,6 +87,8 @@
     UploadChunk,
 )
 
+from .vulnerability_report import VulnerabilityReport
+
 # Moved here to avoid a circular import with Task
 from .progress import GroupProgressReport, ProgressReport
 
@@ -170,4 +172,5 @@
     "OpenPGPSignature",
     "OpenPGPUserAttribute",
     "OpenPGPUserID",
+    "VulnerabilityReport",
 ]

pulpcore/app/models/vulnerability_report.py

@@ -0,0 +1,16 @@
+from django.db import models
+
+from pulpcore.app.models import BaseModel
+from pulpcore.plugin.util import get_domain_pk
+
+
+class VulnerabilityReport(BaseModel):
+    """
+    Model used in vulnerability report.
+    """
+
+    vulns = models.JSONField()
+    pulp_domain = models.ForeignKey("core.Domain", default=get_domain_pk, on_delete=models.CASCADE)
+
+    class Meta:
+        default_related_name = "%(app_label)s_%(model_name)s"

pulpcore/app/serializers/vulnerability_report.py

@@ -0,0 +1,17 @@
+from rest_framework import serializers
+
+from pulpcore.plugin.models import VulnerabilityReport
+from pulpcore.plugin.serializers import IdentityField, ModelSerializer
+
+
+class VulnerabilityReportSerializer(ModelSerializer):
+    """
+    A serializer for the VulnerabilityReport Model.
+    """
+
+    vulns = serializers.JSONField()
+    pulp_href = IdentityField(view_name="vuln_report-detail")
+
+    class Meta:
+        model = VulnerabilityReport
+        fields = ModelSerializer.Meta.fields + ("vulns",)