Skip to content

1943 refactor doc to restructure and improve #2257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DennisClark wants to merge 5 commits into
base: main
Choose a base branch
from
+446 −42
Open

1943 refactor doc to restructure and improve #2257

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7320764
Update index.rst to restructure
DennisClark Apr 7, 2026
7730110
Create PIPELINES-AVID.rst in docs/source
DennisClark Apr 7, 2026
00e9f24
Create SOURCES.rst in docs/source
DennisClark Apr 7, 2026
797a72c
Create api_v3_usage.rst in docs/source
DennisClark Apr 8, 2026
fb305eb
Update index.rst with new docs
DennisClark Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/source/PIPELINES-AVID.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
.. list-table:: Pipeline AVID Mapping
:header-rows: 1
:widths: 35 65

* - pipeline name
- AVID
* - alpine_linux_importer_v2
- {package_name}/{distroversion}/{version}/{vulnerability_id}
* - aosp_dataset_fix_commits
- CVE ID of the record
* - apache_httpd_importer_v2
- CVE ID of the record
* - apache_kafka_importer_v2
- CVE ID of the record
* - apache_tomcat_importer_v2
- {page_id}/{cve_id}
* - archlinux_importer_v2
- AVG ID of the record
* - curl_importer_v2
- CURL-CVE ID of the record
* - debian_importer_v2
- {package_name}/{debian_record_id}
* - elixir_security_importer_v2
- {package_name}/{file_id}
* - epss_importer_v2
- CVE ID of the record
* - fireeye_importer_v2
- {file_id}
* - gentoo_importer_v2
- GLSA ID of the record
* - github_osv_importer_v2
- ID of the OSV record
* - gitlab_importer_v2
- Identifier of the GitLab community advisory record
* - istio_importer_v2
- ISTIO-SECURITY-<ID>
* - mattermost_importer_v2
- MMSA-<ID>
* - mozilla_importer_v2
- MFSA-<ID>
* - nginx_importer_v2
- First alias of the record
* - nodejs_security_wg
- NPM-<ID>
* - nvd_importer_v2
- CVE ID of the record
* - openssl_importer_v2
- CVE ID of the record
* - oss_fuzz_importer_v2
- ID of the OSV record
* - postgresql_importer_v2
- CVE ID of the record
* - project-kb-msr-2019_v2
- Vulnerability ID of the record
* - project-kb-statements_v2
- Vulnerability ID of the record
* - pypa_importer_v2
- {package_name}/{ID of the OSV record}
* - pysec_importer_v2
- ID of the OSV record
* - redhat_importer_v2
- RHSA ID of the record
* - retiredotnet_importer_v2
- retiredotnet-{file_id}
* - ruby_importer_v2
- {file_id}
* - suse_importer_v2
- CVE ID of the record
* - ubuntu_osv_importer_v2
- ID of the OSV record
* - vulnrichment_importer_v2
- CVE ID of the record
* - xen_importer_v2
- XSA-<ID>
53 changes: 53 additions & 0 deletions docs/source/SOURCES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|Importer Name | Data Source |Ecosystems Covered |
+================+======================================================================================================+====================================================+
|rust | https://github.com/RustSec/advisory-db |rust crates |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|alpine | https://secdb.alpinelinux.org/ |alpine packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|archlinux | https://security.archlinux.org/json |arch packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|debian | https://security-tracker.debian.org/tracker/data/json |debian packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|npm | https://github.com/nodejs/security-wg.git |npm packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|ruby | https://github.com/rubysec/ruby-advisory-db.git |ruby gems |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|ubuntu | |ubuntu packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|retiredotnet | https://github.com/RetireNet/Packages.git |.NET packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|suse_backports | http://ftp.suse.com/pub/projects/security/yaml/ |SUSE packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|debian_oval | https://www.debian.org/security/oval/ |debian packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|redhat | https://access.redhat.com/hydra/rest/securitydata/cve.json |rpm packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|nvd | https://nvd.nist.gov/vuln/data-feeds#JSON_FEED |none |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|gentoo | https://anongit.gentoo.org/git/data/glsa.git |gentoo packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|openssl | https://www.openssl.org/news/vulnerabilities.xml |openssl |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|ubuntu_usn | https://usn.ubuntu.com/usn-db/database-all.json.bz2 |ubuntu packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|github | https://api.github.com/graphql |maven, .NET, php-composer, pypi packages. ruby gems |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|msr2019 | https://raw.githubusercontent.com/SAP/project-kb/master/MSR2019/dataset/vulas_db_msr2019_release.csv |maven packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|apache_httpd | https://httpd.apache.org/security/json |apache-httpd |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|kaybee | https://github.com/SAP/project-kb.git |maven packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|nginx | http://nginx.org/en/security_advisories.html |nginx |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|postgresql | https://www.postgresql.org/support/security/ |postgresql |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|elixir_security | https://github.com/dependabot/elixir-security-advisories |hex packages |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|suse_scores | https://ftp.suse.com/pub/projects/security/yaml/suse-cvss-scores.yaml |vulnerability severity scores by SUSE |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|mozilla | https://github.com/mozilla/foundation-security-advisories |mozilla |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
|mattermost | https://mattermost.com/security-updates/ |mattermost server, desktop and mobile apps |
+----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+
254 changes: 254 additions & 0 deletions docs/source/api_v3_usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading