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,108 @@
+# 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 store known vulnerabilities from OSV for `content units` within a specified `RepositoryVersion`.
+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).
+
+The next step is to create an async function at the top level of the module (so it can be
+loaded in pulpcore) that will be run as a Pulp task. This async function should return a generator
+object with a dictionary containing the `osv_data` (created through `build_osv_data` function in the following sample),
+and also the `Content` and `RepositoryVersion` objects.
+
+Here is an example of a function with the above steps:
+
+```python
+async def get_content_from_repo_version(repo_version_pk: str):
+    repo_version = await sync_to_async(RepositoryVersion.objects.get)(pk=repo_version_pk)
+    content_units = await sync_to_async(list)(repo_version.content.all())
+    
+    for content_unit in content_units:
+        content = await sync_to_async(content_unit.cast)()
+        content_name = await sync_to_async(lambda: content.name)()
+        content_version = await sync_to_async(lambda: content.version)()
+        ecosystem = "PyPI"
+        repo_content_osv_data = _build_osv_data(content_name, ecosystem, content_version)
+        repo_content_osv_data["repo_version"] = repo_version
+        repo_content_osv_data["content"] = content
+        yield repo_content_osv_data
+
+def _build_osv_data(name, ecosystem, version=None):
+    osv_data = {"package": {"name": name, "ecosystem": ecosystem}}
+    if version:
+        osv_data["version"] = version
+    return osv_data
+```
+
+
+Now that we have the async generator function, we need to create a `ViewSet` to dispatch a task with it:
+
+!!! note
+    In the following sample, we are not defining the permissions to access the endpoint.
+    Plugin writters should define them according to each plugin needs.
+
+```python
+from rest_framework.views import APIView
+
+from pulpcore.plugin.models import VulnerabilityReport
+from pulpcore.plugin.serializers import AsyncOperationResponseSerializer, VulnerabilityReportSerializer
+from pulpcore.plugin.tasking import check_content, dispatch
+from pulpcore.plugin.viewsets import OperationPostponedResponse
+
+from my_plugin.app.serializers import MyPluginVulnerabilityReportSerializer
+from my_plugin.app.utils import get_content_from_repo_version
+
+class MyPluginVulnerabilityReport(APIView):
+
+    queryset = VulnerabilityReport.objects.all()
+    serializer_class = VulnerabilityReportSerializer
+
+    @extend_schema(
+        request=MyPluginVulnerabilityReportSerializer,
+        description="Trigger a task to generate the package vulnerability report",
+        summary="Generate vulnerability report",
+        responses={202: AsyncOperationResponseSerializer},
+    )
+    def create(self, request):
+        serializer = MyPluginVulnerabilityReportSerializer(data=request.data, context={"request": request})
+        serializer.is_valid(raise_exception=True)
+        repo_version = serializer.validated_data["repo_version"]
+        
+        # we need to pass the function as string because dispatch() args only accepts JSON serializable content
+        func = f"{get_content_from_repo_version.__module__}.{get_content_from_repo_version.__name__}"
+
+        task = dispatch(
+            check_content,
+            shared_resources=[repo_version.repository],
+            args = [func, [repo_version.pk]],
+        )
+        return OperationPostponedResponse(task, request)
+```
+
+Here is a sample for the `MyPluginVulnerabilityReportSerializer` where we serialize the
+`RepositoryVersion` string into a `RepositoryVersionRelatedField` object:
+
+```python
+from rest_framework import serializers
+from pulpcore.plugin.serializers import ValidateFieldsMixin, RepositoryVersionRelatedField
+
+class MyPluginVulnerabilityReportSerializer(serializers.Serializer, ValidateFieldsMixin):
+
+    repo_version = RepositoryVersionRelatedField(
+        required=True,
+        allow_null=False,
+        help_text=_("RepositoryVersion HREF with the packages to be checked."),
+    )
+```

pulpcore/app/migrations/0137_vulnerabilityreport.py

