Customizable explanation modes

.github/workflows/repotests.yml

@@ -115,6 +115,14 @@ jobs:
           uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/Signal-Android --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/Signal-Android --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/Signal-Android --reachability-analyzer SemanticReachability --explain
           rm -rf ${GITHUB_WORKSPACE}/depscan_reports
         shell: bash
+      - name: repotests dependency-track
+        run: |
+          mkdir -p ${GITHUB_WORKSPACE}/depscan_reports/dependency-track
+          uv run huggingface-cli download AppThreat/ukaina --include "java/dependency-track/*.json" --exclude "java/dependency-track/*.vdr.json" --repo-type dataset --local-dir ${GITHUB_WORKSPACE}/depscan_reports/dependency-track
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --reachability-analyzer SemanticReachability --explain
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/dependency-track --reachability-analyzer SemanticReachability --explain --explanation-mode NonReachables
+          rm -rf ${GITHUB_WORKSPACE}/depscan_reports
+        shell: bash
       - name: repotests kafka-4.0.0-src
         run: |
           mkdir -p ${GITHUB_WORKSPACE}/depscan_reports/kafka-4.0.0-src
@@ -155,13 +163,16 @@ jobs:
           mkdir -p ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo
           uv run huggingface-cli download AppThreat/ukaina --include "python/django-DefectDojo/*.json" --exclude "python/django-DefectDojo/*.vdr.json" --repo-type dataset --local-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo
           uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reachability-analyzer SemanticReachability --explain
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reachability-analyzer SemanticReachability --explain --explanation-mode Endpoints
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/django-DefectDojo --reachability-analyzer SemanticReachability --explain --explanation-mode NonReachables
           rm -rf ${GITHUB_WORKSPACE}/depscan_reports
         shell: bash
       - name: repotests depscan
         run: |
           mkdir -p ${GITHUB_WORKSPACE}/depscan_reports/depscan
           uv run huggingface-cli download AppThreat/ukaina --include "python/depscan/*.json" --exclude "python/depscan/*.vdr.json" --repo-type dataset --local-dir ${GITHUB_WORKSPACE}/depscan_reports/depscan
           uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/depscan --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/depscan --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/depscan --reachability-analyzer SemanticReachability --explain
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/depscan --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/depscan --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/depscan --reachability-analyzer SemanticReachability --explain --explanation-mode Endpoints
           rm -rf ${GITHUB_WORKSPACE}/depscan_reports
         shell: bash
       - name: repotests phpmyadmin
@@ -189,7 +200,7 @@ jobs:
         run: |
           mkdir -p ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0
           uv run huggingface-cli download AppThreat/ukaina --include "c/curl-8.13.0/*.json" --exclude "c/curl-8.13.0/*.vdr.json" --repo-type dataset --local-dir ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0
-          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --reachability-analyzer SemanticReachability --explain
+          uv run depscan --src ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --bom-dir ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --reports-dir ${GITHUB_WORKSPACE}/depscan_reports/curl-8.13.0 --reachability-analyzer SemanticReachability --explain --explanation-mode NonReachables
           rm -rf ${GITHUB_WORKSPACE}/depscan_reports
         shell: bash
       - name: Set up JDK

README.md

