From df94a25ac76db05e3b4118230b3a6a292ceec711 Mon Sep 17 00:00:00 2001 From: Hayley Denbraver Date: Thu, 23 Feb 2023 00:11:46 +0000 Subject: [PATCH] Moving Working Docs to Current (#234) You can preview the docs here: https://hayleycd.github.io/osv-scanner/ Updating docs for the new release. --- docs/current/output.md | 75 +++++++++++++++++++++++++++++++++++--- docs/current/usage.md | 70 +++++++++++++++++++++++------------ docs/working_docs/usage.md | 5 ++- 3 files changed, 120 insertions(+), 30 deletions(-) diff --git a/docs/current/output.md b/docs/current/output.md index 76b7f1f733..dc2954c14f 100644 --- a/docs/current/output.md +++ b/docs/current/output.md @@ -4,12 +4,75 @@ title: Output permalink: /output/ nav_order: 5 --- -## JSON output -By default osv-scanner outputs a human readable table. To have osv-scanner output JSON instead, pass the `--json` flag when calling osv-scanner. +## Output formats -When using the --json flag, only the JSON output will be printed to stdout, with all other outputs being directed to stderr. So to save only the json output to file, you can redirect the output with `osv-scanner --json ... > /path/to/file.json` +You can control the format used by the scanner to output results with the `--format` flag. -### Output Format +### Table (Default) + +The default format, which outputs the results as a human-readable table. + +```bash +osv-scanner --format table your/project/dir +``` + +
+Sample table output + +```bash +╭─────────────────────────────────────┬───────────┬──────────────────────────┬─────────┬────────────────────╮ +│ OSV URL (ID IN BOLD) │ ECOSYSTEM │ PACKAGE │ VERSION │ SOURCE │ +├─────────────────────────────────────┼───────────┼──────────────────────────┼─────────┼────────────────────┤ +│ https://osv.dev/GHSA-c3h9-896r-86jm │ Go │ github.com/gogo/protobuf │ 1.3.1 │ path/to/go.mod │ +│ https://osv.dev/GHSA-m5pq-gvj9-9vr8 │ crates.io │ regex │ 1.3.1 │ path/to/Cargo.lock │ +╰─────────────────────────────────────┴───────────┴──────────────────────────┴─────────┴────────────────────╯ +``` +
+ +--- + +### Markdown Table + +```bash +osv-scanner --format markdown your/project/dir +``` + +
+Sample markdown output + +**Raw output:** + +``` +| OSV URL | Ecosystem | Package | Version | Source | +| --- | --- | --- | --- | --- | +| https://osv.dev/GHSA-c3h9-896r-86jm
https://osv.dev/GO-2021-0053 | Go | github.com/gogo/protobuf | 1.3.1 | ../scorecard-check-osv-e2e/go.mod | +| https://osv.dev/GHSA-m5pq-gvj9-9vr8
https://osv.dev/RUSTSEC-2022-0013 | crates.io | regex | 1.5.1 | ../scorecard-check-osv-e2e/sub-rust-project/Cargo.lock | +``` + +**Rendered:** + +| OSV URL | Ecosystem | Package | Version | Source | +| --- | --- | --- | --- | --- | +| https://osv.dev/GHSA-c3h9-896r-86jm
https://osv.dev/GO-2021-0053 | Go | github.com/gogo/protobuf | 1.3.1 | ../scorecard-check-osv-e2e/go.mod | +| https://osv.dev/GHSA-m5pq-gvj9-9vr8
https://osv.dev/RUSTSEC-2022-0013 | crates.io | regex | 1.5.1 | ../scorecard-check-osv-e2e/sub-rust-project/Cargo.lock | + +
+ +--- + +### JSON + +```bash +osv-scanner --format json your/project/dir +``` + +Outputs the results as a JSON object to stdout, with all other output being directed to stderr - this makes it safe to redirect the output to a file with +```bash +osv-scanner --format json -L path/to/lockfile > /path/to/file.json +``` + +
+Sample JSON output ```json { @@ -98,4 +161,6 @@ When using the --json flag, only the JSON output will be printed to stdout, with } ] } -``` \ No newline at end of file +``` + +
\ No newline at end of file diff --git a/docs/current/usage.md b/docs/current/usage.md index ad2f34b7f1..442a090ad3 100644 --- a/docs/current/usage.md +++ b/docs/current/usage.md @@ -4,32 +4,38 @@ title: Usage permalink: /usage/ nav_order: 3 --- -OSV-Scanner collects a list of dependencies and versions that are used in your project, before matching this list against the OSV database via the [OSV.dev API](https://osv.dev#use-the-api). To build the list of dependencies, you can point OSV-Scanner at your project directory, or manually pass in the path to individual manifest files. +## Usage -### Scan a directory +OSV-Scanner parses lockfiles, SBOMs, and git directories to determine your project's open source dependencies. These dependencies are matched against the OSV database via the [OSV.dev API](https://osv.dev#use-the-api) and known vulnerabilities are returned to you in the output. -Walks through a list of directories to find: +### General use case: scanning a directory -- Lockfiles -- SBOMs -- git directories for the latest commit hash +```bash +osv-scanner -r /path/to/your/dir +``` -which is used to build the list of dependencies to be matched against OSV vulnerabilities. +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. -Can be configured to recursively walk through subdirectories with the `--recursive` / `-r` flag. +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. -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. +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. -#### Example +### 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 -r /path/to/your/dir +osv-scanner --sbom=/path/to/your/sbom.json ``` -### Input an SBOM - [SPDX] and [CycloneDX] SBOMs using [Package URLs] are supported. The format is auto-detected based on the input file contents. @@ -37,19 +43,25 @@ auto-detected based on the input file contents. [CycloneDX]: https://cyclonedx.org/ [Package URLs]: https://github.com/package-url/purl-spec -#### Example +### Specify Lockfile(s) +If you want to check for known vulnerabilities in specific lockfiles, you can use the following command: ```bash -osv-scanner --sbom=/path/to/your/sbom.json +osv-scanner --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/Cargo.lock ``` -### Input a lockfile +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 --lockfile 'requirements.txt:/path/to/your/extra-requirements.txt' +``` A wide range of lockfiles are supported by utilizing this [lockfile package](https://github.com/google/osv-scanner/tree/main/pkg/lockfile). This is the current list of supported lockfiles: - `buildscript-gradle.lockfile` - `Cargo.lock` - `composer.lock` +- `conan.lock` - `Gemfile.lock` - `go.mod` - `gradle.lockfile` @@ -63,16 +75,28 @@ A wide range of lockfiles are supported by utilizing this [lockfile package](htt - `pubspec.lock` - `requirements.txt`[\*](https://github.com/google/osv-scanner/issues/34) - `yarn.lock` -- `/lib/apk/db/installed` (Alpine) -#### Example +The scanner also supports: +- `installed` files used by the Alpine Package Keeper (apk) that typically live at `/lib/apk/db/installed` +- `status` files used by the Debian Package manager (dpkg) that typically live at `/var/lib/dpkg/status` + +however you must specify them explicitly using the `--lockfile` flag: ```bash -osv-scanner --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/Cargo.lock +osv-scanner --lockfile 'apk-installed:/lib/apk/db/installed' +osv-scanner --lockfile 'dpkg-status:/var/lib/dpkg/status' ``` -### Scanning a Debian based docker image packages (preview) +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 --lockfile ':/path/to/my:projects/package-lock.json' +``` +### Scanning a Debian based docker image packages +Preview +{: .label } This tool will scrape the list of installed packages in a Debian image and query for vulnerabilities on them. Currently only Debian based docker image scanning is supported. @@ -106,4 +130,4 @@ appropriate osv-scanner flags: ```bash docker run -it -v ${PWD}:/src ghcr.io/google/osv-scanner -L /src/go.mod -``` +``` \ No newline at end of file diff --git a/docs/working_docs/usage.md b/docs/working_docs/usage.md index 8b99aa1282..58d4008a03 100644 --- a/docs/working_docs/usage.md +++ b/docs/working_docs/usage.md @@ -99,8 +99,9 @@ it should infer the parser based on the filename: osv-scanner --lockfile ':/path/to/my:projects/package-lock.json' ``` -### Scanning a Debian based docker image packages (preview) - +### Scanning a Debian based docker image packages +Preview +{: .label } This tool will scrape the list of installed packages in a Debian image and query for vulnerabilities on them. Currently only Debian based docker image scanning is supported.