[npm][보안] include-attestations JSON를 릴리스마다 얼마나 보관해야 하는지 감사 기준으로 정리

IT 리서치 노트

[npm][보안] include-attestations JSON를 릴리스마다 얼마나 보관해야 하는지 감사 기준으로 정리

npm provenance를 팀 릴리스 절차에 넣기 시작하면 `include-attestations` JSON을 모든 배포마다 남겨야 하는지부터 헷갈리기 쉽다. 2026년 7월 3일 기준 npm 공식 문서를 다시 보면 `include-attestations`는 `npm audit signatures --json` 출력에 full sigstore bundle을 실어 주고, registry provenance 화면은 사람이 읽는 감사 정보를 따로 제공한다. 이 글은 어떤 릴리스에서 bundle JSON까지 남기는 편이 맞는지 감사 기준으로 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 include-attestations JSON은 모든 릴리스에 기계적으로 남기는 것보다, 재검증 가능성을 요구하는 릴리스에 선택적으로 남기는 편이 효율적이다. 일상 릴리스는 npm audit signatures 결과와 registry provenance 링크만으로 충분할 수 있고, 보안 민감 변경이나 감사 대응 릴리스는 full bundle JSON까지 보관하는 편이 낫다. 중요한 것은 보관 여부를 릴리스 기준으로 문서화하는 일이다.

이미 package provenance release audit 글이 CLI·registry·workflow 증거 묶음을 다뤘다면, 이번 글은 그중 include-attestations 보관 깊이를 정하는 기준에 더 가깝다. 또 attestation 누락 원인 글과 같이 보면 '없어서 문제인 경우'와 '있지만 얼마나 오래 남길지의 문제'를 구분하기 쉽다.

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

실무에서 먼저 막히는 지점은 세 가지다. 첫째, provenance가 붙었으니 green check와 CLI PASS만 남기면 충분하다고 생각한다. 둘째, 반대로 모든 릴리스에 full bundle JSON을 남겨야 한다고 보고 저장소와 승인 문서를 불필요하게 무겁게 만든다. 셋째, registry signatures 오류와 provenance bundle 보관 문제를 같은 축으로 섞는다.

npm 문서는 include-attestations를 full sigstore bundle 포함 옵션으로 설명하고, provenance viewing 문서는 registry UI에서 Build Environment, Source Commit, Build File, Public Ledger를 별도로 보라고 안내한다. 즉 사람 읽기용 증거와 기계 재검증용 증거는 역할이 다르다. 모든 릴리스가 동일한 깊이의 증거를 요구하지 않는다는 뜻이기도 하다.

또 registry signatures 문서는 서명이 빠진 패키지가 있으면 CLI가 error를 낼 수 있다고 설명한다. 이런 예외 상황에서는 bundle 보관 여부보다 먼저 오류 원문과 registry 상태를 남겨야 한다. 그러니 retention 정책은 'bundle을 남길지 말지' 하나만이 아니라, 어떤 실패가 났을 때 어떤 층의 증거를 최소로 남길지까지 포함해야 한다.

• 증상: provenance는 붙었는데 감사 근거가 매번 다르다.
• 실패: 사람 읽기용 registry 정보와 JSON bundle을 같은 역할로 본다.
• 막힘: 모든 릴리스에 같은 깊이의 증거를 강제한다.
• 누락: missing signatures 같은 예외 상황의 raw CLI 기록을 안 남긴다.

상황	먼저 남길 것	JSON bundle 필요성
일상 배포	CLI 결과, registry 상세 링크	낮음
보안 민감 변경	CLI 결과, registry 상세, workflow run	높음
서명 누락/예외	CLI raw output, 오류 기록	선택이 아니라 추가 보강

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

가장 실용적인 기준은 네 단계다. 먼저 이번 릴리스가 단순 patch인지, 보안 민감 변경인지, 외부 감사 가능성이 있는지 분류한다. 두 번째로 모든 릴리스에서 npm audit signatures와 registry provenance 상세 확인은 기본으로 남긴다. 세 번째로 재검증 가능성이나 승인 추적이 필요한 릴리스만 --json --include-attestations 산출물을 저장한다. 마지막으로 missing signatures나 provenance 누락이 나면 bundle 보관 여부와 별개로 raw CLI 결과와 registry 상태를 보강한다.

1. 릴리스 중요도를 먼저 분류한다.
2. CLI 결과와 registry provenance 확인은 기본값으로 남긴다.
3. 감사성 릴리스만 JSON bundle을 저장한다.
4. 예외가 나면 raw CLI 결과와 registry 상태를 같이 보강한다.

이 구조를 잡아 두면 provenance를 '항상 켜야 하는 옵션'이 아니라 '어떤 릴리스에서 얼마나 깊게 증거를 남길지'의 문제로 다루게 된다. npm 문서가 CLI 검증 층과 registry 상세 층을 나눠 설명하는 이유도 같은 방향으로 해석할 수 있다.

명령 예시

npm audit signatures
npm audit signatures --json --include-attestations > audit-signatures.json
# release note에는 registry provenance 상세 링크도 함께 남긴다

중요한 점은 '왜 이번 릴리스에서 bundle을 남겼는지' 또는 '왜 남기지 않았는지'까지 메모하는 것이다. 그래야 나중에 릴리스별 편차가 생겨도 의도된 차이인지 누락인지 구분할 수 있다.

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

