diff --git a/.github/dependency-vulnerability-policy.md b/.github/dependency-vulnerability-policy.md index f046077e..cda1c924 100644 --- a/.github/dependency-vulnerability-policy.md +++ b/.github/dependency-vulnerability-policy.md @@ -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 검사를 +유지한다. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b0736f82..a9b235c0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,17 @@ -## What changed and why +## 무엇을 왜 바꿨나 - + -## Verification +## 검증 -- [ ] I ran focused `::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. +- [ ] 바꾼 모듈마다 `::check`를 돌렸다. +- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다. +- [ ] registry에 없는 production 모듈 의존을 더하지 않았다. +- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다. +- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다. +- [ ] 간헐 실패 테스트는 격리하지 않고 고치거나 지웠다(격리 레지스트리는 없다). +- [ ] 돌리지 못한 검사와 그 때문에 남은 위험을 적었다. -## Compatibility and operations +## 호환성과 운영 - + diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index d384cec2..8a5aa7f4 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -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