[npm][보안] package provenance 점검 뒤 release record에 repository.url·Source Commit·CLI verify를 어떤 템플릿으로 같이 남기나

IT 리서치 노트

[npm][보안] package provenance 점검 뒤 release record에 repository.url·Source Commit·CLI verify를 어떤 템플릿으로 같이 남기나

npm package provenance를 점검하고 나서도 팀 문서에 무엇을 남겨야 하는지는 별도로 정해 두지 않으면 매 릴리스마다 증거 깊이가 달라진다. 2026년 7월 24일 KST 기준 npm 공식 문서를 다시 보면 provenance 상세 화면은 Source Commit, Build File, Build Summary, Public Ledger를 제공하고, trusted publishing 문서는 repository.url exact match와 자동 provenance 조건을 설명하며, CLI는 npm audit signatures로 registry signatures를 검증한다. 이 글은 provenance 점검 뒤 release record에 repository.url, Source Commit, CLI verify를 어떤 템플릿으로 같이 남기는 편이 좋은지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 npm provenance release record는 green check 한 줄로 끝내지 말고, publish path, repository.url exact match, Source Commit, Build File, npm audit signatures 결과를 함께 남기는 편이 안전하다. 사람 읽기용 registry UI와 기계 검증용 CLI를 분리해 적어야 다음 감사나 회고에서 근거가 남는다.

특히 rename, fork, transfer, linked source repository 경고 같은 문제가 있었던 저장소는 repository.url 정합성을 별도 필드로 남기는 편이 중요하다. Source Commit 링크만 남기면 왜 provenance가 흔들렸는지 설명이 모자라기 쉽다.

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

현장에서 자주 보는 실패는 세 가지다. 첫째, npmjs.com의 provenance badge나 UI 캡처만 남기고 CLI 검증 결과를 안 남긴다. 둘째, Source Commit은 적는데 repository.url exact match는 확인하지 않는다. 셋째, trusted publishing이 켜져 있다는 사실만 적고 실제로 이번 릴리스가 public repository와 public package 조건을 만족했는지는 빼먹는다.

하지만 npm 문서 구조를 같이 보면 필드가 다르다. trusted publishers 문서는 provenance가 자동 생성되는 조건과 repository.url exact match를 말한다. viewing provenance 문서는 Source Commit, Build File, Build Summary, Public Ledger 같은 사람이 읽는 필드를 제공한다. verifying registry signatures 문서는 npm audit signatures라는 기계 검증 층을 제공한다. 이 셋을 따로 남기지 않으면 release record가 매번 감에 의존하게 된다.

또 linked source repository 경고가 나중에 뜨는 저장소라면 '당시에는 문제없었다'는 사실을 문서로 남겨 두는 것도 중요하다. release record에 registry provenance 상세 링크와 CLI 결과와 repository.url match 여부가 있으면, 나중에 저장소 상태가 바뀐 뒤에도 원인 설명이 짧아진다.

• 증상: provenance는 봤는데 릴리스 문서마다 남는 증거가 다르다.
• 실패: registry UI 캡처만 남기고 CLI verify 결과를 생략한다.
• 막힘: Source Commit은 적지만 repository.url 정합성은 누락한다.
• 누락: trusted publishing의 전제 조건과 실제 릴리스 경로를 한 줄로 남기지 않는다.

누락된 항목	나중에 생기는 문제	왜 지금 남기나
repository.url exact match	fork·rename 뒤 provenance 경고 원인 설명이 길어진다	publish 당시 메타데이터 상태를 남기기 위해
npm audit signatures 결과	UI만 보고 승인했다는 기록만 남는다	기계 검증 결과를 함께 남기기 위해
Source Commit / Build File	어느 workflow와 커밋이 publish를 만들었는지 재추적해야 한다	후속 회고와 감사 재현성을 높이기 위해

3. 실무에서 적용하는 순서

