mirror of
https://github.com/anchore/grype
synced 2024-11-10 06:34:13 +00:00
Update high level docs (#162)
* move dev section to separate doc; generally update readme Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * remove line breaks from docs Signed-off-by: Alex Goodman <alex.goodman@anchore.com>
This commit is contained in:
Alex Goodman
GitHub
parent
ed9f9bcb2b
commit
b2715ffdba
2 changed files with 97 additions and 85 deletions
65
DEVELOPING.md
Normal file
65
DEVELOPING.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
# Developing
|
||||
|
||||
There are a few useful things to know before diving into the codebase. This project depends on a few things being available like a vulnerability database, which you might want to create manually instead of retrieving a released version.
|
||||
|
||||
## Getting started
|
||||
|
||||
After cloning do the following:
|
||||
1. run `make bootstrap` to download go mod dependencies, create the `/.tmp` dir, and download helper utilities.
|
||||
2. run `make` to run linting, tests, and other verifications to make certain everything is working alright.
|
||||
|
||||
Checkout `make help` to see what other actions you can take.
|
||||
|
||||
## Inspecting the database
|
||||
|
||||
The currently supported database format is Sqlite3. Install `sqlite3` in your system and ensure that the `sqlite3` executable is available in your path. Ask `grype` about the location of the database, which will be different depending on the operating system:
|
||||
|
||||
```
|
||||
$ go run main.go db status
|
||||
Location: /Users/alfredo/Library/Caches/grype/db
|
||||
Built: 2020-07-31 08:18:29 +0000 UTC
|
||||
Current DB Version: 1
|
||||
Require DB Version: 1
|
||||
Status: Valid
|
||||
```
|
||||
|
||||
The database is located within the XDG_CACHE_HOME path. To verify the database filename, list that path:
|
||||
|
||||
```
|
||||
# OSX-specific path
|
||||
$ ls -alh /Users/alfredo/Library/Caches/grype/db
|
||||
total 445392
|
||||
drwxr-xr-x 4 alfredo staff 128B Jul 31 09:27 .
|
||||
drwxr-xr-x 3 alfredo staff 96B Jul 31 09:27 ..
|
||||
-rw------- 1 alfredo staff 139B Jul 31 09:27 metadata.json
|
||||
-rw-r--r-- 1 alfredo staff 217M Jul 31 09:27 vulnerability.db
|
||||
```
|
||||
|
||||
Next, open the `vulnerability.db` with `sqlite3`:
|
||||
|
||||
```
|
||||
$ sqlite3 /Users/alfredo/Library/Caches/grype/db/vulnerability.db
|
||||
```
|
||||
|
||||
To make the reporting from Sqlite3 easier to read, enable the following:
|
||||
|
||||
```
|
||||
sqlite> .mode column
|
||||
sqlite> .headers on
|
||||
```
|
||||
|
||||
List the tables:
|
||||
|
||||
```
|
||||
sqlite> .tables
|
||||
id vulnerability vulnerability_metadata
|
||||
```
|
||||
|
||||
In this example you retrieve a specific vulnerability from the `nvd` namespace:
|
||||
|
||||
```
|
||||
sqlite> select * from vulnerability where (namespace="nvd" and package_name="libvncserver") limit 1;
|
||||
id record_source package_name namespace version_constraint version_format cpes proxy_vulnerabilities
|
||||
------------- ------------- ------------ ---------- ------------------ -------------- ----------------------------------------------------------- ---------------------
|
||||
CVE-2006-2450 libvncserver nvd = 0.7.1 unknown ["cpe:2.3:a:libvncserver:libvncserver:0.7.1:*:*:*:*:*:*:*"] []
|
||||
```
|
||||
117
README.md
117
README.md
|
|
@ -89,6 +89,18 @@ You may experience a "macOS cannot verify app is free from malware" error upon r
|
|||
xattr -rd com.apple.quarantine grype
|
||||
```
|
||||
|
||||
## Shell Completion
|
||||
|
||||
Grype supplies shell completion through it's CLI implementation ([cobra](https://github.com/spf13/cobra/blob/master/shell_completions.md)).
|
||||
Generate the completion code for your shell by running one of the following commands:
|
||||
* `grype completion <bash|fish>`
|
||||
* `go run main.go completion <bash|fish>`
|
||||
|
||||
This will output a shell script to STDOUT, which can then be used as a completion script for Grype. Running one of the above commands with the
|
||||
`-h` or `--help` flags will provide instructions on how to do that for your chosen shell.
|
||||
|
||||
Note: [Cobra hs not yet released full ZSH support](https://github.com/spf13/cobra/issues/1226), but as soon as that gets released, we will add it here!
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration search paths:
|
||||
|
|
@ -101,7 +113,14 @@ Configuration search paths:
|
|||
Configuration options (example values are the default):
|
||||
|
||||
```yaml
|
||||
# same as -o ; the output format of the vulnerability report (options: table, json)
|
||||
# enable/disable checking for application updates on startup
|
||||
check-for-app-update: true
|
||||
|
||||
# same as --fail-on ; upon scanning, if a severity is found at or above the given severity then the return code will be 1
|
||||
# default is unset which will skip this validation (options: negligible, low, medium, high, critical)
|
||||
fail-on-severity: ''
|
||||
|
||||
# same as -o ; the output format of the vulnerability report (options: table, json, cyclonedx)
|
||||
output: "table"
|
||||
|
||||
# same as -s ; the search space to look for packages (options: all-layers, squashed)
|
||||
|
|
@ -110,103 +129,31 @@ scope: "squashed"
|
|||
# same as -q ; suppress all output (except for the vulnerability list)
|
||||
quiet: false
|
||||
|
||||
log:
|
||||
# use structured logging
|
||||
structured: false
|
||||
|
||||
# the log level; note: detailed logging suppress the ETUI
|
||||
level: "error"
|
||||
|
||||
# location to write the log file (default is not to have a log file)
|
||||
file: ""
|
||||
|
||||
# enable/disable checking for application updates on startup
|
||||
check-for-app-update: true
|
||||
|
||||
db:
|
||||
# check for database updates on execution
|
||||
auto-update: true
|
||||
|
||||
# location to write the vulnerability database cache
|
||||
cache-dir: "$XDG_CACHE_HOME/grype/db"
|
||||
|
||||
# URL of the vulnerability database
|
||||
update-url: "https://toolbox-data.anchore.io/grype/databases/listing.json"
|
||||
|
||||
# check for database updates on execution
|
||||
auto-update: true
|
||||
log:
|
||||
# location to write the log file (default is not to have a log file)
|
||||
file: ""
|
||||
|
||||
# the log level; note: detailed logging suppress the ETUI
|
||||
level: "error"
|
||||
|
||||
# use structured logging
|
||||
structured: false
|
||||
```
|
||||
|
||||
## Developing
|
||||
|
||||
There are a few useful things to know before diving into the codebase. This project depends on a few things being available like a vulnerability database, which you might want to create manually instead of retrieving a released version.
|
||||
|
||||
### Inspecting the database
|
||||
|
||||
The currently supported database provider is Sqlite3. Install `sqlite3` in your system and ensure that the `sqlite3` executable is available in your path. Ask `grype` about the location of the database, which will be different depending on the operating system:
|
||||
|
||||
```
|
||||
$ go run main.go db status
|
||||
Location: /Users/alfredo/Library/Caches/grype/db
|
||||
Built: 2020-07-31 08:18:29 +0000 UTC
|
||||
Current DB Version: 1
|
||||
Require DB Version: 1
|
||||
Status: Valid
|
||||
```
|
||||
|
||||
In this case (OSX), the database is located in the user's home directory. To verify the database filename, list that path:
|
||||
|
||||
```
|
||||
$ ls -alh /Users/alfredo/Library/Caches/grype/db
|
||||
total 445392
|
||||
drwxr-xr-x 4 alfredo staff 128B Jul 31 09:27 .
|
||||
drwxr-xr-x 3 alfredo staff 96B Jul 31 09:27 ..
|
||||
-rw------- 1 alfredo staff 139B Jul 31 09:27 metadata.json
|
||||
-rw-r--r-- 1 alfredo staff 217M Jul 31 09:27 vulnerability.db
|
||||
```
|
||||
|
||||
Next, open the `vulnerability.db` with `sqlite3`:
|
||||
|
||||
```
|
||||
$ sqlite3 /Users/alfredo/Library/Caches/grype/db/vulnerability.db
|
||||
```
|
||||
|
||||
To make the reporting from Sqlite3 easier to read, enable the following:
|
||||
|
||||
```
|
||||
sqlite> .mode column
|
||||
sqlite> .headers on
|
||||
```
|
||||
|
||||
List the tables:
|
||||
|
||||
```
|
||||
sqlite> .tables
|
||||
id vulnerability vulnerability_metadata
|
||||
```
|
||||
|
||||
In this example you retrieve a specific vulnerability from the `nvd` namespace:
|
||||
|
||||
```
|
||||
sqlite> select * from vulnerability where (namespace="nvd" and package_name="libvncserver") limit 1;
|
||||
id record_source package_name namespace version_constraint version_format cpes proxy_vulnerabilities
|
||||
------------- ------------- ------------ ---------- ------------------ -------------- ----------------------------------------------------------- ---------------------
|
||||
CVE-2006-2450 libvncserver nvd = 0.7.1 unknown ["cpe:2.3:a:libvncserver:libvncserver:0.7.1:*:*:*:*:*:*:*"] []
|
||||
```
|
||||
|
||||
## Shell Completion
|
||||
Grype supplies shell completion through it's CLI implementation ([cobra](https://github.com/spf13/cobra/blob/master/shell_completions.md)).
|
||||
Generate the completion code for your shell by running one of the following commands:
|
||||
* `grype completion <bash|fish>`
|
||||
* `go run main.go completion <bash|fish>`
|
||||
|
||||
This will output a shell script to STDOUT, which can then be used as a completion script for Grype. Running one of the above commands with the
|
||||
`-h` or `--help` flags will provide instructions on how to do that for your chosen shell.
|
||||
|
||||
Note: [Cobra hs not yet released full ZSH support](https://github.com/spf13/cobra/issues/1226), but as soon as that gets released, we will add it here!
|
||||
|
||||
## Future plans
|
||||
|
||||
The following areas of potential development are currently being investigated:
|
||||
|
||||
- Add CycloneDX to list of output formats
|
||||
- Support for allowlist, package mapping
|
||||
- Establish a stable interchange format w/Syft
|
||||
- Accept SBOM (CycloneDX, Syft) as input instead of image/directory
|
||||
|
|
|
|||
Loading…
Reference in a new issue