Add docs, changelog, and refine the implementation

Signed-off-by: tdruez <tdruez@nexb.com>

Author: tdruez

CHANGELOG.rst

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+v35.1.0 (unreleased)
+--------------------
+
+- Add a ``--fail-on-vulnerabilities`` option in ``check-compliance`` management command.
+  When this option is enabled, the command will exit with a non-zero status if known
+  vulnerabilities are detected in discovered packages and dependencies.
+  Requires the ``find_vulnerabilities`` pipeline to be executed beforehand.
+  https://github.com/aboutcode-org/scancode.io/pull/1702
+
 v35.0.0 (2025-06-23)
 --------------------
 

docs/command-line-interface.rst

@@ -497,6 +497,10 @@ Optional arguments:
 - ``--fail-level {ERROR,WARNING,MISSING}`` Compliance alert level that will cause the
   command to exit with a non-zero status. Default is ERROR.
 
+- ``--fail-on-vulnerabilities`` Exit with a non-zero status if known vulnerabilities
+  are detected in discovered packages and dependencies.
+  Requires the ``find_vulnerabilities`` pipeline to be executed beforehand.
+
 `$ scanpipe archive-project --project PROJECT`
 ----------------------------------------------
 

scanpipe/management/commands/check-compliance.py

@@ -86,21 +86,10 @@ def check_compliance(self, fail_level):
         return count > 0
 
     def check_vulnerabilities(self):
-        # TODO: Remove duplication with scanpipe.pipes.output.add_vulnerabilities_sheet
-        vulnerable_packages_queryset = (
-            self.project.discoveredpackages.vulnerable()
-            .only_package_url_fields(extra=["affected_by_vulnerabilities"])
-            .order_by_package_url()
-        )
-        vulnerable_dependencies_queryset = (
-            self.project.discovereddependencies.vulnerable()
-            .only_package_url_fields(extra=["affected_by_vulnerabilities"])
-            .order_by_package_url()
-        )
+        packages = self.project.discoveredpackages.vulnerable_ordered()
+        dependencies = self.project.discovereddependencies.vulnerable_ordered()
 
-        vulnerable_records = list(vulnerable_packages_queryset) + list(
-            vulnerable_dependencies_queryset
-        )
+        vulnerable_records = list(packages) + list(dependencies)
         count = len(vulnerable_records)
 
         if self.verbosity > 0:

scanpipe/models.py

@@ -3150,6 +3150,13 @@ class VulnerabilityQuerySetMixin:
     def vulnerable(self):
         return self.filter(~Q(affected_by_vulnerabilities__in=EMPTY_VALUES))
 
+    def vulnerable_ordered(self):
+        return (
+            self.vulnerable()
+            .only_package_url_fields(extra=["affected_by_vulnerabilities"])
+            .order_by_package_url()
+        )
+
 
 class DiscoveredPackageQuerySet(
     VulnerabilityQuerySetMixin,

scanpipe/pipes/output.py

@@ -567,21 +567,11 @@ def to_xlsx(project):
 
 
 def add_vulnerabilities_sheet(workbook, project):
-    vulnerable_packages_queryset = (
-        DiscoveredPackage.objects.project(project)
-        .vulnerable()
-        .only_package_url_fields(extra=["affected_by_vulnerabilities"])
-        .order_by_package_url()
-    )
-    vulnerable_dependencies_queryset = (
-        DiscoveredDependency.objects.project(project)
-        .vulnerable()
-        .only_package_url_fields(extra=["affected_by_vulnerabilities"])
-        .order_by_package_url()
-    )
+    vulnerable_packages = project.discoveredpackages.vulnerable_ordered()
+    vulnerable_dependencies = project.discovereddependencies.vulnerable_ordered()
     vulnerable_querysets = [
-        vulnerable_packages_queryset,
-        vulnerable_dependencies_queryset,
+        vulnerable_packages,
+        vulnerable_dependencies,
     ]
 
     vulnerability_fields = [

scanpipe/tests/test_commands.py

@@ -49,6 +49,7 @@
 from scanpipe.pipes import flag
 from scanpipe.pipes import purldb
 from scanpipe.tests import filter_warnings
+from scanpipe.tests import make_dependency
 from scanpipe.tests import make_mock_response
 from scanpipe.tests import make_package
 from scanpipe.tests import make_project
@@ -1224,8 +1225,12 @@ def test_scanpipe_management_command_check_compliance_vulnerabilities(self):
         out_value = out.getvalue().strip()
         self.assertEqual("No vulnerabilities found", out_value)
 
-        package1.update(
-            affected_by_vulnerabilities=[{"vulnerability_id": "VCID-cah8-awtr-aaad"}]
+        vulnerability_data = [{"vulnerability_id": "VCID-cah8-awtr-aaad"}]
+        package1.update(affected_by_vulnerabilities=vulnerability_data)
+        make_dependency(
+            project,
+            dependency_uid="dependency1",
+            affected_by_vulnerabilities=vulnerability_data,
         )
         out = StringIO()
         options = ["--project", project.name, "--fail-on-vulnerabilities"]
@@ -1234,7 +1239,11 @@ def test_scanpipe_management_command_check_compliance_vulnerabilities(self):
         self.assertEqual(cm.exception.code, 1)
         out_value = out.getvalue().strip()
         expected = (
-            "1 vulnerable records found:\npkg:generic/name@1.0\n > VCID-cah8-awtr-aaad"
+            "2 vulnerable records found:\n"
+            "pkg:generic/name@1.0\n"
+            " > VCID-cah8-awtr-aaad\n"
+            "dependency1\n"
+            " > VCID-cah8-awtr-aaad"
         )
         self.assertEqual(expected, out_value)