# 컨테이너 이미지에 서명하고 서명 없는 이미지 거부하기(cosign)

> 내 컴퓨터의 로컬 레지스트리에 작은 이미지를 올리고 cosign으로 서명해 검증합니다. SBOM 증명을 붙이고, 같은 태그로 다른 이미지를 덮어쓰면 검증이 실패하는 것과 서명 없는 이미지가 거부되는 것을 재현한 뒤, 다이제스트로 고정해 배포하는 게이트 스크립트로 마무리합니다.

- 주소: https://copyandrun.com/blog/cosign-image-signing-local-registry/
- 분야: DevSecOps
- 발행일: 2026-10-25
- 태그: cosign, 이미지 서명, 공급망, SBOM, Docker

이미지를 만든 쪽이 누구인지, 지금 받는 이미지가 그때 올린 것과 같은지를 서명으로 확인합니다. 로컬 레지스트리에 이미지를 올려 cosign으로 서명하고, 검증이 성공하는 것을 본 다음, 같은 태그에 다른 이미지를 덮어써서 검증이 실패하는 것과 서명 없는 이미지가 거부되는 것을 재현합니다. 마지막에는 검증을 배포 전 게이트로 만들어 실패하면 종료 코드 1로 멈추게 합니다.

이미지 안의 취약점을 찾는 일은 [Trivy로 컨테이너 이미지 취약점을 스캔하고 빌드 게이트 만들기](/blog/trivy-image-scan-gate/)에서, SBOM 만드는 법은 [취약한 의존성 스캔하고 CycloneDX SBOM 만들기](/blog/sca-sbom-practice/)에서 다룹니다. 이 글은 서명과 검증, 그리고 서명이 무엇을 보장하고 무엇을 보장하지 않는지를 다룹니다. 로컬 레지스트리는 http로 띄우는 실습용입니다. 실제 서비스의 레지스트리는 TLS와 인증을 붙여 운영합니다.

## 준비물

| 항목 | 버전 | 용도 |
|---|---|---|
| Docker | 29.5.3 (Docker Desktop) | 레지스트리, 이미지 빌드, 도구 실행 |
| cosign | 3.1.4 (Docker 이미지, 다이제스트로 고정) | 서명, 검증, 증명 |
| Syft | 1.55.0 (Docker 이미지, 다이제스트로 고정) | CycloneDX SBOM 생성 |
| registry | `registry:2` (다이제스트로 고정) | 로컬 이미지 저장소 |
| Docker Registry UI | joxit/docker-registry-ui 2.6.0 | 저장소와 태그를 브라우저로 보기 |
| Python, Flask | 3.12.10, 3.1.3 | 검증 결과 화면 |

명령은 Windows의 Git Bash에서 확인했고, 리눅스와 macOS에서는 실행하지 않았습니다. 예상 소요 시간은 30분 안팎입니다. cosign과 Syft는 설치하지 않고 Docker 이미지로 실행합니다. 이미지 다이제스트는 2026-10-26에 `docker inspect`로 확인한 값입니다.

이 글의 코드는 모두 본문에 실었고, 글 맨 위의 실습 코드 내려받기에서도 같은 파일을 받을 수 있습니다. 개인키(`cosign.key`)와 비밀번호는 첨부하지 않고 공개키(`cosign.pub`)만 첨부했습니다. 첨부한 공개키는 이 글을 쓸 때 만든 것이라, 직접 실습하면 3단계에서 자기 키 쌍을 새로 만들고 그 키로 서명과 검증을 합니다.

## 1. 레지스트리와 웹 UI 띄우기

<!-- files: docker-compose.yml -->

컨테이너 이름은 `cr-t10-`로 시작합니다. 레지스트리는 5390, 웹 UI는 5391 포트에 `127.0.0.1`로만 엽니다. 레지스트리 안쪽 포트도 5390으로 맞춰 둔 것은 아래 `lab.sh` 때문입니다.

