Skip to content
Back to search

dep-scan

SkillWorks with Claude CodeGitHub

OWASP dep-scan is a next-generation security and risk audit tool based on known vulnerabilities, advisories, and license limitations for project dependencies. Both local repositories and container images are supported as the input, and the tool is ideal for integration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/owasp-dep-scan/dep-scan with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/owasp-dep-scan/dep-scan'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/appthreat--dep-scan/badge.svg)](/listings/appthreat--dep-scan)

HTML

<a href="/listings/appthreat--dep-scan"><img src="/api/listings/appthreat--dep-scan/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 full version with all extensions and server mode (Multiple Licenses)
pip install owasp-depscan[all]

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}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # SKILL.md
  2. This document describes the skill profile an AI agent should use when reviewing or modifying `dep-scan`.
  3. ## Core mindset
  4. Work like a careful security engineer who also understands packaging, automation, and developer ergonomics.
  5. The repository rewards agents that can switch between several modes of thinking:
  6. - Python application review
  7. - server-side input validation review
  8. - subprocess and toolchain safety review
  9. - supply chain and release engineering review
  10. - documentation quality review
  11. A weak agent treats this repository as a simple CLI. A strong agent recognizes that `dep-scan` is a security product whose workflows, containers, and default guidance matter as much as its Python code.
  12. ## What strong repository knowledge looks like
  13. A skilled agent knows that `dep-scan` operates across several layers.
  14. At the top level, `depscan/cli.py` orchestrates scans, report generation, and server startup.
  15. BOM generation is delegated to code in `depscan/lib/bom.py` and `packages/xbom-lib/src/xbom_lib/cdxgen.py`. That means scan behavior is shaped by local tools, HTTP calls to cdxgen server mode, and container-image based execution.
  16. Analysis and explanation logic lives in the Python workspace packages, especially `analysis-lib`, `reporting-lib`, and the reachability and explanation code.
  17. Server mode lives in `packages/server-lib/src/server_lib/simple.py`, which is a separate attack surface with request parsing, file uploads, path handling, URL validation, and optional authentication.
  18. The release and assurance story lives in `.github/workflows/`, Dockerfiles, and packaging metadata. That is not background noise. It is production code with authority.
  19. ## Skills an agent should actively apply
  20. ### 1. Trace external influence
  21. For every change, identify where outside data enters the system. Typical examples are:
  22. - CLI flags
  23. - environment variables
  24. - uploaded files
  25. - local paths
  26. - remote Git URLs
  27. - package URLs
  28. - registry responses
  29. - GitHub API responses
  30. - workflow inputs, artifacts, and downloaded binaries
  31. The agent should follow those values forward until they hit one of these sinks:
  32. - filesystem reads or writes
  33. - subprocess execution
  34. - network requests
  35. - template rendering
  36. - log output
  37. - generated artifacts and release assets
  38. ### 2. Understand trust boundaries
  39. This repository has multiple trust zones.
  40. A local CLI scan is usually user-driven and trusted by the operator, but it can still point at untrusted source trees or archives.
  41. Server mode is much more sensitive because the caller may be remote.
  42. CI on pull requests usually runs untrusted proposed code with limited repository authority.
  43. Release workflows run on trusted branches or tags and have package and contents write access.
  44. A strong agent changes behavior with those trust zones in mind.
  45. ### 3. Review subprocess construction carefully
  46. `dep-scan` delegates important work to other tools. Reviewers should look for:
  47. - argument list construction
  48. - use of `shell=True` or platform-specific shell execution
  49. - user-controlled arguments being passed through unchecked
  50. - environment variables that change tool behavior
  51. - networked backends where a local-only assumption no longer holds
  52. The right question is not just "does this command run?" but "who gets to shape what this command does?"
  53. ### 4. Read workflows as attack surface
  54. A capable agent should be comfortable reviewing GitHub Actions with the same depth used for Python code.
  55. That means checking:
  56. - event triggers
  57. - permissions blocks
  58. - use of secrets and trusted publishing
  59. - action pinning by commit SHA
  60. - direct downloads with `curl`
  61. - checksums, signatures, or pinned digests
  62. - artifact upload and download chains
  63. - external repository checkouts
  64. - self-hosted runner exposure
  65. In this repository, workflows test real sample repos, download datasets, fetch binaries, build containers, and publish artifacts. That deserves first-class review attention.
  66. ### 5. Understand output sensitivity
  67. Some outputs are more sensitive than they look.
  68. Reachability reports, endpoint summaries, and prompt-oriented explanation outputs can expose:
  69. - internal endpoint names
  70. - code hotspots
  71. - file paths
  72. - dependency names and versions
  73. - potentially sensitive operational details
  74. A strong agent evaluates whether a change increases accidental disclosure in logs, artifacts, or published outputs.
  75. ## Review heuristics by subsystem
  76. ### CLI and analysis flow
  77. When reviewing `depscan/cli.py` and related logic, check whether a new argument changes:
  78. - which files are read
  79. - which network calls happen
  80. - which report files are written
  81. - which analyzers are selected automatically
  82. - whether behavior differs between local use and CI
  83. ### Server mode
  84. When reviewing `packages/server-lib/src/server_lib/simple.py`, treat each request field as adversarial.
  85. Focus on:
  86. - authentication
  87. - authorization by host and path
  88. - SSRF resistance
  89. - body size limits
  90. - file type validation
  91. - temporary file lifecycle
  92. - error behavior
  93. - safe defaults for network exposure
  94. ### BOM generation
  95. When reviewing `depscan/lib/bom.py` and `packages/xbom-lib/src/xbom_lib/cdxgen.py`, check:
  96. - fallback behavior between local CLI, container image, and cdxgen server
  97. - execution with untrusted source directories
  98. - how optional `cdxgen_args` or environment variables alter behavior
  99. - whether network access is implicit or explicit
  100. ### Package metadata and GitHub integrations
  101. When reviewing registry and GitHub lookups, check:
  102. - fixed vs user-controlled hosts
  103. - timeout behavior
  104. - retries and circuit breakers
  105. - error handling that changes security posture
  106. - token handling and scope interpretation
  107. ### Containers and release automation
  108. When reviewing Dockerfiles and publish workflows, check:
  109. - downloaded tool provenance
  110. - package manager trust
  111. - pinned versions
  112. - final runtime user and filesystem permissions
  113. - what exactly is being published, signed, or attached
  114. ## What a high quality agent output should include
  115. A strong review or implementation response should usually contain:
  116. A brief architecture-aware summary of the affected surface.
  117. A clear statement of the trust boundary involved.
  118. Any residual risk or assumption that remains after the change.
  119. Evidence of validation. This usually means targeted tests, lint, or workflow reasoning grounded in the current files.
  120. If the change affects operator behavior, the response should also mention the corresponding docs that were updated or should be updated.
  121. ## Common mistakes to avoid
  122. Do not focus only on syntax and unit tests.
  123. Do not miss workflow privilege changes because they live outside Python.
  124. Do not assume that validation in the CLI automatically protects server mode.
  125. Do not overlook the security effect of changing defaults.
  126. Do not ignore release integrity just because package publishing is "ops". In this repository, it is part of the product trust model.
  127. ## Fast review playbook
  128. When time is short, use this sequence.
  129. First, identify the entrypoint and trust boundary.
  130. Second, identify user-controlled inputs.
  131. Third, identify execution sinks such as filesystem access, network access, subprocesses, and artifact publication.
  132. Fourth, check whether there is a limiting control such as allowlisting, size limits, authentication, or pinned integrity data.
  133. Fifth, check tests and docs.
  134. This simple loop catches a surprising amount of real risk in `dep-scan`.
  135. ## Relationship to other repository docs
  136. Read `AGENTS.md` for repository operating guidance.
  137. Read `THREAT_MODEL.md` for the detailed security model, attack paths, and workflow review guidance.