가장 실용적인 release record 작성 순서는 다섯 단계다. 먼저 이번 릴리스가 trusted publishing, public repository, public package 조건을 만족했는지 적는다. 두 번째로 package.json의 repository.url이 실제 GitHub 저장소와 정확히 일치하는지 확인한다. 세 번째로 registry provenance 상세에서 Source Commit, Build File, Build Summary, Public Ledger를 적는다. 네 번째로 npm audit signatures 결과를 적는다. 마지막으로 linked source repository 경고 유무나 예외 메모를 한 줄 남긴다.

1. publish path와 자동 provenance 조건을 먼저 적는다.
2. repository.url exact match를 적는다.
3. Source Commit, Build File, Build Summary를 적는다.
4. npm audit signatures 결과를 적는다.
5. 예외 메모를 남긴다.

이 순서가 중요한 이유는 provenance badge만으로는 충분하지 않기 때문이다. UI는 사람이 읽기 좋지만, CLI 검증 결과가 없으면 registry signatures까지 확인했는지 알 수 없다. 반대로 CLI 결과만 남기면 어떤 workflow와 어떤 commit에서 publish가 만들어졌는지 사람이 빠르게 읽기 어렵다.

release record 한 장에 이 필드를 붙여 두면 linked source repository 경고가 나중에 생겨도 당시 릴리스의 신뢰 근거를 되짚기 쉽다. 특히 repository rename이나 transfer가 있었던 패키지는 release note보다 provenance release record가 더 긴 수명을 가진다.

실제 작성 순서는 더 단순하다. 먼저 package.json 파일에서 repository.url 값을 확인하고 복사한다. 그다음 npmjs.com provenance 상세 화면에서 Source Commit, Build File, Build Summary를 각각 열어 URL을 복사하고 release record에 붙여 넣는다. 이어서 터미널에서 npm audit signatures 명령을 실행하고 PASS 또는 오류 문구를 기록한다. 마지막으로 trusted publisher 설정 화면이나 workflow 파일 경로를 확인해 publish path 메모를 저장한다.

• package.json 파일에서 repository.url을 확인한다.
• registry UI에서 Source Commit과 Build File URL을 복사해 저장한다.
• 터미널에서 npm audit signatures 명령을 실행한다.
• 오류나 경고가 있으면 그대로 기록한다.
• release record 파일에 publish path와 verify 결과를 함께 저장한다.

check trusted publishing path
check repository.url exact match
copy Source Commit / Build File / Build Summary / Public Ledger
run npm audit signatures
write one-line exception note

이미 linked source repository 경고 글과 CLI verify와 registry UI 로그 순서 글이 조사 방법을 다뤘다면, 이번 글은 그 조사 결과를 release 문서에 어떤 형태로 남길지 정리하는 마무리 단계다.

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

첫 화면은 provenance가 어떤 조건에서 자동 생성되는지 다시 고정한다. npm trusted publishers 문서는 OIDC, public repository, public package 조건에서 provenance가 자동 생성된다고 설명한다.

npm trusted publishers 문서는 provenance 자동 생성 조건을 설명한다.

따라서 release record에도 단순히 green check만 적는 것이 아니라, 이번 릴리스가 그 조건을 실제로 만족했는지 함께 적어 두는 편이 안전하다.

두 번째 자료는 trusted publishing에서 자주 놓치는 메타데이터 조건이다. npm 문서는 GitHub publish에서는 package.json의 repository.url이 실제 저장소와 정확히 일치해야 한다고 적고 있다.

npm trusted publishers 문서는 package.json의 repository.url이 GitHub 저장소와 정확히 일치해야 한다고 설명한다.

즉 provenance 점검 후 release record에는 source commit 링크만 적을 것이 아니라 repository.url 정합성까지 적어 두는 편이 맞다. fork나 rename 이후에는 이 한 줄이 빠지면 원인 설명이 길어진다.

세 번째 화면은 npm registry provenance 상세에 어떤 필드가 실제로 보이는지 보여 준다. viewing provenance 문서는 Build Environment, Build Summary, Source Commit, Build File, Public Ledger를 제시한다.