```yaml
name: cr-t10

services:
  registry:
    image: registry:2@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373
    container_name: cr-t10-registry
    environment:
      REGISTRY_HTTP_ADDR: 0.0.0.0:5390
    ports:
      - "127.0.0.1:5390:5390"
    volumes:
      - data:/var/lib/registry

  ui:
    image: joxit/docker-registry-ui@sha256:bb5956a6b378706f1c3a92c947d0a0c606e280460cd9e37c0198caf46399c839
    container_name: cr-t10-ui
    environment:
      SINGLE_REGISTRY: "true"
      REGISTRY_TITLE: Local Registry (lab)
      NGINX_PROXY_PASS_URL: http://registry:5390
      SHOW_CATALOG_NB_TAGS: "true"
      SHOW_CONTENT_DIGEST: "true"
      DELETE_IMAGES: "false"
    ports:
      - "127.0.0.1:5391:80"
    depends_on:
      - registry

volumes:
  data:
    name: cr-t10-data
```

cosign과 Syft를 레지스트리 컨테이너와 같은 네트워크 공간에서 실행하면 컨테이너 안에서도 `localhost:5390`이 같은 레지스트리를 가리킵니다. 그러면 호스트와 컨테이너가 이미지 이름을 똑같이 쓸 수 있고, `localhost`는 cosign이 http 레지스트리로 허용하는 주소라서 별도 옵션이 필요 없습니다. 아래 파일을 `lab.sh`로 저장해 두고 `source`로 읽으면 `cosign`과 `syft` 명령이 이 컨테이너 실행으로 바뀝니다.

```bash
# 실습용 도구 함수. 다른 스크립트가 source 해서 씁니다.
# cosign, syft 를 설치하지 않고 Docker 이미지로 실행합니다.
# --network container:cr-t10-registry 는 레지스트리 컨테이너와 네트워크를 공유해서
# 컨테이너 안에서도 localhost:5390 으로 같은 레지스트리에 닿게 합니다.
REGISTRY=localhost:5390
COSIGN_IMG=ghcr.io/sigstore/cosign/cosign:v3.1.4@sha256:0f06154836d2de34f887a5c273506d52ca43edaa1d9e53e6510fa78a48f69c2d
SYFT_IMG=anchore/syft:v1.55.0@sha256:4cc92b64ca74ffca4c94d4c8fcc01f217731375300be14d0b6eeb2e82eaa110a

cosign() {
  MSYS_NO_PATHCONV=1 docker run --rm --user "$(id -u):$(id -g)" --tmpfs /tmp:rw,mode=1777 --network container:cr-t10-registry \
    -v "$PWD:/work" -w /work -e HOME=/tmp -e COSIGN_PASSWORD "$COSIGN_IMG" "$@"
}

syft() {
  MSYS_NO_PATHCONV=1 docker run --rm --user "$(id -u):$(id -g)" --tmpfs /tmp:rw,mode=1777 --network container:cr-t10-registry \
    -e HOME=/tmp -e SYFT_REGISTRY_INSECURE_USE_HTTP=true \
    -v "$PWD:/work" -w /work "$SYFT_IMG" "$@"
}
```

`--user`와 `--tmpfs /tmp`, `HOME=/tmp`는 컨테이너 안의 cosign과 Syft가 현재 폴더에 키 파일을 쓰고 임시 파일을 만들 수 있게 하는 설정입니다. 이 설정이 없으면 `open cosign.key: permission denied`나 `mkdir /.sigstore: permission denied`로 실패했습니다. 호스트의 `/var/run/docker.sock`은 마운트하지 않습니다.

```bash
docker compose up -d
curl -s localhost:5390/v2/_catalog
```

기대 출력은 아래 화면과 같습니다. 컨테이너 네 줄이 Started로 끝나고 저장소 목록은 비어 있습니다.

![레지스트리와 웹 UI 컨테이너가 시작되고 저장소 목록이 비어 있는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/01-registry-up.png)

## 2. 서명할 이미지 만들어 올리기

<!-- files: app.py, Dockerfile -->

파이썬 한 줄을 출력하는 작은 이미지를 만듭니다. 빌드 인자 `MSG`로 출력 문구를 바꿀 수 있게 해서, 뒤에서 내용이 다른 이미지를 쉽게 만듭니다.

```python
import os

print("service up:", os.environ.get("MSG", "no message"))
```

```dockerfile
FROM python:3.12-slim
ARG MSG="hello from the reviewed build"
ENV MSG=$MSG
COPY app.py /app.py
CMD ["python", "/app.py"]
```

