GitHub package firewall: 정책보다 먼저 npm 설치 경로를 확인해야 하는 이유

AI 코딩 에이전트에게 기능 구현을 맡겼는데, 작업 도중 새로운 npm 패키지를 설치한다면 무엇을 먼저 확인해야 할까. 패키지 이름이나 정책 화면의 스위치만 확인해서는 부족하다. 그 설치 요청이 실제로 어느 레지스트리로 나가는지가 출발점이다. GitHub package firewall은 기업 정책과 패키지 요청 경로를 연결하는 기능이지, 계정에서 기능을 켜는 순간 모든 개발 도구를 자동으로 감싸는 장치가 아니다.

공식 변경 기록의 발표 날짜는 2026년 10월 20일이며, 발표 시각을 한국 시간으로 바꾸면 10월 21일이다. 아래 내용은 10월 21일 수집한 공식 발표와 설정 문서를 기준으로 한다. 이 글에서 얻을 결과물은 도입 대상을 가르는 판단표와, 차단이 발생했을 때 예외를 어디까지 허용할지 정하는 운영 기준이다. 제품의 보안 성능 순위나 공격 탐지율을 제시하는 글은 아니다.

1. 정책과 요청 경로가 모두 갖춰져야 한다

공식 발표는 사용 절차를 두 부분으로 설명한다. 먼저 관리자가 기업 정책을 설정한다. 다음으로 에이전트나 CI/CD 호스트 등 각 엔드포인트가 공개 레지스트리에 직접 요청하는 대신 방화벽을 이용하도록 구성한다. 이 경로를 통과하는 패키지 목록 메타데이터 요청과 실제 패키지 다운로드를 정책에 따라 평가한다. 따라서 정책을 강화하는 일과 요청이 방화벽에 도달하게 만드는 일은 별도 작업이다. 공식 발표의 동작 설명

정책 설정과 요청 경로 설정은 별개다. 직접 연결은 방화벽을 통과하는 경로가 아니며, 이 그림은 실제 제품 화면이나 차단 시험이 아니다. 출처: github.blog/changelog/2026-10-20-github-package-firewall-in-public-preview.

개발자 노트북의 설정이 맞는다고 에이전트 작업 환경이나 CI 러너의 설정까지 같다고 단정할 수는 없다. 실행 환경별로 적용한 레지스트리 주소와 인증 비밀의 주입 위치를 확인하는 접근이 필요하다. 이것은 공식 구성 절차를 운영 점검으로 바꾼 이 글의 제안이다. 네트워크 차단을 통한 우회 방지까지 제품이 자동 보장한다는 뜻은 아니다. 정책 화면의 설정값과 실제 설치 요청의 경로는 서로 다른 확인 대상이다.

2. 계정과 생태계부터 도입 대상을 좁힌다

발표 기준 제공 대상은 GitHub Enterprise Cloud 고객이며 데이터 레지던시를 사용하는 Enterprise Cloud도 포함한다. 상태는 정식 출시가 아닌 공개 미리보기이고, 현재 지원 패키지는 npm뿐이다. 개인 계정이나 다른 패키지 생태계까지 기본 보호된다고 읽으면 안 된다. 미리보기 중에는 무료지만, 정식 출시 이후에는 Actions 청구와 비슷한 사용량 기반 과금이 예정되어 있다. 이 발표만으로 정식 출시일이나 최종 단가, 우리 팀의 월 비용을 계산할 수는 없다.

다음 표는 공식 제공 범위와 설정 요건을 실제 도입 판단으로 재구성한 것이다. 표의 조치는 편집상 권고이며 제품이 실행한 결과가 아니다.

현재 상황	판단	다음 확인 대상
Enterprise Cloud에서 npm 설치 경로를 관리할 수 있다	제한된 환경부터 도입 검토	해당 엔드포인트의 레지스트리·인증 구성
기업 정책은 켰지만 에이전트의 설치 주소는 모른다	적용 완료로 판단할 수 없다	에이전트가 실제 사용하는 npm 설정
npm이 아닌 의존성 보호가 목적이다	이번 미리보기의 지원 범위와 다르다	해당 생태계의 별도 통제 수단
공개 레지스트리 직접 연결을 남긴 Artifactory를 쓴다	방화벽 우회 경로를 점검해야 한다	가상 저장소에 포함된 원격 저장소 목록
미리보기 비용만 보고 장기 운영을 결정하려 한다	무료라는 조건만으로는 부족하다	정식 출시 과금 발표와 실제 사용 규모

