How to Configure Trivy with a Config File Instead of Command-Line Flags

You can configure Trivy using a YAML configuration file (default trivy.yaml) by using the --config flag, which leverages the Viper library to load settings before any subcommands execute, allowing you to replace repetitive CLI flags with a single maintainable file.

The aquasecurity/trivy repository supports declarative configuration through YAML files, eliminating the need to pass long flag strings for every scan. This approach centralizes your scanning policies and makes CI/CD pipelines easier to maintain.

How Trivy Loads Configuration Files

Trivy’s configuration system is built on top of the Viper library, which handles file discovery, parsing, and merging with default values.

The Initialization Flow

When the CLI starts, Trivy executes a specific sequence to load your configuration:

1. Flag Registration – The --config (or -c) flag is defined in pkg/flag/global_flags.go as ConfigFileFlag [source]. This flag accepts the path to your configuration file.

2. Viper Initialization – In pkg/commands/app.go, the initConfig function initializes Viper and calls viper.SetConfigFile(configFile) to specify which file to read [source].

3. Value Merging – Viper loads the file and merges its values with built-in defaults. All command-line flags are subsequently bound to the same Viper instance, ensuring that flags override file values when conflicts occur.

If the file cannot be opened or parsed, initConfig returns an error such as “config file X loading error: …” [source].

Creating and Using a Trivy Config File

Default File Location and Discovery

By default, Trivy looks for a file named trivy.yaml in the current working directory. If present, Trivy automatically loads it without requiring the --config flag. The file must contain valid YAML that conforms to the JSON schema stored in schema/trivy-config.json [source].

Generating a Starter Config File

Trivy includes a built-in helper to generate a default configuration file. The implementation resides in pkg/commands/artifact/run.go, which handles the --generate-default-config flag [source].

Run the following command to create trivy-default.yaml in your current directory:

trivy config init

Rename the file if you prefer the standard name:

mv trivy-default.yaml trivy.yaml

Custom Config File Paths

To use a config file located elsewhere, specify the path with the --config flag:

trivy --config /etc/trivy/custom.yaml fs /my/project

You can also use the short form:

trivy -c /etc/trivy/custom.yaml image nginx:latest

Trivy Configuration File Structure

The configuration file supports all global options and subcommand-specific settings. Here is a minimal example that configures severity levels, enables specific scanners, and sets registry credentials:

# trivy.yaml

# Global options

severity: "HIGH,CRITICAL"
ignore-unfixed: true

# Scanners you want to enable (comma-separated or list)

scanners:
  - vuln
  - secret
  - config

# Registry credentials (optional)

registry:
  username: myuser
  password: mypass

After creating this file in your working directory, run Trivy normally:

trivy image nginx:latest

Overriding Config File Values with CLI Flags

Command-line flags take precedence over configuration file values. This allows you to maintain baseline settings in trivy.yaml while overriding specific options for individual runs.

For example, to use your config file but change the severity threshold for a single scan:

trivy --config ./trivy.yaml --severity MEDIUM,LOW image alpine:3.12

Viper processes the file first, then applies the flag value, ensuring the CLI input wins.

Summary

• Trivy uses Viper to load YAML configuration files via the --config flag, defined in pkg/flag/global_flags.go and initialized in pkg/commands/app.go.
• Default location is trivy.yaml in the current directory; custom paths require the --config flag.
• Validation follows the JSON schema in schema/trivy-config.json.
• Generation of starter files is available via trivy config init (implemented in pkg/commands/artifact/run.go).
• CLI flags override file settings, allowing flexible per-run adjustments while maintaining baseline configurations.

Frequently Asked Questions

What is the default name for the Trivy config file?

Trivy automatically looks for a file named trivy.yaml in the current working directory. If this file exists, Trivy loads it automatically without requiring the --config flag.

Does Trivy support config file formats other than YAML?

According to the source code in pkg/commands/app.go and the schema location at schema/trivy-config.json, Trivy specifically expects YAML format. While Viper supports multiple formats, Trivy’s implementation explicitly configures YAML parsing for configuration files.

How do I validate my Trivy configuration file?

Trivy validates configuration against the JSON schema located at schema/trivy-config.json in the repository. If your file contains invalid YAML or unsupported keys, the initConfig function in pkg/commands/app.go returns a loading error with specific details about the parsing failure.

Will command-line flags override settings in the config file?

Yes. Trivy binds all flags to the same Viper instance after loading the configuration file. This means any flag you pass on the command line will override the corresponding value in your trivy.yaml file, allowing you to keep default settings while making exceptions for specific scans.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}