SkillSpector Main Features: AI-Agent Security Scanner by NVIDIA

SkillSpector is a security scanner for AI-agent skills that combines fast static analysis with optional LLM-based semantic evaluation to detect 68 vulnerability patterns across 17 categories before installation.

NVIDIA/SkillSpector is an open-source security tool designed to answer "Is this skill safe to install?" by analyzing code, metadata, and dependencies prior to execution. It provides machine-readable output suitable for CI pipelines, MCP servers, and developer tools through a combination of regex-based detection, AST analysis, YARA signatures, and configurable LLM providers.

Core SkillSpector Features

Multi-Format Input Support

SkillSpector accepts diverse input sources including Git repositories, URLs, zip files, local directories, or single SKILL.md files. This flexibility allows security teams to scan skills regardless of how they are distributed or stored.

Two-Stage Security Analysis

The tool implements a two-stage analysis pipeline as defined in src/skillspector/graph.py. First, static analysis runs regex patterns, AST traversal, YARA signatures, and live OSV lookups. Second, an optional LLM analysis performs semantic evaluation to reduce false positives and catch complex logic bugs. Set use_llm: False or pass --no-llm for environments without API keys.

Comprehensive Vulnerability Detection

SkillSpector detects 68 vulnerability patterns across 17 categories including prompt injection, data exfiltration, privilege escalation, supply-chain attacks, AST-based execution, and MCP-specific checks. These patterns are implemented in the static analysis layer with severity mappings defined in src/skillspector/constants.py.

Live Dependency Scanning (SC4)

The scanner queries OSV.dev for known CVEs in dependencies, falling back to an offline vulnerability list when operating without network connectivity. This ensures dependency security checks function in air-gapped environments.

Risk Scoring and Recommendations

Each scan generates a 0-100 risk score mapped to severity bands: LOW, MEDIUM, HIGH, and CRITICAL. The tool provides actionable recommendations of SAFE, CAUTION, or DO_NOT_INSTALL based on findings. Risk assessment logic is centralized in src/skillspector/models.py with scoring calculations in the graph workflow.

Flexible Output Formats

SkillSpector supports four output formats: Terminal (human-readable), JSON (machine-readable), Markdown, and SARIF (for IDE integration). Control the format using --format json or the output_format parameter in the Python API.

Baseline and False-Positive Suppression

The src/skillspector/suppression.py module implements baseline handling and fingerprinting to suppress known findings. Provide a baseline file via --baseline .skillspector-baseline.yaml to hide previously accepted risks, ensuring only new issues affect the risk score.

MCP Server Integration

SkillSpector exposes a Model-Context-Protocol server via src/skillspector/mcp_server.py, implementing the scan_skill endpoint. Agents can call this at runtime to gate skill installations, supporting both HTTP and STDIO transports:

skillspector mcp --transport http --host 127.0.0.1 --port 8000

Configurable LLM Providers

The src/skillspector/llm_utils.py and src/skillspector/providers/registry.py modules support multiple providers including OpenAI, Anthropic, Bedrock, NVIDIA Build, Claude CLI, and Codex CLI. The registry auto-discovers available models and handles provider-specific request formatting.

Architecture and Implementation

SkillSpector's extensible architecture centers on src/skillspector/graph.py, which orchestrates the LangGraph workflow coordinating static analyzers, LLM evaluation, scoring, and output formatting. Key implementation files include:

• src/skillspector/cli.py: Command-line interface with argument parsing and pipeline dispatch
• src/skillspector/models.py: Data models for findings, risk assessment, and report serialization
• src/skillspector/suppression.py: Baseline handling and false-positive suppression logic
• src/skillspector/constants.py: Centralized configuration for pattern IDs, severity mappings, and default scores

Command-Line and API Usage

Scan a local skill directory with full analysis:

skillspector scan ./my-skill/

Fast static-only scan for CI environments:

skillspector scan ./my-skill/ --no-llm

Generate JSON reports for automation:

skillspector scan ./my-skill/ --format json --output report.json

Create and use baselines:

skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

Exit-code contract for CI gating: 0 (safe/caution), 1 (risky), 2 (errors).

Python API via src/skillspector/graph.py:

from skillspector import graph

result = graph.invoke({
    "input_path": "/path/to/skill",
    "output_format": "json",
    "use_llm": True,
})

print(f"Score: {result['risk_score']}/100")
print(f"Recommendation: {result['risk_recommendation']}")
for f in result["filtered_findings"]:
    print(f"[{f['severity']}] {f['rule_id']}: {f['message']}")

Summary

• SkillSpector analyzes AI-agent skills through 68 vulnerability patterns across 17 security categories before execution
• Two-stage analysis combines static scanning (regex, AST, YARA, OSV) with optional LLM semantic evaluation
• Supports multiple input formats (Git, URLs, zip, directories) and output formats (Terminal, JSON, Markdown, SARIF)
• Provides 0-100 risk scoring with SAFE/CAUTION/DO_NOT_INSTALL recommendations and baseline suppression for false-positive management
• Offers MCP server mode for runtime agent integration and configurable LLM providers (OpenAI, Anthropic, NVIDIA Build, etc.)
• Returns semantic exit codes (0, 1, 2) ideal for CI/CD pipeline gating

Frequently Asked Questions

What is SkillSpector used for?

SkillSpector is a security scanner that evaluates AI-agent skills before installation to determine if they contain malicious code, vulnerable dependencies, or risky behaviors. It answers "Is this skill safe to install?" through automated static and semantic analysis.

How does SkillSpector detect vulnerabilities?

SkillSpector employs 68 detection patterns across categories like prompt injection, data exfiltration, and privilege escalation using regex matching, AST traversal, YARA signatures, and live OSV.dev lookups. An optional LLM layer in src/skillspector/graph.py reduces false positives by evaluating code context.

Can SkillSpector run without an LLM?

Yes. Pass --no-llm to the CLI or set use_llm: False in the Python API to run static-only analysis. This mode is ideal for CI environments or air-gapped networks where LLM API keys are unavailable, though it may have higher false-positive rates.

What is the MCP server mode in SkillSpector?

The MCP (Model-Context-Protocol) server mode exposes a scan_skill endpoint that AI agents can call via HTTP or STDIO to gate skill installations at runtime. Implemented in src/skillspector/mcp_server.py, it allows agents to query SkillSpector before executing third-party skills.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}