개요
SkillSpector는 AI 에이전트 스킬의 취약점, 악성 패턴 및 보안 위험을 분석하며, Git 리포지토리, URL, 파일 등 다양한 입력 형식을 지원하고, 위험 점수와 다양한 형식의 상세 보고서를 제공하며, 선택적으로 LLM 시맨틱 분석을 사용하여 탐지를 강화할 수 있습니다.
README 미리보기
# SkillSpector\n\n**Security scanner for AI agent skills.** Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.\n\n[](https://www.python.org/downloads/)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n\n## Overview\n\nAI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal vetting. Research shows that **26.1% of skills contain vulnerabilities** and **5.2% show likely malicious intent**.\n\nSkillSpector helps you answer: **"Is this skill safe to install?"**\n\n## Documentation\n\n- **[Development guide](docs/DEVELOPMENT.md)** — Architecture, package layout, and how to extend the analyzer pipeline.\n\n## Features\n\n- **Multi-format input**: Scan Git repos, URLs, zip files, directories, or single files\n- **64 vulnerability patterns** across 16 categories: prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning\n- **Two-stage analysis**: Fast static analysis + optional LLM semantic evaluation\n- **Live vulnerability lookups**: SC4 queries [OSV.dev](https://osv.dev) for real-time CVE data with automatic offline fallback\n- **Multiple output formats**: Terminal, JSON, Markdown, and SARIF reports\n- **Risk scoring**: 0-100 score with severity labels and clear recommendations\n\n## Quick Start\n\n### Installation\n\nCreate and activate a virtual environment first (all `make` targets assume the venv is active). Use **uv** or **pip**; the Makefile uses `uv` if available, otherwise `pip`.\n\n```bash\n# Clone the repository\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\n\n# Create and activate virtual environment\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\n\n# Install fo
FAQ (5)
문제 해결SkillSpector TP4(`mcp_tool_poisoning`) LLM 배치가 직렬로 실행되어 스캔 타임아웃이 발생하는 문제를 어떻게 해결하나요?
2026-10-06에 main에 병합된 PR #731이 포함된 SkillSpector 빌드로 업그레이드하세요. 이 수정은 src/skillspector/nodes/analyzers/mcp_tool_poisoning.py의 _check_tp4를 다음에서:
batch_outcome = analyzer.run_batches_detailed(batches)다음으로 변경합니다:
batch_outcome = run_async(analyzer.arun_batches_detailed(batches))이는 시맨틱 분석기 및 메타 리뷰와 동일한 공유 동시 실행 러너를 사용합니다. 다음과 같이 동시성 제한을 설정하세요:
export SKILLSPECTOR_MAX_LLM_CONCURRENCY=4값을 1로 설정하면 여전히 직렬 실행이 강제됩니다. 결과는 배치 순서를 유지하므로 TP4_MAX_FINDINGS와 원장 프로젝션은 기존과 동일하게 동작합니다. 테스트에서 TP4는 약 270초에서 75초로, 전체 스캔은 320초에서 206초로 단축되었습니다. 즉시 업그레이드할 수 없는 경우 임시 해결 방법으로 SKILLSPECTOR_MAX_WORKFLOW_SECONDS를 늘리거나 코드 청크 수를 줄이세요.
문제 해결커스텀 YARA 규칙이 컴파일에 실패할 때 SAFE를 반환하는 대신 SkillSpector가 실패하도록 만들려면 어떻게 해야 하나요?
이 문제는 커밋 9749372의 SkillSpector 2.11.2에 영향을 미칩니다. PR #557에서 수정되었으므로, 해당 PR이 포함된 main 빌드 또는 릴리스로 업그레이드하세요.
업그레이드 후에는 잘못된 .yar 파일이 경로와 이유를 포함한 WARNING을 발생시키고, static_yara가 degraded/partial로 보고되며, --fail-on-incomplete이 SAFE를 반환하는 대신 0이 아닌 값으로 종료됩니다.
즉시 업그레이드할 수 없는 경우, 스캔하기 전에 모든 커스텀 규칙을 검증하세요:
for f in rules/*.yar; do
python -c "import sys,pathlib,yara; p=pathlib.Path(sys.argv[1]); p.read_text(encoding='utf-8'); yara.compile(filepath=str(p))" "$f" || exit 1
done이 명령은 UTF-8 디코딩과 YARA 컴파일을 모두 확인합니다. UTF-8 BOM을 제거하려면 다음을 사용하세요:
sed -i '1s/^\xEF\xBB\xBF//' rules/acme.yarWindows-1252 규칙을 UTF-8로 변환하려면 다음을 사용하세요:
iconv -f WINDOWS-1252 -t UTF-8 rules/acme.yar -o rules/acme.yar.utf8 \
&& mv rules/acme.yar.utf8 rules/acme.yar영향을 받는 버전에서는 SKILLSPECTOR_LOG_LEVEL=DEBUG로 실행하면 건너뛴 규칙 메시지를 볼 수 있지만, 스캔이 여전히 성공적으로 완료되므로 종료 코드에 의존하지 마세요.
문제 해결“Send BTC”가 포함된 Bitcoin 자금 조달 문서에서 발생한 SkillSpector ransomware_behavior 오탐지를 어떻게 수정하나요?
오탐지(false positive)는 ransomware_behavior YARA 규칙이 nocase send\s+.*btc 랜섬 노트 패턴으로 일반적인 결제 문구와 매칭되고 any of them을 사용했기 때문에 발생했으며, 따라서 암호화나 몸값 요구가 필요하지 않았습니다. 이 문제는 PR #608(commit a0d489e6, 2026-10-08에 머지됨, Jira SKILLSPECT-232)에서 수정되었습니다. 이제 이 규칙은 Bitcoin 결제 문구 주변에 랜섬 특정 컨텍스트를 요구하며, 암호화, 이름 변경, 덮어쓰기 및 위협 지표는 유지하면서 절의 시작 부분에 오는 결제 안내를 필터링합니다. commit a0d489e6이 포함된 릴리스로 SkillSpector를 업데이트한 다음 ClawHub/SkillSpector 감사를 다시 실행하세요. 즉시 업데이트할 수 없는 경우, 일반적인 send ... BTC 패턴을 피하도록 자금 관련 안내 문구를 임시로 바꾸세요. 예를 들어 "Fund the account using Bitcoin,"으로 바꾼 후 다시 스캔하세요.
문제 해결`skillspector --help`가 API 키 누락 경고를 표시하고 느리게 실행되는 이유는 무엇인가요?
이 문제는 skillspector.graph가 모듈 임포트 시점에 graph = create_graph()를 실행하면서 발생하며, 이로 인해 CLI가 --help나 --version 실행 시에도 모든 분석기를 빌드하고 초기화합니다. 즉시(eager) 그래프 생성을 지연(lazy) 방식의 스레드 안전한 그래프 프록시로 대체하는 PR #436이 포함된 릴리스로 업그레이드하세요. 그래프는 실제 graph.invoke() 또는 graph.ainvoke() 호출이 처음 발생할 때만 컴파일되며, 기존 API는 그대로 유지됩니다. 업그레이드 후 프로바이더 자격 증명을 삭제하고 time skillspector --help로 확인하세요. 도움말이 키 누락 경고 없이 즉시 표시되어야 합니다. 실제 스캔이 사용할 수 없는 분석기를 초기화할 때는 자격 증명 누락 경고가 계속 표시됩니다.
문제 해결SkillSpector가 .ZIP 또는 .ZiP 압축 파일을 추출하지 않고 일반 파일로 취급하는 문제를 어떻게 해결하나요?
이 문제는 InputHandler.resolve(), _download_file(), _download_transitive_file()에서 대소문자를 구분하는 .endswith(".zip") 검사를 사용하기 때문에 발생합니다. ZIP 확장자를 대소문자 구분 없이 인식하는 병합된 PR #727이 포함된 빌드로 SkillSpector를 업데이트하세요. 업데이트가 불가능한 경우, 아카이브의 이름을 소문자 확장자로 변경하세요:
mv skill.ZIP skill.zip
mv skill.ZiP skill.zipapplication/octet-stream으로 제공되는 다운로드 파일의 경우, URL 또는 저장된 파일 이름이 소문자 .zip으로 끝나는지 확인하세요. 소스 수준의 해결 방법은 세 메서드 모두에서 해당 검사를 filename.lower().endswith(".zip")으로 변경하는 것입니다.