Files
clean-architecture-backend-…/.github/dependency-vulnerability-policy.md
T
DongHyeonka 9682c52c65
pr / done (pull_request) Canceled after 0s
build(release): 이미지를 만들 때 OS 보안 업데이트를 받는다
문제: noble로 올린 release 수동 실행(run 101)의 이미지 검사가 HIGH 2건으로
실패한다. apt와 libapt-pkg6.0t64의 CVE-2026-109518이고, 고친 버전
2.8.4ubuntu0.1이 이미 나왔다. 가장 새로운 eclipse-temurin:21-jre-noble
digest(2026-10-29)에는 아직 들어오지 않았다. 정책은 고칠 수 있는
High/Critical을 실패로 둔다(2026-11-11 소유자 결정).

고른 방법: 실행 단계에서 `apt-get update && apt-get upgrade`로 이미 나온 보안
수정을 받고 패키지 목록을 지운다. desktop에서 같은 digest에 그대로 해 보니
apt가 2.8.4ubuntu0.1이 되었다. 정책 문서에 같은 내용을 적는다.

버린 대안: 예외로 두기. 정책은 아직 고친 버전이 없는 것만 예외로 둔다.
기본 이미지가 따라올 때까지 기다리기. 그동안 release가 막힌다.

위험·한계: 같은 커밋이라도 빌드한 날에 따라 OS 패키지 버전이 달라질 수 있다.
digest 고정은 시작점만 고정한다. SBOM이 그 빌드의 실제 버전을 남긴다.

검증: desktop 이미지 빌드, runner release 수동 실행(이 PR 본문에 적는다).
2026-11-12 10:59:43 +09:00

104 lines
6.9 KiB
Markdown