제공 범위를 먼저 확인한 뒤 인증과 경로를 검토한다. 미리보기 무료는 정식 출시 후 영구 무료 약속이 아니다. 출처: github.blog/changelog/2026-10-20-github-package-firewall-in-public-preview.

도입 검토에서 중요한 것은 “기능이 있는가”를 “내 설치 경로에 적용되는가”로 바꾸는 일이다. 로컬·에이전트·CI 중 한 환경만 먼저 구성해 범위를 명확히 하는 것은 운영 제안이며 GitHub가 요구하는 강제 순서는 아니다. 모든 엔드포인트가 같은 구성을 공유한다는 가정부터 두지 않는 편이 낫다.

3. 기본값은 보안 보증이 아니라 출발 설정이다

공식 설정 문서는 알려진 악성 패키지 차단, attestation downgrade 차단, 새로 도입된 설치 스크립트 차단의 기본값을 켜짐으로 설명한다. 취약점 advisory 차단의 기본 기준은 Critical only다. 알려진 악성 패키지 차단은 GitHub Advisory Database의 활성 악성 advisory와 일치하는 패키지를 대상으로 한다. 알려지지 않은 모든 악성 의존성을 반드시 탐지한다는 설명과는 다르다. 공식 정책·엔드포인트 설정 문서

최소 패키지 나이는 새로 발표된 버전에 대기 기간을 두는 설정이다. 활성화 값은 1일부터 365일까지이고, 0은 비활성화이며 기본값은 1일이다. 오래된 패키지는 안전하다는 인증이 아니라 위협이 발견될 시간을 벌기 위한 조건으로 이해해야 한다. 예를 들어 긴급 보안 수정 버전도 새 버전이라는 이유로 이 조건에 걸릴 수 있다. 공식 문서가 예외 요청을 설명하는 이유이기도 하다.

공식 기본값을 정리했다. 증명 후퇴는 attestation downgrade를 뜻하며, 알려진 악성·증명 후퇴·새 설치 스크립트 통제는 기본 켜짐이다. 탐지율이나 안전성 보증이 아니다. 출처: docs.github.com/en/enterprise-cloud@latest/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/protecting-endpoints-with-package-firewall.

attestation downgrade 통제는 과거 버전에 SLSA attestation이 있었는데 요청 버전에는 없는 경우를 비교한다. 단순히 모든 패키지에 증명 자료가 있어야 한다는 규칙으로 바꾸어 설명하면 범위가 달라진다. 설치 스크립트 통제 역시 새로 추가된 preinstall·postinstall 같은 스크립트를 점검하는 설명이지, 모든 설치 스크립트를 금지한다는 선언은 아니다. 실제 정책 효과를 평가하려면 차단 사유와 정상 업무 영향을 함께 관찰해야 하며, 이 글에는 그런 측정 결과가 없다.

4. 설정 예시는 비밀을 넣기 전에 경계를 이해한다

엔드포인트 요청에는 기업 구성원인 사용자 또는 봇 계정과 연결된 토큰이 필요하다. 공식 문서는 공개 저장소 읽기 전용 접근을 넘는 상위 권한이 필요하지 않다고 설명한다. 정책을 설정하는 기업 관리자·보안 관리자 역할과 패키지를 요청하는 계정의 권한을 같은 것으로 취급하지 않아야 한다. 별도 Copilot 요금제나 추가 보안 제품 라이선스가 필수라고 이 자료만으로 추론하지도 않는다.

문서에 제시된 사용자 수준 .npmrc 구성 형태는 다음과 같다. ENTERPRISE는 실제 기업 식별자로 바꿔야 하는 자리표시자이고, GITHUB_TOKEN은 안전하게 주입하는 환경 변수다. 아래 코드는 설명용으로 제시했을 뿐 이 글 작성 중 실행하거나 사용자의 npm 설정을 바꾸지 않았다.

