GitHub - NVIDIA/SkillSpector: Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks.

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 — 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 updates

SC6 Typosquatting HIGH Package names similar to popular packages

Excessive Agency (4 patterns)

ID Pattern Severity Description

EA1 Unrestricted Tool Access HIGH Unfettered tool access without constraints

EA2 Autonomous Decision Making HIGH High-impact decisions without human-in-the-loop

EA3 Scope Creep MEDIUM Capabilities extending beyond stated purpose

EA4 Unbounded Resource Access MEDIUM No rate limits or quotas on resource consumption

Output Handling (3 patterns)

ID Pattern Severity Description

OH1 Unvalidated Output Injection HIGH Model output used without sanitization

OH2 Cross-Context Output MEDIUM Output flows across trust boundaries without validation

OH3 Unbounded Output MEDIUM No limits on output size or generation rate

System Prompt Leakage (3 patterns)

ID Pattern Severity Description

P6 Direct Leakage HIGH Instructions that expose system prompts or internal rules

P7 Indirect Extraction MEDIUM Extraction via rephrasing, translation, or side-channels

P8 Tool-Based Exfiltration HIGH System prompts exfiltrated via file writes or network requests

Memory Poisoning (3 patterns)

ID Pattern Severity Description

MP1 Persistent Context Injection HIGH Content designed to persist across interactions

MP2 Context Window Stuffing MEDIUM Filler content displacing safety constraints

MP3 Memory Manipulation HIGH Tampering with agent memory or stored state

Tool Misuse (3 patterns)

ID Pattern Severity Description

TM1 Tool Parameter Abuse HIGH Crafted parameters for unintended behavior (shell=True, --force)

TM2 Chaining Abuse HIGH Tool chains that bypass individual safety checks

TM3 Unsafe Defaults MEDIUM Overly permissive defaults (disabled TLS, no auth)

Rogue Agent (2 patterns)

ID Pattern Severity Description

RA1 Self-Modification CRITICAL Modifying own code or configuration at runtime

RA2 Session Persistence HIGH Unauthorized persistence via cron jobs or startup scripts

Trigger Abuse (3 patterns)

ID Pattern Severity Description

TR1 Overly Broad Trigger MEDIUM Trigger patterns matching common words

TR2 Shadow Command Trigger HIGH Triggers that shadow built-in commands or other skills

TR3 Keyword Baiting Trigger MEDIUM Generic triggers designed to maximize activation

Behavioral AST (8 patterns)

ID Pattern Severity Description

AST1 exec() Call CRITICAL Direct exec() enabling arbitrary code execution

AST2 eval() Call HIGH Direct eval() evaluating arbitrary expressions

AST3 Dynamic Import HIGH __import__() loading arbitrary modules at runtime

AST4 subprocess Call HIGH External command execution via subprocess

AST5 os.system / exec-family HIGH Shell commands via os module

AST6 compile() Call MEDIUM Code object creation from strings

AST7 Dynamic getattr() MEDIUM Arbitrary attribute access with non-literal names

AST8 Dangerous Execution Chain CRITICAL exec/eval combined with dynamic source (network, encoded data)

Taint Tracking (5 patterns)

ID Pattern Severity Description

TT1 Direct Taint Flow HIGH Data flows directly from a source to a sink without sanitization

TT2 Variable-Mediated Taint Flow MEDIUM Data flows from source to sink through intermediate variables

TT3 Credential Exfiltration Chain CRITICAL Credentials (env vars, secrets) flow to network output sinks

TT4 File Read to Network Exfiltration HIGH File contents flow to network output sinks

TT5 External Input to Code Execution CRITICAL Network or user input flows to

exec/eval/subprocess sinks

YARA Signatures (4 patterns)

ID Pattern Severity Description

YR1 Malware Match CRITICAL YARA rule match for known malware signatures

YR2 Webshell Match CRITICAL YARA rule match for webshell patterns

YR3 Cryptominer Match HIGH YARA rule match for crypto mining indicators

YR4 Hack Tool / Exploit Match HIGH YARA rule match for hack tools or exploit code

MCP Least Privilege (4 patterns)

ID Pattern Severity Description

LP1 Underdeclared Capability HIGH Code uses capabilities not listed in declared permissions

LP2 Wildcard Permission MEDIUM Permission list contains wildcards (*, all, full, any)

LP3 Missing Permission Declaration MEDIUM No permissions field but code has detectable capabilities

LP4 Overdeclared Permission LOW Permission declared but no corresponding code capability found

MCP Tool Poisoning (4 patterns)

ID Pattern Severity Description

TP1 Hidden Instructions HIGH Hidden directives in metadata (HTML comments, zero-width chars, base64, data URIs)

TP2 Unicode Deception HIGH Homoglyphs, RTL overrides, mixed-script identifiers in tool metadata

TP3 Parameter Description Injection MEDIUM Injection patterns in parameter definitions (overrides, system tokens, malicious defaults)

TP4 Description-Behavior Mismatch MEDIUM Declared tool description does not match actual code behavior (LLM-powered)

All detected patterns are listed in the tables above. Risk Scoring Score Calculation

CRITICAL issues: +50 points HIGH issues: +25 points MEDIUM issues: +10 points LOW issues: +5 points Executable scripts: 1.3x multiplier

Severity Levels

Score Severity Recommendation

0-20 LOW SAFE

21-50 MEDIUM CAUTION

51-80