Chainguard Images

안전한 소프트웨어 공급망을 위해 Wolfi Linux 기반으로 빌드된 최소 제로-CVE 컨테이너 이미지.

시작하기

이미지 풀링

명령어	설명
`docker pull cgr.dev/chainguard/static:latest`	최소 정적 베이스 이미지 풀
`docker pull cgr.dev/chainguard/busybox:latest`	디버깅용 busybox 이미지 풀
`docker pull cgr.dev/chainguard/wolfi-base:latest`	셸 포함 Wolfi 베이스 이미지 풀
`docker pull cgr.dev/chainguard/python:latest`	Python 런타임 이미지 풀
`docker pull cgr.dev/chainguard/node:latest`	Node.js 런타임 이미지 풀
`docker pull cgr.dev/chainguard/go:latest`	Go 빌드 이미지 풀
`docker pull cgr.dev/chainguard/nginx:latest`	nginx 웹 서버 이미지 풀
`docker pull cgr.dev/chainguard/git:latest`	최소 git 이미지 풀
`docker pull cgr.dev/chainguard/jdk:latest`	Java JDK 이미지 풀
`docker pull cgr.dev/chainguard/rust:latest`	Rust 빌드 이미지 풀
`docker pull cgr.dev/chainguard/redis:latest`	Redis 서버 이미지 풀
`docker pull cgr.dev/chainguard/postgres:latest`	PostgreSQL 이미지 풀
`docker pull cgr.dev/chainguard/curl:latest`	최소 curl 이미지 풀

이미지 태그

명령어	설명
`:latest` 태그	가장 최신 빌드, 프로덕션 준비 완료
`:latest-dev` 태그	셸 및 패키지 관리자 포함 개발 변형
`:latest` `-dev` 이미지	apk, 셸, 디버깅 도구 포함
`cgr.dev/chainguard-private/IMAGE`	프라이빗/엔터프라이즈 이미지 레지스트리
다이제스트 고정 `@sha256:abc123...`	재현성을 위한 정확한 이미지 빌드 고정

이미지 사용

기본 사용법

명령어	설명
`FROM cgr.dev/chainguard/static:latest`	Dockerfile에서 정적 이미지 사용
`FROM cgr.dev/chainguard/python:latest-dev`	pip과 셸 포함 dev 변형 사용
`FROM cgr.dev/chainguard/node:latest AS build`	빌드 스테이지로 사용
`FROM cgr.dev/chainguard/go:latest AS builder`	컴파일용 Go 이미지 사용
`docker run --rm cgr.dev/chainguard/wolfi-base sh`	대화형 셸 실행
`docker run --rm -p 8080:8080 cgr.dev/chainguard/nginx`	nginx 서버 실행
`docker run --rm cgr.dev/chainguard/python -- python -c "print('hello')"`	Python 원라이너 실행

Go 멀티 스테이지 빌드

# 빌드 스테이지
FROM cgr.dev/chainguard/go:latest AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /server ./cmd/server

# 런타임 스테이지 - 디스트로리스, 셸 없음, 패키지 관리자 없음
FROM cgr.dev/chainguard/static:latest
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Python 멀티 스테이지 빌드

# pip 사용 가능한 빌드 스테이지
FROM cgr.dev/chainguard/python:latest-dev AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
COPY . .

# 런타임 스테이지 - 최소 Python, pip 없음, 셸 없음
FROM cgr.dev/chainguard/python:latest
COPY --from=builder /install /usr/local
COPY --from=builder /app /app
WORKDIR /app
ENTRYPOINT ["python", "-m", "myapp"]

Node.js 멀티 스테이지 빌드

# 빌드 스테이지
FROM cgr.dev/chainguard/node:latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 런타임 스테이지
FROM cgr.dev/chainguard/node:latest
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
ENTRYPOINT ["node", "dist/index.js"]

Java 멀티 스테이지 빌드

# 빌드 스테이지
FROM cgr.dev/chainguard/jdk:latest-dev AS builder
WORKDIR /app
COPY . .
RUN ./gradlew build --no-daemon -x test

# 런타임 스테이지
FROM cgr.dev/chainguard/jre:latest
COPY --from=builder /app/build/libs/app.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

탐색

Chainctl 작업

