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

depscan/cli.py

@@ -1,710 +1,439 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3 -W ignore::DeprecationWarning
 # -*- coding: utf-8 -*-
 
-import argparse
+import contextlib
 import json
 import os
 import sys
 import tempfile
+from typing import List
 
-from defusedxml.ElementTree import parse
-from quart import Quart, request
+from analysis_lib import (
+    ReachabilityAnalysisKV,
+    VdrAnalysisKV,
+)
+from analysis_lib.csaf import export_csaf, write_toml
+from analysis_lib.search import get_pkgs_by_scope
+from analysis_lib.utils import (
+    get_all_bom_files,
+    get_all_pkg_list,
+    get_pkg_list,
+    licenses_risk_table,
+    pkg_risks_table,
+    summary_stats,
+)
+from analysis_lib.vdr import VDRAnalyzer
+from analysis_lib.reachability import get_reachability_impl
+from custom_json_diff.lib.utils import file_write, 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 db as db_lib
-from vdb.lib.gha import GitHubSource
-from vdb.lib.nvd import NvdSource
-from vdb.lib.osv import OSVSource
+from vdb.lib import db6 as db_lib
 from vdb.lib.utils import parse_purl
 
-from depscan.lib import explainer, github, utils
-from depscan.lib.analysis import (
-    PrepareVdrOptions,
-    analyse_licenses,
-    analyse_pkg_risks,
-    find_purl_usages,
-    jsonl_report,
-    prepare_vdr,
-    suggest_version,
-    summary_stats,
-)
+from depscan import get_version
+from depscan.cli_options import build_parser
+from depscan.lib import explainer, utils
 from depscan.lib.audit import audit, risk_audit, risk_audit_map, type_audit_map
 from depscan.lib.bom import (
+    annotate_vdr,
+    create_empty_vdr,
     create_bom,
+    export_bom,
     get_pkg_by_type,
-    get_pkg_list,
-    submit_bom,
 )
 from depscan.lib.config import (
+    DEPSCAN_DEFAULT_VDR_FILE,
     UNIVERSAL_SCAN_TYPE,
+    VDB_AGE_HOURS,
     license_data_dir,
+    pkg_max_risk_score,
     spdx_license_list,
+    vdb_database_url,
 )
-from depscan.lib.csaf import export_csaf, write_toml
 from depscan.lib.license import build_license_data, bulk_lookup
-from depscan.lib.logger import DEBUG, LOG, console
-from depscan.lib.orasclient import download_image
+from depscan.lib.logger import DEBUG, LOG, SPINNER, console, IS_CI
 
-try:
-    os.environ["PYTHONIOENCODING"] = "utf-8"
-except Exception:
-    pass
+if sys.platform == "win32" and os.environ.get("PYTHONIOENCODING") is None:
+    sys.stdin.reconfigure(encoding="utf-8")
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
 
 LOGO = """
-██████╗ ███████╗██████╗ ███████╗ ██████╗ █████╗ ███╗   ██╗
-██╔══██╗██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗████╗  ██║
-██║  ██║█████╗  ██████╔╝███████╗██║     ███████║██╔██╗ ██║
-██║  ██║██╔══╝  ██╔═══╝ ╚════██║██║     ██╔══██║██║╚██╗██║
-██████╔╝███████╗██║     ███████║╚██████╗██║  ██║██║ ╚████║
-╚═════╝ ╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═══╝
+  _|  _  ._   _  _  _. ._
+ (_| (/_ |_) _> (_ (_| | |
+         |
 """
 
+QUART_AVAILABLE = False
+try:
+    from quart import Quart, request
+
+    app = Quart(__name__, static_folder=None)
+    app.config.from_prefixed_env()
+    app.config["PROVIDE_AUTOMATIC_OPTIONS"] = True
+    QUART_AVAILABLE = True
+except ImportError:
+    pass
+
+ORAS_AVAILABLE = False
+try:
+    from vdb.lib.orasclient import download_image
 
-app = Quart(__name__)
-app.config.from_prefixed_env()
+    ORAS_AVAILABLE = True
+except ImportError:
+    pass
 
 
 def build_args():
     """
     Constructs command line arguments for the depscan tool
     """
-    parser = argparse.ArgumentParser(
-        description="Fully open-source security and license audit for "
-        "application dependencies and container images based on "
-        "known vulnerabilities and advisories.",
-        epilog="Visit https://github.com/owasp-dep-scan/dep-scan to learn more.",
-    )
-    parser.add_argument(
-        "--no-banner",
-        action="store_true",
-        default=False,
-        dest="no_banner",
-        help="Do not display the logo and donation banner. Please make a donation to OWASP before using this argument.",
-    )
-    parser.add_argument(
-        "--cache",
-        action="store_true",
-        default=False,
-        dest="cache",
-        help="Cache vulnerability information in platform specific "
-        "user_data_dir",
-    )
-    parser.add_argument(
-        "--csaf",
-        action="store_true",
-        default=False,
-        dest="csaf",
-        help="Generate a OASIS CSAF VEX document",
-    )
-    parser.add_argument(
-        "--sync",
-        action="store_true",
-        default=False,
-        dest="sync",
-        help="Sync to receive the latest vulnerability data. Should have "
-        "invoked cache first.",
-    )
-    parser.add_argument(
-        "--profile",
-        default="generic",
-        choices=(
-            "appsec",
-            "research",
-            "operational",
-            "threat-modeling",
-            "license-compliance",
-            "generic",
-        ),
-        dest="profile",
-        help="Profile to use while generating the BOM.",
-    )
-    parser.add_argument(
-        "--no-suggest",
-        action="store_false",
-        default="True",
-        dest="suggest",
-        help="Disable suggest mode",
-    )
-    parser.add_argument(
-        "--risk-audit",
-        action="store_true",
-        default=os.getenv("ENABLE_OSS_RISK", "") in ("true", "1"),
-        dest="risk_audit",
-        help="Perform package risk audit (slow operation). Npm only.",
-    )
-    parser.add_argument(
-        "--cdxgen-args",
-        default=os.getenv("CDXGEN_ARGS"),
-        dest="cdxgen_args",
-        help="Additional arguments to pass to cdxgen",
-    )
-    parser.add_argument(
-        "--private-ns",
-        dest="private_ns",
-        default=os.getenv("PKG_PRIVATE_NAMESPACE"),
-        help="Private namespace to use while performing oss risk audit. "
-        "Private packages should not be available in public registries "
-        "by default. Comma separated values accepted.",
-    )
-    parser.add_argument(
-        "-t",
-        "--type",
-        dest="project_type",
-        default=os.getenv("DEPSCAN_PROJECT_TYPE"),
-        help="Override project type if auto-detection is incorrect",
-    )
-    parser.add_argument(
-        "--bom",
-        dest="bom",
-        help="Examine using the given Software Bill-of-Materials (SBOM) file "
-        "in CycloneDX format. Use cdxgen command to produce one.",
-    )
-    parser.add_argument(
-        "-i",
-        "--src",
-        dest="src_dir_image",
-        help="Source directory or container image or binary file",
-    )
-    parser.add_argument(
-        "-o",
-        "--report_file",
-        dest="report_file",
-        help="DEPRECATED. Use reports directory since multiple files are "
-        "created. Report filename with directory",
-    )
-    parser.add_argument(
-        "--reports-dir",
-        default=os.getenv(
-            "DEPSCAN_REPORTS_DIR", os.path.join(os.getcwd(), "reports")
-        ),
-        dest="reports_dir",
-        help="Reports directory",
-    )
-    parser.add_argument(
-        "--report-template",
-        dest="report_template",
-        help="Jinja template file used for rendering a custom report",
-    )
-    parser.add_argument(
-        "--report-name",
-        default="rendered.report",
-        dest="report_name",
-        help="Filename of the custom report written to the --reports-dir",
-    )
-    parser.add_argument(
-        "--no-error",
-        action="store_true",
-        default=False,
-        dest="noerror",
-        help="UNUSED: Continue on error to prevent build from breaking",
-    )
-    parser.add_argument(
-        "--no-license-scan",
-        action="store_true",
-        default=False,
-        dest="no_license_scan",
-        help="UNUSED: dep-scan doesn't perform license scanning by default",
-    )
-    parser.add_argument(
-        "--deep",
-        action="store_true",
-        default=False,
-        dest="deep_scan",
-        help="Perform deep scan by passing this --deep argument to cdxgen. "
-        "Useful while scanning docker images and OS packages.",
-    )
-    parser.add_argument(
-        "--no-universal",
-        action="store_true",
-        default=False,
-        dest="non_universal_scan",
-        help="Depscan would attempt to perform a single universal scan "
-        "instead of individual scans per language type.",
-    )
-    parser.add_argument(
-        "--no-vuln-table",
-        action="store_true",
-        default=False,
-        dest="no_vuln_table",
-        help="Do not print the table with the full list of vulnerabilities. "
-        "This can help reduce console output.",
-    )
-    parser.add_argument(
-        "--threatdb-server",
-        default=os.getenv("THREATDB_SERVER_URL"),
-        dest="threatdb_server",
-        help="ThreatDB server url. Eg: https://api.sbom.cx",
-    )
-    parser.add_argument(
-        "--threatdb-username",
-        default=os.getenv("THREATDB_USERNAME"),
-        dest="threatdb_username",
-        help="ThreatDB username",
-    )
-    parser.add_argument(
-        "--threatdb-password",
-        default=os.getenv("THREATDB_PASSWORD"),
-        dest="threatdb_password",
-        help="ThreatDB password",
-    )
-    parser.add_argument(
-        "--threatdb-token",
-        default=os.getenv("THREATDB_ACCESS_TOKEN"),
-        dest="threatdb_token",
-        help="ThreatDB token for token based submission",
-    )
-    parser.add_argument(
-        "--server",
-        action="store_true",
-        default=False,
-        dest="server_mode",
-        help="Run depscan as a server",
-    )
-    parser.add_argument(
-        "--server-host",
-        default=os.getenv("DEPSCAN_HOST", "127.0.0.1"),
-        dest="server_host",
-        help="depscan server host",
-    )
-    parser.add_argument(
-        "--server-port",
-        default=os.getenv("DEPSCAN_PORT", "7070"),
-        dest="server_port",
-        help="depscan server port",
-    )
-    parser.add_argument(
-        "--cdxgen-server",
-        default=os.getenv("CDXGEN_SERVER_URL"),
-        dest="cdxgen_server",
-        help="cdxgen server url. Eg: http://cdxgen:9090",
-    )
-    parser.add_argument(
-        "--debug",
-        action="store_true",
-        default=False,
-        dest="enable_debug",
-        help="Run depscan in debug mode.",
-    )
-    parser.add_argument(
-        "--explain",
-        action="store_true",
-        default=False,
-        dest="explain",
-        help="Makes depscan to explain the various analysis. Useful for creating detailed reports.",
-    )
-    parser.add_argument(
-        "--reachables-slices-file",
-        dest="reachables_slices_file",
-        help="Path for the reachables slices file created by atom.",
-    )
-    parser.add_argument(
-        "--purl",
-        dest="search_purl",
-        help="Scan a single package url.",
-    )
-    parser.add_argument(
-        "-v",
-        "--version",
-        help="Display the version",
-        action="version",
-        version="%(prog)s " + utils.get_version(),
-    )
+    parser = build_parser()
     return parser.parse_args()
 
 
