How to Use the Command 'osv-scanner' (with Examples)

The osv-scanner command is a powerful tool used to analyze various software components for vulnerabilities. It scans for dependencies across different mediums and checks them against the Open Source Vulnerabilities (OSV) database, providing a crucial layer of security by identifying known issues in libraries or packages used in your projects. Whether you’re working with Docker images, package lockfiles, software bill of materials (SBOM), or directories containing multiple projects, osv-scanner assists in quickly pinpointing potential weaknesses and keeping your software secure.

Use Case 1: Scan a Docker Image

Code:

osv-scanner -D docker_image_name

Motivation:

Scanning Docker images is essential as these images often contain multiple layers, each with its own set of dependencies. An unscanned image could hide vulnerabilities that compromise an entire application or system. By using osv-scanner to analyze a Docker image, developers and DevOps teams can ensure that all dependencies within the image are checked against the OSV database, securing the deployment environment.

Explanation:

• -D: This argument specifies that the target is a Docker image, which the scanner will analyze.
• docker_image_name: Represents the name of the Docker image you wish to scan. It acts as an identifier for the specific image stored locally or in a registry.

Example Output:

Scanning Docker image: myapp_image
Scanning layer: 0b123abc45de...
Found vulnerabilities: 2
- CVE-2023-1234 - High severity
- CVE-2023-5678 - Medium severity

Use Case 2: Scan a Package Lockfile

Code:

osv-scanner -L path/to/lockfile

Motivation:

Package lockfiles, such as package-lock.json or yarn.lock, explicitly specify the version of each dependency used in a project. Scanning these lockfiles is vital because it helps identify vulnerabilities directly linked to the particular versions of libraries your application depends on. By doing so, developers can promptly upgrade or patch vulnerable dependencies.

Explanation:

• -L: This argument tells osv-scanner to examine a lockfile for dependencies.
• path/to/lockfile: The path pointing to the lockfile you intend to analyze, ensuring that all dependencies listed are scrutinized for vulnerabilities.

Example Output:

Scanning lockfile at path/to/lockfile
Dependencies analyzed: 115
Found vulnerabilities: 5
- CVE-2023-2345 - High severity in 'example-lib'
- CVE-2023-6789 - Low severity in 'utils-lib'
...

Use Case 3: Scan an SBOM File

Code:

osv-scanner -S path/to/sbom_file

Motivation:

A Software Bill of Materials (SBOM) is a formal record of the components and dependencies in a project, often used for compliance and risk management. Scanning an SBOM file with osv-scanner helps maintain up-to-date security oversight on components listed in the SBOM, particularly useful for organizations that manage numerous software products or are subject to strict regulatory requirements.

Explanation:

• -S: Indicates that the scanner should analyze an SBOM file for details on dependencies.
• path/to/sbom_file: The file path to your SBOM, allowing the tool to parse and scrutinize the recorded dependencies.

Example Output:

Scanning SBOM at path/to/sbom_file
Components listed: 45
Detected vulnerabilities: 3
- CVE-2023-8910 - Critical in 'network-lib'
- CVE-2023-0912 - Medium in 'cache-lib'
...

Use Case 4: Scan Multiple Directories Recursively

Code:

osv-scanner -r directory1 directory2 ...

Motivation:

Projects often span across several directories, especially in larger applications with microservices or modular components. Scanning directories recursively ensures a comprehensive analysis of all dependencies, including nested ones, which might otherwise be overlooked. This approach helps in maintaining the security integrity of the entire codebase.

Explanation:

• -r: Instructs the scanner to perform a recursive scan, delving into subdirectories to analyze all contained dependencies.
• directory1 directory2 ...: Represents multiple directories to be scanned, allowing users to cover extensive project structures seamlessly.

Example Output:

Scanning directories: src/, lib/
Total files scanned: 350
Vulnerabilities found: 12
- CVE-2023-3456 - High severity in 'db-connector'
- CVE-2023-6543 - Medium severity in 'auth-module'
...

Use Case 5: Skip Scanning Git Repositories

Code:

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

Motivation:

Sometimes, the goal is to quickly scan directories without analyzing associated Git repositories. This might be the case in continuous integration environments where time efficiency is paramount or when you want to focus on non-version-controlled files. The --skip-git option allows osv-scanner to bypass these repositories, saving time and focusing scanning efforts where they are most needed.

Explanation:

• --skip-git: A flag to skip any directories that are recognized as Git repositories, optimizing scanning duration.
• -r|-D target: Options to specify whether you’re scanning directories or a Docker image, followed by the respective target(s) to be scanned.

Example Output:

Scanning docker image: myapp_image (Git repos skipped)
Layers analyzed: 5
Vulnerabilities discovered: 1
- CVE-2023-1594 - Low severity

Use Case 6: Output Result in JSON Format

Code:

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

Motivation:

Producing output in JSON format facilitates automated processing of scan results, integrating with monitoring tools, cloud services, or other applications. It allows security teams to systematically parse and handle findings, enabling more sophisticated analytics or reporting within their security management pipelines.

Explanation:

• --json: This flag ensures that the scanner outputs results in JSON format, suitable for machine processing.
• -D|-L|-S|-r target: Specifies the type of scan you are running (Docker image, lockfile, SBOM, or directory) and the target(s) for that scan.

Example Output:

{
  "total_vulnerabilities": 8,
  "vulnerabilities": [
    {
      "id": "CVE-2023-4782",
      "severity": "High",
      "package_name": "core-module"
    },
    {
      "id": "CVE-2023-1123",
      "severity": "Low",
      "package_name": "helper-lib"
    }
  ]
}

Conclusion:

The osv-scanner command is an immensely versatile tool that serves a variety of scanning purposes across different software components. From Docker images to SBOM files, and recursive directory analysis, osv-scanner empowers developers and security professionals to proactively identify vulnerabilities in their software projects. By understanding how to apply each of these use cases, you can ensure a robust security posture for your applications across all stages of development and deployment.