owasp-depscan 5.5.0__py3-none-any.whl → 6.0.0a3__py3-none-any.whl

depscan/lib/bom.py

@@ -1,46 +1,22 @@
-import json
 import os
-import shlex
 import shutil
-import subprocess
 import sys
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
 from urllib.parse import unquote_plus
 
-import httpx
+from custom_json_diff.lib.utils import json_load, json_dump
 from defusedxml.ElementTree import parse
-
-from depscan.lib.logger import LOG
-from depscan.lib.utils import cleanup_license_string, find_files
-
-headers = {
-    "Content-Type": "application/json",
-    "Accept-Encoding": "gzip",
-}
-
-
-def exec_tool(args, cwd=None, stdout=subprocess.PIPE):
-    """
-    Convenience method to invoke cli tools
-
-    :param args: Command line arguments
-    :param cwd: Working directory
-    :param stdout: Specifies stdout of command
-    """
-    try:
-        LOG.debug('⚡︎ Executing "%s"', " ".join(args))
-        cp = subprocess.run(
-            args,
-            stdout=stdout,
-            stderr=subprocess.STDOUT,
-            cwd=cwd,
-            env=os.environ.copy(),
-            shell=sys.platform == "win32",
-            encoding="utf-8",
-            check=False,
-        )
-        LOG.debug(cp.stdout)
-    except Exception as e:
-        LOG.exception(e)
+from xbom_lib.blint import BlintGenerator
+from xbom_lib.cdxgen import (
+    CdxgenGenerator,
+    CdxgenImageBasedGenerator,
+    CdxgenServerGenerator,
+)
+from depscan.lib.logger import LOG, SPINNER, console
+from depscan.lib.utils import cleanup_license_string
+from typing import Dict, Optional
 
 
 def parse_bom_ref(bomstr, licenses=None):
@@ -95,15 +71,13 @@ def get_licenses(ele):
     """
     license_list = []
     namespace = "{http://cyclonedx.org/schema/bom/1.5}"
-    for data in ele.findall(
-        f"{namespace}licenses/{namespace}license/{namespace}id"
-    ):
+    for data in ele.findall(f"{namespace}licenses/{namespace}license/{namespace}id"):
         license_list.append(data.text)
     if not license_list:
         for data in ele.findall(
             f"{namespace}licenses/{namespace}license/{namespace}name"
         ):
-            if data and data.text:
+            if data is not None and data.text:
                 ld_list = [data.text]
                 if "http" in data.text:
                     ld_list = [
@@ -161,40 +135,49 @@ def get_pkg_list_json(jsonfile):
     return List of dicts representing extracted packages
     """
     pkgs = []
-    with open(jsonfile, encoding="utf-8") as fp:
-        try:
-            bom_data = json.load(fp)
-            if bom_data and bom_data.get("components"):
-                for comp in bom_data.get("components"):
-                    licenses = []
-                    vendor = comp.get("group")
-                    if not vendor:
-                        vendor = ""
-                    if comp.get("licenses"):
-                        for lic in comp.get("licenses"):
-                            license_obj = lic
-                            # licenses has list of dict with either license
-                            # or expression as key Only license is supported
-                            # for now
-                            if lic.get("license"):
-                                license_obj = lic.get("license")
-                            if license_obj.get("id"):
-                                licenses.append(license_obj.get("id"))
-                            elif license_obj.get("name"):
-                                licenses.append(
-                                    cleanup_license_string(
-                                        license_obj.get("name")
-                                    )
-                                )
-                    pkgs.append(
-                        {**comp, "vendor": vendor, "licenses": licenses}
-                    )
-        except Exception:
-            # Ignore json errors
-            pass
+    if bom_data := json_load(jsonfile, log=LOG):
+        if bom_data.get("components"):
+            for comp in bom_data.get("components", []):
+                licenses, vendor, url = get_license_vendor_url(comp)
+                pkgs.append(
+                    {**comp, "vendor": vendor, "licenses": licenses, "url": url}
+                )
         return pkgs
 
 
