@codacy/tools-trivy-0

Table of Contents

• Overview
• Umbrella patterns
• Issue parity with codacy-trivy
  • sourceId — why every issue carries its CVE
  • Scan flags that affect what is found
  • Line-number resolution
  • Fix version
  • Known divergences
• DB update management
• Malicious package detection
• Container image mode
• Updating patterns
• Updating the Trivy version
• Development
• Notes for maintainers

Overview

Security scanner using the Trivy binary. Scans for vulnerabilities in dependencies and hardcoded secrets. Uses the CLI execution strategy with two separate scan modes (vulnerability + secret).

Umbrella patterns

Trivy uses umbrella patterns rather than individual CVE patterns:

Issue parity with codacy-trivy

Codacy Cloud analyses repositories with the codacy-trivy Docker engine, so a repository scanned locally and uploaded must produce the same results as the same repository scanned on the cloud. Three pieces of this adapter exist only to hold that line; the reference implementation is codacy-trivy internal/tool/tool.go, and the ports live in src/vuln-mapping.ts (fallbackSearchForLineNumber, findLeastDisruptiveFixedVersion, purlPrettyPrint). Change them only alongside that file.

sourceId — why every issue carries its CVE

Codacy derives a result's deterministic UUID from an MD5 over four keys: filename, pattern id, the line's text with whitespace stripped, and sourceId (codacy-worker shared/rules/…/rules/components/ResultUUIDRules.scala).

Trivy reports many CVEs under one of four severity umbrella patterns, so two CVEs on the same lockfile line share three of those four keys. Without sourceId they collapse into a single Codacy result. Every issue this adapter produces therefore sets it:

