Npm on 엔지니어 생존기록

npm 공급망 공격 방어 가이드: min-release-age 설정하기

Mon, 20 Apr 2026 21:17:43 +0900

이 문서는 CLAUDE를 통해 작성되었습니다.

목적: 이 가이드는 npm 생태계에 대한 공급망 공격(Supply Chain Attack) 으로부터 개발자와 조직을 보호하기 위한 실무 설정 가이드입니다. macOS, Windows 모두에서 동일하게 적용할 수 있도록 작성되었습니다.

배경: 왜 이 설정이 필요한가 — axios 사태 (2026년 3월 31일)

2026년 3월 31일, 주당 약 1억 회 다운로드되는 인기 HTTP 클라이언트 라이브러리 axios 의 메인테이너 npm 계정이 탈취되어, 악성 버전 axios@1.14.1과 axios@0.30.4가 npm 레지스트리에 공개되었습니다.

공격 요약

공격자는 사회공학 기법(위장된 회사, 가짜 Slack/Teams 미팅)으로 메인테이너 계정을 탈취했습니다.
악성 버전은 plain-crypto-js@4.2.1이라는 별도의 악성 패키지를 의존성으로 주입했습니다.
해당 패키지의 postinstall 훅은 npm install 실행 즉시 macOS / Windows / Linux용 RAT(원격 제어 트로이목마)을 자동으로 다운로드하여 실행했습니다.
코드를 한 줄도 import 하지 않고, 단지 설치만 해도 감염되었습니다.
악성 버전은 공개 후 약 3시간 뒤에 npm 레지스트리에서 제거되었습니다.

핵심 교훈

만약 새 패키지 버전의 설치를 단 하루만 지연시켰다면, 대부분의 개발자는 이 공격에서 안전했을 것입니다.

대부분의 악성 npm 패키지는 보안 연구자들에 의해 수 시간 내에 탐지·제거됩니다. 따라서 갓 출시된 버전의 설치를 일정 기간 지연시키는 “쿨다운(cooldown)” 전략이 가장 단순하고 강력한 공급망 공격 방어 수단 중 하나입니다.

npm CLI는 11.10.0 버전부터 이 기능을 min-release-age 설정으로 제공합니다.

전체 절차 개요

Node.js 및 npm 버전 확인
Node.js를 24.x로 업그레이드 (필요 시)
npm을 11.10.0 이상으로 업그레이드
min-release-age 설정
설정이 실제로 적용되는지 검증
추가 보안 설정 (선택)

1단계: 현재 버전 확인

터미널(macOS: Terminal / Windows: PowerShell 또는 CMD)을 열고 다음을 실행합니다.

node -v
npm -v

요구 버전

Node.js: v24.x 이상 (npm 11은 공식적으로 Node 24와 함께 제공됨)
npm: 11.10.0 이상

두 버전 모두 충족한다면 3단계로 건너뛸 수 있습니다.

2단계: Node.js 설치 / 업그레이드

Node 버전을 유연하게 관리하기 위해 nvm(Node Version Manager) 사용을 권장합니다.

macOS / Linux — nvm

nvm 설치 (이미 설치되어 있다면 생략):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

설치 후 새 터미널을 엽니다. 그 다음:

# 최신 Node 24.x 설치 및 기본값으로 지정
nvm install 24
nvm alias default 24

이미 Node 24.x가 설치된 경우, 최신 패치 버전으로 업데이트:

nvm install 24 --reinstall-packages-from=current
nvm alias default 24

--reinstall-packages-from=current는 기존에 전역 설치한 패키지들을 새 버전으로 자동 이전합니다.

Windows — nvm-windows

Windows는 별도의 프로젝트인 nvm-windows를 사용합니다.

https://github.com/coreybutler/nvm-windows/releases 에서 nvm-setup.exe 다운로드 후 설치
관리자 권한으로 PowerShell 또는 CMD 실행

# 최신 Node 24.x 설치
nvm install 24

# 설치된 24.x 중 하나를 활성화
nvm use 24

