Skip to Content
문서아티팩트 검증

아티팩트 검증

앱 배포로 내려온 아티팩트를 Agent가 워크플로우 실행 전에 검사해요.
검사에 실패하면 워크플로우는 한 스텝도 실행되지 않고 잡이 실패로 끝나요.

검사는 두 단계예요.

단계확인하는 것신뢰 기점
체크섬전송 중 파일이 손상되지 않았는지Deplite 서버가 계산한 값
서명이 아티팩트를 내 CI가 만들었는지기기에 직접 둔 공개키 파일

체크섬은 서버가 알려준 값이라 서버를 신뢰하는 범위 안에서만 의미가 있어요.
서명은 기기에 있는 공개키로 확인하므로 서버를 신뢰하지 않아도 성립해요.

서명 검증에는 별도 도구가 필요하지 않아요.
cosign sign-blob --key가 만든 서명을 Agent가 직접 확인하므로 기기에 cosign을 설치하지 않아도 돼요.

공개키 준비

CI에서 사용할 키 쌍을 만들어요.

cosign generate-key-pair

cosign.key는 CI 시크릿 저장소에만 두고, cosign.pub은 배포 대상 기기마다 복사해요.

sudo install -D -m 0444 -o root -g root cosign.pub /etc/deplite/keys/app.pub

이 파일이 검증의 기준점이에요.
Deplite 서버가 바꿀 수 없는 값이어야 하므로 root 소유의 읽기 전용으로 두기를 권해요.

한 기기에서 여러 앱을 운영한다면 앱마다 <application_id>.pub 이름으로 둘 수 있어요.
해당 파일이 없으면 Agent는 app.pub을 사용해요.

워크플로우가 자체 검증 단계를 갖고 있다면 그 단계가 읽는 키 경로도 같은 파일로 맞춰주세요.
앱별 키만 두고 워크플로우는 app.pub을 가리키는 상태라면, Agent 검증이 성공하더라도 워크플로우 쪽에서 키를 찾지 못해 배포가 멈춰요.

릴리스에 서명 첨부

CI에서 아티팩트를 만든 뒤 서명하고, 릴리스를 만들 때 서명도 함께 등록해요.

cosign sign-blob \ --key cosign.key \ --tlog-upload=false \ --yes \ --output-signature app.tar.gz.sig \ app.tar.gz

--tlog-upload=false는 공개 투명성 로그에 릴리스 존재를 남기지 않는 설정이에요.
Agent는 이 로그를 조회하지 않으므로 두 방식 모두 그대로 검증돼요.

등록할 수 있는 키는 ECDSA(P-256/384/521)와 RSA(2048비트 이상)예요.
cosign generate-key-pair의 기본값인 ECDSA P-256을 그대로 사용하면 돼요.

Ed25519 키는 cosign이 sign-blob을 지원하지 않아 서명 자체를 만들 수 없으므로 등록 단계에서 거절돼요.

위 명령은 cosign v2 기준이에요.
v3부터는 sign-blob의 옵션이 달라지므로 cosign version으로 확인해주세요.

동작 모드

공개키 파일이 있는지가 기본 동작을 결정해요.

기기 상태릴리스 상태결과
공개키 있음서명 있음검증 후 배포
공개키 있음서명 없음잡 실패
공개키 있음서명이 맞지 않음잡 실패
공개키 없음서명 있음잡 실패 (아래 옵트인으로 완화 가능)
공개키 없음서명 없음배포하되 잡 로그에 미검증으로 남김

공개키를 한 번 두면 그 뒤로는 서명을 뺀 릴리스가 통과하지 못해요.
검증을 끄는 결정이 기기에만 남고 서버 쪽에서는 내릴 수 없도록 하기 위한 동작이에요.

환경변수

변수기본값설명
DEPLITE_ARTIFACT_VERIFYautorequire로 두면 검증할 수 없는 아티팩트를 항상 거부해요.
off는 서명 검사를 생략하며 체크섬 검사는 유지해요.
유효 값은 auto, require, off이고 대소문자를 구분하지 않아요. 알 수 없는 값은 auto로 처리해요.
DEPLITE_ARTIFACT_KEY_DIR/etc/deplite/keys공개키를 찾을 디렉토리예요.
DEPLITE_ARTIFACT_TRUST_SERVER_KEY꺼짐1로 두면 기기에 공개키가 없을 때 서버가 보낸 공개키로 검증해요.

DEPLITE_ARTIFACT_TRUST_SERVER_KEY는 서버가 보낸 키로 서버가 보낸 서명을 확인하는 방식이라 전송 중 변조는 잡지만, 서버 자체가 침해된 경우에는 도움이 되지 않아요.
공개키를 기기에 배치하기 전까지의 임시 수단으로만 사용해주세요.

워크플로우에서 검증 여부 확인

Agent가 어떤 검사를 끝냈는지 각 step에 환경변수로 알려줘요.

변수값
DEPLITE_ARTIFACT_SIGNATURE_VERIFIED서명을 실제로 검증했으면 1, 아니면 0
DEPLITE_ARTIFACT_CHECKSUM_VERIFIED체크섬을 실제로 대조했으면 1, 아니면 0

두 변수는 아티팩트를 내려받는 잡에서만 설정되고, 이 기능이 없던 이전 버전 Agent에서는 설정되지 않아요.
그래서 워크플로우에 자체 검증 단계를 남겨 두더라도 아래처럼 쓰면 새 Agent에서는 건너뛰고 이전 버전에서는 그대로 수행돼요.

if [ "${DEPLITE_ARTIFACT_SIGNATURE_VERIFIED:-0}" = "1" ]; then echo "agent already verified the signature" else cosign verify-blob --key "$APP_PUBLIC_KEY_FILE" ... fi

값은 Agent가 검증을 마친 뒤에 채우므로 워크플로우의 env: 블록이나 서버가 보낸 파라미터로는 바꿀 수 없어요.

이 변수로 건너뛸 수 있는 것은 검증 명령 자체예요.
워크플로우가 따로 확인하는 조건(공개키 파일이 있는지 등)은 그대로 실행되므로, 공개키 준비 섹션의 키 배치와 어긋나 있으면 여전히 그 지점에서 멈춰요.

잡 로그

검증 결과는 잡 로그의 system 스트림에 남아요.

  • artifact signature verified with local key /etc/deplite/keys/app.pub
  • artifact is unverified: the release carries no signature and there is no public key at ...
  • the public key sent by the server differs from ...; verifying with the local key

세 번째 메시지는 키 교체 중에 정상적으로 나타날 수 있어요.
어느 경우에도 검증은 기기의 공개키로 수행하므로 잡은 그대로 진행돼요.

키 교체

공개키를 교체하면 이전 키로 서명된 릴리스는 그 기기에서 더 이상 배포되지 않아요.
롤백 대상으로 남겨 둘 버전이 있다면 새 키로 다시 서명해 릴리스를 만든 뒤 기기의 공개키를 교체해주세요.

컨테이너 이미지 릴리스

컨테이너 이미지는 서명이 레지스트리에 함께 저장되므로 Agent가 아니라 워크플로우가 cosign verify로 확인해요.
이 경우에는 기기에 cosign이 필요해요.

레지스트리 접근에 쓰이는 단기 자격증명은 잡 로그에서 자동으로 가려지지만, 워크플로우에서 직접 출력하지 않도록 주의해주세요.
docker login에는 --password-stdin을 사용하기를 권해요.

관련 문서

최종 수정 일자: