SkillSpector

AI 에이전트 스킬용 보안 스캐너. 에이전트 스킬을 설치하기 전에 취약점, 악성 패턴, 보안 위험을 탐지합니다.

개요

AI 에이전트 스킬(Claude Code, Codex CLI, Gemini CLI 등에서 사용됨)은 암묵적 신뢰와 최소한의 검증만으로 실행됩니다. 연구 데이터셋에서 분석된 31,132개 스킬 중 26.1%의 스킬에 취약점이 존재하며 5.2%는 악의적 의도가 있는 것으로 보입니다.

SkillSpector는 "이 스킬은 설치해도 안전한가?" 라는 질문에 답하는 데 도움을 줍니다.

SkillSpector는 NVIDIA Verified Skills 파이프라인의 일부로, 게시 전에 에이전트 스킬을 스캔, 평가, 서명합니다. 통과한 스킬은 NVIDIA 스킬 카탈로그에 게시됩니다.

문서

설치 전 에이전트 스킬 스캔 — 호스팅 가이드: 언제 스캔할지, 보고서를 읽는 방법, 설치를 게이팅하는 방법.
개발 가이드 — 아키텍처, 패키지 레이아웃, 분석기 파이프라인 확장 방법.
분석 리소스 한도 — 실패 시 차단(fail-closed) 번들, 파서, 중첩 아티팩트, 원장(ledger), 발견 항목 상한.
Pi 확장 — 에이전트 세션 내부에서 스킬을 스캔하기 위해 SkillSpector를 Pi 도구로 설치합니다.
OpenCode 확장 — 에이전트 세션 내부에서 스킬을 스캔하기 위해 SkillSpector를 OpenCode 도구 및 /skillspector 명령으로 설치합니다.

기능

다중 형식 입력: Git 저장소, URL, zip 파일, 디렉터리 또는 단일 파일 스캔
17개 카테고리에 걸친 71개 취약점 패턴: 프롬프트 인젝션, 데이터 유출, 권한 상승, 공급망, 과도한 에이전시, 출력 처리, 시스템 프롬프트 유출, 메모리 포이즈닝, 도구 오용, 로그 에이전트, 반(反)거부, 트리거 남용, 위험한 코드(AST), 테인트 추적, YARA 시그니처, MCP 최소 권한, MCP 도구 포이즈닝
2단계 분석: 빠른 정적 분석 + 선택적 LLM 의미 평가
실시간 취약점 조회: SC4는 자동 오프라인 폴백과 함께 실시간 CVE 데이터를 위해 OSV.dev에 쿼리합니다
다중 출력 형식: 터미널, JSON, Markdown, SARIF 보고서
위험 점수 산정: 심각도 레이블과 명확한 권장 사항이 포함된 0-100 점수
베이스라인 / 오탐 억제: glob 규칙 또는 지문(fingerprint) 베이스라인을 통해 알려진 발견 항목을 수용하여 재스캔 시 새로운 문제만 표시되도록 합니다 (문서)

빠른 시작

설치

오픈 소스 소프트웨어 고지: 이 프로젝트는 추가적인 제3자 오픈 소스 소프트웨어 프로젝트를 다운로드하고 설치합니다. 사용 전에 해당 오픈 소스 프로젝트의 라이선스 조건을 검토하십시오.

먼저 가상 환경을 생성하고 활성화하십시오(모든 make 타깃은 venv가 활성화되어 있다고 가정합니다). uv 또는 pip를 사용하십시오. Makefile은 uv가 있으면 uv를, 그렇지 않으면 pip를 사용합니다.

uv를 사용한 빠른 설치(CLI 전용):

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

skillspector mcp를 실행할 계획이라면 설치 시 MCP extra를 설치하세요:

uv tool install '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 .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install

# Or install with development dependencies
make install-dev

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

배치 스캔

contrib/batch_scan/에서 스킬의 전체 디렉터리를 병렬로 스캔합니다:

python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20

다국어 감지(zh/ja/ko)와 터미널/JSON/Markdown 출력을 지원합니다.

더 높은 동시성을 가진 LLM 스캔을 위해서는 .env.example에 따라 여러 API 키를 구성하세요 — 키들이 계정 수준의 속도 제한을 공유하지 않는 경우, 이 풀은 처리량과 복원력을 향상시킵니다.

자세한 내용은 기여 가이드를 참조하세요.

LLM 지원에 관한 참고 사항: 기본 구성은 가장 저렴한 공개 옵션인 DeepSeek를 대상으로 합니다. DeepSeek-Chat은 서비스 종료가 예상되며, 기여자는 로컬 모델을 테스트할 하드웨어가 없습니다. 배치 스캐너는 원래 OpenAI 호환 엔드포인트로 테스트되었으며 — DeepSeek의 구조화된 출력 지원 부재로 인해 수동 JSON 파싱 패치가 필요했습니다. 더 범용적인 백엔드(Ollama, vLLM 또는 다른 제공자)를 기여할 수 있다면, PR을 매우 환영합니다.

MCP 레지스트리 스냅샷 비교하기

원시 레지스트리 페이로드 캡처(registry-before.json 및 registry-after.json)로 시작하세요. 스캔 보고서를 previous.json으로 저장한 다음, 이후 스캔을 생성된 로컬 보고서와 비교하세요:

skillspector scan registry-before.json --mcp-registry --format json --output previous.json
skillspector scan registry-after.json --mcp-registry --format json \
  --mcp-registry-compare previous.json --output compared.json

선택적 comparison 객체는 추가 및 제거된 서버 아이덴티티, 이전 값과 현재 값이 함께 표시된 변경된 정규화 필드, 그리고 unchanged_count를 나열합니다. 아이덴티티는 서버 이름과 버전이므로, 새 버전은 추가로 나타나고 이전 버전은 새 스캔에 없을 경우 제거로 나타납니다. 수집 소스와 스캔 타임스탬프는 비교에서 제외됩니다. unmodeled_changes는 정규화 필드는 일치하지만 원시 레코드 해시가 변경된 동일 아이덴티티 레코드를 나열하며, 이들은 변경되지 않은 것으로 집계되지 않습니다. 이는 스냅샷 모델 외부의 필드 변경 또는 원시 레코드의 배열 재정렬을 나타낼 수 있습니다. 패키지 및 원격 순서만의 변경은 정규화 필드 변경이 아닙니다. changed의 항목에도 스냅샷 모델 외부의 변경이 포함될 수 있으므로, 해당 변경을 확인하려면 원시 레코드를 검사하십시오. 동일한 선택 범위로 보고서를 비교하십시오. 현재 입력에 없는 서버는 제거된 것으로 보고되지만, 이는 해당 서버가 레지스트리에서 제거되었음을 증명하지는 않습니다.

비교 파일은 유효한 정규화 스냅샷을 가진 이 레지스트리 모드로 생성된 로컬 보고서여야 합니다. 형식이 잘못되었거나, 크기가 초과되었거나, 중복된 서버 아이덴티티는 거부됩니다. 이 옵션은 --mcp-registry를 필요로 하며, 파인딩 억제용 --baseline과는 별개입니다. 이 옵션은 파인딩을 억제하거나 위험 점수를 변경하지 않으며, 나열된 서버 엔드포인트를 가져오거나 실행하지도 않습니다.

오탐 억제 (baseline)

알려졌거나 수용된 파인딩을 억제하여 위험 점수가 미분류 이슈만 반영하도록 하고, 재스캔 시 새로운 파인딩만 표시되도록 합니다. 전체 참조는 억제 가이드를 참조하십시오.

# Accept all current findings into a baseline (run once), then commit it.
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml