docs/scan-source.md
OSV-Scanner can be used to scan your project source and lockfiles to find vulnerabilities in your dependencies.
osv-scanner scan source <flags> [paths...]
As this is the most common use case of osv-scanner, scan source is the default subcommand of osv-scanner, so the above is equivalent to:
osv-scanner <flags> [paths...]
osv-scanner scan source -r /path/to/your/dir
The preceding command will find lockfiles, SBOMs, and git directories in your target directory and use them to determine the dependencies to check against the OSV database for any known vulnerabilities.
The recursive flag -r or --recursive will tell the scanner to search all subdirectories in addition to the specified directory. It can find additional lockfiles, dependencies, and vulnerabilities. If your project has deeply nested subdirectories, a recursive search may take a long time.
By default, OSV-Scanner will not scan files that are ignored by .gitignore files. All recursively scanned files are matched to a git repository (if it exists) and any matching .gitignore files within that repository are taken into account.
There is a known issue that the parser does not correctly respect repository boundaries.
The --no-ignore flag can be used to force the scanner to scan ignored files.
Experimental {: .label }
You can exclude specific paths from scanning using the --experimental-exclude flag. This is useful for excluding test directories, documentation, or vendor directories from vulnerability scans.
Note: This flag currently only excludes directories, not individual files. This is an experimental feature and the syntax may change in future versions.
The flag supports three pattern types, matching the --lockfile flag syntax:
: prefix): Matches directories with the exact nameg: prefix): Matches using glob patternsr: prefix): Matches using regular expressions# Exclude directories named "test" or "docs" (exact match)
osv-scanner scan source -r --experimental-exclude=test --experimental-exclude=docs /path/to/your/dir
# Exclude using glob patterns
osv-scanner scan source -r --experimental-exclude="g:**/test/**" --experimental-exclude="g:**/docs/**" /path/to/your/dir
# Exclude using regex patterns
osv-scanner scan source -r --experimental-exclude="r:.*_test$" /path/to/your/dir
# Mix different pattern types
osv-scanner scan source -r --experimental-exclude=vendor --experimental-exclude="g:**/test/**" --experimental-exclude="r:\\.cache" /path/to/your/dir
# Escape directory names containing colons using : prefix
osv-scanner scan source -r --experimental-exclude=":my:project" /path/to/your/dir
--experimental-exclude=test or --experimental-exclude="g:**/test/**"--experimental-exclude=docs--experimental-exclude=vendorAlternatively, you can use the osv-scanner.toml configuration file with [[PackageOverrides]] to ignore specific packages or directories. See Configuration for more details.
SBOMs will be automatically identified so long as their name follows the specification for the particular format:
*.spdx.json*.spdx*.spdx.yml*.spdx.rdf*.spdx.rdf.xmlbom.json*.cdx.jsonbom.xml*.cdx.xmlosv-scanner scan source -L /path/to/your/sbom.spdx.json
SPDX and CycloneDX SBOMs using Package URLs are supported.
If you want to check for known vulnerabilities in specific lockfiles, you can use the following command:
osv-scanner scan source --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/Cargo.lock
It is possible to specify more than one lockfile at a time; you can also specify how to parse an arbitrary file:
osv-scanner scan source --lockfile 'requirements.txt:/path/to/your/extra-requirements.txt'
The list of supported lockfile formats can be found here.
If the file you are scanning is located in a directory that has a colon in its name, you can prefix the path to just a colon to explicitly signal to the scanner that it should infer the parser based on the filename:
osv-scanner scan source --lockfile ':/path/to/my:projects/package-lock.json'
OSV-Scanner will automatically scan git submodules and vendored directories for C/C++ code and try to attribute them to specific dependencies and versions. See C/C++ Scanning for more details.
By default, root git directories (i.e. git repositories that are not a submodule of a bigger git repo) are skipped. You can include those repositories by setting the --include-git-root flag.
Call stack analysis can be performed on some languages to check if the vulnerable code is actually being executed by your project. If the code is not being executed, these vulnerabilities will be marked as unexecuted.
To enable call analysis in all languages, call OSV-Scanner with the --call-analysis=all flag. By default, call analysis in Go is enabled, but you can disable it using the --no-call-analysis=go flag.
OSV-Scanner uses the govulncheck library to analyze Go source code to identify called vulnerable functions.
go compiler needs to be installed and available on PATH.
Experimental {: .label }
Call analysis in Rust is still considered experimental.
{: .warning }
Running call analysis for Rust will execute build scripts (
build.rs) in your dependencies as part of the compilation. This may execute arbitrary code.
OSV-Scanner compiles Rust source code and analyzes the output binary's DWARF debug information to identify called vulnerable functions.
Rust toolchain (including cargo) that can compile the source code being scanned needs to be installed and available on PATH.
The installed Rust toolchain must be capable of compiling every crate/target in the scanned code, for code with a lot of dependencies this will take a few minutes.
Current implementation has a few limitations:
osv-scanner scan source --call-analysis=rust --no-call-analysis=go ./my/project/path