[npm][보안] package provenance incident를 볼 때 linked source repository, release record, staged approval evidence를 어떤 순서로 점검하나

IT 리서치 노트

[npm][보안] package provenance incident를 볼 때 linked source repository, release record, staged approval evidence를 어떤 순서로 점검하나

npm package provenance incident를 만났을 때 많은 팀이 바로 CLI verify 한 줄만 본다. 하지만 2026년 7월 25일 기준 npm 공식 문서를 다시 보면 package page의 linked source repository, registry provenance, release record, staged publish approve 단계는 서로 다른 층이다. 이 글은 provenance incident를 볼 때 어떤 층부터 어떤 순서로 점검해야 linked source mismatch, release record 누락, staged approval evidence 누락을 짧게 나눌 수 있는지 정리한 허브 글이다.

목차

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

1. 개요

결론부터 말하면 npm provenance incident는 package page와 linked source repository를 먼저 보고, 그다음 release record를 보고, staged publishing을 썼다면 마지막에 human approval evidence를 보는 편이 가장 빠르다. registry provenance가 붙었다는 사실과 팀의 release record가 충분한지는 다른 문제고, staged approve 기록은 또 한 단계 아래의 사람 통제층이다.

즉 허브 순서는 package page, registry proof, team record, staged approval evidence다. 이 사다리를 써 두면 linked source repository mismatch 글, release record template 글, staged approval evidence 글로 쉽게 내려갈 수 있다.

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

현장에서 가장 흔한 실패는 세 가지다. 첫째, package page의 linked source repository 표시가 어긋났는데도 release record만 본다. 둘째, registry provenance는 붙어 있는데 팀 release note와 release record가 비어 있다. 셋째, staged publishing을 썼는데 approve actor와 2FA 통제점을 기록하지 않았다.

npm 문서는 층을 분리해 둔다. viewing package provenance 문서는 package page와 provenance view를 설명하고, trusted publishers 문서는 provenance 자동 생성을 설명하고, staged publishing 문서는 review와 approve를 별도 단계로 설명한다. 이 세 문서를 합치면 provenance incident도 계층별로 나눠 봐야 한다는 결론이 나온다.

• 증상: provenance는 붙었는데 링크된 소스 repo나 팀 기록이 어긋난다.
• 실패: CLI verify 결과만 보고 incident를 종료한다.
• 막힘: release record와 staged approval evidence를 같은 층으로 본다.
• 누락: package page에서 독자가 먼저 보는 linked source repository 표시를 안 본다.

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

실무 순서는 다섯 단계가 좋다. 먼저 package page와 linked source repository 표시를 본다. 두 번째로 CLI verify와 registry provenance를 확인한다. 세 번째로 release record에 repository URL, source commit, audit verify, provenance detail URL이 있는지 본다. 네 번째로 staged publish를 썼다면 approve actor와 2FA confirmation을 본다. 마지막으로 빠진 층에 맞는 상세 runbook으로 내려간다.

현장에서는 package 화면을 열고 linked source repository 표시를 확인한 뒤, verify 명령 결과를 저장하고, release record 파일을 조회하고, approve 로그를 비교하는 식으로 움직이는 편이 안전하다. 같은 incident 메모 안에 패키지 화면, 명령 결과, release 파일, 승인 로그를 함께 저장하면 공급망 증거와 운영 기록을 나눠 설명하기 쉬워진다. 마지막에는 audit 파일과 응답 로그도 다시 확인하고 저장해 두는 편이 좋다.

1. package page와 linked source repository 표시를 본다.
2. CLI verify와 registry provenance를 확인한다.
3. release record 필드를 본다.
4. staged publish라면 approve actor와 2FA evidence를 본다.
5. 빠진 층에 맞는 상세 글로 내려간다.

package=@example/pkg
check_1=linked_source_repository_checked
check_2=npm_verify_saved
check_3=release_record_file_reviewed
check_4=staged_approval_log_checked
check_5=missing_layer_classified

이 구조를 잡아 두면 provenance 문제를 모두 supply chain proof 문제로만 몰아가지 않게 된다. registry proof는 멀쩡한데 package page 링크가 어긋난 경우도 있고, 반대로 proof는 붙었지만 팀 문서가 비어 감사나 회고가 어려운 경우도 있다. 허브 글은 그 차이를 먼저 짧게 자르는 역할을 맡는다.

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

