Documentation menu

📎 Unreleased docs. This is the next version (from main), features here may change or not be in a release yet.See the latest release →

Scanners

trivy-fs

On this page
  • Control: sca
  • Tool: Aqua Trivy (filesystem mode), https://trivy.dev
  • Status: ✅ implemented (dependency vulnerabilities)
  • Target: source repository (RepositoryTarget), checked out at the scanned revision
  • License / terms: Apache-2.0 (permissive). Run via exec. Vulnerability DB has separate terms (see the Trivy scanner doc).

What it does

Checks out the component's repository, then runs trivy fs --debug --scanners vuln --format json --list-all-pkgs --offline-scan <dir> to find known vulnerabilities in the project's dependencies (Software Composition Analysis), and converts the result to SARIF. Trivy's JSON names the package as a field, where its SARIF names it only in prose, and --list-all-pkgs records the line of each package's entry in its manifest. --debug keeps the log line naming a dependency file Trivy failed to parse, which Draugr reports as unread with the parser's error; the JSON is the same either way. See the SCA glossary entry.

Saga options

config:
  controls:
    sca:
      trivyFs:
        pkgTypes: [library]                          # skip the OS layer
        dbRepository: [registry.internal/trivy-db:2] # an internal mirror
        filePatterns: ["pip:requirements-.*\\.txt"]  # more files for the pip analyzer
        detectionPriority: comprehensive             # read >=1.2 as 1.2
        resolveMaven: true                           # fetch each dependency's pom from Maven Central
OptionWhat it does
pkgTypesWhich package types to analyze: os, library, or both (--pkg-types). Narrow it when the OS layer is a platform team's responsibility.
dbRepositoryOCI repositories to pull the vulnerability database from, in priority order (--db-repository). For runners with no route to a public registry.
filePatternsMore files for an analyzer to read, each analyzer:regex (--file-patterns, once per entry). Trivy's pip analyzer reads only requirements.txt; the example adds files named requirements-<something>.txt. draugr init writes the patterns for the requirements files it finds.
detectionPriorityprecise, the default, reads pinned versions only. comprehensive also reads a range such as >=1.2 in requirements.txt as its minimum version, and reports Go standard-library vulnerabilities (--detection-priority).
resolveMaventrue resolves a pom.xml's transitive dependencies by fetching each dependency's pom from Maven Central and the repositories the pom names, which declares the disclosure effect for the job (see What is sent). false, the default, passes --offline-scan. Ignored with --offline.
includeDevDepsDeprecated. Read as config.controls.sca.devDependencies, true as report and false as suppress, with a warning.

pkgTypes and dbRepository also apply to the trivy image scanner. The rest decide which of a checkout's dependencies are read, and belong to trivy-fs only.

Development dependencies are read on every run. Trivy marks each one Dev in its JSON, and each finding about it carries dev on its package. A lockfile holding only development dependencies counts as read. Development dependencies says which lockfiles carry the mark, how other scanners take it, and which setting decides whether those findings count.

Trivy's --severity and --ignorefile are deliberately absent: both drop findings inside the tool, where a suppression cannot be recorded or reviewed. Use config.exclude instead.

Notes

  • Integration mode: exec over a local checkout; Trivy + git must be on PATH.
  • License findings come from trivy-license, a separate scanner serving the licenses control, which has its own policy and its own gate threshold.
  • Each lang-pkgs result in Trivy's JSON names a file it took packages from. Those are the files the report counts as read; every other dependency file in the checkout is listed as unread, see sca.
  • A pom.xml whose dependency versions or transitive dependencies Trivy did not resolve is listed as read in part, see sca.

Data

The vulnerability database, from mirror.gcr.io and ghcr.io, which are Trivy's own defaults in that order. Warmed once per run. With --offline, Draugr passes --skip-db-update.

Every run passes --offline-scan, which stops Trivy resolving a pom.xml against remote Maven repositories. Trivy reads the dependencies the pom declares, and the dependencies of each one whose pom is in the local Maven repository (~/.m2/repository, or the one settings.xml names). Without the flag Trivy fetches the pom of every declared and transitive dependency, and of each parent pom, from Maven Central and the repositories the pom and settings.xml name. resolveMaven turns resolution on for trivy-fs alone. Maven Central rate-limits repeated lookups from one address, and every Trivy scanner of a run repeats them.

Every run, and the database warm, passes --skip-version-check and --disable-telemetry, so Trivy makes no version-check or telemetry request to check.trivy.dev. A Trivy older than 0.63.0 has neither flag and makes no such request.

config.controls.sca.trivyFs.dbRepository replaces both database hosts with an internal mirror.

What is sent

With resolveMaven: true, and only then, Trivy requests <group path>/<artifact>/<version>/<artifact>-<version>.pom for each dependency it resolves and each parent pom, internal artifacts included. It asks the repositories settings.xml names, then those the pom names, then repo.maven.apache.org, each through any mirror settings.xml sets, and stops at the first that has the pom; an artifact found nowhere has been asked of all of them. Each request carries the scanning machine's address. No source code, file content or path leaves the machine.

Maven Central is operated by Sonatype under the Central Repository Terms of Service. A repository your own pom names is governed by your agreement with its operator.

Effects

disclosurewith resolveMaven: true, sends the coordinates described above to Maven Central and the repositories the pom names

Declared for a job whose block sets resolveMaven: true and for no other. draugr controls lists it with the option, the MCP server asks before a scan that has it, and the report records it. disclosure needs no entry in config.allowEffects.