npm provenance 상세 화면은 Source Commit과 Build File 같은 감사 필드를 제공한다.

release record가 실무에서 유용하려면 이 필드들을 어디서 확인했고 어떤 값을 남겼는지 같이 정리해야 한다. 그렇지 않으면 나중에 UI 캡처만 남고 판단 근거는 다시 찾아야 한다.

네 번째 자료는 CLI 검증 층이다. npm은 registry signatures를 npm audit signatures로 검증할 수 있다고 설명한다.

npm 문서는 npm audit signatures로 registry signatures를 검증할 수 있다고 설명한다.

이 값이 빠지면 registry UI의 provenance 상세만 보고 릴리스를 승인하게 된다. release record에는 사람 읽기용 UI와 기계 검증용 CLI를 함께 남겨야 하는 이유다.

release record는 필드 이름과 출처를 미리 고정할수록 좋다. repository.url, Source Commit, Build File, CLI verify 결과를 어떤 칸에 넣을지 정리해 두면 감사나 장애 회고에서 재사용하기 쉽다.

npm provenance release record에 어떤 필드를 어떤 출처에서 채울지 정리한 표다.

이미 CLI verify와 registry UI 로그 순서 글이 조사 흐름을 다뤘다면, 이번 표는 그 결과를 release 문서에 어떻게 남길지 정리한 후속편이다.

마지막 자료는 바로 붙여 쓸 수 있는 release record 템플릿이다. 필드를 글로만 설명하면 팀마다 누락이 생기기 쉬우므로, 템플릿 한 장을 두는 편이 안전하다.

package provenance release record 템플릿 예시다.

이 템플릿을 쓰면 provenance green check를 봤다는 사실만 남기지 않고, 어떤 URL과 어떤 CLI 결과를 근거로 승인했는지까지 같이 남길 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 provenance green check만 캡처하고 Source Commit과 Build File을 안 적는 것이다. 두 번째 리스크는 repository.url exact match를 안 적어 rename·fork 이후 설명이 길어지는 것이다. 세 번째 리스크는 CLI verify 결과를 안 적어 registry signatures 확인 여부가 사라지는 것이다.

팀 템플릿에는 최소한 publish path, repository.url match, Source Commit, Build File, Build Summary, Public Ledger, npm audit signatures, exception note 여덟 칸을 두는 편이 좋다. 이 정도만 있어도 provenance 회고가 훨씬 짧아진다. UI 캡처를 저장할 때는 어떤 화면에서 복사한 값인지 같이 적고, CLI 실행 결과는 터미널 출력이나 저장한 로그 파일 위치를 함께 남기는 편이 좋다.

• UI 캡처만으로는 기계 검증 결과가 남지 않는다.
• repository.url 정합성은 rename·fork 이후 특히 중요하다.
• release record는 배포 직후 상태를 남기는 문서여야 한다.

6. 결론

npm provenance release record는 badge 확인 메모가 아니라, publish path와 repository.url 정합성, Source Commit, Build File, npm audit signatures 결과를 한 장에 묶는 문서여야 한다. 이 틀이 있어야 provenance 조사 글에서 얻은 판단을 실제 릴리스 승인 기록으로 바꿀 수 있다.

• trusted publishing 조건과 publish path를 먼저 적는다.
• repository.url exact match와 Source Commit을 같이 남긴다.
• registry UI와 npm audit signatures 결과를 함께 남긴다.

팀이 staged publishing까지 쓰기 시작했다면 일반 provenance record만으로는 부족하다. 후속 글인 approval evidence와 2FA 확인 필드를 같이 남기는 staged publishing 글에서 stage submit 이후 승인 기록을 어떤 항목으로 덧붙일지 바로 이어서 정리할 수 있다.

7. 참고 링크

1. https://docs.npmjs.com/viewing-package-provenance/
2. https://docs.npmjs.com/verifying-registry-signatures/
3. https://docs.npmjs.com/trusted-publishers/