src/metadata.ts sets needsSourceIdUpload: true, which is what makes upload include the field in the v2 payload (mirroring needs_source_id_upload in the Go CLI's Trivy plugin manifest). Adapters without the flag omit the field entirely — sending it where the cloud engine does not would give the same finding a different UUID.

Scan flags that affect what is found

The vulnerability scan passes --detection-priority comprehensive, matching codacy-trivy's DetectionPriority: PriorityComprehensive. It reports more vulnerabilities — some of which may be false positives — and it is required for Go standard-library findings: verified against trivy 0.70, a go.mod scan without it reports zero stdlib vulnerabilities (6 issues instead of 26 on a small go 1.20 module). Removing the flag would silently drop every stdlib finding and make the go.mod handling below dead code.

Line-number resolution

Trivy reports no line for a vulnerable dependency, so the line is reconstructed:

1. Look up the package's Locations[0].StartLine, keyed by PURL — the key the cloud engine uses. PkgID is a secondary key for the rare package Trivy reports without a PURL.
2. On a miss or a zero, scan the manifest top to bottom for the first line whose trimmed text contains the package name.
3. Still nothing ⇒ emit a file-level error (Line numbers not supported, deduplicated to one per file), not an issue on line 1. A confidently wrong location is worse than an honest "unknown"; codacy-trivy makes the same call via mapIssuesWithoutLineNumber.

go.mod standard library. Trivy reports standard-library vulnerabilities against a package named stdlib, which never literally appears in go.mod. Trivy documents using the minimum of the toolchain and go directives, but in practice always uses toolchain when it exists. So the scan returns the toolchain line as soon as it sees one, and only falls back to the go directive line after reading the whole file. This is not derivable from Trivy's docs — do not "simplify" it.

Fix version

Trivy's FixedVersion is a comma-separated list of every fixing version ("1.9.0, 1.10.0, 2.0.1"). The message reports only the least disruptive one: the smallest candidate strictly greater than the installed version, by semantic version. When no candidate is greater (or the scheme isn't semver — Ruby's ~>, Maven qualifiers), Trivy's raw value is passed through; when FixedVersion is empty the message reads (no fix available).

Message format, matching the cloud engine verbatim:

Insecure dependency {pretty-printed PURL} ({CVE}: {title}) (update to {version})
Insecure dependency {pretty-printed PURL} ({CVE}: {title}) (no fix available)

Comparison uses a port of Go's golang.org/x/mod/semver (compareSemver), not npm semver: it accepts two-component versions like v1.2, and treats an unparseable version as lower than any valid one, which is what makes non-semver schemes fall through instead of being ranked.

Known divergences

Both are deliberate; see docs/tech-debt.md.

• Fix-version ordering. codacy-trivy sorts the candidate strings before adding the v prefix, so x/mod/semver sees them all as invalid, compares them equal, and falls back to a lexicographic tiebreak — picking 1.10.0 over 1.9.0. We sort on the prefixed values and return the genuinely smallest.
• Packages without a PURL. codacy-trivy skips those vulnerabilities entirely. We keep them, resolving the line by name and rendering the package as name@version, because silently dropping a real vulnerability is worse than a message that differs from the cloud's.
• Secret message text. Ours appends the secret's category (Possible hardcoded secret: {title} ({category})); the cloud engine stops at the title.
• Offline scan. codacy-trivy sets OfflineScan: true (its container is air-gapped); we don't, so Trivy may resolve some Java/Maven dependencies over the network and report slightly more accurate results for those ecosystems. Not changed here: making local scans less accurate to match an air-gap constraint we don't have would be the wrong trade.

DB update management

The adapter reads Trivy's metadata.json (at {cacheDir}/db/metadata.json) to determine if the vulnerability database is still fresh. The NextUpdate field tells us when Trivy expects the next DB update.

Malicious package detection

Detects known malicious packages by querying the OSV.dev batch API. This piggybacks on the vulnerability scan output — the package list from --list-all-pkgs is extracted and cross-referenced against the OpenSSF malicious packages index (MAL-* IDs).

• Covers 14 ecosystems: npm, PyPI, Go, RubyGems, crates.io, NuGet, Maven, Packagist, Pub, Hex, ConanCenter, CocoaPods, SwiftURL, conda
• Uses a 10-second timeout per API call
• On API failure (network error, timeout), logs a warning and skips — never blocks the core scan
• Message format: Malicious package detected: {name}@{version} ({MAL-ID}). {summary}

Container image mode

Besides the repository scan, the adapter implements the optional containerImage capability (src/image.ts), which backs the CLI's container-scan and upload-sbom commands. The descriptor advertises it with scansContainerImages: true.

• The image reference is re-validated with validateImageReference right before it becomes an argv element, even though the runner validated it first.
• --exit-code is deliberately not passed. The finding count comes from the parsed JSON, so any non-zero exit is a real failure — no stderr heuristics like cli-v2's to decide whether it failed.
• Findings reuse describeVulnerability (src/findings.ts), the same mapping the repository scan uses: umbrella pattern by severity, codacy-trivy's message format, CVE as sourceId, UNKNOWN dropped. The location is Trivy's Target (the OS layer or an in-image manifest) at line 1.
• generateSbom succeeds only if Trivy exits 0 and wrote a non-empty file.
• Every Trivy spawn (both modes) sets TRIVY_SKIP_VERSION_CHECK=true, and a failure's stderr goes through summarizeTrivyStderr (src/trivy-errors.ts) rather than being echoed: Trivy's stderr is a log stream (INFO lines, an ANSI version notice, then a FATAL Go error-wrap chain), and the text formatter truncates errors at 240 characters, which used to cut it off before the cause. The env var rather than --skip-version-check, because an older global Trivy would reject the flag.
• test/fixtures/image-scan.json is trimmed from a real trivy image run against nginx:1.21.0-alpine, plus one synthetic UNKNOWN finding and one synthetic library finding. CODACY_TRIVY_IMAGE_IT=1 pnpm test runs the opt-in integration test against the real registry.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Updating the Trivy version

1. Update preferredVersion in src/metadata.ts
2. Update the download URL template if the release format changed
3. Run pnpm test to verify compatibility

Development

pnpm build    # Build with tsup
pnpm test     # Run tests (requires trivy in PATH or auto-install)

Notes for maintainers

• Trivy runs two separate scan invocations: one for vulnerabilities (--scanners vuln --detection-priority comprehensive) and one for secrets (--scanners secret). Malicious package detection piggybacks on the vuln scan output (no extra invocation). Which scans run depends on which umbrella patterns are enabled.

• The vulnerability database is downloaded lazily on first run to --cache-dir ~/.codacy/cache/trivy/. Internet access is required on first use. DB staleness is managed via metadata.json → NextUpdate.

• Trivy scans a directory, not a file list, and there is no include flag. Both scans keep the repository root as the target, so Target is repo-relative, and results are filtered to ctx.targetFiles afterwards. The secret scan also passes --skip-dirs for every directory with no target file beneath it (src/scan-scope.ts, computeSkipDirs). That is lossless, because a secret is reported on the file that holds it. Before this, analyzing one file walked the whole tree twice, node_modules included, which took minutes on a large repository. Pruning is off in two cases:

  • The vulnerability scan is never pruned. Its findings depend on files in other directories. A yarn workspace's member package.json files decide which yarn.lock entries are dev-only, so skipping packages/ made Trivy report dev dependencies' vulnerabilities.
  • No pruning when a local trivy.yaml is in use. A command-line --skip-dirs replaces the config's skip-dirs instead of adding to it, so the user's exclusions would stop applying.

  The scan also runs unpruned if the skip list would not fit on a Windows command line.

• The vulnerability scan (and the malicious-package check that reuses its package list) is skipped when every target file has a source-code or document extension (needsVulnScan). That list is a deny-list on purpose: an extension missing from it only costs speed, whereas a forgotten manifest name in an allow-list would silently drop findings. Never add data formats (.json, .yaml, .toml, .xml, .lock, .txt) to it.

• Target is normalized to forward slashes before it is matched against ctx.targetFiles, so a Windows-style path can never silently match nothing.

• The binary is downloaded from GitHub releases as a .tar.gz archive.

• Vulnerability severity (CRITICAL/HIGH/MEDIUM/LOW) maps to the corresponding umbrella pattern.

• Message format, line resolution and sourceId are all parity-critical — see Issue parity with codacy-trivy before touching them.

• A vulnerability whose line cannot be resolved becomes a file-level AnalysisError (kind: "LineNumbersNotSupported"), one per file, rather than an issue on line 1.

• Malicious package detection uses the OSV.dev batch API. On failure, it degrades gracefully (warning only).

• Config file: checks for trivy.yaml in the repo root.