-
[npm][보안] package provenance를 release audit에 넣을 때 npm audit signatures와 registry 화면을 같이 보는 체크리스트기타개발지식/풀스택개발 2026. 7. 2. 20:13
IT 리서치 노트
[npm][보안] package provenance를 release audit에 넣을 때 npm audit signatures와 registry 화면을 같이 보는 체크리스트
npm 패키지 배포에서 provenance를 켰다고 해도 release audit는 저절로 끝나지 않는다. 2026년 7월 2일 기준 npm 공식 문서를 다시 보면, provenance 자동 생성 조건, `npm audit signatures` 검증, registry 화면의 Build Environment와 Source Commit 확인, 필요할 때 `include-attestations`로 남기는 JSON 산출물이 서로 다른 역할을 가진다. 이 글은 package provenance를 release audit에 넣을 때 무엇을 어디까지 같이 봐야 하는지 체크리스트로 정리한 것이다.
1. 개요
결론부터 말하면 release audit에서 provenance는 세 층으로 보는 편이 안전하다. 첫째, trusted publishing과 public repository/public package 조건이 맞는지 본다. 둘째,
npm audit signatures로 verified attestations와 registry signatures를 확인한다. 셋째, npm registry provenance 화면에서 Build Environment, Source Commit, Public Ledger를 사람이 읽는다. 필요하면 여기에include-attestationsJSON 산출물을 더한다.이미 provenance attestation이 안 붙을 때 먼저 볼 값이 누락 원인을 다뤘다면, 이번 글은 provenance가 붙든 안 붙든 릴리스마다 어떤 증거를 남겨야 하는지에 더 가깝다. 또 Trusted Publishing 절차 글은 배포 경로 설명이라면, 오늘은 배포 직후 검증 경로 설명이다.
이번에 include-attestations JSON를 릴리스마다 얼마나 보관할지 정리한 글을 같이 보면, release audit 증거를 어디까지 남길지까지 이어서 설계할 수 있다.
2. 어디서 실제로 막히는가
실무에서 자주 꼬이는 지점은 세 가지다. 첫째, npm registry에 green check가 보이니 release audit가 끝났다고 생각한다. 둘째, 반대로
npm audit signatures만 PASS면 provenance 세부 정보는 안 봐도 된다고 생각한다. 셋째, registry signatures와 provenance attestations를 같은 것으로 취급한다.하지만 npm 문서는 trusted publishing 문서에서 provenance 자동 생성 조건을 따로 적고, generating provenance statements 문서에서 CLI 검증 명령을 따로 적고, viewing package provenance 문서에서 사람이 읽는 registry 상세 화면을 따로 설명한다. 또 registry signature 문서는 signing keys가 제공되는데 일부 패키지에 signature가 빠지면 에러가 날 수 있다고 설명한다. 즉 release audit는 단일 신호가 아니라 여러 층의 확인을 묶는 작업이다.
여기에 npm v11 config의
include-attestations가 추가된다. 일상 배포에서 이 옵션이 늘 필요한 것은 아니지만, 릴리스 승인 기록이나 사후 감사가 필요할 때는 full sigstore bundle을 JSON으로 남기는 것이 유용하다. 특히 팀이 공급망 검증을 문서화해야 하는 환경이라면 PASS/FAIL 한 줄보다 구조화된 산출물이 훨씬 낫다.- 증상: registry에 green check가 있는데도 release audit 증거가 빈약하다.
- 실패: provenance attestation과 registry signature를 같은 것으로 본다.
- 막힘: CLI PASS만 남기고 source commit, workflow run, ledger 링크를 안 남긴다.
- 누락: 심층 감사가 필요한데 attestation bundle JSON을 저장하지 않는다.
증상 먼저 볼 곳 판단 기준 provenance가 안 보인다 trusted publishing 조건 OIDC/public repo/public package가 맞는지 본다 CLI는 PASS지만 감사 근거가 부족하다 registry provenance 상세 화면 Build Environment와 Source Commit을 남긴다 추후 분쟁 대응이 필요하다 include-attestationsJSONbundle 보존 범위를 릴리스마다 결정한다 3. 실무에서 적용하는 순서
가장 실용적인 release audit 순서는 다섯 단계다. 먼저 이번 배포가 trusted publishing 조건을 만족했는지 본다. 두 번째로
npm audit signatures를 실행해 verified attestations와 verified registry signatures를 확인한다. 세 번째로 registry provenance 화면에서 Build Environment, Build Summary, Source Commit, Build File, Public Ledger를 눈으로 확인한다. 네 번째로 중요 릴리스라면npm audit signatures --json와include-attestations를 함께 써 산출물을 저장한다. 마지막으로 이 결과를 release note나 승인 기록에 연결한다.- trusted publishing 조건부터 확인한다.
npm audit signatures로 attestations와 registry signatures를 본다.- registry provenance 상세 화면을 사람이 읽는다.
- 필요한 릴리스만 attestation bundle JSON을 저장한다.
- 결과를 release note나 승인 로그에 연결한다.
핵심은 provenance를 '배포 성공 여부'가 아니라 '릴리스 증거 묶음'으로 보는 것이다. CLI는 기계 검증에 강하고, registry 화면은 사람이 읽는 감사 기록에 강하다. JSON bundle은 더 깊은 추적이 필요할 때를 대비한 보관층으로 두면 된다.
이 순서를 정해 두면 provenance 누락, registry signature 누락, source commit 불일치 같은 문제가 어느 층에서 생겼는지 더 빨리 분리할 수 있다. 특히 npm provenance를 팀의 release checklist에 처음 넣는 단계라면, 사람 읽기용 증거와 기계 검증용 증거를 같이 설계하는 편이 훨씬 낫다.
4. 공식 문서와 예시 화면으로 확인하기
첫 화면은 trusted publishing 문서의 provenance 자동 생성 조건이다. release audit에 provenance를 넣으려면 먼저 어떤 경우에 자동 생성이 성립하는지 다시 확인해야 한다.
즉 provenance audit은 '배포가 성공했는가'보다 '배포가 어떤 경로에서 이루어졌는가'를 보는 작업이다. 이미 Trusted Publishing 절차 글을 읽었다면, 이번 글은 배포 뒤 검증 레이어다.
두 번째 자료는 npm이 release audit 단계에서 바로 쓰라고 안내하는 검증 명령이다. provenance attestations는 `npm audit signatures`로 확인할 수 있다.
문서가 강조하는 포인트는 검증 명령이 npm registry 화면 대체재가 아니라는 점이다. CLI와 registry 둘 다 보는 편이 release audit에서는 훨씬 강하다.
세 번째 화면은 npm registry에서 provenance를 사람이 읽는 단계다. package page의 green check 뒤에서 Build Environment, Build Summary, Source Commit, Build File, Public Ledger를 확인할 수 있다.
release audit 관점에서는 CLI가 '있다/없다'를 확인하고, registry 화면이 '어디서 어떻게 만들어졌는가'를 설명해 준다. 둘을 같이 남겨야 나중에 감사 기록으로도 쓸 수 있다.
네 번째 자료는 npm v11 config 문서다. `npm audit signatures --json`와 함께 `include-attestations`를 쓰면 full sigstore attestation bundle까지 출력에 포함할 수 있다.
release audit가 단순 PASS/FAIL보다 더 깊은 검토를 요구한다면 이 옵션이 유용하다. 다만 평소 운영 로그는 너무 무거워질 수 있으니, 정기 릴리스 점검과 일상 배포 점검을 나눠 두는 편이 낫다.
다섯 번째 화면은 registry signatures 자체가 빠진 경우다. provenance만 보다가 registry signatures 누락을 놓치면 공급망 검증이 반쪽이 될 수 있다.
그래서 release audit에서는 attestation 존재 여부와 registry signature 존재 여부를 나눠 보는 편이 맞다. provenance가 있다고 registry signature 문제까지 사라지는 것은 아니다.
이 표는 릴리스 직후 무엇을 사람 눈으로 보고, 무엇을 CLI로 보고, 무엇을 JSON 산출물로 저장할지 구분하기 위한 것이다.
post 40이 provenance 누락 원인을 먼저 좁히는 글이었다면, 이번 표는 배포 성공 뒤에 남길 release audit 증거를 묶는 용도다.
마지막 자료는 실제 배포 직후 남길 짧은 release audit 메모다. 검증 레이어를 분리해 적어 두면 provenance와 registry signatures를 섞어 말하는 실수를 줄일 수 있다.
이 메모를 남겨 두면 누락 문제가 생겼을 때 post 40 같은 원인 분석 글로 되돌아가기도 쉽다. 또 GitHub OIDC claims 검증 글과 같이 보면 GitHub 쪽 증빙과 npm 쪽 증빙을 같은 release audit에 넣을 수 있다.
5. 주의사항과 리스크
첫 번째 리스크는 registry 화면의 green check만 보고 끝내는 것이다. 두 번째 리스크는 verified attestations 수치만 보고 source commit과 workflow run을 기록하지 않는 것이다. 세 번째 리스크는 registry signatures와 provenance attestations를 같은 지표로 오해하는 것이다.
운영 전에 최소한 CLI 출력, registry provenance 상세 확인 여부, JSON bundle 저장 여부를 구분해 두는 편이 좋다. 릴리스 규모가 커질수록 이 셋이 섞이면 나중에 감사 근거가 불분명해진다.
- CLI PASS와 registry provenance 상세 확인은 서로 대체재가 아니다.
- registry signatures와 attestations를 따로 기록한다.
- JSON bundle은 모든 배포가 아니라 중요한 릴리스 중심으로 남겨도 된다.
6. 결론
npm package provenance를 release audit에 넣으려면 trusted publishing 조건,
npm audit signatures, registry provenance 상세 화면, 필요할 때의 attestation bundle JSON을 따로 묶어 봐야 한다. 이 구조를 잡아 두면 provenance는 배포 뱃지가 아니라 실무 릴리스 증거로 바뀐다.- release audit는 CLI, registry, JSON 산출물의 세 층으로 본다.
- verified attestations와 registry signatures를 분리해 읽는다.
- 중요 릴리스는 provenance 상세 정보를 기록으로 남긴다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
