Group advisories with common identifiers and same affected range

CHANGELOG.rst

@@ -1,6 +1,12 @@
 Release notes
 =============
 
+Version v38.0.0
+---------------------
+
+- This is a major version, we have changed our V3 API, refer to ``api_v3_usage.rst`` for details.
+- We have started grouping advisories which have aliases or identifiers in common and also affect same set of packages together.
+
 Version v37.0.0
 ---------------------
 

PIPELINES-AVID.rst

@@ -55,7 +55,7 @@
    * - project-kb-statements_v2
      - Vulnerability ID of the record
    * - pypa_importer_v2
-     - ID of the OSV record
+     - {package_name}/{ID of the OSV record}
    * - pysec_importer_v2
      - ID of the OSV record
    * - redhat_importer_v2

api_v3_usage.rst

@@ -0,0 +1,254 @@
+Package Endpoint
+================
+
+We are migrating from **API v1** to **API v3**.
+
+Previously, the ``/api/packages`` endpoint exposed multiple routes:
+
+- ``bulk_search``
+- ``bulk_lookup``
+- ``lookup``
+- ``all``
+
+In **API v3**, all these capabilities are consolidated into a **single endpoint**:
+
+::
+
+    POST /api/v3/packages
+
+
+Pagination
+----------
+
+Responses from the package endpoint are **always paginated**, with **10 results per page**.
+
+Each response includes:
+
+- ``count`` — total number of results
+- ``next`` — URL for the next page
+- ``previous`` — URL for the previous page
+
+If a package is associated with **more than 100 advisories**, the response will include:
+
+- ``affected_by_vulnerabilities_url`` instead of ``affected_by_vulnerabilities``
+- ``fixing_vulnerabilities_url`` instead of ``fixing_vulnerabilities``
+
+
+Getting All Vulnerable Packages
+-------------------------------
+
+Instead of calling ``/api/packages/all``, call the v3 endpoint with an empty ``purls`` list.
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": []
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 596,
+        "next": "http://example.com/api/v3/packages?page=2",
+        "previous": null,
+        "results": [
+            "pkg:npm/626@1.1.1",
+            "pkg:npm/aedes@0.35.0",
+            "pkg:npm/airbrake@0.3.8",
+            "pkg:npm/angular-http-server@1.4.3",
+            "pkg:npm/apex-publish-static-files@2.0.0",
+            "pkg:npm/atob@2.0.3",
+            "pkg:npm/augustine@0.2.3",
+            "pkg:npm/backbone@0.3.3",
+            "pkg:npm/base64-url@1.3.3",
+            "pkg:npm/base64url@2.0.0"
+        ]
+    }
+
+
+Bulk Search (Replacement)
+-------------------------
+
+Instead of calling ``/api/packages/bulk_search``, use:
+
+::
+
+    POST /api/v3/packages
+
+Parameters:
+
+- ``purls`` — list of package URLs to query
+- ``details`` — boolean (default: ``false``)
+- ``ignore_qualifiers_subpath`` — boolean (default: ``false``)
+
+The ``ignore_qualifiers_subpath`` flag replaces the previous ``plain_purl`` parameter.  
+When set to ``true``, qualifiers and subpaths in PURLs are ignored.
+
+
+Get Only Vulnerable PURLs
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"],
+        "details": false
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            "pkg:npm/atob@2.0.3"
+        ]
+    }
+
+
+Get Detailed Vulnerability Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"],
+        "details": true
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            {
+                "purl": "pkg:npm/atob@2.0.3",
+                "affected_by_vulnerabilities": [
+                    {
+                    "advisory_id": "GHSA-g5vw-3h65-2q3v",
+                    "aliases": [],
+                    "weighted_severity": null,
+                    "exploitability_score": null,
+                    "risk_score": null,
+                    "summary": "Access control vulnerable to user data",
+                    "fixed_by_packages": [
+                        "pkg:pypi/accesscontrol@7.2"
+                    ],
+                },
+                ],
+                "fixing_vulnerabilities": [],
+                "next_non_vulnerable_version": "2.1.0",
+                "latest_non_vulnerable_version": "2.1.0",
+                "risk_score": null
+            }
+        ]
+    }
+
+
+Using Approximate Matching
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3?foo=bar"],
+        "ignore_qualifiers_subpath": true,
+        "details": true
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            {
+                "purl": "pkg:npm/atob@2.0.3",
+                "affected_by_vulnerabilities": [
+                {
+                    "advisory_id": "GHSA-g5vw-3h65-2q3v",
+                    "aliases": [],
+                    "weighted_severity": null,
+                    "exploitability_score": null,
+                    "risk_score": null,
+                    "summary": "Access control vulnerable to user data",
+                    "fixed_by_packages": [
+                        "pkg:pypi/accesscontrol@7.2"
+                    ],
+                }
+                ],
+                "fixing_vulnerabilities": [],
+                "next_non_vulnerable_version": "2.1.0",
+                "latest_non_vulnerable_version": "2.1.0",
+                "risk_score": null
+            }
+        ]
+    }
+
+
+Advisory Endpoint
+=================
+
+Retrieve advisories for one or more PURLs:
+
+::
+
+    POST /api/v3/advisories
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"]
+    }
+
+Responses are paginated (10 results per page) and include ``next`` and ``previous`` links.
+
+
+Affected-By Advisories Endpoint
+===============================
+
+Retrieve advisories that **affect (impact)** a given PURL:
+
+::
+
+    GET /api/v3/affected-by-advisories?purl=<purl>
+
+Example:
+
+::
+
+    GET /api/v3/affected-by-advisories?purl=pkg:npm/atob@2.0.3
+
+
+Fixing Advisories Endpoint
+==========================
+
+Retrieve advisories that are **fixed by** a given PURL:
+
+::
+
+    GET /api/v3/fixing-advisories?purl=<purl>
+
+Example:
+
+::
+
+    GET /api/v3/fixing-advisories?purl=pkg:npm/atob@2.1.0

etc/nginx/conf.d/default.conf

@@ -12,6 +12,8 @@ server {
         proxy_redirect off;
         client_max_body_size 10G;
         proxy_read_timeout 600s;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
     }
 
     location /static/ {

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = vulnerablecode
-version = 37.0.0
+version = 38.0.0
 license = Apache-2.0 AND CC-BY-SA-4.0
 
 # description must be on ONE line https://github.com/pypa/setuptools/issues/1390