[npm][보안] provenance attestation이 안 붙을 때 GitHub Actions에서 먼저 볼 값

IT 리서치 노트

[npm][보안] provenance attestation이 안 붙을 때 GitHub Actions에서 먼저 볼 값

npm provenance attestation은 단순 뱃지가 아니라 패키지가 어디서 어떻게 빌드됐는지 추적 가능한 공급망 증거다. 2026년 6월 24일 기준 npm 공식 문서를 다시 보면, GitHub Actions의 trusted publishing에서는 provenance가 자동으로 붙을 수 있지만 몇 가지 조건을 정확히 맞춰야 한다. 실제 현장에서는 publish는 성공했는데 provenance만 안 붙는 경우가 자주 생긴다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무 적용 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

먼저 결론부터 말하면, provenance attestation 누락은 대개 다섯 곳에서 생긴다. trusted publisher 설정이 없거나, package.json의 repository URL이 실제 저장소와 다르거나, public repository가 아니거나, workflow에 id-token: write가 없거나, publish 후 검증을 안 해서 놓친 경우다. 이미 npm token 없이 배포하는 trusted publishing 절차를 써 본 상태라면, 이번 글은 그 다음 단계인 provenance 누락 점검표라고 보면 된다.

또 provenance는 publish 성공과 별개다. 패키지가 올라갔다고 자동으로 attestation이 붙었다고 보면 안 된다. GitHub Actions 쪽 권한, npm 설정, repository metadata, package visibility를 같이 맞춰야 하고, 배포 직후 npm audit signatures 같은 검증까지 해야 누락을 빨리 잡을 수 있다. GitHub Actions 권한을 넓게 주기 전에 GITHUB_TOKEN과 OIDC 권한 분리 글도 같이 보는 편이 좋다.

2. 어디서 실제로 막히는가

실무에서 가장 흔한 막힘은 publish 자체는 성공했는데 npmjs.com에 provenance가 안 보이거나, npm audit signatures 결과에서 provenance가 빠졌다고 나오는 경우다. 이때 많은 팀이 바로 npm CLI 버그나 registry 문제로 의심하지만, 공식 문서를 다시 읽으면 대부분은 조건 누락이다.

trusted publishing 문서는 자동 provenance가 public repository와 public package에서 trusted publishing을 쓸 때 기본으로 생성된다고 적고 있다. 즉 private repository에서 public package를 올리거나, traditional token으로 publish하거나, trusted publisher 설정이 잘못되어 있으면 provenance를 기대하기 어렵다. generating provenance statements 문서는 repository.url이 실제 publish 위치와 case-sensitive하게 맞아야 한다고도 명시한다.

또 GitHub Actions 쪽에서는 id-token: write가 빠진 상태로 publish는 되는데 provenance 조건이 깨지는 경우가 있다. trusted publishing이 OIDC 기반이므로 id-token 권한이 없다면 OIDC 토큰 교환 단계가 성립하지 않는다. 이럴 때 권한을 무작정 넓히기보다, 먼저 id-token과 publish 경로가 trusted publishing인지 확인해야 한다.

• 증상: 패키지는 올라갔는데 provenance 뱃지가 보이지 않는다.
• 실패: trusted publisher를 설정하지 않고 token publish만 계속 쓴다.
• 누락: package.json의 repository.url이 실제 저장소와 다르다.
• 막힘: workflow에 id-token: write가 없어 OIDC 경로가 성립하지 않는다.

증상	먼저 볼 값	실무 판단
publish 성공, provenance 누락	trusted publisher, public repo/package	조건 미충족을 먼저 의심한다
OIDC publish가 불안정하다	workflow permissions.id-token	id-token: write가 빠졌는지 본다
패키지 페이지와 GitHub 저장소 연결이 이상하다	package.json repository.url	실제 publish repo와 완전히 일치해야 한다

3. 실무 적용 순서

점검 순서는 네 단계면 충분하다. 첫째, npm 패키지 settings의 trusted publisher가 실제 GitHub organization, repository, workflow filename과 일치하는지 확인한다. 둘째, workflow에 id-token: write가 있는지 확인한다. 셋째, package.json의 repository.url이 publish를 수행한 public repository와 정확히 일치하는지 본다. 넷째, 배포 후 npm audit signatures와 npmjs.com provenance 화면으로 실제 attestation 존재 여부를 검증한다.

1. trusted publisher 설정의 organization, repo, workflow filename을 맞춘다.
2. workflow permissions에 id-token: write를 둔다.
3. package.json repository.url과 실제 저장소를 정확히 일치시킨다.
4. public repository / public package 조건을 확인한다.
5. 배포 직후 npm audit signatures로 provenance를 검증한다.

특히 전환기에는 traditional npm token이 남아 있는지 같이 본다. trusted publishing이 가능한데도 token publish가 fallback되면 provenance 생성 기대와 실제 경로가 달라질 수 있다. npm 문서도 trusted publishers를 우선 쓰고, token access를 제한하라고 권장한다.