```bash
docker build -q -t localhost:5390/demo/hello:1.0 .
docker push localhost:5390/demo/hello:1.0
docker inspect localhost:5390/demo/hello:1.0 --format '{{index .RepoDigests 0}}'
docker inspect localhost:5390/demo/hello:1.0 --format '{{index .RepoDigests 0}}' | cut -d@ -f2 > signed.digest
```

마지막 줄은 올린 이미지의 다이제스트를 `signed.digest` 파일에 저장합니다. 이후 단계에서 서명과 배포 기준으로 쓰는 값입니다. 이 값은 빌드할 때마다 달라지므로 아래 화면의 값 대신 자기 값이 나옵니다.

![이미지를 푸시하면 1.0 태그의 다이제스트(sha256:87d0fd15...)가 나오고 docker inspect의 값과 같은 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/03-build-push.png)

Docker가 containerd 이미지 저장소를 쓰면 올라가는 것은 이미지 하나가 아니라 인덱스(여러 플랫폼과 빌드 증명을 묶은 목록)이고, 위의 다이제스트는 그 인덱스의 값입니다. 클래식 저장소를 쓰는 Docker에서는 매니페스트 하나의 다이제스트가 나옵니다. 어느 쪽이든 `docker push`가 출력한 `digest:` 값이 서명 대상입니다.

## 3. 실습용 키 쌍 만들고 서명하기

키 쌍을 만들 때 비밀번호를 묻는데, 실습에서는 환경 변수 `COSIGN_PASSWORD`로 미리 넣습니다. 아래 값은 실습용 문자열이므로 실제 키에는 쓰지 않습니다.

```bash
source lab.sh
export COSIGN_PASSWORD=lab-only-password
cosign generate-key-pair
```

`cosign.key`(개인키, 비밀번호로 암호화)와 `cosign.pub`(공개키)가 생깁니다. 개인키는 서명하는 쪽만 가지고, 공개키는 검증하는 쪽에 배포합니다. 개인키를 저장소에 올리면 누구나 서명할 수 있게 되어 서명이 의미를 잃습니다. 이 글에서 만든 공개키는 아래와 같습니다.

```text
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwnJMC5gtWZGjgf4LeA3PHQiq++kh
P+3v/6gAQAU9Ez2bWuSNO6PmWuw5yNRn5OmJSxjdDvK1zT05ge8uUCCF+A==
-----END PUBLIC KEY-----
```

이 글은 keyless 서명(Sigstore 공개 인프라에서 단기 인증서를 받아 서명하는 방식)을 쓰지 않고 키 방식만 씁니다. keyless는 서명할 때 로그인한 계정 정보와 서명 기록이 공개 투명성 로그에 남기 때문에, 연습용 이미지라도 외부에 기록이 생깁니다. 로컬 실습에서는 이를 피하려고 키 파일로 서명하고 로그 업로드를 끕니다.

cosign 3.1.4에서는 이 부분이 이전 버전과 다릅니다. 서명 명령에 `--tlog-upload=false`만 붙였더니 `--tlog-upload=false is not supported with --signing-config or --use-signing-config` 오류가 났고, 오류 문구가 안내하듯 기본 서명 설정에는 투명성 로그 서비스가 들어 있습니다. 그래서 `--use-signing-config=false`를 함께 지정했습니다. 두 옵션 모두 실행 때 deprecated 경고가 나옵니다. 다음 버전에서는 옵션 이름이 바뀔 수 있으므로, 쓰는 버전의 `cosign sign --help`를 확인합니다.

```bash
DIGEST=$(cat signed.digest); REF=localhost:5390/demo/hello@$DIGEST
cosign sign --key cosign.key --use-signing-config=false --tlog-upload=false --yes $REF
```

서명은 태그가 아니라 다이제스트에 붙입니다. 태그로 서명해도 그 순간 태그가 가리키던 다이제스트에 서명하는 것이지만, 어느 이미지에 서명했는지가 명령에 남도록 다이제스트를 직접 씁니다.

## 4. 서명 검증하기

```bash
cosign verify --key cosign.pub --insecure-ignore-tlog=true $REF
curl -s localhost:5390/v2/demo/hello/tags/list
```

