Usage

dep-scan is ideal for use during continuous integration (CI) and as a local development tool.

Scanning projects locally (Python version)

sudo npm install -g @cyclonedx/cdxgen
# Normal version recommended for most users (MIT)
pip install owasp-depscan

# For a performant version, that uses valkey cache during risk audit (BSD-3-Clause)
pip install owasp-depscan[perf]

This would install two commands called cdxgen and depscan.

You can invoke the scan command directly with the various options.

cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

The full list of options is below:

usage: depscan [-h] [--config CONFIG] [--no-banner] [-i SRC_DIR_IMAGE] [-o REPORTS_DIR] [--csaf]
               [--profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}]
               [--lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]]
               [--technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...]]
               [--bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} |
               --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}] [--reachability-analyzer {off,FrameworkReachability,SemanticReachability}] [--no-suggest]
               [--risk-audit] [--cdxgen-args CDXGEN_ARGS] [--private-ns PRIVATE_NS] [-t PROJECT_TYPE [PROJECT_TYPE ...]] [--bom BOM | --bom-dir BOM_DIR | --purl SEARCH_PURL]
               [--report-template REPORT_TEMPLATE] [--report-name REPORT_NAME] [--deep] [--fuzzy-search] [--search-order {purl,pcu,cpe,cpu,url}] [--no-universal]
               [--no-vuln-table] [--server] [--server-host SERVER_HOST] [--server-port SERVER_PORT] [--cdxgen-server CDXGEN_SERVER] [--debug] [-q | --explain] [-v]

Fully open-source security and license audit for application dependencies and container images based on known vulnerabilities and advisories.

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to the configuration file. Default: $PWD/.config/depscan.toml
  --no-banner           Do not display the logo and donation banner. Please make a donation to OWASP before using this argument.
  -i, --src SRC_DIR_IMAGE
                        Source directory or container image or binary file
  -o, --reports-dir REPORTS_DIR
                        Reports directory
  --csaf                Generate a OASIS CSAF VEX document
  --profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}
                        Profile to use while generating the BOM. For granular control, use the arguments --bom-engine, --vulnerability-analyzer, or --reachability-analyzer.
  --lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]
                        Product lifecycle for the generated BOM. Multiple values allowed.
  --technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...]
                        Analysis technique to use for BOM generation. Multiple values allowed.
  --bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator}
                        BOM generation engine to use. Defaults to automatic selection based on project type and lifecycle.
  --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}
                        Vulnerability analyzer to use. Defaults to automatic selection based on bom_dir argument.
  --reachability-analyzer {off,FrameworkReachability,SemanticReachability}
                        Reachability analyzer to use. Default FrameworkReachability.
  --no-suggest          Disable suggest mode
  --risk-audit          Perform package risk audit (slow operation). Npm only.
  --cdxgen-args CDXGEN_ARGS
                        Additional arguments to pass to cdxgen
  --private-ns PRIVATE_NS
                        Private namespace to use while performing oss risk audit. Private packages should not be available in public registries by default. Comma separated
                        values accepted.
  -t, --type PROJECT_TYPE [PROJECT_TYPE ...]
                        Override project types if auto-detection is incorrect. Multiple values supported.
  --bom BOM             Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one.
  --bom-dir BOM_DIR     Examine all the Bill-of-Materials (BOM) files in the given directory.
  --purl SEARCH_PURL    Scan a single package url.
  --custom-data CUSTOM_DATA
                        Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results.
  --report-template REPORT_TEMPLATE
                        Jinja template file used for rendering a custom report
  --report-name REPORT_NAME
                        Filename of the custom report written to the --reports-dir
  --deep                Perform deep scan by passing this --deep argument to cdxgen. Useful while scanning docker images and OS packages.
  --fuzzy-search        Perform fuzzy search by creating variations of package names. Use this when the input SBOM lacks a PURL.
  --search-order {purl,pcu,cpe,cpu,url}
                        Attributes to use while searching for vulnerabilities. Default: PURL, CPE, URL (pcu).
  --no-universal        Depscan would attempt to perform a single universal scan instead of individual scans per language type.
  --no-vuln-table       Do not print the table with the full list of vulnerabilities. This can help reduce console output.
  --server              Run depscan as a server
  --server-host SERVER_HOST
                        depscan server host
  --server-port SERVER_PORT
                        depscan server port
  --server-allowed-hosts [SERVER_ALLOWED_HOSTS ...]
                        List of allowed hostnames or IPs that can access the server (e.g., 'localhost 192.168.1.10'). If unspecified, no host allowlist is
                        enforced.
  --server-allowed-paths [SERVER_ALLOWED_PATHS ...]
                        List of allowed filesystem paths that can be scanned by the server. Restricts `path` parameter in /scan requests.
  --cdxgen-server CDXGEN_SERVER
                        cdxgen server url. Eg: http://cdxgen:9090
  --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,LLMPrompts}
                        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

