Trivy Security Scan and Evidence Upload

Scan source code or built images and upload a bounded Trivy evidence report.

Reference: loha/trivy-scan@v2

Category: security

Runtime: aquasec/trivy:0.58.0 (non-root, digest-pinned)

License: Apache-2.0

When to use

Use this step for pipeline feedback and evidence collection. Run in fs mode against dependency lockfiles or in image mode after building. Workspace policy enforcement uses platform-managed scans and does not trust this task as managed custody.

Parameters

Parameter	Type	Default	Required	Description
SCAN_TYPE	enum: fs, image	fs	No	Scan type: fs (source filesystem) or image (container image reference).
SCAN_TARGET	string	.	No	Scan target. For fs mode: directory path relative to WORKING_DIRECTORY. For image mode: full image reference.
WORKING_DIRECTORY	string	.	No	Directory to run in, relative to workspace root. Use for monorepo subdirectories.
SCANNERS	enum: vuln,secret, vuln,secret,misconfig, vuln,secret,license, vuln,secret,misconfig,license	vuln,secret	No	Comma-separated Trivy scanners. vuln,secret is the default; add misconfig and/or license explicitly.

Workspaces

• source (required): bound from pipeline workspace source

Results

Result	Description
SCAN_RESULT	COMPLETED or ERROR
REPORT_ID	Accepted security report identifier
VULN_COUNT	Total vulnerability occurrences in the report
CRITICAL_COUNT	Number of CRITICAL vulnerabilities

How it works

Runs digest-pinned Trivy with all severities and the explicit SCANNERS selection, then uploads its raw JSON through a controller-issued, short-lived receipt. The receipt and collector URL are injected by Loha, are not task parameters, and the task cannot invent a report when they are absent. The collector validates and sanitizes the report before durable storage; secrets, source snippets, tokens, and receipt data are never printed. SCAN_RESULT means collection completed or errored; it is not a release gate. Evidence from this customer-controlled pipeline task is recorded as pipeline_uploaded, so it is useful for observation but never substitutes for Loha-managed custody in an enforced workspace policy.

Examples

Filesystem evidence scan of a monorepo app

steps:
  - name: scan-deps
    uses: loha/trivy-scan@v2
    with:
      SCAN_TYPE: 'fs'
      WORKING_DIRECTORY: 'apps/dashboard'
      SCANNERS: 'vuln,secret'

Image scan after a build

steps:
  - name: build
    uses: loha/buildah-build@v1
    with:
      IMAGE: 'registry.example.com/my-org/app:${COMMIT_SHA}'

  - name: scan-image
    uses: loha/trivy-scan@v2
    with:
      SCAN_TYPE: 'image'
      SCAN_TARGET: 'registry.example.com/my-org/app:${COMMIT_SHA}'
      SCANNERS: 'vuln,secret,misconfig'

Opt into configuration and license analysis

steps:
  - name: scan-deps
    uses: loha/trivy-scan@v2
    with:
      SCAN_TYPE: 'fs'
      SCANNERS: 'vuln,secret,misconfig,license'

Troubleshooting

Problem: The task returns SCAN_RESULT: ERROR.

Solution: A scanner error, unavailable vulnerability database, invalid report, missing Loha receipt, or rejected collector response cannot produce evidence. Fix the runtime or collector configuration and retry; do not treat ERROR as clean.

---

Problem: Database download error on first run.

Solution: Trivy needs to fetch its CVE DB. If your cluster blocks egress, pre-cache the DB or run an internal mirror. See Trivy docs for TRIVY_DB_REPOSITORY.

---

Problem: A workspace policy blocks a release despite this task completing.

Solution: This v2 task is pipeline-uploaded evidence. An enforced policy requires Loha-managed evidence and independently approved exceptions. Review the Build Security assessment rather than adding repository-controlled ignores.