-def scan(db, project_type, pkg_list, suggest_mode):
-    """
-    Method to search packages in our vulnerability database
-
-    :param db: Reference to db
-    :param project_type: Project Type
-    :param pkg_list: List of packages
-    :param suggest_mode: True if package fix version should be normalized across
-            findings
-    :returns: A list of package issue objects or dictionaries.
-              A dictionary mapping package names to their aliases.
-              A dictionary mapping packages to their suggested fix versions.
-              A dictionary mapping package URLs to their aliases.
-    """
-    if not pkg_list:
-        LOG.debug("Empty package search attempted!")
-    else:
-        LOG.debug("Scanning %d oss dependencies for issues", len(pkg_list))
-    results, pkg_aliases, purl_aliases = utils.search_pkgs(
-        db, project_type, pkg_list
-    )
-    # pkg_aliases is a dict that can be used to find the original vendor and
-    # package name This way we consistently use the same names used by the
-    # caller irrespective of how the result was obtained
-    sug_version_dict = {}
-    if suggest_mode:
-        # From the results identify optimal max version
-        sug_version_dict = suggest_version(results, pkg_aliases, purl_aliases)
-        if sug_version_dict:
-            LOG.debug(
-                "Adjusting fix version based on the initial suggestion %s",
-                sug_version_dict,
-            )
-            # Recheck packages
-            sug_pkg_list = []
-            for k, v in sug_version_dict.items():
-                if not v:
-                    continue
-                vendor = ""
-                version = v
-                # Key is already a purl
-                if k.startswith("pkg:"):
-                    try:
-                        purl_obj = parse_purl(k)
-                        vendor = purl_obj.get("namespace")
-                        if not vendor:
-                            vendor = purl_obj.get("type") or ""
-                        name = purl_obj.get("name") or ""
-                        version = purl_obj.get("version") or ""
-                        sug_pkg_list.append(
-                            {
-                                "vendor": vendor,
-                                "name": name,
-                                "version": version,
-                                "purl": k,
-                            }
-                        )
-                        continue
-                    except Exception:
-                        pass
-                tmp_a = k.split(":")
-                if len(tmp_a) == 3:
-                    vendor = tmp_a[0]
-                    name = tmp_a[1]
-                else:
-                    name = tmp_a[0]
-                # De-alias the vendor and package name
-                full_pkg = f"{vendor}:{name}:{version}"
-                full_pkg = pkg_aliases.get(full_pkg, full_pkg)
-                vendor, name, version = full_pkg.split(":")
-                sug_pkg_list.append(
-                    {"vendor": vendor, "name": name, "version": version}
-                )
-            LOG.debug(
-                "Re-checking our suggestion to ensure there are no further "
-                "vulnerabilities"
-            )
-            override_results, _, _ = utils.search_pkgs(
-                db, project_type, sug_pkg_list
-            )
-            if override_results:
-                new_sug_dict = suggest_version(override_results)
-                LOG.debug("Received override results: %s", new_sug_dict)
-                for nk, nv in new_sug_dict.items():
-                    sug_version_dict[nk] = nv
-    return results, pkg_aliases, sug_version_dict, purl_aliases
-
-
-def summarise(
+def vdr_analyze_summarize(
     project_type,
     results,
-    pkg_aliases,
-    purl_aliases,
-    sug_version_dict,
+    suggest_mode,
     scoped_pkgs,
-    report_file,
     bom_file,
+    bom_dir,
+    pkg_list,
+    reachability_analyzer,
+    reachability_options,
     no_vuln_table=False,
-    direct_purls=None,
-    reached_purls=None,
+    fuzzy_search=False,
+    search_order=None,
 ):
     """
-    Method to summarise the results
-    :param project_type: Project type
-    :param results: Scan or audit results
-    :param pkg_aliases: Package aliases used
-    :param purl_aliases: Package URL to package name aliase
-    :param sug_version_dict: Dictionary containing version suggestions
-    :param scoped_pkgs: Dict containing package scopes
-    :param report_file: Output report file
-    :param bom_file: SBOM file
+    Method to perform VDR analysis followed by summarization.
+    :param project_type: Project type.
+    :param results: Scan or audit results.
+    :param suggest_mode: Normalize fix versions automatically.
+    :param scoped_pkgs: Dict containing package scopes.
+    :param bom_file: Single BOM file.
+    :param bom_dir: Directory containining bom files.
+    :param pkg_list: Direct list of packages when the bom file is empty.
+    :param reachability_analyzer: Reachability Analyzer specified.
+    :param reachability_options: Reachability Analyzer options.
     :param no_vuln_table: Boolean to indicate if the results should get printed
-            to the console
+            to the console.
+    :param fuzzy_search: Perform fuzzy search.
+    :param search_order: Search order.
+
     :return: A dict of vulnerability and severity summary statistics
     """
-    if report_file:
-        jsonl_report(
-            project_type,
-            results,
-            pkg_aliases,
-            purl_aliases,
-            sug_version_dict,
-            scoped_pkgs,
-            report_file,
-            direct_purls=direct_purls,
-            reached_purls=reached_purls,
-        )
-    options = PrepareVdrOptions(
+    pkg_vulnerabilities = []
+    summary = {}
+    direct_purls = {}
+    reached_purls = {}
+    reached_services = {}
+    endpoint_reached_purls = {}
+    # Perform the reachability analysis first
+    reach_result = get_reachability_impl(
+        reachability_analyzer, reachability_options
+    ).process()
+    # We now have reachability results, OpenAPI endpoints, BOMs, and component scope information.
+    if reach_result and reach_result.success:
+        direct_purls = reach_result.direct_purls
+        reached_purls = reach_result.reached_purls
+        reached_services = reach_result.reached_services
+        endpoint_reached_purls = reach_result.endpoint_reached_purls
+    console.record = True
+    # We might already have the needed slices files when we reach here.
+    options = VdrAnalysisKV(
         project_type,
         results,
-        pkg_aliases,
-        purl_aliases,
-        sug_version_dict,
+        pkg_aliases={},
+        purl_aliases={},
+        suggest_mode=suggest_mode,
         scoped_pkgs=scoped_pkgs,
         no_vuln_table=no_vuln_table,
         bom_file=bom_file,
+        bom_dir=bom_dir,
+        pkg_list=pkg_list,
         direct_purls=direct_purls,
         reached_purls=reached_purls,
-    )
-    pkg_vulnerabilities, pkg_group_rows = prepare_vdr(options)
-    vdr_file = bom_file.replace(".json", ".vdr.json") if bom_file else None
-    if pkg_vulnerabilities and bom_file:
-        try:
-            with open(bom_file, encoding="utf-8") as fp:
-                bom_data = json.load(fp)
-                if bom_data:
-                    # Add depscan information as metadata
-                    metadata = bom_data.get("metadata", {})
-                    tools = metadata.get("tools", {})
-                    bom_version = str(bom_data.get("version", 1))
-                    # Update the version
-                    if bom_version.isdigit():
-                        bom_version = int(bom_version) + 1
-                        bom_data["version"] = bom_version
-                    # Update the tools section
-                    if isinstance(tools, dict):
-                        components = tools.get("components", [])
-                        ds_version = utils.get_version()
-                        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,
-                            }
-                        )
-                        tools["components"] = components
-                        metadata["tools"] = tools
-                        bom_data["metadata"] = metadata
-
-                    bom_data["vulnerabilities"] = pkg_vulnerabilities
-                    with open(vdr_file, mode="w", encoding="utf-8") as vdrfp:
-                        json.dump(bom_data, vdrfp, indent=4)
-                        LOG.debug(
-                            "VDR file %s generated successfully", vdr_file
-                        )
-        except Exception:
-            LOG.warning("Unable to generate VDR file for this scan")
-    summary = summary_stats(results)
-    return summary, vdr_file, pkg_vulnerabilities, pkg_group_rows
-
+        reached_services=reached_services,
+        endpoint_reached_purls=endpoint_reached_purls,
+        console=console,
+        logger=LOG,
+        fuzzy_search=fuzzy_search,
+        search_order=search_order,
+    )
+    ds_version = get_version()
+    vdr_result = VDRAnalyzer(vdr_options=options).process()
+    vdr_file = bom_file.replace(".cdx.json", ".vdr.json") if bom_file else None
+    if not vdr_file and bom_dir:
+        vdr_file = os.path.join(bom_dir, DEPSCAN_DEFAULT_VDR_FILE)
+    if vdr_result.success:
+        pkg_vulnerabilities = vdr_result.pkg_vulnerabilities
+        cdx_vdr_data = None
+        # Always create VDR files even when empty
+        if pkg_vulnerabilities is not None:
+            # Case 1: Single BOM file resulting in a single VDR file
+            if bom_file:
+                cdx_vdr_data = json_load(bom_file, log=LOG)
+            # Case 2: Multiple BOM files in a bom directory
+            elif bom_dir:
+                cdx_vdr_data = create_empty_vdr(pkg_list, ds_version)
+        if cdx_vdr_data:
+            export_bom(cdx_vdr_data, ds_version, pkg_vulnerabilities, vdr_file)
+            LOG.debug(f"The VDR file '{vdr_file}' was created successfully.")
+        else:
+            LOG.debug(
+                f"VDR file '{vdr_file}' was not created for the type {project_type}."
+            )
+        summary = summary_stats(pkg_vulnerabilities)
+    elif bom_dir or bom_file or pkg_list:
+        if project_type != "bom":
+            LOG.info("No vulnerabilities found for project type '%s'!", project_type)
+        else:
+            LOG.info("No vulnerabilities found!")
+    return summary, vdr_file, vdr_result
 