+def get_license_vendor_url(comp):
+    licenses = []
+    vendor = comp.get("group") or ""
+    if comp.get("licenses"):
+        for lic in comp.get("licenses"):
+            license_obj = lic
+            if lic.get("license"):
+                license_obj = lic.get("license")
+            if license_obj.get("id"):
+                licenses.append(license_obj.get("id"))
+            elif license_obj.get("name"):
+                licenses.append(cleanup_license_string(license_obj.get("name")))
+    url = ""
+    for aref in comp.get("externalReferences", []):
+        if aref.get("type") in (
+            "vcs",
+            "issue-tracker",
+            "website",
+            "bom",
+            "source-distribution",
+            "distribution",
+            "distribution-intake",
+            "build-system",
+            "model-card",
+            "evidence",
+            "formulation",
+        ):
+            url = aref.get("url", "")
+            break
+    return licenses, vendor, url
+
+
+# Unused
 def get_pkg_list(xmlfile):
     """Method to parse the bom xml file and convert into packages list
 
@@ -232,247 +215,362 @@ def get_pkg_by_type(pkg_list, pkg_type):
     if not pkg_list:
         return []
     return [
-        pkg
-        for pkg in pkg_list
-        if pkg.get("purl", "").startswith("pkg:" + pkg_type)
+        pkg for pkg in pkg_list if pkg.get("purl", "").startswith("pkg:" + pkg_type)
     ]
 
 
-def resource_path(relative_path):
+def create_bom(bom_file, src_dir=".", options=None):
     """
-    Determine the absolute path of a resource file based on its relative path.
+    Method to create BOM file by executing cdxgen command
 
-    :param relative_path: Relative path of the resource file.
-    :return: Absolute path of the resource file
+    :param bom_file: BOM file
+    :param src_dir: Source directory
+    :param options: Additional options for generating the BOM file.
+    :returns: True if the command was executed. False if the executable was
+    not found.
     """
-    try:
-        base_path = sys._MEIPASS
-    except Exception:
-        base_path = os.path.dirname(__file__)
-    return os.path.join(base_path, relative_path)
-
-
-def exec_cdxgen(use_bin=True):
-    if use_bin:
-        cdxgen_cmd = os.environ.get("CDXGEN_CMD", "cdxgen")
-        if not shutil.which(cdxgen_cmd):
-            local_bin = resource_path(
-                os.path.join(
-                    "local_bin",
-                    "cdxgen.exe" if sys.platform == "win32" else "cdxgen",
-                )
+    if not options:
+        options = {}
+    # Get the various options and filenames
+    techniques = options.get("techniques") or []
+    lifecycles = options.get("lifecycles") or []
+    project_type_list = options.get("project_type") or []
+    bom_engine = options.get("bom_engine", "")
+    lifecycle_analysis_mode = options.get("lifecycle_analysis_mode", False)
+    # Detect if blint needs to be used for the given project type, technique, and lifecycle.
+    # For binaries, generate an sbom with blint directly
+    if (
+        bom_engine == "BlintGenerator"
+        or "binary-analysis" in techniques
+        or "post-build" in lifecycles
+        or any([t in ("binary", "apk") for t in project_type_list])
+    ):
+        return create_blint_bom(bom_file, src_dir, options=options)
+    cdxgen_server = options.get("cdxgen_server")
+    cdxgen_lib = CdxgenGenerator
+
+    # Should we call cdxgen server
+    if cdxgen_server or bom_engine == "CdxgenServerGenerator":
+        if not cdxgen_server:
+            LOG.error(
+                "Pass the `--cdxgen-server` argument to use the cdxgen server for BOM generation. Alternatively, use `--bom-engine auto` or `--bom-engine CdxgenGenerator`."
             )
-            if not os.path.exists(local_bin):
-                LOG.warning(
-                    "%s command not found. Please install using npm install "
-                    "@cyclonedx/cdxgen or set PATH variable",
-                    cdxgen_cmd,
-                )
-                return False
-            try:
-                cdxgen_cmd = local_bin
-                # Set the plugins directory as an environment variable
-                os.environ["CDXGEN_PLUGINS_DIR"] = resource_path("local_bin")
-                return cdxgen_cmd
-            except Exception:
-                return None
-        else:
-            return cdxgen_cmd
+            return False
+        cdxgen_lib = CdxgenServerGenerator
     else:
-        lbin = os.getenv("APPDATA") if sys.platform == "win32" else "local_bin"
-        local_bin = resource_path(
-            os.path.join(
-                f"{lbin}\\npm\\" if sys.platform == "win32" else "local_bin",
-                "cdxgen" if sys.platform != "win32" else "cdxgen.cmd",
-            )
-        )
-        if not os.path.exists(local_bin):
-            LOG.warning(
-                "%s command not found. Please install using npm install "
-                "@cyclonedx/cdxgen or set PATH variable",
-                local_bin,
-            )
-            return None
-        try:
-            cdxgen_cmd = local_bin
-            # Set the plugins directory as an environment variable
-            os.environ["CDXGEN_PLUGINS_DIR"] = (
-                resource_path("local_bin")
-                if sys.platform != "win32"
-                else resource_path(
-                    os.path.join(
-                        lbin,
-                        "\\npm\\node_modules\\@cyclonedx\\cdxgen\\node_modules\\@cyclonedx\\cdxgen-plugins-bin\\plugins",
+        # Prefer the new image based generators if docker command is available in auto mode
+        if bom_engine == "CdxgenImageBasedGenerator":
+            cdxgen_lib = CdxgenImageBasedGenerator
+        elif bom_engine == "auto":
+            # Prefer local CLI while scanning container images
+            if any(
+                [
+                    t in ("docker", "podman", "oci", "os", "hardware")
+                    for t in project_type_list
+                ]
+            ):
+                cdxgen_lib = CdxgenGenerator
+                if lifecycle_analysis_mode:
+                    LOG.warning(
+                        "Lifecycle analysis is not supported for oci and os project types."
                     )
-                )
+                    lifecycle_analysis_mode = True
+            elif (
+                shutil.which(os.getenv("DOCKER_CMD", "docker"))
+                and sys.platform != "win32"
+            ):
+                cdxgen_lib = CdxgenImageBasedGenerator
+    # We now have the cdxgen library to use.
+    # For lifecycle analysis, we need to generate multiple BOM files
+    if lifecycle_analysis_mode:
+        return create_lifecycle_boms(cdxgen_lib, src_dir, options)
+    # Invoke the cdxgen library directly
+    with console.status(
+        f"Generating BOM for the source '{src_dir}' with cdxgen.", spinner=SPINNER
+    ):
+        bom_result = cdxgen_lib(
+            src_dir, bom_file, logger=LOG, options=options
+        ).generate()
+        if not bom_result.success:
+            LOG.info(
+                "The cdxgen invocation was unsuccessful. Try generating the BOM separately."
             )
-            return cdxgen_cmd
-        except Exception:
-            return None
+            LOG.debug(bom_result.command_output)
+        return bom_result.success and os.path.exists(bom_file)
 
 
-def create_bom(project_type, bom_file, src_dir=".", deep=False, options={}):
+def create_blint_bom(
+    bom_file: str, src_dir: str = ".", options: Optional[Dict] = None
+) -> bool:
     """
-    Method to create BOM file by executing cdxgen command
+    Method to create BOM file by using blint
 
-    :param project_type: Project type
     :param bom_file: BOM file
     :param src_dir: Source directory
-    :param deep: A boolean flag indicating whether to perform a deep scan.
     :param options: Additional options for generating the BOM file.
-    :returns: True if the command was executed. False if the executable was
-    not found.
+    :returns: True if the bom was generated successfully. False otherwise.
     """
-    cdxgen_server = options.get("cdxgen_server")
-    # Generate SBOM by calling cdxgen server
-    if cdxgen_server:
-        # Fallback to universal if no project type was provided
-        if not project_type:
-            project_type = "universal"
-        if not src_dir and options.get("path"):
-            src_dir = options.get("path")
-        with httpx.Client(
-            http2=True, base_url=cdxgen_server, timeout=180
-        ) as client:
-            sbom_url = f"{cdxgen_server}/sbom"
-            LOG.debug("Invoking cdxgen server at %s", sbom_url)
-            try:
-                r = client.post(
-                    sbom_url,
-                    json={
-                        "url": options.get("url", ""),
-                        "path": options.get("path", src_dir),
-                        "type": options.get("type", project_type),
-                        "multiProject": options.get("multiProject", ""),
-                    },
-                    headers=headers,
-                )
-                if r.status_code == httpx.codes.OK:
-                    try:
-                        json_response = r.json()
-                        if json_response:
-                            with open(
-                                bom_file, mode="w", encoding="utf-8"
-                            ) as fp:
-                                json.dump(json_response, fp)
-                            return os.path.exists(bom_file)
-                    except Exception as je:
-                        LOG.error(je)
-                        LOG.info(
-                            "Unable to generate SBOM with cdxgen server. "
-                            "Trying to generate one locally."
-                        )
-                else:
-                    LOG.warning(
-                        "Unable to generate SBOM via cdxgen server due to %s",
-                        r.status_code,
-                    )
-            except Exception as e:
-                LOG.error(e)
+    if options is None:
+        options = {}
+    reachability_analyzer = options.get("reachability_analyzer")
+    # The side effect is that we will almost always run blint in deep mode
+    if reachability_analyzer != "off" and not options.get("deep"):
+        options["deep"] = True
+    blint_lib = BlintGenerator(src_dir, bom_file, logger=LOG, options=options)
+    with console.status(
+        f"Generating BOM for the source '{src_dir}' with blint.", spinner=SPINNER
+    ):
+        bom_result = blint_lib.generate()
+        if not bom_result.success:
+            LOG.info(
+                "The blint invocation was unsuccessful. Try generating the BOM separately."
+            )
+        return bom_result.success and os.path.exists(bom_file)
+
+
+def create_lifecycle_boms(cdxgen_lib, src_dir, options):
+    """
+    Method to create multiple BOM files for each lifecycle
+
+    :param cdxgen_lib: cdxgen library to use
+    :param src_dir: Source directory
+    :param options: Additional options for generating the BOM files
+    """
+    lifecycles = options.get("lifecycles", []) or []
+    if lifecycles:
+        LOG.warning(
+            "Ignoring the `lifecycles` argument, as it is not required for lifecycle analysis."
+        )
+    any_success = False
+    prebuild_bom_file = options.get("prebuild_bom_file")
+    build_bom_file = options.get("build_bom_file")
+    postbuild_bom_file = options.get("postbuild_bom_file")
+    container_bom_file = options.get("container_bom_file")
+    reachability_analyzer = options.get("reachability_analyzer")
+    with console.status(
+        f"Generating lifecycle-specific BOMs for {src_dir}.", spinner=SPINNER
+    ) as status:
+        # Start with build BOM generation.
+        # This would help atom compute reachable slices from a build perspective without getting confused
+        # about the pre-build state.
+        status.update(f"Generating build BOM for '{src_dir}' with cdxgen.")
+        coptions = {**options, "deep": "true", "lifecycles": ["build"]}
+        # We must also run it under research profile to help the reachability analyzer
+        # This logic could get refactored in the future
+        if reachability_analyzer != "off" and options.get("profile") != "research":
+            coptions["profile"] = "research"
+        bom_result = cdxgen_lib(
+            src_dir, build_bom_file, logger=LOG, options=coptions
+        ).generate()
+        if not bom_result.success or not os.path.exists(build_bom_file):
+            LOG.debug(
+                "The cdxgen invocation was unsuccessful. Trying pre-build lifecycle."
+            )
+            LOG.debug(bom_result.command_output)
+        else:
+            any_success = True
+        # pre-build
+        status.update(f"Now generating pre-build BOM for '{src_dir}' with cdxgen.")
+        coptions = {**options, "deep": "false", "lifecycles": ["pre-build"]}
+        bom_result = cdxgen_lib(
+            src_dir, prebuild_bom_file, logger=LOG, options=coptions
+        ).generate()
+        if not bom_result.success or not os.path.exists(prebuild_bom_file):
+            LOG.debug(
+                "The cdxgen invocation was unsuccessful. Trying the build lifecycle."
+            )
+            LOG.debug(bom_result.command_output)
+        else:
+            any_success = True
+        # container bom. For this we need the image name.
+        container_image_name = os.getenv("DEPSCAN_SOURCE_IMAGE") or options.get(
+            "source_image"
+        )
+        if container_image_name:
+            status.update(f"Generating container BOM for '{src_dir}' with cdxgen.")
+            coptions = {**options, "deep": "true", "project_type": ["oci"]}
+            if container_image_name == src_dir:
                 LOG.info(
-                    "Unable to generate SBOM with cdxgen server. Trying to "
-                    "generate one locally."
+                    "Set the environment variable DEPSCAN_SOURCE_IMAGE to the name of the container image to include its components."
                 )
-    cdxgen_cmd = exec_cdxgen()
-    if not cdxgen_cmd:
-        cdxgen_cmd = exec_cdxgen(False)
-    if project_type in ("docker",):
-        LOG.info(
-            "Generating Software Bill-of-Materials for container image %s. "
-            "This might take a few mins ...",
-            src_dir,
-        )
-    args = [cdxgen_cmd, "-r", "-t", project_type, "-o", bom_file]
-    if deep or project_type in ("jar", "jenkins") or options.get("reachables"):
-        args.append("--deep")
-        LOG.info("About to perform deep scan. This could take a while ...")
-    if options.get("profile"):
-        args.append("--profile")
-        args.append(options.get("profile"))
-        if options.get("profile") != "generic":
-            LOG.debug("BOM Profile: %s", options.get("profile"))
-    if options.get("cdxgen_args"):
-        args += shlex.split(options.get("cdxgen_args"))
-    # Bug #233 - Source directory could be None when working with url
-    if src_dir:
-        args.append(src_dir)
-    if cdxgen_cmd:
-        exec_tool(
-            args,
-            src_dir
-            if project_type not in ("docker", "oci", "container")
-            and src_dir
-            and os.path.isdir(src_dir)
-            else None,
+            bom_result = cdxgen_lib(
+                container_image_name, container_bom_file, logger=LOG, options=coptions
+            ).generate()
+            if not bom_result.success or not os.path.exists(container_bom_file):
+                LOG.debug(
+                    "The cdxgen invocation was unsuccessful. Trying for the next lifecycle."
+                )
+                LOG.debug(bom_result.command_output)
+            else:
+                any_success = True
+        else:
+            LOG.debug(
+                "Set the environment variable DEPSCAN_SOURCE_IMAGE to the name of the container image to include its components."
+            )
+        status.update("Preparing blint for post-build BOM generation.")
+    # post-build BOM with blint
+    coptions = {
+        **options,
+        "deep": False,
+        "use_blintdb": False,
+        "lifecycles": ["post-build"],
+    }
+    # What if the build directory is different to the source
+    build_dir = os.getenv("DEPSCAN_BUILD_DIR") or options.get("build_dir") or src_dir
+    res = create_blint_bom(postbuild_bom_file, build_dir, options=coptions)
+    if not res or not os.path.exists(postbuild_bom_file):
+        LOG.debug(
+            "The blint invocation was unsuccessful. Try building this project prior to invoking depscan. Alternatively, check if this project generates binary artefacts."
         )
     else:
-        LOG.warning("Unable to locate cdxgen command. ")
-    return os.path.exists(bom_file)
+        any_success = True
+    return any_success
+
 
+def create_empty_vdr(pkg_list, ds_version):
+    components = pkg_list or []
+    bom_data = update_tools_metadata(None, None, ds_version)
+    return {**bom_data, "components": components}
 
-def submit_bom(reports_dir, threatdb_params):
+
+def update_tools_metadata(tools, bom_data, ds_version):
+    """
+    Helper function to add depscan information as metadata
+    :param tools: Tools section of the SBOM
+    :param bom_data: SBOM data
+    :param ds_version: depscan version
+    :return: None
     """
-    Method to submit the SBOM to threatdb for analysis
+    if not bom_data:
+        now_utc = datetime.now(timezone.utc)
+        bom_data = {
+            "bomFormat": "CycloneDX",
+            "specVersion": "1.6",
+            "serialNumber": f"urn:uuid:{uuid.uuid4()}",
+            "version": 1,
+            "metadata": {
+                "timestamp": now_utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            },
+        }
+    components = tools.get("components", []) if tools else []
+    needs_ds_component = (
+        len([c for c in components if c.get("name") == "owasp-depscan"]) == 0
+    )
+    if needs_ds_component:
+        ds_purl = f"pkg:pypi/owasp-depscan@{ds_version}"
+        components.append(
+            {
+                "type": "application",
+                "name": "owasp-depscan",
+                "version": ds_version,
+                "purl": ds_purl,
+                "bom-ref": ds_purl,
+            }
+        )
+    bom_data["metadata"]["tools"] = {"components": components}
+    return bom_data
+
 
-    :param reports_dir: The directory where the SBOM reports are located.
-    :param threatdb_params: A dict of threatdb parameters
+def export_bom(bom_data, ds_version, pkg_vulnerabilities, vdr_file):
     """
