wbsong111
981d36daa4
* 차단 CVE 가 나오면 자체 빌드 이미지를 스스로 재빌드한다 + Dockerfile 작성 규칙
두 가지다. (1) 이전 이미지에서 CVE 가 발견되면 재빌드가 자동으로 일어나게 한다.
(2) Dockerfile 을 OS·언어 축으로 일관되게 쓰도록 규칙을 정한다.
(1) 재빌드 자동화 — 트리거를 로컬 실측으로 고쳤다
------------------------------------------------
처음에는 트리거를 "핀이 뒤처졌는가" 로 잡았다. **배포 중인 이미지 8개를 실제로 스캔해 보니
그게 틀렸다** — 차단 CVE 가 있는 4개 중 핀 변경이 필요한 것은 하나도 없었고, 그 판정은
"0건" 을 냈다. 재빌드로 고쳐지는 경우가 셋이기 때문이다.
핀이 뒤처졌다 → 핀 올려서 빌드
핀은 맞는데 그 핀으로 아직 안 빌드됐다 → 그냥 빌드 ← 핀만 고친 PR 직후 상태
베이스 OS 패키지가 뒤처졌다 → 그냥 빌드 ← 재빌드하면 zypper 가 최신을 깐다
그래서 트리거는 **"수정 버전이 있는 차단 CVE 가 있는가"** 다. 핀 변경은 필요하면 함께 하는
부수 작업이고 트리거가 아니다. 수정 버전 없는 차단(affected·will_not_fix)은 재빌드해도
그대로이므로 no-fix 로 따로 보고해 사람이 다른 레버를 판단하게 한다.
scripts/build/check-rebuild-needed.py 신규
카탈로그가 실제로 가리키는 이미지를 기준으로 잰다 — 재빌드해 보지 않고도 "지금 배포 중인
것이 규정을 벗어났는가" 를 답한다.
catalog.env → 카탈로그 values 의 ref → 그 ref 의 스캔 리포트 ↕ build.env 의 핀
판정 규칙은 게이트와 같은 출처를 쓴다(max(벤더,NVD)·승인 예외·만료 예외 무효) —
cve-gate.py 의 함수를 그대로 가져다 쓴다. 핀 산출은 suggest-go-upgrades.py 재사용.
--list-refs 로 "무엇을 스캔해야 하나" 도 스크립트가 낸다 — ref 해석 규칙이 워크플로로
새면 두 곳이 어긋난다.
suggest-go-upgrades.py 는 산출 로직이 main() 안에 있어 재사용할 수 없었다. collect_modules/
collect_stdlib/builder_candidates/effective_severity 로 빼고 main() 은 호출해 출력만 한다 —
CLI 출력은 리팩터 전후 동일하다(실측 대조).
build-image.yml 에 schedule(월요일 02:00 UTC)과 mode=drift 를 추가했다. 판정 → (핀이
뒤처졌으면) 브랜치 push → 빌드·verify.sh·게이트까지 자동이고 **레지스트리 push 와 카탈로그
반영은 하지 않는다.** 게시 여부 로직에서 catch-all 을 true → false 로 바꿨다 — 원래는
트리거를 추가하면 자동으로 push 가 켜지는 구조였고 schedule 을 넣는 순간 사고가 났다.
이제 push 는 workflow_dispatch + mode=image 에서만 켜진다.
(2) Dockerfile 작성 규칙 — 실제 8개에서 추출했다
----------------------------------------------
image-authoring.md 가 규칙 본문의 단일 출처이고 skill 은 "어느 절을 읽어야 하는가" 선택표만
갖는다(CLAUDE.md 의 "Skill 은 절차 본문을 복제하지 않는다").
두 축은 독립이다 — 같은 bci-micro 최종 위에 Go 빌더도 Node 빌더도 온다.
축 1 최종 베이스 bci-base / bci-micro / scratch+micro rootfs — 셋뿐이다.
네 번째를 만들기 전에 왜 셋으로 안 되는지 먼저 적는다.
micro·scratch 는 nonroot 계정을 직접 만들어야 한다(실측 형태 첨부).
축 2 빌더 Go(BUILDPLATFORM/TARGETARCH, ldflags 에 SOURCE_COMMIT) /
Node(런타임은 OS 패키지) / JVM(재컴파일 없이 jar 만 OLD/NEW 쌍으로
교체 — OLD 를 받는 이유는 못 찾으면 실패시키기 위함) /
C·Lua(정적 링크 금지 — SLE_BCI 에 static glibc 없음)
"업스트림 런타임 계약은 보존한다" 절을 새로 넣었다(USER·ENTRYPOINT·파일 레이아웃).
cloudnative-pg 가 멀티아치 심볼릭 링크를 부수 장치로 오판해 지웠다가 리컨실이 실패한 것이
근거다. 스캐너는 이걸 전혀 보지 못한다.
로컬 검증 — 판정만이 아니라 빌드까지 돌렸다
-----------------------------------------
판정이 지목한 4건을 실제로 빌드해 전제를 확인했다. 문서에 단정만 해두고 넘어가지 않았다.
이미지 배포 중 재빌드 후 핀 변경
apisix-ingress-controller 차단 8 0/0 PASS · VERIFY-OK · cov=ok 없음
cloudnative-pg 차단 8 0/0 PASS · VERIFY-OK · cov=ok 없음
etcd 차단 8 0/0 PASS · VERIFY-OK · cov=ok 없음
cnpg-postgresql 차단 2 0/0 PASS · VERIFY-OK · cov=ok 없음
- cnpg-postgresql 이 "베이스 OS 패키지 갱신으로 해소" 사례다(perl·rpm-ndb). 핀을 하나도
안 바꾸고 재빌드만으로 0건이 됐다 — 검증 없이 단정했던 부분이라 이게 핵심 확인이다.
- 빌드된 etcd 바이너리가 go1.26.6 + pinned commit 을 보고한다 — 핀이 실제로 반영됐다.
- 4건 다 CoverageProbe=ok 이므로 0건이 "측정되지 않음" 이 아니다.
- 빌드 후에도 git status images/ 가 깨끗하다 = 트리거를 핀 기준으로 뒀다면 4건 전부
놓쳤을 것이라는 확인.
그 외: 예외 적용(keycloak CVE-2025-59250 → 0건), --fail-on-drift rc=1, 워크플로 셸 재현
(GITHUB_OUTPUT 4개 JSON·fromJson OK·핀 변경 0 → 브랜치 미생성 → 기본 ref 로 빌드),
push 정책 전 조합 확인.
CI 에서 미검증인 것은 환경 특성뿐이다 — trivy 설치 스텝, GITHUB_STEP_SUMMARY 출력,
matrix 팬아웃, contents:write 로 브랜치 push. 빌드 자체는 로컬과 같은 스크립트를 쓴다.
Refs #35
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* self-build-image SKILL 의 자동 재빌드 절을 실행 계약만 남긴다
같은 커밋에서 image-authoring.md 와 SKILL 양쪽에 자동 재빌드 절차를 거의 동일하게 썼다.
SKILL 이 "작성 규칙 본문은 image-authoring.md 가 단일 출처다 — 여기 복제하지 않는다" 고
두 번 선언한 파일에서 내가 그 규칙을 어겼다.
SKILL 에는 실행 계약(수동 실행 명령 · 로컬 판정 명령 · push 안 한다는 사실)만 남기고
트리거 조건과 그 근거는 image-authoring.md 를 가리킨다.
frontmatter 도 함께 고친다 — "7종" 에 argocd 가 빠져 있어 실제 images/ 8개와 어긋났다.
description 은 Skill 로딩 판단에 쓰이는 텍스트이므로 "목록은 images/ 가 단일 출처" 라는
회피 조항으로 덮을 수 없다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* 레포 분리 시 갈라지는 이음선을 코드와 문서에 명시한다
커스텀 이미지가 별도 레포로 분리될 예정인데, check-rebuild-needed.py 는 카탈로그(무엇을
배포 중인가)와 build.env(어떻게 만드는가)를 **양쪽 다** 읽는다. 분리 시 이 파일이 갈라진다.
절단면은 이미 함수 경계에 있다. 6개월 뒤에 "이 함수가 왜 카탈로그를 읽지" 를 다시 파지
않도록 어느 함수가 어느 쪽인지 docstring 에 적었다.
A (카탈로그 레포) resolve_current_ref + blocking_cves → "차단됐는가"
B (이미지 레포) pin_changes + apply_changes → "핀을 올려야 하는가"
check_image 둘을 엮는 오케스트레이션 — 여기가 갈라진다
image-authoring.md 의 드리프트 절에도 같은 사실을 한 문단으로 적어 분리 작업 때 이 주석을
먼저 읽게 했다. 결합점 전체 목록은 경계 문서화 작업에서 표로 정리한다.
코드 동작은 바뀌지 않았다 — 주석과 문서만 추가했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
6.8 KiB
6.8 KiB
name, description
| name | description |
|---|---|
| self-build-image | 자체 빌드 하드닝 이미지를 추가하거나 기존 빌드 정의를 변경할 때 사용한다. "이미지 자체 빌드해줘", "하드닝 이미지 추가", "차단 CVE를 자체 빌드로 해소", "build-hardened-image.sh 실행", "images/ 아래 새 이미지" 같은 요청이 해당한다. 현재 adc, apisix, apisix-ingress-controller, argocd, cloudnative-pg, cnpg-postgresql, etcd, keycloak 8종이 있다(정확한 목록은 images/ 디렉토리가 단일 출처). |
자체 빌드 하드닝 이미지
CVE 게이트 대응 우선순위(상위 태그 교체 → 베이스 OS 교체 → 자체 빌드 → 예외 승인)에서 앞의 두 단계로 해소가 안 될 때만 온다.
원칙 — 오케스트레이션은 항상 하나다
scripts/build/build-hardened-image.sh 하나가 모든 자체 빌드 이미지를 빌드한다.
OS 패키지 재설치든 소스 컴파일이든 스크립트는 같고, 차이는 전부 images/<image>/ 안에 있다.
"이 이미지는 성격이 다르다"는 이유로 새 오케스트레이션 스크립트를 만들지 않는다 —
절차(빌드 → 기능검증 → SBOM → 스캔 → 게이트 → push)는 이미지 종류와 무관하게 동일하다.
SBOM·스캔·게이트도 다시 만들지 않는다 — build-hardened-image.sh가 이미
scan-sbom.sh/cve-gate.py를 호출한다.
실행
IMAGE=<image> BASE_OS=<variant> bash scripts/build/build-hardened-image.sh /tmp/out
images/<image>/<variant>.build.env가 계약(DOCKERFILE, TARGET, BUILD_ARGS 등)을
선언하면 스크립트는 이미지 종류를 몰라도 된다. 전체 계약표와 신규 이미지 추가 7단계 절차는
.claude/image-authoring.md에 있다 — 여기 복제하지 않는다.
CI는 build-image.yml이 image 입력으로 이미 파라미터화돼 있다. images/<image>/catalog.env만
추가하면 워크플로 수정 없이 태울 수 있다.
새 Dockerfile 은 두 축을 먼저 고른다
작성 규칙 본문은 .claude/image-authoring.md가 단일 출처다 — 여기 복제하지 않는다. 이 표는 "어느 절을 읽어야 하는가" 만 정한다.
두 축은 독립이다. 같은 bci-micro 최종 위에 Go 빌더가 오기도 하고 Node 빌더가 오기도 한다.
축 1 — 최종 런타임 베이스 (스캔·배포 대상. 원칙 2)
| 런타임이 필요로 하는 것 | 고른다 | 선례 |
|---|---|---|
| OS 패키지·셸 (zypper 설치, 셸 entrypoint) | bci-base |
adc apisix argocd cnpg-postgresql |
| 정적 링크 바이너리 하나뿐 | bci-micro |
apisix-ingress-controller cloudnative-pg etcd |
| 런타임 트리를 builder 에서 조립 (JVM 등) | scratch + micro rootfs 씨앗 |
keycloak |
→ 세 조합 밖으로 나가려면 왜 셋으로 안 되는지 먼저 적는다. micro/scratch 는
nonroot 계정·sed/grep 부재를 직접 감당해야 한다(image-authoring.md "어느 BCI 변종").
축 2 — 빌더 스테이지 (최종에 남지 않음. 원칙 2 대상 아님 → 공식 언어 이미지 그대로)
| 언어 | 빌더 | 핀 키 |
|---|---|---|
| Go | golang:${GO_BUILDER_TAG} + $BUILDPLATFORM/TARGETARCH |
GO_BUILDER_TAG · GO_MODULE_UPGRADES |
| Node | node:* (런타임은 OS 패키지 nodejs24) |
NODE_BUILDER_TAG · NODE_PKG |
| JVM | BCI base — 재컴파일 없이 취약 jar 만 교체 | <LIB>_OLD / <LIB>_VERSION 쌍 |
| C · Lua | BCI base — 정적 링크 금지(static glibc 없음) | 컴포넌트별 버전 ARG |
→ 상세는 image-authoring.md "언어별 빌더 규칙". 세 가지가 언어와 무관하게 공통이다:
버전은 Dockerfile 에 박지 말고 build.env 값으로, BUILD_ARGS 에 반드시 등록(빠뜨리면
조용히 기본값으로 빌드된다), 그리고 업스트림 런타임 계약(USER·ENTRYPOINT·파일 레이아웃)은
보존한다.
자동 재빌드 — 실행 계약만
build-image.yml 이 주간(월요일 02:00 UTC)으로 배포 중인 이미지를 스캔해 재빌드가 필요한
것을 찾아 빌드·검증·게이트까지 돈다. 트리거 조건과 왜 그 조건인지는
.claude/image-authoring.md "핀은 가만히 있어도 뒤처진다" 가
단일 출처다 — 여기 복제하지 않는다.
# 수동으로 같은 것을 돌린다
gh workflow run self-build-image --repo <org>/dip-catalog -f mode=drift
# 판정만 로컬에서 본다
python3 scripts/build/check-rebuild-needed.py --list-refs
python3 scripts/build/check-rebuild-needed.py --reports <trivy-reports> [--apply]
이 경로는 레지스트리 push 와 카탈로그 반영을 하지 않는다 — push 는
workflow_dispatch + mode=image 에서만 켜진다.
실측된 함정
FROM에 쓰는ARG는 첫FROM이전(전역 스코프)에 선언한다. 스테이지 내부에 선언하면 그 스테이지 지역 변수가 되어 이후FROM의 이미지명 해석에 쓰이지 않고 빈 이미지명 에러가 난다.- 게이트 PASS는 "동작한다"를 증명하지 않는다. CVE 스캐너는 런타임 요구사항(오퍼레이터가 자신의 파일 레이아웃에 의존하는 것 등)을 전혀 보지 못한다. 배포 검증을 반드시 한다 — 절차는 .claude/deploy-test-procedure.md.
CoverageProbe가ok인지 확인한다.none이면 findings 0건이 진짜 0건이 아니라 스캐너에 그 배포판 데이터가 없다는 뜻이다(sbom-cve-gateskill 참고).- 롤링 태그를 쓰지 않는다. 같은 앱 버전이라도 베이스 업데이트 결과가 시점마다 달라
태그에 빌드일을 포함한다(예:
1.30.0-security-hardened-20260804). - 핀을 고정한 대가로 핀이 뒤처진다. 소스를 안 바꿔도 새 CVE 가 공개되면 어제 PASS 였던
핀이 오늘 FAIL 이 된다. 위 "자동 재빌드" 가 이것을 잡는다. 조치 전에 그 결과를 먼저 본다:
python3 scripts/build/check-rebuild-needed.py --reports <trivy-reports> [--image <name>] [--apply] - 단, 같은 날 다시 빌드하면 그 태그가 겹친다. 노드가 캐시한 옛 digest 가 그대로 쓰여
(
imagePullPolicy: IfNotPresent) 고친 것이 반영되지 않은 채 "안 고쳐졌다" 로 보인다. 배포 검증 중이라면imagePullPolicy: Always로 우회하고, digest 로 확인한다 —kubectl get pod -o jsonpath='{..imageID}'. 프레임워크 차원의 미결 사항이다.
마무리
카탈로그 values(custom-values.yaml/dip-values.yaml) 태그 갱신은
scripts/build/patch-catalog-tag.py가 한다. 조사·결정 근거는 PR 설명과
MEMORY.md에 남긴다. images/**+manifests/helm/** 변경은 PR로만 반영한다.