npm Provenance + SLSA 실전 구축: GitHub Actions로 공급망 위변조 리스크를 줄이는 운영 가이드

발행일: 2026-03-05 | 카테고리: 개발정보

1) 문제 정의

Node.js 라이브러리를 배포하는 팀에서 가장 자주 놓치는 구간은 “누가, 어떤 커밋으로, 어떤 빌드 환경에서 배포했는지”를 검증하는 체계입니다. 릴리스 계정 탈취나 CI 토큰 오남용이 발생하면 정상 버전처럼 보이는 악성 패키지가 배포될 수 있습니다. 이 글은 GitHub Actions + npm registry를 사용하는 1~20명 규모 제품팀을 대상으로, 2주 내 도입 가능한 provenance 중심 배포 구조를 제시합니다. 반면 자체 아티팩트 레지스트리(사내 npm mirror)만 사용하는 폐쇄망 조직의 별도 서명 인프라는 범위에서 제외합니다.

2) 근거 및 비교

현장에서 선택 가능한 배포 무결성 전략은 크게 3가지입니다. 핵심 비교축은 비용·시간·검증강도·운영 난이도입니다.

• 비용: 추가 인프라 비용보다 사고 시 롤백·신뢰회복 비용이 더 큽니다.
• 시간: CI 워크플로우, 브랜치 보호, 릴리스 정책 정렬이 병목입니다.
• 정확도: “서명 여부”보다 “재현 가능한 빌드 출처 추적”이 중요합니다.
• 난이도: 배포권한 축소(least privilege)와 증빙 검증 자동화가 핵심입니다.

3) 단계별 실행 방법

1. D+1: 배포 권한 축소
   npm automation token을 제거하고, GitHub OIDC 기반 publish로 전환합니다.
2. D+2: 릴리스 브랜치 보호
   main 보호 + 필수 리뷰 1인 + required status check 2개(테스트/빌드) 적용.
3. D+3: provenance 활성화 배포
   npm publish 시 provenance를 활성화하고, 태그 기반 릴리스만 허용합니다.
4. D+4: SLSA 게이트 추가
   릴리스 전 attestation 존재 여부와 commit SHA 일치 여부를 검증해 불일치 시 차단합니다.
5. D+7: 소비자 검증 루틴 도입
   주요 의존 프로젝트에서 주간 1회 provenance 검증 리포트를 자동 생성합니다.

name: release
on:
  push:
    tags:
      - 'v*'
permissions:
  contents: read
  id-token: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci && npm test
      - run: npm publish --provenance --access public

4) 실수/함정(Pitfalls)

1. 실패 패턴: 태그 푸시 권한을 넓게 열어둠
   예방: 릴리스 태그 생성 권한을 Maintainer 1~2명으로 제한
   복구: 권한 재설정 후 최근 30일 릴리스 재검증
2. 실패 패턴: provenance 생성만 하고 소비자 검증 미구현
   예방: 배포 파이프라인에 “검증 실패 시 배포 중단” 게이트 삽입
   복구: 과거 버전 샘플링 검증 후 신뢰 등급 재분류
3. 실패 패턴: 릴리스 노트와 실제 SHA 불일치
   예방: release drafter에서 SHA 자동 주입 + 수동 수정 금지
   복구: 해당 버전 deprecate 후 정정 버전 재배포

5) 실행 체크리스트

• npm 장기 토큰이 제거되고 OIDC 기반 배포만 허용됐다.
• main 브랜치에 리뷰/상태체크 보호정책이 적용됐다.
• 태그 릴리스에서 npm publish --provenance가 강제된다.
• attestation SHA와 릴리스 SHA 자동 대조가 동작한다.
• 검증 실패 시 배포가 즉시 중단되고 알림이 전송된다.
• 주간 검증 리포트(성공률/실패원인/조치상태)가 남는다.

Definition of Done: 최근 4주 릴리스에서 provenance 검증 성공률 95% 이상, 수동 긴급배포 0건이면 완료로 본다.

6) 참고자료

• npm Docs - Generating provenance statements (확인일: 2026-03-05)
• GitHub Docs - OIDC로 배포 보안 강화 (확인일: 2026-03-05)
• SLSA Specification v1.0 Levels (확인일: 2026-03-05)
• SLSA Blog - Incremental Adoption Guide (확인일: 2026-03-05)

7) 작성자 관점(Author Viewpoint)

제 권장은 “OIDC 전환만으로 끝내지 말고, provenance 검증까지 파이프라인 안으로 넣는 것”입니다. 실제 사고는 배포 시점보다 사후 추적 실패에서 커집니다. 공개 패키지를 운영하는 팀이라면 2026년 기준 최소선은 태그 보호 + provenance + SHA 검증 자동화입니다. 반대로 하루 수십 회 실험 배포가 필요한 내부 서비스라면, 모든 릴리스에 최고 레벨 게이트를 거는 대신 프로덕션 대상 패키지에만 SLSA 강화정책을 선택적으로 적용하는 것이 현실적입니다.