
SkillSpector v2.11.1
AI 에이전트 스킬용 보안 스캐너. 설치 전에 Claude Code, Codex 및 MCP 스킬에서 취약점, 악성 패턴, 보안 위험, 프롬프트 인젝션, 데이터 유출 및 공급망 위험을 탐지합니다.
SkillSpector
AI 에이전트 스킬을 위한 보안 스캐너. 에이전트 스킬을 설치하기 전에 취약점, 악성 패턴, 보안 위험을 탐지합니다.
개요
AI 에이전트 스킬(Claude Code, Codex CLI, Gemini CLI 등에서 사용됨)은 암묵적인 신뢰와 최소한의 검증만으로 실행됩니다. 연구 데이터셋에서 분석된 31,132개 스킬 중 26.1%의 스킬에 취약점이 존재하며 5.2%는 악의적인 의도가 있는 것으로 보입니다.
SkillSpector는 "이 스킬은 설치해도 안전한가?" 라는 질문에 답하는 데 도움을 줍니다.
SkillSpector는 에이전트 스킬을 게시 전에 스캔, 평가, 서명하는 NVIDIA Verified Skills 파이프라인의 일부입니다. 검사를 통과한 스킬은 NVIDIA 스킬 카탈로그에 게시됩니다.
문서
- 설치 전 에이전트 스킬 스캔 — 호스팅 가이드: 언제 스캔해야 하는지, 보고서를 읽는 방법, 설치를 게이트하는 방법.
- 개발 가이드 — 아키텍처, 패키지 레이아웃, 분석기 파이프라인을 확장하는 방법.
- 보안 정책 — 의심되는 취약점을 NVIDIA PSIRT에 비공개로 신고합니다.
- 분석 리소스 한도 — 번들, 파서, 중첩 아티팩트, 원장, 발견 항목에 대한 fail-closed 상한.
- Pi 확장 — 에이전트 세션 내부에서 스킬을 스캔하기 위해 SkillSpector를 Pi 도구로 설치합니다.
- OpenCode 확장 — 에이전트 세션 내부에서 스킬을 스캔하기 위해 SkillSpector를 OpenCode 도구 및
/skillspector명령으로 설치합니다. - LLM 분석기 기반 가이드 —
LLMAnalyzerBase위에 LLM 기반 분석기 노드를 구축하는 방법. - 의존성 소스 리다이렉션 — SC4 발견 항목이 패키지를 가져오는 위치를 변경하는 스킬을 어떻게 표시하는지.
- 실시간 취약점 조회 (SC4) — SC4가 OSV.dev를 기준으로 의존성을 검사하는 방법.
- 평가 데이터셋 스캔 — 정적 패턴 분석기가 건너뛰는 평가 데이터셋 파일.
- MCP 최소 권한 분석 (LP1–LP4) 및 MCP 도구 중독 탐지 (TP1–TP4) — MCP 분석기에 대한 설계 노트.
기능
- 다중 형식 입력: Git 저장소, URL, zip 파일, 디렉터리 또는 단일 파일 스캔
- 17개 카테고리에 걸친 71개 취약점 패턴: 프롬프트 인젝션, 데이터 유출, 권한 상승, 공급망, 과도한 에이전시, 출력 처리, 시스템 프롬프트 유출, 메모리 중독, 도구 오용, 로그 에이전트, 반(反)거부, 트리거 남용, 위험한 코드(AST), 오염 추적, YARA 시그니처, MCP 최소 권한, MCP 도구 중독
- 2단계 분석: 빠른 정적 분석 + 선택적 LLM 의미 평가
- 실시간 취약점 조회: SC4가 자동 오프라인 폴백과 함께 실시간 CVE 데이터를 OSV.dev에 쿼리
- 다중 출력 형식: 터미널, JSON, Markdown, SARIF 보고서
- 위험 점수 산정: 심각도 레이블과 명확한 권장 사항이 포함된 0-100 점수
- 베이스라인 / 오탐 억제: glob 규칙 또는 지문 베이스라인을 통해 알려진 발견 항목을 수용하여 재스캔 시 새로운 문제만 표시 (문서)
빠른 시작
설치
오픈 소스 소프트웨어 고지: 이 프로젝트는 추가적인 타사 오픈 소스 소프트웨어 프로젝트를 다운로드하여 설치합니다. 사용 전에 해당 오픈 소스 프로젝트의 라이선스 조건을 검토하십시오.
지원되는 플랫폼에서 미리 빌드된 YARA wheel을 사용하여 설치하려면 Python 3.12 또는 3.13을 사용하세요. 아래 예시는 3.13을 명시적으로 선택합니다. 더 새로운 인터프리터에 대해서는 Python 설치 참고 사항을 참조하세요.
소스 설치의 경우 먼저 가상 환경을 생성하고 활성화하세요(모든 make
타깃은 venv가 활성화되어 있다고 가정합니다). uv 또는 pip를 사용하세요. Makefile은 uv가
사용 가능하면 uv를, 그렇지 않으면 pip를 사용합니다.
uv를 사용한 빠른 설치(CLI 전용):
uv tool install --python 3.13 git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector
skillspector mcp를 실행할 계획이라면 설치 시 MCP extra를 설치하세요:
uv tool install --python 3.13 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
출처:
# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
# Create and activate virtual environment
uv venv --python 3.13 .venv && source .venv/bin/activate
# or: python3.13 -m venv .venv && source .venv/bin/activate
# Install for production use
make install
기여하려면 지원되는 Python 인터프리터와 개발 종속성에 대해 개발 환경 설정을 따르세요.
Python 설치 참고 사항
패키지는 pyproject.toml에서 Python >=3.12,<3.16을 선언합니다.
이 범위가 모든 종속성과 플랫폼에 대해 미리 빌드된 wheel을 보장하지는 않습니다.
PyPI의 yara-python 4.5.4는
CPython 3.12/3.13 wheel을 제공하지만 CPython 3.14/3.15 wheel은 제공하지 않습니다.
이를 더 새로운 인터프리터에서 설치하려면 C 툴체인과 Python 개발 헤더를 갖춘
네이티브 소스 빌드가 필요합니다. 이러한 빌드는 OpenSSL 4 헤더에서 실패할 수 있으며,
이슈 #1008에서 해당 설치 문제와
업스트림 wheel 제공 여부를 추적하고 있습니다.
YARA를 컴파일하는 중에 설치가 실패하면 위 명령을 사용하여 Python 3.12 또는 3.13을
명시적으로 선택하세요. pipx를 사용하는 새로운 CLI 전용 설치의 경우, 먼저 Python 3.13을
설치하고 PATH에서 python3.13을 사용할 수 있게 한 다음, 다음을 실행하세요:
pipx install --python python3.13 git+https://github.com/NVIDIA/skillspector.git
업스트림 wheel 빌드 업데이트는 PyPI에 새 릴리스를 게시하는 것과는 별개입니다. 더 새로운 인터프리터를 선택하기 전에 게시된 파일을 확인하세요. 소스 빌드가 여전히 필요할 수 있습니다.
Docker (Python 불필요)
포함된 Dockerfile에서 로컬로 빌드하여 Python을 설치하지 않고도 SkillSpector를 실행할 수 있습니다. 이미지는 Docker 공식 Python 3.12-slim-bookworm 이미지를 기반으로 합니다.
이미지 빌드:
make docker-build
# or: docker build -t skillspector .
로컬 디렉터리 스캔은 현재 디렉터리를 컨테이너의 작업 디렉터리인 /scan에 마운트하여 수행합니다:
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm
LLM 분석을 통한 스캔 — 로컬 .env 파일로 자격 증명을 전달하여 수행:
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF
docker run --rm \
-v "$PWD:/scan" \
--env-file .env \
skillspector scan ./my-skill/
자격 증명을 셸 환경에서 직접 전달할 수도 있습니다:
docker run --rm \
-v "$PWD:/scan" \
-e SKILLSPECTOR_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
skillspector scan ./my-skill/
마운트된 디렉터리에 작성하여 호스트 파일시스템에 보고서 작성:
docker run --rm --user "$(id -u):$(id -g)" \
-v "$PWD:/scan" \
skillspector scan ./my-skill/ --no-llm --format json --output report.json
반복되는 정적 스캔을 위한 선택적 별칭:
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm
기본 사용법
# Scan a local skill directory
skillspector scan ./my-skill/
# Scan a single SKILL.md file
skillspector scan ./SKILL.md
# Scan a Git repository
skillspector scan https://github.com/user/my-skill
# Scan a zip file
skillspector scan ./my-skill.zip
크기 제한
SkillSpector는 과도한 다운로드와 zip 폭탄의 영향을 제한하기 위해 원격 및 아카이브 입력에 두 가지 독립적인 상한을 적용합니다:
- 수집당 상한:
INGEST_MAX_BYTES(100 MiB) — 스트리밍 URL 다운로드, zip 아카이브의 총 비압축 크기, Git 저장소의 클론 후 디스크 사용량에 적용됩니다. - Zip 멤버 상한:
INGEST_MAX_ZIP_MEMBERS(10,000) — 단일 zip의 항목 수를 제한합니다.
파일당 1 MB 분석 상한(MAX_FILE_BYTES)은 별개의 하위 단계 제한이라는 점에 유의하십시오. 이는 이미 수집된 디렉터리에서 개별 분석기가 읽어들이는 양을 제한합니다. 위의 수집 상한은 애초에 디스크에 기록될 수 있는 콘텐츠의 양을 제한합니다. 두 수집 상한 중 하나라도 위반되면 IngestLimitExceededError와 함께 fail-closed 방식으로 실패합니다.
출력 형식
# Terminal output (default) - pretty formatted
skillspector scan ./my-skill/
# JSON output - machine readable
skillspector scan ./my-skill/ --format json --output report.json
# Markdown output - for documentation
skillspector scan ./my-skill/ --format markdown --output report.md
# SARIF output - for CI/CD integration and IDE tooling
skillspector scan ./my-skill/ --format sarif --output report.sarif
재귀적 컬렉션 스캔
--recursive는 SKILL.md를 포함하는 바로 아래 하위 디렉터리를 독립적인
스킬로 스캔하며, 기본 집계 한도는 32개 스킬입니다. 이 한도를 높이거나 낮추려면:
skillspector scan ./my-skills/ --recursive --max-skills 100 --no-llm --format json