Support for vdb custom data (#472)

* Support for vdb custom data

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

* Bug fix

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

---------

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

Author: prabhu

.github/workflows/pythonapp.yml

@@ -55,6 +55,40 @@ jobs:
         uv run depscan --purl "pkg:npm/@biomejs/biome@1.8.1"
       env:
         PYTHONIOENCODING: utf-8
+    - name: Custom data tests
+      run: |
+        mkdir -p custom_vulns
+        cat > custom_vulns/private.yaml <<EOF
+        dataType: CVE_RECORD
+        dataVersion: "5.2"
+        cveMetadata:
+          cveId: PRIVATE-DEPSCAN-TEST
+          assignerOrgId: 00000000-0000-4000-8000-000000000000
+          state: PUBLISHED
+          datePublished: "2024-01-01T00:00:00Z"
+          dateUpdated: "2024-01-01T00:00:00Z"
+        containers:
+          cna:
+            providerMetadata:
+              orgId: 00000000-0000-4000-8000-000000000000
+            descriptions:
+              - lang: en
+                value: "Depscan Test Vulnerability"
+            affected:
+              - vendor: internal
+                product: custom-test
+                packageName: custom-test
+                packageURL: pkg:pypi/custom-test
+                versions:
+                  - version: "1.0.0"
+                    status: affected
+                    versionType: semver
+        EOF
+
+        uv run depscan --purl "pkg:pypi/custom-test@1.0.0" --custom-data custom_vulns
+      if: ${{ matrix.os == 'ubuntu-latest' }}
+      env:
+        PYTHONIOENCODING: utf-8
 
   devenv:
     env:

README.md

@@ -163,6 +163,8 @@ options:
   --bom BOM             Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one.
   --bom-dir BOM_DIR     Examine all the Bill-of-Materials (BOM) files in the given directory.
   --purl SEARCH_PURL    Scan a single package url.
+  --custom-data CUSTOM_DATA
+                        Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results.
   --report-template REPORT_TEMPLATE
                         Jinja template file used for rendering a custom report
   --report-name REPORT_NAME

depscan/cli.py

@@ -25,7 +25,7 @@
 from custom_json_diff.lib.utils import json_load
 from rich.panel import Panel
 from rich.terminal_theme import DEFAULT_TERMINAL_THEME, MONOKAI
-from vdb.lib import config
+from vdb.lib import config, search
 from vdb.lib import db6 as db_lib
 from vdb.lib.utils import parse_purl
 
@@ -288,6 +288,7 @@ def run_depscan(args):
                 debug=args.enable_debug or os.environ.get("SCAN_DEBUG_MODE") == "debug",
                 create_bom=create_bom,
                 max_content_length=os.getenv("DEPSCAN_SERVER_MAX_CONTENT_LENGTH"),
+                custom_data_directory=args.custom_data,
             )
             return simple.run_server(server_options)
         else:
@@ -382,6 +383,9 @@ def run_depscan(args):
             )
             sys.exit(0)
     pkg_list, project_types_list = set_project_types(args, src_dir)
+    if args.custom_data:
+        LOG.info(f"Loading custom vulnerability data from {args.custom_data}")
+        search.load_custom_data(args.custom_data)
     if args.search_purl:
         # Automatically enable risk audit for single purl searches
         perform_risk_audit = True

depscan/cli_options.py

@@ -171,6 +171,11 @@ def build_parser():
         dest="search_purl",
         help="Scan a single package url.",
     )