[!IMPORTANT] Binding dep-scan to a non-local address is authenticated by default as of 6.2.0. Set DEPSCAN_SERVER_API_KEY before using --server-host 0.0.0.0, or explicitly opt out with DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true only for trusted development environments.

Scanning containers locally (Python version)

Scan a Java project.

depscan --src <path> -o containertests -t java

Scan latest tag of the container shiftleft/scan-slim

depscan --src shiftleft/scan-slim -o containertests -t docker

Include license to the type to perform the license audit.

depscan --src shiftleft/scan-slim -o containertests -t docker,license

You can also specify the image using the sha256 digest

depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

You can also save container images using docker or podman save command and pass the archive to depscan for scanning.

docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
# podman save --format oci-archive -o /tmp/scanslim.tar shiftleft/scan-slim:latest
depscan --src /tmp/scanslim.tar -o reports -t docker

Refer to the docker tests under the GitHub action workflow for this repo for more examples.

Scanning projects locally (Docker container)

ghcr.io/owasp-dep-scan/dep-scan container image can be used to perform the scan.

To scan with default settings

docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

To scan with custom environment variables based configuration

docker run --rm \
    -e VDB_HOME=/db \
    -e GITHUB_TOKEN=<token> \
    -v /tmp:/db \
    -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

In the above example, /tmp is mounted as /db into the container. This directory is then specified as VDB_HOME for caching the vulnerability information. This way the database can be cached and reused to improve performance.

Specify the BOM engine (Python version)

depscan allows you to customize the BOM generator engine. The supported values are: auto, CdxgenGenerator, CdxgenServerGenerator, CdxgenImageBasedGenerator, and BlintGenerator.

• auto: Uses the container-image-based cdxgen generator (CdxgenImageBasedGenerator) if the Docker command is available and the project type specified is not an oci image type (such as docker, podman, and oci). Otherwise, it uses the local cdxgen CLI via CdxgenGenerator or the local cdxgen server CdxgenServerGenerator if you pass the --cdxgen-server argument.
• CdxgenGenerator: Always uses the local cdxgen CLI. Install cdxgen using the npm command or download the standalone executable.
• CdxgenServerGenerator: Uses the cdxgen server. Specify the URL using the --cdxgen-server argument.
• CdxgenImageBasedGenerator: Generates a BOM using the official cdxgen container images. You can customize the image name using CDXGEN_IMAGE_{project_type} and CDXGEN_IMAGE_VERSION. Container image–based generation is more suitable for enterprise applications that require specific build tools and OS libraries for successful BOM generation. This approach is resource-intensive but typically has a higher success rate.
• BlintGenerator: Uses the optional OWASP blint library. This requires installing depscan with all optional packages:

  pip install owasp-depscan[all]

Customize cdxgen container image

Container images used by CdxgenImageBasedGenerator can be customized using environment variables prefixed with CDXGENIMAGE. For example, to use a custom cdxgen image for Java, set the environment variable CDXGEN_IMAGE_JAVA.

Specify the Vulnerability Analyzer

depscan supports customizing the vulnerability analyzer engine. The supported values are: auto, VDRAnalyzer, and LifecycleAnalyzer.

• auto: Uses LifecycleAnalyzer when invoked with a valid --bom-dir containing multiple xBOMs; otherwise, it defaults to VDRAnalyzer.
• VDRAnalyzer: Mimics the analysis performed by depscan v5 by focusing on a single xBOM and a single BOM lifecycle phase.
• LifecycleAnalyzer: Optimized for analyzing multiple phases of a BOM lifecycle—such as pre-build, build, post-build, and operations—to support better prioritization.

The LifecycleAnalyzer works by repeatedly invoking cdxgen (for pre-build, build, and container phases) and blint (for post-build) to generate multiple SBOMs. With this rich context, depscan can suppress more false positives and more accurately identify high-priority CVEs. Use the environment variable DEPSCAN_SOURCE_IMAGE to specify the image for container SBOM generation.

Configuration File support

You can pass CLI options to depscan using a configuration file with the --config argument. By default, depscan looks for .config/depscan.toml in the current directory. A sample file named depscan.toml.sample is also generated in the reports directory (Specified via --reports-dir). Customize this file as needed and copy it to the .config directory to run depscan without specifying arguments each time.