docs: Image scanning docs and various refactors to docs (#1535)

Update the docs to include information for image scanning + some restructuring of the docs. Specifically refactors usage into two sub pages and 1 parent page to match how the `scan` command works. See https://another-rex.github.io/osv-scanner/usage/scan-source for a preview. Need followup work to make this fully work with V2, including: - [x] Mention usage of OSV-Scalibr - [x] Add newly supported lockfiles - More detail on the HTML output format Also finally fixed the Note being really hard to read: ![image](https://github.com/user-attachments/assets/5a405649-d44e-4b78-9fe6-497ea875d244)
google · Jan 28, 2025 · 9d55ac1 · 9d55ac1
1 parent e4deb9d
commit 9d55ac1
Show file tree

Hide file tree

Showing 6 changed files with 364 additions and 156 deletions.
diff --git a/docs/_sass/color_schemes/_variables.scss b/docs/_sass/color_schemes/_variables.scss
@@ -11,7 +11,8 @@ $grey-lt-300: #e6e1e8 !default;
 $purple-000: #7253ed !default;
 $purple-100: #5e41d0 !default;
 $purple-200: #4e26af !default;
-$purple-300: #381885 !default;
+// Override the default purple 300 for better visibility
+$purple-300: #d7c6ff;
 $blue-000: #2c84fa !default;
 $blue-100: #2869e6 !default;
 $blue-200: #264caf !default;

diff --git a/docs/images/html-container-output.png b/docs/images/html-container-output.png
diff --git a/docs/scan-image.md b/docs/scan-image.md
@@ -0,0 +1,135 @@
+---
+layout: page
+title: Container Image Scanning
+parent: Usage
+permalink: /usage/scan-image
+nav_order: 1
+---
+
+# Container Image Scanning
+
+{: .no_toc }
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+- TOC
+{:toc}
+</details>
+
+OSV-Scanner analyzes container images by extracting package information and matching it against known vulnerabilities in the OSV.dev database. This helps identify potential security risks in your containerized applications.
+
+### Prerequisites
+
+- **Docker (Optional)**: If you want to scan images directly by name (e.g., my-image:latest) without exporting them first, the docker command-line tool must be installed and available in your system's PATH. If you choose to scan exported image archives, Docker is not required.
+
+All image scanning is done with the `scan image` subcommand:
+
+```bash
+osv-scanner scan image <image-name>:<tag>
+```
+
+## Scanning Methods
+
+You can scan container images using two primary methods:
+
+1. **Direct Image Scan:** Specify the image name and tag (e.g., `my-image:latest`). OSV-Scanner will attempt to locate the image locally. If not found locally, it will attempt to pull the image from the appropriate registry using the `docker` command.
+
+   ```bash
+   osv-scanner scan image image-name:tag
+   ```
+
+   - **How it works:** OSV-Scanner uses `docker save` to export the image to a temporary archive, which is then analyzed. No container code is executed during the scan.
+
+2. **Scan from Exported Image Archive:** If you have already exported your container image as a Docker archive (`.tar` file), you can scan it directly using the `--local` flag. This method does not require Docker to be installed.
+
+   ```bash
+   osv-scanner scan image --local ./path/to/my-image.tar
+   ```
+
+   - **How to create an image archive:** You can create an image archive using the following commands:
+
+     ```bash
+     # Using Docker
+     docker save my-image:latest > my-image.tar
+
+     # Using Podman
+     podman save --format=docker-archive my-image:latest > my-image.tar
+
+     # Other image tools: Use the docker archive format to export the tar
+     ```
+
+### Usage Notes
+
+- **No other scan targets:** When using `scan image`, you cannot specify other scan targets (e.g., directories or lockfiles).
+
+- **Configuration Flags:** All the global configuration flags available for the `scan` command (as described in the [Usage documentation](./usage.md)) can be used with the `scan image` subcommand. This includes flags for output format, verbosity, config files, and experimental features.
+
+## Output
+
+By default, OSV-Scanner provides a summarized output of the scan results, grouping vulnerabilities by package. This is designed to handle the large number of vulnerabilities often found in container images.
+
+<details markdown="1">
+<summary><b>Sample table output</b></summary>
+
+```bash
+Container Scanning Result (Debian GNU/Linux 12 (bookworm)):
+Total 20 packages affected by 105 vulnerabilities (7 Critical, 14 High, 19 Medium, 1 Low, 64 Unknown) from 2 ecosystems.
+54 vulnerabilities have fixes available.
+
+Go
+╭─────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Source:artifact:artifact/tester-built-with-1-21-0                                           │
+├─────────┬───────────────────┬───────────────┬────────────┬──────────────────┬───────────────┤
+│ PACKAGE │ INSTALLED VERSION │ FIX AVAILABLE │ VULN COUNT │ INTRODUCED LAYER │ IN BASE IMAGE │
+├─────────┼───────────────────┼───────────────┼────────────┼──────────────────┼───────────────┤
+│ stdlib  │ 1.21.0            │ Fix Available │         20 │ # 8 Layer        │ --            │
+╰─────────┴───────────────────┴───────────────┴────────────┴──────────────────┴───────────────╯
+╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Source:artifact:src/tester                                                                                      │
+├─────────────────────────────┬───────────────────┬───────────────┬────────────┬──────────────────┬───────────────┤
+│ PACKAGE                     │ INSTALLED VERSION │ FIX AVAILABLE │ VULN COUNT │ INTRODUCED LAYER │ IN BASE IMAGE │
+├─────────────────────────────┼───────────────────┼───────────────┼────────────┼──────────────────┼───────────────┤
+│ github.com/gogo/protobuf    │ 1.3.1             │ Fix Available │          1 │ # 9 Layer        │ --            │
+│ github.com/ipfs/go-bitfield │ 1.0.0             │ Fix Available │          1 │ # 9 Layer        │ --            │
+│ stdlib                      │ 1.19.8            │ Fix Available │         25 │ # 9 Layer        │ --            │
+╰─────────────────────────────┴───────────────────┴───────────────┴────────────┴──────────────────┴───────────────╯
+Debian:12
+╭───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Source:os:var/lib/dpkg/status                                                                             │
+├─────────────┬───────────────────┬─────────────────────────┬────────────┬──────────────────┬───────────────┤
+│ PACKAGE     │ INSTALLED VERSION │ FIX AVAILABLE           │ VULN COUNT │ INTRODUCED LAYER │ IN BASE IMAGE │
+├─────────────┼───────────────────┼─────────────────────────┼────────────┼──────────────────┼───────────────┤
+│ aom         │ 3.6.0-1+deb12u1   │ No fix available        │          2 │ # 1 Layer        │ --            │
+...
+│ zlib        │ 1:1.2.13.dfsg-1   │ No fix available        │          1 │ # 0 Layer        │ debian        │
+╰─────────────┴───────────────────┴─────────────────────────┴────────────┴──────────────────┴───────────────╯
+
+Filtered Vulnerabilities:
+╭─────────────┬───────────┬───────────────────────┬─────────────────────┬────────────────╮
+│ PACKAGE     │ ECOSYSTEM │ INSTALLED VERSION     │ FILTERED VULN COUNT │ FILTER REASONS │
+├─────────────┼───────────┼───────────────────────┼─────────────────────┼────────────────┤
+│ apt         │ Debian:12 │ 2.6.1                 │                   1 │ Unimportant    │
+│ binutils    │ Debian:12 │ 2.40-2                │                   8 │ Unimportant    │
+...
+│ util-linux  │ Debian:12 │ 2.38.1-5+deb12u2      │                   1 │ Unimportant    │
+╰─────────────┴───────────┴───────────────────────┴─────────────────────┴────────────────╯
+```
+
+</details>
+
+### Detailed Output:
+
+For a more detailed view of vulnerabilities, including individual **vulnerability details**, **base image identification**, and **layer specific filters**, use the HTML output format. You can enable it using:
+
+- `--format=html`: This will output the results to an HTML file.
+
+- `--serve`: This will generate an HTML report and host it locally on `localhost:8000`.
+
+See the [Output documentation](./output.md) for more information on output formats.
+
+**Sample HTML Output**:
+
+![Screenshot of HTML output for container image scanning](./images/html-container-output.png)
diff --git a/docs/scan-source.md b/docs/scan-source.md
@@ -0,0 +1,134 @@
+---
+layout: page
+title: Project Source Scanning
+parent: Usage
+permalink: /usage/scan-source
+nav_order: 2
+---
+
+# Source Scanning
+
+OSV-Scanner can be used to scan your project source and lockfiles to find vulnerabilities in your dependencies.
+
+```bash
+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:
+
+```bash
+osv-scanner <flags> [paths...]
+```
+
+## General use case: scanning a directory
+
+```bash
+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.
+
+Git directories are searched for the latest commit hash. Searching for git commit hash is intended to work with projects that use git submodules or a similar mechanism where dependencies are checked out as real git repositories.
+
+## Ignored files
+
+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](https://github.com/google/osv-scanner/issues/209) that the parser does not correctly respect repository boundaries.
+
+The `--no-ignore` flag can be used to force the scanner to scan ignored files.
+
+## Specify SBOM
+
+If you want to check for known vulnerabilities only in dependencies in your SBOM, you can use the following command:
+
+```bash
+osv-scanner scan source --sbom=/path/to/your/sbom.spdx.json
+```
+
+[SPDX] and [CycloneDX] SBOMs using [Package URLs] are supported. The format is
+auto-detected based on the input file contents and the file name.
+
+When scanning a directory, only SBOMs following the specification filename will be scanned. See the specs for [SPDX Filenames] and [CycloneDX Filenames].
+
+[SPDX]: https://spdx.dev/
+[SPDX Filenames]: https://spdx.github.io/spdx-spec/v2.3/conformance/
+[CycloneDX Filenames]: https://cyclonedx.org/specification/overview/#recognized-file-patterns
+[CycloneDX]: https://cyclonedx.org/
+[Package URLs]: https://github.com/package-url/purl-spec
+
+## Specify Lockfile(s)
+
+If you want to check for known vulnerabilities in specific lockfiles, you can use the following command:
+
+```bash
+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:
+
+```bash
+osv-scanner scan source --lockfile 'requirements.txt:/path/to/your/extra-requirements.txt'
+```
+
+The list of supported lockfile formats can be found [here](/osv-scanner/supported-languages-and-lockfiles/).
+
+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:
+
+```bash
+osv-scanner scan source --lockfile ':/path/to/my:projects/package-lock.json'
+```
+
+## Git Repository Scanning
+
+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](<supported_languages_and_lockfiles#C/C++ scanning>) for more details.
+
+## Scanning with call analysis
+
+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.
+
+### Call analysis in Go
+
+OSV-Scanner uses the [`govulncheck`](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) library to analyze Go source code to identify called vulnerable functions.
+
+#### Additional Dependencies
+
+`go` compiler needs to be installed and available on `PATH`.
+
+### Call analysis in Rust
+
+Experimental
+{: .label }
+
+Call analysis in Rust is still considered experimental.
+
+OSV-Scanner compiles Rust source code and analyzes the output binary's DWARF debug information to identify called vulnerable functions.
+
+#### Additional Dependencies
+
+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.
+
+### Limitations
+
+Current implementation has a few limitations:
+
+- Does not support dependencies on proc-macros (Tracked in [#464](https://github.com/google/osv-scanner/issues/464))
+- Does not support any dependencies that are dynamically linked
+- Does not support dependencies that link external non-rust code
+
+### Example
+
+```bash
+osv-scanner scan source --call-analysis=rust --no-call-analysis=go ./my/project/path
+```