문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
89 lines
5.5 KiB
Markdown
89 lines
5.5 KiB
Markdown
# 의존성 취약점 정책
|
|
|
|
이 정책을 강제하는 것은
|
|
[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request·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)에서 돈다.
|
|
`vulnerabilities` job은 pull request, `main` push, 매일 예약 실행, 손으로 부른 실행에서 돈다. pull request의
|
|
필수 검사 `pr / done`이 그 결과를 포함한다.
|
|
|
|
외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를
|
|
남긴다. 스캐너는 action이 아니라 체크섬을 고정한 릴리스 실행 파일이다.
|
|
|
|
GitHub dependency review와 dependency submission은 GitHub.com API에만 있어 2026-11-08 Gitea로 옮길 때
|
|
지웠다. Trivy 전체 스냅숏 검사가 플랫폼에 묶이지 않는, 병합을 막는 검사다.
|
|
|
|
이미지 빌드·스캔, SBOM, 서명, 태그 릴리스는 `.gitea/workflows/release.yml`이 맡는다. 이미지 스캔도 같은
|
|
스크립트(`image` 모드)와 같은 예외 파일을 쓴다.
|
|
|
|
## 심각도와 대응
|
|
|
|
| 심각도 | 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 검사를
|
|
유지한다.
|