adamsjack711-ux/pkgxrayAI 에이전트, npm 패키지 및 MCP 서버를 위한 설치 전 보안. 제로 종속성 로컬 정적 분석; 일반 스캔은 패키지 코드를 실행하지 않습니다.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — 설치 전에 패키지를 분석하세요" width="820"> # pkgxray — npm 패키지, MCP 서버, AI 에이전트를 위한 설치 전 보안 npm 패키지나 MCP 서버를 **설치하거나 연결하기 전에** 검사하여 결정적이고 증거 기반의 `SAFE`, `REVIEW`, `BLOCK` 판정을 받으세요. 로컬, 제로 의존성 정적 분석 — 일반 스캔은 패키지 코드를 절대 실행하지 않습니다. [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**웹사이트**](https://pkgxray.ca) · [**문서**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**캘리브레이션**](https://pkgxray.ca/stats) · [**버그 신고**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard가 [email protected]을 SAFE A+ 판정으로 통과시킨 뒤, 트로이 목마가 심긴 샘플을 BLOCK F 판정과 HIGH 자격 증명 접근 발견으로 차단하는 모습" width="820"> <sub>실제 실행: <code>guard</code>가 <code>[email protected]</code>을 통과시킨 뒤, 2024년 <code>@solana/web3.js</code> 침해 사고를 모델링한 샘플을 차단합니다.</sub> </div> ## 주요 기능 - **런타임 의존성 제로** — 순수 Node, 전적으로 사용자 머신에서 실행(~25 ms 정적 패스). - **일반 스캔은 패키지 코드를 실행하지 않음** — tarball을 격리 상태에서 바이트로 읽습니다. - **결정적이고 출처가 명시된 판정** — 모든 발견 사항이 파일과 증거를 명시합니다. 판정 경로에 LLM이 없으므로 주입된 텍스트가 판정을 좌우할 수 없습니다. - **에이전트 시대에 맞게 설계** — 연결 전에 MCP 서버를 검증하고, 에이전트가 실행하는 설치를 게이트하며, 실시간 MCP 트래픽을 재감사합니다. - **캘리브레이션 및 회귀 게이트 적용** — 다운로드 상위 1000개 패키지에서 휴리스틱 오탐 차단 0건을 CI에서 강제합니다. > **[1. 빠른 시작](#quick-start)** · [2. 스캔 및 탐지 항목](#what-it-scans--detects) · [3. 판정](#verdicts) · [4. 사용법](#usage) · [5. 통합](#integrations) · [6. 다른 도구와 비교](#how-it-compares) · [7. 문서](#documentation) ## 왜 필요한가 AI 코딩 어시스턴트는 머신 속도로 패키지를 설치하고 MCP 서버에 연결하며, 인간이 코드를 읽지 않는 경우가 많습니다. Sonatype은 2025년 한 해 모니터링 대상 에코시스템에서 **454,600개 이상의 새로운 악성 오픈소스 패키지**를 식별했으며, 그중 99% 이상이 npm에 있었습니다 ([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `npm audit`은 *알려진 CVE가 있나?* 를 묻습니다. pkgxray는 *코드가 실제로 무엇을 하는가*도 묻습니다 — 어떤 것도 설치되기 전에. ## 빠른 시작 **1. 알려진 양성 패키지 스캔** (pkgxray 설치 불필요): ```bash npx --yes [email protected] guard npm:[email protected] ``` tarball을 격리 상태로 스테이징한 뒤 정적 및 공급망 검사를 실행합니다 — `npm install` 없이, 라이프사이클 스크립트 없이, 패키지 코드 실행 없이. <details> <summary>샘플 출력</summary> ```text 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) ``` </details> **2. 판정 읽기:** | 판정 | 종료 코드 | 의미 | |---|---:|---| | `SAFE` | `0` | 높음 또는 중간 위험 지표 없음. 기본 정책은 승격을 허용합니다. | | `REVIEW` | `3` | 증거가 불완전하거나 권한 있는 기능에 인간 검토가 필요합니다. | | `BLOCK` | `2` | 높은 심각도의 인용된 증거 — 거부하거나 조사하세요. | `SAFE`는 패키지가 무해하다는 증명이 아닙니다. 정적 분석은 런타임에만 다운로드되는 페이로드를 볼 수 없습니다. [위협 모델](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)을 참조하세요. **3. 제공된 비활성 픽스처에서 BLOCK 확인:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` 이 픽스처는 분할 문자열 SSH 키 읽기 및 유출을 모델링한 비활성 소스 텍스트입니다 — **절대 실행되지 않습니다**. 인용된 파일과 증거와 함께 `BLOCK`(종료 코드 `2`)을 반환합니다. **4. 워크플로우에 추가** — [재검사 및 CI](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck), [MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server), [Hookshot 설치 게이트](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **두 가지 실행 모델.** 기본 `guard` 및 `audit` 스캔은 **정적**입니다 — 패키지 코드가 절대 실행되지 않습니다. MCP 서버를 열거하면 서버가 실행될 수 있고, `mcp-proxy`는 게이트 뒤에서 실행합니다. 옵트인 [`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md)는 샌드박스에서 패키지를 *실행*하여 동작을 확인하는 유일한 의도적 예외입니다 — 악성을 확인할 수는 있지만 패키지가 안전하다는 증명은 불가능합니다. 전체 경계: [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## 스캔 및 탐지 항목 **스캔 대상** — `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 기능 표면 남용. 전체 적용 범위 매트릭스와 알려진 '나중에 다운로드' 사각지대는 [위협 모델](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)에 있습니다. 나란히 비교한 표는 [웹사이트](https://pkgxray.ca/#catches)에 있습니다. ## 판정 | 판정 | 권장 조치 | |---|---| | `SAFE` | 설치하세요. 기본적으로 `safe`만 격리에서 승격됩니다. | | `REVIEW` | 승격 전에 격리된 사본을 검사하세요. | | `BLOCK` | 설치하지 마세요. 모든 발견 사항이 파일과 증거를 명시합니다. | 종료 코드는 안정적이며 CI 친화적입니다: **`0`** 안전/허용 · **`2`** 차단 · **`3`** 검토. ## 사용법 ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json). ## 통합 모든 진입점 뒤에는 하나의 엔진이 있습니다. "지원함(Works with)"은 문서화된 설정 가이드가 있다는 뜻이지, 공급업체가 보증한 통합이 아닙니다. | 위치 | 역할 | 가이드 | |---|---|---| | 코딩 에이전트 — Codex, Claude Code, Cursor, Windsurf | 설치를 게이트하고 감사 도구를 에이전트에 노출 | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | MCP 클라이언트 | 연결 전에 서버 검증. pkgxray 자체를 MCP 서버로 실행 | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | 의존성이 정책을 위반하면 빌드 실패 | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | 설치 게이트 — Hookshot | 에이전트가 설치하려는 모든 패키지에 `guard` 실행 | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | 런타임 MCP 게이트 | 실시간 MCP 서버를 프록시하고 모든 도구 호출을 게이트 | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | 의존성 모니터링 | 예약에 따라 설치된 의존성을 재검증하고 업그레이드를 사전 검증 | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 다른 도구와 비교 pkgxray를 `npm audit` / OSV-Scanner *대신*이 아니라 *함께* 실행하세요 — 그들은 *"알려진 CVE?"*에 답합니다. 같은 분야(동작 기반 공급망 검증 — Socket.dev, OpenSSF 패키지 분석, Cisco MCP Scanner)의 도구에 대한 전체 기능 비교는 [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md)와 [웹사이트](https://pkgxray.ca/#comparison)에 있습니다. ## 근거 **다운로드 상위 1000개 패키지에 대한 휴리스틱 오탐 차단 0건 캘리브레이션**은 CI에서 회귀 게이트로 강제되며([범위 및 방법론](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), 공개된 실행 결과는 [pkgxray.ca/stats](https://pkgxray.ca/stats)에 있습니다. 이 주장은 가장 많이 설치된 패키지 집합에 한정됩니다 — 모든 패키지에서 오탐 차단이 0건이라는 주장이 아닙니다. ## 문서 | 문서 | 내용 | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | 파이프라인, 진입점, 원칙 | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | 범위, 사각지대, 프롬프트 인젝션 대응 | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | MCP 검증, 런타임 프록시, 레지스트리 항목 | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | 옵트인 동작 카나리 | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json`, 심각도 정책, `recheck`, 캐시 서버 | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | 캘리브레이션 및 다른 도구와의 비교 | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | 1.0 계약, `--format json` 스키마 | [문서 인덱스](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md)에서 시작하세요. ## 기여 ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md)와 [행동 강령](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md)을 읽어주세요. 취약점은 [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md)에 따라 비공개로 신고해주세요. 릴리스는 테스트, 캘리브레이션 벤치마크, pkgxray 자체 공급망 가드에 의해 게이트되며, 출처 증명(SLSA attestation)과 함께 npm에 게시됩니다. <div align="center"> <sub><a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> 제작 · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