`--insecure-ignore-tlog=true`는 투명성 로그 항목이 없어도 통과시키는 옵션입니다. 이 옵션을 빼면 검증이 `failed to verify log inclusion: not enough verified log entries from transparency log: 0 < 1`로 실패했습니다. 로그에 올리지 않고 서명했기 때문입니다. 출력에는 `Existence of the claims in the transparency log was verified offline`이라는 줄도 나오지만, 로그를 건너뛰었다는 경고가 바로 위에 함께 나오므로 로그 검증이 실제로 이루어졌다는 뜻으로 읽으면 안 됩니다.

![검증이 성공하고 docker-manifest-digest가 서명한 다이제스트와 같으며, 태그 목록에 1.0과 sha256-87d0fd15... 형태의 서명 객체 태그가 생긴 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/04-sign-verify.png)

서명은 이미지 옆에 별도 객체로 저장됩니다. 태그 목록에 `1.0` 외에 `sha256-<다이제스트>` 이름의 태그가 생겼고, 이것이 서명 객체입니다. cosign 3.x는 서명을 Sigstore 번들 형식으로 저장하고, 레지스트리가 referrers API를 지원하지 않으면 이런 태그 이름으로 저장합니다. `registry:2`가 이 경우였습니다. 이전 버전 설명에 나오는 `sha256-<다이제스트>.sig` 태그가 아닙니다.

웹 UI에서도 같은 것이 보입니다. 저장소 하나에 태그는 세 개입니다(1.0, 서명 객체, 뒤에서 올릴 2.0).

![Repositories 화면에 demo/hello 저장소가 있고 태그가 3개로 표시되는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/02-registry-catalog.png)

태그 화면에서는 서명 객체 태그가 이미지 태그와 같은 목록에 나옵니다. Content Digest 열의 값은 이 UI에서 인덱스가 아니라 안쪽의 플랫폼 매니페스트 값으로 나오므로, `docker push` 출력의 값과 다르게 보일 수 있습니다.

![태그 목록에 1.0, 2.0과 함께 sha256-87d0fd15... 이름의 서명 객체가 1.2MB 크기로 보이는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/05-tags-signed.png)

## 5. SBOM을 만들어 서명된 증명으로 붙이기

Syft로 이미지의 구성 요소 목록을 CycloneDX 형식으로 만들고, `cosign attest`로 그 목록에 서명해 이미지에 붙입니다. 서명이 "이 이미지를 이 키로 승인했다"는 뜻이라면, 증명은 "이 이미지의 구성 요소 목록은 이것이다"를 서명으로 묶은 것입니다.

```bash
syft registry:$REF -o cyclonedx-json=sbom.cdx.json
python -c "import json; d=json.load(open('sbom.cdx.json')); print(d['bomFormat'], d['specVersion'], len(d['components']), 'components')"
cosign attest --key cosign.key --use-signing-config=false --tlog-upload=false --yes \
  --type cyclonedx --predicate sbom.cdx.json $REF
cosign verify-attestation --key cosign.pub --insecure-ignore-tlog=true --type cyclonedx $REF | cut -c1-110
```

Syft는 레지스트리에서 직접 읽으므로 `registry:` 접두어를 붙이고, http 레지스트리라서 `lab.sh`에서 `SYFT_REGISTRY_INSECURE_USE_HTTP=true`를 지정했습니다. 이 이미지는 구성 요소가 2748건으로 나왔습니다. 마지막 줄은 증명의 본문(payload)을 한 줄로 출력하므로 `cut`으로 앞부분만 봅니다.

![SBOM이 CycloneDX 1.7 형식으로 2748개 구성 요소를 담고, 증명 검증의 확인 항목 세 줄과 payload가 나오는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/06-sbom-attest.png)

## 6. 검증을 배포 전 게이트로 만들기

검증이 사람 눈에만 보이면 소용이 없으므로, 실패하면 종료 코드 1을 돌려주는 스크립트로 묶습니다. 서명 검증을 기본으로 하고, 환경 변수 `REQUIRE_SBOM=1`을 주면 SBOM 증명도 요구합니다. 통과하면 검증한 다이제스트를 `DEPLOY` 줄로 출력합니다. 태그로 검증했더라도 배포는 이 값으로 하라는 뜻입니다.

