How to use the command osv-scanner (with examples)

The osv-scanner command is used to scan various mediums, such as docker images, package lockfiles, SBOM files, and directories, for dependencies. It then matches these dependencies against the OSV (Open Source Vulnerabilities) database to identify any vulnerabilities. It can skip scanning git repositories and output the results in JSON format.

Use case 1: Scan a docker image

Code:

osv-scanner -D docker_image_name

Motivation: This use case is useful when you want to scan a docker image and check for any vulnerabilities in the dependencies used in the image. It helps in identifying any security risks before deploying the image.

Explanation:

• -D: Specifies that we want to scan a docker image.
• docker_image_name: Specifies the name of the docker image to be scanned.

Example output:
The output will display a list of vulnerabilities found in the docker image along with their severity levels and other details.

Use case 2: Scan a package lockfile

Code:

osv-scanner -L path/to/lockfile

Motivation: This use case is helpful when you want to scan a package lockfile (e.g., package-lock.json) and identify any vulnerabilities in the dependencies listed in the lockfile. It allows you to ensure the security of your project by detecting any potential risks.

Explanation:

• -L: Specifies that we want to scan a package lockfile.
• path/to/lockfile: Specifies the path to the package lockfile that needs to be scanned.

Example output:
The output will display a list of vulnerabilities found in the package lockfile along with their severity levels and other details.

Use case 3: Scan an SBOM file

Code:

osv-scanner -S path/to/sbom_file

Motivation: This use case is useful when you have an SBOM (Software Bill of Materials) file and want to check for any vulnerabilities in the listed dependencies. It helps in ensuring the security of the software by detecting any potential vulnerabilities.

Explanation:

• -S: Specifies that we want to scan an SBOM file.
• path/to/sbom_file: Specifies the path to the SBOM file that needs to be scanned.

Example output:
The output will display a list of vulnerabilities found in the SBOM file along with their severity levels and other details.

Use case 4: Scan multiple directories recursively

Code:

osv-scanner -r directory1 directory2 ...

Motivation: This use case is beneficial when you want to scan multiple directories and their subdirectories recursively to identify any vulnerabilities in the dependencies used within the files in those directories. It helps in finding security risks across various files in the specified directories.

Explanation:

• -r: Specifies recursive scanning of directories.
• directory1 directory2 ...: Specifies the directories that need to be scanned. Multiple directories can be provided.

Example output:
The output will display a list of vulnerabilities found in the files within the specified directories along with their severity levels and other details.

Use case 5: Skip scanning git repositories

Code:

osv-scanner --skip-git -r|-D target

Motivation: This use case is helpful when you want to skip scanning git repositories during the scanning process. Git repositories may contain dependencies that are already being scanned individually, and skipping them can save time and resources.

Explanation:

• --skip-git: Specifies to skip scanning git repositories.
• -r|-D target: Specifies the target for scanning, which can be either a directory (-r) or a docker image (-D).

Example output:
The output will display a list of vulnerabilities found in the specified target (directories or docker image) after skipping the git repositories.

Use case 6: Output result in JSON format

Code:

osv-scanner --json -D|-L|-S|-r target

Motivation: This use case is useful when you want the scan result to be in a machine-readable format. JSON format allows easy parsing of the output for further analysis or integration with other tools.

Explanation:

• --json: Specifies the output format as JSON.
• -D|-L|-S|-r target: Specifies the target for scanning, which can be a docker image (-D), package lockfile (-L), SBOM file (-S), or directories (-r).

Example output:
The scan result will be displayed in JSON format, containing information about the vulnerabilities found in the target along with their severity levels and other details.

Conclusion:

The osv-scanner command is a versatile tool that allows scanning various mediums for dependencies and matching them against the OSV database to detect vulnerabilities. With the provided use cases, you can scan docker images, package lockfiles, SBOM files, directories, while also skipping git repositories and obtaining the scan results in JSON format. By utilizing this command, you can enhance the security of your software projects and ensure that no known vulnerabilities are present in your dependencies.