registry=https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE
//package-firewall.githubapp.com/npm/enterprises/ENTERPRISE/:_authToken=${GITHUB_TOKEN}

토큰 값을 파일에 직접 적어 저장소에 커밋하지 말고, CI 비밀 저장소 등 안전한 위치에서 관리한다. 점검을 위해 전체 설정이나 환경 변수를 로그로 덤프하는 방식도 비밀 노출을 만들 수 있으므로 피하는 것이 좋다. 실제 토큰을 발급하거나 설치 명령을 실행하지 않아도 설계 검토에서는 어떤 계정이 요청하고 어떤 경로로 전달되는지 먼저 정리할 수 있다.

Artifactory를 쓰는 경우에는 엔드포인트가 Artifactory를 계속 이용하면서 그 뒤의 공개 패키지 요청을 방화벽으로 보낼 수 있다. 다만 공식 문서는 이 지원을 실험적이라고 표시한다. 가상 npm 저장소에 공개 npm 레지스트리로 직접 가져오는 다른 원격 저장소가 남아 있으면 정책을 우회할 수 있으므로 제외하라고 안내한다. “중앙 저장소를 쓴다”와 “공개 요청이 전부 방화벽을 지난다”는 같은 말이 아니다.

5. 차단을 해제할 때는 버전 범위를 남긴다

패키지가 차단되면 npm 출력이나 CI/CD 로그에 예외를 요청할 URL이 포함된다. 요청자는 패키지·버전·이유 등을 확인해 요청하고, 기업 관리자나 보안 관리자가 검토한다. 공식 문서는 허용 버전을 별표(*)로 바꾸면 모든 버전으로 예외 범위가 넓어진다고 설명한다. 특정 수정 버전이 필요한 상황에서 전체 버전 허용으로 바꾸는 것은 다른 결정이다.

요청과 승인을 분리하고 버전 범위를 확인한다. 별표(*)는 모든 버전으로 범위를 넓힌다. 좁은 범위 검토는 이 글의 운영 제안이다. 출처: docs.github.com/en/enterprise-cloud@latest/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/protecting-endpoints-with-package-firewall.

운영 관점에서는 에이전트가 필요한 패키지와 차단 사유를 정리하도록 하되 스스로 예외를 승인하거나 허용 범위를 넓히도록 맡기지 않는 편이 낫다. 이는 이 글의 권한 분리 제안이며 제품이 모든 에이전트의 행위를 자동 제한한다는 보장은 아니다. 예외 요청에는 왜 지금 이 버전이 필요한지 남기고, 승인 범위와 나중에 제거할 조건을 함께 기록하는 방식을 권한다. 승인된 예외는 정책에 추가되며 관리자가 검토·제거할 수 있다는 점은 공식 문서에 명시되어 있다.

6. 적용 완료의 기준은 스위치가 아니라 연결된 경로다

이 기능을 검토할 때 가장 먼저 물을 질문은 “우리 기업에서 켰는가”가 아니라 “어느 환경의 npm 요청이 어떤 인증으로 방화벽에 도달하는가”다. 그다음 기본 정책과 예외의 범위를 확인하면, 지원 대상이 아닌 환경이나 우회 가능한 구성을 적용 완료로 착각하는 일을 줄일 수 있다. 미리보기 제공 범위와 장기 비용 조건도 그 판단에 함께 들어가야 한다.

이 글은 공식 발표와 설정 문서를 바탕으로 한 운영 설계 해설이며, 실제 기업 환경에서 설치·차단 성능을 재현한 시험은 아니다. 그림은 공식 제품 화면이 아닌 직접 작성한 개념도다. 설치 성공 로그, 공격 차단률 또는 비용 절감 수치를 만들어 제시하지 않았다. 정책과 경로, 계정과 승인 역할을 나눠 보는 것이 이번 발표에서 바로 가져갈 수 있는 실무적 판단 기준이다.

참고 자료

• GitHub 공식 발표: Package firewall 공개 미리보기: 제공 범위, 요청 경로, 미리보기와 과금 계획.
• GitHub 공식 문서: 엔드포인트 보호와 예외 관리: 정책 기본값, 인증, npm·Artifactory 구성과 버전 예외.