README.md · README · 658 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Introduction
  2. OWASP dep-scan is a next-generation security and risk audit tool based on known vulnerabilities, advisories, and license limitations for project dependencies. Both local repositories and container images are supported as the input, and the tool is ideal for integration with ASPM/VM platforms and in CI environments.
  3. <img src="depscan-logo.png" width="200" height="auto" />
  4. [![SBOM](https://img.shields.io/badge/SBOM-with_%E2%9D%A4%EF%B8%8F_by_cdxgen-FF753D)](https://github.com/cdxgen/cdxgen) [![release](https://github.com/owasp-dep-scan/dep-scan/actions/workflows/pythonpublish.yml/badge.svg)](https://github.com/owasp-dep-scan/dep-scan/actions/workflows/pythonpublish.yml)
  5. ## Contents
  6. - [Features](#features)
  7. - [Precise reachable data-flows](#precise-reachable-data-flows)
  8. - [Reachability matrix](#reachability-matrix)
  9. - [Rust reachability (via rusi)](#rust-reachability-via-rusi)
  10. - [Go reachability (via golem)](#go-reachability-via-golem)
  11. - [.NET reachability (via dosai)](#net-reachability-via-dosai)
  12. - [JVM, JavaScript, Python, and PHP reachability (via atom)](#jvm-javascript-python-and-php-reachability-via-atom)
  13. - [Vulnerability Data sources](#vulnerability-data-sources)
  14. - [Linux distros](#linux-distros)
  15. - [Quick Start](#quick-start)
  16. - [Scanning projects locally (Python version)](#scanning-projects-locally-python-version)
  17. - [Homebrew (macOS and Linux)](#homebrew-macos-and-linux)
  18. - [Standalone binaries (no Python or Node.js required)](#standalone-binaries-no-python-or-nodejs-required)
  19. - [Scanning containers locally (Python version)](#scanning-containers-locally-python-version)
  20. - [Scanning projects locally (Docker container)](#scanning-projects-locally-docker-container)
  21. - [Server mode](#server-mode)
  22. - [Local development](#local-development)
  23. - [Documentation (depscan.readthedocs.io)](https://depscan.readthedocs.io)
  24. - [License](#license)
  25. ## Features
  26. - Scan most application code (local repos, Linux container images, Kubernetes manifests, and OS) to identify known CVEs with prioritization
  27. - Perform advanced reachability analysis for multiple languages (see the [reachability matrix](#reachability-matrix) below)
  28. - Package vulnerability scanning is performed locally and is quite fast. No server is used
  29. - Generate Software Bill-of-Materials (SBOM) with Vulnerability Disclosure Report (VDR) information
  30. - Generate a Common Security Advisory Framework (CSAF) 2.0/2.1 VEX document (check out the [CSAF Readme](contrib/CSAF_README.md))
  31. - Perform deep packages risk audit for dependency confusion attacks and maintenance risks (see the [risk audit docs](https://depscan.readthedocs.io/adv-usage#package-risk-audit))
  32. ### Precise Reachable data-flows
  33. Detailed data flows to identify both reachable and non-reachable paths in your application based on the full context.
  34. ![Reachable Flows](documentation/static/img/depscan-flows.png)
  35. ### Reachability matrix
  36. dep-scan computes reachability for seven language ecosystems through four slicers. A vulnerable package whose code is actually on an executed path is marked **Reachable**, while a package that is merely declared in the BOM but never called is not. Every slicer feeds the same shared, purl-keyed reachability engine, so the behavior is uniform across languages. Reachability is on by default (`--reachability-analyzer FrameworkReachability`); `SemanticReachability` additionally attributes reached services, endpoints, and post-build (binary/container) reachability.
  37. | Language / ecosystem | Reachability engine | Default analyzer |
  38. | ---------------------------------- | ----------------------------------------------------- | ----------------------- |
  39. | Java / JVM (Groovy, Kotlin, Scala) | [atom](https://github.com/AppThreat/atom) | `FrameworkReachability` |
  40. | JavaScript / TypeScript | atom | `FrameworkReachability` |
  41. | Python | atom | `FrameworkReachability` |
  42. | PHP | atom | `FrameworkReachability` |
  43. | Rust | [rusi](https://github.com/cdxgen/cdxgen-plugins-bin) | `FrameworkReachability` |
  44. | Go | [golem](https://github.com/cdxgen/cdxgen-plugins-bin) | `FrameworkReachability` |
  45. | .NET (C#, VB, F#, R) | [dosai](https://github.com/owasp-dep-scan/dosai) | `FrameworkReachability` |
  46. For the concepts behind reachability and prioritization, read the [reachability model](https://depscan.readthedocs.io/concepts/reachability-model) and [prioritization](https://depscan.readthedocs.io/concepts/prioritization) chapters. For per-language worked examples, see the [Language Guides](https://depscan.readthedocs.io/languages/rust-reachability). For the compliance story (VDR and CSAF VEX), see the [VDR guide](https://depscan.readthedocs.io/output/vdr-guide) and the [CSAF VEX guide](https://depscan.readthedocs.io/output/vex-csaf-guide).
  47. Reachability is on by default: dep-scan asks cdxgen for its research BOM profile, which writes the slices the analyzers read. The commands below are enough to get started; the per-language guides cover binary resolution, backend and network safety, restore requirements, and worked examples on the in-repo fixtures.
  48. **Rust (rusi).** cdxgen runs [rusi](https://github.com/cdxgen/cdxgen-plugins-bin) and persists its report, which dep-scan converts into the shared pipeline, so a crate that is actually called (for example `time::now()` for RUSTSEC-2020-0071) is Reachable while one merely present is not. See the [Rust reachability guide](https://depscan.readthedocs.io/languages/rust-reachability).
  49. ```bash
  50. depscan scan ./my-rust-app -o ./reports --bom-profile research
  51. ```
  52. **Go (golem).** dep-scan invokes [golem](https://github.com/cdxgen/cdxgen-plugins-bin) directly for Go projects (needs `go` on `PATH`), marking a module Reachable when its functions are on a traced path. golem runs with cgo off, so packages that need cgo are not loaded and their reachability is missing; pass `--go-analyzer-cgo` for trusted input. Use `--go-analyzer-network offline` for untrusted repos with a warm module cache. See the [Go reachability guide](https://depscan.readthedocs.io/languages/go-reachability).
  53. ```bash
  54. depscan scan ./my-go-app -o ./reports -t go
  55. ```
  56. **.NET (dosai).** cdxgen runs [dosai](https://github.com/owasp-dep-scan/dosai), which emits an explicit per-package reachability verdict (`PackageReachability` with `ReachabilityKind` and `Confidence`) that dep-scan treats as authoritative, so a NuGet package actually called (for example `JsonConvert.DeserializeObject` on a controlled input) is Reachable. Scan a restored tree for versioned purls. See the [.NET reachability guide](https://depscan.readthedocs.io/languages/dotnet-reachability).
  57. ```bash
  58. depscan scan ./my-dotnet-app -o ./reports -t dotnet
  59. ```
  60. **JVM, JavaScript/TypeScript, Python, and PHP (atom).** These four ecosystems share the [atom](https://github.com/AppThreat/atom) slicer, which builds a language-agnostic intermediate representation and performs static slicing. See the [JVM, JS, Python, and PHP reachability guide](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).
  61. ```bash
  62. depscan scan ./my-java-app --bom-profile research -t java -o ./reports --explain
  63. ```
  64. To move beyond framework-forward reachability to endpoint, service, and post-build tiers, pass `--reachability-analyzer SemanticReachability` with a directory of lifecycle BOMs as the target and `--target-kind bom-dir`. See the [semantic reachability guide](https://depscan.readthedocs.io/analyzers/semantic-reachability).
  65. ### Clear insights about CVEs
  66. Understand CVEs clearly without having to read through the description.
  67. ![Dependency Tree with Insights](documentation/static/img/tree1.png)
  68. ### Automatic prioritization
  69. Only focus on CVEs that need your attention.
  70. ![Prioritization](documentation/static/img/prioritization.png)
  71. ### Stay proactive
  72. Always stay a step ahead with advanced vulnerability and exploit prediction.
  73. ![Proactive Measures](documentation/static/img/proactive.png)
  74. ### Vulnerability Data sources
  75. - OSV
  76. - NVD
  77. - GitHub
  78. - NPM
  79. - Linux [vuln-list](https://github.com/appthreat/vuln-list)
  80. ### Linux distros
  81. - AlmaLinux
  82. - Debian
  83. - Alpine
  84. - Amazon Linux
  85. - Arch Linux
  86. - RHEL/CentOS
  87. - Rocky Linux
  88. - Ubuntu
  89. - OpenSUSE/SLES
  90. - Photon
  91. - Chainguard
  92. - Wolfi OS
  93. ## Quick Start
  94. dep-scan is ideal for use during continuous integration (CI) and as a local development tool.
  95. ### Scanning projects locally (Python version)
  96. ```bash
  97. sudo npm install -g @cdxgen/cdxgen@13.8.0
  98. # Normal version recommended for most users (MIT)
  99. pip install owasp-depscan
  100. # For a full version with all extensions and server mode (Multiple Licenses)
  101. pip install owasp-depscan[all]
  102. ```
  103. This would install two commands called `cdxgen` and `depscan`.
  104. You can invoke the scan command directly with the various options.
  105. ```bash
  106. cd <project to scan>
  107. depscan scan $PWD --reports-dir $PWD/reports
  108. ```
  109. The verbs and the full list of scan options are below (`depscan --help`):
  110. ```text
  111. usage: depscan [-h]
  112. {scan,report,vdb,doctor,schema,config,serve,validate,version,help} ...
  113. Fully open-source security and license audit for application dependencies and
  114. container images based on known vulnerabilities and advisories.
  115. positional arguments:
  116. {scan,report,vdb,doctor,schema,config,serve,validate,version,help}
  117. scan Scan a project, BOM, purl or container image for
  118. vulnerabilities.
  119. report Render the console tables and explanations of a saved
  120. scan.
  121. vdb Download and inspect the vdb vulnerability database.
  122. doctor Report the tools, data and capabilities a scan can use
  123. here.
  124. schema Print the published finding schemas.
  125. config Show the effective scan options or write a config
  126. file.
  127. serve Run depscan as a server.
  128. validate Validate CSAF VEX or CycloneDX VDR/VEX documents
  129. against their schema.
  130. version Print the dep-scan version, with tool versions as
  131. JSON.
  132. help Show the top-level help, or one verb's help.
  133. options:
  134. -h, --help show this help message and exit
  135. Visit https://github.com/owasp-dep-scan/dep-scan to learn more
  136. ```
  137. The scan verb's own options (`depscan scan --help`):
  138. ```text
  139. usage: depscan scan [-h]
  140. [--target-kind {purl,git,container,bom,bom-dir,binary,android,ios,source,firmware}]
  141. [--checks CHECKS]
  142. [--profile {quick,ci,deep,research,offline}]
  143. [--bom-profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}]
  144. [--exclude-type TYPE] [--format {text,json}]
  145. [--config CONFIG] [--no-banner] [-o REPORTS_DIR] [--debug]
  146. [-q | --explain] [--csaf] [--csaf-version {2.0,2.1}]
  147. [--custom-data CUSTOM_DATA]
  148. [--report-template REPORT_TEMPLATE]
  149. [--report-name REPORT_NAME]
  150. [--lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]]
  151. [--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} ...]]
  152. [--bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} |
  153. --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}]
  154. [--reachability-analyzer {off,FrameworkReachability,SemanticReachability}]
  155. [--spec-version SPEC_VERSION] [--cdxgen-args CDXGEN_ARGS]
  156. [--cdxgen-server CDXGEN_SERVER]
  157. [--rust-analyzer-backend {stable,compiler}]
  158. [--go-analyzer-network {auto,offline}] [--go-analyzer-cgo]
  159. [--dotnet-analyzer-mode {source,assembly,auto}]
  160. [--no-suggest] [--fail-on-error]
  161. [-t PROJECT_TYPE [PROJECT_TYPE ...]]
  162. [--private-ns PRIVATE_NS] [--deep] [--fuzzy-search]
  163. [--search-order {purl,pcu,cpe,cpu,url}]
  164. [--severity {low,medium,high,critical}] [--malware-only]
  165. [--vdb-flavor {full,app-only,app-extended,app-10y,app-10y-extended}]
  166. [--vdb-scope {app,app+os}] [--vdb-time {2y,default,10y}]
  167. [--vdb-extended] [--vdb-compression {xz,zst}]
  168. [--vdb-distro {alpine,debian,redhat,alma,rocky,ubuntu}]
  169. [--vdb-image VDB_IMAGE] [--no-universal] [--no-vuln-table]
  170. [--explanation-mode {Endpoints,EndpointsAndReachables,NonReachables,LLMPrompts}]
  171. [--annotate]
  172. [target ...]
  173. positional arguments:
  174. target What to scan: a source directory, git URL, container
  175. image reference, BOM file, BOM directory, purl or
  176. binary. The kind is detected; pass --target-kind to
  177. force one. Multiple targets run one scan each.
  178. options:
  179. -h, --help show this help message and exit
  180. --target-kind {purl,git,container,bom,bom-dir,binary,android,ios,source,firmware}
  181. Force the kind of every target instead of detecting
  182. it. firmware is accepted only to be refused: it has no
  183. inventory path in this version.
  184. --checks CHECKS Comma-separated list of checks to run: all,
  185. vulnerabilities, reachability, license, supply-chain,
  186. binary, memory-safety, mobile, code, crypto. An
  187. explicit list defines the whole optional set;
  188. vulnerabilities always runs.
  189. --profile {quick,ci,deep,research,offline}
  190. Scan profile: quick (vulnerabilities only), ci
  191. (vulnerabilities and reachability, no explanations),
  192. deep (adds license and supply-chain with semantic
  193. reachability), research (deep plus cdxgen's research
  194. BOM profile), offline (no database download, no remote
  195. cdxgen). Explicit options win over the profile.
  196. --bom-profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}
  197. Profile to use while generating the BOM. For granular
  198. control, use the arguments --bom-engine,
  199. --vulnerability-analyzer, or --reachability-analyzer.
  200. --exclude-type TYPE Project type dropped from the detected list before any
  201. stage runs, so no inventory or scan runs for it (an
  202. excluded os or docker type stops the OS and container
  203. scans), and passed to cdxgen as a repeated --exclude-
  204. type argument so the BOM contents are filtered the
  205. same way. Repeatable; comma-separated values are
  206. accepted.
  207. --format {text,json} text for people, json for scripts (default: text)
  208. --config CONFIG Path to the configuration file. Default:
  209. $PWD/.config/depscan.toml
  210. --no-banner Do not display the logo and donation banner. Please
  211. make a donation to OWASP before using this argument.
  212. -o, --reports-dir REPORTS_DIR
  213. Reports directory
  214. --debug Run depscan in debug mode.
  215. -q, --quiet Makes depscan quiet.
  216. --explain Makes depscan to explain the various analysis. Useful
  217. for creating detailed reports.
  218. --csaf Generate a OASIS CSAF VEX document
  219. --csaf-version {2.0,2.1}
  220. CSAF schema version to target (default: 2.1). CSAF 2.1
  221. retains CVSS v4 scores; 2.0 drops them because the
  222. schema has no cvss_v4 slot.
  223. --custom-data CUSTOM_DATA
  224. Path to directory containing custom vulnerability data
  225. (JSON/YAML/TOML) to override/augment results.
  226. --report-template REPORT_TEMPLATE
  227. Jinja template file used for rendering a custom report
  228. --report-name REPORT_NAME
  229. Filename of the custom report written to the
  230. --reports-dir
  231. --lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]
  232. Product lifecycle for the generated BOM. Multiple
  233. values allowed.
  234. --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} ...]
  235. Analysis technique to use for BOM generation. Multiple
  236. values allowed.
  237. --bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator}
  238. BOM generation engine to use. Defaults to automatic
  239. selection based on project type and lifecycle.
  240. --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}
  241. Vulnerability analyzer to use. Defaults to automatic
  242. selection based on bom_dir argument.
  243. --reachability-analyzer {off,FrameworkReachability,SemanticReachability}
  244. Reachability analyzer to use. Default
  245. FrameworkReachability.
  246. --spec-version SPEC_VERSION
  247. CycloneDX specification version to request from
  248. cdxgen. Choices: 1.4, 1.5, 1.6, 1.7, 2.0. Defaults to
  249. 1.6 (1.7 is not yet supported by Dependency-Track and
  250. some other consumers).
  251. --cdxgen-args CDXGEN_ARGS
  252. Additional arguments to pass to cdxgen
  253. --cdxgen-server CDXGEN_SERVER
  254. cdxgen server url. Eg: http://cdxgen:9090
  255. --rust-analyzer-backend {stable,compiler}
  256. rusi (Rust Source Inspector) backend for Rust
  257. reachability. ``stable`` (default) is syn-based
  258. parsing with no cargo/rustc build and is safe on
  259. untrusted repos. ``compiler`` embeds nightly rustc and
  260. builds the target for higher fidelity -- only use on
  261. trusted input (see rusi THREAT_MODEL). Implied by
  262. --deep for Rust projects. Set DEPSCAN_RUSI_BINARY to
  263. point at a non-PATH rusi binary.
  264. --go-analyzer-network {auto,offline}
  265. Network mode for golem (Go Source Inspector)
  266. reachability. golem runs with cgo off, so packages
  267. that need cgo are not loaded and their reachability is
  268. missing; pass --go-analyzer-cgo to enable cgo for
  269. trusted input. ``auto`` (default) allows golem's
  270. package loader to download missing modules per the
  271. user's Go env (GOFLAGS=-mod=readonly is still set to
  272. prevent go.mod rewrites). ``offline`` sets GOPROXY=off
  273. to forbid all downloads -- requires a warm module
  274. cache (GOMODCACHE). Set DEPSCAN_GOLEM_BINARY to point
  275. at a non-PATH golem binary.
  276. --go-analyzer-cgo Allow cgo while golem loads Go packages. Default is
  277. cgo off: packages that need cgo are not loaded and
  278. their reachability is missing. With this flag the C
  279. compiler runs with flags taken from the scanned code
  280. and its dependencies, so use it only for input you
  281. trust. Can also be enabled with
  282. DEPSCAN_GO_ANALYZER_CGO.
  283. --dotnet-analyzer-mode {source,assembly,auto}
  284. dosai (Dotnet Source and Assembly Inspector) analysis
  285. mode for .NET reachability. ``auto`` (default)
  286. inspects source when a source tree is present and
  287. falls back to assembly inspection for bin/.nupkg-only
  288. inputs. ``source`` forces Roslyn-based C#/VB/F# source
  289. inspection; ``assembly`` forces Reflection-based
  290. .dll/.exe inspection. Pattern packs default to
  291. ``all``. dosai requires a .NET runtime (or a self-
  292. contained ``-full`` binary). Set DOSAI_CMD to point at
  293. a non-PATH dosai binary. dep-scan does NOT run
  294. ``dotnet restore``; a restored tree yields the best
  295. versioned NuGet purls.
  296. --no-suggest Disable suggest mode
  297. --fail-on-error Abort the scan with a non-zero exit code instead of
  298. silently degrading. Passed through to cdxgen so
  299. extractor failures fail BOM generation, and applied to
  300. blint, rusi, golem, and dosai failures, unreadable
  301. reachability reports, empty slices, and empty package
  302. lists.
  303. -t, --type PROJECT_TYPE [PROJECT_TYPE ...]
  304. Override project types if auto-detection is incorrect.
  305. Multiple values supported.
  306. --private-ns PRIVATE_NS
  307. Private namespace to use while performing oss risk
  308. audit. Private packages should not be available in
  309. public registries by default. Comma separated values
  310. accepted.
  311. --deep Perform deep scan by passing this --deep argument to
  312. cdxgen. Useful while scanning docker images and OS
  313. packages.
  314. --fuzzy-search Perform fuzzy search by creating variations of package
  315. names. Use this when the input SBOM lacks a PURL.
  316. --search-order {purl,pcu,cpe,cpu,url}
  317. Attributes to use while searching for vulnerabilities.
  318. Default: PURL, CPE, URL (pcu).
  319. --severity {low,medium,high,critical}
  320. Minimum severity threshold to report (low, medium,
  321. high, critical). Only advisories at or above this
  322. severity are returned. depscan applies this floor to
  323. the final VDR on any database; on the extended vdb
  324. (VDB_INCLUDE_METADATA) it is additionally pushed down
  325. into the search for speed. Findings with no rated
  326. severity are kept.
  327. --malware-only Report only malware advisories (MAL-*). Works on the
  328. default vdb because is_malware is always populated via
  329. the MAL- fallback.
  330. --no-universal Depscan would attempt to perform a single universal
  331. scan instead of individual scans per language type.
  332. --no-vuln-table Do not print the table with the full list of
  333. vulnerabilities. This can help reduce console output.
  334. --explanation-mode {Endpoints,EndpointsAndReachables,NonReachables,LLMPrompts}
  335. Style of explanation needed. Defaults to Endpoints and
  336. Reachables.
  337. --annotate Include the generated text VDR report as an
  338. annotation. Defaults to true when explain is enabled;
  339. false otherwise.
  340. vulnerability database selection:
  341. Select which published vdb database the scan downloads. These can also be
  342. persisted in the depscan config file (e.g. vdb_flavor = "app-only"). An
  343. explicit VDB_DATABASE_URL env pin always wins. The `depscan vdb download`
  344. command shares the same options for pre-fetching.
  345. --vdb-flavor {full,app-only,app-extended,app-10y,app-10y-extended}
  346. Which published database flavor to use: 'full'
  347. (app+OS), 'app-only' (application ecosystems, NVD
  348. 2020+), 'app-extended' (adds metadata tables for
  349. severity, text, alias, reference, symbol and date
  350. search), 'app-10y' (NVD 2016+), 'app-10y-extended'
  351. (both). Default: full.
  352. --vdb-scope {app,app+os}
  353. Deprecated alias for --vdb-flavor: 'app' maps to app-
  354. only (or app-extended/app-10y/app-10y-extended with
  355. the other deprecated options), 'app+os' to full.
  356. Default: app+os.
  357. --vdb-time {2y,default,10y}
  358. Deprecated alias for --vdb-flavor: '10y' selects a
  359. 10-year flavor; '2y' has no v7 equivalent and is
  360. rejected. Default: default.
  361. --vdb-extended Deprecated alias selecting the metadata flavor (app-
  362. extended or app-10y-extended), needed for severity,
  363. text, alias, reference, symbol, and date search. Auto-
  364. selected when --severity is set.
  365. --vdb-compression {xz,zst}
  366. Compression format. 'xz' (tar.xz) always works; 'zst'
  367. (zstd) is faster to decompress but needs a zstd
  368. decompressor. Default: xz.
  369. --vdb-distro {alpine,debian,redhat,alma,rocky,ubuntu}
  370. Rejected: vdb 7 publishes no per-distro complete
  371. database. Pass --vdb-flavor full and scan the distro
  372. packages, or fetch type shards with `depscan vdb
  373. download`.
  374. --vdb-image VDB_IMAGE
  375. Override the vdb image URL verbatim (bypasses the
  376. resolver). Equivalent to setting VDB_DATABASE_URL.
  377. ```
  378. ### Homebrew (macOS and Linux)
  379. Homebrew installs the [standalone binary](#standalone-binaries-no-python-or-nodejs-required) as `depscan` from the [OWASP dep-scan tap](https://github.com/owasp-dep-scan/homebrew-tap), with cdxgen bundled and no Python or Node.js needed. `brew trust` accepts the tap, which Homebrew requires before loading formulae from a third-party tap when `HOMEBREW_REQUIRE_TAP_TRUST` is set:
  380. ```bash
  381. brew tap owasp-dep-scan/tap
  382. brew trust --tap owasp-dep-scan/tap
  383. brew install dep-scan
  384. depscan scan $PWD --reports-dir $PWD/reports
  385. ```
  386. ### Standalone binaries (no Python or Node.js required)
  387. Pre-built single-file executables are attached to each [GitHub release](https://github.com/owasp-dep-scan/dep-scan/releases). They bundle a matching [cdxgen](https://github.com/cdxgen/cdxgen) SEA binary, so BOM generation works out of the box without installing Python, Node.js, or cdxgen.
  388. | Platform | Architecture | Asset |
  389. | --------------------- | ------------- | --------------------------- |
  390. | Linux (glibc) | x86_64 | `depscan-linux-amd64` |
  391. | Linux (glibc) | arm64 | `depscan-linux-arm64` |
  392. | Linux (musl / Alpine) | x86_64 | `depscan-linux-amd64-musl` |
  393. | Linux (musl / Alpine) | arm64 | `depscan-linux-arm64-musl` |
  394. | macOS | Apple silicon | `depscan-darwin-arm64` |
  395. | macOS | Intel | `depscan-darwin-amd64` |
  396. | Windows | x86_64 | `depscan-windows-amd64.exe` |
  397. Each asset has a matching `.sha256` file for verification.
  398. ```bash
  399. # Example: Linux x86_64
  400. curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64
  401. curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64.sha256
  402. sha256sum -c depscan-linux-amd64.sha256
  403. chmod +x depscan-linux-amd64
  404. ./depscan-linux-amd64 scan $PWD --reports-dir $PWD/reports
  405. ```
  406. > [!NOTE]
  407. > The macOS binaries are currently unsigned. On first run macOS Gatekeeper may block them; clear the quarantine attribute with `xattr -d com.apple.quarantine ./depscan-darwin-arm64` (or allow the binary under System Settings, Privacy & Security).
  408. > [!NOTE]
  409. > The vulnerability database is still downloaded on first run. Only cdxgen is bundled, not the vuln DB. Use the `depscan vdb download` command to select a specific database variant, for example `depscan vdb download --flavor app-only` for a smaller app-only database. See the [vulnerability database guide](https://depscan.readthedocs.io/vulnerability-database) for the full image matrix.
  410. All standalone binaries bundle `blint`, but not its optional `nyxstone` disassembly backend (which has no wheels and no Windows support). Deep disassembly-based binary analysis is therefore unavailable in the standalone binaries; use the Python package (`pip install owasp-depscan[all]`) if you need it.
  411. ### Scanning containers locally (Python version)
  412. Scan a Java project.
  413. ```bash
  414. depscan scan <path> -o containertests -t java
  415. ```
  416. Scan `latest` tag of the container `shiftleft/scan-slim`
  417. ```bash
  418. depscan scan shiftleft/scan-slim -o containertests -t docker
  419. ```
  420. Include `license` to the type to perform the license audit.
  421. ```bash
  422. depscan scan shiftleft/scan-slim -o containertests -t docker license
  423. ```
  424. You can also specify the image using the sha256 digest
  425. ```bash
  426. depscan scan redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker
  427. ```
  428. You can also save container images using docker or podman save command and pass the archive to depscan for scanning.
  429. ```bash
  430. docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
  431. # podman save --format oci-archive -o /tmp/scanslim.tar shiftleft/scan-slim:latest
  432. depscan scan /tmp/scanslim.tar -o reports -t docker
  433. ```
  434. Refer to the docker tests under the GitHub action workflow for this repo for more examples.
  435. ### Scanning projects locally (Docker container)
  436. `ghcr.io/owasp-dep-scan/dep-scan` container image can be used to perform the scan.
  437. To scan with default settings
  438. ```bash
  439. docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan scan /app --reports-dir /app/reports
  440. ```
  441. To scan with custom environment variables based configuration
  442. ```bash
  443. docker run --rm \
  444. -e VDB_HOME=/db \
  445. -e GITHUB_TOKEN=<token> \
  446. -v /tmp:/db \
  447. -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan scan /app --reports-dir /app/reports
  448. ```
  449. 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.
  450. ### Server mode
  451. dep-scan and cdxgen could be run in server mode. Use the included docker-compose file to get started.
  452. ```bash
  453. git clone https://github.com/owasp-dep-scan/dep-scan
  454. docker compose up
  455. ```
  456. The bundled compose file sets `DEPSCAN_SERVER_API_KEY` to a development placeholder by default so the dep-scan service can bind to `0.0.0.0`. Override this value before exposing the service outside a local lab.
  457. ```bash
  458. depscan serve --server-host 127.0.0.1 --server-port 7070
  459. ```
  460. If you need to bind dep-scan to a non-local address, set an API key first:
  461. ```bash
  462. export DEPSCAN_SERVER_API_KEY="change-this-before-production"
  463. depscan serve --server-host 0.0.0.0 --server-port 7070
  464. ```
  465. > [!IMPORTANT]
  466. > dep-scan refuses to bind to a non-local address without either `DEPSCAN_SERVER_API_KEY` or an explicit opt-in via `DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true`.
  467. The server refuses cross-site browser requests (a `Sec-Fetch-Site` of `cross-site` or `same-site`, or an `Origin` that does not match `Host`). Without an API key it also accepts only `localhost`, `*.localhost`, IP addresses and the names in `DEPSCAN_SERVER_TRUSTED_HOST_NAMES` as the `Host` header, which stops DNS rebinding, and when it is reached by a name or address other than `localhost` or loopback, `path` and `url` must be sent in a JSON body.
  468. Use the `/scan` endpoint to perform scans.
  469. > [!NOTE]
  470. > The `type` parameter is mandatory in server mode. When API key authentication is enabled, send the key using `X-API-Key` or `Authorization: Bearer <key>`.
  471. - Scanning a local directory.
  472. Scanning an SBOM file (present locally).
  473. ```bash
  474. curl \
  475. -H 'X-API-Key: dev-only-change-me' \
  476. --json '{"path": "/tmp/vulnerable-aws-koa-app/sbom_file.json", "type": "js"}' \
  477. http://127.0.0.1:7070/scan
  478. ```
  479. - Scanning a GitHub repo.
  480. ```bash
  481. curl \
  482. -H 'Authorization: Bearer dev-only-change-me' \
  483. --json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' \
  484. http://127.0.0.1:7070/scan \
  485. -o app.vdr.json
  486. ```
  487. - Uploading an SBOM file and generating results based on it.
  488. ```bash
  489. curl -X POST \
  490. -H 'X-API-Key: dev-only-change-me' \
  491. -H 'Content-Type: multipart/form-data' \
  492. -F 'file=@/tmp/app/sbom_file.json' \
  493. http://127.0.0.1:7070/scan?type=js
  494. ```
  495. ## Local development
  496. Setup uv by following the official [documentation](https://docs.astral.sh/uv/).
  497. ```shell
  498. uv sync --all-extras --all-packages
  499. uv run depscan --help
  500. uv run pytest
  501. uv run pyrefly check
  502. ```
  503. Type checking uses [pyrefly](https://pyrefly.org) (configuration lives in
  504. `[tool.pyrefly]` in `pyproject.toml`); the check is expected to report zero
  505. errors.
  506. ### Local VDB setup
  507. ```shell
  508. vdb --clean
  509. vdb db refresh full --app-only
  510. # To scan containers and OS images
  511. # vdb db refresh full
  512. ```
  513. ### Scan local depscan
  514. ```shell
  515. uv run depscan scan --config .config/depscan-dev.toml
  516. ```
  517. This would automatically use the configuration specified in the local config [file](./.config/depscan.toml).
  518. ## Documentation
  519. Full documentation is at [depscan.readthedocs.io](https://depscan.readthedocs.io). Key pages:
  520. - [Supported languages and reachability matrix](https://depscan.readthedocs.io/supported-languages)
  521. - [Reachability analysis](https://depscan.readthedocs.io/reachability-analysis) (hub)
  522. - [The reachability model](https://depscan.readthedocs.io/concepts/reachability-model)
  523. - [How dep-scan prioritizes](https://depscan.readthedocs.io/concepts/prioritization)
  524. - [SBOM and evidence](https://depscan.readthedocs.io/concepts/sbom-and-evidence)
  525. - Language guides: [Rust](https://depscan.readthedocs.io/languages/rust-reachability), [Go](https://depscan.readthedocs.io/languages/go-reachability), [.NET](https://depscan.readthedocs.io/languages/dotnet-reachability), [JVM/JS/Python/PHP](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability)
  526. - Analyzers: [Framework reachability](https://depscan.readthedocs.io/analyzers/framework-reachability), [Semantic reachability](https://depscan.readthedocs.io/analyzers/semantic-reachability)
  527. - Output and compliance: [VDR guide](https://depscan.readthedocs.io/output/vdr-guide), [CSAF VEX guide](https://depscan.readthedocs.io/output/vex-csaf-guide)
  528. - [Customization through environment variables](https://depscan.readthedocs.io/env-var#customization-through-environment-variables)
  529. - Advanced usage: [GitHub Security Advisory](https://depscan.readthedocs.io/adv-usage#github-security-advisory), [Suggest mode](https://depscan.readthedocs.io/adv-usage#suggest-mode), [Package Risk audit](https://depscan.readthedocs.io/adv-usage#package-risk-audit), [Live OS scan](https://depscan.readthedocs.io/adv-usage#live-os-scan), [License scan](https://depscan.readthedocs.io/adv-usage#license-scan), [Custom reports](https://depscan.readthedocs.io/adv-usage#custom-reports)
  530. ## License
  531. MIT License
  532. This project was donated to the OWASP Foundation in August 2023 by AppThreat Ltd.
  533. ## Funding
  534. This project is funded through [NGI Zero Core](https://nlnet.nl/core), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/OWASP-dep-scan).
  535. [<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
  536. [<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/core)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.