pkgxray — npm 패키지, MCP 서버, AI 에이전트를 위한 설치 전 보안

npm 패키지나 MCP 서버를 설치하거나 연결하기 전에 검사하여 결정적이고 증거 기반의 SAFE, REVIEW, BLOCK 판정을 받으세요. 로컬, 제로 의존성 정적 분석 — 일반 스캔은 패키지 코드를 절대 실행하지 않습니다.

웹사이트 · 문서 · 캘리브레이션 · 버그 신고

_{실제 실행: guard가 [email protected]을 통과시킨 뒤, 2024년 @solana/web3.js 침해 사고를 모델링한 샘플을 차단합니다.}

주요 기능

• 런타임 의존성 제로 — 순수 Node, 전적으로 사용자 머신에서 실행(~25 ms 정적 패스).
• 일반 스캔은 패키지 코드를 실행하지 않음 — tarball을 격리 상태에서 바이트로 읽습니다.
• 결정적이고 출처가 명시된 판정 — 모든 발견 사항이 파일과 증거를 명시합니다. 판정 경로에 LLM이 없으므로 주입된 텍스트가 판정을 좌우할 수 없습니다.
• 에이전트 시대에 맞게 설계 — 연결 전에 MCP 서버를 검증하고, 에이전트가 실행하는 설치를 게이트하며, 실시간 MCP 트래픽을 재감사합니다.
• 캘리브레이션 및 회귀 게이트 적용 — 다운로드 상위 1000개 패키지에서 휴리스틱 오탐 차단 0건을 CI에서 강제합니다.

1. 빠른 시작 · 2. 스캔 및 탐지 항목 · 3. 판정 · 4. 사용법 · 5. 통합 · 6. 다른 도구와 비교 · 7. 문서

왜 필요한가

AI 코딩 어시스턴트는 머신 속도로 패키지를 설치하고 MCP 서버에 연결하며, 인간이 코드를 읽지 않는 경우가 많습니다. Sonatype은 2025년 한 해 모니터링 대상 에코시스템에서 454,600개 이상의 새로운 악성 오픈소스 패키지를 식별했으며, 그중 99% 이상이 npm에 있었습니다 (Sonatype). npm audit은 알려진 CVE가 있나? 를 묻습니다. pkgxray는 코드가 실제로 무엇을 하는가도 묻습니다 — 어떤 것도 설치되기 전에.

빠른 시작

1. 알려진 양성 패키지 스캔 (pkgxray 설치 불필요):

npx --yes [email protected] guard npm:[email protected]

tarball을 격리 상태로 스테이징한 뒤 정적 및 공급망 검사를 실행합니다 — npm install 없이, 라이프사이클 스크립트 없이, 패키지 코드 실행 없이.

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. 판정 읽기:

SAFE는 패키지가 무해하다는 증명이 아닙니다. 정적 분석은 런타임에만 다운로드되는 페이로드를 볼 수 없습니다. 위협 모델을 참조하세요.

3. 제공된 비활성 픽스처에서 BLOCK 확인:

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

이 픽스처는 분할 문자열 SSH 키 읽기 및 유출을 모델링한 비활성 소스 텍스트입니다 — 절대 실행되지 않습니다. 인용된 파일과 증거와 함께 BLOCK(종료 코드 2)을 반환합니다.

4. 워크플로우에 추가 — 재검사 및 CI, MCP, Hookshot 설치 게이트.

두 가지 실행 모델. 기본 guard 및 audit 스캔은 정적입니다 — 패키지 코드가 절대 실행되지 않습니다. MCP 서버를 열거하면 서버가 실행될 수 있고, mcp-proxy는 게이트 뒤에서 실행합니다. 옵트인 canary는 샌드박스에서 패키지를 실행하여 동작을 확인하는 유일한 의도적 예외입니다 — 악성을 확인할 수는 있지만 패키지가 안전하다는 증명은 불가능합니다. 전체 경계: SECURITY.md.

스캔 및 탐지 항목

스캔 대상 — pkgxray guard npm:name@version, github:owner/repo, 로컬 디렉터리, 전체 잠금 파일(npm, yarn, pnpm), MCP 서버, AI 에이전트 확장.

탐지 항목 — 자격 증명 탈취(분할 조각 경로 포함), 클라우드 인스턴스 메타데이터 및 시크릿 저장소 탈취, 프롬프트 인젝션, 유니코드 밀수, base64 페이로드 및 2단계 로더, 데이터 유출, 지속성(셸 프로파일, OS 스케줄러, 주입된 CI/CD 워크플로우), 자체 삭제 드로퍼, 레지스트리 웜 복제(설치 시 npm publish), 난독화된 계산 인자 실행, 알려진 CVE(다운로드 전 OSV 활용), npm↔GitHub 아티팩트 불일치, 트로이 목마 업데이트(recheck), MCP 기능 표면 남용.

전체 적용 범위 매트릭스와 알려진 '나중에 다운로드' 사각지대는 위협 모델에 있습니다. 나란히 비교한 표는 웹사이트에 있습니다.

판정

종료 코드는 안정적이며 CI 친화적입니다: 0 안전/허용 · 2 차단 · 3 검토.

사용법

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

선택적인 .pkgxray.json 하나(모든 진입점에서 읽음)로 정책을 조정합니다. 설정이 없으면 최대 엄격함을 의미합니다. CVE는 절대 허용 해제할 수 없고, 모든 완화가 출력에 표시되며, 오류가 발생한 스캔은 fail-closed로 review 처리됩니다. 스키마 및 불변 조건: configuration.md · .pkgxray.example.json.

통합

모든 진입점 뒤에는 하나의 엔진이 있습니다. "지원함(Works with)"은 문서화된 설정 가이드가 있다는 뜻이지, 공급업체가 보증한 통합이 아닙니다.

다른 도구와 비교

pkgxray를 npm audit / OSV-Scanner 대신이 아니라 함께 실행하세요 — 그들은 *"알려진 CVE?"*에 답합니다. 같은 분야(동작 기반 공급망 검증 — Socket.dev, OpenSSF 패키지 분석, Cisco MCP Scanner)의 도구에 대한 전체 기능 비교는 docs/comparison.md와 웹사이트에 있습니다.

근거

다운로드 상위 1000개 패키지에 대한 휴리스틱 오탐 차단 0건 캘리브레이션은 CI에서 회귀 게이트로 강제되며(범위 및 방법론), 공개된 실행 결과는 pkgxray.ca/stats에 있습니다. 이 주장은 가장 많이 설치된 패키지 집합에 한정됩니다 — 모든 패키지에서 오탐 차단이 0건이라는 주장이 아닙니다.

문서

문서 인덱스에서 시작하세요.

기여

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

Pull request를 환영합니다 — CONTRIBUTING.md와 행동 강령을 읽어주세요. 취약점은 SECURITY.md에 따라 비공개로 신고해주세요. 릴리스는 테스트, 캘리브레이션 벤치마크, pkgxray 자체 공급망 가드에 의해 게이트되며, 출처 증명(SLSA attestation)과 함께 npm에 게시됩니다.