```bash
#!/usr/bin/env bash
# 배포 전 게이트: 서명(과 선택적으로 SBOM 증명)이 맞아야 종료 코드 0, 아니면 1.
# 사용법: ./verify_gate.sh <이미지 참조> [공개키 파일]
#   REQUIRE_SBOM=1 ./verify_gate.sh localhost:5390/demo/hello@sha256:...
set -u
cd "$(dirname "$0")"
. ./lab.sh

REF="${1:?usage: verify_gate.sh <image-ref> [public-key]}"
PUB="${2:-cosign.pub}"

if ! cosign verify --key "$PUB" --insecure-ignore-tlog=true "$REF" >/tmp/gate-verify.out 2>&1; then
  echo "GATE FAIL  signature  $REF"
  grep -E "^Error|no signatures|no matching" /tmp/gate-verify.out | head -3
  exit 1
fi
echo "GATE PASS  signature  $REF"

if [ "${REQUIRE_SBOM:-0}" = "1" ]; then
  if ! cosign verify-attestation --key "$PUB" --insecure-ignore-tlog=true \
       --type cyclonedx "$REF" >/tmp/gate-att.out 2>&1; then
    echo "GATE FAIL  sbom       $REF"
    grep -E "^Error|none of the attestations" /tmp/gate-att.out | head -3
    exit 1
  fi
  echo "GATE PASS  sbom       $REF"
fi

# 검증을 통과한 다이제스트를 알려 줍니다. 배포는 태그가 아니라 이 값으로 합니다.
DIGEST="$(grep -o '"docker-manifest-digest":"sha256:[0-9a-f]*"' /tmp/gate-verify.out | head -1 | cut -d'"' -f4)"
NAME="${REF%%@*}"                  # @sha256:... 제거
LAST="${NAME##*/}"
NAME="${NAME%/*}/${LAST%%:*}"         # :태그 제거
echo "DEPLOY     ${NAME}@${DIGEST}"
exit 0
```

서명 없는 새 릴리스(2.0)를 올려 게이트를 돌려 보고, 서명한 이미지는 SBOM 증명까지 요구해 봅니다.

```bash
docker build -q --build-arg MSG="release 2.0, not signed yet" -t localhost:5390/demo/hello:2.0 .
docker push -q localhost:5390/demo/hello:2.0
./verify_gate.sh localhost:5390/demo/hello:2.0; echo "exit=$?"
REQUIRE_SBOM=1 ./verify_gate.sh localhost:5390/demo/hello@$(cat signed.digest); echo "exit=$?"
./verify_gate.sh localhost:5390/demo/hello:1.0; echo "exit=$?"
```

![서명 없는 2.0은 no signatures found로 종료 코드 1, 서명한 다이제스트는 서명과 SBOM 모두 통과해 종료 코드 0이 나오는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/07-gate-unsigned.png)

서명이 없는 이미지는 `no signatures found`로 거부됩니다. 지금은 `1.0` 태그도 서명한 다이제스트를 가리키고 있어 통과합니다. 여기까지는 문제가 없어 보입니다.

## 7. 발견: 같은 태그로 다른 이미지를 올리면

같은 `1.0` 태그에 내용이 다른 이미지를 덮어씁니다. 레지스트리 계정이 탈취되었거나, 빌드 파이프라인이 오염되었거나, 단순한 실수로도 일어나는 일입니다.

```bash
docker build -q --build-arg MSG="tampered build" -t localhost:5390/demo/hello:1.0 .
docker push -q localhost:5390/demo/hello:1.0
docker inspect localhost:5390/demo/hello:1.0 --format '{{index .RepoDigests 0}}'
./verify_gate.sh localhost:5390/demo/hello:1.0; echo "exit=$?"
./verify_gate.sh localhost:5390/demo/hello@$(cat signed.digest); echo "exit=$?"
```

![1.0 태그가 새 다이제스트(sha256:ecef2568...)를 가리키며 게이트는 종료 코드 1로 실패하고, 처음 서명한 다이제스트로는 여전히 통과하는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/08-tamper.png)

덮어쓴 뒤의 `1.0`은 검증에 실패합니다. 웹 UI에서도 1.0 태그의 Content Digest가 바뀌었는데, 이전 화면에서 `sha256:f380ba2e...`였던 값이 `sha256:ab849c3a...`로 달라졌습니다.

![1.0 태그의 Content Digest가 변조 전과 다른 값으로 바뀌었고 서명 객체 태그는 그대로 남아 있는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/09-tags-tampered.png)

