Configuration

Grype is configured through a layered system provided by anchore/clio + anchore/fangs. Sources, in priority order:

1. CLI flags (highest priority).
2. Environment variables (GRYPE_*).
3. Config file (-c <path>, otherwise default search).
4. Defaults from cmd/grype/cli/options/grype.go::DefaultGrype.

Default config search

If -c is not given, Grype searches:

1. ./.grype.yaml, ./.grype/config.yaml
2. ~/.grype.yaml, ~/.grype/config.yaml
3. /etc/grype/config.yaml

The first match wins. Use grype config to print the resolved configuration.

Top-level config keys

The full shape lives in cmd/grype/cli/options/, but the high-frequency ones are:

output: ['table'] # one or more output formats
file: '' # write primary output to a file
distro: '' # override detected distro
add-cpes-if-none: false # synthesize CPEs for packages without one
by-cve: false # normalize advisory IDs to CVEs
fail-on: '' # severity threshold (low/medium/high/critical)
default-image-pull-source: '' # docker, podman, registry, ...
exclude: [] # paths to skip during cataloging
match-upstream-kernel-headers: false
ignore-states: '' # comma-separated fix states to ignore

db:
  cache-dir: '' # default: ~/.cache/grype/db
  update-url: '' # default: https://grype.anchore.io/databases/v6/listing.json
  ca-cert: ''
  auto-update: true
  validate-by-hash-on-start: false
  require-update-check: true # treat update failure as fatal
  max-allowed-built-age: 120h # warn or fail if DB is older

ignore:
  - vulnerability: CVE-...

vex-documents: []
vex-add: [] # statuses (e.g. affected) to add when augmenting

registry:
  insecure-skip-tls-verify: false
  auth: []

log:
  quiet: false
  verbosity: 0 # 0 info, 1 debug, 2 trace
  file: ''
  structured: false

check-for-app-update: true
only-fixed: false
only-not-fixed: false
platform: ''
show-suppressed: false
pretty: false
exp:
  alerts:
    enable-eol-distro-warnings: false

The complete authoritative list comes from running grype config against an installed binary.

Environment variables

Every YAML key has a corresponding GRYPE_* env var with dots replaced by underscores and uppercased. Examples:

Env	YAML
GRYPE_DB_AUTO_UPDATE	db.auto-update
GRYPE_DB_CACHE_DIR	db.cache-dir
GRYPE_LOG_LEVEL (alias)	log.verbosity
GRYPE_OUTPUT	output
GRYPE_FAIL_ON	fail-on
GRYPE_BY_CVE	by-cve
GRYPE_PLATFORM	platform
GRYPE_CHECK_FOR_APP_UPDATE	check-for-app-update

The Taskfile sets GRYPE_CHECK_FOR_APP_UPDATE=false for local development to avoid the version-check overhead.

CLI flags vs YAML keys

The CLI flags are generated from the same option struct via cobra + fangs. There is one flag per leaf YAML key. grype --help is the easiest way to see the current flag list for any subcommand.

Per-subcommand options

Each subcommand has its own option struct in cmd/grype/cli/options/:

Struct	Subcommand
Grype	root scan
Database	shared db flags
DatabaseSearchVulnerabilities	db search vuln
DatabaseSearchPackages	db search package
DatabaseSearchOS	db search os
Match	the matcher config (Java, Python, etc.)
Registry	image registry auth
Secret	secret detection (Syft passthrough)

Layered config precedence

For a single key:

1. If a CLI flag was given, use it.
2. Else if a GRYPE_* env var is set, use it.
3. Else if the resolved config file has the key, use it.
4. Else use the default from Default*.

The clio framework handles the merging.