---
title: "Trivy — Filtering & Suppression Policy (trivyignore / trivyignore.yaml)"
source_type: official-doc
url: https://trivy.dev/docs/latest/configuration/filtering/
archive_url:
vendor: Aqua Security (Trivy)
related_branches: [feature-dependency-vulnerability-management-contract]
related_projects: []
tags: [official-doc, security, vulnerability-management, trivy, devops]
created: 2026-06-15
---

# Trivy — Filtering & Suppression Policy (trivyignore / trivyignore.yaml)

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

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-dependency-vulnerability-management-contract]] | 취약점 suppression governance — `.trivyignore` / `.trivyignore.yaml` 포맷, CVE ID별 무시, 그리고 만료일(`exp:` / `expired_at:`) 지정 기능으로 영구 suppress를 방지한다는 결정의 근거 |

## 출처 / Source

- 원본 URL: https://trivy.dev/docs/latest/configuration/filtering/
- 아카이브 URL: (미등록)
- 저자 / 조직: Aqua Security — Trivy project (official docs)
- 발행일: 미상 (latest 브랜치 문서)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

Trivy의 공식 문서에서 `.trivyignore`(텍스트 포맷, 만료일 `exp:YYYY-MM-DD`)와 `.trivyignore.yaml`(구조화 YAML, `expired_at` 필드, `statement` 사유 기록) 두 suppression 파일 포맷을 명세한다. `feature-dependency-vulnerability-management-contract` 브랜치의 suppression 거버넌스 결정 — 특히 만료일 강제로 영구 suppress 방지 — 의 공식 근거로 보관한다.

## 핵심 인용 / Key quotes (verbatim, self-grep 통과)

> [§Suppression Methods / By Finding IDs] "`.trivyignore`: Simple text format listing CVE IDs or check codes, optionally with expiration dates"

> [§Suppression Methods / By Finding IDs] "`.trivyignore.yaml`: Structured YAML format allowing granular control by vulnerability type, file paths, and package URLs (PURLs)"

> [§.trivyignore File Format / code example] `CVE-2019-14697 exp:2023-01-01`

> [§.trivyignore.yaml Format / field list] "`expired_at`: Expiration date in `yyyy-mm-dd` format (always valid if omitted)"

> [§.trivyignore.yaml Format / field list] "`statement`: Reason for ignoring the finding (not used for filtering)"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| C1 | `.trivyignore`는 CVE ID 또는 체크 코드를 한 줄씩 열거하는 텍스트 포맷이며, 만료일(expiration date) 지정을 선택적으로 지원한다 | [§Suppression/By Finding IDs] "`.trivyignore`: Simple text format listing CVE IDs or check codes, optionally with expiration dates" | `official-vendor-doc` | Trivy를 사용하는 모든 CI/CD 파이프라인 | `.trivyignore`가 기본 경로로 자동 로드된다는 것(경로 지정이 필요할 수 있음) |
| C2 | `.trivyignore.yaml`은 취약점·오류·시크릿·라이선스를 타입별로 분리하고, 대상 경로(paths), PURL, 만료일, 사유(statement)를 구조화해 suppression할 수 있다 | [§Suppression/By Finding IDs] "`.trivyignore.yaml`: Structured YAML format allowing granular control by vulnerability type, file paths, and package URLs (PURLs)" | `official-vendor-doc` | Trivy ≥ (YAML 포맷 지원 버전) | 모든 Trivy 버전에서 기본 지원된다는 것(experimental phase 명시됨) |
| C3 | `.trivyignore` 텍스트 포맷에서 만료일은 `exp:YYYY-MM-DD` 형식으로 CVE ID 뒤에 공백으로 구분해 지정한다 | [§.trivyignore File Format / code] `CVE-2019-14697 exp:2023-01-01` | `official-vendor-doc` | `.trivyignore` 파일 작성 | 만료일이 지난 항목을 Trivy가 자동으로 에러로 처리한다는 것(동작은 버전별 확인 필요) |
| C4 | `.trivyignore.yaml`의 `expired_at` 필드는 `yyyy-mm-dd` 포맷을 사용하며, 미지정 시 항상 유효(always valid)로 처리된다 | [§.trivyignore.yaml Format] "`expired_at`: Expiration date in `yyyy-mm-dd` format (always valid if omitted)" | `official-vendor-doc` | `.trivyignore.yaml` 파일 작성 | 미지정(영구 유효) suppression을 파이프라인 정책 레벨에서 거부하는 내장 기능이 있다는 것 |
| C5 | `.trivyignore.yaml`의 `statement` 필드는 무시 사유를 기록하기 위한 것이며, 필터링에는 사용되지 않는다 | [§.trivyignore.yaml Format] "`statement`: Reason for ignoring the finding (not used for filtering)" | `official-vendor-doc` | `.trivyignore.yaml` 파일 작성 | statement가 외부 감사 시스템과 연동된다는 것 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `C1`: `.trivyignore` 텍스트 포맷 문법 (CVE ID 한 줄, `exp:` suffix)
  - `C2`: `.trivyignore.yaml` 포맷 구조 (타입별 분리, 주요 필드 목록)
  - `C3`: `exp:YYYY-MM-DD` 만료일 지정 문법 (`.trivyignore` 전용)
  - `C4`: `expired_at: yyyy-mm-dd` 만료일 필드 (`trivyignore.yaml`), 미지정 시 영구 유효 동작
  - `C5`: `statement` 필드는 사유 기록 전용, 필터링 영향 없음
- 이 자료가 증명하지 않는 것:
  - `.trivyignore.yaml`이 모든 Trivy 버전에서 기본 활성화된다는 것 — 문서에 "experimental phase"로 명시, `--ignorefile` 플래그 명시 필요
  - 만료일 경과 후 항목을 파이프라인이 자동으로 에러/경고 처리한다는 것 (버전별 동작 확인 필요)
  - `.trivyignore`의 기본 탐색 경로 (루트 디렉토리 자동 로드 여부)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - 사용 중인 Trivy 버전에서 `.trivyignore.yaml` experimental 지원 여부
  - `exp:` 만료일 경과 항목의 실제 Trivy 동작 (무시 해제 여부 vs 경고 출력 여부)
  - CI/CD 파이프라인에서 `--ignorefile` 플래그 전달 방식

## 메모 / Notes

- `.trivyignore.yaml` 의 `statement` 필드는 필터링에 영향 없음(C5) — 감사 목적으로는 유용하나, 사유 필드만으로 suppression을 통제할 수 없음
- 만료일 미지정 suppression이 "always valid"(C4) — 이는 영구 suppress 위험이므로, 거버넌스 정책에서 `expired_at` 필수화를 lint 또는 PR 체크로 강제해야 함 (이 자료 자체가 해결하는 것은 아님)
- 추가로 봐야 할 동일 출처 페이지: Trivy VEX 통합 문서, Rego policy 예제

## Related / 관련

- 이 자료를 인용한 branch-note: [[raw/branch-notes/feature-dependency-vulnerability-management-contract]]
- 같은 주제 다른 official-doc: Trivy VEX 공식 문서, OWASP Dependency-Check ignore 정책
- 생성 시 wiki 요약 대상: `[[wiki/concepts/trivy-vulnerability-suppression]]` (미생성)