---
title: aquasecurity/trivy-action — GitHub Actions Official README
source_type: official-doc
url: https://github.com/aquasecurity/trivy-action
archive_url:
related_branches: [feature-dependency-vulnerability-management-contract]
related_projects: []
tags: [official-doc, ci-cd, docker, slsa]
created: 2026-06-15
---

# aquasecurity/trivy-action — GitHub Actions Official README

> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수, 최소 1개+)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-dependency-vulnerability-management-contract]] | D1/게이트 — Trivy를 GitHub Actions CI에서 release-blocking 게이트로 구성하는 방법(exit-code + severity 임계값), 그리고 suppression 파일(`trivyignores:`) 파라미터 |

## 출처 / Source

- 원본 URL: https://github.com/aquasecurity/trivy-action
- 아카이브 URL:
- 저자 / 조직: Aqua Security (aquasecurity)
- 발행일: (리포지터리 README, 지속 갱신 — 확인 시점 기준 v0.36.0)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

`aquasecurity/trivy-action` 의 공식 README 는 GitHub Actions CI 에서 `exit-code: '1'` + `severity: 'CRITICAL,HIGH'` 조합으로 취약점 발견 시 빌드를 실패시키는 release-blocking 게이트 구성의 **유일한 공식 출처**다. `trivyignores` 파라미터를 통한 suppression 파일 지정 방법도 동일 문서에서 확인 가능하므로 보관한다.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§Scan CI Pipeline / inputs table] `| \`exit-code\`                  | String  | \`0\`                                | Exit code when specified vulnerabilities are found                                                                                                               |`
> (inputs 표, line 877 of fetched README)

> [§Scan CI Pipeline — 예제 YAML, lines 57–60]
> ```yaml
>           exit-code: '1'
>           ignore-unfixed: true
>           vuln-type: 'os,library'
>           severity: 'CRITICAL,HIGH'
> ```

> [§Scan CI Pipeline (w/ Trivy Config) — fs 모드 예제, line 83]
> ```yaml
>         scan-type: 'fs'
>         scan-ref: '.'
>         trivy-config: trivy.yaml
> ```

> [§inputs table, line 889] `| \`trivyignores\`               | String  |                                    | comma-separated list of relative paths within the repository to one or more \`.trivyignore\` files, or a single \`.trivyignore.yaml\` file.                          |`