첫 화면은 npm provenance 확인의 출발점이다. viewing package provenance 문서는 npmjs.com package page와 build provenance 정보를 운영자가 직접 확인하는 흐름을 설명한다.

npm viewing package provenance 문서는 package page에서 provenance를 확인하는 출발점을 제공한다.

따라서 incident triage도 CLI verify 이전에 package page와 linked source repository 표시부터 보는 편이 빠르다. 첫 화면이 이미 어긋나면 그 뒤 release record가 맞아도 독자가 보는 신호는 틀릴 수 있다.

두 번째 자료는 trusted publishers 문서의 provenance 자동 생성 구간이다. npm은 trusted publishing을 쓰면 provenance가 자동으로 생성된다고 설명한다.

trusted publishers 문서는 trusted publishing 경로에서 provenance가 자동 생성된다고 설명한다.

즉 자동 생성 자체는 출발점이지, release record와 staged approval evidence를 대신하지는 않는다. provenance가 붙었다는 사실과 팀이 남긴 운영 기록은 다른 층이다.

세 번째 자료는 staged publishing 문서의 approve 단계다. 이 구간을 봐야 staged publish incident에서 human approval evidence가 왜 필요한지 분명해진다.

staged publishing 문서는 approve 단계와 review 단계를 별도로 설명한다.

따라서 staged publishing을 쓰는 패키지는 linked source repository와 release record만으로 incident review를 끝내면 안 된다. approve 단계의 사람 기록과 2FA 통제점이 빠지면 provenance 설명이 반쪽이 된다.

허브 글의 핵심은 provenance incident ladder다. linked source repository mismatch, release record 누락, staged approval evidence 누락은 처음 보는 화면과 다음 액션이 다르다.

linked source repository, release record, staged approval evidence를 한 번에 나누는 허브 표다.

이 표를 기준으로 보면 linked source repository mismatch 글, release record template 글, staged approval evidence 글로 어느 순서에 내려갈지 빨라진다.

실무에서는 provenance triage note를 한 번 만들어 두는 편이 좋다. package page, release record, stage approval 흔적을 한 메모에 붙여야 증상이 어디 층인지 바로 보인다.

package provenance incident triage note 예시다.

이 메모 구조를 쓰면 registry 화면은 맞는데 release record만 비었는지, 아니면 staged approval evidence가 사라졌는지 바로 나뉜다.

마지막 자료는 review 순서다. provenance incident는 package page, team record, human approval을 같은 사다리로 읽을 때만 짧아진다.

package page, release record, staged approval evidence 순으로 비교하는 운영 순서다.

허브 글은 npm 공급망 보안의 모든 세부를 대신하지 않는다. 다만 어떤 증상이 어느 상세 글로 이어지는지 정하는 첫 순서를 제공한다.

5. 주의사항과 리스크

첫 번째 리스크는 package page 링크가 틀렸는데 verify 출력만 믿는 것이다. 두 번째 리스크는 release record가 비었는데 provenance가 붙었다는 이유로 운영 기록을 생략하는 것이다. 세 번째 리스크는 staged publish 승인 흔적이 없는데 trusted publisher 자동 증거가 모든 것을 대신한다고 생각하는 것이다.

운영 전에 최소한 linked source repository 상태, verify 결과, release record 필드, staged approval evidence를 같은 triage note에 붙여 두는 편이 좋다. 그래야 provenance incident가 registry proof 문제인지, 운영 기록 문제인지, human approval 문제인지 짧게 갈린다.

• package page와 registry proof는 다른 층이다.
• release record는 team-facing evidence 층이다.
• staged approval evidence는 human control 층이다.

6. 결론

npm package provenance incident를 짧게 풀려면 package page, registry proof, release record, staged approval evidence를 한 사다리로 봐야 한다. linked source repository부터 보고, release record를 보고, staged publish 승인 흔적까지 확인하면 같은 provenance 문제라도 어디가 비었는지 훨씬 빨리 자를 수 있다.

• linked source repository를 먼저 본다.
• registry provenance와 release record를 구분한다.
• staged publish를 썼다면 approval evidence를 따로 본다.
• 상세 대응은 linked source 글, release record 글, staged approval evidence 글, linked source recovery 순서 글 순으로 이어 읽으면 된다.

7. 참고 링크

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