llm-wiki/raw/official-docs/trivy-severity-exit-code-gating.md

---
title: "Trivy Exit Code & Severity Gating — Official Configuration Reference"
source_type: official-doc
url: https://trivy.dev/docs/latest/configuration/others/
archive_url:
vendor: Trivy (Aqua Security)
related_branches: [feature-build-release-supply-chain-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, ci-cd, security, slsa]
created: 2026-06-15
---

# Trivy Exit Code & Severity Gating — Official Configuration Reference

> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-build-release-supply-chain-contract]] | Decision D2 — severity→release-block 정책의 집행(enforcement) 메커니즘: Trivy `--severity HIGH,CRITICAL --exit-code 1` 기본 패턴의 공식 출처. |

## 출처 / Source

- 원본 URL: https://trivy.dev/docs/latest/configuration/others/
- 아카이브 URL: (미등록)
- 저자 / 조직: Aqua Security / Trivy project (CNCF 인큐베이팅)
- 발행일: (지속 갱신 — latest 경로)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

`feature-build-release-supply-chain-contract` branch 의 D2 결정(high/critical vulnerability는 기본 release-blocking)에서 **집행 메커니즘**이 명확히 정의되지 않은 상태였다. Trivy 공식 docs 의 `--exit-code` + `--severity` 조합이 해당 집행 메커니즘의 공식 출처이므로 보관. 또한 `--ignore-unfixed` 가 false-negative를 유발한다는 EOL 섹션의 경고는 D2 집행 시 함정이다.

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

> [§Exit Code] "By default, Trivy exits with code 0 even when security issues are detected."

> [§Exit Code] "Use the --exit-code option if you want to exit with a non-zero exit code."

> [§Exit Code] "This option is useful for CI/CD. In the following example, the test will fail only when a critical vulnerability is found."

> [§Exit Code — code example] "$ trivy image --exit-code 0 --severity MEDIUM,HIGH ruby:2.4.0 / $ trivy image --exit-code 1 --severity CRITICAL ruby:2.4.0"

> [§Exit on EOL] "Enabling --ignore-unfixed option while all packages have no fixed versions."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| TRIVY-EG-C1 | Trivy는 기본적으로 취약점이 발견되어도 exit code 0으로 종료한다 (기본값은 non-blocking) | [§Exit Code] "By default, Trivy exits with code 0 even when security issues are detected." | `official-vendor-doc` | Trivy 전체 scanner (vuln/misconfig/secret/license) | 다른 scanner 도구(Grype, Snyk 등)의 기본 동작을 말하지 않음 |
| TRIVY-EG-C2 | `--exit-code 1` 과 `--severity CRITICAL` 조합으로 critical 취약점 발견 시 CI/CD pipeline 을 실패시킬 수 있다 | [§Exit Code] "This option is useful for CI/CD. In the following example, the test will fail only when a critical vulnerability is found." / `$ trivy image --exit-code 1 --severity CRITICAL ruby:2.4.0` | `official-vendor-doc` | `trivy image` 타겟. vuln/misconfig/secret/license scanner 모두 `--exit-code` 지원 (공식 표 명시) | `--severity HIGH,CRITICAL` 복합 조건이 best practice 임을 말하지 않음 — 예시는 CRITICAL 단독. HIGH 포함은 조직 정책 선택 |
| TRIVY-EG-C3 | `--exit-code 0 --severity MEDIUM,HIGH` 와 `--exit-code 1 --severity CRITICAL` 을 단계적으로 사용하는 패턴이 공식 예시로 제공된다 | [§Exit Code] "$ trivy image --exit-code 0 --severity MEDIUM,HIGH ruby:2.4.0 / $ trivy image --exit-code 1 --severity CRITICAL ruby:2.4.0" | `official-vendor-doc` | CI/CD 2-단계 severity gating 패턴 | 이 패턴이 모든 조직의 표준이라는 뜻은 아님 — "the following example" 수준 |
| TRIVY-EG-C4 | `--ignore-unfixed` 옵션을 켜면 fix 버전 없는 패키지의 취약점이 0으로 보고될 수 있다 (false-negative 함정) | [§Exit on EOL] "Enabling --ignore-unfixed option while all packages have no fixed versions." | `official-vendor-doc` | EOL OS 또는 fix 미제공 패키지 환경 | `--ignore-unfixed` 를 쓰면 안 된다고 말하는 것이 아님 — 함정 경고만 |
| TRIVY-EG-C5 | `--exit-on-eol 1` 로 EOL OS 스캔 시 non-zero exit code 발생 가능. `--exit-code 1 --exit-on-eol 1 --severity CRITICAL` 조합이 공식 예시로 제공된다 | [§Exit on EOL] "$ trivy image --exit-code 1 --exit-on-eol 1 --severity CRITICAL alpine:3.16.3" | `official-vendor-doc` | container image / VM image / SBOM / rootfs 타겟 | EOL OS 탐지가 vuln 스캐너와 동일한 강도의 block 이어야 한다는 뜻은 아님 |

