Copy & Run

npm audit --audit-level 사용법: 종료 코드로 배포 막기

npm audit --audit-level은 지정한 심각도 이상의 취약점이 있을 때만 종료 코드 1을 돌려줍니다. low부터 critical까지 단계별 종료 코드와 --omit=dev를 붙였을 때의 차이를 실제 실행 결과로 확인합니다. npm script와 CI 단계에 넣는 방법도 정리합니다.

실습 노트 · 2026-11-16 발행 · 14분 · 2026-11 확인

npm audit은 취약점이 하나라도 있으면 종료 코드 1을 돌려줍니다. --audit-level=high를 붙이면 high 이상이 있을 때만 1이 되고, 그보다 낮은 취약점만 있으면 0이 됩니다. CI는 종료 코드가 0이 아닌 단계에서 멈추므로, 이 옵션 하나로 "어느 심각도부터 배포를 막을지"를 정할 수 있습니다.

npm audit과 npm audit fix의 기본 사용법은 Node.js 시작하기: 프로젝트 만들기와 npm audit 점검에 있습니다. 이 글은 그다음 단계로, 점검 결과를 통과와 실패로 나누는 기준을 다룹니다.

준비물

항목 내용
Node.js v24.15.0
npm 11.12.1
실행 의존성 cookie@0.6.0 (low), word-wrap@1.2.3 (moderate)
개발 의존성 lodash@4.17.15 (high)
실습 위치 빈 폴더 하나 (실제 프로젝트와 분리)
셸 bash (Windows에서는 Git Bash)

세 패키지는 심각도가 서로 다른 취약 버전으로 일부러 골랐습니다. npm audit 결과는 실행한 날짜의 보안 권고 목록을 기준으로 하므로, 날짜가 다르면 개수와 심각도가 달라질 수 있습니다.

1. 심각도가 다른 패키지 설치하기

빈 폴더에서 프로젝트를 만들고, 실행 의존성 두 개와 개발 의존성 한 개를 설치합니다.

npm init -y
npm install cookie@0.6.0 word-wrap@1.2.3
npm install --save-dev lodash@4.17.15

마지막 설치 명령의 출력입니다.

added 1 package, and audited 4 packages in 2s

