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:
@@ -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 검사를
|
||||
유지한다.
|
||||
|
||||
@@ -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·설정 변경, 마이그레이션 필요 여부, 배포·되돌리기 영향, 외부 차단 요인을 적는다. -->
|
||||
|
||||
@@ -5,8 +5,6 @@
|
||||
# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다.
|
||||
|
||||
# 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다.
|
||||
language .github/dependency-vulnerability-policy.md
|
||||
language .github/pull_request_template.md
|
||||
language compose/keycloak/README.md
|
||||
language compose/redis/acl/README.md
|
||||
language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md
|
||||
|
||||
Reference in New Issue
Block a user