# 의존성 취약점 정책
이 정책을 강제하는 것은
[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request workflow의 `done` job, main·nightly
workflow의 `vulnerabilities` job, release workflow의 이미지 job이 부른다),
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
[`../renovate.json`](../renovate.json)이다.
## 실행 위치와 플랫폼 경계
workflow는 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml`이고 Gitea Actions(desktop runner)에서 돈다.
검사는 pull request(필수 검사 `pr / done`의 마지막 step), `main` push, 매일 예약 실행, 손으로 부른 실행에서
돈다.
외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를
남긴다. 스캐너는 action이 아니라 체크섬을 고정한 릴리스 실행 파일이다.
GitHub dependency review와 dependency submission은 GitHub.com API에만 있어 2026-11-08 Gitea로 옮길 때
지웠다. Trivy 전체 스냅숏 검사가 플랫폼에 묶이지 않는, 병합을 막는 검사다.
이미지 빌드·스캔, SBOM, 서명, 태그 릴리스는 `.gitea/workflows/release.yml`이 맡는다. 이미지 스캔도 같은
스크립트(`image` 모드)와 같은 예외 파일을 쓴다.
릴리스 이미지(2026-11-11 소유자 결정):
- 기본 이미지는 고칠 수 있는 최신 digest로 둔다(`Dockerfile`, 지금 `eclipse-temurin:21-jre-noble`).
OS 패키지의 High/Critical도 아래 표대로 막는다. 최신 digest가 Ubuntu 보안 업데이트보다 늦을 수 있어
이미지를 만들 때 `apt-get upgrade`로 이미 나온 수정을 받는다(2026-11-12: apt CVE-2026-109518).
- 아직 고친 버전이 없는 High/Critical만 `.trivyignore.yaml`에 이유와 `expired_at`을 달아 둔다.
- 라이선스: 배포하는 의존성의 금지 라이선스(Trivy CRITICAL)만 막는다. 배포하는 것은 기본 조립의 jar이므로
`src/bootstrap/app/gradle.lockfile`의 `runtimeClasspath` 항목을 본다. 그 밖의 라이선스 결과(OS 패키지,
빌드 도구 SpotBugs·Checkstyle·Error Prone, 시험 라이브러리, restricted 등급)는 보고만 한다. 배포판의 GPL
패키지는 이 애플리케이션의 이용 조건이 아니다.
- 이 라이선스 판정은 pull request의 `done` job이 빌드한 뒤에 돈다. Trivy는 같은 기계의 Gradle 캐시에서만
lockfile의 라이선스를 읽고, 이미지 안 jar의 라이선스는 읽지 못한다. 예전의 따로 된 검사 job에는 캐시가
없어 라이선스 검사가 라이선스를 한 번도 보지 못했다(2026-11-12 확인). 캐시가 없으면 건너뛴다고 적고,
캐시가 있는데 라이선스를 하나도 읽지 못하면 실패한다.
## 심각도와 대응
| 심각도 | CI 처리 | 고칠 기한 |
| --- | --- | --- |
| KEV / Critical | 막는다 | 7일 또는 CISA 기한 중 빠른 쪽 |
| High | 막는다 | 30일 |
| Medium | 알리기만 한다 | 90일 |
| Low | 알리기만 한다 | 가능한 대로 |
High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다.
템플릿을 받아 쓸 때 다시 검토한다.
Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도
대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다.
- 목록 메타데이터가 비어 있지 않다.
- 선언한 개수가 양의 정수다.
- 취약점 배열이 비어 있지 않고 길이가 선언한 개수와 같다.
- `cveID` 값이 CVE 형식이고 서로 다르다.
KEV 목록이 없거나, 비었거나, 형식이 깨졌거나, 개수가 맞지 않거나, 중복이 있거나, 받을 수 없으면 실패한다
(fail closed). CISA에 직접 닿을 수 없으면 저장소 변수 `KEV_FEED_URL`을 승인된 내부 mirror로 설정한다.
후보를 뽑을 때도 Trivy JSON을 먼저 검사한다. 맨 위가 객체이고 `Results` 배열이 비어 있지 않아야 한다.
각 결과는 객체이고, `Vulnerabilities` 값은 null이거나 배열이다. 나열된 취약점마다 비어 있지 않은 문자열
`VulnerabilityID`가 있어야 한다. 스캐너 출력이 잘못됐으면 빈 후보 목록으로 넘어가지 않고 실패한다.
## 스캐너와 네트워크 요구사항
Trivy는 커밋된 파일 시스템과 Gradle lockfile을 검사한다. High/Critical이 나오면 0이 아닌 코드로 끝나고,
Medium/Low는 보고만 하고 0으로 끝난다. 스캐너 DB나 도구를 받지 못하면 빈 결과가 아니라 실패다.
runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다.
- 설정한 Trivy 실행 파일 출처(기본은 GitHub Releases)
- Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리)
- jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽)
- CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽)
- workflow가 전체 URL로 부르는 GitHub action 출처(`https://github.com/...`)
닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과
`JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다.
mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mirror는 탐지를 늦출 수 있다.
## 예외(suppression) 관리
예외의 출처는 저장소 루트 `.trivyignore.yaml` 하나다. 모든 Trivy 검사가 `--ignorefile .trivyignore.yaml`로
그 파일을 명시한다. 앞으로 더하는 항목마다 식별자, 비어 있지 않은 이유, 90일 안의 미래 만료일이 있어야
한다. CODEOWNERS 리뷰어가 모양과 만료일을 확인하고, CODEOWNERS와 branch protection이 누가 그 변경을 승인할
수 있는지 정한다. 둘 중 하나가 다른 하나를 대신하지 않는다.
임시 ignore 파일이나 스캐너를 건너뛰는 인라인 옵션을 쓰지 않는다. 만료된 예외는 지우거나, 소유자가 새로
검토하고 지금의 증거를 붙여 갱신한다.
## 의존성 갱신 정책
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
막는다.
봇 알림은 모든 forge에서 전이 의존성(transitive dependency)까지 봐 주지 않는다. 취약한 전이 의존성은
Gradle constraint나 resolution rule로 고정하고, 잠금을 의도적으로 다시 만들고, 전체 스냅숏 Trivy 검사를
유지한다.