@@ -0,0 +1,34 @@
+# Generated by Django 4.2.19 on 2025-08-04 19:29
+
+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', '0136_delete_basedistribution'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='VulnerabilityReport',
+            fields=[
+                ('pulp_created', models.DateTimeField(auto_now_add=True)),
+                ('pulp_last_updated', models.DateTimeField(auto_now=True, null=True)),
+                ('pulp_type', models.TextField(db_index=True, default=None)),
+                ('pulp_id', models.UUIDField(default=pulpcore.app.models.base.pulp_uuid, editable=False, unique=True)),
+                ('content', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='core.content')),
+                ('vulns', models.JSONField()),
+                ('pulp_domain', models.ForeignKey(default=pulpcore.app.util.get_domain_pk, on_delete=django.db.models.deletion.CASCADE, to='core.domain')),
+                ('repo_versions', models.ManyToManyField(blank=True, to='core.repositoryversion')),
+            ],
+            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,24 @@
+from django.db import models
+
+from pulpcore.app.models.base import MasterModel, pulp_uuid
+from pulpcore.app.util import get_domain_pk
+
+
+class VulnerabilityReport(MasterModel):
+    """
+    Model used in vulnerability report.
+    """
+
+    TYPE = "vuln_report"
+    pulp_id = models.UUIDField(default=pulp_uuid, editable=False, unique=True)
+    content = models.OneToOneField(
+        "core.Content",
+        on_delete=models.CASCADE,
+        primary_key=True,
+    )
+    vulns = models.JSONField()
+    pulp_domain = models.ForeignKey("core.Domain", default=get_domain_pk, on_delete=models.CASCADE)
+    repo_versions = models.ManyToManyField("core.RepositoryVersion", blank=True)
+
+    class Meta:
+        default_related_name = "%(app_label)s_%(model_name)s"

pulpcore/app/serializers/__init__.py

@@ -121,6 +121,7 @@
     UserSerializer,
 )
 from .replica import UpstreamPulpSerializer
+from .vulnerability_report import VulnerabilityReportSerializer
 from .openpgp import (
     OpenPGPDistributionSerializer,
     OpenPGPKeyringSerializer,

pulpcore/app/serializers/content.py

@@ -27,6 +27,10 @@ class NoArtifactContentSerializer(base.ModelSerializer):
         view_name_pattern=r"repositories(-.*/.*)-detail",
         queryset=models.Repository.objects.all(),
     )
+    core_vulnerabilityreport = DetailRelatedField(
+        read_only=True,
+        view_name="vuln_report-detail",
+    )
 
     def get_artifacts(self, validated_data):
         """
@@ -116,6 +120,7 @@ class Meta:
         fields = base.ModelSerializer.Meta.fields + (
             "repository",
             "pulp_labels",
+            "core_vulnerabilityreport",
         )
 
 

pulpcore/app/serializers/repository.py

@@ -491,6 +491,12 @@ class RepositoryVersionSerializer(ModelSerializer, NestedHyperlinkedModelSeriali
         read_only=True,
     )
 
+    core_vulnerabilityreport = DetailRelatedField(
+        many=True,
+        read_only=True,
+        view_name="vuln_report-detail",
+    )
+
     class Meta:
         model = models.RepositoryVersion
         fields = ModelSerializer.Meta.fields + (
@@ -499,6 +505,7 @@ class Meta:
             "repository",
             "base_version",
             "content_summary",
+            "core_vulnerabilityreport",
         )
 
 

pulpcore/app/serializers/vulnerability_report.py

@@ -0,0 +1,27 @@
+from rest_framework import serializers
+
+from pulpcore.app.models import VulnerabilityReport
+from pulpcore.app.serializers import (
+    DetailRelatedField,
+    IdentityField,
+    ModelSerializer,
+    RepositoryVersionRelatedField,
+)
+
+
+class VulnerabilityReportSerializer(ModelSerializer):
+    """
+    A serializer for the VulnerabilityReport Model.
+    """
+
+    vulns = serializers.JSONField()
+    pulp_href = IdentityField(view_name="vuln_report-detail")
+    content = DetailRelatedField(
+        read_only=True,
+        view_name_pattern=r"content(-.*/.*)-detail",
+    )
+    repo_versions = RepositoryVersionRelatedField(many=True, required=False)
+
+    class Meta:
+        model = VulnerabilityReport
+        fields = ModelSerializer.Meta.fields + ("vulns", "repo_versions", "content")