-@app.get("/")
-async def index():
-    """
 
-    :return: An empty dictionary
+def set_project_types(args, src_dir):
     """
-    return {}
+    Detects the project types and perform the right type of scan
 
+    :param args: cli arguments
+    :param src_dir: source directory
 
-@app.get("/cache")
-async def cache():
+    :return: A tuple containing the package list, the parsed package URL object,
+    and the list of project types.
     """
+    pkg_list, purl_obj = [], {}
+    project_types_list: List[str] = []
+    if args.search_purl:
+        purl_obj = parse_purl(args.search_purl)
+        purl_obj["purl"] = args.search_purl
+        purl_obj["vendor"] = purl_obj.get("namespace")
+        if purl_obj.get("type"):
+            project_types_list = [purl_obj.get("type", "")]
+        pkg_list = [purl_obj]
+    elif args.bom or args.bom_dir:
+        project_types_list = ["bom"]
+    elif args.project_type:
+        project_types_list = (
+            args.project_type
+            if isinstance(args.project_type, list)
+            else args.project_type.split(",")
+        )
+        if len(project_types_list) == 1 and "," in project_types_list[0]:
+            project_types_list = project_types_list[0].split(",")
+    elif not args.non_universal_scan:
+        project_types_list = [UNIVERSAL_SCAN_TYPE]
+    else:
+        project_types_list = utils.detect_project_type(src_dir)
+    return pkg_list, project_types_list
 
-    :return: a JSON response indicating the status of the caching operation.
-    """
-    db = db_lib.get()
-    if not db_lib.index_count(db["index_file"]):
-        paths_list = download_image()
-        if paths_list:
-            return {
-                "error": "false",
-                "message": "vulnerability database cached successfully",
-            }
-        else:
-            return {
-                "error": "true",
-                "message": "vulnerability database was not cached",
-            }
-    return {
-        "error": "false",
-        "message": "vulnerability database already exists",
-    }
 
+if QUART_AVAILABLE:
 
-@app.route("/scan", methods=["GET", "POST"])
-async def run_scan():
-    """
-    :return: A JSON response containing the SBOM file path and a list of
-    vulnerabilities found in the scanned packages
-    """
-    q = request.args
-    params = await request.get_json()
-    uploaded_bom_file = await request.files
+    @app.get("/")
+    async def index():
+        """
 
-    url = None
-    path = None
-    multi_project = None
-    project_type = None
-    results = []
-    db = db_lib.get()
-    profile = "generic"
-    deep = False
-    if q.get("url"):
-        url = q.get("url")
-    if q.get("path"):
-        path = q.get("path")
-    if q.get("multiProject"):
-        multi_project = q.get("multiProject", "").lower() in ("true", "1")
-    if q.get("deep"):
-        deep = q.get("deep", "").lower() in ("true", "1")
-    if q.get("type"):
-        project_type = q.get("type")
-    if q.get("profile"):
-        profile = q.get("profile")
-    if params is not None:
-        if not url and params.get("url"):
-            url = params.get("url")
-        if not path and params.get("path"):
-            path = params.get("path")
-        if not multi_project and params.get("multiProject"):
-            multi_project = params.get("multiProject", "").lower() in (
-                "true",
-                "1",
-            )
-        if not deep and params.get("deep"):
-            deep = params.get("deep", "").lower() in (
-                "true",
-                "1",
-            )
-        if not project_type and params.get("type"):
-            project_type = params.get("type")
-        if not profile and params.get("profile"):
-            profile = params.get("profile")
+        :return: An empty dictionary
+        """
+        return {}
 
