Docker

This repository includes a Dockerfile that makes it easy to build and quickly get started with CVEScan. The resulting image exposes the cvescan CLI, which can be used interactively or to run any subcommand, including a CVEScan runner.

Image Build

Docker, with BuildKit enable is needed for this step

At the root of the repository, run the following command:

docker build -t cvescan -f ./docker/Dockerfile .

This will build the CVEScan image.

Warning

For compatibility with microprocessors not supporting Advanced Vector Extensions (AVX) add the --build-arg LTS_CPU=1 to you docker build command.

Usage

The base invocation is:

docker run \
    --rm \
    -v "$CVESCAN_WORKDIR:/home/user/workdir" \
    -v "$CVESCAN_SOURCES:/home/user/.local/share/cvescan" \
    -v "$CVESCAN_CACHE:/home/user/.cache/cvescan" \
    -v $SSH_AUTH_SOCK:${SSH_AUTH_SOCK} -e SSH_AUTH_SOCK=${SSH_AUTH_SOCK} \
    -e uid=$(id -u) \
    -e gid=$(id -g) \
    -it \
    cvescan \
    <trailing command>

Note

The cvescan on its own line is the image name (built earlier with docker build -t cvescan ...) and tells Docker which image to start. The trailing command on the next line is what runs inside the container, and it usually starts with cvescan itself (the CLI), so having the word twice is normal.

CVESCAN_WORKDIR needs to be set to an absolute path of a directory that will be shared with the container.
CVESCAN_SOURCES should be set to the directory which will contain the databases. If you already have them, the expected directory structure is as follows:
```
CVESCAN_SOURCES
    ├── linux
    ├── nvd
    └── uct
```
CVESCAN_CACHE should also be set to the directory which will contain CVEScan's cache. If you already have a cache, the expected directory structure is as follows:
```
CVESCAN_CACHE
    └── cache
```

IMPORTANT: Anything outside the above specified volumes will either not be accessible or not persisted.

The trailing command is what gets executed inside the container. The image does not set a default, so it must always be provided. Common choices:

Goal	Trailing command (and extra flags)
Run any `cvescan` subcommand	the subcommand itself, e.g. `cvescan datasources-update`, `cvescan run --inventory ...`
Open an interactive shell	`bash`
Serve the UI locally	`cvescan serve-ui --host 0.0.0.0`, plus `-p 8000:8000` on the docker flags
Run as a runner	`cvescan start-runner`, plus the runner configuration (typically passed as `-e CVESCAN_RUNNER_ENDPOINT=... -e CVESCAN_RUNNER_TOKEN=...`)

Note

To reach an API endpoint that is not resolvable via DNS from the container, add --add-host=<api-hostname>:<api-ip> to the docker flags.

For example, launching a runner looks like the below command. The runner needs to know which jobs API to contact and how to authenticate, which is passed in via the CVESCAN_RUNNER_ENDPOINT and CVESCAN_RUNNER_TOKEN environment variables (see the runner configuration for the full set of options):

docker run \
    --rm \
    -v "$CVESCAN_WORKDIR:/home/user/workdir" \
    -v "$CVESCAN_SOURCES:/home/user/.local/share/cvescan" \
    -v "$CVESCAN_CACHE:/home/user/.cache/cvescan" \
    -v $SSH_AUTH_SOCK:${SSH_AUTH_SOCK} -e SSH_AUTH_SOCK=${SSH_AUTH_SOCK} \
    -e uid=$(id -u) \
    -e gid=$(id -g) \
    -e CVESCAN_RUNNER_ENDPOINT=... \
    -e CVESCAN_RUNNER_TOKEN=... \
    cvescan \
    cvescan start-runner