+    parser.add_argument(
+        "--custom-data",
+        dest="custom_data",
+        help="Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results.",
+    )
     parser.add_argument(
         "--report-template",
         dest="report_template",

devenv.lock

@@ -3,10 +3,10 @@
     "devenv": {
       "locked": {
         "dir": "src/modules",
-        "lastModified": 1763386227,
+        "lastModified": 1766921574,
         "owner": "cachix",
         "repo": "devenv",
-        "rev": "9f855598530d6ee075cc126e4f13812fd008209a",
+        "rev": "02c9dcf3e050400d8101057f9f00ec458af7c959",
         "type": "github"
       },
       "original": {
@@ -19,10 +19,10 @@
     "flake-compat": {
       "flake": false,
       "locked": {
-        "lastModified": 1761588595,
+        "lastModified": 1766929376,
         "owner": "edolstra",
         "repo": "flake-compat",
-        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
+        "rev": "236f248441a986331cda53b039e7f9fd96e03635",
         "type": "github"
       },
       "original": {
@@ -34,10 +34,10 @@
     "flake-compat_2": {
       "flake": false,
       "locked": {
-        "lastModified": 1761588595,
+        "lastModified": 1766929376,
         "owner": "edolstra",
         "repo": "flake-compat",
-        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
+        "rev": "236f248441a986331cda53b039e7f9fd96e03635",
         "type": "github"
       },
       "original": {
@@ -49,10 +49,10 @@
     "flake-compat_3": {
       "flake": false,
       "locked": {
-        "lastModified": 1761588595,
+        "lastModified": 1766929376,
         "owner": "edolstra",
         "repo": "flake-compat",
-        "rev": "f387cd2afec9419c8ee37694406ca490c3f34ee5",
+        "rev": "236f248441a986331cda53b039e7f9fd96e03635",
         "type": "github"
       },
       "original": {
@@ -87,10 +87,10 @@
         ]
       },
       "locked": {
-        "lastModified": 1763319842,
+        "lastModified": 1765911976,
         "owner": "cachix",
         "repo": "git-hooks.nix",
-        "rev": "7275fa67fbbb75891c16d9dee7d88e58aea2d761",
+        "rev": "b68b780b69702a090c8bb1b973bab13756cc7a27",
         "type": "github"
       },
       "original": {
@@ -121,10 +121,10 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1761313199,
+        "lastModified": 1764580874,
         "owner": "cachix",
         "repo": "devenv-nixpkgs",
-        "rev": "d1c30452ebecfc55185ae6d1c983c09da0c274ff",
+        "rev": "dcf61356c3ab25f1362b4a4428a6d871e84f1d1d",
         "type": "github"
       },
       "original": {
@@ -142,10 +142,10 @@
         ]
       },
       "locked": {
-        "lastModified": 1761999567,
+        "lastModified": 1765052656,
         "owner": "cachix",
         "repo": "nixpkgs-python",
-        "rev": "100c43175443402084f557154b06f2745995e742",
+        "rev": "04b27dbad2e004cb237db202f21154eea3c4f89f",
         "type": "github"
       },
       "original": {
@@ -163,10 +163,10 @@
         ]
       },
       "locked": {
-        "lastModified": 1759902829,
+        "lastModified": 1766728475,
         "owner": "bobvanderlinden",
         "repo": "nixpkgs-ruby",
-        "rev": "5fba6c022a63f1e76dee4da71edddad8959f088a",
+        "rev": "f167828eab19c3a7e3faa066a140d92e307f7b16",
         "type": "github"
       },
       "original": {

devenv.nix

@@ -37,11 +37,11 @@ in
         };
         java = lib.mkIf (lib.elem config.profile [ "android" "flutter" "reactNative" ] == false) {
           enable = true;
-          jdk.package = pkgs.jdk23_headless;
+          jdk.package = pkgs.jdk25_headless;
         };
         ruby = {
           enable = lib.mkIf (config.profile == "ruby") true;
-          version = "3.4.4";
+          version = "4.0.1";
         };
         dotnet = {
           enable = lib.mkIf (config.profile == "dotnet") true;

documentation/docs/adv-usage.mdx

@@ -8,8 +8,8 @@ sidebar_position: 8
 
 To download security advisories from GitHub, a personal access token with minimal permissions is necessary.
 
--   Fine-grained token: Grant no permissions and select the following for repository access: `Public Repositories (read-only)`
--   Token (classic): Grant no permissions
+- Fine-grained token: Grant no permissions and select the following for repository access: `Public Repositories (read-only)`
+- Token (classic): Grant no permissions
 
 ```bash
 export GITHUB_TOKEN="<PAT token>"
@@ -19,9 +19,8 @@ export GITHUB_TOKEN="<PAT token>"
 
 Depscan comes with a suggest mode enabled by default to simplify the triaging experience. The fix version for each vulnerability is retrieved from the sources. Sometimes, there might be known vulnerabilities in the fix version reported. Eg: in the below screenshot the fix versions suggested for jackson-databind might contain known vulnerabilities.
 
-[//]: # (![Normal mode]&#40;docs/depscan-normal.png&#41;)
-
-[//]: # (![Suggest mode]&#40;docs/depscan-suggest.png&#41;)
+[//]: # "![Normal mode](docs/depscan-normal.png)"
+[//]: # "![Suggest mode](docs/depscan-suggest.png)"
 
 Notice, how the new suggested version is `2.9.10.5` which is an optimal fix version. Please note that the optimal fix version may not be the appropriate version for your application based on compatibility.
 
@@ -91,7 +90,7 @@ export FETCH_LICENSE=true
 
 The license data is sourced from choosealicense.com and is quite limited. If the license of a given package cannot be reliably matched against this list it will get silently ignored to reduce any noise. This behavior could change in the future once the detection logic gets improved.
 
-[//]: # (![License scan]&#40;docs/license-scan.png&#41;)
+[//]: # "![License scan](docs/license-scan.png)"
 
 ## Kubernetes and Cloud apps
 
@@ -129,15 +128,103 @@ Severity counts:
 
 The objects available are taken from the CycloneDX \*.vdr.json BOM file generated, just have a look at the file for its full structure:
 
--   `metadata`
--   `vulnerabilities`
--   `components`
--   `dependencies`
--   `services`
+- `metadata`
+- `vulnerabilities`
+- `components`
+- `dependencies`
+- `services`
 
 `summary` is a dictionary type with vulnerability severity quantities as shown in the example above.
 `pkg_vulnerabilities` - Same as `vulnerabilities` from the VDR
 `pkg_group_rows` - List of vulnerability id and the dependency tree prioritized by depscan.
 
 Furthermore, insights are imaginable to be made available to the template, please reach out or contribute on demand.
 We appreciate it if you like to contribute your report templates as examples, please add/find them [here](https://github.com/owasp-dep-scan/dep-scan/blob/master/contrib/report-templates).
+
+## Custom Vulnerability Data
+
+VDB 6 supports loading custom vulnerability data from a local directory at runtime. This allows you to:
+
+1.  **Add Private Vulnerabilities:** Include internal CVEs that are not public.
+2.  **Override False Positives:** Correct data returned by the official database by marking specific versions as `unaffected`.
+
+Custom data must follow the **CVE 5.2 JSON Schema**. Supported file extensions are `.json`, `.yaml`, `.yml`, and `.toml`.
+
+To use custom data, pass the directory path to the `--custom-data` argument.
+
+```shell
+depscan --purl pkg:npm/my-lib@1.0.0 --custom-data /path/to/custom/vulns
+```
+
+Custom data is also supported in server mode.
+
+```shell
+depscan --server --custom-data /path/to/custom/vulns
+```
+
+### Example 1: Adding a Private Vulnerability
+
+Create a file `private-vuln.yaml`. Since you are defining a new vulnerability record, you use the `cna` container.
+
+```yaml
+dataType: CVE_RECORD
+dataVersion: "5.2"
+cveMetadata:
+    cveId: PRIVATE-2025-001
+    assignerOrgId: 00000000-0000-4000-8000-000000000000
+    state: PUBLISHED
+    datePublished: "2025-01-01T00:00:00Z"
+    dateUpdated: "2025-01-01T00:00:00Z"
+containers:
+    cna:
+        providerMetadata:
+            orgId: 00000000-0000-4000-8000-000000000000
+        descriptions:
+            - lang: en
+              value: "Private vulnerability in internal library"
+        affected:
+            - vendor: internal
+              product: my-lib
+              packageName: my-lib
+              packageURL: pkg:npm/my-lib
+              versions:
+                  - version: "1.0.0"
+                    status: affected
+                    versionType: semver
+                    lessThan: "2.0.0"
+```
+
+### Example 2: Overriding a False Positive
+
+If the official database reports `CVE-2023-9999` for `pkg:pypi/requests` but you have determined it is a false positive for your specific version, you can override it using an **ADP (Authorized Data Publisher)** container. This is the recommended way to append or dispute existing vulnerability data.
+
+**Logic:** If a CVE ID and Package URL combination exists in your custom data, VDB will **ignore** the entry from the official database and use yours instead.
+
+Create `override.yaml`:
+
+```yaml
+dataType: CVE_RECORD
+dataVersion: "5.2"
+cveMetadata:
+    cveId: CVE-2023-9999
+    assignerOrgId: 00000000-0000-4000-8000-000000000000
+    state: PUBLISHED
+containers:
+    # Use 'adp' to append/modify existing vulnerability data
+    adp:
+        - providerMetadata:
+              orgId: 00000000-0000-4000-8000-000000000000
+              shortName: "MySecTeam"
+          descriptions:
+              - lang: en
+                value: "Override to mark specific version as unaffected"
+          affected:
+              - product: requests
+                packageName: requests
+                packageURL: pkg:pypi/requests
+                versions:
+                    # Explicitly mark your version as unaffected
+                    - version: "2.31.0"
+                      status: unaffected
+                      versionType: semver
+```

documentation/docs/cli-usage.mdx

@@ -74,6 +74,8 @@ options:
   --bom BOM             Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one.
   --bom-dir BOM_DIR     Examine all the Bill-of-Materials (BOM) files in the given directory.
   --purl SEARCH_PURL    Scan a single package url.
+  --custom-data CUSTOM_DATA
+                        Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results.
   --report-template REPORT_TEMPLATE
                         Jinja template file used for rendering a custom report
   --report-name REPORT_NAME

packages/analysis-lib/src/analysis_lib/output.py

@@ -790,6 +790,8 @@ def summary_stats(results):
         ratings = i.get("ratings")
         if ratings:
             sev = ratings[0].get("severity", "").upper()
+            if not sev:
+                sev = "UNSPECIFIED"
             summary[sev] += 1
 
     return summary
@@ -808,6 +810,7 @@ def pkg_risks_table(
     :param project_type: Project type
     :param scoped_pkgs: A dict of lists of required/optional/excluded packages.
     :param risk_results: A dict of the risk metrics and scope for each package.
+    :param pkg_max_risk_score: Max risk score
     :param risk_report_file: Path to the JSON file for the risk audit findings.
     """
     if not risk_results:

packages/analysis-lib/src/analysis_lib/utils.py

@@ -680,7 +680,15 @@ def cve_to_vdr(cve: CVE, vid: str):
     except AttributeError:
         description, detail = "", ""
     if not source:
-        source = {"name": cve.root.cveMetadata.assignerShortName.root.capitalize()}
+        assigner_short_name = cve.root.cveMetadata.assignerShortName
+        assigner_name = ""
+        if assigner_short_name:
+            if hasattr(assigner_short_name, "root"):
+                assigner_name = str(assigner_short_name.root)
+            else:
+                assigner_name = str(assigner_short_name)
+
+        source = {"name": assigner_name.capitalize()}
         if source.get("name") == "Github_m":
             source = {
                 "name": "GitHub Advisory Database",