Windows에서 최신 패치 버전으로 업데이트:

nvm install 24
nvm use 24
# (선택) 이전 버전 제거
nvm uninstall <이전버전>

설치 확인

node -v # v24.x.x 가 출력되어야 함

3단계: npm 11.10.0 이상으로 업그레이드

Node 24를 설치해도 번들된 npm이 11.10.0보다 낮을 수 있습니다.

npm -v

11.10.0 미만이라면 업그레이드:

npm install -g npm@latest

nvm 사용자 참고: 이 명령은 -g로 설치하지만, nvm이 각 Node 버전마다 독립된 전역 디렉터리를 두기 때문에 sudo / 관리자 권한 없이 실행할 수 있습니다. 단, 이렇게 업그레이드한 npm은 현재 활성화된 Node 버전에만 적용됩니다. 다른 Node 버전으로 전환(nvm use)하면 해당 버전에 번들된 npm으로 되돌아갑니다.

확인:

npm -v # 11.10.0 이상이어야 함

4단계: `min-release-age` 설정

사용자 수준 .npmrc 파일에 설정을 추가합니다. 이 파일의 위치는 OS별로 다릅니다.

macOS / Linux: ~/.npmrc
Windows: C:\Users\<사용자명>\.npmrc

OS 공통 명령으로 설정:

npm config set min-release-age 7

7은 일(day) 단위입니다 (pnpm은 분 단위이니 혼동 주의). 권장값:

값	설명	적합한 환경
`1`	최소 방어. 대부분의 악성 패키지는 수 시간 내 제거됨	빠른 업데이트가 필요한 개인 프로젝트
`3`	균형 잡힌 선택. Renovate Bot의 권장 기본값	일반 팀/프로젝트
`7`	견고한 방어. 일반적으로 추천	대부분의 팀에 적합
`14`+	매우 보수적	엔터프라이즈 / 금융권

파일 내용 확인

macOS / Linux:

cat ~/.npmrc

Windows (PowerShell):

Get-Content $HOME\.npmrc

출력에 min-release-age=7이 포함되어 있으면 정상입니다.

5단계: 설정이 실제로 작동하는지 검증

⚠️ 알려진 버그 주의: 현재 npm 버전(~11.12.x)에서는 npm config get min-release-age가 null을 반환하는 표시 버그(npm/cli#9199)가 있습니다. 실제 기능은 정상 동작합니다. 따라서 config get 대신 아래의 실제 설치 시험으로 검증하세요.

최근 7일 이내에 배포된 버전을 찾아 설치 시도

# 최근에 자주 배포되는 패키지의 버전 히스토리 확인
npm view @types/node time --json

출력에서 최근 7일 이내 날짜의 버전을 하나 고릅니다. 그 다음 임시 폴더에서:

macOS / Linux:

mkdir -p /tmp/npm-test && cd /tmp/npm-test
npm install @types/node@<최근버전> --dry-run

Windows (PowerShell):

mkdir $env:TEMP\npm-test; cd $env:TEMP\npm-test
npm install @types/node@<최근버전> --dry-run

성공 시 출력 예시

npm error code ETARGET
npm error notarget No matching version found for @types/node@X.X.X
 with a date before 2026/M/D, HH:MM:SS.

“with a date before ...” 의 날짜가 오늘로부터 설정한 일수 이전이면 정상 동작 중입니다. 설정된 기간보다 최근에 배포된 버전은 설치가 거부됩니다.

긴급 상황 대응: 일회성으로 제한 우회

긴급 CVE 패치가 출시되어 최신 버전을 즉시 설치해야 하는 경우, 한 번만 제한을 우회할 수 있습니다:

npm install <패키지명> --min-release-age=0

전역 .npmrc 설정은 유지되며, 이 명령에서만 제한이 무시됩니다.

주의사항 및 한계

npm ci는 영향을 받지 않습니다. min-release-age는 npm install의 의존성 해결 과정에 적용됩니다. package-lock.json이 이미 있고 npm ci로 설치하는 경우(주로 CI 환경), 락파일에 고정된 버전을 설치하므로 이 설정과 무관합니다. → 개발자의 로컬 머신에서 락파일에 악성 버전이 고정되는 것을 막는 것이 핵심 방어선입니다.
~ 버전 범위 관련 버그. 의존성에 ~1.2.3처럼 ~ 범위 지정자가 포함된 경우 min-release-age가 에러를 일으킬 수 있습니다 (npm/cli#9005). 수정되기 전까지는 ^를 사용하는 것을 권장합니다.
숫자만 허용. 7d, 7days 같은 문자 접미사 형식은 지원하지 않습니다. 오직 정수(일수) 만 유효한 값입니다.
예외 목록 미지원. pnpm과 달리 현재 npm은 “이 패키지만 예외” 같은 화이트리스트 기능이 없습니다(npm/cli#8979). 긴급한 경우 위의 --min-release-age=0 플래그로 우회하세요.

추가 보안 권장 사항 (axios 공격에서 배운 교훈)

min-release-age는 공급망 공격 방어의 첫 번째 방어선일 뿐입니다. 다음 조치들을 함께 적용하면 훨씬 안전합니다.

(1) `package-lock.json`을 반드시 Git에 커밋

락파일이 있어야 npm ci로 재현 가능한 설치가 가능하고, 의도치 않은 버전 업그레이드를 막을 수 있습니다.

(2) CI에서는 `npm install` 대신 `npm ci` 사용

npm ci

락파일에 고정된 버전만 설치하므로, 악성 패키지가 떠도 CI가 자동으로 업그레이드하지 않습니다.

(3) 프로덕션 빌드에서 lifecycle script 비활성화 고려

npm config set ignore-scripts true

postinstall 같은 훅이 실행되지 않아 axios 사례와 같은 공격 대부분을 원천 차단합니다. 단, 일부 정상 패키지(네이티브 바인딩 포함)는 빌드에 실패할 수 있으므로 CI에서 먼저 검증 후 적용하세요.

(4) axios 감염 여부 직접 점검

현재 프로젝트에 악성 버전이 혹시 들어와 있지 않은지 확인:

npm ls axios
npm ls plain-crypto-js

다음 중 하나라도 발견되면 즉시 감염으로 간주하고 조치하세요:

axios@1.14.1
axios@0.30.4
plain-crypto-js(모든 버전)

조치 절차

해당 머신의 모든 자격증명 즉시 회전(rotate): API 키, SSH 키, GitHub/npm 토큰, 클라우드 크리덴셜 등
캐시 삭제:
```
npm cache clean --force
```
안전한 버전으로 다운그레이드 (axios@1.14.0 또는 axios@0.30.3)
CI/CD 로그에서 2026년 3월 31일 00:21 UTC ~ 03:15 UTC 사이 npm install 실행 이력 검토

참고 자료

최종 업데이트: 2026년 4월 16일

patch-package로 패키지 커스터마이즈하기

Sat, 10 May 2025 08:45:21 +0900

react와 같이 node.js 기반으로 개발하다보면, 여러 패키지를 설치해서 사용하게 됩니다. 그리고 그러다 보면, 기존 패키지의 코드를 수정해서 사용해야 하는 경우가 생깁니다! 이럴 때는 어떻게 해야 할까요?

미련했던 옛 시절

현재 작업 중인 프로젝트에서는 webrtc 기반으로 코드 에디터의 내용을 동기화 하는 기능을 구현했었습니다. 그러다 보니 오픈소스 패키지를 사용하다가 필요한 기능을 넣기 위해 패키지를 수정할 필요가 있었죠. 그래서 고민하다가… node_modules 폴더에서 해당 패키지의 소스 코드를 찾아서 그걸 /src/lib 폴더에 복사해두고 직접 수정했습니다! 그리곤 설치된 패키지를 import 하는 대신에 /src/lib에 복사해서 수정한 파일을 import 하는 방식으로 구현했죠.

물론 이 방법에도 장점은 있습니다. 간단하죠! 그리고 디버깅도 쉽습니다. 코드가 내 프로젝트 안에 있으니까요. 그런데 이 작업을 할 당시에도 "나중에 시간이 좀 지나서 패키지를 업데이트해야 되면, 일일이 변경점을 찾아서 수정해야 되나...?" 하는 불안감은 있었지만 그런 걸 생각할 여유가 아예 없었기 때문에 그냥 그대로 뒀습니다.

기술적 부채는 결국 돌아온다!

그렇게 대충 마무리를 하고 2년이 지났고, 그 프로젝트를 다시 들여다 보고 있었습니다. 어떻게든 회사가 죽지 않고 버티다 보면 신기하게도 이미 수명이 끝났다고 생각했던 솔루션이 다시 부활하게 되는 순간이 오곤 합니다. 네, 지금이 그런 순간이었던 거죠. 거의 포기했던 솔루션을 다시 봐야 하는 상황인거죠. 개발자라면 이때의 막막한 심정을 공감하실 겁니다. 본인이 막대한 노력을 들여서 일을 장황하게 벌여놨지만, 시간이 한참 지나서 그걸 다시 스스로 수습해야 하는 상황말이죠…

어쨌거나 그 당시에 넘쳐나던 요구사항을 쫓아가기 급급하면서 계속 새로운 기능을 공장처럼 찍어냈고, 여러가지 사정으로 인해 그 기능들은 제대로 테스트 과정을 거치지도 못한 채 방치되었습니다. 빚을 내면서 빨리 개발했지만, 그 빚을 갚지 못하면서 이자만 눈덩이 처럼 불어난 셈이죠. 패키지 파일을 /src/lib에 복사했던 건 수 많은 부채 중의 하나였습니다.

좀 더 우아한 방법이 없을까?

이 문제에 대해 위대하신 ChatGPT님과 대화하다 보니, 여러가지 방법이 있지만 가장 간단한 건 patch-package를 활용하는 방법이라는 걸 알게되었습니다. 그러니까, node_modules/some-package/src/source.js 파일을 직접 수정하고, npx patch-package some-package 명령을 실행하면, 원래 패키지에서 변경된 점을 찾아서 patches 폴더에 기록하고 패키지를 새롭게 빌드해줍니다. patches 폴더에 기록된 내용을 들여다보면 대충 다음과 같은 내용입니다.

diff --git a/node_modules/some-package/src/source.js b/node_modules/some-package/src/source.js
index c0fc343..92a2941 100644
--- a/node_modules/some-package/src/source.js
+++ b/node_modules/some-package/src/source.js
@@ -97,6 +97,7 @@ someArray[someIndex] = (

 // @todo - blah blah some original source code
 const someVariable = 30000
+const someOtherVariable = 4000;

게다가! package.json의 scripts에 postinstall 스크립트를 추가하면, 패키지를 설치할 때마다 자동으로 패치 파일을 적용해줍니다.

"scripts": {
 ...
 "postinstall": "patch-package"
}

패키지를 새로 설치할 때 마다 수작업으로 변경사항을 적용할 필요가 없는 거죠! 다만, patch 파일 이름(some-package+0.1.6.patch) 에서도 알 수 있듯이 패키지의 버전이 바뀐다면 패치는 자동 적용되지 않습니다. 그럴 때는 다음과 같이 파일의 이름을 변경하고 다시 시도해볼 수 있습니다.

# 패키지 버전이 0.1.6에서 0.1.7로 바뀌었다고 가정해봅니다.
> cp patches/some-package+0.1.6.patch patches/some-package+0.1.7.patch
# 패치를 적용해봅니다.
> npx patch-package

만약 패키지가 업데이트 되면서 패치와 관련된 코드가 변경되었다면 패치는 실패하며 그때는 패치를 새로 만들어야 합니다. 이 방법도 만능은 아닌 셈이죠. 그래도 현 시점에서 가장 간단하면서도 우아하게 적용할 수 있는 방법이었습니다.