3 vulnerabilities (1 low, 1 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

package.json에 어떻게 나뉘어 들어갔는지 확인합니다.

npm pkg get dependencies devDependencies
{
  "dependencies": {
    "cookie": "^0.6.0",
    "word-wrap": "^1.2.3"
  },
  "devDependencies": {
    "lodash": "^4.17.15"
  }
}

2. 옵션 없이 실행: 한 건만 있어도 실패

먼저 옵션 없이 실행하고 종료 코드를 봅니다.

npm audit
echo $?
# npm audit report

cookie  <0.7.0
cookie accepts cookie name, path, and domain with out of bounds characters - https://github.com/advisories/GHSA-pxg6-pf52-xh8x
fix available via `npm audit fix --force`
Will install cookie@2.0.2, which is a breaking change
node_modules/cookie

lodash  <=4.17.23
Severity: high
Command Injection in lodash - https://github.com/advisories/GHSA-35jh-r3h4-6jhm
Prototype Pollution in lodash - https://github.com/advisories/GHSA-p6mc-m468-83gw
Regular Expression Denial of Service (ReDoS) in lodash - https://github.com/advisories/GHSA-29mw-wpgm-hmr9
lodash vulnerable to Code Injection via `_.template` imports key names - https://github.com/advisories/GHSA-r5fr-rjxr-66jc
Lodash has Prototype Pollution Vulnerability in `_.unset`, `_.omit`, and `_.pullAt` functions - https://github.com/advisories/GHSA-xxjr-mmjv-4gpg
fix available via `npm audit fix`
node_modules/lodash

word-wrap  <1.2.4
Severity: moderate
word-wrap vulnerable to Regular Expression Denial of Service - https://github.com/advisories/GHSA-j8xg-fqg3-53r7
fix available via `npm audit fix`
node_modules/word-wrap

3 vulnerabilities (1 low, 1 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force
1

마지막 줄의 1이 종료 코드입니다. cookie 항목에는 Severity: 줄이 없는데, 아래 요약 줄을 보면 low 한 건으로 집계돼 있습니다. 이 프로젝트에서 가장 높은 심각도는 high이고 critical은 없습니다.

3. --audit-level 단계별 종료 코드

같은 프로젝트에서 --audit-level에 네 단계를 차례로 넣어 종료 코드만 출력합니다. 보고서는 /dev/null로 버립니다.

for level in low moderate high critical; do
  npm audit --audit-level=$level > /dev/null
  echo "$level: $?"
done
low: 1
moderate: 1
high: 1
critical: 0

high까지는 1이고 critical에서 0으로 바뀝니다. 이 프로젝트의 최고 심각도가 high이기 때문입니다. --audit-level은 "이 단계 이상이 한 건이라도 있으면 실패"라는 기준선입니다.

주의할 점이 하나 있습니다. --audit-level은 종료 코드만 바꾸고 보고서 내용은 줄이지 않습니다. 종료 코드가 0인 critical 단계에서도 화면에는 세 건이 그대로 나옵니다.

npm audit --audit-level=critical
echo $?
3 vulnerabilities (1 low, 1 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force
0

보고서 본문은 2번과 같아서 요약 줄부터만 남겼습니다. CI 로그에 취약점 목록이 보인다고 해서 그 단계가 실패했다는 뜻은 아닙니다. 판정은 종료 코드로 확인합니다.

4. --omit=dev로 실행 의존성만 판정하기

lodash는 개발 의존성이라 운영 서버에는 설치되지 않습니다. --omit=dev를 붙이면 개발 의존성을 빼고 점검합니다.

npm audit --omit=dev
echo $?
# npm audit report

cookie  <0.7.0
cookie accepts cookie name, path, and domain with out of bounds characters - https://github.com/advisories/GHSA-pxg6-pf52-xh8x
fix available via `npm audit fix --force`
Will install cookie@2.0.2, which is a breaking change
node_modules/cookie

word-wrap  <1.2.4
Severity: moderate
word-wrap vulnerable to Regular Expression Denial of Service - https://github.com/advisories/GHSA-j8xg-fqg3-53r7
fix available via `npm audit fix`
node_modules/word-wrap

2 vulnerabilities (1 low, 1 moderate)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force
1

lodash가 빠져 두 건이 됐습니다. 여기에 다시 네 단계를 넣습니다.

for level in low moderate high critical; do
  npm audit --omit=dev --audit-level=$level > /dev/null
  echo "$level: $?"
done
low: 1
moderate: 1
high: 0
critical: 0

high 단계의 종료 코드가 1에서 0이 됩니다. 유일한 high였던 lodash가 점검 대상에서 빠졌기 때문입니다.

5. --json으로 요약 개수 읽기

스크립트에서 개수를 직접 쓰려면 --json으로 받습니다. 출력 형식을 바꿔도 종료 코드 규칙은 같습니다.

npm audit --json > audit.json
echo $?
1

JSON의 최상위 키는 세 개입니다.

node -p "Object.keys(require('./audit.json'))"
[ 'auditReportVersion', 'vulnerabilities', 'metadata' ]

요약 개수는 metadata.vulnerabilities에 있습니다.

node -p "require('./audit.json').metadata.vulnerabilities"
{ info: 0, low: 1, moderate: 1, high: 1, critical: 0, total: 3 }

심각도별 건수와 합계(total)가 한 줄에 들어 있습니다. --audit-level=high가 실패하는 조건을 이 값으로 바꿔 말하면 high + critical이 1 이상인 경우입니다. --omit=dev를 붙여 받은 JSON에서는 high가 0으로 바뀝니다.

npm audit --omit=dev --json > audit-prod.json
node -p "require('./audit-prod.json').metadata.vulnerabilities"
{ info: 0, low: 1, moderate: 1, high: 0, critical: 0, total: 2 }

패키지별 상세는 vulnerabilities 아래에 패키지 이름을 키로 해서 들어 있습니다. word-wrap 한 건을 꺼내 봅니다.

node -p "JSON.stringify(require('./audit.json').vulnerabilities['word-wrap'], null, 2)"
{
  "name": "word-wrap",
  "severity": "moderate",
  "isDirect": true,
  "via": [
    {
      "source": 1102444,
      "name": "word-wrap",
      "dependency": "word-wrap",
      "title": "word-wrap vulnerable to Regular Expression Denial of Service",
      "url": "https://github.com/advisories/GHSA-j8xg-fqg3-53r7",
      "severity": "moderate",
      "cwe": [
        "CWE-1333"
      ],
      "cvss": {
        "score": 5.3,
        "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L"
      },
      "range": "<1.2.4"
    }
  ],
  "effects": [],
  "range": "<1.2.4",
  "nodes": [
    "node_modules/word-wrap"
  ],
  "fixAvailable": true
}

판정에 자주 쓰는 값은 severity, 직접 설치한 패키지인지 알려 주는 isDirect, 수정 버전이 있는지 알려 주는 fixAvailable입니다.

6. npm script와 CI 단계로 만들기

기준을 package.json의 script로 적어 두면 PC와 CI가 같은 명령을 씁니다. 전체 의존성 기준과 실행 의존성 기준을 하나씩 등록합니다.

npm pkg set "scripts.audit:all=npm audit --audit-level=high"
npm pkg set "scripts.audit:prod=npm audit --omit=dev --audit-level=high"
npm pkg get scripts
{
  "test": "echo \"Error: no test specified\" && exit 1",
  "audit:all": "npm audit --audit-level=high",
  "audit:prod": "npm audit --omit=dev --audit-level=high"
}

npm run은 script의 종료 코드를 그대로 돌려줍니다. &&와 ||로 통과와 실패를 확인합니다.

npm run audit:prod > /dev/null && echo "gate passed"
npm run audit:all > /dev/null || echo "gate failed: $?"
gate passed
gate failed: 1

실행 의존성 기준은 통과하고, 개발 의존성까지 넣은 기준은 lodash 때문에 실패합니다.

CI에서는 이 script를 한 단계로 넣습니다. 아래는 GitHub Actions 형식의 예시이고, 이 글에서 직접 실행해 본 것은 run: 뒤의 명령입니다.

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 24
  - run: npm ci
  - run: npm run audit:prod

npm run audit:prod가 1을 돌려주면 그 단계에서 작업이 멈추고 뒤의 빌드와 배포 단계는 실행되지 않습니다. npm ci를 먼저 두는 이유는 package.json과 package-lock.json 차이: npm ci로 확인하기에 정리했습니다.

PowerShell에서는 $? 대신 $LASTEXITCODE에 숫자가 들어갑니다. 같은 프로젝트에서 npm audit --audit-level=high 뒤에는 1, --audit-level=critical 뒤에는 0이 나왔습니다.

7. 기준별 결과 비교

이 프로젝트(low 1, moderate 1, 개발 의존성 high 1)에서 확인한 종료 코드입니다.

명령 low moderate high critical
npm audit --audit-level=<단계> 1 1 1 0
npm audit --omit=dev --audit-level=<단계> 1 1 0 0

기준은 다음 순서로 정합니다.

  1. 배포를 막는 기준은 --omit=dev --audit-level=high에서 시작합니다. 운영 서버에 들어가는 패키지의 high와 critical만 막습니다.
  2. 개발 의존성은 audit:all처럼 별도 script로 두고, 실패해도 배포는 막지 않는 점검 작업에서 실행합니다.
  3. moderate 이하는 종료 코드로 막지 않더라도 metadata.vulnerabilities의 개수를 기록해 늘어나는지 봅니다.
  4. 기준선을 critical로 바꾸면 3번 실험처럼 high가 있어도 통과하므로, 바꿀 때는 이유를 남깁니다.

npm audit은 npm 레지스트리의 권고만 대조합니다. lock 파일을 다른 취약점 데이터베이스와 대조하려면 OSV-Scanner로 잠금 파일 점검하기를 함께 봅니다.

자주 묻는 질문

--audit-level을 주면 낮은 심각도 취약점은 출력에서 사라집니까?

사라지지 않으며, 보고서는 그대로 나오고 종료 코드만 지정한 단계 이상이 있을 때 1이 됩니다.

--audit-level을 생략하면 기준이 무엇입니까?

이 글의 2번 실험처럼 취약점이 한 건이라도 있으면 종료 코드가 1입니다.

개발 의존성의 취약점은 무시해도 됩니까?

운영 서버에는 들어가지 않지만 빌드와 테스트를 돌리는 PC와 CI에서는 실행되므로, 배포 기준과 따로 점검해 고칩니다.

이 글의 다음 단계

  • Node.js 시작하기: 프로젝트 만들기와 npm audit 점검Node.js 버전을 확인하고 npm 프로젝트를 만든 뒤, 취약한 lodash 4.17.15를 설치해 npm audit가 무엇을 보고하는지 확인합니다. npm audit fix로 고친 뒤 다시 점검하는 순서까지 실제 출력으로 정리합니다.
  • package.json과 package-lock.json 차이: npm ci로 확인하기package.json에는 허용하는 버전 범위가, package-lock.json에는 실제로 설치된 버전과 integrity 해시가 적힙니다. 같은 프로젝트에서 npm install과 npm ci를 번갈아 실행해 두 파일의 역할과 두 명령의 차이를 실제 출력으로 확인합니다.

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글