첫 화면은 npm v11 config 문서의 `include-attestations` 정의다. 이 옵션은 `npm audit signatures --json`과 함께 쓸 때 full sigstore bundle을 JSON 출력에 포함한다고 적혀 있다.

`include-attestations`는 verified package마다 full sigstore attestation bundle을 JSON에 실어 준다.

즉 이 옵션은 단순 PASS/FAIL 로그를 넘어, 나중에 다시 검증할 수 있는 증거 묶음을 남길지 말지를 결정하는 스위치다. 그래서 모든 릴리스에 무조건 켜는 문제보다 어떤 릴리스에 남길지가 먼저다.

두 번째 자료는 provenance 검증 문서의 `npm audit signatures` 구간이다. npm은 verified registry signatures와 verified attestations를 구분해 보여 준다.

npm은 `npm audit signatures`로 registry signatures와 provenance attestations 검증 결과를 따로 보여 준다.

이 차이가 retention 기준에도 중요하다. 단순 설치 무결성 확인만 필요한 릴리스라면 수치 로그와 registry 화면만으로 충분할 수 있지만, 공급망 감사나 사후 포렌식이 필요한 릴리스는 bundle JSON까지 남기는 편이 낫다.

세 번째 자료는 npm registry provenance 상세 화면 설명이다. 문서는 Build Environment, Build Summary, Source Commit, Build File, Public Ledger를 사람이 읽는 감사 정보로 제시한다.

registry provenance 상세 화면은 사람이 읽는 감사 정보 다섯 가지를 보여 준다.

즉 모든 증거를 꼭 JSON으로만 남길 필요는 없다. 사람이 바로 확인할 정보는 registry 화면 캡처나 링크 기록으로 충분할 수 있고, bundle JSON은 그보다 깊은 재검증이 필요한 릴리스에 쓰는 편이 효율적이다.

네 번째 화면은 registry signatures 누락 사례다. 문서는 registry가 signing key를 제공하는데 일부 패키지에 signature가 빠지면 CLI가 error를 낼 수 있다고 설명한다.

registry signatures 누락은 provenance badge와 별개로 따로 다뤄야 하는 실패 신호다.

그래서 retention 정책도 'provenance bundle만 남기면 끝'이 아니다. missing signature 같은 예외를 만났을 때 어떤 CLI 출력과 registry 증거를 같이 남길지 정해 두는 편이 좋다.

보관 기준은 릴리스 중요도별로 나누는 편이 실용적이다. 매일 배포와 보안 민감 배포가 같은 깊이의 증거를 요구하지는 않는다.

`include-attestations` JSON 보관 여부를 릴리스 성격별로 나눈 표다.

이 표를 기준으로 잡으면 증거가 항상 부족하거나 반대로 매번 과하게 무거운 산출물을 남기는 일을 줄일 수 있다.

release audit 메모에 최소 무엇을 남길지 체크리스트로 고정해 두면 팀마다 들쑥날쑥해지는 일을 줄일 수 있다.

`include-attestations`를 남길지 판단할 때 함께 보는 release audit 체크리스트다.

이미 package provenance release audit 글이 감사 항목 전체를 다뤘다면, 이번 체크리스트는 그중 JSON bundle 보관 기준을 더 좁혀서 정리한 것이다.

마지막 자료는 릴리스 노트에 남길 수 있는 간단한 기록 예시다. 필요한 릴리스에만 bundle을 붙이고, 아닌 경우는 왜 안 남겼는지도 적어 두면 좋다.

attestation bundle 보관 여부를 릴리스 메모에 남기는 예시다.

이 메모가 있으면 post 40처럼 누락 원인을 다시 볼 때도 '원래 이 릴리스는 bundle 보관 대상이었는가'를 빠르게 되짚을 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 JSON bundle이 있으면 registry provenance 상세 확인을 생략해도 된다고 보는 것이다. 두 번째 리스크는 반대로 registry green check만 캡처하고 재검증용 산출물을 전혀 남기지 않는 것이다. 세 번째 리스크는 missing signatures 같은 예외 상황을 일반 성공 케이스와 같은 템플릿에 밀어 넣는 것이다.

운영 전에 최소한 patch 릴리스, 보안 민감 릴리스, 예외 발생 릴리스 세 가지에 대해 어떤 증거를 남길지 표로 고정해 두는 편이 좋다. 같은 npm provenance라도 보관 깊이는 달라질 수 있다.

• CLI PASS와 registry 상세 화면은 서로 대체재가 아니다.
• JSON bundle은 재검증 필요성이 있을 때 가치가 커진다.
• 예외 릴리스는 raw CLI와 오류 기록을 더 먼저 챙긴다.

6. 결론

include-attestations JSON은 provenance를 더 깊게 보존하는 수단이지 모든 릴리스의 기본값은 아니다. 릴리스 중요도에 따라 CLI 결과, registry provenance 상세, full bundle JSON의 깊이를 나눠 두면 감사 근거는 충분히 남기면서도 절차가 과하게 무거워지지 않는다.

• 모든 릴리스의 기본값은 CLI 결과와 registry 상세 확인이다.
• 재검증이 필요한 릴리스만 bundle JSON을 남긴다.
• 보관 여부 자체를 릴리스 메모에 남긴다.

7. 참고 링크

1. https://docs.npmjs.com/cli/v11/using-npm/config/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/viewing-package-provenance/
4. https://docs.npmjs.com/verifying-registry-signatures/
5. https://docs.npmjs.com/trusted-publishers/