package.json 확인 예시

{
  "name": "@example/pkg",
  "version": "1.2.3",
  "repository": {
    "type": "git",
    "url": "https://github.com/example/pkg.git"
  },
  "publishConfig": {
    "access": "public"
  }
}

이 확인 순서를 정해두면 provenance 누락 때 원인을 빠르게 좁힐 수 있다. 배포 실패가 아니라 증거 누락 문제이므로, publish 로그만 보는 것보다 metadata와 OIDC 경로를 같이 보는 편이 빠르다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 npm trusted publishers 문서의 automatic provenance generation 구간이다. 여기서 trusted publishing이면 provenance가 기본으로 붙는 조건을 확인해야 한다.

Trusted publishing 문서는 GitHub Actions trusted publishing에서 provenance가 자동으로 생성되는 조건을 보여 준다.

핵심은 '항상 붙는다'가 아니라는 점이다. trusted publishing, public repository, public package 같은 조건이 같이 맞아야 provenance가 자동으로 생성된다.

두 번째는 generating provenance statements 문서다. CLI 버전, repository 필드, 지원 CI provider 조건을 같이 확인하는 데 적합하다.

Prerequisites 구간은 npm CLI 버전, repository 일치, 지원 CI provider 같은 사전 조건을 한 번에 보여 준다.

즉 attestation이 안 붙으면 workflow YAML만 볼 것이 아니라 package.json의 repository와 npm CLI 버전까지 같이 봐야 한다.

세 번째는 viewing package provenance 문서다. 단순히 npmjs.com 화면만 보는 대신 CLI에서 실제로 검증하는 방법을 확인할 수 있다.

Viewing provenance 문서는 npm audit signatures로 provenance와 registry signatures를 확인하는 흐름을 보여 준다.

즉 배포가 끝난 뒤에는 패키지 페이지 확인과 함께 CLI 검증까지 해야 provenance 누락을 빨리 잡을 수 있다.

workflow 파일에서는 trusted publishing 전제가 맞는지 확인한다. 특히 GitHub Actions에서 provenance를 기대한다면 id-token: write와 public repo 조건을 빠뜨리기 쉽다.

GitHub Actions workflow 예시는 trusted publishing과 provenance를 기대할 때 먼저 볼 권한과 publish 단계를 보여 준다.

여기서 id-token 권한이 빠지면 OIDC 토큰 교환 단계 자체가 막힐 수 있다. 이 부분은 기존의 id-token: write 실패 원인 글과 바로 이어진다.

마지막 화면은 라이브 검증 순서를 요약한 CLI 예시다. provenance가 붙었다고 생각해도 실제로는 누락된 경우가 있으니, publish 직후에 확인 명령을 정해 두는 편이 낫다.

배포 직후에는 npm audit signatures와 패키지 메타데이터 확인을 같이 해 provenance 누락을 빨리 잡는다.

여기서 실패하면 publish 자체보다 조건 누락을 먼저 의심한다. repository URL, public repo 여부, trusted publisher 설정, id-token 권한이 대표적인 원인이다.

5. 주의사항과 리스크

첫 번째 리스크는 trusted publishing을 써도 provenance가 무조건 붙는다고 생각하는 것이다. 공식 문서는 public repository와 public package 조건을 분명히 적고 있다. 두 번째 리스크는 traditional token fallback을 허용한 채 provenance를 기대하는 것이다. 세 번째 리스크는 provenance가 붙었는지 사람 눈으로만 보고 CLI 검증을 안 하는 것이다.

CircleCI support나 private repository 같은 예외도 문서에 따라 달라질 수 있으니, 지금 내 workflow가 어떤 provider 위에서 돌고 있는지 먼저 확인하는 편이 좋다. 또 provenance가 있다고 해서 패키지 내용이 안전하다는 뜻은 아니고, 어디서 빌드됐는지 추적 가능한 증거가 생긴다는 뜻에 가깝다.

• trusted publishing이어도 public repo/public package 조건이 안 맞으면 provenance가 안 붙을 수 있다.
• token publish fallback은 provenance 기대를 깨뜨릴 수 있다.
• 배포 직후 CLI 검증을 안 하면 누락을 늦게 발견한다.

6. 결론

npm provenance attestation 누락은 대개 registry 장애보다 조건 누락이다. trusted publisher 설정, workflow의 id-token 권한, public repo 여부, package.json repository URL, 배포 후 검증 순서를 같이 보면 대부분의 원인을 빠르게 좁힐 수 있다.

• trusted publisher와 public repo 조건을 먼저 본다.
• workflow의 id-token: write를 확인한다.
• repository.url과 CLI 검증 명령까지 같이 점검한다.

provenance가 붙었는지 여부를 넘어 release audit 증거까지 묶고 싶다면 package provenance를 release audit에 넣을 때 npm audit signatures와 registry 화면을 같이 보는 체크리스트가 바로 다음 단계다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/viewing-package-provenance/