npm audit 명령어 정리 — 보안 취약점 검사부터 Breaking Change까지

이 글에서 다루는 내용

이 글에서는 npm 프로젝트의 보안 취약점을 검사하고 수정하는 npm audit 명령어의 사용법과 관련 옵션들을 정리하고, 자동 수정 시 주의해야 할 Breaking Change의 개념까지 함께 다룬다.

프로젝트에 설치된 의존성 패키지에 보안 취약점이 있는지 검사하는 명령어다. npm 레지스트리의 보안 데이터베이스와 대조하여 취약점을 리포트해준다.

취약점의 심각도는 아래 순서로 구분된다.

critical > high > moderate > low > info

기본 검사는 아래 명령어로 실행한다.

npm audit

결과를 JSON 형식으로 출력하려면 --json 옵션을 사용한다. CI/CD 파이프라인 연동에 유용하다.

npm audit --json

특정 심각도 이상의 취약점만 표시하려면 --audit-level 옵션을 사용한다.

npm audit --audit-level=high

low | moderate | high | critical 중 하나를 지정할 수 있다.

semver 범위 내에서 수정 가능한 취약점을 자동으로 업데이트한다.

npm audit fix

semver 범위를 무시하고 major 버전 업그레이드까지 강제 적용한다. Breaking Change가 발생할 수 있으므로 주의해서 사용해야 한다.

npm audit fix --force

실제 수정 없이 어떤 변경이 일어날지 미리 확인하려면 --dry-run 옵션을 사용한다.

npm audit fix --dry-run
npm audit fix --dry-run --json

devDependencies를 제외하고 프로덕션 의존성만 검사한다.

npm audit --omit=dev

node_modules가 없어도 package-lock.json만으로 검사한다.

npm audit --package-lock-only

취약한 패키지가 간접 의존성(transitive dependency)인 경우 audit fix만으로는 해결되지 않을 수 있다. 이때는 npm v8.3+에서 지원하는 overrides를 package.json에 직접 명시하는 방법을 사용할 수 있다.

{
  "overrides": {
    "취약한-패키지명": "^안전한버전"
  }
}

업데이트 후 기존에 잘 동작하던 코드가 에러가 나거나 동작이 달라지는 것, 즉 기존 코드와의 호환성을 깨뜨리는 변경사항을 말한다.

// v1 (기존)
library.getUserInfo()

// v2 (업데이트 후) — 함수명 변경
library.fetchUser()  // 기존 코드 전부 에러 💥

// v1
login(username, password)

// v2 — 객체로 변경
login({ username, password })  // 기존 호출부 전부 수정 필요 💥

// v1
const user = getUser()
user.name  // ✅

// v2 — 반환 구조 변경
const { data } = getUser()
data.name  // 기존 코드에서 user.name은 undefined 💥

Semver(Semantic Versioning)는 Major.Minor.Patch 형태로 버전을 표기하는 규칙이다.

npm audit fix는 Minor/Patch 업만 수행하기 때문에 안전하고, npm audit fix --force는 Major 업까지 건드리기 때문에 Breaking Change 위험이 발생한다.