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

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

- 주소: https://copyandrun.com/blog/npm-audit-dependency-severity-gate/
- 분야: DevSecOps
- 발행일: 2026-11-16
- 태그: npm audit, audit-level, 종료 코드, CI, 의존성 점검

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

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

## 준비물

| 항목 | 내용 |
| --- | --- |
| 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. 심각도가 다른 패키지 설치하기

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

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

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

```text
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`에 어떻게 나뉘어 들어갔는지 확인합니다.

```bash
npm pkg get dependencies devDependencies
```

```json
{
  "dependencies": {
    "cookie": "^0.6.0",
    "word-wrap": "^1.2.3"
  },
  "devDependencies": {
    "lodash": "^4.17.15"
  }
}
```

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

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

```bash
npm audit
echo $?
```

```text
# 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`로 버립니다.

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

```text
low: 1
moderate: 1
high: 1
critical: 0
```

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

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

```bash
npm audit --audit-level=critical
echo $?
```

```text
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`를 붙이면 개발 의존성을 빼고 점검합니다.

```bash
npm audit --omit=dev
echo $?
```

```text
# 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`가 빠져 두 건이 됐습니다. 여기에 다시 네 단계를 넣습니다.

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

```text
low: 1
moderate: 1
high: 0
critical: 0
```

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

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

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

```bash
npm audit --json > audit.json
echo $?
```

```text
1
```

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

```bash
node -p "Object.keys(require('./audit.json'))"
```

```text
[ 'auditReportVersion', 'vulnerabilities', 'metadata' ]
```

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

```bash
node -p "require('./audit.json').metadata.vulnerabilities"
```

```text
{ info: 0, low: 1, moderate: 1, high: 1, critical: 0, total: 3 }
```

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

```bash
npm audit --omit=dev --json > audit-prod.json
node -p "require('./audit-prod.json').metadata.vulnerabilities"
```

```text
{ info: 0, low: 1, moderate: 1, high: 0, critical: 0, total: 2 }
```

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

```bash
node -p "JSON.stringify(require('./audit.json').vulnerabilities['word-wrap'], null, 2)"
```

```json
{
  "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가 같은 명령을 씁니다. 전체 의존성 기준과 실행 의존성 기준을 하나씩 등록합니다.

```bash
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
```

```json
{
  "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의 종료 코드를 그대로 돌려줍니다. `&&`와 `||`로 통과와 실패를 확인합니다.

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

```text
gate passed
gate failed: 1
```

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

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

```yaml
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로 확인하기](/blog/npm-package-json-lockfile-basics/)에 정리했습니다.

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로 잠금 파일 점검하기](/blog/osv-scanner-lockfile-vulnerabilities/)를 함께 봅니다.

## 자주 묻는 질문

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

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

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

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

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

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