-    if not path and not url and (uploaded_bom_file.get("file", None) is None):
-        return {
-            "error": "true",
-            "message": "path or url or a bom file upload is required",
-        }, 400
-    if not project_type:
-        return {"error": "true", "message": "project type is required"}, 400
+    @app.get("/download-vdb")
+    async def download_vdb():
+        """
 
-    if not db_lib.index_count(db["index_file"]):
-        return (
-            {
+        :return: a JSON response indicating the status of the caching operation.
+        """
+        if db_lib.needs_update(days=0, hours=VDB_AGE_HOURS, default_status=False):
+            if not ORAS_AVAILABLE:
+                return {
+                    "error": "true",
+                    "message": "The oras package must be installed to automatically download the vulnerability database. Install depscan using `pip install owasp-depscan[all]` or use the official container image.",
+                }
+            if download_image(vdb_database_url, config.DATA_DIR):
+                return {
+                    "error": "false",
+                    "message": "vulnerability database downloaded successfully",
+                }
+            return {
                 "error": "true",
-                "message": "Vulnerability database is empty. Prepare the "
-                "vulnerability database by invoking /cache endpoint "
-                "before running scans.",
-            },
-            500,
-            {"Content-Type": "application/json"},
-        )
-
-    cdxgen_server = app.config.get("CDXGEN_SERVER_URL")
-    bom_file_path = None
+                "message": "vulnerability database did not get downloaded correctly. Check the server logs.",
+            }
+        return {
+            "error": "false",
+            "message": "vulnerability database already exists",
+        }
+
+    @app.route("/scan", methods=["GET", "POST"])
+    async def run_scan():
+        """
+        :return: A JSON response containing the SBOM file path and a list of
+        vulnerabilities found in the scanned packages
+        """
+        q = request.args
+        params = await request.get_json()
+        uploaded_bom_file = await request.files
+
+        url = None
+        path = None
+        multi_project = None
+        project_type = None
+        results = []
+        profile = "generic"
+        deep = False
+        suggest_mode = True if q.get("suggest") in ("true", "1") else False
+        fuzzy_search = True if q.get("fuzzy_search") in ("true", "1") else False
+        if q.get("url"):
+            url = q.get("url")
+        if q.get("path"):
+            path = q.get("path")
+        if q.get("multiProject"):
+            multi_project = q.get("multiProject", "").lower() in ("true", "1")
+        if q.get("deep"):
+            deep = q.get("deep", "").lower() in ("true", "1")
+        if q.get("type"):
+            project_type = q.get("type")
+        if q.get("profile"):
+            profile = q.get("profile")
+        if params is not None:
+            if not url and params.get("url"):
+                url = params.get("url")
+            if not path and params.get("path"):
+                path = params.get("path")
+            if not multi_project and params.get("multiProject"):
+                multi_project = params.get("multiProject", "").lower() in (
+                    "true",
+                    "1",
+                )
+            if not deep and params.get("deep"):
+                deep = params.get("deep", "").lower() in (
+                    "true",
+                    "1",
+                )
+            if not project_type and params.get("type"):
+                project_type = params.get("type")
+            if not profile and params.get("profile"):
+                profile = params.get("profile")
 
-    if uploaded_bom_file.get("file", None) is not None:
-        bom_file = uploaded_bom_file["file"]
-        bom_file_content = bom_file.read().decode("utf-8")
-        try:
-            if str(bom_file.filename).endswith(".json"):
-                _ = json.loads(bom_file_content)
-            else:
-                _ = parse(bom_file_content)
-        except Exception as e:
-            LOG.info(e)
+        if not path and not url and (uploaded_bom_file.get("file", None) is None):
+            return {
+                "error": "true",
+                "message": "path or url or a bom file upload is required",
+            }, 400
+        if not project_type:
+            return {"error": "true", "message": "project type is required"}, 400
+        if db_lib.needs_update(days=0, hours=VDB_AGE_HOURS, default_status=False):
             return (
                 {
                     "error": "true",
-                    "message": "The uploaded file must be a valid JSON or XML.",
+                    "message": "Vulnerability database is empty. Prepare the "
+                    "vulnerability database by invoking /download-vdb endpoint "
+                    "before running scans.",
                 },
-                400,
+                500,
                 {"Content-Type": "application/json"},
             )
 
-        LOG.debug("Processing uploaded file")
-        bom_file_suffix = str(bom_file.filename).rsplit(".", maxsplit=1)[-1]
-        tmp_bom_file = tempfile.NamedTemporaryFile(
-            delete=False, suffix=f".bom.{bom_file_suffix}"
-        )
-        with open(tmp_bom_file.name, "w", encoding="utf-8") as f:
-            f.write(bom_file_content)
-        path = tmp_bom_file.name
-
-    # Path points to a project directory
-    # Bug# 233. Path could be a url
-    if url or (path and os.path.isdir(path)):
-        with tempfile.NamedTemporaryFile(
-            delete=False, suffix=".bom.json"
-        ) as bfp:
-            bom_status = create_bom(
-                project_type,
-                bfp.name,
-                path,
-                deep,
-                {
-                    "url": url,
-                    "path": path,
-                    "type": project_type,
-                    "multiProject": multi_project,
-                    "cdxgen_server": cdxgen_server,
-                    "profile": profile,
-                },
-            )
-            if bom_status:
-                LOG.debug("BOM file was generated successfully at %s", bfp.name)
-                bom_file_path = bfp.name
+        cdxgen_server = app.config.get("CDXGEN_SERVER_URL")
+        bom_file_path = None
 
-    # Path points to a SBOM file
-    else:
-        if os.path.exists(path):
-            bom_file_path = path
+        if uploaded_bom_file.get("file", None) is not None:
+            bom_file = uploaded_bom_file["file"]
+            bom_file_content = bom_file.read().decode("utf-8")
+            try:
+                _ = json.loads(bom_file_content)
+            except Exception as e:
+                LOG.info(e)
+                return (
+                    {
+                        "error": "true",
+                        "message": "The uploaded file must be a valid JSON or XML.",
+                    },
+                    400,
+                    {"Content-Type": "application/json"},
+                )
 
-    if bom_file_path is not None:
-        pkg_list = get_pkg_list(bom_file_path)
-        if not pkg_list:
-            return {}
-        if project_type in type_audit_map:
-            audit_results = audit(project_type, pkg_list)
-            if audit_results:
-                results = results + audit_results
-        vdb_results, pkg_aliases, sug_version_dict, purl_aliases = scan(
-            db, project_type, pkg_list, True
-        )
-        if vdb_results:
-            results += vdb_results
-        results = [r.to_dict() for r in results]
-        bom_data = None
-        with open(bom_file_path, encoding="utf-8") as fp:
-            bom_data = json.load(fp)
-        if not bom_data:
-            return (
-                {
-                    "error": "true",
-                    "message": "Unable to generate SBOM. Check your input path or url.",
-                },
-                400,
-                {"Content-Type": "application/json"},
+            LOG.debug("Processing uploaded file")
+            bom_file_suffix = str(bom_file.filename).rsplit(".", maxsplit=1)[-1]
+            tmp_bom_file = tempfile.NamedTemporaryFile(
+                delete=False, suffix=f".bom.{bom_file_suffix}"
             )
-        options = PrepareVdrOptions(
-            project_type,
-            results,
-            pkg_aliases,
-            purl_aliases,
-            sug_version_dict,
-            scoped_pkgs={},
-            no_vuln_table=True,
-            bom_file=bom_file_path,
-            direct_purls=None,
-            reached_purls=None,
-        )
-        pkg_vulnerabilities, _ = prepare_vdr(options)
-        if pkg_vulnerabilities:
-            bom_data["vulnerabilities"] = pkg_vulnerabilities
-        return json.dumps(bom_data), 200, {"Content-Type": "application/json"}
+            path = tmp_bom_file.name
+            file_write(path, bom_file_content)
+
+        # Path points to a project directory
+        # Bug# 233. Path could be a url
+        if url or (path and os.path.isdir(path)):
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".bom.json") as bfp:
+                project_type_list = project_type.split(",")
+                bom_status = create_bom(
+                    bfp.name,
+                    path,
+                    {
+                        "url": url,
+                        "path": path,
+                        "project_type": project_type_list,
+                        "multiProject": multi_project,
+                        "cdxgen_server": cdxgen_server,
+                        "profile": profile,
+                        "deep": deep,
+                    },
+                )
+                if bom_status:
+                    LOG.debug("BOM file was generated successfully at %s", bfp.name)
+                    bom_file_path = bfp.name
 
