shai-scan

npm 및 PyPI 공급망 손상 탐지를 위한 의존성 제로 CLI 스캐너

왜 필요한가?

2026년 5월 11일, 미니 샤이훌루드(Mini Shai-Hulud) (CVE-2026-45321, GHSA-g7cv-rxg3-hmpx)라는 자가 전파형 공급망 웜이 npm 생태계를 손상시켰습니다. TeamPCP(일명 DeadCatx3, PCPcat, ShellForce, CipherForce)에 의한 이 악성코드는 GitHub Actions OIDC 토큰을 탈취하여 유효한 SLSA Build Level 3 출처 증명을 가진 악성 패키지를 게시했습니다. CI/CD 파이프라인, 클라우드 제공자, 암호화폐 지갑에서 자격 증명을 도용했으며, Claude Code와 VS Code에 지속성 후크를 설치했습니다. 내장된 데드맨 스위치(dead-man switch)는 npm 토큰이 취소되면 사용자의 홈 디렉터리를 지우겠다고 위협했습니다.

영향을 받은 패키지에는 TanStack 라우터 및 시작 패키지, Mistral AI SDK, OpenSearch 클라이언트, UiPath 도구 등 수십 개가 포함되었습니다. 공급망 공격은 빠르게 확산되므로, 조직은 새로운 의존성을 추가하지 않고도 어디서나 실행할 수 있는 가볍고 신뢰할 수 있는 스캐너가 필요합니다.

기능

• Lockfile 스캔 — package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, bun.lockb, poetry.lock, Pipfile.lock, requirements.txt에서 손상된 npm 및 PyPI 패키지를 탐지합니다
• 시스템 IOC 검사 — 실행 중인 프로세스, 파일 시스템 아티팩트, 네트워크 연결, 알려진 지속성 경로에서 침해 지표를 스캔합니다
• 런타임 의존성 제로 — Node.js/Bun 내장 모듈(fs, path, child_process, os)만 사용합니다. 스캐너가 공급망 위험을 증가시키지 않습니다
• 다중 출력 형식 — 사람이 읽을 수 있는 텍스트, 기계가 읽을 수 있는 JSON, GitHub Code Scanning용 SARIF
• CI/CD 네이티브 — 자동화를 위한 종료 코드 설계 (0 = 깨끗함, 1 = 발견, 2 = 오류)
• 경로 독립적 — 모든 디렉터리 허용; 기본값은 현재 작업 디렉터리
• 캠페인 기반 데이터베이스 — 새로운 공격 웨이브가 src/db.ts에 개별 캠페인으로 추가됩니다; 파일을 업데이트하고 다시 실행하세요

설치

설치가 필요 없습니다. 원하는 패키지 실행기로 직접 실행하세요:

# npx
npx @digi4care/shai-scan

# bunx
bunx @digi4care/shai-scan

# pnpm dlx
pnpm dlx @digi4care/shai-scan

전역 설치 (선택 사항):

npm install -g @digi4care/shai-scan
# 또는
pnpm add -g @digi4care/shai-scan

소스에서:

git clone https://github.com/digi4care/shai-scan.git
cd shai-scan
pnpm install
bun run src/cli.ts --help   # Bun (개발에 권장)
# 또는 Node.js로 빌드 후 실행:
pnpm run build && node dist/cli.js --help

사용법

현재 프로젝트 스캔

npx @digi4care/shai-scan

특정 경로 스캔

npx @digi4care/shai-scan ~/projects/my-app

자동화를 위한 JSON 출력

npx @digi4care/shai-scan --json .

GitHub Code Scanning을 위한 SARIF 출력

npx @digi4care/shai-scan --sarif --sarif-file results.sarif .

CI/CD 종료 코드

#!/bin/bash
npx @digi4care/shai-scan --severity high . || {
  code=$?
  if [ "$code" -eq 1 ]; then
    echo "공급망 발견 사항 감지됨"
    exit 1
  elif [ "$code" -eq 2 ]; then
    echo "스캐너 오류"
    exit 2
  fi
}

CI/CD 통합

GitHub Actions (텍스트 출력)

name: Supply Chain Scan
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: npx @digi4care/shai-scan --severity high .

GitHub Actions (SARIF 업로드)

name: Supply Chain Scan SARIF
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: npx @digi4care/shai-scan --sarif --sarif-file results.sarif .
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

출력 형식

형식	플래그	설명
텍스트	(기본값)	심각도, 패키지 이름, 버전, 캠페인 세부 정보가 포함된 사람이 읽을 수 있는 표
JSON	--json	SIEM 또는 사용자 지정 대시보드에 적합한 구조화된 JSON 배열
SARIF	--sarif	GitHub Code Scanning, GitLab Secure 또는 기타 SARIF 소비자에게 업로드하기 위한 OASIS SARIF 2.1.0 형식

JSON 예시 발췌:

[
  {
    "package": "@tanstack/react-router",
    "version": "1.169.5",
    "ecosystem": "npm",
    "severity": "critical",
    "campaign": "mini-shai-hulud-wave4",
    "cve": "CVE-2026-45321",
    "reference": "https://github.com/TanStack/router/security/advisories/GHSA-g7cv-rxg3-hmpx"
  }
]

종료 코드

코드	의미
0	손상된 패키지 또는 IOC 미감지
1	하나 이상의 발견 사항 감지
2	런타임 오류 (잘못된 경로, 읽을 수 없는 lockfile 등)

새 캠페인 추가

새로운 공급망 공격이 발견되면 src/db.ts를 업데이트하세요:

1. 영향을 받는 패키지와 버전이 포함된 새 CompromisedVersion[] 배열을 추가하세요
2. CVE/GHSA 식별자, 심각도, 설명, 참조 URL 및 IOC 지표를 포함한 새 Campaign 객체를 CAMPAIGNS 배열에 추가하세요
3. buildLookup() 함수가 다음 실행 시 자동으로 조회 맵을 다시 구축합니다

Bun을 사용하는 경우 재빌드 단계가 필요하지 않습니다. src/db.ts 변경 사항은 bun run src/cli.ts로 즉시 적용됩니다. npm 패키지의 경우 편집 후 pnpm run build를 실행하세요.

보안 고려 사항

• 런타임 의존성 제로: 스캐너는 Node.js/Bun 내장 모듈만 사용합니다. 런타임에 타사 코드를 다운로드하거나 실행하지 않으므로 스캐너 자체가 손상 벡터가 될 위험이 없습니다.

• pnpm을 패키지 관리자로 사용: pnpm은 엄격한 lockfile을 사용하고 기본적으로 라이프사이클 스크립트를 실행하지 않으며 콘텐츠 주소 지정 저장소를 지원합니다. 이러한 속성은 다른 패키지 관리자에 비해 공격 표면을 줄여줍니다.

• 권장 .npmrc 설정: 패키지 설치 시 최대 보호를 위해 프로젝트 또는 전역 .npmrc에 다음을 추가하세요:

  ignore-scripts=true
  engine-strict=true
  

• 네트워크 호출 없음: shai-scan은 홈으로 전화를 걸거나, 서명을 다운로드하거나, API 키가 필요하지 않습니다. 모든 캠페인 데이터는 패키지와 함께 제공됩니다.

영향을 받은 패키지 (현재 캠페인)

다음 패키지와 버전은 CVE-2026-45321(미니 샤이훌루드 웨이브 4)에서 손상된 것으로 알려져 있습니다. 이는 대표적인 하위 집합입니다. 전체 목록은 src/db.ts에 유지됩니다.