-    vdr_files = find_files(reports_dir, ".vdr.json")
-    if vdr_files:
-        threatdb_server = threatdb_params["threatdb_server"]
-        if not threatdb_server.endswith("/import"):
-            threatdb_server = f"{threatdb_server}/import"
-        login_url = threatdb_server.replace("/import", "/login")
-        with httpx.Client(
-            http2=True, base_url=threatdb_server, timeout=180
-        ) as client:
-            token = threatdb_params.get("threatdb_token")
-            if not token:
-                LOG.debug(
-                    "Attempting to retrieve access token from %s", login_url
-                )
-                r = client.post(
-                    login_url,
-                    json={
-                        "username": threatdb_params["threatdb_username"],
-                        "password": threatdb_params["threatdb_password"],
-                    },
-                    headers=headers,
-                )
-                if r.status_code == httpx.codes.OK:
-                    json_response = r.json()
-                    if json_response and json_response.get("access_token"):
-                        token = json_response.get("access_token")
-                else:
-                    LOG.warning(
-                        "Unable to retrieve access token from %s due to %s",
-                        login_url,
-                        r.status_code,
-                    )
-            if token:
-                for vf in vdr_files:
-                    files = {"file": open(vf, "rb")}
-                    r = client.post(
-                        threatdb_server,
-                        files=files,
-                        headers={"Authorization": f"Bearer {token}"},
-                    )
-                    if r.status_code == httpx.codes.OK:
-                        json_response = r.json()
-                        if not json_response.get("success"):
-                            LOG.debug(
-                                "Uploaded file %s was not processed successfully",
-                                vf,
-                            )
-                        else:
-                            LOG.debug(
-                                "VDR file %s was submitted successfully to "
-                                "the threatdb server",
-                                vf,
-                            )
-                    else:
-                        LOG.warning(
-                            "Unable to submit VDR file to %s due to %s",
-                            threatdb_server,
-                            r.status_code,
-                        )
+    Exports the Bill of Materials (BOM) data along with package vulnerabilities
+    to a Vulnerability Data Report (VDR) file.
+
+    :param bom_data: SBOM data
+    :param ds_version: depscan version
+    :param pkg_vulnerabilities: Package vulnerabilities
+    :param vdr_file: VDR file path
+    """
+    # Add depscan information as metadata
+    metadata = bom_data.get("metadata", {})
+    tools = metadata.get("tools", {})
+    bom_version = str(bom_data.get("version", 0))
+    # Update the version
+    if bom_version.isdigit():
+        bom_data["version"] = int(bom_version) + 1
+    # Update the tools section
+    if isinstance(tools, dict):
+        bom_data = update_tools_metadata(tools, bom_data, ds_version)
+    bom_data = trim_vdr_bom_data(bom_data)
+    bom_data["vulnerabilities"] = pkg_vulnerabilities
+    json_dump(
+        vdr_file,
+        bom_data,
+        compact=True,
+        error_msg=f"Unable to generate VDR file at {vdr_file}",
+    )
+
+
+def trim_vdr_bom_data(bom_data):
+    components = bom_data.get("components")
+    if not components:
+        return bom_data
+    metadata = bom_data.get("metadata")
+    if metadata and metadata.get("properties"):
+        del metadata["properties"]
+        bom_data["metadata"] = metadata
+    new_components = {}
+    component_identities = defaultdict(list)
+    for comp in components:
+        identity_evidences = comp.get("evidence", {}).get("identity", []) or []
+        if isinstance(identity_evidences, dict):
+            identity_evidences = [identity_evidences]
+        for p in (
+            "properties",
+            "signature",
+            "url",
+            "vendor",
+            "licenses",  # We need a better logic to retain licenses here
+        ):
+            if comp.get(p) is not None:
+                del comp[p]
+        ref = comp.get("bom-ref") or comp.get("purl")
+        # This is an error condition really
+        if not ref:
+            continue
+        component_identities[ref] += identity_evidences
+        if not new_components.get(ref):
+            new_components[ref] = comp
+    vdr_components = []
+    for ref, comp in new_components.items():
+        identity_evidences = component_identities[ref]
+        comp["evidence"] = {"identity": identity_evidences}
+        vdr_components.append(comp)
+    bom_data["components"] = vdr_components
+    for p in (
+        "annotations",
+        "signature",
+    ):
+        if bom_data.get(p):
+            del bom_data[p]
+    return bom_data
+
+
+def annotate_vdr(vdr_file, txt_report_file):
+    if (
+        not vdr_file
+        or not txt_report_file
+        or not os.path.exists(vdr_file)
+        or not os.path.exists(txt_report_file)
+    ):
+        return
+    vdr = json_load(vdr_file)
+    metadata = vdr.get("metadata", {})
+    tools = metadata.get("tools", {}).get("components", {})
+    with open(txt_report_file, errors="ignore", encoding="utf-8") as txt_fp:
+        report = txt_fp.read()
+        annotations = vdr.get("annotations", []) or []
+        depscan_annotation = {
+            "subjects": [vdr.get("serialNumber")],
+            "annotator": {"component": tools[-1] if len(tools) > 0 else {}},
+            "timestamp": metadata.get("timestamp"),
+            "text": report,
+        }
+        annotations.append(depscan_annotation)
+    vdr["annotations"] = annotations
+    json_dump(
+        vdr_file,
+        vdr,
+        compact=True,
+        error_msg=f"Unable to add annotations to the VDR file at {vdr_file}",
+    )