run

Documentation

Overview

Package run implements the run command.

Index

• Variables

Variables

var CmdRun = &base.Command{
	UsageLine: "run [flags] checktype target",
	Short:     "run scan",
	Long: `
Run a checktype against a target.

Run accepts two arguments: the checktype to run and the target of the
scan. The checktype is a container image reference (e.g.
"vulcansec/vulcan-trivy:edge") or a path pointing to a directory with
the source code of a checktype. The target is any of the targets
supported by the -type flag.

The -type flag determines the type of the provided target. Valid
values are "AWSAccount", "DockerImage", "GitRepository", "IP",
"IPRange", "DomainName", "Hostname", "WebAddress" and "Path". If not
specified, "Path" is used. For more details, use "lava help
lava.yaml".

The -timeout flag sets the timeout of the checktype execution. This
flag accepts a value acceptable to time.ParseDuration. If not
specified, "600s" is used.

The -opt and -optfile flags specify the checktype options. The -opt
flag accepts a string with the options. The -optfile flag accepts a
path to an options file. The options must be provided in JSON format
and follow the checktype manifest.

The -var flag sets the environment variables passed to the
checktype. The environment variables must be provided using the format
"name[=value]". If there is no equal sign, the value of the variable
is got from the environment. This flag can be specified multiple
times.

The -pull flag determines the pull policy for container images. Valid
values are "Always" (always download the image), "IfNotPresent" (pull
the image if it not present in the local cache) and "Never" (never
pull the image). If not specified, "IfNotPresent" is used. If the
checktype is a path, only "IfNotPresent" and "Never" are allowed.

The -registry flag specifies the container registry. If the registry
requires authentication, the credentials are provided using the -user
flag. The -user flag accepts the credentials with the format
"username[:[password]]". The username and password are split around
the first instance of the colon. So the username cannot contain a
colon. If there is no colon, the password is read from the standard
input.

The -severity flag determines the minimum severity required to report
a finding. Valid values are "critical", "high", "medium", "low" and
"info". If not specified, "high" is used.

The -o flag specifies the output file to write the results of the
scan. If not specified, the standard output is used. The format of the
output is defined by the -fmt flag. The -fmt flag accepts the values
"human" for human-readable output and "json" for JSON-encoded
output. If not specified, "human" is used.

The -metrics flag specifies the file to write the security,
operational and configuration metrics of the scan. For more details,
use "lava help metrics".

The -log flag defines the logging level. Valid values are "debug",
"info", "warn" and "error". If not specified, "info" is used.

# Path checktype

When the specified checktype is a path that points to a directory,
Lava assumes that the directory contains the source code of the
checktype.

The directory must contains at least the following files:

  - Dockerfile
  - Go source code (*.go)

Lava will build the Go source code and then it will create a Docker
image based on the Dockerfile file found in the directory. The
reference of the generated image has the format "name:lava-run". Where
name is the name of the directory pointed by the specified path. If
the path is "/", the string "lava-checktype" is used. If the path is
".", the name of the current directory is used.

Thus, the following command:

	lava run /path/to/vulcan-trivy .

would generate a Docker image with the reference
"vulcan-trivy:lava-run".

Finally, the generated Docker image is used as checktype to run a scan
against the provided target with the specified options.

This mode requires a working Go toolchain in PATH.

# Examples

Run the checktype "vulcansec/vulcan-trivy:edge" against the current
directory:

	lava run vulcansec/vulcan-trivy:edge .

Run the checktype "vulcansec/vulcan-trivy:edge" against the current
directory with the options stored in the "options.json" file:

	lava run -optfile=options.json vulcansec/vulcan-trivy:edge .

Build and run the checktype in the path "/path/to/vulcan-trivy"
against the current directory:

	lava run /path/to/vulcan-trivy .

Run the checktype "vulcansec/vulcan-nuclei:edge" against the remote
"WebAddress" target "https://example.com":

	lava run -type=WebAddress vulcansec/vulcan-nuclei:edge https://example.com

Run the checktype "vulcansec/vulcan-nuclei:edge" against the local
"WebAddress" target "http://localhost:1234". Write the results in JSON
format to the "output.json" file. Also write security, operational and
configuration metrics to the "metrics.json" file:

	lava run -o output.json -fmt=json -metrics=metrics.json \
	         -type=WebAddress vulcansec/vulcan-nuclei:edge http://localhost:1234
	`}

CmdRun represents the run command.