SkillSpector - Security scanner for AI agent skills. Detect vulne

项目说明

SkillSpector

Security scanner for AI agent skills. Detect , malicious patterns, and security risks before installing agent skills.

![Python 3.12+]()
![License: Apache 2.0]()

O

AI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal . In the 31,132-skill analyzed subset of the research dataset, 26.1% of skills contain and 5.2% show likely malicious intent.

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

SkillSpector is part of the NVIDIA Skills pipeline, which scans, e, 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.

De guide — Architecture, package layout, and how to extend the analyzer pipeline.

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 /skillspector command for scanning skills from inside agent sessions.

Features

Multi-format input: Scan Git repos, URLs, zip files, directories, or single files

71 patterns across 17 categories: prompt injection, data exfiltration, pri escalation, supply chain, excessi, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, anti-refusal, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least pri, and MCP tool poisoning

Two-stage analysis: Fast static analysis + optional LLM semantic e

Li 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 se labels and clear recommendations

Baseline / false-positi: 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.

Create and activate a en first (all make targets assume the venv is active). Use uv or pip; the Makefile uses uv if a, otherwise pip.

Quick install with u):

If you plan to run skillspector mcp, install the MCP extra at install time:

From source:

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:

Scan a local directory by mounting your current directory into /scan, the container's working directory:

Scan with LLM analysis by passing credentials with a local .env file:

Or pass credentials directly from your shell en:

Write a report to the host filesystem by writing to the mounted directory:

Optional alias for repeated static scans:

Basic Usage

#### Size limits

SkillSpector enforces two independent caps on remote and archi to bound the impact of o downloads and zip bombs:

Per-ingest cap: INGEST_MAX_BYTES (100 MiB) — applied to streamed URL downloads, total uncompressed size of zip archives, and post-clone disk usage of Git repos.

Zip member cap: INGEST_MAX_ZIP_MEMBERS (10,000) — caps the number of entries in a single zip.

Note that the per-file 1 MB analysis cap (MAX_FILE_BYTES) is a separate, downstream limit: it bounds what indi analyzers will read out of an already-ingested directory. The ingest caps abo how much content can land on disk in the first place. A breach of either ingest cap fails closed with an IngestLimitExceededError.

Output Formats

Batch Scanning

Scan entire directories of skills in parallel from contrib/batch_scan/:

Supports multilingual detection (zh/ja/ko) and terminal/JSON/Markdown output.

For LLM scans with higher concurrency, configure multiple API keys following
.en — the pool impro
and resilience, provided the keys don't share an account-level rate limit.

See the contrib guide for details.

> Note on LLM support: The default configuration targets DeepSeek as the
> cheapest public option. DeepSeek-Chat is
> expected to sunset, and the contributor
> does not ha to test against local models. The batch scanner was
> originally tested with OpenAI-compatible endpoints — DeepSeek's lack of
> structured-output support required manual JSON-parsing patches. If you can
> contribute a more uni backend (Ollama, vLLM, or a different provider),
> PRs are very welcome.

Comparing MCP Registry snapshots

Start with raw registry payload captures (registry-before.json and
registry-after.json). Save a scan report as previous.json, then compare a
later scan against that generated local report:

The optional comparison object lists added and remo identities,
changed normalized fields with their previous and current , and an
unchanged_count. Identity is the server name and , so a new
appears as an addition and the old as a removal if it is absent from the
new scan. Acquisition source and scan timestamp are excluded from comparison.
unmodeled_changes lists same-identity records whose raw-record hash changed
while normalized fields match; these are not counted as unchanged. This can
indicate a change to fields outside the snapshot model, or array reordering in
the raw record. Package and remote ordering alone is not a normalized field change.
Entries in changed may also contain changes outside the snapshot model; inspect
the raw record to see those changes.
Compare reports with the same selection scope: a ser from the current
input is reported as removed, which does not prove it was removed from a registry.

The comparison file must be a local report produced by this registry mode with
valid normalized snapshots. Malformed, o or duplicate ser
are rejected. This option requires --mcp-registry and is separate from the
finding-suppression --baseline: it ne findings or changes risk
scores, and it does not fetch or execute listed ser.

