docs(github): PR 양식과 의존성 취약점 정책을 한국어로 옮긴다

문제: `.github/pull_request_template.md`와 `.github/dependency-vulnerability-policy.md`가
영어라 언어 검사 예외에 있다. 옮기면서 보니 코드와 다른 주장이 넷이다.
- PR 양식이 격리 테스트를 `flaky-quarantine.yaml`에 등록하라고 한다. 그 레지스트리는
  지웠다(`src/README.md` 「Trivy suppression과 플래키 격리」).
- 정책이 이미지 빌드·SBOM·서명·provenance를 「없는 job」이라 한다. 지금은
  `release.yml`에 있다.
- 정책이 patch·pin·digest 보안 갱신은 필수 검사 뒤 자동 병합할 수 있다고 한다.
  `renovate.json`은 모든 갱신이 `automerge: false`이고, lockfile은 사람이 다시 만든다.
- 정책이 `gradle.lockfile`을 「19개」라 한다. 지금 68개다.

고른 방법: 뜻을 그대로 옮기고 위 넷은 코드에 맞춘다. lockfile 개수는 숫자를 쓰지
않는다. 명령·경로·변수 이름은 원문으로 둔다.

검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움).
This commit is contained in:
DongHyeonka
2026-11-07 17:18:18 +09:00
parent 145ae00f90
commit 81f17b49e0
3 changed files with 79 additions and 82 deletions
+67 -67
View File
@@ -1,92 +1,92 @@
# Dependency Vulnerability Policy
# 의존성 취약점 정책
This policy is enforced by
이 정책을 강제하는 것은
[`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml),
[`dependency-review-config.yml`](dependency-review-config.yml),
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, and
[`../renovate.json`](../renovate.json).
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
[`../renovate.json`](../renovate.json)이다.
## Execution and platform boundary
## 실행 위치와 플랫폼 경계
Canonical workflow files live under `.github/workflows`. The current origin is Gitea and
server-side Actions is externally disabled; committing these controls does not enable or prove
remote execution. An administrator must enable Actions, provide compatible runners, configure
required checks, and require code-owner review separately.
정본 workflow 파일은 `.github/workflows` 아래에 있다. 지금 origin은 Gitea이고, 서버 쪽 Actions는 밖에서
꺼져 있다. 이 통제를 커밋해도 원격 실행이 켜지거나 증명되지 않는다. 관리자가 따로 Actions를 켜고, 맞는
runner를 주고, 필수 검사(required check)를 설정하고, code owner 리뷰를 필수로 해야 한다.
External actions execute only by verified full commit SHA; inline comments retain the immutable
release tag for review. GitHub dependency review publishes check output but never writes a PR
summary comment, preserving the workflow-wide `contents: read` permission.
외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를
남긴다. GitHub dependency review는 검사 결과만 내고 PR 요약 댓글은 쓰지 않는다. 그래서 workflow 전체의
`contents: read` 권한이 유지된다.
GitHub dependency review and dependency submission depend on GitHub.com APIs. They are guarded by
`github.server_url == 'https://github.com'` and intentionally skip on Gitea. `trivy-fs` is the
platform-neutral release-blocking snapshot and runs for pull requests, `main` pushes, daily
schedule, and manual dispatch.
GitHub dependency review와 dependency submission은 GitHub.com API에 기댄다. 둘은
`github.server_url == 'https://github.com'` 조건으로 막혀 있고, Gitea에서는 일부러 건너뛴다. `trivy-fs`는
플랫폼에 묶이지 않는, 릴리스를 막는 전체 스냅숏 검사다. pull request, `main` push, 매일 예약 실행, 손으로
부른 실행에서 돈다.
The later supply-chain slice owns image builds/scans, SBOM, signing, provenance, tag release, and
retention. This policy does not claim those absent jobs.
이미지 빌드·스캔, SBOM, 서명, provenance, 태그 릴리스는 `workflows/release.yml`이 맡는다. 이 정책은 그
job을 다루지 않는다.
## Severity and response
## 심각도와 대응
| Severity | CI posture | Target remediation |
| 심각도 | CI 처리 | 고칠 기한 |
| --- | --- | --- |
| KEV / Critical | block | 7 days or the CISA due date, whichever is sooner |
| High | block | 30 days |
| Medium | advisory | 90 days |
| Low | advisory | best effort |
| KEV / Critical | 막는다 | 7일 또는 CISA 기한 중 빠른 쪽 |
| High | 막는다 | 30일 |
| Medium | 알리기만 한다 | 90일 |
| Low | 알리기만 한다 | 가능한 대로 |
High/Critical is the template's release threshold. The exact threshold and remediation targets are
team policy rather than an external mandate and should be reviewed when the template is adopted.
GitHub dependency review applies the same High threshold to newly introduced runtime dependencies.
High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다.
템플릿을 받아 쓸 때 다시 검토한다. GitHub dependency review도 새로 들어온 runtime 의존성에 같은 High
기준을 쓴다.
The Trivy JSON snapshot is also compared with the CISA Known Exploited Vulnerabilities catalog.
Any intersection blocks regardless of Trivy severity. Before intersection, CI requires nonblank
catalog metadata, a positive integral declared count, a non-empty vulnerability array whose length
matches that count, and unique CVE-pattern `cveID` values. A missing, empty, malformed,
count-inconsistent, duplicate, or unreachable KEV feed fails closed; configure the `KEV_FEED_URL`
repository variable to an approved internal mirror when direct CISA access is unavailable.
Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도
대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다.
Candidate extraction also validates Trivy's JSON first: the top level must be an object with a
non-empty `Results` array; each result is an object whose `Vulnerabilities` value is null or an
array; and every listed vulnerability has a nonblank string `VulnerabilityID`. Invalid scanner
output fails closed instead of becoming an empty candidate set.
- 목록 메타데이터가 비어 있지 않다.
- 선언한 개수가 양의 정수다.
- 취약점 배열이 비어 있지 않고 길이가 선언한 개수와 같다.
- `cveID` 값이 CVE 형식이고 서로 다르다.
## Scanner and network requirements
KEV 목록이 없거나, 비었거나, 형식이 깨졌거나, 개수가 맞지 않거나, 중복이 있거나, 받을 수 없으면 실패한다
(fail closed). CISA에 직접 닿을 수 없으면 저장소 변수 `KEV_FEED_URL`을 승인된 내부 mirror로 설정한다.
Trivy scans the committed filesystem and Gradle lockfiles. High/Critical findings exit non-zero;
Medium/Low findings are reported with exit zero. Scanner database or tool-download failures remain
failures rather than silently producing an empty result.
후보를 뽑을 때도 Trivy JSON을 먼저 검사한다. 맨 위가 객체이고 `Results` 배열이 비어 있지 않아야 한다.
각 결과는 객체이고, `Vulnerabilities` 값은 null이거나 배열이다. 나열된 취약점마다 비어 있지 않은 문자열
`VulnerabilityID`가 있어야 한다. 스캐너 출력이 잘못됐으면 빈 후보 목록으로 넘어가지 않고 실패한다.
Runners need HTTPS egress to:
## 스캐너와 네트워크 요구사항
- the configured Trivy binary source (GitHub Releases by default);
- Trivy vulnerability databases (the scanner defaults, commonly OCI registries);
- jq releases, unless `JQ_DOWNLOAD_BASE_URL` points to an internal mirror;
- the CISA KEV feed, unless `KEV_FEED_URL` points to an internal mirror;
- GitHub action sources when the forge does not mirror actions.
Trivy는 커밋된 파일 시스템과 Gradle lockfile을 검사한다. High/Critical이 나오면 0이 아닌 코드로 끝나고,
Medium/Low는 보고만 하고 0으로 끝난다. 스캐너 DB나 도구를 받지 못하면 빈 결과가 아니라 실패다.
Closed networks must mirror the pinned Trivy/jq artifacts and checksums, set
`TRIVY_DOWNLOAD_BASE_URL` and `JQ_DOWNLOAD_BASE_URL`, configure Trivy's documented database mirror
environment, and set `KEV_FEED_URL`. Mirror availability and freshness are operational
dependencies; stale mirrors can delay detection.
runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다.
## Suppression governance
- 설정한 Trivy 실행 파일 출처(기본은 GitHub Releases)
- Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리)
- jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽)
- CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽)
- forge가 action을 mirror하지 않으면 GitHub action 출처
The only suppression source is repository-root `.trivyignore.yaml`. Every Trivy scan passes it
explicitly with `--ignorefile .trivyignore.yaml`. Each future entry must contain an identifier, a
non-empty rationale, and a future expiry no more than 90 days away. A CODEOWNERS reviewer validates
the shape and expiry; CODEOWNERS plus branch protection controls who may approve the change.
Neither control substitutes for the other.
닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과
`JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다.
mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mirror는 탐지를 늦출 수 있다.
Do not use an ad-hoc ignore file or an inline scanner bypass. An expired suppression is removed or
renewed with fresh owner review and current evidence.
## 예외(suppression) 관리
## Dependency update policy
예외의 출처는 저장소 루트 `.trivyignore.yaml` 하나다. 모든 Trivy 검사가 `--ignorefile .trivyignore.yaml`로
그 파일을 명시한다. 앞으로 더하는 항목마다 식별자, 비어 있지 않은 이유, 90일 안의 미래 만료일이 있어야
한다. CODEOWNERS 리뷰어가 모양과 만료일을 확인하고, CODEOWNERS와 branch protection이 누가 그 변경을 승인할
수 있는지 정한다. 둘 중 하나가 다른 하나를 대신하지 않는다.
Renovate is the checked-in security-update bot configuration. Patch/pin/digest security updates
may auto-merge only after every configured required check succeeds; minor and major updates require
human review. Dependency declarations and all 19 `gradle.lockfile` files must move together, and
`verifyDependencyLocks` remains release-blocking.
임시 ignore 파일이나 스캐너를 건너뛰는 인라인 옵션을 쓰지 않는다. 만료된 예외는 지우거나, 소유자가 새로
검토하고 지금의 증거를 붙여 갱신한다.
Bot alerts are not a transitive-dependency backstop on every forge. Use a Gradle constraint or
resolution rule for a vulnerable transitive dependency, refresh locks deliberately, and retain the
full-snapshot Trivy scan.
## 의존성 갱신 정책
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`cd src && ./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
막는다.
봇 알림은 모든 forge에서 전이 의존성(transitive dependency)까지 봐 주지 않는다. 취약한 전이 의존성은
Gradle constraint나 resolution rule로 고정하고, 잠금을 의도적으로 다시 만들고, 전체 스냅숏 Trivy 검사를
유지한다.
+12 -13
View File
@@ -1,18 +1,17 @@
## What changed and why
## 무엇을 왜 바꿨나
<!-- Summarize the behavior, architecture boundary, or policy being changed. -->
<!-- 바꾼 동작, 아키텍처 경계, 정책을 요약한다. -->
## Verification
## 검증
- [ ] I ran focused `:<changed-leaf>:check` tasks for the modules I changed.
- [ ] I ran `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks` when the change touched repository structure, dependencies, or public paths.
- [ ] I did not add an unregistered production module dependency.
- [ ] Dependency changes include refreshed `gradle.lockfile` files and a strict-lock verification.
- [ ] Trivy suppressions include an owner-reviewed reason and an expiry within 90 days.
- [ ] Any quarantined test is registered in `flaky-quarantine.yaml` with a reason, issue, and
`quarantined_since` date.
- [ ] I documented checks that could not run and their remaining risk.
- [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다.
- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] registry에 없는 production 모듈 의존을 더하지 않았다.
- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다.
- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다.
- [ ] 간헐 실패 테스트는 격리하지 않고 고치거나 지웠다(격리 레지스트리는 없다).
- [ ] 돌리지 못한 검사와 그 때문에 남은 위험을 적었다.
## Compatibility and operations
## 호환성과 운영
<!-- Note public API/config changes, migration needs, rollout/rollback impact, and external blockers. -->
<!-- 공개 API·설정 변경, 마이그레이션 필요 여부, 배포·되돌리기 영향, 외부 차단 요인을 적는다. -->