명령어	설명
`chainctl auth login`	Chainguard 인증
`chainctl auth login --headless`	헤드리스 환경에서 로그인
`chainctl auth configure-docker`	Chainguard 레지스트리를 사용하도록 Docker 구성
`chainctl images list`	사용 가능한 Chainguard 이미지 목록
`chainctl images repos list --group=GROUP_ID`	그룹의 이미지 리포 목록
`chainctl images diff IMAGE1 IMAGE2`	두 이미지 버전 비교
`chainctl images history cgr.dev/chainguard/python`	이미지 버전 히스토리 표시
`images.chainguard.dev` 브라우징	모든 이미지의 웹 카탈로그

이미지 검사

명령어	설명
`crane ls cgr.dev/chainguard/python`	이미지의 사용 가능한 태그 목록
`crane manifest cgr.dev/chainguard/python:latest`	이미지 매니페스트 보기
`crane config cgr.dev/chainguard/python:latest`	이미지 설정 보기
`docker inspect cgr.dev/chainguard/python:latest`	이미지 메타데이터 검사
`docker history cgr.dev/chainguard/python:latest`	이미지 레이어 보기
`dive cgr.dev/chainguard/python:latest`	이미지 레이어 대화형 탐색

검증

서명 검증

명령어	설명
`cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp='chainguard' cgr.dev/chainguard/python`	이미지 서명 검증
`cosign verify-attestation --type spdx cgr.dev/chainguard/python`	SBOM 증명 검증
`cosign verify-attestation --type vuln cgr.dev/chainguard/python`	취약점 증명 검증
`cosign tree cgr.dev/chainguard/python`	공급망 아티팩트 보기
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	SLSA 출처 검증

Cosign 검증 예시

# Chainguard 이미지의 서명 검증
cosign verify \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

# SBOM 증명 검증 및 출력
cosign verify-attestation \
  --type spdx \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest | jq -r '.payload' | base64 -d | jq .

# 취약점 스캔 증명 검증
cosign verify-attestation \
  --type vuln \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

취약점 스캐닝

명령어	설명
`grype cgr.dev/chainguard/python`	Grype로 이미지 취약점 스캔
`grype cgr.dev/chainguard/python --only-fixed`	수정 가능한 취약점만 표시
`trivy image cgr.dev/chainguard/python`	Trivy 스캐너로 스캔
`trivy image --severity HIGH,CRITICAL cgr.dev/chainguard/python`	높음/심각만 스캔
`docker scout cves cgr.dev/chainguard/python`	Docker Scout로 스캔
`chainctl images vulns cgr.dev/chainguard/python`	chainctl로 알려진 취약점 보기

Wolfi APK 관리

패키지 작업

명령어	설명
`apk update`	패키지 인덱스 업데이트 (dev 이미지에서)
`apk add curl`	패키지 설치
`apk add --no-cache python3 py3-pip`	인덱스 캐싱 없이 설치
`apk add --virtual .build-deps gcc musl-dev`	가상 빌드 의존성 설치
`apk del .build-deps`	가상 패키지 그룹 제거
`apk del curl`	패키지 제거
`apk list --installed`	설치된 패키지 목록
`apk search nginx`	사용 가능한 패키지 검색
`apk info python3`	패키지 상세 정보 표시
`apk info -L python3`	패키지의 파일 목록

커스텀 이미지 빌드

Melange 패키지 빌드

명령어	설명
`melange keygen`	패키지용 서명 키 생성
`melange build recipe.yaml --signing-key melange.rsa`	레시피에서 APK 패키지 빌드
`melange build recipe.yaml --arch x86_64,aarch64`	여러 아키텍처용 빌드
`melange bump recipe.yaml 1.2.3`	레시피에서 버전 범프

Melange 레시피 예시

package:
  name: myapp
  version: 1.0.0
  epoch: 0
  description: 커스텀 애플리케이션
  copyright:
    - license: Apache-2.0

environment:
  contents:
    packages:
      - build-base
      - go
      - ca-certificates-bundle

pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/org/myapp
      tag: v${{package.version}}

  - uses: go/build
    with:
      packages: ./cmd/myapp
      output: myapp
      ldflags: -s -w

  - uses: strip

Apko 이미지 빌드

명령어	설명
`apko build config.yaml tag output.tar`	YAML 설정에서 OCI 이미지 빌드
`apko publish config.yaml tag`	이미지 빌드 및 레지스트리에 푸시
`apko build config.yaml tag output.tar --arch x86_64,aarch64`	멀티 아키텍처 이미지 빌드
`docker load < output.tar`	빌드된 이미지를 Docker에 로드

Apko 설정 예시