-    else:
+        # Path points to a SBOM file
+        else:
+            if os.path.exists(path):
+                bom_file_path = path
+        # Direct purl-based lookups are not supported yet.
+        if bom_file_path is not None:
+            pkg_list, _ = get_pkg_list(bom_file_path)
+            # Here we are assuming there will be only one type
+            if project_type in type_audit_map:
+                audit_results = audit(project_type, pkg_list)
+                if audit_results:
+                    results = results + audit_results
+            if not pkg_list:
+                LOG.debug("Empty package search attempted!")
+            else:
+                LOG.debug("Scanning %d oss dependencies for issues", len(pkg_list))
+            bom_data = json_load(bom_file_path)
+            if not bom_data:
+                return (
+                    {
+                        "error": "true",
+                        "message": "Unable to generate SBOM. Check your input path or url.",
+                    },
+                    400,
+                    {"Content-Type": "application/json"},
+                )
+            options = VdrAnalysisKV(
+                project_type,
+                results,
+                pkg_aliases={},
+                purl_aliases={},
+                suggest_mode=suggest_mode,
+                scoped_pkgs={},
+                no_vuln_table=True,
+                bom_file=bom_file_path,
+                pkg_list=[],
+                direct_purls={},
+                reached_purls={},
+                console=console,
+                logger=LOG,
+                fuzzy_search=fuzzy_search,
+            )
+            vdr_result = VDRAnalyzer(vdr_options=options).process()
+            if vdr_result.success:
+                pkg_vulnerabilities = vdr_result.pkg_vulnerabilities
+                if pkg_vulnerabilities:
+                    bom_data["vulnerabilities"] = pkg_vulnerabilities
+                return json.dumps(bom_data), 200, {"Content-Type": "application/json"}
         return (
             {
                 "error": "true",
@@ -714,48 +443,50 @@ async def run_scan():
             {"Content-Type": "application/json"},
         )
 
+    def run_server(args):
+        """
+        Run depscan as server
 
-def run_server(args):
-    """
-    Run depscan as server
-
-    :param args: Command line arguments passed to the function.
-    """
-    print(LOGO)
-    console.print(
-        f"Depscan server running on {args.server_host}:{args.server_port}"
-    )
-    app.config["CDXGEN_SERVER_URL"] = args.cdxgen_server
-    app.run(
-        host=args.server_host,
-        port=args.server_port,
-        debug=os.getenv("SCAN_DEBUG_MODE") == "debug"
-        or os.getenv("AT_DEBUG_MODE") == "debug",
-        use_reloader=False,
-    )
+        :param args: Command line arguments passed to the function.
+        """
+        print(LOGO)
+        console.print(
+            f"Depscan server running on {args.server_host}:{args.server_port}"
+        )
+        app.config["CDXGEN_SERVER_URL"] = args.cdxgen_server
+        app.run(
+            host=args.server_host,
+            port=args.server_port,
+            debug=os.getenv("SCAN_DEBUG_MODE") == "debug",
+            use_reloader=False,
+        )
 
 
-def main():
+def run_depscan(args):
     """
     Detects the project type, performs various scans and audits,
     and generates reports based on the results.
     """
-    args = build_args()
     perform_risk_audit = args.risk_audit
     # declare variables that get initialized only conditionally
     (
         summary,
         vdr_file,
         bom_file,
+        prebuild_bom_file,
+        build_bom_file,
+        postbuild_bom_file,
+        container_bom_file,
+        operations_bom_file,
         pkg_list,
-        pkg_vulnerabilities,
-        pkg_group_rows,
-    ) = (None, None, None, None, None, None)
+        all_pkg_vulnerabilities,
+        all_pkg_group_rows,
+    ) = (None, None, None, None, None, None, None, None, None, [], {})
     if (
         os.getenv("CI")
+        and not os.getenv("GITHUB_REPOSITORY", "").lower().startswith("owasp")
         and not args.no_banner
-        and not os.getenv("INPUT_THANK_YOU", "")
-        == ("I have sponsored OWASP-dep-scan.")
+        and not os.getenv("INPUT_THANK_YOU", "") == "I have sponsored OWASP-dep-scan."
     ):
         console.print(
             Panel(
@@ -764,14 +495,49 @@ def main():
                 expand=False,
             )
         )
-    # Should we turn on the debug mode
+    # Should we be quiet
+    if args.quiet:
+        args.explain = False
+        LOG.disabled = True
+        args.enable_debug = False
+        os.environ["SCAN_DEBUG_MODE"] = "off"
+        os.environ["CDXGEN_DEBUG_MODE"] = "off"
+        console.quiet = True
+        args.no_vuln_table = True
+    # Should we enable debug
     if args.enable_debug:
-        os.environ["AT_DEBUG_MODE"] = "debug"
+        os.environ["SCAN_DEBUG_MODE"] = "debug"
+        os.environ["CDXGEN_DEBUG_MODE"] = "debug"
         LOG.setLevel(DEBUG)
     if args.server_mode:
-        return run_server(args)
+        if QUART_AVAILABLE:
+            return run_server(args)
+        else:
+            LOG.info(
+                "The required packages for server mode are unavailable. Reinstall depscan using `pip install owasp-depscan[all]`."
+            )
+            return False
     if not args.no_banner:
-        print(LOGO)
+        with contextlib.suppress(UnicodeEncodeError):
+            print(LOGO)
+    # Break early if the user prefers CPE-based searches
+    search_order = args.search_order
+    if search_order:
+        if search_order.startswith("c") and not args.bom and not args.bom_dir:
+            LOG.warning(
+                "To perform CPE-based searches, the SBOM must include a CPE identifier for each component. Generate the SBOM using a compatible tool such as Syft or Trivy, and invoke depscan with the --bom or --bom-dir argument."
+            )
+            LOG.info(
+                "Alternatively, run depscan without the `--search-order` argument to perform PURL-based searches. This method is more accurate and recommended."
+            )
+            sys.exit(1)
+        elif search_order.startswith("u") and not os.getenv("FETCH_LICENSE"):
+            LOG.warning(
+                "To perform URL-based searches, the SBOM must include externalReferences with a URL. Set the environment variable `FETCH_LICENSE=true` to force cdxgen to populate this attribute."
+            )
+            LOG.info(
+                "Alternatively, include the project type `-t license` to ensure this attribute is populated."
+            )
     src_dir = args.src_dir_image
     if not src_dir or src_dir == ".":
         if src_dir == "." or args.search_purl:
@@ -779,9 +545,51 @@ def main():
         # Try to infer from the bom file
         elif args.bom and os.path.exists(args.bom):
             src_dir = os.path.dirname(os.path.realpath(args.bom))
+        elif args.bom_dir and os.path.exists(args.bom_dir):
+            src_dir = os.path.realpath(args.bom_dir)
         else:
             src_dir = os.getcwd()
     reports_dir = args.reports_dir
