|
| 1 | +# Adding vulnerability report for plugins |
| 2 | + |
| 3 | + |
| 4 | +!!! warning |
| 5 | + This feature is provided as a tech preview and could change in backwards incompatible |
| 6 | + ways in the future. |
| 7 | + |
| 8 | + |
| 9 | +Pulp provides a way to store known vulnerabilities from OSV for `content units` within a specified `RepositoryVersion`. |
| 10 | +Each plugin will need to implement a function to construct the [package payload](https://google.github.io/osv.dev/post-v1-query/#parameters) |
| 11 | +that will be used to query osv.dev database. |
| 12 | + |
| 13 | +!!! note |
| 14 | + As of now, querying by osv.dev `commit` is not supported (use `package` instead). |
| 15 | + |
| 16 | +The first step in writing a vulnerability report for a Pulp `content unit` is to identify the |
| 17 | +package [`ecosystem`](https://google.github.io/osv.dev/post-v1-query/#parameters) by checking |
| 18 | +[https://ossf.github.io/osv-schema/#defined-ecosystems](https://ossf.github.io/osv-schema/#defined-ecosystems). |
| 19 | + |
| 20 | +The next step is to create an async function at the top level of the module (so it can be |
| 21 | +loaded in pulpcore) that will be run as a Pulp task. This async function should return a generator |
| 22 | +object with a dictionary containing the `osv_data` (created through `build_osv_data` function in the following sample), |
| 23 | +and also the `Content` and `RepositoryVersion` objects. |
| 24 | + |
| 25 | +Here is an example of a function with the above steps: |
| 26 | + |
| 27 | +```python |
| 28 | +from asgiref.sync import sync_to_async |
| 29 | +from pulpcore.plugin.models import RepositoryVersion |
| 30 | + |
| 31 | +async def get_content_from_repo_version(repo_version_pk: str): |
| 32 | + repo_version = await sync_to_async(RepositoryVersion.objects.get)(pk=repo_version_pk) |
| 33 | + content_units = await sync_to_async(list)(repo_version.content.all()) |
| 34 | + |
| 35 | + for content_unit in content_units: |
| 36 | + content = await sync_to_async(content_unit.cast)() |
| 37 | + content_name = await sync_to_async(lambda: content.name)() |
| 38 | + content_version = await sync_to_async(lambda: content.version)() |
| 39 | + ecosystem = "PyPI" |
| 40 | + repo_content_osv_data = _build_osv_data(content_name, ecosystem, content_version) |
| 41 | + repo_content_osv_data["repo_version"] = repo_version |
| 42 | + repo_content_osv_data["content"] = content |
| 43 | + yield repo_content_osv_data |
| 44 | + |
| 45 | +def _build_osv_data(name, ecosystem, version=None): |
| 46 | + osv_data = {"package": {"name": name, "ecosystem": ecosystem}} |
| 47 | + if version: |
| 48 | + osv_data["version"] = version |
| 49 | + return osv_data |
| 50 | +``` |
| 51 | + |
| 52 | + |
| 53 | +Now that we have the async generator function, we need to create a `ViewSet` to dispatch a task with it: |
| 54 | + |
| 55 | +!!! note |
| 56 | + In the following sample, we are not defining the permissions to access the endpoint. |
| 57 | + Plugin writters should define them according to each plugin needs. |
| 58 | + |
| 59 | +```python |
| 60 | +from drf_spectacular.utils import extend_schema |
| 61 | +from rest_framework.views import APIView |
| 62 | + |
| 63 | +from pulpcore.plugin.models import VulnerabilityReport |
| 64 | +from pulpcore.plugin.serializers import AsyncOperationResponseSerializer, VulnerabilityReportSerializer |
| 65 | +from pulpcore.plugin.tasking import check_content, dispatch |
| 66 | +from pulpcore.plugin.viewsets import OperationPostponedResponse |
| 67 | + |
| 68 | +from my_plugin.app.serializers import MyPluginVulnerabilityReportSerializer |
| 69 | +from my_plugin.app.utils import get_content_from_repo_version |
| 70 | + |
| 71 | +class MyPluginVulnerabilityReport(APIView): |
| 72 | + |
| 73 | + queryset = VulnerabilityReport.objects.all() |
| 74 | + serializer_class = VulnerabilityReportSerializer |
| 75 | + |
| 76 | + @extend_schema( |
| 77 | + request=MyPluginVulnerabilityReportSerializer, |
| 78 | + description="Trigger a task to generate the package vulnerability report", |
| 79 | + summary="Generate vulnerability report", |
| 80 | + responses={202: AsyncOperationResponseSerializer}, |
| 81 | + ) |
| 82 | + def create(self, request): |
| 83 | + serializer = MyPluginVulnerabilityReportSerializer(data=request.data, context={"request": request}) |
| 84 | + serializer.is_valid(raise_exception=True) |
| 85 | + repo_version = serializer.validated_data["repo_version"] |
| 86 | + |
| 87 | + # we need to pass the function as string because dispatch() args only accepts JSON serializable content |
| 88 | + func = f"{get_content_from_repo_version.__module__}.{get_content_from_repo_version.__name__}" |
| 89 | + |
| 90 | + task = dispatch( |
| 91 | + check_content, |
| 92 | + shared_resources=[repo_version.repository], |
| 93 | + args = (func, [repo_version.pk]), |
| 94 | + ) |
| 95 | + return OperationPostponedResponse(task, request) |
| 96 | +``` |
| 97 | + |
| 98 | +Here is a sample for the `MyPluginVulnerabilityReportSerializer` where we serialize the |
| 99 | +`RepositoryVersion` string into a `RepositoryVersionRelatedField` object: |
| 100 | + |
| 101 | +```python |
| 102 | +from rest_framework import serializers |
| 103 | +from pulpcore.plugin.serializers import ValidateFieldsMixin, RepositoryVersionRelatedField |
| 104 | + |
| 105 | +class MyPluginVulnerabilityReportSerializer(serializers.Serializer, ValidateFieldsMixin): |
| 106 | + |
| 107 | + repo_version = RepositoryVersionRelatedField( |
| 108 | + required=True, |
| 109 | + allow_null=False, |
| 110 | + help_text=_("RepositoryVersion HREF with the packages to be checked."), |
| 111 | + ) |
| 112 | +``` |
0 commit comments