Update VulnerableCode documentation for advisories

Signed-off-by: ziad hany <ziadhany2016@gmail.com>

Author: ziadhany

SOURCES.rst

@@ -23,7 +23,7 @@ This can be done in the admin and from the command line::
 API client configuration
 ----------------------------
 
-API clients must send a User-Agent header that matches the value of the
+API clients must send a `User-Agent` header that matches the value of the
 `VCIO_USER_AGENT` setting.
 
 Add the following to your .env file::

docs/source/api-admin.rst

@@ -21,170 +21,95 @@ your API key, click on the ``Authorize`` button on the top right of the page and
 your API key in the ``value`` field with ``Token`` prefix, so if your token is "1234567890abcdef"
 then you have to enter this: ``Token 1234567890abcdef``.
 
-.. _Package Vulnerabilities Query:
+.. _Vulnerable Packages Query:
 
-Query for Package Vulnerabilities
+Query for Vulnerable Packages
 ------------------------------------
 
-The package endpoint allows you to query vulnerabilities by package using a
+The package endpoint allows you to query vulnerable packages using a
 purl or purl fields.
 
 Sample python script::
 
     import requests
 
     # Query by purl
-    resp = requests.get(
-        "https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/log4j@1.2.27",
-        headers={"Authorization": "Token 123456789"},
-    ).json()
-
-    # Query by purl type, get all the vulnerable maven packages
-    resp = requests.get(
-        "https://public.vulnerablecode.io/api/packages?type=maven",
-        headers={"Authorization": "Token 123456789"},
+    resp = requests.post(
+        "https://public.vulnerablecode.io/api/v3/packages/",
+        headers={"Authorization": "Token 123456789", "User-Agent": "VCIO_API_AGENT"},
+        json={
+            "purls": ["pkg:npm/atob@2.0.3?foo=bar"],
+            "ignore_qualifiers_subpath": True,
+            "details": True
+        }
     ).json()
 
 Sample using curl::
 
-    curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/log4j@1.2.27
-
-
-The response will be a list of packages, these are packages
-that are affected by and/or that fix a vulnerability.
-
-
-.. _Package Bulk Search:
-
-Package Bulk Search
----------------------
-
-
-The package bulk search endpoint allows you to search for purls in bulk. You can
-pass a list of purls in the request body and the endpoint will return a list of
-purls with vulnerabilities.
-
-
-You can pass a list of ``purls`` in the request body. Each package should be a
-valid purl string.
-
-You can also pass options like ``purl_only`` and ``plain_purl`` in the request.
-``purl_only`` will return only a list of vulnerable purls from the purls received in request.
-``plain_purl`` allows you to query the API using plain purls by removing qualifiers
-and subpath from the purl.
-
-The request body should be a JSON object with the following structure::
-
-    {
+    curl -X POST "https://public.vulnerablecode.io/api/v3/packages/" \
+      -H "Authorization: Token <YOUR_TOKEN>" \
+      -H "Content-Type: application/json" \
+      -H "User-Agent: VCIO_API_AGENT" \
+      -d '{
         "purls": [
-            "pkg:pypi/flask@1.2.0",
-            "pkg:npm/express@1.0"
+          "pkg:pypi/flask@2.3.2"
         ],
-        "purl_only": false,
-        "plain_purl": false,
-    }
-
-Sample python script::
-
-    import requests
-
-    request_body = {
-        "purls": [
-            "pkg:npm/grunt-radical@0.0.14"
-        ],
-    }
-
-    resp = requests.post('https://public.vulnerablecode.io/api/packages/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
-
+        "ignore_qualifiers_subpath": true,
+        "details": true,
+        "reachability": true
+      }'
 
 The response will be a list of packages, these are packages
-that are affected by and/or that fix a vulnerability.
+that are affected by and/or that fix a vulnerability advisory.
 
 API endpoints reference
 --------------------------
 
-There are two primary endpoints:
-
-- packages/: this is the main endpoint where you can lookup vulnerabilities by package.
-
-- vulnerabilities/: to lookup by vulnerabilities
-
-And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
-and vulnerability by CPEs: cpes/ and aliases/
-
-
 .. list-table:: Table for the main API endpoints
    :widths: 30 40 30
    :header-rows: 1
 
    * - Endpoint
      - Query Parameters
      - Expected Output
-   * - ``/api/packages``
-     -
-       - ``purl`` (string) = package-url of the package
-       - ``type`` (string) = type of the package
-       - ``namespace`` (string) = namespace of the package
-       - ``name`` (string) = name of the package
-       - ``version`` (string) = version of the package
-       - ``qualifiers`` (string) = qualifiers of the package
-       - ``subpath`` (string) = subpath of the package
-       - ``page`` (integer) = page number of the response
-       - ``page_size`` (integer) = number of packages in each page
-     - Return a list of packages using a package-url (purl) or a combination of
-       type, namespace, name, version, qualifiers, subpath purl fields. See the
-       `purl specification <https://github.com/package-url/purl-spec>`_ for more details. See example at :ref:`Package Vulnerabilities Query` section for more details.
-   * - ``/api/packages/bulk_search``
-     - Refer to package bulk search section :ref:`Package Bulk Search`
-     - Return a list of packages
-   * - ``/api/vulnerabilities/``
+   * - POST ``/api/v3/packages/``
      -
-       - ``vulnerability_id`` (string) = VCID (VulnerableCode Identifier) of the vulnerability
-       - ``page`` (integer) = page number of the response
-       - ``page_size`` (integer) = number of vulnerabilities in each page
-     - Return a list of vulnerabilities
-   * - ``/api/cpes``
+       - ``purls`` (array of strings) = List of package URLs ( a package-url (purl) or a combination of
+         type, namespace, name, version, qualifiers, subpath purl fields. See the
+         `purl specification <https://github.com/package-url/purl-spec>`_ for more details. )
+       - ``details`` (boolean) = Display all details about the packages provided
+       - ``ignore_qualifiers_subpath`` (boolean) = Ignore qualifiers/subpaths
+       - ``max_advisories`` (integer) = Maximum advisories to return
+       - ``reachability`` (boolean) = Display details about reachability
+         (introduced_in_patches and fixed_in_patches)
+     - Return a list of vulnerable packages
+   * - POST ``/api/v3/advisories/``
      -
-       - ``cpe`` (string) = value of the cpe
-       - ``page`` (integer) = page number of the response
-       - ``page_size`` (integer) = number of cpes in each page
-     - Return a list of vulnerabilities
-   * - ``/api/cpes/bulk_search``
-     - Refer to CPE bulk search section :ref:`CPE Bulk Search`
-     - Return a list of cpes
-   * - ``/api/aliases``
+        - ``purls`` (array of strings) = list of package urls
+     - Returns a list of advisories related to the provided packages
+   * - GET ``/api/v3/affected-by-advisories/``
      -
-       - ``alias`` (string) = value of the alias
-       - ``page`` (integer) = page number of the response
-       - ``page_size`` (integer) = number of aliases in each page
-     - Return a list of vulnerabilities
-
-.. list-table:: Table for other API endpoints
-   :widths: 30 40 30
-   :header-rows: 1
-
-   * - Endpoint
-     - Query Parameters
-     - Expected Output
-   * - ``/api/packages/{id}``
+       - ``page`` (string) = A page number within the paginated result set.
+       - ``page_size`` (integer) = Number of results to return per page.
+       - ``search`` (string) = A search term.
+     - Returns a paginated list of advisories vulnerabilities that affect given packages.
+   * - GET ``/api/v3/affected-by-advisories/{id}/``
      -
-       - ``id`` (integer) = internal primary id of the package
-     - Return a package with the given id
-   * - ``/api/packages/all``
-     - No parameter required
-     - Return a list of all vulnerable packages
-   * - ``/api/vulnerabilities/{id}``
+       - ``id`` (string) = A unique integer value identifying this advisory v2.
+     - Returns a specific advisory that affect a given package.
+   * - GET ``/api/v3/fixing-advisories/``
      -
-       - ``id`` (integer) = internal primary id of the vulnerability
-     - Return a vulnerability with the given id
-   * - ``/api/aliases/{id}``
+       - ``page`` (integer) = A page number within the paginated result set.
+       - ``page_size`` (integer) = Number of results to return per page.
+       - ``search`` (string) = A search term.
+     - Return a paginated list of advisories that fix a given package.
+   * - GET ``/api/v3/fixing-advisories/{id}/``
      -
-       - ``id`` (integer) = internal primary id of the alias
-     - Return an alias with the given id
-   * - ``/api/cpes/{id}``
+       - ``id`` (string) = A unique integer value identifying this advisory v2.
+     - Returns a specific advisory that fix a given package.
+   * - GET ``/api/v3/package-types/``
      -
-       - ``id`` = internal primary id of the cpe
-     - Return a cpe with the given id
+     - Return a list of to all the packages types in the database.
 
 Miscellaneous
 ----------------

docs/source/api.rst

@@ -46,10 +46,10 @@ VulnerableCode Documentation
 
 *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
+sources including packages affected by a vulnerability advisories and packages that fix a
 vulnerability.
 
-There is a `public VulnerableCode database <https://public.vulnerablecode.io/>`_
+There is a `public vulnerableCode database <https://public.vulnerablecode.io/>`_
 and the project also provides the tools to build your own instance of the database.
 
 Documentation overview

docs/source/index.rst

@@ -18,15 +18,16 @@ What can I do with VulnerableCode?
 
 **For security researchers and software developers, VulnerableCode offers a web
 UI and a JSON API to efficiently find if the FOSS packages and dependencies that
-you use are affected by known vulnerabilities and to determine whether a later package version
-fixes those vulnerabilities.**
+you use are affected by known vulnerabilities advisories and to determine whether a later package version
+fixes those vulnerabilities advisories.**
 
 
-- With the web UI, you can search by package using Package URLs or navigate directly to advisory/AVID page
+- With the web UI, you can search by package using Package URLs and navigate directly to advisory/AVID page
 
 - With the JSON API, you can perform package queries using Package URLs (`purl
   <https://github.com/package-url/purl-spec>`__) or query
-  by advisory/AVID
+  by advisory/AVID.
+  For comprehensive details, see the :ref:`api` section.
 
 You can install VulnerableCode locally or use the provided publicly hosted instance,
 or host your own installation. You can contact the VulnerableCode team

docs/source/introduction.rst

@@ -8,6 +8,4 @@ This is a set of Graphviz-based graph diagrams of the application and admin mode
 .. figure:: images/vcio-model.svg
     :alt: application and Admin model diagrams
     :width: 100%
-    :class: with-shadow
-
-.. rst-class::  clear-both
+    :class: with-shadow clear-both

docs/source/reference_model_overview.rst

@@ -20,7 +20,7 @@ The search by packages is available at the following URL:
 How to search by packages:
 
     1. Go to the URL: `https://public.vulnerablecode.io/ <https://public.vulnerablecode.io/>`_
-    2. Enter the package URL or purl prefix fragment such as ``pkg:pypi/flask``
+    2. Enter the package URL or purl prefix fragment such as ``pkg:pypi/aubio``
        or by package name in the search box.
     3. Click on the search button.
 
@@ -42,5 +42,5 @@ You can directly navigate to an advisory page by specifying the importer name (f
 and the advisory identifier (for example, CVE-2026-23918). `https://public.vulnerablecode.io/advisories/advisory_name/AVID`
 
 For example:
-    - `https://public.vulnerablecode.io/advisories/github_osv/GHSA-xrcv-f9gm-v42c <https://public.vulnerablecode.io/advisories/github_osv/GHSA-xrcv-f9gm-v42c>`_
-    - `https://public.vulnerablecode.io/advisories/nvd/CVE-2026-23918 <https://public.vulnerablecode.io/advisories/nvd/CVE-2026-23918>`_
+    - `https://public.vulnerablecode.io/advisories/github_osv/GHSA-6xcx-gx7r-rccj <https://public.vulnerablecode.io/advisories/github_osv/GHSA-6xcx-gx7r-rccj>`_
+    - `https://public.vulnerablecode.io/advisories/nvd/CVE-2026-23918 <https://public.vulnerablecode.io/advisories/nvd/CVE-2023-40024>`_