## 8. 원인: 태그는 움직이는 이름이고 서명은 다이제스트에 붙는다

서명은 이미지 내용의 해시인 다이제스트에 붙습니다. 태그는 레지스트리에 쓰기 권한이 있으면 누구나 다른 다이제스트로 옮길 수 있는 이름표입니다. 그래서 검증이 실패한 것은 서명이 깨졌기 때문이 아니라, 새 다이제스트에 붙은 서명이 처음부터 없기 때문입니다. 서명은 오히려 정상 동작하고 있습니다.

| 참조 방식 | 예 | 가리키는 대상 | 덮어쓰기 영향 |
|---|---|---|---|
| 태그 | `demo/hello:1.0` | 지금 그 태그가 가리키는 이미지 | 내용이 바뀌어도 이름은 그대로라 알아채기 어렵습니다. |
| 다이제스트 | `demo/hello@sha256:87d0...` | 해시가 같은 이미지 하나 | 내용이 바뀌면 해시가 달라지므로 같은 참조로는 받을 수 없습니다. |

태그로 검증한 뒤 태그로 배포하는 절차에는 틈이 있습니다. 검증하는 순간과 이미지를 받는 순간 사이에 태그가 바뀔 수 있기 때문입니다. 게이트가 통과한 다이제스트를 `DEPLOY` 줄로 출력하는 이유가 이것입니다.

## 9. 수정: 검증한 다이제스트로 배포하기

수정은 간단합니다. 검증은 그대로 두고, 배포 설정(Kubernetes 매니페스트, compose 파일, 스크립트)에는 태그 대신 게이트가 알려 준 다이제스트를 씁니다.

```yaml
# 수정 전: 태그가 바뀌면 다른 이미지가 배포됩니다.
image: localhost:5390/demo/hello:1.0

# 수정 후: 서명을 검증한 다이제스트로 고정합니다.
image: localhost:5390/demo/hello@sha256:87d0fd151add24431496b8af19c74502d2db7f85ab0c31438f8ffc3d70d603d4
```

이 값은 위 단계에서 본 다이제스트이고, 자기 실습에서는 `signed.digest`의 값을 넣습니다. 다이제스트로 고정하면 덮어쓰기가 있어도 배포되는 이미지는 바뀌지 않고, 새 이미지를 배포하려면 서명과 검증을 거쳐 설정의 다이제스트를 바꾸는 변경 이력이 남습니다.

## 10. 재확인: 검증 결과를 화면으로 보기

같은 게이트를 세 가지 참조에 돌려 표로 보여 주는 Flask 앱입니다. 화면은 게이트 스크립트를 그대로 호출하므로, 표의 통과와 거부는 위 명령의 종료 코드와 같습니다.

