
SkillSpector v2.5.3
Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.
SkillSpector
Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.
Overview
AI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal vetting. In the 31,132-skill analyzed subset of the research dataset, 26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent.
SkillSpector helps you answer: "Is this skill safe to install?"
SkillSpector is part of the NVIDIA Verified Skills pipeline, which scans, evaluates, and signs agent skills before publication. Skills that pass are published to the NVIDIA skills catalog.
Documentation
- Scan agent skills before installation — Hosted guide: when to scan, how to read a report, and how to gate installs.
- Development guide — Architecture, package layout, and how to extend the analyzer pipeline.
- Security policy — Report suspected vulnerabilities privately to NVIDIA PSIRT.
- Analysis resource bounds — Fail-closed bundle, parser, nested-artifact, ledger, and finding ceilings.
- Pi extension — Install SkillSpector as a Pi tool for scanning skills from inside agent sessions.
- OpenCode extension — Install SkillSpector as an OpenCode tool and
/skillspectorcommand for scanning skills from inside agent sessions. - LLM analyzer base guide — How to build LLM-powered analyzer nodes on top of
LLMAnalyzerBase. - Dependency source redirection — How SC10 findings flag a skill that changes where its packages are fetched from.
- Live vulnerability lookups (SC4) — How SC4 checks dependencies against OSV.dev.
- Eval dataset scanning — Which eval dataset files the static pattern analyzers skip.
- MCP least-privilege analysis (LP1–LP4) and MCP tool-poisoning detection (TP1–TP4) — Design notes for the MCP analyzers.
Features
- Multi-format input: Scan Git repos, URLs, zip files, directories, or single files
- 71 vulnerability patterns across 17 categories: prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, anti-refusal, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning
- Two-stage analysis: Fast static analysis + optional LLM semantic evaluation
- Live vulnerability lookups: SC4 queries OSV.dev for real-time CVE data with automatic offline fallback
- Multiple output formats: Terminal, JSON, Markdown, and SARIF reports
- Risk scoring: 0-100 score with severity labels and clear recommendations
- Baseline / false-positive suppression: Accept known findings via a glob-rule or fingerprint baseline so re-scans surface only new issues (docs)
Quick Start
Installation
Open-source software notice: This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.
Use Python 3.12 or 3.13 for installation with prebuilt YARA wheels on supported
platforms. The examples below select 3.13 explicitly; see the
Python installation notes for newer interpreters.
For source installs, create 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.
Quick install with uv (CLI-only):
uv tool install --python 3.13 git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector
If you plan to run skillspector mcp, install the MCP extra at install time:
uv tool install --python 3.13 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
From source:
# 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
To contribute, follow the Development setup for a supported Python interpreter and development dependencies.
Python installation notes
The package declares Python >=3.12,<3.16 in pyproject.toml.
That range does not guarantee prebuilt wheels for every dependency and platform.
yara-python 4.5.4 on PyPI
provides CPython 3.12/3.13 wheels, but no CPython 3.14/3.15 wheels. Installing it
on those newer interpreters requires a native source build with a C toolchain
and Python development headers. Such builds can fail with OpenSSL 4 headers;
issue #1008 tracks that
installation problem and upstream wheel availability.
If installation fails while compiling YARA, select Python 3.12 or 3.13 explicitly
using the commands above. For a new CLI-only installation with pipx, first
install Python 3.13 and make python3.13 available on PATH, then run:
pipx install --python python3.13 git+https://github.com/NVIDIA/skillspector.git
The upstream wheel-build update is separate from publishing a new release to PyPI. Check the published files before choosing a newer interpreter; a source build may still be required.
Docker (no Python required)
Run SkillSpector without installing Python by building it locally from the included Dockerfile. The image is based on the Docker Official Python 3.12-slim-bookworm image.
Build the image:
make docker-build
# or: docker build -t skillspector .
Scan a local directory by mounting your current directory into /scan, the container's working directory:
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm
Scan with LLM analysis by passing credentials with a local .env file:
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/
Or pass credentials directly from your shell environment:
docker run --rm \
-v "$PWD:/scan" \
-e SKILLSPECTOR_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
skillspector scan ./my-skill/