Files
clean-architecture-backend-…/.github/dependency-vulnerability-policy.md
T
DongHyeonka bae2965f06 docs: 단계표·capability 상태·설정 설명을 지금 빌드와 workflow에 맞춘다
문제: 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰다.
- 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다. TESTING_STRATEGY의 repository
  목록은 releaseCheck를 「ci + ...」라 했고, docs/build.md의 mainCheck·
  qualificationCheck 행은 testQualityCheck·verifyFeatureScaffold·graphqlStableTest를
  빠뜨렸다.
- capability-status가 지운 redis-sdk-topology.yml·notification-platform.yml·
  verifyNotificationEvidence, app-bootstrap의 OutboxConfig(지금
  :composition:outbox-relay), 없는 lane 이름을 증거로 들었다. 제거된 코드 표의
  재배치 전 경로는 설명 없이 지금 트리에 없었다.
- docs/build.md·bootstrap-local.sh가 기본 조립이 Flyway를 돈다고 했다(기본은
  web뿐). 알림 키 개수를 복사해 틀렸다.
- roadmap messaging-r2가 지운 VerifyMessagingEvidenceTask·
  MessagingQualificationPlugin을 예시로 들었다.
- cache-redis README·build.gradle, httpclient build.gradle이 #13이 합친
  integration job을 가리켰다.
- renovate.json·취약점 정책이 「두 봇」과 GitHub vulnerability alert를 전제했다.
  이 Gitea repo에 Renovate 실행기는 없다.
- graphql AGENTS·README가 「모듈별 yml 금지·없음」이라 했지만 leaf는
  config/graphql.yml을 직접 읽는다. 지운 execution profile을 적었다.

고친 것: 단계 구성은 gates.md 1절과 루트 build.gradle을 정본으로 가리키고, 남긴
표 행은 지금 태스크대로 고쳤다. capability-status 행 넷을 지금 job·태스크·모듈로
고치고, 제거된 코드 표의 경로가 지운 때의 배치라는 머리말과 지운
ComposeMergeCharacterizationTest 행을 더했다. 기본 조립·Flyway 설명, 알림 키(개수
대신 registry), roadmap(`> 이력`), 세 integration 설명(`main` job이
:integrationCheck :mainCheck를 함께 돈다), renovate·정책(실행기 없음, enforced는
trivy), graphql 설정 파일 설명을 고쳤다.

검증: check-docs.py·check-work-docs.py rc=0, 이 문서들을 읽는 시험은
CapabilityStatusDocumentTest(app-bootstrap document-contract)다.

Refs: RR9-04-09, RR9-04-10, RR9-04-20, RR9-04-21, RR9-04-22, RR9-04-25, RR9-04-28, RR9-03-30
2026-11-13 05:03:52 +09:00

7.4 KiB

의존성 취약점 정책

이 정책을 강제하는 것은 scripts/ci/trivy-scan.sh(pull request workflow의 done job, main·nightly workflow의 vulnerabilities job, release workflow의 이미지 job이 부른다), ../.trivyignore.yaml, CODEOWNERS다. ../renovate.json은 갱신 PR을 만드는 설정일 뿐 강제 수단이 아니다. 이 repo를 보는 Renovate 실행기가 지금 Gitea에 없어서, 그 설정은 누가 Renovate를 이 repo에 붙일 때부터 쓰인다.

실행 위치와 플랫폼 경계

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가 저장소에 커밋된 보안 갱신 봇 설정이다. 실행기가 붙어 있지 않은 동안 갱신은 trivy 실패를 본 관리자가 손으로 한다. GitHub vulnerability alert(vulnerabilityAlerts)는 GitHub 호스트에서만 있고, 그 밖에서는 osvVulnerabilityAlerts가 근거다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다 (renovate.json의 automerge: false). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가 ./gradlew resolveAndLockAll --write-locks로 잠금을 다시 만들고, 잠금 diff를 검토해 함께 커밋한다. 의존성 선언과 모든 gradle.lockfile은 같이 움직이고, verifyDependencyLocks는 계속 릴리스를 막는다.

봇 알림은 모든 forge에서 전이 의존성(transitive dependency)까지 봐 주지 않는다. 취약한 전이 의존성은 Gradle constraint나 resolution rule로 고정하고, 잠금을 의도적으로 다시 만들고, 전체 스냅숏 Trivy 검사를 유지한다.