```python
"""검증 결과를 표로 보여 주는 작은 웹 화면. 게이트 스크립트를 그대로 호출합니다."""
import html
import os
import shutil
import subprocess
import urllib.request
from pathlib import Path

from flask import Flask

HERE = Path(__file__).resolve().parent
REGISTRY = "localhost:5390"
REPO = "demo/hello"
MANIFEST_TYPES = ",".join([
    "application/vnd.oci.image.index.v1+json",
    "application/vnd.oci.image.manifest.v1+json",
    "application/vnd.docker.distribution.manifest.list.v2+json",
    "application/vnd.docker.distribution.manifest.v2+json",
])

app = Flask(__name__)


def tag_digest(tag):
    req = urllib.request.Request(
        f"http://{REGISTRY}/v2/{REPO}/manifests/{tag}",
        method="HEAD", headers={"Accept": MANIFEST_TYPES})
    try:
        with urllib.request.urlopen(req, timeout=5) as r:
            return r.headers["Docker-Content-Digest"]
    except OSError:
        return "-"


def run_gate(ref, sbom=False):
    env = {"REQUIRE_SBOM": "1" if sbom else "0"}
    p = subprocess.run([shutil.which("bash"), str(HERE / "verify_gate.sh"), ref],
                       capture_output=True, text=True, timeout=120, env={**os.environ, **env})
    return p.returncode, (p.stdout + p.stderr).strip()


@app.get("/")
def index():
    signed = (HERE / "signed.digest").read_text().strip()
    rows = [
        ("태그 1.0", f"{REGISTRY}/{REPO}:1.0", tag_digest("1.0"), False),
        ("다이제스트 고정", f"{REGISTRY}/{REPO}@{signed}", signed, True),
        ("태그 2.0 (서명 안 함)", f"{REGISTRY}/{REPO}:2.0", tag_digest("2.0"), False),
    ]
    body = []
    for label, ref, digest, sbom in rows:
        code, out = run_gate(ref, sbom)
        ok = code == 0
        same = "같음" if digest == signed else "다름"
        body.append(
            f"<tr><td>{html.escape(label)}</td>"
            f"<td><code>{html.escape(digest[:19])}...</code></td><td>{same}</td>"
            f"<td class='{'ok' if ok else 'bad'}'>{'통과' if ok else '거부'}</td>"
            f"<td>{code}</td></tr>")
    return f"""<!doctype html><meta charset="utf-8"><title>서명 검증 결과</title>
<style>
body{{font-family:'Malgun Gothic',sans-serif;margin:32px;color:#222}}
table{{border-collapse:collapse;min-width:760px}}
th,td{{border:1px solid #ccc;padding:9px 14px;text-align:left}}
th{{background:#f2f4f7}} .ok{{background:#dff5e1;color:#14692a;font-weight:700}}
.bad{{background:#fde1e1;color:#a11919;font-weight:700}} code{{font-size:13px}}
</style>
<h1>배포 전 서명 검증</h1>
<p>서명한 다이제스트: <code>{html.escape(signed[:19])}...</code></p>
<table><tr><th>대상</th><th>지금 가리키는 다이제스트</th><th>서명한 것과</th><th>게이트</th><th>종료 코드</th></tr>
{''.join(body)}</table>"""


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5392)
```

```bash
python -m pip install flask
python view.py
```

브라우저에서 `http://127.0.0.1:5392`를 엽니다. 게이트를 세 번 실행하므로 표가 나오기까지 10초 안팎 걸립니다. 아래는 2.0을 올린 직후, 1.0을 덮어쓰기 전에 연 화면입니다. 태그 1.0과 다이제스트 고정이 통과하고 서명 없는 2.0만 거부됩니다.

![덮어쓰기 전에는 태그 1.0과 다이제스트 고정이 통과하고 서명하지 않은 태그 2.0만 거부되는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/10-view-before.png)

1.0을 덮어쓴 뒤에 새로고침하면 태그 1.0의 다이제스트가 서명한 것과 달라지고 게이트가 거부합니다. 다이제스트로 고정한 참조는 그대로 통과합니다.