> [§Skipping Setup when Calling Trivy Action multiple times — 예제 YAML, lines 270–279]
> ```yaml
>       - name: Fail build on High/Criticial Vulnerabilities
>         uses: aquasecurity/trivy-action@v0.36.0
>         with:
>           scan-type: "fs"
>           format: table
>           scan-ref: .
>           severity: HIGH,CRITICAL
>           ignore-unfixed: true
>           exit-code: 1
> ```

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| C1 | `exit-code` input 의 기본값은 `0` 이며, 지정된 취약점이 발견됐을 때 종료하는 exit code 를 설정한다 | [§inputs] `Exit code when specified vulnerabilities are found` (default `0`) | `official-vendor-doc` | `aquasecurity/trivy-action` 모든 scan-type | exit-code=1 이 실제로 CI runner 에서 step 실패를 유발하는지 (runner OS 정책에 따라 다를 수 있음) |
| C2 | `exit-code: '1'` + `severity: 'CRITICAL,HIGH'` 조합이 공식 README 의 release-blocking 예제로 제시된다 | [§Scan CI Pipeline] `exit-code: '1'` / `severity: 'CRITICAL,HIGH'` (lines 57, 60) | `official-vendor-doc` | image scan, fs scan, config scan 모두 동일 파라미터 조합 사용 가능 | 해당 severity 기준이 모든 조직의 보안 정책에 충분한지 여부 |
| C3 | `scan-type` 은 `image`, `fs`, `repo`, `config`, `rootfs` 등 다양한 값을 지원하며, image 와 fs 스캔을 동일 action 으로 처리할 수 있다 | [§inputs] `Scan type, e.g. \`image\` or \`fs\`` (line 869); fs 예제 line 83 | `official-vendor-doc` | `aquasecurity/trivy-action` 전체 | scan-type 별 세부 동작 차이(예: repo vs fs 의 git history 포함 여부)는 이 README 만으로 완전히 증명 안 됨 |
| C4 | `trivyignores` 파라미터는 리포지터리 내 상대 경로로 `.trivyignore` 파일 또는 단일 `.trivyignore.yaml` 파일을 comma-separated 로 지정할 수 있다 | [§inputs] `comma-separated list of relative paths within the repository to one or more \`.trivyignore\` files, or a single \`.trivyignore.yaml\` file.` (line 889) | `official-vendor-doc` | `aquasecurity/trivy-action` 의 suppression 구성 | `.trivyignore` 파일 내부 문법(CVE ID 형식, 이유 주석 포맷 등)은 별도 Trivy 공식 문서 참조 필요 |
| C5 | 옵션 우선순위는 GitHub Action flag > Environment variable > Config file > Default 순이다 | [§Order of preference for options] `GitHub Action flag / Environment variable / Config file / Default` (lines 104–107) | `official-vendor-doc` | `trivy-config` (`trivy.yaml`) 와 action inputs 혼용 시 | 이 우선순위가 미래 버전에서도 동일하게 유지된다는 보장은 현재 문서로 증명 불가 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `C1`, `C2`: `exit-code: '1'` 과 `severity: 'CRITICAL,HIGH'` 를 action input 으로 설정하면 해당 severity 취약점 발견 시 GitHub Actions step 이 exit code 1 로 종료됨 — 공식 README 가 직접 release-blocking 패턴으로 제시한 예제
  - `C3`: 동일 action(`aquasecurity/trivy-action`)으로 image 스캔과 fs(filesystem) 스캔 모두 처리 가능. `scan-type` 파라미터로 구분
  - `C4`: `.trivyignore` 파일 경로를 `trivyignores:` 파라미터로 action 에 전달하는 방법
  - `C5`: `trivy.yaml` config 파일보다 action inputs 가 우선한다는 우선순위 계층
- 이 자료가 증명하지 않는 것:
  - Trivy 내부 CVE DB 의 정확성 또는 갱신 주기
  - `.trivyignore` 파일 내 suppression 엔트리 문법(별도 Trivy 공식 docs 필요)
  - 특정 언어/런타임 생태계에서 false positive 비율
  - SARIF 업로드 후 GitHub Security tab 에서의 실제 표시 동작
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - `exit-code: '1'` 이 실제 프로젝트 CI runner (ubuntu-24.04) 에서 step failure 로 올바르게 전파되는지 로컬 검증 필요
  - `trivyignores:` 에 지정할 `.trivyignore` 파일 경로가 실제 리포지터리 구조와 일치하는지 확인

## 메모 / Notes

- 현재 최신 pin 버전: `aquasecurity/trivy-action@v0.36.0` (README 상 기준, 실제 사용 시 최신 릴리즈 확인 권장)
- `ignore-unfixed: true` 는 패치가 없는 취약점을 스킵하므로, false positive 노이즈 감소에 유효하지만 unfixed 취약점을 visibility 에서 제외한다는 trade-off 존재
- SARIF 포맷 + `github/codeql-action/upload-sarif@v4` 조합은 GitHub Advanced Security 라이선스 필요 — 프라이빗 repo 무료 플랜에서는 사용 불가 (README §"Using Trivy if you don't have code scanning enabled" 참조)

## Related / 관련

- Trivy 공식 문서 (config file 문법, `.trivyignore` 형식): https://aquasecurity.github.io/trivy/latest/docs/references/configuration/config-file/
- Trivy 환경 변수 레퍼런스: https://aquasecurity.github.io/trivy/latest/docs/configuration/#environment-variables
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/trivy-ci-gate]]` (생성 시)