NVIDIA/SkillSpector

NVIDIA/SkillSpector

Description: Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks.

Language: Python

License: Apache-2.0

Stars: 2164

Forks: 187

Open issues: 18

Created: 2026-03-21T00:28:43Z

Pushed: 2026-06-10T19:18:13Z

Default branch: main

Fork: no

Archived: no

README:

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. Research shows that 26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent.

SkillSpector helps you answer: "Is this skill safe to install?"

Documentation

• [Development guide](docs/DEVELOPMENT.md) — Architecture, package layout, and how to extend the analyzer pipeline.

Features

• Multi-format input: Scan Git repos, URLs, zip files, directories, or single files
• 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
• 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

Quick Start

Installation

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.

# 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

Basic Usage

# 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

Output Formats

# 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

LLM Analysis

For the best results, configure an OpenAI-compatible LLM endpoint for semantic analysis. Pick a provider with SKILLSPECTOR_PROVIDER; each ships its own bundled default model. SkillSpector also works against local OpenAI-compatible servers (Ollama, vLLM, llama.cpp) and managed inference gateways.

| Provider (SKILLSPECTOR_PROVIDER) | Credential env var | Endpoint | Default model | |----------|----|----|----| | openai | OPENAI_API_KEY (+ optional OPENAI_BASE_URL) | api.openai.com (or any OpenAI-compatible URL) | gpt-5.4 | | anthropic | ANTHROPIC_API_KEY | api.anthropic.com | claude-opus-4-6 | | nv_build | NVIDIA_INFERENCE_KEY | build.nvidia.com | deepseek-ai/deepseek-v4-flash |

# Stock OpenAI
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=sk-...
skillspector scan ./my-skill/

# Anthropic
export SKILLSPECTOR_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
skillspector scan ./my-skill/

# NVIDIA build.nvidia.com
export SKILLSPECTOR_PROVIDER=nv_build
export NVIDIA_INFERENCE_KEY=nvapi-...
skillspector scan ./my-skill/

# Local Ollama or any OpenAI-compatible endpoint
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export SKILLSPECTOR_MODEL=llama3.1:8b
skillspector scan ./my-skill/

# Override the provider's default model
export SKILLSPECTOR_MODEL=gpt-5.2
skillspector scan ./my-skill/

# Skip LLM analysis (faster, static analysis only)
skillspector scan ./my-skill/ --no-llm

Vulnerability Patterns

SkillSpector detects 64 vulnerability patterns across 16 categories:

Prompt Injection (5 patterns)

| ID | Pattern | Severity | Description | |----|---------|----------|-------------| | P1 | Instruction Override | HIGH | Commands to ignore safety constraints | | P2 | Hidden Instructions | HIGH | Malicious directives in comments/invisible text | | P3 | Exfiltration Commands | HIGH | Instructions to transmit context externally | | P4 | Behavior Manipulation | MEDIUM | Subtle instructions altering agent decisions | | P5 | Harmful Content | CRITICAL | Instructions that could cause physical harm |

Data Exfiltration (4 patterns)

| ID | Pattern | Severity | Description | |----|---------|----------|-------------| | E1 | External Transmission | MEDIUM | Sending data to external URLs | | E2 | Env Variable Harvesting | HIGH | Collecting API keys and secrets | | E3 | File System Enumeration | MEDIUM | Scanning directories for sensitive files | | E4 | Context Leakage | HIGH | Transmitting conversation context externally |

Privilege Escalation (3 patterns)

| ID | Pattern | Severity | Description | |----|---------|----------|-------------| | PE1 | Excessive Permissions | LOW | Requesting access beyond stated functionality | | PE2 | Sudo/Root Execution | MEDIUM | Invoking elevated system privileges | | PE3 | Credential Access | HIGH | Reading SSH keys, tokens, passwords |

Supply Chain (6 patterns)

| ID | Pattern | Severity | Description | |----|---------|----------|-------------| | SC1 | Unpinned Dependencies | LOW | No version constraints on packages | | SC2 | External Script Fetching | HIGH | curl \| bash and remote code execution | | SC3 | Obfuscated Code | HIGH | Base64/hex encoded execution | | SC4 | Known Vulnerable Dependencies | HIGH | Dependencies with known CVEs (live OSV.dev lookup) | | SC5 | Abandoned Dependencies | MEDIUM | Unmaintained packages without security…