+    # User has not provided an explicit reports_dir. Reuse the bom_dir
+    if not reports_dir and args.bom_dir:
+        reports_dir = os.path.realpath(args.bom_dir)
+    # Are we running for a BOM directory
+    bom_dir_mode = args.bom_dir and os.path.exists(args.bom_dir)
+    # Are we running with a config file
+    config_file_mode = args.config and os.path.exists(args.config)
+    depscan_options = {**vars(args)}
+    depscan_options["src_dir"] = src_dir
+    depscan_options["reports_dir"] = reports_dir
+    # Is the user looking for semantic analysis?
+    # We can default to this when run against a BOM directory
+    if (
+        args.reachability_analyzer == "SemanticReachability"
+    ) and args.vuln_analyzer != "LifecycleAnalyzer":
+        LOG.debug(
+            "Automatically switching to the `LifecycleAnalyzer` for vulnerability analysis."
+        )
+        depscan_options["vuln_analyzer"] = "LifecycleAnalyzer"
+        args.vuln_analyzer = "LifecycleAnalyzer"
+    # Should we download the latest vdb.
+    if db_lib.needs_update(
+        days=0,
+        hours=VDB_AGE_HOURS,
+        default_status=db_lib.get_db_file_metadata is not None,
+    ):
+        if ORAS_AVAILABLE:
+            with console.status(
+                f"Downloading the latest vulnerability database to {config.DATA_DIR}. Please wait ...",
+                spinner=SPINNER,
+            ) as vdb_download_status:
+                if not IS_CI:
+                    vdb_download_status.stop()
+                # This line may exit with an exception if the database cannot be downloaded.
+                # Example: urllib3.exceptions.IncompleteRead, urllib3.exceptions.ProtocolError, requests.exceptions.ChunkedEncodingError
+                download_image(vdb_database_url, config.DATA_DIR)
+        else:
+            LOG.warning(
+                "The latest vulnerability database is not found. Follow the documentation to manually download it."
+            )
     if args.csaf:
         toml_file_path = os.getenv(
             "DEPSCAN_CSAF_TEMPLATE", os.path.join(src_dir, "csaf.toml")
@@ -789,9 +597,7 @@ def main():
         if not os.path.exists(toml_file_path):
             LOG.info("CSAF toml not found, creating template in %s", src_dir)
             write_toml(toml_file_path)
-            LOG.info(
-                "Please fill out the toml with your details and rerun depscan."
-            )
+            LOG.info("Please fill out the toml with your details and rerun depscan.")
             LOG.info(
                 "Check out our CSAF documentation for an explanation of "
                 "this feature. https://github.com/owasp-dep-scan/dep-scan"
@@ -803,32 +609,24 @@ def main():
                 "depscan."
             )
             sys.exit(0)
-    # Detect the project types and perform the right type of scan
-    if args.project_type:
-        project_types_list = args.project_type.split(",")
-    elif args.search_purl:
+    pkg_list, project_types_list = set_project_types(args, src_dir)
+    if args.search_purl:
         # Automatically enable risk audit for single purl searches
         perform_risk_audit = True
-        purl_obj = parse_purl(args.search_purl)
-        purl_obj["purl"] = args.search_purl
-        purl_obj["vendor"] = purl_obj.get("namespace")
-        project_types_list = [purl_obj.get("type")]
-        pkg_list = [purl_obj]
-    elif args.bom:
-        project_types_list = ["bom"]
-    elif not args.non_universal_scan:
-        project_types_list = [UNIVERSAL_SCAN_TYPE]
-    else:
-        project_types_list = utils.detect_project_type(src_dir)
-    db = db_lib.get()
-    run_cacher = args.cache
-    areport_file = (
-        args.report_file
-        if args.report_file
-        else os.path.join(reports_dir, "depscan.json")
+    # Construct the various report files
+    html_report_file = depscan_options.get(
+        "html_report_file", os.path.join(reports_dir, "depscan.html")
+    )
+    pdf_report_file = depscan_options.get(
+        "pdf_report_file", os.path.join(reports_dir, "depscan.pdf")
     )
-    html_file = areport_file.replace(".json", ".html")
-    pdf_file = areport_file.replace(".json", ".pdf")
+    txt_report_file = depscan_options.get(
+        "txt_report_file", os.path.join(reports_dir, "depscan.txt")
+    )
+    run_config_file = os.path.join(reports_dir, "depscan.toml.sample")
+    depscan_options["html_report_file"] = html_report_file
+    depscan_options["pdf_report_file"] = pdf_report_file
+    depscan_options["txt_report_file"] = txt_report_file
     # Create reports directory
     if reports_dir and not os.path.exists(reports_dir):
         os.makedirs(reports_dir, exist_ok=True)
@@ -846,41 +644,126 @@ def main():
                 expand=False,
             )
         )
+    # Let’s create a sample configuration file based on the CLI options used.
+    if not config_file_mode:
+        run_config = {**depscan_options}
+        del run_config["no_banner"]
+        write_toml(run_config_file, run_config, write_version=False)
+        LOG.debug(
+            f"Created a sample depscan config file at '{run_config_file}', based on this run."
+        )
+    # We have everything needed to start the composition analysis. There are many approaches to implementing an SCA tool.
+    # Our style of analysis is comparable to that of an intelligent Hubble telescope or a rover—examining the same subject through multiple optics, colors, and depths to gain a deeper understanding.
+    # We begin by iterating over the project types provided or assumed.
     for project_type in project_types_list:
         results = []
