From 7320764bfe6e9875d591a9c50c5ec60f6f7c7e0b Mon Sep 17 00:00:00 2001 From: Dennis Clark Date: Tue, 7 Apr 2026 16:48:03 -0700 Subject: [PATCH 1/5] Update index.rst to restructure Issue #1943 --- docs/source/index.rst | 104 +++++++++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 42 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index b20b1c9b5..b6398dc9f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,58 +1,78 @@ -Welcome to VulnerableCode! -============================= +VulnerableCode Documentation +============================ -*VulnerableCode* provides an open database of software packages that are affected -by known security vulnerabilities aka. *"vulnerable packages"*. +*VulnerableCode* provides a Web UI and API to access a database of known software package +vulnerabilities with comprehensive information from upstream and downstream public +sources including packages affected by a vulnerability and packages that fix a +vulnerability. -VulnerableCode is also a free and open source software (FOSS) project that -provides the tools to build this open database. The tools handle collecting, -aggregating and correlating these vulnerabilities and relating them to a correct -package version. Our project also supports a public cloud instance of this -database - VulnerableCode.io. +There is a `public VulnerableCode database `_ +and the project also provides the tools to build your own instance of the database. -In this documentation you will find information on: +Documentation overview +~~~~~~~~~~~~~~~~~~~~~~ -- An overview of VulnerableCode and what you can do with it -- Installation instructions -- How to make technical contributions to the project and the community +The overview below outlines how the documentation is structured +to help you know where to look for certain things. -.. toctree:: - :maxdepth: 2 - :caption: Getting Started +.. rst-class:: clearfix row - introduction - user-interface - installation - api - api-admin - contributing - faq - misc +.. rst-class:: column column2 top-left -.. toctree:: - :maxdepth: 2 - :caption: Tutorial +Getting started +~~~~~~~~~~~~~~~~~~~~~~ - tutorial_add_importer_pipeline - tutorial_add_improver_pipeline +Start here if you are new to VulnerableCode. +- :ref:`introduction` +- :ref:`user_interface` +- :ref:`installation` +- :ref:`api` +- :ref:`api-admin` +- :ref:`contributing` -.. toctree:: - :maxdepth: 2 - :caption: Reference Documentation +.. rst-class:: column column2 top-right - reference_importer_overview - reference_improver_overview - reference_framework_overview - reference_model_overview - command-line-interface - importers_link +Tutorials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. toctree:: - :maxdepth: 1 - :caption: Summer of Codes +Learn via practical step-by-step guides. + +- :ref:`tutorial_add_importer_pipeline` +- :ref:`tutorial_add_improver_pipeline` + +.. rst-class:: column column2 bottom-left + +Reference Docs +~~~~~~~~~~~~~~~~~~ + +Reference documentation for VulnerableCode features and customizations. + +- :ref:`reference_importer_overview` +- :ref:`reference_improver_overview` +- :ref:`reference_framework_overview` +- :ref:`reference_model_overview` +- :ref:`command_line_interface` +- :ref:`importers_link` + +.. rst-class:: column column2 bottom-right + +Explanations +~~~~~~~~~~~~~~~~~~ + +Consult the reference to understand VulnerableCode concepts. + +.. rst-class:: row clearfix + +Misc +~~~~~~~~~~~~~~~ + +- :ref:`faq` +- :ref:`misc` +- :ref:`soc_gsoc21` + +.. include:: improve-docs.rst - soc_gsoc21 Indices and tables ================== From 773011083a14ba06d12481a4734eddee5544bcdf Mon Sep 17 00:00:00 2001 From: Dennis Clark Date: Tue, 7 Apr 2026 16:58:16 -0700 Subject: [PATCH 2/5] Create PIPELINES-AVID.rst in docs/source Issue #1943 --- docs/source/PIPELINES-AVID.rst | 74 ++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/source/PIPELINES-AVID.rst diff --git a/docs/source/PIPELINES-AVID.rst b/docs/source/PIPELINES-AVID.rst new file mode 100644 index 000000000..bdf7008da --- /dev/null +++ b/docs/source/PIPELINES-AVID.rst @@ -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- + * - mattermost_importer_v2 + - MMSA- + * - mozilla_importer_v2 + - MFSA- + * - nginx_importer_v2 + - First alias of the record + * - nodejs_security_wg + - NPM- + * - 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- From 00e9f24d67d3cc00c51dd27388f83cc0e14ba5dd Mon Sep 17 00:00:00 2001 From: Dennis Clark Date: Tue, 7 Apr 2026 16:59:56 -0700 Subject: [PATCH 3/5] Create SOURCES.rst in docs/source Issue #1943 --- docs/source/SOURCES.rst | 53 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/source/SOURCES.rst diff --git a/docs/source/SOURCES.rst b/docs/source/SOURCES.rst new file mode 100644 index 000000000..bc0963a10 --- /dev/null +++ b/docs/source/SOURCES.rst @@ -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 | ++----------------+------------------------------------------------------------------------------------------------------+----------------------------------------------------+ From 797a72ce08bdc9e8ccaf157ccc8b7593d90a5e15 Mon Sep 17 00:00:00 2001 From: Dennis Clark Date: Tue, 7 Apr 2026 17:01:48 -0700 Subject: [PATCH 4/5] Create api_v3_usage.rst in docs/source Issue #1943 --- docs/source/api_v3_usage.rst | 254 +++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/source/api_v3_usage.rst diff --git a/docs/source/api_v3_usage.rst b/docs/source/api_v3_usage.rst new file mode 100644 index 000000000..f4add89c6 --- /dev/null +++ b/docs/source/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= + +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= + +Example: + +:: + + GET /api/v3/fixing-advisories?purl=pkg:npm/atob@2.1.0 From fb305eb532605daa32468be60708fcedeb1995e8 Mon Sep 17 00:00:00 2001 From: Dennis Clark Date: Tue, 7 Apr 2026 17:05:56 -0700 Subject: [PATCH 5/5] Update index.rst with new docs Issue #1943 --- docs/source/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index b6398dc9f..c3fc07402 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,6 +29,7 @@ Start here if you are new to VulnerableCode. - :ref:`installation` - :ref:`api` - :ref:`api-admin` +- :ref:`api_v3_usage.rst` - :ref:`contributing` .. rst-class:: column column2 top-right @@ -54,6 +55,8 @@ Reference documentation for VulnerableCode features and customizations. - :ref:`reference_model_overview` - :ref:`command_line_interface` - :ref:`importers_link` +- :ref:`PIPELINES-AVID.rst` +- :ref:`SOURCES.rst` .. rst-class:: column column2 bottom-right