### Strength 허용값 (적용된 것만)

- `official-vendor-doc` — Aqua Security 공식 Trivy 문서

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `TRIVY-EG-C1`: Trivy 기본 exit code = 0 (non-blocking). 명시적 `--exit-code 1` 없으면 CI gate 불가.
  - `TRIVY-EG-C2`: `--exit-code 1 --severity CRITICAL` 이 critical 전용 release gate 의 공식 패턴.
  - `TRIVY-EG-C3`: `--severity MEDIUM,HIGH --exit-code 0` + `--severity CRITICAL --exit-code 1` 2-단계 패턴이 공식 예시로 존재.
  - `TRIVY-EG-C4`: `--ignore-unfixed` 는 fix 없는 취약점을 숨겨 false-negative 를 유발할 수 있음.
  - `TRIVY-EG-C5`: EOL OS 탐지를 위한 `--exit-on-eol` 플래그가 존재하며 `--exit-code` + `--severity` 와 결합 가능.
- 이 자료가 증명하지 않는 것:
  - `--severity HIGH,CRITICAL --exit-code 1` 가 "업계 표준"이라는 것 (공식 예시는 CRITICAL 단독).
  - HIGH 를 blocking 에 포함해야 한다는 규범 (D2 의 "high/critical release-blocking" 결정은 조직 정책이며 이 자료는 메커니즘만 제공).
  - Trivy 가 CVSS v3.1 Base Score 를 사용하는지 v2/v4 혼용 여부 (별도 확인 필요 — D2 의 Open Risk).
  - 다른 scanner 도구(Grype, Snyk 등)의 동작.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton GitHub Actions workflow 에서 `trivy image --exit-code 1 --severity HIGH,CRITICAL` 실제 통합 및 동작 확인.
  - Trivy 가 CVSS v3.1 severity 등급을 사용하는지 (`CVSS-SRS-C1` 의 7.0–8.9 = High, 9.0–10.0 = Critical 와 동일한 band 를 쓰는지).

## 메모 / Notes

- D2 의 Open Risk("Trivy 등 scanner 가 CVSS v3.1 Base Score 를 사용하는지 v2/v4 혼용 여부는 별도 확인 필요")는 이 자료로 해소되지 않는다 — Trivy severity 매핑 문서 (예: `trivy.dev/docs/scanner/vulnerability/`) 별도 조사 권고.
- 공식 예시는 `ruby:2.4.0` / `python:3.4-alpine3.9` / `alpine:3.10` 으로 구버전 이미지 — severity gating 동작을 보여주는 목적의 예시이므로 실제 base image 선택 기준으로 해석 금지.
- `--exit-on-eol` 은 vuln/misconfig/secret/license 중 vuln scanner 만 지원 (공식 표 참조).

## Related / 관련

- [[raw/official-docs/vuln-severity-cvss-v31-spec-first-official]] — D2 의 CVSS v3.1 severity band 정의 (TRIVY-EG-C1 의 "기본값 non-blocking" 과 조합하면 "scanner 기본값이 왜 위험한가" 설명 가능)
- [[raw/branch-notes/feature-build-release-supply-chain-contract]] — 본 자료를 인용하는 branch note (D2)