Add the vulnerability report

closes: #6773

Author: git-hyagi

CHANGES/6773.feature

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

docs/admin/reference/settings.md

@@ -392,6 +392,12 @@ This is [recommended by aiohttp] for performance improvements.
 The `uvloop` python package must be installed in the content-app's system.
 That's available as an optional dependency for pulpcore: `pulpcore[uvloop]`.
 
+### VULN\_REPORT\_TASK\_LIMITER
+
+This number determines the amount of concurrent vulnerability report processes that can be spawned
+at one time. Increasing this number will generally increase the speed of the task, but will also
+consume more resources of the worker. Defaults to 10 concurrent processes.
+
 ### WORKER\_TTL
 
 The number of seconds before a worker should be considered lost.

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,80 @@
+# 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
+from asgiref.sync import sync_to_async
+from pulpcore.plugin.models import RepositoryVersion
+from pulpcore.plugin.sync import sync_to_async_iterable
+from myplugin.app.models import MyPluginContent
+
+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 = MyPluginContent.objects.filter(pk__in=repo_version.content)
+    ecosystem = "MyContentUnitEcosystem" # Content unit ecosystem from osv.dev (for ex "PyPI" for python content unit)
+    async for content in sync_to_async_iterable(content_units):
+        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 new method in the plugin
+RepositoryVersionViewSet subclass (the plugin class that inherits from core.RepositoryVersionViewSet)
+that will be used to dispatch the `vulnerability report` task.
+
+!!! 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 drf_spectacular.utils import extend_schema
+from rest_framework.decorators import action
+
+from pulpcore.plugin import viewsets as core_viewsets
+from pulpcore.plugin.tasking import check_content, dispatch
+
+class MyPluginRepositoryVersionViewSet(core_viewsets.RepositoryVersionViewSet):
+    parent_viewset = MyPluginRepositoryViewSet
+
+    @extend_schema(summary="Generate vulnerability report", responses={202: AsyncOperationResponseSerializer})
+    @action(detail=True, methods=["post"])
+    def scan(self, request, repository_pk, **kwargs):
+        repository_version = self.get_object()
+        func = f"{get_content_from_repo_version.__module__}.{get_content_from_repo_version.__name__}"
+        task = dispatch(
+            check_content,
+            shared_resources=[repository_version.repository],
+            args=[func, [repository_version.pk]],
+        )
+        return core_viewsets.OperationPostponedResponse(task, request)
+```

pulpcore/app/migrations/0137_vulnerabilityreport.py

@@ -0,0 +1,33 @@
+# Generated by Django 4.2.19 on 2025-08-07 00:07
+
+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_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()),
+                ('content', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, to='core.content')),
+                ('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,34 @@
+from django.db import models
+
+from pulpcore.app.models.base import BaseModel
+from pulpcore.app.util import get_domain_pk
+
+
+class VulnerabilityReport(BaseModel):
+    """
+    A model for storing vulnerability reports for Content/RepositoryVersion.
+
+    Fields:
+        vulns (models.JSONField): A JSON field containing the list of vulnerabilities found
+            in osv.dev.
+
+    Relations:
+        content (models.OneToOneField): The Content object that was scanned for vulnerabilities.
+        pulp_domain (models.ForeignKey): The Domain this vulnerability report belongs to,
+            providing multi-tenancy isolation.
+        repo_versions (models.ManyToManyField): The RepositoryVersion(s) where the scanned
+            Content appears. This allows tracking which repository versions contain
+            vulnerable content.
+    """
+
+    content = models.OneToOneField(
+        "Content",
+        on_delete=models.CASCADE,
+        unique=True,
+    )
+    vulns = models.JSONField()
+    pulp_domain = models.ForeignKey("Domain", default=get_domain_pk, on_delete=models.CASCADE)
+    repo_versions = models.ManyToManyField("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

@@ -5,7 +5,13 @@
 from rest_framework.validators import UniqueValidator
 
 from pulpcore.app import models
-from pulpcore.app.serializers import base, fields, pulp_labels_validator, DetailRelatedField
+from pulpcore.app.serializers import (
+    base,
+    fields,
+    pulp_labels_validator,
+    DetailRelatedField,
+    RelatedField,
+)
 from pulpcore.app.util import get_domain
 
 
@@ -27,6 +33,11 @@ class NoArtifactContentSerializer(base.ModelSerializer):
         view_name_pattern=r"repositories(-.*/.*)-detail",
         queryset=models.Repository.objects.all(),
     )
+    vuln_report = RelatedField(
+        read_only=True,
+        view_name="vuln_report-detail",
+        source="core_vulnerabilityreport",
+    )
 
     def get_artifacts(self, validated_data):
         """
@@ -116,6 +127,7 @@ class Meta:
         fields = base.ModelSerializer.Meta.fields + (
             "repository",
             "pulp_labels",
+            "vuln_report",
         )
 
 

pulpcore/app/serializers/repository.py

@@ -7,7 +7,7 @@
 from rest_framework_nested.serializers import NestedHyperlinkedModelSerializer
 
 from pulpcore.app import models, settings
-from pulpcore.app.util import get_prn
+from pulpcore.app.util import get_prn, reverse
 from pulpcore.app.serializers import (
     DetailIdentityField,
     DetailRelatedField,
@@ -490,6 +490,12 @@ class RepositoryVersionSerializer(ModelSerializer, NestedHyperlinkedModelSeriali
         source="*",
         read_only=True,
     )
+    vuln_report = serializers.SerializerMethodField(
+        read_only=True,
+    )
+
+    def get_vuln_report(self, object):
+        return f"{reverse('vuln_report-list')}?repository_version={get_prn(object)}"
 
     class Meta:
         model = models.RepositoryVersion
@@ -499,6 +505,7 @@ class Meta:
             "repository",
             "base_version",
             "content_summary",
+            "vuln_report",
         )