-        report_file = areport_file.replace(".json", f"-{project_type}.json")
-        risk_report_file = areport_file.replace(
-            ".json", f"-risk.{project_type}.json"
+        vuln_analyzer = args.vuln_analyzer
+        # Are we performing a lifecycle analysis
+        if not args.search_purl and (
+            vuln_analyzer == "LifecycleAnalyzer"
+            or (vuln_analyzer == "auto" and bom_dir_mode)
+        ):
+            if args.reachability_analyzer == "SemanticReachability":
+                if not args.bom_dir:
+                    LOG.info(
+                        "Semantic Reachability analysis requested for project type '%s'. This might take a while ...",
+                        project_type,
+                    )
+                else:
+                    LOG.info(
+                        "Attempting semantic analysis using existing data at '%s'",
+                        args.bom_dir,
+                    )
+            else:
+                LOG.info(
+                    "Lifecycle-based vulnerability analysis requested for project type '%s'. This might take a while ...",
+                    project_type,
+                )
+            prebuild_bom_file = os.path.join(
+                reports_dir, f"sbom-prebuild-{project_type}.cdx.json"
+            )
+            build_bom_file = os.path.join(
+                reports_dir, f"sbom-build-{project_type}.cdx.json"
+            )
+            postbuild_bom_file = os.path.join(
+                reports_dir, f"sbom-postbuild-{project_type}.cdx.json"
+            )
+            # We support only one container SBOM per project.
+            # Projects that rely on docker compose and multiple services require some thinking
+            container_bom_file = os.path.join(
+                reports_dir, f"sbom-container-{project_type}.cdx.json"
+            )
+            operations_bom_file = os.path.join(
+                reports_dir, f"sbom-operations-{project_type}.cdx.json"
+            )
+            if vuln_analyzer == "auto":
+                vuln_analyzer = "LifecycleAnalyzer"
+                depscan_options["vuln_analyzer"] = "LifecycleAnalyzer"
+            # We need to set the following two values to make the rest of the code correctly use
+            # the generated BOM files after lifecycle analysis
+            depscan_options["lifecycle_analysis_mode"] = True
+            if not args.bom_dir:
+                args.bom_dir = os.path.realpath(reports_dir)
+        # If the user opts out of lifecycle analysis, we need to maintain multiple SBOMs based on the project type.
+        bom_file = os.path.join(reports_dir, f"sbom-{project_type}.cdx.json")
+        risk_report_file = os.path.join(
+            reports_dir, f"depscan-risk-{project_type}.json"
         )
         # Are we scanning a single purl
         if args.search_purl:
             bom_file = None
             creation_status = True
         # Are we scanning a bom file
+        ###################
+        # Note to students and researchers benchmarking depscan:
+        #   we’ve seen attempts to run depscan using SBOMs generated by tools like Syft, Trivy, etc.
+        # It’s important to understand that not all SBOMs contain the same level of detail.
+        # Component PURLs can differ slightly, especially in qualifiers.
+        #
+        # For container SBOMs, qualifiers like distro_name and distro_version are critical for accurate results.
+        # Tools like Syft and Trivy often include internal metadata—such as vendor IDs or fabricated CPE strings—to brute-force vulnerability matches.
+        # Because of these inconsistencies, it’s not possible to achieve identical results with depscan when using a non-cdxgen or non-blint SBOM.
+        # If in doubt, speak to us before benchmarking depscan. Don’t run depscan with default settings and expect magic.
+        # SCA and xBOM are complex domains that require understanding, configuration, and continuous learning.
+        ###################
         elif args.bom and os.path.exists(args.bom):
             bom_file = args.bom
             creation_status = True
+        # Are we scanning a bom directory
+        elif bom_dir_mode:
+            bom_file = None
+            creation_status = True
         else:
-            if args.profile in ("appsec", "research"):
-                # The bom file has to be called bom.json for atom reachables to work :(
-                bom_file = os.path.join(src_dir, "bom.json")
-            else:
-                bom_file = report_file.replace("depscan-", "sbom-")
+            # Create a bom for each project type
             creation_status = create_bom(
-                project_type,
                 bom_file,
                 src_dir,
-                args.deep_scan,
                 {
-                    "cdxgen_server": args.cdxgen_server,
-                    "profile": args.profile,
-                    "cdxgen_args": args.cdxgen_args,
+                    **depscan_options,
+                    "project_type": [project_type],
+                    "bom_file": bom_file,
+                    "prebuild_bom_file": prebuild_bom_file,
+                    "build_bom_file": build_bom_file,
+                    "postbuild_bom_file": postbuild_bom_file,
+                    "container_bom_file": container_bom_file,
+                    "operations_bom_file": operations_bom_file,
                 },
             )
         if not creation_status:
-            LOG.debug("Bom file %s was not created successfully", bom_file)
+            LOG.warning(
+                "The BOM file `%s` was not created successfully. Set the `SCAN_DEBUG_MODE=debug` environment variable to troubleshoot.",
+                bom_file,
+            )
             continue
-        if bom_file:
+        # We have a BOM directory. Let’s aggregate all packages from every file within it.
+        if args.bom_dir:
+            LOG.debug(
+                "Collecting components from all the BOM files at %s",
+                args.bom_dir,
+            )
+            pkg_list = get_all_pkg_list(args.bom_dir)
+        # We are working with a single BOM file and will collect all packages from it accordingly.
+        elif bom_file:
             LOG.debug("Scanning using the bom file %s", bom_file)
             if not args.bom:
                 LOG.info(
@@ -888,11 +771,15 @@ def main():
                     "depscan with --bom %s instead of -i",
                     bom_file,
                 )
-            pkg_list = get_pkg_list(bom_file)
-        if not pkg_list:
-            LOG.debug("No packages found in the project!")
+            pkg_list, _ = get_pkg_list(bom_file)
+        if not pkg_list and not args.bom_dir:
+            LOG.info(
+                "No packages were found in the project. Try generating the BOM manually or use the `CdxgenImageBasedGenerator` engine."
+            )
             continue
-        scoped_pkgs = utils.get_pkgs_by_scope(pkg_list)
+        # Depending on the SBOM tool used, there may be details about component usage and scopes. Let’s analyze and interpret that information.
+        scoped_pkgs = get_pkgs_by_scope(pkg_list)
+        # Is the user interested in seeing license risks? Handle that first before any security-related analysis.
         if (
             os.getenv("FETCH_LICENSE", "") in (True, "1", "true")
             or "license" in args.profile
@@ -902,50 +789,51 @@ def main():
                 pkg_list=pkg_list,
             )
             license_report_file = os.path.join(
-                reports_dir, "license-" + project_type + ".json"
+                reports_dir, f"license-{project_type}.json"
             )
-            analyse_licenses(
+            ltable = licenses_risk_table(
                 project_type, licenses_results, license_report_file
             )
-        if project_type in risk_audit_map:
-            if perform_risk_audit:
-                if len(pkg_list) > 1:
-                    console.print(
-                        Panel(
-                            f"Performing OSS Risk Audit for packages from "
-                            f"{src_dir}\nNo of packages [bold]{len(pkg_list)}"
-                            f"[/bold]. This will take a while ...",
-                            title="OSS Risk Audit",
-                            expand=False,
-                        )
-                    )
-                try:
-                    risk_results = risk_audit(
-                        project_type,
-                        scoped_pkgs,
-                        args.private_ns,
-                        pkg_list,
-                    )
-                    analyse_pkg_risks(
-                        project_type,
-                        scoped_pkgs,
-                        risk_results,
-                        risk_report_file,
-                    )
-                except Exception as e:
-                    LOG.error(e)
-                    LOG.error("Risk audit was not successful")
-            else:
+            if ltable and not args.no_vuln_table:
+                console.print(ltable)
+        # Do we support OSS risk audit for this type? If yes, proceed with the relevant checks.
+        if perform_risk_audit and project_type in risk_audit_map:
+            if len(pkg_list) > 1:
                 console.print(
                     Panel(
-                        "Depscan supports OSS Risk audit for this "
-                        "project.\nTo enable set the environment variable ["
-                        "bold]ENABLE_OSS_RISK=true[/bold]",
-                        title="Risk Audit Capability",
+                        f"Performing OSS Risk Audit for packages from "
+                        f"{src_dir}\nNo of packages [bold]{len(pkg_list)}"
+                        f"[/bold]. This will take a while ...",
+                        title="OSS Risk Audit",
                         expand=False,
                     )
                 )
-        if project_type in type_audit_map:
+            try:
+                risk_results = risk_audit(
+                    project_type,
+                    scoped_pkgs,
+                    args.private_ns,
+                    pkg_list,
+                )
+                rtable, report_data = pkg_risks_table(
+                    project_type,
+                    scoped_pkgs,
+                    risk_results,
+                    pkg_max_risk_score=pkg_max_risk_score,
+                    risk_report_file=risk_report_file,
+                )
+                if not args.no_vuln_table and report_data and rtable:
+                    console.print(rtable)
+            except Exception as e:
+                LOG.error(e)
+                LOG.error("Risk audit was not successful")
+        # Do we support remote audit for this type?
+        # Remote audits can improve results for some project types like npm by fetching vulnerabilities that might not yet be in our database.
+        # In v6, remote audit is disabled by default and gets enabled with risk audit
+        #
+        # NOTE: Enabling risk audit may lead to some precision loss in reachability results.
+        #   This is a known limitation with no immediate plan for resolution.
+        if perform_risk_audit and project_type in type_audit_map:
             LOG.debug(
                 "Performing remote audit for %s of type %s",
                 src_dir,
@@ -955,9 +843,7 @@ def main():
             try:
                 audit_results = audit(project_type, pkg_list)
                 if audit_results:
-                    LOG.debug(
-                        "Remote audit yielded %d results", len(audit_results)
-                    )
+                    LOG.debug("Remote audit yielded %d results", len(audit_results))
                     results = results + audit_results
             except Exception as e:
                 LOG.error("Remote audit was not successful")
@@ -965,7 +851,7 @@ def main():
                 results = []
         # In case of docker, bom, or universal type, check if there are any
         # npm packages that can be audited remotely
-        if project_type in (
+        if perform_risk_audit and project_type in (
             "podman",
             "docker",
             "oci",
@@ -987,129 +873,135 @@ def main():
                 except Exception as e:
                     LOG.error("Remote audit was not successful")
                     LOG.error(e)
-        if not db_lib.index_count(db["index_file"]):
-            run_cacher = True
         else:
-            LOG.debug(
-                "Vulnerability database loaded from %s", config.vdb_bin_file
-            )
-
-        sources_list = [OSVSource(), NvdSource()]
-        github_token = os.environ.get("GITHUB_TOKEN")
-        if github_token and os.getenv("CI"):
-            try:
-                github_client = github.GitHub(github_token)
-
-                if not github_client.can_authenticate():
-                    LOG.info(
-                        "The GitHub personal access token supplied appears to be invalid or expired. Please see: https://github.com/owasp-dep-scan/dep-scan#github-security-advisory"
-                    )
-                else:
-                    sources_list.insert(0, GitHubSource())
-                    scopes = github_client.get_token_scopes()
-                    if scopes:
-                        LOG.warning(
-                            "The GitHub personal access token was granted more permissions than is necessary for depscan to operate, including the scopes of: %s. It is recommended to use a dedicated token with only the minimum scope necesary for depscan to operate. Please see: https://github.com/owasp-dep-scan/dep-scan#github-security-advisory",
-                            ", ".join(scopes),
-                        )
-            except Exception:
-                pass
-        if run_cacher:
-            paths_list = download_image()
-            LOG.debug("VDB data is stored at: %s", paths_list)
-            run_cacher = False
-            db = db_lib.get()
-        elif args.sync:
-            for s in sources_list:
-                LOG.debug("Syncing %s", s.__class__.__name__)
-                try:
-                    s.download_recent()
-                except NotImplementedError:
-                    pass
-                run_cacher = False
+            LOG.debug("Vulnerability database loaded from %s", config.VDB_BIN_FILE)
         if len(pkg_list) > 1:
-            LOG.info(
-                "Performing regular scan for %s using plugin %s",
-                src_dir,
-                project_type,
-            )
-        vdb_results, pkg_aliases, sug_version_dict, purl_aliases = scan(
-            db, project_type, pkg_list, args.suggest
-        )
-        if vdb_results:
-            results += vdb_results
-        results = [r.to_dict() for r in results]
-        direct_purls, reached_purls = find_purl_usages(
-            bom_file, src_dir, args.reachables_slices_file
+            if project_type == "bom":
+                LOG.info("Scanning CycloneDX xBOMs and atom slices")
+            elif args.bom:
+                LOG.info(
+                    "Scanning %s with type %s",
+                    args.bom,
+                    project_type,
+                )
+            else:
+                LOG.info(
+                    "Scanning %s with type %s",
+                    src_dir,
+                    project_type,
+                )
+        # We could be dealing with multiple bom files
+        bom_files = (
+            get_all_bom_files(args.bom_dir)
+            if args.bom_dir
+            else [bom_file]
+            if bom_file
+            else []
         )
-        # Summarise and print results
-        summary, vdr_file, pkg_vulnerabilities, pkg_group_rows = summarise(
+        if not pkg_list and not bom_files:
+            LOG.debug("Empty package search attempted!")
+        elif bom_files:
+            LOG.debug("Scanning %d bom files for issues", len(bom_files))
+        else:
+            LOG.debug("Scanning %d oss dependencies for issues", len(pkg_list))
+        # There are many ways to perform reachability analysis.
+        # Most tools—including commercial ones—rely on a vulnerability database with affected modules (sinks) to detect reachable flows.
+        # This has several downsides:
+        # 1. These databases are often incomplete and manually maintained.
+        # 2. If a CVE or ADP enhancement isn’t available yet, reachability won’t be detected.
+        #
+        # In contrast, depscan computes reachable flows (via atom) without relying on vulnerability data upfront.
+        # It then identifies a smaller subset of those flows that are actually vulnerable.
+        # From there, we can further narrow it down to flows that are Endpoint-Reachable, Exploitable, Container-Escapable, etc.
+        reachability_analyzer = depscan_options.get("reachability_analyzer")
+        reachability_options = None
+        if (
+            reachability_analyzer and reachability_analyzer != "off"
+        ) or depscan_options.get("profile") != "generic":
+            reachability_options = ReachabilityAnalysisKV(
+                project_types=[project_type],
+                src_dir=src_dir,
+                bom_dir=args.bom_dir or reports_dir,
+                require_multi_usage=depscan_options.get("require_multi_usage", False),
+                source_tags=depscan_options.get("source_tags"),
+                sink_tags=depscan_options.get("sink_tags"),
+            )
+        # Let’s proceed with the VDR analysis.
+        summary, vdr_file, vdr_result = vdr_analyze_summarize(
             project_type,
             results,
-            pkg_aliases,
-            purl_aliases,
-            sug_version_dict,
+            suggest_mode=args.suggest,
             scoped_pkgs=scoped_pkgs,
-            report_file=report_file,
-            bom_file=bom_file,
+            bom_file=bom_files[0] if len(bom_files) == 1 else None,
+            bom_dir=args.bom_dir,
+            pkg_list=pkg_list,
+            reachability_analyzer=reachability_analyzer,
+            reachability_options=reachability_options,
             no_vuln_table=args.no_vuln_table,
-            direct_purls=direct_purls,
-            reached_purls=reached_purls,
+            fuzzy_search=depscan_options.get("fuzzy_search", False),
+            search_order=depscan_options.get("search_order"),
         )
+        if vdr_result.pkg_vulnerabilities:
+            all_pkg_vulnerabilities += vdr_result.pkg_vulnerabilities
+        if vdr_result.prioritized_pkg_vuln_trees:
+            all_pkg_group_rows.update(vdr_result.prioritized_pkg_vuln_trees)
         # Explain the results
         if args.explain:
             explainer.explain(
                 project_type,
                 src_dir,
-                args.reachables_slices_file,
+                args.bom_dir or reports_dir,
                 vdr_file,
-                pkg_vulnerabilities,
-                pkg_group_rows,
-                direct_purls,
-                reached_purls,
+                vdr_result,
+                args.explanation_mode,
+            )
+        else:
+            LOG.debug(
+                "Pass the `--explain` argument to get a detailed explanation of the analysis."
             )
         # CSAF VEX export
         if args.csaf:
             export_csaf(
-                pkg_vulnerabilities,
+                vdr_result,
                 src_dir,
                 reports_dir,
-                bom_file,
+                vdr_file,
             )
+    console.record = True
+    # Export the console output
     console.save_html(
-        html_file,
-        theme=(
-            MONOKAI if os.getenv("USE_DARK_THEME") else DEFAULT_TERMINAL_THEME
-        ),
+        html_report_file,
+        clear=False,
+        theme=(MONOKAI if os.getenv("USE_DARK_THEME") else DEFAULT_TERMINAL_THEME),
     )
-    utils.export_pdf(html_file, pdf_file)
+    console.save_text(txt_report_file, clear=False)
+    utils.export_pdf(html_report_file, pdf_report_file)
+    # This logic needs refactoring
     # render report into template if wished
     if args.report_template and os.path.isfile(args.report_template):
         utils.render_template_report(
             vdr_file=vdr_file,
             bom_file=bom_file,
-            pkg_vulnerabilities=pkg_vulnerabilities,
-            pkg_group_rows=pkg_group_rows,
+            pkg_vulnerabilities=all_pkg_vulnerabilities,
+            pkg_group_rows=all_pkg_group_rows,
             summary=summary,
             template_file=args.report_template,
             result_file=os.path.join(reports_dir, args.report_name),
+            depscan_options=depscan_options,
         )
     elif args.report_template:
         LOG.warning(
             "Template file %s doesn't exist, custom report not created.",
             args.report_template,
         )
-    # Submit vdr/vex files to threatdb server
-    if args.threatdb_server and (args.threatdb_username or args.threatdb_token):
-        submit_bom(
-            reports_dir,
-            {
-                "threatdb_server": args.threatdb_server,
-                "threatdb_username": args.threatdb_username,
-                "threatdb_password": args.threatdb_password,
-                "threatdb_token": args.threatdb_token,
-            },
-        )
+    # Should we include the generated text report as an annotation in the VDR file?
+    if args.explain or args.annotate:
+        annotate_vdr(vdr_file, txt_report_file)
+
+
+def main():
+    cli_args = build_args()
+    run_depscan(cli_args)
 
 
 if __name__ == "__main__":