Skip to content

Commit

Permalink
docs: improve triage documentation
Browse files Browse the repository at this point in the history
It is still possible to provide triage information through the `--input-file` parameter,
but since that is not usable with scan input from json or csv files the docs now emphasize
using the separate `--triage-input-file` parameter.

Towards intel#1747
  • Loading branch information
raboof committed Nov 9, 2022
1 parent 8b22d3b commit 90699ad
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 74 deletions.
10 changes: 10 additions & 0 deletions .github/actions/spelling/expect.txt
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,13 @@ rdf
sbom
spdx
swid
aiohttp
cdx
cwes
getbootstrap
GMS
NOTKNOWN
pyyaml
skontar
Svunknown
urllib
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,6 @@ To scan a comma-delimited (CSV) or JSON file which lists dependencies and versio
cve-bin-tool --input-file <filename>
```

Note that the `--input-file` option can also be used to add extra triage data like remarks, comments etc. while scanning a directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool -i=test.csv /path/to/scan`).
A VEX file (which may be created using the `--vex` command line option) can also be used as a triage file. A VEX file
is detected if the file suffix is '.vex'.

### Scanning an SBOM file for known vulnerabilities

To scan a software bill of materials file (SBOM):
Expand All @@ -94,6 +90,11 @@ cve-bin-tool --sbom <sbom_filetype> --sbom-file <sbom_filename>
Valid SBOM types are [SPDX](https://spdx.dev/specifications/),
[CycloneDX](https://cyclonedx.org/specification/overview/), and [SWID](https://csrc.nist.gov/projects/software-identification-swid/guidelines).

### Providing triage input

The `--triage-input-file` option can be used to add extra triage data like remarks, comments etc. while scanning a directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool --triage-input-file test.vex /path/to/scan`).
The supported format is the [CycloneDX](https://cyclonedx.org/capabilities/vex/) VEX format which can be generated using the `--vex` option.

### Using the tool offline

Specifying the `--offline` option when running a scan ensures that cve-bin-tool doesn't attempt to download the latest database files or to check for a newer version of the tool.
Expand All @@ -114,7 +115,7 @@ Note: Please don't use spaces between comma (',') and the output formats.

The reported vulnerabilities can additionally be reported in the
Vulnerability Exchange (VEX) format by specifying `--vex` command line option.
The generated VEX file can then be used as an `--input-file` to support
The generated VEX file can then be used as a `--triage-input-file` to support
a triage process.

If you wish to use PDF support, you will need to install the `reportlab`
Expand Down Expand Up @@ -400,11 +401,11 @@ with security issues that have been compiled into their binaries.

The tool does not guarantee that any vulnerabilities reported are actually present or exploitable, neither is it able to find all present vulnerabilities with a guarantee.

Users can add triage information to reports to mark issues as false positives, false negatives, indicate that the risk has been mitigated by configuration/usage changes, and so on.
Users can add triage information to reports to mark issues as false positives, indicate that the risk has been mitigated by configuration/usage changes, and so on.

Triage details can be re-used on other projects so, for example, triage on a Linux base image could be applied to multiple containers using that image.

For more information and usage of triage information with the tool kindly have a look [here](https://cve-bin-tool.readthedocs.io/en/latest/MANUAL.html#i-input-file-input-file-input-file).
For more information and usage of triage information with the tool kindly have a look [here](https://cve-bin-tool.readthedocs.io/en/latest/MANUAL.html#triage-input-file-input-file).

If you are using the binary scanner capabilities, be aware that we only have a limited number of binary checkers (see table above) so we can only detect those libraries. Contributions of new checkers are always welcome! You can also use an alternate way to detect components (for example, a bill of materials tool such as [tern](https://github.com/tern-tools/tern)) and then use the resulting list as input to cve-bin-tool to get a more comprehensive vulnerability list.

Expand Down
Loading

0 comments on commit 90699ad

Please sign in to comment.