@@ -16,6 +16,7 @@ OWASP dep-scan is a next-generation security and risk audit tool based on known
     - [Scanning containers locally (Python version)](#scanning-containers-locally-python-version)
     - [Scanning projects locally (Docker container)](#scanning-projects-locally-docker-container)
     - [Server mode](#server-mode)
+- [depscanGPT](https://chatgpt.com/g/g-674f260c887c819194e465d2c65f4061-owasp-dep-scan)
 - [Documentation (depscan.readthedocs.io)](https://depscan.readthedocs.io)
     - [Supported languages and package format](https://depscan.readthedocs.io/supported-languages)
     - [Reachability analysis](https://depscan.readthedocs.io/reachability-analysis)
@@ -43,11 +44,29 @@ OWASP dep-scan is a next-generation security and risk audit tool based on known
 - Generate a Common Security Advisory Framework (CSAF) 2.0 VEX document (check out the [CSAF Readme](contrib/CSAF_README.md))
 - Perform deep packages risk audit for dependency confusion attacks and maintenance risks (See risk audit)
 
+### Precise Reachable data-flows
+
+Detailed data flows to identify both reachable and non-reachable paths in your application based on the full context.
+
 ![Reachable Flows](documentation/static/img/depscan-flows.png)
 
-![Dependency Tree with Insights](documentation/static/img/tree1.jpg)
+### Clear insights about CVEs
+
+Understand CVEs clearly without having to read through the description.
+
+![Dependency Tree with Insights](documentation/static/img/tree1.png)
+
+### Automatic prioritization
+
+Only focus on CVEs that need your attention.
+
+![Prioritization](documentation/static/img/prioritization.png)
+
+### Stay proactive
+
+Always stay a step ahead with advanced vulnerability and exploit prediction.
 
-![Dependency Tree with Insights](documentation/static/img/prioritization.jpg)
+![Proactive Measures](documentation/static/img/proactive.png)
 
 ### Vulnerability Data sources
 
@@ -166,6 +185,9 @@ options:
   --debug               Run depscan in debug mode.
   -q, --quiet           Makes depscan quiet.
   --explain             Makes depscan to explain the various analysis. Useful for creating detailed reports.
+  --explanation-mode {Endpoints,EndpointsAndReachables,NonReachables}
+                        Style of explanation needed. Defaults to Endpoints and Reachables.
+  --annotate            Include the generated text VDR report as an annotation. Defaults to true when explain is enabled; false otherwise.
   -v, --version         Display the version
 ```
 

contrib/depscanGPT/README.md

@@ -46,11 +46,12 @@ For anything else, respond: “I’m sorry, but I can only help with BOM and VDR
 - Accept CycloneDX VDR JSON alongside the HTML/TXT when both are supplied.
 - If key details (e.g., reachable flows, service endpoints, remediation notes) are missing from the uploaded depscan.html or depscan.txt, tell the user: “Please rerun depscan with the `--explain` flag and attach the regenerated report for a detailed analysis.”
 
-**How to analyse the report (HTML or TXT)**
-	1.	Locate the “Dependency Scan Results (BOM)” table → extract package, CVE, severity, score and fix version.
-	2.	Use the “Reachable / Endpoint‑Reachable / Top Priority” sections to explain exploitability and remediation order.
-	3.	Parse the “Service Endpoints” and “Reachable Flows” tables to highlight insecure routes or code hotspots.
-	4.	Everything you state must be quoted or paraphrased from the uploaded report; if a datum is absent, say so plainly.
+**How to analyse the report (JSON, HTML or TXT)**
+    1.  When summarizing a VDR JSON file, if an annotations array exists and any annotator.name is "owasp-depscan", prefer the text field as the primary summary. Choose the latest timestamped annotation if multiple exist.
+	2.	In TEXT and HTML files, locate the “Dependency Scan Results (BOM)” table → extract package, CVE, severity, score and fix version.
+	    1.	Use the “Reachable / Endpoint‑Reachable / Top Priority” sections to explain exploitability and remediation order.
+	    2.	Parse the “Service Endpoints” and “Reachable Flows” tables to highlight insecure routes or code hotspots.
+	    3.	Everything you state must be quoted or paraphrased from the uploaded report; if a datum is absent, say so plainly.
 
 **Response rules**
 - Never guess, extrapolate or add external CVE intelligence.
@@ -68,7 +69,7 @@ For anything else, respond: “I’m sorry, but I can only help with BOM and VDR
 
 ## Feedback nudge
 
-When a user expresses satisfaction, once per session invite them to review cdxgenGPT on social media or donate to CycloneDX.
+When a user expresses satisfaction, once per session invite them to review depscanGPT on social media or donate to the OWASP Foundation.
 
 ## Optional ASCII logo
 

depscan/cli.py

@@ -36,6 +36,7 @@
 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,
@@ -51,7 +52,7 @@
     vdb_database_url,
 )
 from depscan.lib.license import build_license_data, bulk_lookup
-from depscan.lib.logger import DEBUG, LOG, SPINNER, console
+from depscan.lib.logger import DEBUG, LOG, SPINNER, console, IS_CI
 
 if sys.platform == "win32" and os.environ.get("PYTHONIOENCODING") is None:
     sys.stdin.reconfigure(encoding="utf-8")
@@ -169,13 +170,14 @@ def vdr_analyze_summarize(
         vdr_file = os.path.join(bom_dir, DEPSCAN_DEFAULT_VDR_FILE)
     if vdr_result.success:
         pkg_vulnerabilities = vdr_result.pkg_vulnerabilities
-        if pkg_vulnerabilities:
+        # 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:
                 if bom_data := json_load(bom_file, log=LOG):
                     export_bom(bom_data, ds_version, pkg_vulnerabilities, vdr_file)
             # Case 2: Multiple BOM files in a bom directory
-            if bom_dir:
+            elif bom_dir:
                 bom_data = create_empty_vdr(pkg_list, ds_version)
                 export_bom(bom_data, ds_version, pkg_vulnerabilities, vdr_file)
                 LOG.debug(f"The VDR file '{vdr_file}' was created successfully.")
@@ -570,7 +572,9 @@ def run_depscan(args):
             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)
@@ -932,6 +936,7 @@ def run_depscan(args):
                 src_dir,
                 args.bom_dir or reports_dir,
                 vdr_result,
+                args.explanation_mode,
             )
         else:
             LOG.debug(
@@ -972,6 +977,9 @@ def run_depscan(args):
             "Template file %s doesn't exist, custom report not created.",
             args.report_template,
         )
+    # 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():

depscan/cli_options.py

@@ -274,6 +274,24 @@ def build_parser():
         dest="explain",
         help="Makes depscan to explain the various analysis. Useful for creating detailed reports.",
     )
+    parser.add_argument(
+        "--explanation-mode",
+        choices=(
+            "Endpoints",
+            "EndpointsAndReachables",
+            "NonReachables",
+        ),
+        default="EndpointsAndReachables",
+        dest="explanation_mode",
+        help="Style of explanation needed. Defaults to Endpoints and Reachables.",
+    )
+    parser.add_argument(
+        "--annotate",
+        action="store_true",
+        default=False,
+        dest="annotate",
+        help="Include the generated text VDR report as an annotation. Defaults to true when explain is enabled; false otherwise.",
+    )
     parser.add_argument(
         "-v",
         "--version",

depscan/lib/bom.py

@@ -522,3 +522,33 @@ def trim_vdr_bom_data(bom_data):
         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}",
+    )

depscan/lib/config.py

@@ -311,3 +311,12 @@ def get_int_from_env(name, default):
 DEPSCAN_DEFAULT_VDR_FILE = os.getenv(
     "DEPSCAN_DEFAULT_VDR_FILE", "depscan-universal.vdr.json"
 )
+
+COMMON_CHECK_TAGS = (
+    "validation",
+    "encode",
+    "encrypt",
+    "sanitize",
+    "authentication",
+    "authorization",
+)