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 예시 발췌:

[
  {
    "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"
  }
]

종료 코드

새 캠페인 추가

새로운 공급망 공격이 발견되면 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에 다음을 추가하세요:

  root@kitploit:~

  ignore-scripts=true
  engine-strict=true
  

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

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

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

라이선스

MIT. 자세한 내용은 LICENSE를 참조하세요.

면책 조항

shai-scan은 탐지 보조 도구일 뿐, 포괄적인 보안 감사, 의존성 검토 또는 위협 인텔리전스 플랫폼을 대체하지 않습니다. 제공된 데이터베이스를 기반으로 알려진 손상된 버전을 식별합니다. 새로운 또는 제로데이 공급망 공격은 캠페인이 추가될 때까지 탐지되지 않을 수 있습니다. 항상 심층 방어를 실천하세요: 의존성 감사, 버전 고정, 출처 증명 확인, CI/CD 파이프라인 모니터링.