Suppressing False Positives (baseline)

Suppress known/accepted findings so the risk score reflects only un-triaged
issues and re-scans surface only *new* findings. See the
suppression guide for the full reference.

A baseline can also use drift-tolerant glob rules (by rule id, file path, or
message) — see .skillspector-baseline.example.yaml.
Exact fingerprint baselines are e: changing the scanned source or
SkillSpector keeps the finding acti it is re again.
When a selected baseline or baseline output is stored inside the skill
directory, SkillSpector excludes that exact file from content analysis so its
suppression text cannot create findings or enter regenerated fingerprints;
sibling files remain in normal scan scope.

Explicit scan scope

For a local directory containing one SKILL.md or skill.md, repeat --exclude to omit
selected files before content analysis:

Patterns are case-sensiti matched against the entire relati path;
* also matches /. Quote patterns so your shell does not expand them. This is
an explicit caller option, not an author-controlled ignore file. Patterns matching
either manifest name (SKILL.md or skill.md) are rejected, as are recursi, transiti, and
non-directory inputs. No-match patterns are still recorded in the report.

Files already outside the scan in, such as policy-excluded dependencies,
retain their existing policy handling and are not counted as caller exclusions.
Explicitly excluded in files remain in the co denominator as entirely uninspected. The
report lists the applied patterns, excluded count and indi skipped paths;
any matched exclusion makes co partial and prevents a SAFE recommendation.
Use --fail-on-incomplete when partial scope should fail CI. These exclusions do
not suppress findings in included files or o existing safety limits.

LLM Analysis

For the best results, configure an OpenAI-compatible LLM endpoint for
semantic analysis. Pick a provider with SKILLSPECTOR_PROVIDER; hosted pro ship bundled default models, while CLI pro fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. 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 |
| anthropic_proxy | ANTHROPIC_PROXY_API_KEY + ANTHROPIC_PROXY_ENDPOINT_URL | Any raw-predict proxy | claude-sonnet-4-6 |
| bedrock | AWS_PROFILE (optional) + AWS_REGION — SigV4 | AWS Bedrock Runtime | us.anthropic.claude-sonnet-4-6-20250915-v1:0 |
| n | N | build.nvidia.com | z-ai/glm-5.2 |
| ollama | _(none)_ | OLLAMA_BASE_URL (default ) | llama3.1:8b |
| azure_openai | AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT | Azure OpenAI Service | gpt-4o (deployment defaults to the model label) |
| openai_compatible | SKILLSPECTOR_COMPAT_API_KEY + SKILLSPECTOR_COMPAT_BASE_URL | Any OpenAI-compatible endpoint | llama-3.1-70b- |
| claude_cli | _(none — uses local CLI auth)_ | local claude binary | local Claude runtime fallback, or SKILLSPECTOR_MODEL |
| codex_cli | _(none — uses local CLI auth)_ | local codex binary | local Codex runtime fallback, or SKILLSPECTOR_MODEL |
| gemini_cli | _(none — uses local CLI auth)_ | local gemini binary | local Gemini runtime fallback, or SKILLSPECTOR_MODEL |
| opencode_cli | _(none — uses local CLI auth)_ | local opencode 1.18.33 binary | local OpenCode runtime fallback, or SKILLSPECTOR_MODEL |

