npm·PyPI 게시 신원을 승인된 릴리스 아티팩트에 연결하기

무엇인가

2026년 10월 25일 기준입니다. trusted publishing은 영구적인 게시 토큰을 저장하는 대신 CI 신원을 임시 레지스트리 자격 증명으로 교환합니다. 릴리스 워크플로를 변경하기 전에 레지스트리가 지원하는 제공업체, 러너 제한 및 설정 요건을 다시 확인해야 합니다. 인용된 문서는 이번 검토를 위해 조회한 수시 갱신 참고 문서이며, 특정 날짜에 발표된 사고 권고문은 아닙니다.

npm 문서에 명시된 전제 조건은 npm CLI 11.5.1 이상과 Node 22.14.0 이상입니다. 이 글은 npm 패키지를 게시하거나 Python 배포물을 PyPI에 게시하는 GitHub Actions 워크플로에 초점을 맞춥니다.

왜 중요한가

PyPI의 보안 모델은 워크플로 무결성에 대한 책임이 게시자에게 있음을 명시합니다. 임시 자격 증명도 민감한 정보이며, 권한을 부여받은 워크플로가 침해되면 공격자가 이를 발급받을 수 있습니다. 저장된 토큰을 제거하면 자격 증명 노출은 줄지만, 의존성 실행이 안전해지는 것은 아닙니다.

npm의 출처 증명 문서는 소스 및 빌드 지침과의 검증 가능한 연결과 코드가 무해하다는 보장을 구분합니다. 운영상 의미는 명확합니다. 권한을 부여받은 파이프라인도 악성 아티팩트를 증명할 수 있습니다. 승인할 때는 서명하는 신원뿐 아니라 릴리스 입력 자료와 산출물도 평가해야 합니다.

적용 방법

• 의도한 소유자, 저장소 및 게시 워크플로를 정확히 등록합니다. npm의 GitHub 설정에는 워크플로 파일명을 입력하고, 선택 사항인 환경 이름은 보호된 게시 환경과 연결합니다. 이전 인증 경로를 제거하기 전에 설정된 신원을 실제 작업과 대조합니다.
• PyPI의 분리 방식을 따릅니다. 빌드 작업은 배포물을 생성하고, 작은 게시 작업은 이를 가져와 업로드합니다. OIDC가 필요한 작업에만 permissions: {id-token: write}를 부여합니다. 의존성 설치, 테스트 및 신뢰할 수 없는 변경 사항이 해당 작업의 권한을 사용할 수 없게 합니다.
• 환경 검토자를 설정하고, 자기 승인을 막으며, 릴리스 브랜치 또는 태그를 제한하고, 지원되는 경우 관리자의 우회를 비활성화합니다. 해당 저장소와 요금제에서 기능을 사용할 수 있는지 확인합니다. GitHub의 기본 설정은 관리자가 환경 보호를 우회하도록 허용하므로, 이름이 있는 환경을 만드는 것만으로는 충분하지 않습니다.
• 승인 대상을 구체적으로 지정합니다. 소스 리비전, 빌드 실행 및 아티팩트 다이제스트를 릴리스 기록에 남긴 다음 검토한 바이트 그대로 게시합니다. 증명에 담긴 신원과 소스 정보를 그 기록과 대조합니다. 출처 증명 배지를 릴리스 승인으로 받아들이지 말고 불일치를 조사합니다.
• 워크플로 코드와 타사 액션을 검토합니다. 저장소 토큰에 최소한의 권한만 부여하고 액션을 검토한 전체 commit 식별자로 고정합니다. 디버깅을 위해 자격 증명을 출력하거나 환경 전체를 덤프하지 않습니다. GitHub는 값이 변환된 경우 등을 포함하여 자동 로그 마스킹이 실패할 수 있다고 경고합니다. 성공한 실행뿐 아니라 실패 경로의 로그도 검사합니다.
• 전환 후에는 사용하지 않는 게시 토큰을 제거하고 trusted publisher 등록 내역을 점검합니다. PyPI 등록은 프로젝트에 속하며, 등록한 사람이 제거되어도 남아 있습니다. 유지관리자의 권한 회수 절차에 이 등록을 명시적으로 포함합니다.

함정

승인 절차가 있어도 승인자 계정이 침해되었거나 승인 절차 자체가 검토 없이 변경되었다면 이를 보완할 수 없습니다. 재사용 가능한 빌드 cache와 영구 러너는 각각 별도의 신뢰성 평가가 필요합니다. 신원 또는 아티팩트 검사에서 거부된 경우 릴리스 실패로 기록합니다. 이를 알리지 않고 저장된 쓰기 토큰으로 대체 인증하면 의도한 통제가 무너집니다.