Configuration file format

Each Lava project is defined by a configuration file (usually named lava.yaml) that defines the parameters of the security scan.

A Lava configuration file is a YAML document that supports environment variable substitution with ${ENVVAR_NAME} notation.

Example

A Lava configuration file is a YAML document as shown in the following example.

lava: v0.0.0
checktypes:
  - checktypes.json
targets:
  - identifier: .
    type: GitRepository
  - identifier: ${DOCKER_IMAGE}
    type: DockerImage
agent:
  parallel: 4
report:
  severity: high
  exclusions:
    - description: Ignore test certificates.
      summary: 'Secret Leaked in Git Repository'
      resource: '/testdata/certs/'
log: error

This help topic describes every configuration parameter in detail.

lava

The "lava" field describes the minimum required version of the Lava command. For instance,

lava: v0.0.0

Using a Lava command whose version is lower than the minimum version required by the configuration file returns an error.

This field is mandatory.

checktypes

The "checktypes" field contains a list of URLs that point to checktype catalogs.

If the URL omits the scheme, it is considered a file path relative to the current working directory of the Lava command. For instance,

checktypes:
  - checktypes.json

HTTP and HTTPS URLs are supported. For instance,

checktypes:
  - https://example.com/checktypes.json

At least one catalog must be specified.

targets

The "targets" field contains the list of targets to scan. Every target is defined by the following properties:

  • identifier: string that identifies the target. For instance, a path, a URL, a container image, etc. It is mandatory.
  • type: the asset type of the target. Valid values are "AWSAccount", "DockerImage", "GitRepository", "IP", "IPRange", "DomainName", "Hostname", "WebAddress" and "Path". It is mandatory.
  • options: map of target-specific options. These options are merged with the options coming from the checktype catalog.

For instance,

targets:
  - identifier: .
    type: GitRepository
    options:
      branch: master

At least one target must be specified.

agent

The "agent" field contains the configuration passed to the Vulcan agent that Lava runs internally. The agent accepts the following properties:

  • pullPolicy: policy used to decide when to pull a required container image. Valid values are "Always", "IfNotPresent" and "Never". If not specified, "IfNotPresent" is used.
  • parallel: maximum number of checks that can run in parallel. If not specified, this limit is set to one.
  • vars: map with the environment variables passed to the executed checktypes.
  • registries: configuration of the required container registries. It requires the following properties: "server", "username" and "password".

The sample below is a full agent configuration:

agent:
  pullPolicy: Always
  parallel: 4
  vars:
    DEBUG: true
  registries:
    - server: example.com
      username: user
      password: ${REGISTRY_PASSWORD}

It is important to note that Lava is able to use the credentials from the container runtime CLIs installed in the system. So, if these CLIs are already logged in, it is not necessary to configure the registry in the configuration file.

report

The "report" field describes how to report the findings. It supports the following properties.

  • severity: minimum severity required to exit with error. Valid values are "critical", "high", "medium", "low" and "info". If not specified, "high" is used.
  • show: minimum severity required to show a finding. Valid values are "critical", "high", "medium", "low" and "info". If not specified, the severity value is used.
  • format: output format. Valid values are "human" and "json". If not specified, "human" is used.
  • output: path of the output file. If not specified, stdout is used.
  • metrics: path of the file where the metrics report will be written. If not specified, then the metrics report is not generated. For more details, use "lava help metrics".
  • exclusions: list of rules that define what findings should be excluded from the report. It allows to ignore findings because of accepted risks, false positives, etc.
  • errorOnStaleExclusions: boolean specifying whether Lava should exit with error when stale exclusions are detected. If not specified, the default value is false.

The sample below is a full report configuration:

report:
  severity: high
  show: low
  format: json
  output: findings.json
  metrics: metrics.json
  exclusions:
    - description: Ignore test certificates.
      summary: 'Secret Leaked in Git Repository'
      resource: '/testdata/certs/'
  errorOnStaleExclusions: true

The exclusion rules support the following filters:

  • target: regular expression that matches the name of the affected target.
  • resource: regular expression that matches the name of the affected resource.
  • fingerprint: context in where the vulnerability has been found.
  • summary: regular expression that matches the summary of the vulnerability.
  • expiration: is the date on which the exclusion becomes inactive. The format is YYYY/MM/DD.

A finding is excluded if it matches all the filters of an exclusion rule.

It is possible to provide a human-friendly description of an exclusion rule using its "description" property.

log

The "log" field describes the logging level of the Lava command. Valid values are "debug", "info", "warn" and "error". If not specified, "info" is used. For instance,

log: error