![덮어쓴 뒤에는 태그 1.0이 서명한 것과 다름으로 표시되며 거부되고 다이제스트 고정만 통과하는 것을 확인합니다.](https://copyandrun.com/img/cosign-image-signing-local-registry/11-view-after.png)

## 자주 막히는 곳

**`open cosign.key: permission denied`가 납니다**
컨테이너 안의 cosign이 현재 폴더에 쓰지 못하는 경우입니다. `lab.sh`의 `--user "$(id -u):$(id -g)"`가 있는지 확인하고, Git Bash에서는 `/c/...` 형태의 경로에서 실행합니다.

**`mkdir /.sigstore: permission denied`가 납니다**
컨테이너의 홈 폴더가 쓸 수 없는 위치일 때 나옵니다. `lab.sh`처럼 `-e HOME=/tmp`를 줍니다.

**검증이 `not enough verified log entries from transparency log: 0 < 1`로 실패합니다**
로그에 올리지 않고 서명했기 때문입니다. 실습에서는 `--insecure-ignore-tlog=true`를 붙입니다. 이 옵션은 투명성 로그 확인을 포기하는 것이므로 운영에서는 사용 정책을 따로 정해야 합니다.

**`no signatures found`가 서명한 이미지에서도 나옵니다**
태그가 다른 다이제스트를 가리키고 있을 수 있습니다. `docker inspect`로 태그의 다이제스트를 확인하고, `signed.digest`의 값과 비교합니다. 이 글의 7단계가 바로 이 상황입니다.

**Syft가 임시 폴더 오류로 빈 파일을 만듭니다**
처음 실행했을 때 `oci-registry: mkdir /tmp/stereoscope-...: permission denied`가 나오고 `sbom.cdx.json`이 0바이트로 만들어졌습니다. `lab.sh`의 `--tmpfs /tmp:rw,mode=1777`을 확인합니다.

**`python view.py`에서 게이트가 모두 실패합니다**
Windows에서 `bash` 이름이 Git Bash가 아니라 WSL의 bash를 가리킬 수 있습니다. 이 글의 `view.py`는 `shutil.which("bash")`로 PATH에서 찾은 실행 파일을 씁니다. 처음에 `["bash", ...]`로 호출했을 때는 `WSL ... execvpe(/bin/bash) failed`가 나왔습니다.

## 한계

- **서명은 이미지가 안전하다는 뜻이 아닙니다.** 키를 가진 쪽이 승인했다는 뜻일 뿐, 취약점이 없다는 보장이 아닙니다. 서명 전에 Trivy 같은 스캔을 게이트에 넣습니다.
- **개인키가 유출되면 모든 서명이 무의미해집니다.** 이 글의 키는 파일과 실습용 비밀번호로 보호할 뿐입니다. 실제 환경에서는 KMS나 하드웨어 키에 두고 교체 절차를 정해 둡니다.
- **투명성 로그를 쓰지 않았습니다.** 서명이 언제 만들어졌는지, 키가 폐기된 뒤에 만든 서명인지를 외부에서 확인할 근거가 없습니다. 이 글에서 로그를 끈 것은 연습용 기록이 공개 로그에 남는 일을 피하기 위해서이고, 운영에서는 이 선택을 다시 판단해야 합니다.
- **검증을 강제하는 곳이 없으면 아무 일도 일어나지 않습니다.** `docker pull`과 `docker run`은 서명을 확인하지 않습니다. 이 글의 게이트는 스크립트를 부른 경우에만 동작하며, 클러스터에서 서명 없는 이미지를 거부하는 정책 엔진은 실행하지 않았습니다.
- **로컬 레지스트리는 http로 열고 인증이 없습니다.** 실습용이며, 같은 컴퓨터에서만 열도록 `127.0.0.1`에 묶었습니다.
- **cosign 3.1.4 기준입니다.** 서명 옵션과 서명 저장 방식(번들 형식)이 버전마다 다르므로, 다른 버전에서는 같은 명령이 그대로 되지 않을 수 있습니다.

## 정리하기

실습이 끝나면 만든 것을 지웁니다. 아래 명령은 이 글에서 만든 이름만 지정합니다.

```bash
docker compose down -v
docker rmi localhost:5390/demo/hello:1.0 localhost:5390/demo/hello:2.0
rm -f cosign.key cosign.pub sbom.cdx.json signed.digest
```

Flask는 실행한 터미널에서 Ctrl+C로 끕니다.

## 이어서 해 볼 것

- 서명한 이미지를 `docker rmi`로 지운 뒤 `docker pull localhost:5390/demo/hello@sha256:...`로 다시 받아, 받은 이미지의 다이제스트가 같은지 확인합니다.
- `REQUIRE_SBOM=1`로 SBOM 증명이 없는 서명 이미지가 거부되는지, `cosign sign`만 한 새 이미지로 확인해 봅니다.
- 게이트를 CI에서 배포 직전 단계로 넣고, 통과한 `DEPLOY` 줄의 다이제스트로 배포 파일을 갱신하는 작업까지 이어 봅니다.

## 확인 범위

- **해 본 것:** 1~10단계 명령을 Windows의 Git Bash와 Docker Desktop(Docker 29.5.3)에서 직접 실행했습니다. cosign 3.1.4, Syft 1.55.0 이미지를 사용했습니다. 화면은 같은 실행에서 얻은 것입니다. 기본 서명 설정에 로그 서비스가 들어 있다는 것은 cosign의 오류 문구로 확인했습니다.
- **해 보지 않은 것:** Linux와 macOS에서의 실행. keyless 서명과 투명성 로그 업로드. cosign이 서명 중에 외부 서버에 접속하는지 네트워크 감시로 확인. 클러스터의 정책 엔진으로 서명을 강제하는 부분.
- **읽을 때 주의:** 이미지 다이제스트와 SBOM 구성 요소 수는 실행 때마다 달라질 수 있습니다.