contents:
  packages:
    - ca-certificates-bundle
    - wolfi-baselayout
    - myapp
  repositories:
    - https://packages.wolfi.dev/os
    - /path/to/local/packages

accounts:
  groups:
    - groupname: nonroot
      gid: 65532
  users:
    - username: nonroot
      uid: 65532
      gid: 65532
  run-as: 65532

entrypoint:
  command: /usr/bin/myapp

archs:
  - x86_64
  - aarch64

environment:
  APP_ENV: production
  PORT: "8080"

SBOM 및 출처

공급망 아티팩트

명령어	설명
`cosign download sbom cgr.dev/chainguard/python`	이미지 SBOM 다운로드
`syft cgr.dev/chainguard/python`	Syft로 SBOM 생성
`syft cgr.dev/chainguard/python -o spdx-json`	SPDX SBOM 생성
`syft cgr.dev/chainguard/python -o cyclonedx-json`	CycloneDX SBOM 생성
`cosign download attestation cgr.dev/chainguard/python`	모든 증명 다운로드
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	SLSA 출처 검증
`chainctl images vulns cgr.dev/chainguard/python`	알려진 취약점 보기

정책 시행

Kubernetes 어드미션 정책

# Sigstore Policy Controller - Chainguard 서명 요구
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: require-chainguard-signatures
spec:
  images:
    - glob: "cgr.dev/chainguard/**"
    - glob: "cgr.dev/chainguard-private/**"
  authorities:
    - keyless:
        url: https://fulcio.sigstore.dev
        identities:
          - issuerRegExp: ".*"
            subjectRegExp: ".*chainguard.*"
        ctlog:
          url: https://rekor.sigstore.dev

Kyverno 정책 예시

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-chainguard-images
spec:
  validationFailureAction: Enforce
  background: true
  rules:
    - name: check-image-registry
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "cgr.dev의 Chainguard 이미지만 허용됩니다."
        pattern:
          spec:
            containers:
              - image: "cgr.dev/chainguard/*"
            initContainers:
              - image: "cgr.dev/chainguard/*"

CI/CD 검증 파이프라인

# GitHub Actions - 배포 전 검증 및 스캔
name: Image Verification
on:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Install cosign
        uses: sigstore/cosign-installer@v3

      - name: Verify image signature
        run: |
          cosign verify \
            --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
            --certificate-identity-regexp="chainguard" \
            cgr.dev/chainguard/python:latest

      - name: Scan for vulnerabilities
        uses: anchore/grype-action@v0
        with:
          image: cgr.dev/chainguard/python:latest
          fail-on: high

모범 사례

멀티 스테이지 빌드 사용 — -dev 이미지(컴파일러와 패키지 관리자 포함)에서 빌드하고 최종 아티팩트만 최소 런타임 이미지로 복사합니다.
다이제스트로 이미지 고정 — 재현성을 보장하기 위해 프로덕션 배포에 태그 대신 @sha256:... 다이제스트를 사용합니다.
적절한 베이스 이미지 선택 — OS 의존성 없는 컴파일된 바이너리에는 static, 셸이 필요할 때는 wolfi-base, 인터프리터 언어에는 언어별 이미지를 사용합니다.
CI/CD에서 서명 검증 — 빌드 또는 배포 전에 항상 cosign으로 Chainguard 이미지 서명을 검증합니다.
제로-CVE 이미지도 스캔 — 검증 단계로 취약점 스캔을 실행합니다. Chainguard 이미지는 제로 결과를 반환해야 하며, 파이프라인이 정품 이미지를 사용하고 있음을 확인합니다.
-dev 변형은 빌드 스테이지에서만 사용 — -dev 이미지를 프로덕션에 배포하지 마세요. 공격 표면을 증가시키는 도구가 포함되어 있습니다.
nonroot로 실행 — Chainguard 이미지는 기본적으로 nonroot 사용자를 사용합니다. Dockerfile에서 root로 전환하지 마세요.
이미지 정책 시행 — Kyverno, OPA Gatekeeper, 또는 Sigstore Policy Controller를 사용하여 클러스터에서 컨테이너 레지스트리를 제한합니다.
SBOM 생성 및 저장 — 컴플라이언스와 감사 추적을 위해 Syft 또는 cosign을 사용하여 SBOM을 다운로드합니다.
이미지를 최신 상태로 유지 — Chainguard는 이미지를 자주 재빌드합니다. 최신 보안 패치를 적용하기 위해 정기적으로 다이제스트를 업데이트하세요.