diff --git a/.claude/image-authoring.md b/.claude/image-authoring.md index f4ae982..79bb3e4 100644 --- a/.claude/image-authoring.md +++ b/.claude/image-authoring.md @@ -3,10 +3,10 @@ [CLAUDE.md](../CLAUDE.md) 에서 분리했다. 새 자체 빌드 이미지를 추가하거나(CVE 게이트 대응 우선순위 중 "자체 빌드") 기존 이미지의 빌드 정의를 바꿀 때만 참고한다. -security-catalog 레포에서 검증한 자체 빌드 프레임워크를 포팅했다. 현재 -`images/` 에 이미지 3종(`cloudnative-pg`, `cnpg-postgresql`, `etcd`)이 있고 -`docker.io/paasup` 에 push 되어 카탈로그 values 가 이 태그를 참조한다. 아래는 -프레임워크가 어떻게 동작하는지와, 이미지를 추가·변경할 때 지켜야 할 규칙이다. +security-catalog 레포에서 검증한 자체 빌드 프레임워크를 포팅했다. 자체 빌드 이미지는 +`images//` 에 있고(목록은 그 디렉토리가 단일 출처) `docker.io/paasup` 에 push 되어 +카탈로그 values 가 그 태그를 참조한다. 아래는 프레임워크가 어떻게 동작하는지와, +이미지를 추가·변경할 때 지켜야 할 규칙이다. ## 원칙 1 — 오케스트레이션은 항상 하나, 이미지 종류는 몰라도 된다 @@ -49,8 +49,8 @@ security-catalog 레포에서 검증한 자체 빌드 프레임워크를 포팅 **배포판은 결정됐다(2026-08-07, `keycloak` 이미지 추가 PR).** 그전까지는 "security-catalog 의 SUSE BCI 단일화 결정을 이식하지 않았다" 는 미결 상태였다. `keycloak` 은 업스트림이 UBI9 기반이라 "업스트림과 최대한 동일하게" 와 정면으로 -충돌했고, **카탈로그 내 일관성을 우선**했다 — 기존 3종이 전부 BCI 이고 trivy 의 -SLES 15.7 커버리지가 양성 대조로 실측 확인돼 있다 +충돌했고, **카탈로그 내 일관성을 우선**했다 — 먼저 들어온 이미지들이 전부 BCI 이고 +trivy 의 SLES 15.7 커버리지가 양성 대조로 실측 확인돼 있다 (`doc/analysis/sles-oval-measurement.md`). - 이 정책과 "업스트림과 최대한 동일하게" 가 충돌하면 **무엇을 우선했는지와 왜인지를 diff --git a/.github/workflows/build-image.yml b/.github/workflows/build-image.yml index 63dcd61..dcd2ab9 100644 --- a/.github/workflows/build-image.yml +++ b/.github/workflows/build-image.yml @@ -2,10 +2,11 @@ name: self-build-image # 자체 빌드 이미지(images/, 실행기 scripts/build/build-hardened-image.sh)의 # 빌드·검증·스캔·게이트·카탈로그 반영을 자동화한다. security-catalog 의 동일 워크플로에서 -# 프레임워크만 포팅했다 — 아직 이 레포에 도입된 자체 빌드 이미지는 없다(images/ 디렉토리 -# 자체가 비어 있음). 게이트(scripts/pipeline/cve-gate.py)가 상위 태그·베이스 OS 교체로 -# 해소되지 않는 차단 CVE 를 찾으면 이 워크플로로 자체 빌드를 검토한다 — -# 절차: .claude/image-authoring.md +# 프레임워크를 포팅했고 이 레포 CI 에서 빌드→검증→게이트→push→카탈로그 브랜치 push 까지 +# 실제로 검증됐다(2026-08 기준). 대상 이미지 목록은 images/ 디렉토리가 단일 출처다. +# 게이트(scripts/pipeline/cve-gate.py)가 상위 태그·베이스 +# OS 교체로 해소되지 않는 차단 CVE 를 찾으면 이 워크플로로 자체 빌드를 검토한다 — +# 절차: .claude/image-authoring.md, 트리거·제약 요약: doc/sbom-pipeline.md 의 "자체 빌드" 절 # # "이미지가 어느 차트의 어느 필드를 가리키는가" 는 images//catalog.env 가 선언한다 # (CHART_DIRS·TAG_STYLE·TAG_BLOCK·DEFAULT_BASE_OS). 태그 표기 스타일이 두 가지다: diff --git a/CLAUDE.md b/CLAUDE.md index 77367ba..fc86cd5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -150,14 +150,20 @@ extract-helm-images.sh → generate-sbom.sh → scan-sbom.sh → cve-gate.py (scripts/pipeline/, .github/workflows/sbom.yml·cve-edge-post.yml 이 실행) ``` -- **현재 warn-only**: 게이트가 실패해도 CI/PR 을 막지 않는다. 45+ 개 카탈로그 차트가 +- **현재 warn-only**: 게이트가 실패해도 CI/PR 을 막지 않는다. 카탈로그 차트 전체가 이 게이트로 트리아지된 적이 없다. +- **CI 는 전 심각도로 스캔한다** — 게이트가 벤더 하향 등급·NVD 재평가·사각지대 판정에 + MEDIUM/LOW 까지 필요로 하기 때문이다. 스크립트 기본값(`HIGH,CRITICAL`)으로 만든 + 리포트로 게이트를 돌리면 판정이 달라진다. - 자체 빌드 프레임워크(`scripts/build/`, `.github/workflows/build-image.yml`)로 - `images/`에 이미지 3종(`cloudnative-pg`, `cnpg-postgresql`, `etcd`, 전부 - security-catalog 프로젝트에서 포팅)이 있으나 dip-catalog 자체 CI 로는 한 번도 - 실행된 적이 없다(빌드·게이트·push 모두 미검증 — 현재 참조 태그는 security-catalog - 쪽에서 이미 빌드된 것). 게이트가 상위 태그·베이스 OS 교체로 해소 안 되는 차단 CVE 를 - 찾으면 이 프레임워크로 자체 빌드를 검토한다 — 절차는 + `images//` 아래에 자체 빌드 이미지를 둔다(목록은 그 디렉토리가 단일 출처). + 최종 런타임 베이스 OS 는 SUSE BCI 로 통일하되 버전은 이미지마다 실측해서 고른다. + **push·카탈로그 반영을 동반하는 빌드는 + `workflow_dispatch` 수동 실행뿐이고**(`images/**` PR 은 검증 전용, `schedule` 없음), + `sbom.yml` 의 게이트가 이 워크플로를 자동 호출하지 않는다 — 자체 빌드로 갈지는 사람이 + 판단한다. 2026-08-04 에 `etcd`·`cloudnative-pg` 로 빌드→게이트→push→카탈로그 브랜치 + push 까지 실제 CI 에서 검증됐다. 게이트가 상위 태그·베이스 OS 교체로 해소 안 되는 차단 + CVE 를 찾으면 이 프레임워크로 자체 빌드를 검토한다 — 절차는 [.claude/image-authoring.md](.claude/image-authoring.md). - 상세: [doc/sbom-pipeline.md](doc/sbom-pipeline.md) · 승인 예외: `doc/cve-exceptions.json` · 현재 미결 사항: [MEMORY.md](MEMORY.md) diff --git a/MEMORY.md b/MEMORY.md index ac5bcd9..a16ee2c 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -5,7 +5,7 @@ - 프로젝트 개요·설계 원칙 → [CLAUDE.md](CLAUDE.md) - SBOM·CVE 게이트 메커니즘 → [doc/sbom-pipeline.md](doc/sbom-pipeline.md) -최종 갱신: 2026-08-03 +최종 갱신: 2026-08-07 --- @@ -18,9 +18,17 @@ 차단되는지 파악해야 한다. `gh workflow run helm-catalog-sbom --ref main`(또는 대상 브랜치)으로 전체 스캔 후 `cve-gate.md` 아티팩트를 확인한다. -**`doc/cve-exceptions.json` 이 비어 있다.** 첫 전체 스캔에서 차단 항목이 나오면 대응 -우선순위(상위 태그 교체 → 베이스 OS 교체 → 자체 빌드 → 예외 승인)를 검토하고, 예외는 -근거·만료일을 명시해 추가한다. +**`doc/cve-exceptions.json` 에 첫 예외가 들어갔다(2026-08-07, keycloak 자체 빌드).** +`CVE-2025-59250` — 트리비가 같은 mssql-jdbc jar 하나로 컴포넌트를 두 개 만들어 +(`13.2.1.jre11` from pom.properties / `13.2.1` from 파일명) 접미사가 잘린 쪽이 취약 +범위에 매칭된 **파싱 오탐**이다. 만료 2026-11-07. 이후 차단 항목이 나오면 같은 대응 +우선순위(상위 태그 교체 → 베이스 OS 교체 → 자체 빌드 → 예외 승인)를 지킨다. + +**keycloak 자체 빌드로 베이스 OS 정책이 확정됐다(2026-08-07).** SUSE BCI 로 통일하되 +**버전은 이미지마다 실측해서 고른다** — BCI 16.0 이 나와 있지만 SLE_BCI 의 +`java-21-openjdk-headless` 가 15.7 은 `21.0.12`, 16.0 은 `21.0.11` 이라 최신 베이스가 +오히려 CVE 를 남긴다. 상세: `.claude/image-authoring.md` 원칙 2, +`images/keycloak/README.md`. **커버리지 자가진단(`CoverageProbe`)을 security-catalog 에서 이식했다(2026-08-03).** `scan-sbom.sh` 가 os-pkgs findings 0건인 이미지의 SBOM 사본에 배포판별 센티널 패키지 @@ -48,11 +56,12 @@ etcd/1.1.12}/{custom-values,dip-values}.yaml` — etcd 는 `dip-values.yaml`에 `helm template`·`extract-helm-images.sh` 로 렌더링 결과까지 재확인했다. `DOCKERHUB_USER`/`DOCKERHUB_TOKEN` 은 `paasup` 조직에 push 권한이 있음을 이번에 확인했다(기존 "미확인" 상태 해소). 최종 런타임 베이스 OS 정책은 security-catalog 의 -SUSE BCI 고정 결정을 그대로 따랐다(ADR 자체는 미이관, 아래 참고). +SUSE BCI 고정 결정을 그대로 따랐고(ADR 자체는 미이관), 2026-08-07 keycloak 작업에서 +이 레포의 정책으로 확정됐다(위 참고). **남은 것: `SBOM_PIPELINE_IMAGE`(sbom.yml 이 쓰는 실행 컨테이너)는 이번 마이그레이션 대상이 아니다** — 여전히 `docker.io/wbsong111/sbom-pipeline:latest` 를 가리킨다. -이건 이미지 3종과 무관한 별개 결정(아래 미결 결정 참고). +이건 자체 빌드 이미지와 무관한 별개 결정(아래 미결 결정 참고). **`doc/decisions/`·`doc/analysis/` 디렉토리 자체가 dip-catalog 에 없다.** 포팅된 3개 이미지의 README·values 코멘트가 `doc/decisions/000X-*.md`, `doc/analysis/*.md`, @@ -73,11 +82,19 @@ requests/limits/storage 값을 근거로 표를 추가하는 별도 작업으로 않지만, `paasup` 네임스페이스로 이전할지는 별도 결정이 필요하다. **재빌드 + push + Repo Variable `SBOM_PIPELINE_IMAGE` 갱신은 git 커밋으로 되지 않는 수동 작업**이다. -**`build-image.yml` 의 `REGISTRY_HOST` 를 `docker.io/paasup` 로 설정했다.** 로컬에서 -`docker login docker.io` 로 로그인한 계정은 `docker.io/paasup` 에 push 권한이 있음을 -위 3종 이미지 push 로 확인했다. **단, 이건 로컬 자격증명 확인일 뿐이다** — GitHub -Actions 시크릿(`DOCKERHUB_USER`/`DOCKERHUB_TOKEN`)이 같은 계정/권한인지는 별도 확인이 -필요하다(`build-image.yml` workflow_dispatch 를 실제로 한 번 돌려봐야 안다). +**`build-image.yml` 의 `REGISTRY_HOST` 를 `docker.io/paasup` 로 설정했고, CI 에서 +동작을 확인했다(2026-08-04).** `workflow_dispatch` 로 `etcd`·`cloudnative-pg` 를 돌려 +레지스트리 로그인 → 빌드 → `verify.sh` → SBOM → 스캔 → 게이트 PASS → push → 카탈로그 +브랜치 push 까지 전부 성공했다(`build/etcd-20260804060806`, +`build/cloudnative-pg-20260804063006` 브랜치 생성 + `helm-catalog-sbom` PR 스캔 통과). +**GitHub Actions 시크릿(`DOCKERHUB_USER`/`DOCKERHUB_TOKEN`)이 `docker.io/paasup` push +권한을 갖는다는 것도 이때 확인됐다** — 기존 "로컬 자격증명만 확인" 상태 해소. + +**단, PR 자동 생성은 조직 정책으로 불가하다(실측 확정).** `GITHUB_TOKEN` 으로는 PR 을 +만들 수 없다(run 30882785612, GraphQL: "GitHub Actions is not permitted to create or +approve pull requests"). 리포 설정으로 못 바꾸는 제약이라 `gh pr create` 호출을 +워크플로에서 제거했고(`d449504`), 브랜치 push + Job Summary 의 compare 링크까지만 +자동화한다. **PR 오픈·병합 전 게이트 재확인·배포 검증은 사람의 몫이다.** --- diff --git a/doc/sbom-pipeline.md b/doc/sbom-pipeline.md index d914370..077cc0e 100644 --- a/doc/sbom-pipeline.md +++ b/doc/sbom-pipeline.md @@ -14,15 +14,39 @@ GitHub Dependency-Graph SBOM(예: `paasup_dip-catalog_199087.json`)은 pypi 등 이미지를 **한 번만 pull** 해서 SBOM 을 만들고, 취약점은 그 SBOM 에서 오프라인으로 뽑는다. -``` -extract-helm-images.sh generate-sbom.sh scan-sbom.sh -manifests/helm/** ──helm template──▶ images_final.tsv ──trivy image──▶ sbom/*.cdx.json ──trivy sbom──▶ trivy-summary.md - (오프라인·결정론) (이미지 1회 pull, 인증 필요) (CycloneDX) (오프라인·인증 불필요) + trivy-reports/ +```mermaid +flowchart TB + CAT[/"manifests/helm/**
차트 카탈로그"/] + + subgraph S1["① 인벤토리 추출  ·  오프라인 · 결정론"] + direction LR + EX["extract-helm-images.sh"] --> INV[/"images_final.tsv
chart ⇥ version ⇥ image"/] + end + + subgraph S2["② SBOM 생성  ·  네트워크 · 레지스트리 인증 필요 · 비용의 대부분"] + direction LR + GN["generate-sbom.sh"] --> SB[/"sbom/*.cdx.json
CycloneDX"/] + end + + subgraph S3["③ 스캔 · 게이트  ·  오프라인 · 인증 불필요 · 초 단위 반복 가능"] + direction LR + SC["scan-sbom.sh
+ CoverageProbe"] --> RP[/"trivy-reports/*.json
trivy-summary.md"/] + RP --> GT["cve-gate.py"] + GT --> VD[/"cve-gate.md
cve-gate.json"/] + end + + CAT -- "helm template" --> EX + INV -- "trivy image · 이미지 1회 pull" --> GN + SB -- "trivy sbom" --> SC + + classDef step fill:#dbeafe,stroke:#3b82f6,stroke-width:1.5px,color:#12305c + classDef art fill:#f1f3f5,stroke:#adb5bd,color:#212529 + class EX,GN,SC,GT step + class CAT,INV,SB,RP,VD art ``` -- **레지스트리 pull·인증은 SBOM 생성 단계 1곳으로 집중.** 취약점 스캔은 네트워크·인증 없이 빠르게 반복 가능 - (CVE DB 갱신 시 재pull 없이 재스캔). → 파이프라인 비용의 대부분은 SBOM 생성(이미지 pull)이고 스캔은 초 단위. -- 스캔 대상 이미지는 trivy 가 원격에서 받아 분석 후 폐기하므로 호스트/이미지 스토어에 남지 않는다. +**레지스트리 pull·인증을 ② 한 곳에 몰아둔 것이 이 구조의 핵심이다.** CVE DB 가 갱신돼도 재pull 없이 +③ 만 다시 돌리면 된다. 스캔 대상 이미지는 trivy 가 원격에서 받아 분석 후 폐기하므로 호스트에 남지 않는다. ## 스크립트 (`scripts/pipeline/`) @@ -34,10 +58,18 @@ manifests/helm/** ──helm template──▶ images_final.tsv ──trivy ima | `generate-sbom.sh` | `images_final.tsv` | `sbom/.cdx.json`, `sbom-index.tsv`, `sbom-gen.log` | | `scan-sbom.sh` | `sbom/` + `sbom-index.tsv` | `trivy-summary.{md,tsv}`, `trivy-reports/`, `trivy-run.log` | -주요 환경변수: `PARALLEL`(동시 처리, 기본 3), `LIMIT`(대상 상한, 0=전체 — 테스트용), -`SEVERITY`(기본 `HIGH,CRITICAL`), `TRIVY_CACHE_DIR`(캐시 디렉토리), `MERGE=1`(generate 시 -`catalog.cdx.json` 병합, cyclonedx CLI 필요). 사설 레지스트리 인증은 trivy 네이티브: -`TRIVY_USERNAME`/`TRIVY_PASSWORD`(단일) 또는 `DOCKER_CONFIG`(다중). +SBOM 생성 실패는 대부분 **사설/미인증 레지스트리이거나 대용량 이미지 timeout** 이다 — +`sbom-gen.log` 와 `render_status.tsv` 로 확인한다. + +주요 환경변수: `PARALLEL`(동시 처리 — generate 기본 3/이미지 pull 이라 보수적, scan 기본 4/오프라인이라 +높여도 안전), `LIMIT`(대상 상한, 0=전체 — 테스트용), `SEVERITY`(스크립트 기본 `HIGH,CRITICAL`), +`TRIVY_CACHE_DIR`(캐시 디렉토리), `MERGE=1`(generate 시 `catalog.cdx.json` 병합, cyclonedx CLI 필요). +사설 레지스트리 인증은 trivy 네이티브: `TRIVY_USERNAME`/`TRIVY_PASSWORD`(단일) 또는 `DOCKER_CONFIG`(다중). + +> **게이트를 돌릴 거라면 전 심각도로 스캔해야 한다.** `cve-gate.py` 는 벤더 하향 등급·NVD 재평가· +> 사각지대 판정에 MEDIUM/LOW 데이터까지 쓴다. `HIGH,CRITICAL` 만 스캔한 리포트로 게이트를 돌리면 +> 판정 자체가 달라진다. 그래서 CI 는 스크립트 기본값을 덮어쓴다 — `sbom.yml` 은 +> `UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL`, `cve-edge-post.yml` 은 `LOW,MEDIUM,HIGH,CRITICAL`. ### 로컬/컨테이너 실행 @@ -54,24 +86,17 @@ docker run --rm -v "$PWD:/repo" -w /repo \ ## 실행 이미지 (`scripts/pipeline/Dockerfile`) -파이프라인은 **도구가 설치된 컨테이너 안에서** 돈다. 그 이미지는 [scripts/pipeline/Dockerfile](../scripts/pipeline/Dockerfile)로 빌드한다. - | 항목 | 값 | |------|------| | 베이스 | `debian:stable-slim` (**glibc**) | | 포함 도구 | `helm`(v3) · `trivy` · `python3` · `bash` · `git` | | 아키텍처 | **linux/amd64** (GitHub 러너와 일치) | -| 현재 이미지 | `docker.io/wbsong111/sbom-pipeline:latest` (public) | - -> 재빌드 후 `paasup` 네임스페이스로 이전 예정 — 미완료(`MEMORY.md` 참고). Dockerfile 내용은 -> 안 바뀌었으므로 위 이미지는 이 마이그레이션으로 당장 깨지지 않는다. +| 현재 이미지 | `docker.io/wbsong111/sbom-pipeline:latest` (public) — `paasup` 네임스페이스 이전 미완료(`MEMORY.md`) | > **glibc(debian) 필수**: GitHub Actions 의 `container:` 안에서 `actions/checkout`·`upload-artifact` > (node 기반)가 동작하려면 glibc 이거나 node 가 있어야 한다. `aquasec/trivy` 같은 **alpine(musl) > 이미지는 node 실행 실패** → debian 사용. **amd64 필수**(러너 아키텍처). -### 빌드 & 푸시 - ```bash docker buildx build --platform linux/amd64 \ -t docker.io/paasup/sbom-pipeline:latest \ @@ -83,18 +108,24 @@ docker buildx build --platform linux/amd64 \ ## CI (`.github/workflows/sbom.yml`) -- **트리거** - - `workflow_dispatch` — 수동. 입력 `limit`(기본 0=전체, 테스트 시 예 `3`). - - `pull_request`(`manifests/helm/**`) — **변경된 차트의 이미지만** 증분 스캔(빠른 게이트). - - `schedule`(주 1회) — **전체** 스캔. -- **컨테이너**: `vars.SBOM_PIPELINE_IMAGE` 이미지에서 실행. -- **인증 구성 스텝**: 시크릿으로 `~/.docker/config.json`(인라인 토큰)을 만들어 `DOCKER_CONFIG` 로 trivy 에 전달. -- **아티팩트**: 스테이징 디렉토리(`report/`)로 모아 **상대경로**로 업로드(절대경로면 v4 가 전체 경로트리를 보존하므로). -- **스캔 주기 원칙**: 인벤토리·SBOM 은 차트 변경 시에만 바뀌지만 **취약점은 새 CVE 로 계속 변하므로 스케줄 전체 - 스캔이 필수**. PR 은 변경 차트만, 스케줄은 전체. -- **게이트**: 스캔 뒤 `scripts/pipeline/cve-gate.py` 로 판정(현재 `--warn-only`). +| 트리거 | 스캔 범위 | +|--------|----------| +| `workflow_dispatch` | 입력 `limit`(기본 0=전체) | +| `pull_request` (`manifests/helm/**`) | **변경된 차트의 이미지만** (빠른 게이트) | +| `schedule` (`0 18 * * 0`, 매주 일요일 18:00 UTC) | **전체** | -### 실행 +인벤토리·SBOM 은 차트 변경 시에만 바뀌지만 **취약점은 새 CVE 로 계속 변하므로 스케줄 전체 스캔이 필수**다. + +- **컨테이너**: `vars.SBOM_PIPELINE_IMAGE` 이미지에서 실행. +- **인증**: 시크릿으로 `~/.docker/config.json`(인라인 토큰)을 만들어 `DOCKER_CONFIG` 로 trivy 에 전달. +- **아티팩트**: 스테이징 디렉토리(`report/`)로 모아 **상대경로**로 업로드(절대경로면 v4 가 전체 경로트리를 보존). +- **게이트 판정 범위는 `--inventory` 가 정한다** — PR 증분에서는 `images_scan.tsv`(변경 차트 이미지만)라 + **그 PR 이 건드리지 않은 차트는 게이트가 보지 않는다.** 전체 판정은 스케줄/수동 실행에서만 나온다. + +> **Job Summary 는 축약본만 싣는다.** `$GITHUB_STEP_SUMMARY` 는 1MB 를 넘으면 잘리는데 카탈로그 전체 +> 스캔의 `cve-gate.md` 는 실측 2.2MB 라 실제로 잘렸다. 그래서 Summary 에는 `trivy-summary.md`(건수 표)와 +> `cve-gate-brief.md`(판정 요약)만 넣고, **CVE 상세는 아티팩트의 `cve-gate.md`** 에서 본다. +> `--artifact-name` 은 축약 리포트가 "상세는 이 아티팩트를 보라"고 안내할 때 쓸 이름이다. ```bash gh workflow run helm-catalog-sbom --repo /dip-catalog -f limit=3 # 빠른 검증 @@ -102,15 +133,26 @@ gh workflow run helm-catalog-sbom --repo /dip-catalog # 전체 gh run watch --repo /dip-catalog ``` +### 다른 워크플로 — `cve-edge-post.yml` + +같은 스크립트·같은 실행 이미지를 쓰지만 **목적이 다르다.** `(catalog, version, image)` 단위 취약점 +건수 + CRITICAL 설명을 **단일 JSON 으로 만들어 외부 엔드포인트 +(`https://edge.gke.paasup.io/api/v1/cve-scans`)로 POST** 한다(`X-CVE-API-Key`, Repo Secret `CVE_API_KEY`). +**게이트 판정은 하지 않는다.** + +- 트리거는 `workflow_dispatch` 뿐 — `chart`(빈 값=전체) · `limit` 입력. `schedule` 은 주석 처리 상태다. +- 이미지 하나가 여러 `manifests/helm///` 에서 재사용되면 그 조합 수만큼 항목이 중복된다 + (의도된 동작 — 소비 측이 카탈로그 단위로 집계한다). + ## CVE 게이트 (`scripts/pipeline/cve-gate.py`) 스캔이 끝나면 `cve-gate.py` 가 `trivy-reports/*.json` 을 판정한다: 고유 CVE 단위 집계, `max(벤더 등급, NVD 등급)` 실효 등급, `doc/cve-exceptions.json` 승인 예외 처리. 상세 판정 -로직·근거는 스크립트 자체의 모듈 docstring을 우선 참고한다. +로직·근거는 스크립트 자체의 모듈 docstring 을 우선 참고한다. -현재 `sbom.yml` 은 `--warn-only` 로 호출한다 — 게이트가 실패해도 워크플로/PR 을 막지 -않는다. 45+ 개 카탈로그 차트가 아직 이 게이트로 트리아지된 적이 없어, 강제 전환 전에 -먼저 전체 스캔 1회로 현황을 파악해야 한다(`MEMORY.md`). +**`sbom.yml` 에서는 아직 `--warn-only` 다** — 게이트가 실패해도 워크플로/PR 을 막지 않는다. 카탈로그 +차트 전체가 아직 이 게이트로 트리아지된 적이 없어, 강제 전환 전에 먼저 전체 스캔 1회로 현황을 +파악해야 한다(`MEMORY.md`). `build-image.yml` 의 게이트는 이미 강제다. > **커버리지 자가진단(`CoverageProbe`).** `scan-sbom.sh` 는 os-pkgs findings 가 0건인 > 이미지의 SBOM 사본에 배포판별(deb/rpm/apk) 센티널 패키지를 주입해 재스캔하고, 발화 @@ -119,6 +161,49 @@ gh run watch --repo /dip-catalog > 유일한 수단이다(security-catalog 프로젝트에서 이식, 2026-08-03). 이 키가 없는 구버전 > 리포트는 findings 총계 0건이면 보수적으로 실패 처리하는 예전 경로로 판정한다. +## 자체 빌드 (`.github/workflows/build-image.yml`) + +게이트 대응 우선순위(상위 태그 교체 → 베이스 OS 교체 → **자체 빌드** → 예외 승인)의 세 번째 레버를 +실행하는 워크플로다. 대상은 `images//` 에 빌드 정의가 있는 이미지이고(목록은 그 디렉토리가 +단일 출처), 실행기는 `scripts/build/build-hardened-image.sh` 하나다 — 빌드 → `verify.sh` → SBOM → +`scan-sbom.sh` → `cve-gate.py` 를 순서대로 부른다(이 문서의 파이프라인을 그대로 재사용). +신규 이미지 추가 절차·계약(`build.env`/`catalog.env`)은 +[.claude/image-authoring.md](../.claude/image-authoring.md). + +> `sbom.yml` 과 별도 파일인 이유: `sbom.yml` 은 `vars.SBOM_PIPELINE_IMAGE` 컨테이너 안에서 도는데 +> 거기엔 docker/buildx 가 없다. 빌드는 호스트 러너여야 한다. + +| 트리거 | 대상 결정 | 빌드·검증·게이트 | 레지스트리 push | 카탈로그 태그 갱신 | +|--------|----------|------------------|-----------------|-------------------| +| `workflow_dispatch` | `image` 입력(필수) · `base_os`(비우면 `catalog.env` 의 `DEFAULT_BASE_OS`) · `push`(기본 `true`) | ✅ | `push=true` 일 때만 | 게이트 PASS + 태그 변경 시 | +| `pull_request` (`images/**`) | 변경된 `images//` 를 diff 로 자동 탐지(복수면 매트릭스 병렬) | ✅ | ❌ | ❌ | + +PR 트리거가 push 하지 않는 것은 `REGISTRY` 를 넘기지 않기 때문이다 — 태그가 `localhost/...` 로 남아 +push 를 시도할 수조차 없다(검증 전용 안전장치). + +- **`schedule` 트리거는 없다.** 블라인드 정기 재빌드는 "정말 개선인지"를 매번 되묻게 만들어 제거했다. +- **`sbom.yml` 의 게이트가 이 워크플로를 자동 호출하지 않는다.** 차단 CVE 를 찾아도 자체 빌드로 갈지는 + 사람이 판단해 수동 실행한다 — 두 워크플로 사이에 자동 연결은 없다. +- 레지스트리는 `REGISTRY_HOST: docker.io/paasup` 고정. 인증은 `DOCKERHUB_USER`/`DOCKERHUB_TOKEN`. + +### 카탈로그 반영 — PR 은 자동 생성되지 않는다 + +게이트 PASS 이고 새 태그가 현재 카탈로그 태그와 다르면, 워크플로가 `catalog.env` 의 `CHART_DIRS` 아래 +`custom-values.yaml`/`dip-values.yaml` 을 `scripts/build/patch-catalog-tag.py` 로 갱신하고 +`build/-<타임스탬프>` 브랜치를 push 한다. **여기까지가 자동이다.** + +PR 오픈은 사람이 한다 — `GITHUB_TOKEN` 으로 PR 을 만드는 것 자체를 조직 정책이 막는다("Allow GitHub +Actions to create and approve pull requests" 미허용, 리포 설정으로 변경 불가). 2026-08-04 실측으로 +확인했고(run 30882785612, GraphQL: `GitHub Actions is not permitted to create or approve pull requests`), +`gh pr create` 호출은 워크플로에서 제거했다. 대신 Job Summary 에 compare 링크가 남는다. + +병합 전에 사람이 해야 하는 것: + +1. compare 링크로 PR 오픈. +2. `gh workflow run helm-catalog-sbom --ref <브랜치>` 로 카탈로그 게이트 확인. +3. **배포 검증** — 게이트 PASS 는 "동작한다"를 증명하지 않는다(스캐너는 런타임 요구사항을 보지 못한다). + 절차: [.claude/deploy-test-procedure.md](../.claude/deploy-test-procedure.md). + ## GitHub 설정 (워크플로 활성화에 필요) `Settings → Secrets and variables → Actions` @@ -126,41 +211,46 @@ gh run watch --repo /dip-catalog | 종류 | 이름 | 용도 | |------|------|------| | **Variable** | `SBOM_PIPELINE_IMAGE` | 실행 이미지 태그 (예: `docker.io/wbsong111/sbom-pipeline:latest`) | -| Secret | `DOCKERHUB_USER` / `DOCKERHUB_TOKEN` | **docker.io + docker.getcollate.io rate limit 회피**. getcollate(openmetadata)는 Docker Hub 프록시라 익명 pull 시 rate limit(TOOMANYREQUESTS)에 걸림 → Docker Hub 자격증명으로 인증. pull 만 하므로 read-only PAT 권장 | +| Secret | `DOCKERHUB_USER` / `DOCKERHUB_TOKEN` | **docker.io + docker.getcollate.io rate limit 회피**. getcollate(openmetadata)는 Docker Hub 프록시라 익명 pull 시 rate limit(TOOMANYREQUESTS)에 걸림 → Docker Hub 자격증명으로 인증. `build-image.yml` 의 push 에도 같은 시크릿을 쓴다 | | Secret | `NGC_API_KEY` | **nvcr.io 인증**(NVIDIA nemo/nim — 없으면 pull 불가) | -| Secret | (필요 시) paasup 사설 레지스트리 자격증명 | `paasup/*` 이미지가 사설일 때 | +| Secret | `CVE_API_KEY` | `cve-edge-post.yml` 의 외부 엔드포인트 인증 | 추가 고려: + - `SBOM_PIPELINE_IMAGE` 가 **사설**이면 워크플로 `container:` 에 `credentials:` 추가 필요. - 저장소 Actions 활성화(org 정책). 서드파티 액션은 GitHub 공식(`checkout`·`upload-artifact`)만 사용. - `DOCKERHUB_TOKEN` 이 Docker Desktop 세션 토큰이면 만료 가능 → 장기적으로 **스코프 지정 PAT** 권장. ## 결과 확인 -1. **Job Summary** (권장) — Actions run 페이지 → Summary. `trivy-summary.md` 표가 렌더링된다. -2. **아티팩트** `sbom-and-vuln-report` — 아래 구조. `gh run download -n sbom-and-vuln-report -D ./out`. +`gh run download -n sbom-and-vuln-report -D ./out` ``` sbom-and-vuln-report/ ← 아티팩트 루트 -├── trivy-summary.md ← 취약점 요약(표) +├── trivy-summary.md ← 취약점 요약(차트별 표) ├── trivy-summary.tsv +├── cve-gate.md ← 게이트 판정 전문 (CVE 상세 전부 — 실질적인 트리아지 입력) +├── cve-gate.json ← 게이트 판정 결과(기계 판독용) ├── sbom-index.tsv ← 차트↔이미지↔SBOM 인덱스 +├── catalog.cdx.json ← MERGE=1 로 병합한 경우에만 ├── sbom-gen.log / trivy-run.log └── sbom/ ← 이미지별 상세 CycloneDX SBOM ├── .cdx.json └── ... ``` -### 요약(`trivy-summary.md`) 내용 +### 요약(`trivy-summary.md`) 읽는 법 -- **단계별 소요시간**: `SBOM 생성 소요`(이미지 pull, 주 비용) / `취약점 스캔 소요`(오프라인). 오해를 주던 단일 "총 소요"는 제거. -- **동적 심각도 컬럼**: 실제 스캔한 `SEVERITY` 만 표에 표시(기본 `CRITICAL`·`HIGH`). MEDIUM/LOW 는 스캔 안 하면 컬럼 자체가 없다. -- 차트·이미지별 집계 + 심각도별 총계. TSV 는 `chart⇥image⇥<심각도들>⇥status`(CRITICAL 이 첫 카운트 열). +- **단계별 소요시간**: `SBOM 생성 소요`(이미지 pull, 주 비용) / `취약점 스캔 소요`(오프라인). +- **심각도 컬럼은 실제 스캔한 `SEVERITY` 만** 나온다. CI 는 전 심각도라 컬럼도 전부 나오고, 로컬에서 + 스크립트 기본값으로 돌리면 `CRITICAL`·`HIGH` 두 컬럼만 나온다. +- **차트명 기준으로 묶고 차트마다 합계 행**을 붙인다. 이미지 하나가 여러 차트에 쓰이면(예: `busybox`) + 차트마다 한 행씩 나온다 — 그래야 차트 합계가 그 차트의 실제 노출을 뜻한다. +- TSV 는 `chart⇥image⇥<심각도들>⇥status`(CRITICAL 이 첫 카운트 열), `.md` 표와 같은 범위를 담는다. -### 첫 전체 실행 결과(참고, 2026-07-08) - -- SBOM 생성 **159/178**(19 실패 — 대부분 사설/미인증 레지스트리 또는 대용량 timeout), 스캔 **145 전부 성공**. -- 취약점 합계 **CRITICAL 1,511 · HIGH 15,724**, 총 소요 약 20분(생성 19분 / 스캔 23초). +> **표에는 차트별 최신 버전만 나온다.** 카탈로그는 한 차트의 여러 버전을 동시에 보관하는 "버전 보관소"라 +> 전 버전을 표에 실으면 읽을 수 없게 된다. **구버전도 스캔·게이트 판정은 전부 받는다** — 다만 그 결과는 +> `cve-gate.md`/`cve-gate.json` 에만 있다. 요약 표에 안 보인다고 판정 대상에서 빠진 것이 아니다. ## 렌더 함정 (extract 단계, 스크립트에 내장) @@ -177,23 +267,20 @@ trivy 병렬 실행 시 공유 캐시 bolt 잠금 충돌을 피하려 워커는 원시 CVE 수를 0으로 만드는 것이 목표가 아니다. **고칠 수 있고, 악용 가능하고, 노출된** 것부터 대응한다. 1. **우선순위**: fix 가능(`--ignore-unfixed`) → KEV/EPSS(실제 악용) → 노출도(인터넷 vs 내부) → 심각도. -2. **대응 레버(모두 Git PR)**: 차트/이미지 **버전 업**(최고 레버리지) · **베이스 이미지 교체**(특히 미유지 `bitnamilegacy/*`) · - **소유 이미지(`paasup/*`, `wbsong111/*`) 재빌드** · 좋은 버전 선정 후 **digest 고정**. -3. **게이트·억제**: `scripts/pipeline/cve-gate.py` 가 고유 CVE·실효 등급 기준으로 판정한다(현재 - warn-only — 위 "CVE 게이트" 절 참고). 수용 CVE 는 `doc/cve-exceptions.json`(근거·만료일 명시). +2. **대응 레버(모두 Git PR)**: 차트/이미지 **버전 업**(최고 레버리지) → **베이스 이미지 교체**(특히 미유지 + `bitnamilegacy/*`) → **자체 빌드**(위 절) → 수용. 앞 레버로 안 되는 것만 다음으로 넘긴다. +3. 수용하는 CVE 는 `doc/cve-exceptions.json` 에 **근거·만료일을 명시**해 등록한다. 4. 새 CVE 는 계속 나오므로 스케줄 스캔으로 **추세 추적**. -향후 개선(요약을 행동 가능하게): 이미지별 **fixable(패치 존재) 집계** 컬럼, `.trivyignore` 지원, -소유/legacy/3rd-party **분류 컬럼**. - ## 운영 노트 — `:latest`/무태그 이미지 digest 고정 태그가 고정돼 있어도 내용물이 바뀌는 `:latest`/무태그 이미지는 재현성 저해 + 증분 스캔의 사각지대다. 정기 전체 스캔 대상에 항상 포함하고, 가능하면 **구체 버전 또는 digest(`@sha256:...`)로 고정**한다. 적용된 고정(2026-07-08 기준): + - `mlflow@1.9.0` postgresql → `bitnamilegacy/postgresql@sha256:42a8200d...` (legacy 에 v18 버전 태그 부재, latest 내용 digest 고정) - `vllm@0.0.11` vllm-openai → `vllm/vllm-openai:v0.24.0` -digest 고정은 재현성을 보장하지만 자동 보안 패치는 멈춘다. → 정기 스캔으로 새 CVE 를 감지하고 필요 시 digest 를 갱신한다. -`bitnamilegacy/*` 는 미유지 이미지이므로 중기적으로 legacy 탈피(대체 이미지)를 검토한다. +digest 고정은 재현성을 보장하지만 **자동 보안 패치는 멈춘다** — 정기 스캔으로 새 CVE 를 감지하고 필요 시 +digest 를 갱신한다. `bitnamilegacy/*` 는 미유지 이미지이므로 중기적으로 legacy 탈피를 검토한다. diff --git a/images/keycloak/README.md b/images/keycloak/README.md index bae510d..57182c0 100644 --- a/images/keycloak/README.md +++ b/images/keycloak/README.md @@ -69,10 +69,10 @@ Security Advisory 실측). 스캔 시점 trivy DB 에 아직 없어 게이트에 ### 베이스 OS 결정 배경 (image-authoring.md 원칙 2) -업스트림은 `ubi9` 빌더 + `ubi9-micro` 최종이다. 카탈로그의 기존 자체 빌드 3종 -(`cloudnative-pg`·`cnpg-postgresql`·`etcd`)이 전부 SUSE BCI 이고 trivy 의 SLES 15.7 -커버리지가 양성 대조로 실측 확인돼 있어(`doc/analysis/sles-oval-measurement.md`), -**"업스트림과 최대한 동일하게" 보다 카탈로그 내 일관성을 우선**했다. +업스트림은 `ubi9` 빌더 + `ubi9-micro` 최종이다. 카탈로그의 먼저 들어온 자체 빌드 +이미지들이 전부 SUSE BCI 이고 trivy 의 SLES 15.7 커버리지가 양성 대조로 실측 확인돼 +있어(`doc/analysis/sles-oval-measurement.md`), **"업스트림과 최대한 동일하게" 보다 +카탈로그 내 일관성을 우선**했다. **BCI 16.0 이 나와 있지만 15.7 을 쓴다 — 최신이 이 이미지에는 더 낡았다**(2026-08-07 실측). 필요한 나머지 패키지는 16.0 에도 전부 있지만 JDK 가 뒤처져 있다.