Structured output is requested through LangChain's with_structured_output,
whose default forces a tool call. Some models reject a forced tool call with
HTTP 400 (tool_choice: type "tool" and "any" are not supported for this
model). The anthropic and anthropic_proxy pro route those models
(claude-fable-5-1, claude-mythos-5-1, or any registry entry with
structured_output: json_schema) to the nati response format.
Bedrock has no JSON-schema output for them, so the bedrock provider leaves
toolChoice at auto, asks for the tool call in the prompt, and retries a
prose answer; it recognises the model from the model ID, a geo/global
inference-profile ID, or a foundation-model / inference-profile ARN. An
application-inference-profile ARN hides the model, so add that ARN to the
registry (SKILLSPECTOR_MODEL_REGISTRY) with tool_choice: auto.
The openai_compatible provider honours the same tool_choice: auto entry
for endpoints that ignore both response_format and a forced tool_choice
and answer in prose (for example iFlytek's spark-x2.5, which is bundled).
SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD=json_schema|function_calling
o the method for any provider.

MCP Server

Run SkillSpector as a Model Context Protocol
server so any MCP-capable agent (Claude Code, Codex CLI, Gemini CLI) or remote
runtime can call scanning as a tool and **gate skill/MCP installs on the
result** — turning SkillSpector into a runtime guardrail instead of an
out-of-band audit step.

skillspector mcp requires skillspector[mcp].

The stdio transport is the current FastMCP path for local CLI agents, and the
initialize hang reported in issue #199 still applies there.

The ser a single tool:

scan_skill(target, use_llm=true, output_format="json") — scans a Git

URL, file URL, .zip, .md file, or directory and returns a structured
: risk_score (0-100), se, recommendation,
safe_to_install, and findings. It also reports llm_used / scan_mode
so a low score from a static-only scan is ne for a clean full
scan.

Register it with Claude Code via:

> Security — HTTP transport trust model
>
> The HTTP transport ships without authentication. Any caller that can
> reach the port can invoke scan_skill. O or 127.0.0.1 this is
> the same trust boundary as the CLI. If you bind to a routable interface:
>
> - Sit the ser an authenticating reverse proxy (e.g. nginx + mTLS)
> before exposing it externally.
> - Local paths and file:// URLs are automatically rejected over HTTP to
> prevent unauthenticated callers from reading arbitrary host files. Only
> remote Git and .zip URLs are accepted.

Patterns

SkillSpector detects 71 patterns across 17 categories:

Prompt Injection (6 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| P1 | Instruction O | HIGH | Commands to ignore safety constraints |
| P2 | Hidden Instructions | HIGH | Malicious directives in comments/in 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 |
| P9 | Whitespace Padding | MEDIUM | Large whitespace padding hiding instructions below/beside the area |

Anti-Refusal (3 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| AR1 | Refusal Suppression | HIGH | Instructions to ne or always comply (e.g. "ne", "always comply") |
| AR2 | Disclaimer Suppression | HIGH | Instructions to omit warnings, disclaimers, or ethical commentary (e.g. "no disclaimers", "do not moralize") |
| AR3 | Safety Policy Nullification | HIGH | Jailbreak framing that nullifies guardrails (e.g. "you have no restrictions", "ignore your guidelines", "do anything now") |

Data Exfiltration (4 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| E1 | External Transmission | MEDIUM | Sending data to external URLs |
| E2 | En Har | HIGH | Enumerating, copying, or searching en data to collect secrets |
| E3 | File System Enumeration | MEDIUM | Scanning directories for sensiti |
| E4 | Context Leakage | HIGH | Transmitting con context externally |

Pri Escalation (3 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| PE1 | Excessi | LOW | Requesting access beyond stated functionality |
| PE2 | Sudo/Root Execution | MEDIUM | In elevated system pri |
| PE3 | Credential Access | HIGH | Reading SSH keys, tokens, passwords |

Supply Chain (10+ patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| SC1 | Unpinned Dependencies | LOW | No constraints on packages |
| SC2 | External Script Fetching | HIGH | curl \| bash and remote code execution |
| SC3 | Obfuscated Code | HIGH | Base64/hex encoded execution |
| SC4 | Known Dependencies | HIGH | Dependencies with known CVEs (live OSV.de) |
| SC5 | Abandoned Dependencies | MEDIUM | Unmaintained packages without security updates |
| SC6 | Typosquatting | HIGH | Package names similar to popular packages |
| SC8 | Shipped Python Bytecode | HIGH | __pycache__ / .pyc present (discovery skips; malicious bytecode bypass) |
| SC9 | Concealed Executable Artifact | HIGH | Executable nested in a document container or hidden/disguised artifact |
| SC10 | Dependency Source Redirection | HIGH | Package-manager source added, replaced, or unresolved |

Excessi (5 patterns)

| ID | Pattern | Se | 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 |
| EA5 | External Model or Provider Selection | MEDIUM/HIGH | Model/provider pins or coding-CLI shell-outs that can switch billing accounts |

Output Handling (3 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| OH1 | Un Output Injection | HIGH | Model output used without sanitization |
| OH2 | Cross-Context Output | MEDIUM | Output flows across trust boundaries without |
| OH3 | Unbounded Output | MEDIUM | No limits on output size or generation rate |

System Prompt Leakage (3 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| P6 | Direct Leakage | HIGH | Instructions that expose system prompts or internal rules |
| P7 | Indirect Extraction | MEDIUM | Extraction , translation, or side-channels |
| P8 | Tool-Based Exfiltration | HIGH | System prompts exfiltrated via file writes or network requests |

Memory Poisoning (3 patterns)

| ID | Pattern | Se | 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 | Se | Description |
|----|---------|----------|-------------|
| TM1 | Tool Parameter Abuse | HIGH | Crafted parameters for unintended behavior (shell=True, --force) |
| TM2 | Chaining Abuse | HIGH | Tool chains that bypass indi safety checks |
| TM3 | Unsafe Defaults | MEDIUM | Overly permissi (disabled TLS, no auth) |

Rogue Agent (2 patterns)

| ID | Pattern | Se | 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 | Se | 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 acti |

Beha AST (9 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| AST1 | exec() Call | CRITICAL | Direct exec() enabling arbitrary code execution |
| AST2 | eval() Call | HIGH | Direct eval() e arbitrary expressions |
| AST3 | Dynamic Import | HIGH | \_\_import\_\_() loading arbitrary modules at runtime |
| AST4 | subprocess Call | HIGH | External command execution |
| 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/e with dynamic source (network, encoded data) |
| AST9 | Reflecti() Sink | HIGH | Reflective exec via getattr(os,'system') / getattr(builtins,'exec') that evades AST1/AST5 |

Taint Tracking (5 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| TT1 | Direct Taint Flow | HIGH | Data flows directly from a source to a sink without sanitization |
| TT2 | Taint Flow | MEDIUM | Data flows from source to sink through intermediate |
| 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/e sinks |

YARA Signatures (4 patterns)

| ID | Pattern | Se | 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 Pri (4 patterns)

| ID | Pattern | Se | 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 | O Permission | LOW | Permission declared but no corresponding code capability found |

MCP Tool Poisoning (4 patterns)

| ID | Pattern | Se | Description |
|----|---------|----------|-------------|
| TP1 | Hidden Instructions | HIGH | Hidden directives in metadata (HTML comments, zero-width chars, base64, data URIs) |
| TP2 | Unicode Deception | HIGH | Homoglyphs, RTL o, mixed-script identifiers in tool metadata |
| TP3 | Parameter Description Injection | MEDIUM | Injection patterns in parameter definitions (o, 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

Se Levels

| Score | Se | Recommendation |
|-------|----------|----------------|
| 0-20 | LOW | SAFE |
| 21-50 | MEDIUM | CAUTION |
| 51-80 | HIGH | DO NOT INSTALL |
| 81-100 | CRITICAL | DO NOT INSTALL |

Example Output

Terminal Output

Configuration

En

| | Description | Required |
|----------|-------------|----------|
| SKILLSPECTOR_PROVIDER | Active LLM provider: openai, anthropic, anthropic_proxy, bedrock, n, ollama, azure_openai, openai_compatible, claude_cli, codex_cli, gemini_cli, or opencode_cli. Hosted pro use bundled model_registry.yaml defaults; CLI pro fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. Defaults to n. | Optional |
| N | Credential for the n provider (build.nvidia.com). | Required for LLM analysis when SKILLSPECTOR_PROVIDER=n |
| OPENAI_API_KEY | Credential for the OpenAI provider (SKILLSPECTOR_PROVIDER=openai). Also serves as the tier-2 fallback in the credential waterfall when the acti returns no credentials. | Required for LLM analysis when SKILLSPECTOR_PROVIDER=openai |
| OPENAI_BASE_URL | O the OpenAI endpoint (e.g. point at Ollama). | Optional |
| SKILLSPECTOR_REASONING_EFFORT | Optional pro and model-dependent reasoning-effort setting. Non-empty are trimmed and passed through unchanged; unset or blank preser behavior. | Optional |
| SKILLSPECTOR_OUTPUT_LANGUAGE | Short, single-line language label (letters, numbers, spaces, _, or -; maximum 64 characters) for human-readable LLM finding text such as messages, explanations, and remediation. Rule IDs, se , paths, code, and other machine-readable remain unchanged. Unset, blank, or invalid preserve the default output language. | Optional |
| SKILLSPECTOR_TEMPERATURE | Optional sampling temperature from 0 to 1 for hosted pro. Unset or blank preserves the provider default. Lower can reduce run-to-run but do not guarantee identical output. | Optional |
| SKILLSPECTOR_SEED | Optional integer sampling seed for OpenAI-compatible and Azure OpenAI pro. Other hosted pro and CLI pro do not receive it. Provider support remains model-dependent. | Optional |
| SKILLSPECTOR_COMPACT_PROMPTS | Opt-in compact line numbering in LLM prompts: numbered lines render as L1:, L2: instead of zero-padded L01:, L02:. Accepted truthy are 1, true, and yes (case-insensiti whitespace is trimmed). Unset or any other value keeps the default zero-padded format. | Optional |
| ANTHROPIC_API_KEY | Credential for the Anthropic provider (SKILLSPECTOR_PROVIDER=anthropic). | Required for LLM analysis when SKILLSPECTOR_PROVIDER=anthropic |
| ANTHROPIC_BASE_URL | O the nati endpoint (default: ). | Optional |
| ANTHROPIC_AUTH_SCHEME | Set to bearer to send ANTHROPIC_API_KEY as Authorization: Bearer instead of x-api-key, for gateways exposing the Messages API. | Optional |
| ANTHROPIC_PROXY_ENDPOINT_URL | Full endpoint URL for the Anthropic proxy provider ( raw-predict). | Required when SKILLSPECTOR_PROVIDER=anthropic_proxy |
| ANTHROPIC_PROXY_API_KEY | Bearer token for the Anthropic proxy provider. | Required when SKILLSPECTOR_PROVIDER=anthropic_proxy |
| ANTHROPIC_PROXY_API_ | anthropic_ value sent in the request body (default: ). | Optional |
| AWS_PROFILE | Named AWS profile for the Bedrock provider — authenticates through boto3. When unset, the standard boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves. | Optional (used when SKILLSPECTOR_PROVIDER=bedrock) |
| AWS_REGION | AWS region for the Bedrock Runtime endpoint. Defaults to us-west-2. | Optional (used when SKILLSPECTOR_PROVIDER=bedrock) |
| OLLAMA_BASE_URL | Ollama OpenAI-compatible endpoint. Defaults to . | Optional (used when SKILLSPECTOR_PROVIDER=ollama) |
| AZURE_OPENAI_API_KEY | API key for the Azure OpenAI provider. | Required when SKILLSPECTOR_PROVIDER=azure_openai |
| AZURE_OPENAI_ENDPOINT | Azure resource endpoint for the Azure OpenAI provider. | Required when SKILLSPECTOR_PROVIDER=azure_openai |
| AZURE_OPENAI_DEPLOYMENT | Azure deployment name. Defaults to the selected model label. | Optional |
| AZURE_OPENAI_API_ | Azure OpenAI API . Defaults to 2024-06-01. | Optional |
| SKILLSPECTOR_COMPAT_API_KEY | API key for a generic OpenAI-compatible provider. | Required when SKILLSPECTOR_PROVIDER=openai_compatible |
| SKILLSPECTOR_COMPAT_BASE_URL | Base URL for a generic OpenAI-compatible provider. | Required when SKILLSPECTOR_PROVIDER=openai_compatible |
| SKILLSPECTOR_MODEL | O the acti model. For hosted pro, this replaces the bundled default from the LLM Analysis table. For CLI pro, this is forwarded as --model instead of using the local runtime fallback. | Optional |
| SKILLSPECTOR_MODEL_REGISTRY | O the bundled per-provider YAML registry (src/skillspector/pro/<provider>/model_registry.yaml) with a custom path. | Optional |
| SKILLSPECTOR_LOG_LEVEL | Log level: DEBUG, INFO, WARNING, ERROR (default: WARNING). | Optional |
| SKILLSPECTOR_MAX_DEPENDENCY_SOURCE_ANALYSIS_SECONDS | Ceiling for the dependency-source analysis pass, in seconds. Defaults to 5.0, which is the historical value. Raise it on slow or heavily loaded machines so the same unchanged tree does not come back partially inspected, which would set safe_to_install to false and record runtime_limit. The remaining aggregate workflow time (SKILLSPECTOR_MAX_WORKFLOW_SECONDS, 600 seconds by default) still caps the effecti; above that remaining time have no effect. Invalid, zero, negati, and NaN keep the 5-second default. The setting is resolved when the module is imported, so a new process is required after changing it. See analysis resource bounds. | Optional |

> CLI pro (claude_cli, codex_cli, gemini_cli, opencode_cli): No API key is needed. Authentication is managed entirely by the agent CLI's own login session. SkillSpector ne or forwards API keys when these pro are active. The subprocess is run with capabilities restricted, and untrusted skill content is delivered only .
>
> opencode_cli currently fails closed unless the installed OpenCode is exactly 1.18.33, the whose configuration precedence and deny-all semantics are by this release.

CLI Options

Integrating SkillSpector

SkillSpector is built to be driven by other tools (CI pipelines, install gates, editor integrations). Its exit code and JSON output are a stable contract.

Exit codes

skillspector scan exits with:

| Code | Meaning |
|------|---------|
| 0 | Scan completed, risk_score ≤ 50 (recommendation SAFE or CAUTION), and no enabled strict gate fired |
| 1 | Scan completed and either risk_score > 50, --fail-on-findings found an acti, --fail-on-incomplete found partial/incomplete analysis, or --min-co found co below its threshold |
| 2 | Error (bad input, unreadable source, internal failure) |

> By default, the exit code collapses SAFE and CAUTION into 0. Use --fail-on-findings to gate on any acti, --fail-on-incomplete to gate on incomplete co, --min-co PERCENT to gate on a co floor, or read the JSON recommendation field for custom policy.

Machine-readable output

--format json produces a JSON report; with no --output/-o it is written to stdout:

The top-le is (this example shows a full LLM-backed scan; with --no-llm, metadata.llm_requested is false):

risk_assessment.se ∈ LOW | MEDIUM | HIGH | CRITICAL.

risk_assessment.recommendation ∈ SAFE | CAUTION | DO_NOT_INSTALL, mapped from se: LOW → SAFE, MEDIUM → CAUTION, HIGH/CRITICAL → DO_NOT_INSTALL.

metadata.llm_error appears only when LLM analysis was requested but una.

AE1 findings use Incomplete referenced artifact analysis. Their source

location identifies the reference; e identifies the affected target,
analyzer reasons, and a bounds. Review the target's completeness
ledger when reasons_truncated is true. See
referenced-artifact diagnostics and Perl help text
for interpretation and correcti.

metadata.inference_usage contains one sanitized record per LLM response when the

provider exposes token counters. It is an empty list when usage is una;
SkillSpector ne missing tokens. Prompt totals are inclusive of cache
reads and writes so downstream pricing can separate those partitions safely.
model_source distinguishes an independently identified provider model from
the exact requested model used when response identity is absent or ambiguous.
SkillSpector does not currently send Anthropic prompt-cache controls, so its
scan requests cannot select the separate 5-minute or 1-hour cache-write tiers;
TTL-specific response fields are normalized defensively into the aggregate
cache-write counter.

See Inference usage telemetry for the complete

pro, cache-accounting, privacy, fail-closed ingestion, and downstream
pricing contract.

The full per-issue shape is defined by Finding.to_dict() in models.py; rely on the fields above and treat any additional fields as best-effort.

For CI/IDE tooling, --format sarif emits SARIF 2.1.0. Each result carries its
security se; rule descriptors carry a score only when all of their results
share that se. Mixed-se rules remain unannotated, so consumers that
read only rule-le cannot distinguish their result se.
Recursi chain each percent-encoded skill-directory URI through an
absolute scan-root file URI. External dependency locations retain their source
pro instead of being rebased into the local skill directory.

Recommended gate mapping

When using SkillSpector as an install gate, map the recommendation to an action:

| recommendation | Suggested action |
|------------------|------------------|
| SAFE | allow |
| CAUTION | prompt / warn the user |
| DO_NOT_INSTALL | block |

SkillSpector computes the score band and recommendation; how strict the gate is (e.g. whether CAUTION blocks in CI) is a policy decision for the integrating tool.

De

Setup

All make targets assume a en is already created and activated. The Makefile uses uv if a, else pip.

How It Works

SkillSpector uses a two-stage detection pipeline:

Stage 1: Static Analysis

Fast regex-based pattern matching across 11 static analyzers

AST-based beha analysis detecting dangerous calls (exec, eval, subprocess, etc.)

Li lookups via OSV.dev for known CVEs in dependencies

Scans all analyzer-eligible files in the skill

High recall (catches most issues)

Moderate precision (some false positives)

A valid, root-le Model Signing signature (skill.oms.sig) is retained in the
component in as type oms_signature, but excluded from static and LLM content analysis.
OMS bundles necessarily contain long base64-encoded payload, signature, and certificate fields;
generic obfuscated-code checks can otherwise misclassify those fields as hidden executable content.
The recognizer checks the minimal OMS DSSE/in-toto structure; it does not the signature,
certificate chain, transparency-log entry, or signer identity. Invalid or unrecognized signature
files are scanned normally.

Stage 2: LLM Semantic Analysis (Optional)

E context and intent

Filters false positives

Provides human-readable explanations

Impro to ~87%

The LLM prompt includes anti-jailbreak protections to prevent malicious skills from manipulating the analysis.

Li Lookups (SC4)

SC4 uses the OSV.dev API to check dependencies against the full Open Source database — co tens of thousands of ad across PyPI and npm.

No API key required — OSV.dev is free and unauthenticated.

Batch queries — all dependencies are checked in a single HTTP call.

Automatic fallback — if OSV.dev is unreachable (air-gapped/offline), a small built-in fallback list is used.

Caching — results are cached in-memory for 1 hour to avoid redundant API calls during a session.

The tool requires outbound HTTPS access to api.osv.dev for li data. When that is not a, findings are limited to the static fallback list.

Trust model and data egress

SkillSpector is defense-in-depth, not a sandbox. Know what it does and does not do before relying on it:

It ne the scanned skill. All analysis is static (regex, Python AST, YARA) plus optional LLM e of file *contents* — the skill's code is never run.

LLM analysis sends analyzer-eligible file contents to the configured provider. When LLM analysis is enabled (the default), file contents are sent to the active SKILLSPECTOR_PROVIDER endpoint. Recognized OMS signature files are excluded. Use --no-llm to keep contents local (static analysis only).

SC4 sends dependency names to OSV.dev. The supply-chain check queries OSV.dev with the package names and the skill declares, to look up known CVEs. This is fundamental to the check and runs even with --no-llm. It sends dependency coordinates (not file contents), requires no API key, and falls back to a bundled list when OSV.dev is unreachable.

It does not sandbox the host. SkillSpector flags risky patterns *before* you install a skill; it does not contain or isolate a skill you choose to install anyway.

Limitations

Non-English content: May miss patterns in other languages

Image-based attacks: Cannot analyze text in images

Encrypted/binary code: Cannot analyze compiled or encrypted content

Runtime behavior: Static analysis only, no dynamic execution

Offline SC4: Without network access to api.osv.dev, SC4 uses a small static fallback list

Research Background

Based on research from "Agent Skills in the Wild: An Empirical Study of Security at Scale" (Liu et al., 2026):

Dataset: 42,447 skills from major marketplaces; 31,132 were analyzed for the following rates

: 26.1% of the analyzed subset contain at least one

High-se: 5.2% of the analyzed subset show likely malicious intent

Key finding: Skills with executable scripts are 2.12x more likely to be

Python API Integration

License

Apache License 2.0 - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

Support

Issues: GitHub Issues

项目信息

开发语言：Python

Star 数：19425

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕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.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。