Skip to content
Back to search

SkillSpector

SkillWorks with CodexGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NVIDIA/SkillSpector with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NVIDIA/SkillSpector'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nvidia-skillspector/badge.svg)](/listings/nvidia-skillspector)

HTML

<a href="/listings/nvidia-skillspector"><img src="/api/listings/nvidia-skillspector/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 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 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 '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 .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

Docker (no Python required)

Run SkillSpector without installing Python by building it locally from the included [Dockerfile](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/

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

docker run --rm \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

**Optional alias** for repeated static scans:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

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

Size limits

SkillSpector enforces two independent caps on remote and archive inputs to bound the impact of oversized 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 individual analyzers will read out of an already-ingested directory. The ingest caps above bound how much content can land on disk in the first place. A breach of either ingest cap fails closed with an `IngestLimitExceededError`.

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

Batch Scanning

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,227 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # SkillSpector
  2. **Security scanner for AI agent skills.** Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.
  3. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  4. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
  5. ## Overview
  6. 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**.
  7. SkillSpector helps you answer: **"Is this skill safe to install?"**
  8. SkillSpector is part of the [NVIDIA Verified Skills pipeline](https://docs.nvidia.com/skills/), which scans, evaluates, and signs agent skills before publication. Skills that pass are published to the [NVIDIA skills catalog](https://github.com/NVIDIA/skills).
  9. ## Documentation
  10. - **[Scan agent skills before installation](https://docs.nvidia.com/skills/scanning-agent-skills)** — Hosted guide: when to scan, how to read a report, and how to gate installs.
  11. - **[Development guide](docs/DEVELOPMENT.md)** — Architecture, package layout, and how to extend the analyzer pipeline.
  12. - **[Security policy](SECURITY.md)** — Report suspected vulnerabilities privately to NVIDIA PSIRT.
  13. - **[Analysis resource bounds](docs/ANALYSIS_RESOURCE_BOUNDS.md)** — Fail-closed bundle, parser, nested-artifact, ledger, and finding ceilings.
  14. - **[Pi extension](docs/PI_EXTENSION.md)** — Install SkillSpector as a Pi tool for scanning skills from inside agent sessions.
  15. - **[OpenCode extension](docs/OPENCODE_EXTENSION.md)** — Install SkillSpector as an OpenCode tool and `/skillspector` command for scanning skills from inside agent sessions.
  16. - **[LLM analyzer base guide](docs/LLM_ANALYZER_BASE_GUIDE.md)** — How to build LLM-powered analyzer nodes on top of `LLMAnalyzerBase`.
  17. - **[Dependency source redirection](docs/DEPENDENCY_SOURCE_REDIRECTION.md)** — How SC10 findings flag a skill that changes where its packages are fetched from.
  18. - **[Live vulnerability lookups (SC4)](docs/SC4-osv-live-vulnerability-lookups.md)** — How SC4 checks dependencies against OSV.dev.
  19. - **[Eval dataset scanning](docs/EVAL_DATASETS.md)** — Which eval dataset files the static pattern analyzers skip.
  20. - **[MCP least-privilege analysis (LP1–LP4)](docs/B.3.1-mcp-least-privilege.md)** and **[MCP tool-poisoning detection (TP1–TP4)](docs/B.3.2-mcp-tool-poisoning.md)** — Design notes for the MCP analyzers.
  21. ## Features
  22. - **Multi-format input**: Scan Git repos, URLs, zip files, directories, or single files
  23. - **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
  24. - **Two-stage analysis**: Fast static analysis + optional LLM semantic evaluation
  25. - **Live vulnerability lookups**: SC4 queries [OSV.dev](https://osv.dev) for real-time CVE data with automatic offline fallback
  26. - **Multiple output formats**: Terminal, JSON, Markdown, and SARIF reports
  27. - **Risk scoring**: 0-100 score with severity labels and clear recommendations
  28. - **Baseline / false-positive suppression**: Accept known findings via a glob-rule or fingerprint baseline so re-scans surface only *new* issues ([docs](docs/SUPPRESSION.md))
  29. ## Quick Start
  30. ### Installation
  31. > **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.
  32. Use **Python 3.12 or 3.13** for installation with prebuilt YARA wheels on supported
  33. platforms. The examples below select 3.13 explicitly; see the
  34. [Python installation notes](#python-installation-notes) for newer interpreters.
  35. For source installs, create and activate a virtual environment first (all `make`
  36. targets assume the venv is active). Use **uv** or **pip**; the Makefile uses `uv`
  37. if available, otherwise `pip`.
  38. **Quick install with uv (CLI-only):**
  39. ```bash
  40. uv tool install --python 3.13 git+https://github.com/NVIDIA/skillspector.git
  41. # Update later: uv tool update skillspector
  42. ```
  43. If you plan to run `skillspector mcp`, install the MCP extra at install time:
  44. ```bash
  45. uv tool install --python 3.13 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
  46. ```
  47. **From source:**
  48. ```bash
  49. # Clone the repository
  50. git clone https://github.com/NVIDIA/skillspector.git
  51. cd skillspector
  52. # Create and activate virtual environment
  53. uv venv --python 3.13 .venv && source .venv/bin/activate
  54. # or: python3.13 -m venv .venv && source .venv/bin/activate
  55. # Install for production use
  56. make install
  57. ```
  58. To contribute, follow the [Development setup](#setup) for a supported Python
  59. interpreter and development dependencies.
  60. ### Python installation notes
  61. The package declares Python `>=3.12,<3.16` in [pyproject.toml](pyproject.toml).
  62. That range does not guarantee prebuilt wheels for every dependency and platform.
  63. [yara-python 4.5.4 on PyPI](https://pypi.org/project/yara-python/4.5.4/#files)
  64. provides CPython 3.12/3.13 wheels, but no CPython 3.14/3.15 wheels. Installing it
  65. on those newer interpreters requires a native source build with a C toolchain
  66. and Python development headers. Such builds can fail with OpenSSL 4 headers;
  67. [issue #1008](https://github.com/NVIDIA/SkillSpector/issues/1008) tracks that
  68. installation problem and upstream wheel availability.
  69. If installation fails while compiling YARA, select Python 3.12 or 3.13 explicitly
  70. using the commands above. For a new CLI-only installation with `pipx`, first
  71. install Python 3.13 and make `python3.13` available on PATH, then run:
  72. ```bash
  73. pipx install --python python3.13 git+https://github.com/NVIDIA/skillspector.git
  74. ```
  75. The upstream [wheel-build update](https://github.com/VirusTotal/yara-python/pull/281)
  76. is separate from publishing a new release to PyPI. Check the published files
  77. before choosing a newer interpreter; a source build may still be required.
  78. ### Docker (no Python required)
  79. Run SkillSpector without installing Python by building it locally from the included [Dockerfile](Dockerfile). The image is based on the Docker Official Python `3.12-slim-bookworm` image.
  80. **Build the image:**
  81. ```bash
  82. make docker-build
  83. # or: docker build -t skillspector .
  84. ```
  85. **Scan a local directory** by mounting your current directory into `/scan`, the container's working directory:
  86. ```bash
  87. docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm
  88. ```
  89. **Scan with LLM analysis** by passing credentials with a local `.env` file:
  90. ```bash
  91. cat > .env <<'EOF'
  92. SKILLSPECTOR_PROVIDER=anthropic
  93. ANTHROPIC_API_KEY=sk-ant-...
  94. EOF
  95. ```
  96. ```bash
  97. docker run --rm \
  98. -v "$PWD:/scan" \
  99. --env-file .env \
  100. skillspector scan ./my-skill/
  101. ```
  102. Or pass credentials directly from your shell environment:
  103. ```bash
  104. docker run --rm \
  105. -v "$PWD:/scan" \
  106. -e SKILLSPECTOR_PROVIDER=anthropic \
  107. -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  108. skillspector scan ./my-skill/
  109. ```
  110. **Write a report to the host filesystem** by writing to the mounted directory:
  111. ```bash
  112. docker run --rm --user "$(id -u):$(id -g)" \
  113. -v "$PWD:/scan" \
  114. skillspector scan ./my-skill/ --no-llm --format json --output report.json
  115. ```
  116. **Optional alias** for repeated static scans:
  117. ```bash
  118. alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
  119. skillspector-docker scan ./my-skill/ --no-llm
  120. ```
  121. ### Basic Usage
  122. ```bash
  123. # Scan a local skill directory
  124. skillspector scan ./my-skill/
  125. # Scan a single SKILL.md file
  126. skillspector scan ./SKILL.md
  127. # Scan a Git repository
  128. skillspector scan https://github.com/user/my-skill
  129. # Scan a zip file
  130. skillspector scan ./my-skill.zip
  131. ```
  132. #### Size limits
  133. SkillSpector enforces two independent caps on remote and archive inputs to bound the impact of oversized downloads and zip bombs:
  134. - **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.
  135. - **Zip member cap**: `INGEST_MAX_ZIP_MEMBERS` (10,000) — caps the number of entries in a single zip.
  136. Note that the per-file 1 MB analysis cap (`MAX_FILE_BYTES`) is a separate, downstream limit: it bounds what individual analyzers will read out of an already-ingested directory. The ingest caps above bound how much content can land on disk in the first place. A breach of either ingest cap fails closed with an `IngestLimitExceededError`.
  137. ### Output Formats
  138. ```bash
  139. # Terminal output (default) - pretty formatted
  140. skillspector scan ./my-skill/
  141. # JSON output - machine readable
  142. skillspector scan ./my-skill/ --format json --output report.json
  143. # Markdown output - for documentation
  144. skillspector scan ./my-skill/ --format markdown --output report.md
  145. # SARIF output - for CI/CD integration and IDE tooling
  146. skillspector scan ./my-skill/ --format sarif --output report.sarif
  147. ```
  148. ### Recursive Collection Scanning
  149. `--recursive` scans immediate subdirectories containing `SKILL.md` as independent
  150. skills, with a default aggregate limit of **32 skills**. To raise or lower it:
  151. ```bash
  152. skillspector scan ./my-skills/ --recursive --max-skills 100 --no-llm --format json
  153. ```
  154. `--max-skills` requires a local recursive collection and a positive integer; `0`
  155. does not mean unlimited. Discovery, byte, finding-record, time and report-size
  156. budgets still apply, so increasing the count does not guarantee complete coverage.
  157. When the count limit is reached, the CLI names the limit and suggests adjusting it
  158. or scanning sub-skills separately. Omitted skills remain visible in the aggregate
  159. report and coverage stays incomplete. Use `--fail-on-incomplete` in CI to fail on
  160. incomplete coverage; the default exit policy is unchanged.
  161. ### Batch Scanning
  162. Scan entire directories of skills in parallel from `contrib/batch_scan/`:
  163. ```bash
  164. python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
  165. python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
  166. python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20
  167. ```
  168. Supports multilingual detection (zh/ja/ko) and terminal/JSON/Markdown output.
  169. For LLM scans with higher concurrency, configure multiple API keys following
  170. [`.env.example`](contrib/batch_scan/.env.example) — the pool improves throughput
  171. and resilience, provided the keys don't share an account-level rate limit.
  172. See the [contrib guide](contrib/batch_scan/docs/) for details.
  173. > **Note on LLM support:** The default configuration targets DeepSeek as the
  174. > cheapest public option. DeepSeek-Chat is
  175. > [expected to sunset](https://api-docs.deepseek.com/), and the contributor
  176. > does not have hardware to test against local models. The batch scanner was
  177. > originally tested with OpenAI-compatible endpoints — DeepSeek's lack of
  178. > structured-output support required manual JSON-parsing patches. If you can
  179. > contribute a more universal backend (Ollama, vLLM, or a different provider),
  180. > PRs are very welcome.
  181. ### Comparing MCP Registry snapshots
  182. A named scan fetches only that server's published versions from the official
  183. registry, then selects entries marked as latest. If none are marked as latest,
  184. all matching versions are assessed. The server name remains the report source:
  185. ```bash
  186. skillspector scan 'ac.inference.sh/mcp' --mcp-registry --format json --output current.json
  187. ```
  188. Use `https://registry.modelcontextprotocol.io/v0/servers` as the input to scan
  189. the full catalog. Local registry captures are also supported as UTF-8 JSON,
  190. with or without a leading UTF-8 byte-order mark (BOM). The same encoding is
  191. accepted for saved Registry reports used with `--mcp-registry-compare`.
  192. Start with raw registry payload captures (`registry-before.json` and
  193. `registry-after.json`). Save a scan report as `previous.json`, then compare a
  194. later scan against that generated local report:
  195. ```bash
  196. skillspector scan registry-before.json --mcp-registry --format json --output previous.json
  197. skillspector scan registry-after.json --mcp-registry --format json \
  198. --mcp-registry-compare previous.json --output compared.json
  199. ```
  200. The optional `comparison` object lists added and removed server identities,
  201. changed normalized fields with their previous and current values, and an
  202. `unchanged_count`. Identity is the server name and version, so a new version
  203. appears as an addition and the old version as a removal if it is absent from the
  204. new scan. Acquisition source and scan timestamp are excluded from comparison.
  205. `unmodeled_changes` lists same-identity records whose raw-record hash changed
  206. while normalized fields match; these are not counted as unchanged. This can
  207. indicate a change to fields outside the snapshot model, or array reordering in
  208. the raw record. Package and remote ordering alone is not a normalized field change.
  209. Entries in `changed` may also contain changes outside the snapshot model; inspect
  210. the raw record to see those changes.
  211. Compare reports with the same selection scope: a server absent from the current
  212. input is reported as removed, which does not prove it was removed from a registry.
  213. The comparison file must be a local report produced by this registry mode with
  214. valid normalized snapshots. Malformed, oversized or duplicate server identities
  215. are rejected. This option requires `--mcp-registry` and is separate from the
  216. finding-suppression `--baseline`: it never suppresses findings or changes risk
  217. scores, and it does not fetch or execute listed server endpoints.
  218. Registry mode rejects skill-only controls such as `--use-shipped-baseline`,
  219. `--transitive`, `--transitive-depth`, `--transitive-allow-prefix`, and
  220. `--transitive-deny-prefix` with exit code 2, including an explicitly supplied
  221. default depth (`--transitive-depth 1`). Omit these options for registry scans.
  222. ### Suppressing False Positives (baseline)
  223. Suppress known/accepted findings so the risk score reflects only un-triaged
  224. issues and re-scans surface only *new* findings. See the
  225. [suppression guide](docs/SUPPRESSION.md) for the full reference.
  226. ```bash
  227. # Accept all current findings into a baseline (run once), then commit it.
  228. skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
  229. # Scan against the baseline — only NEW findings are reported and scored.
  230. skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml
  231. # Review what was suppressed (still excluded from the score).
  232. skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed
  233. ```
  234. A baseline can also use drift-tolerant glob rules (by rule id, file path, or
  235. message) — see [`.skillspector-baseline.example.yaml`](.skillspector-baseline.example.yaml).
  236. Exact fingerprint baselines are evidence-bound: changing the scanned source or
  237. SkillSpector version keeps the finding active until it is reviewed again.
  238. When a selected baseline or baseline output is stored inside the skill
  239. directory, SkillSpector excludes that exact file from content analysis so its
  240. suppression text cannot create findings or enter regenerated fingerprints;
  241. sibling files remain in normal scan scope.
  242. ### Explicit scan scope
  243. For a local directory containing one `SKILL.md` or `skill.md`, repeat `--exclude` to omit
  244. selected files before content analysis:
  245. ```bash
  246. skillspector scan ./my-skill --exclude 'tests/*' --exclude 'fixtures/*.json'
  247. ```
  248. Patterns are case-sensitive globs matched against the entire relative POSIX path;
  249. `*` also matches `/`. Quote patterns so your shell does not expand them. This is
  250. an explicit caller option, not an author-controlled ignore file. Patterns matching
  251. either manifest name (`SKILL.md` or `skill.md`) are rejected, as are recursive, multi-skill, transitive, registry, and
  252. non-directory inputs. No-match patterns are still recorded in the report.
  253. Files already outside the scan inventory, such as policy-excluded dependencies,
  254. retain their existing policy handling and are not counted as caller exclusions.
  255. Explicitly excluded inventory files remain in the coverage denominator as entirely uninspected. The
  256. report lists the applied patterns, excluded count and individual skipped paths;
  257. any matched exclusion makes coverage partial and prevents a `SAFE` recommendation.
  258. Use `--fail-on-incomplete` when partial scope should fail CI. These exclusions do
  259. not suppress findings in included files or override existing safety limits.
  260. ### LLM Analysis
  261. For the best results, configure an OpenAI-compatible LLM endpoint for
  262. semantic analysis. Pick a provider with `SKILLSPECTOR_PROVIDER`; hosted providers ship bundled default models, while CLI providers fall back to the local runtime's default model unless `SKILLSPECTOR_MODEL` is set. SkillSpector also works against
  263. local OpenAI-compatible servers (Ollama, vLLM, llama.cpp) and managed
  264. inference gateways.
  265. | Provider (`SKILLSPECTOR_PROVIDER`) | Credential env var | Endpoint | Default model |
  266. | ---------- | ---- | ---- | ---- |
  267. | `openai` | `OPENAI_API_KEY` (+ optional `OPENAI_BASE_URL`) | api.openai.com (or any OpenAI-compatible URL) | `gpt-5.4` |
  268. | `anthropic` | `ANTHROPIC_API_KEY` | api.anthropic.com | `claude-opus-4-6` (`meta_analyzer`: `claude-sonnet-4-6`) |
  269. | `anthropic_proxy` | `ANTHROPIC_PROXY_API_KEY` + `ANTHROPIC_PROXY_ENDPOINT_URL` | Any Vertex-style raw-predict proxy | `claude-sonnet-4-6` |
  270. | `minimax` | `MINIMAX_API_KEY` (+ optional `MINIMAX_REGION`) | Global or China regional endpoint | `MiniMax-M3.1-Flash` |
  271. | `bedrock` | `AWS_PROFILE` (optional) + `AWS_REGION` — SigV4 via boto3 | AWS Bedrock Runtime | `us.anthropic.claude-sonnet-4-6` |
  272. | `nv_build` | `NVIDIA_INFERENCE_KEY` | build.nvidia.com | `z-ai/glm-5.3-flash` |
  273. | `gemini` | `GOOGLE_CLOUD_PROJECT` (+ optional `GOOGLE_CLOUD_LOCATION`) via ADC | Google Cloud OpenAI-compatible Gemini endpoint | `gemini-3.8-flash` |
  274. | `ollama` | _(none)_ | `OLLAMA_BASE_URL` (default `http://localhost:11434/v1`) | `llama3.1:8b` |
  275. | `azure_openai` | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` | Azure OpenAI Service | `gpt-4o` (deployment defaults to the model label) |
  276. | `openai_compatible` | `SKILLSPECTOR_COMPAT_API_KEY` + `SKILLSPECTOR_COMPAT_BASE_URL` | Any OpenAI-compatible endpoint | `llama-3.1-70b-versatile` |
  277. | `claude_cli` | _(none — uses local CLI auth)_ | local `claude` binary | local Claude runtime fallback, or `SKILLSPECTOR_MODEL` |
  278. | `codex_cli` | Disabled | Registered for compatibility; its read-only sandbox permits host-file reads | Use an HTTP API provider or another supported CLI provider |
  279. | `gemini_cli` | _(none — uses local CLI auth)_ | local `gemini` binary | local Gemini runtime fallback, or `SKILLSPECTOR_MODEL` |
  280. | `opencode_cli` | _(none — uses local CLI auth)_ | local `opencode` (verified 1.18.31–1.18.35, 1.19.0–1.19.4) binary | local OpenCode runtime fallback, or `SKILLSPECTOR_MODEL` |
  281. For `openai_compatible` gateways requiring extra HTTP headers, set
  282. `SKILLSPECTOR_COMPAT_HEADERS='{"X-Tenant-ID":"my-tenant","X-API-Key":"gateway-key"}'`.
  283. It must be a JSON object with string keys and values and applies to sync and async requests.
  284. Unset or blank values add no headers; invalid configuration is rejected without exposing header values.
  285. Treat this environment variable as a secret when it contains gateway API keys.
  286. `gpt-6.1-sol`, `claude-opus-5-5`, and `claude-sonnet-5-5` remain opt-in through
  287. `SKILLSPECTOR_MODEL` or per-slot overrides. Promoting them to defaults requires
  288. live scanner acceptance covering benign input, credential disclosure, prompt
  289. injection, refusals, and incomplete responses.
  290. Record findings, completion status, latency, and usage, and compare against
  291. previous defaults where accessible.
  292. For NVIDIA Build's `z-ai/glm-5.3-flash`, SkillSpector requests `high` reasoning effort.
  293. Set `SKILLSPECTOR_REASONING_EFFORT` to override it with `low`, `high`, or `max`.
  294. The bundled 128,000-token context and 32,000-token output budgets are conservative
  295. application limits; they do not claim the hosted endpoint's maximum capacity.
  296. Structured output is requested through LangChain's `with_structured_output`.
  297. The default is client-specific: `ChatOpenAI` uses `json_schema`, while other
  298. clients may use tool calling. Some models reject a forced tool call with
  299. HTTP 400 (`tool_choice: type "tool" and "any" are not supported for this
  300. model`). The `anthropic` and `anthropic_proxy` providers route those models
  301. (`claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-1`, `claude-mythos-5-1`,
  302. or any registry entry with `structured_output: json_schema`) to the native
  303. JSON-schema response format.
  304. Bedrock has no JSON-schema output for them, so the `bedrock` provider leaves
  305. `toolChoice` at `auto`, asks for the tool call in the prompt, and retries a
  306. prose answer; it recognises the model from the model ID, a geo/global
  307. inference-profile ID, or a foundation-model / inference-profile ARN. An
  308. application-inference-profile ARN hides the model, so add that ARN to the
  309. registry (`SKILLSPECTOR_MODEL_REGISTRY`) with `tool_choice: auto`.
  310. The `openai_compatible` provider honours the same `tool_choice: auto` entry
  311. for endpoints that ignore both `response_format` and a forced `tool_choice`
  312. and answer in prose (for example iFlytek's `spark-x2.5`, which is bundled).
  313. The `anthropic`, `anthropic_proxy`, `openai`, and `openai_compatible` providers
  314. also recognise those Claude models inside gateway model IDs such as
  315. `anthropic/claude-opus-5-5` or `aws/anthropic/bedrock-claude-opus-5-5`. Some
  316. OpenAI-compatible gateways turn a `json_schema` response format for Claude into
  317. a forced tool call, so the `openai` and `openai_compatible` providers bind the
  318. schema as a tool with `tool_choice` left at `auto` and retry a prose answer.
  319. `SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD=json_schema|function_calling`
  320. overrides the method for any provider.
  321. The method precedence is `SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD`, the provider's
  322. method hint, an analyzer preference, then the client default. TP4 prefers
  323. `function_calling` only for provider `openai` and the exact model label
  324. `azure/anthropic/claude-opus-5`, with reasoning/thinking controls unset; dated
  325. or suffixed labels and other providers keep their existing behavior. An explicit
  326. environment override or provider hint still wins when reasoning is configured.
  327. ```bash
  328. # Stock OpenAI
  329. export SKILLSPECTOR_PROVIDER=openai
  330. export OPENAI_API_KEY=sk-...
  331. skillspector scan ./my-skill/
  332. # Anthropic
  333. export SKILLSPECTOR_PROVIDER=anthropic
  334. export ANTHROPIC_API_KEY=sk-ant-...
  335. skillspector scan ./my-skill/
  336. # Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)
  337. export SKILLSPECTOR_PROVIDER=anthropic_proxy
  338. export ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict
  339. export ANTHROPIC_PROXY_API_KEY=your-bearer-token
  340. export SKILLSPECTOR_MODEL=claude-sonnet-4-6
  341. skillspector scan ./my-skill/
  342. # AWS Bedrock (Claude via SigV4)
  343. export SKILLSPECTOR_PROVIDER=bedrock
  344. # Optional: select an AWS named profile. When unset, the standard
  345. # boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.
  346. # export AWS_PROFILE=my-profile
  347. export AWS_REGION=us-west-2 # default if unset
  348. # Default model: us.anthropic.claude-sonnet-4-6
  349. # Override with any Bedrock model ID, cross-region inference-profile
  350. # ID, or your own application-inference-profile ARN. Claude 5.5 is opt-in:
  351. # us./eu. profiles keep requests in that geography, global. routes worldwide.
  352. # export SKILLSPECTOR_MODEL=us.anthropic.claude-sonnet-5-5
  353. skillspector scan ./my-skill/
  354. # NVIDIA build.nvidia.com
  355. export SKILLSPECTOR_PROVIDER=nv_build
  356. export NVIDIA_INFERENCE_KEY=nvapi-...
  357. skillspector scan ./my-skill/
  358. # MiniMax global endpoint; use cn_zh for the China endpoint
  359. export SKILLSPECTOR_PROVIDER=minimax
  360. export MINIMAX_API_KEY=your-key
  361. export MINIMAX_REGION=global_en
  362. # Default: MiniMax-M3.1-Flash; set SKILLSPECTOR_MODEL=MiniMax-M3 to select M3.
  363. # Flash reasoning effort: low, medium, high, xhigh, max (endpoint default).
  364. # Explicit legacy/custom model IDs remain supported through SKILLSPECTOR_MODEL.
  365. skillspector scan ./my-skill/
  366. # Gemini on Google Cloud (Application Default Credentials / Workload Identity)
  367. # Prerequisites:
  368. # 1. Google Cloud project with billing enabled.
  369. # 2. Enable Gemini Enterprise Agent Platform / Vertex AI API: `aiplatform.googleapis.com`.
  370. # 3. IAM permission: grant `roles/aiplatform.user` (or at minimum `aiplatform.endpoints.predict`)
  371. # to your user account or Kubernetes service account.
  372. # 4. Local authentication: run `gcloud auth application-default login`.
  373. # Configure a quota project if needed: `gcloud auth application-default set-quota-project PROJECT_ID`.
  374. # 5. Kubernetes / GKE: configure Workload Identity and leave GOOGLE_APPLICATION_CREDENTIALS unset
  375. # rather than exporting service account keys.
  376. # Note on Data Residency:
  377. # The default `global` endpoint does not support data-residency requirements. While you can target
  378. # `us`, `eu`, or regional endpoints (e.g. `us-central1`), endpoint selection alone does not guarantee
  379. # data residency or in-region processing without appropriate organizational policies. Always verify
  380. # that your selected model is supported in your target location.
  381. # Optional credentials:
  382. # GOOGLE_APPLICATION_CREDENTIALS is optional and can reference Workload or Workforce Identity Federation
  383. # configuration files; exporting long-lived service account keys is discouraged.
  384. export SKILLSPECTOR_PROVIDER=gemini
  385. export GOOGLE_CLOUD_PROJECT=my-project-id
  386. # export GOOGLE_CLOUD_LOCATION=global # default is global; or us, eu, or specific region (e.g. us-central1)
  387. # Default model: gemini-3.8-flash
  388. # export SKILLSPECTOR_MODEL=gemini-3.7-flash
  389. skillspector scan ./my-skill/
  390. # Local Claude CLI — no API key; uses your existing `claude auth login` session
  391. # Requires: claude CLI installed and authenticated (claude auth login)
  392. export SKILLSPECTOR_PROVIDER=claude_cli
  393. # Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.
  394. # export SKILLSPECTOR_MODEL=claude-sonnet-4-6
  395. skillspector scan ./my-skill/
  396. # Gemini (via OpenAI compatibility layer)
  397. export SKILLSPECTOR_PROVIDER=openai
  398. export OPENAI_API_KEY="YOUR_GEMINI_API_KEY"
  399. export OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
  400. export SKILLSPECTOR_MODEL=gemini-3.5-flash
  401. skillspector scan ./my-skill/
  402. # Local Ollama — no API key
  403. export SKILLSPECTOR_PROVIDER=ollama
  404. # export OLLAMA_BASE_URL=http://localhost:11434/v1 # shown default
  405. export SKILLSPECTOR_MODEL=llama3.1:8b
  406. skillspector scan ./my-skill/
  407. # Azure OpenAI
  408. export SKILLSPECTOR_PROVIDER=azure_openai
  409. export AZURE_OPENAI_API_KEY=...
  410. export AZURE_OPENAI_ENDPOINT=https://example.openai.azure.com/
  411. export AZURE_OPENAI_DEPLOYMENT=my-deployment
  412. skillspector scan ./my-skill/
  413. # Any other OpenAI-compatible endpoint
  414. export SKILLSPECTOR_PROVIDER=openai_compatible
  415. export SKILLSPECTOR_COMPAT_API_KEY=...
  416. export SKILLSPECTOR_COMPAT_BASE_URL=https://api.groq.com/openai/v1
  417. export SKILLSPECTOR_MODEL=llama-3.1-70b-versatile
  418. skillspector scan ./my-skill/
  419. # Override the provider's default model
  420. export SKILLSPECTOR_MODEL=gpt-5.2
  421. skillspector scan ./my-skill/
  422. # Skip LLM analysis (faster, static analysis only)
  423. skillspector scan ./my-skill/ --no-llm
  424. ```
  425. ### MCP Server
  426. Run SkillSpector as a [Model Context Protocol](https://modelcontextprotocol.io)
  427. server so local MCP-capable agents (Claude Code, Codex CLI, Gemini CLI)
  428. can call scanning as a tool and **gate skill/MCP installs on the
  429. result** — turning SkillSpector into a runtime guardrail instead of an
  430. out-of-band audit step.
  431. `skillspector mcp` requires `skillspector[mcp]`.
  432. ```bash
  433. # Install, or reinstall if you already used the CLI-only path
  434. uv tool install --python 3.13 --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
  435. # FastMCP stdio transport for local CLI agents
  436. skillspector mcp
  437. # Streamable HTTP transport on a local loopback interface
  438. skillspector mcp --transport http --host 127.0.0.1 --port 8000
  439. ```
  440. The stdio transport is the current FastMCP path for local CLI agents, and the
  441. initialize hang reported in issue #199 still applies there.
  442. The server exposes a single tool:
  443. - **`scan_skill(target, use_llm=true, output_format="json", include_report=true)`** — scans a Git
  444. URL, file URL, `.zip`, `.md` file, or directory and returns a structured
  445. verdict: `risk_score` (0-100), `severity`, `recommendation`,
  446. `safe_to_install`, and `findings`. It also reports `llm_used` / `scan_mode`
  447. so a low score from a static-only scan is never mistaken for a clean full
  448. scan.
  449. Set `include_report=false` when you only need the structured verdict. This
  450. omits the rendered `report` string and retains every other response field,
  451. including all findings and their occurrences, analysis completeness, and LLM
  452. accounting. The default still includes the full report. Report-only details,
  453. such as components, skill metadata, and suppressed findings, are unavailable
  454. in the compact response. Scanning and report generation still run normally;
  455. `output_format` must remain one of `json`, `markdown`, `sarif`, or `terminal`.
  456. Register it with Claude Code via:
  457. ```bash
  458. claude mcp add skillspector -- skillspector mcp
  459. ```
  460. > **Security — HTTP transport trust model**
  461. >
  462. > The HTTP transport ships **without authentication**. Any caller that can
  463. > reach the port can invoke `scan_skill`. HTTP bindings are restricted to
  464. > loopback IPs (`127.0.0.1` or `::1`); `localhost` binds to `127.0.0.1` without
  465. > DNS resolution. Wildcard, routable and other hostname bindings are rejected.
  466. >
  467. > - For remote access, put an authenticating reverse proxy (e.g. nginx + mTLS)
  468. > in front of the loopback listener.
  469. > - Local paths and `file://` URLs are **automatically rejected** over HTTP to
  470. > prevent unauthenticated callers from reading arbitrary host files. Only
  471. > remote Git and `.zip` URLs are accepted.
  472. >
  473. > HTTP scans accept only credential-free `https://` targets. Git scans never use
  474. > the server's Git login or Git config. If a proxy or custom CA is needed, set
  475. > `HTTPS_PROXY`, `NO_PROXY` or `GIT_SSL_CAINFO` in the server environment.
  476. > Use stdio or the CLI for private repositories. Git redirects are rejected;
  477. > use the current repository URL after a rename or transfer.
  478. ## Vulnerability Patterns
  479. SkillSpector detects **71 vulnerability patterns** across 17 categories:
  480. ### Prompt Injection (6 patterns)
  481. | ID | Pattern | Severity | Description |
  482. |----|---------|----------|-------------|
  483. | P1 | Instruction Override | HIGH | Commands to ignore safety constraints |
  484. | P2 | Hidden Instructions | HIGH | Malicious directives in comments/invisible text |
  485. | P3 | Exfiltration Commands | HIGH | Instructions to transmit context externally |
  486. | P4 | Behavior Manipulation | MEDIUM | Subtle instructions altering agent decisions |
  487. | P5 | Harmful Content | CRITICAL | Instructions that could cause physical harm |
  488. | P9 | Whitespace Padding | MEDIUM | Large whitespace padding hiding instructions below/beside the visible area |
  489. ### Anti-Refusal (3 patterns)
  490. | ID | Pattern | Severity | Description |
  491. |----|---------|----------|-------------|
  492. | AR1 | Refusal Suppression | HIGH | Instructions to never refuse or always comply (e.g. "never refuse", "always comply") |
  493. | AR2 | Disclaimer Suppression | HIGH | Instructions to omit warnings, disclaimers, or ethical commentary (e.g. "no disclaimers", "do not moralize") |
  494. | AR3 | Safety Policy Nullification | HIGH | Jailbreak framing that nullifies guardrails (e.g. "you have no restrictions", "ignore your guidelines", "do anything now") |
  495. ### Data Exfiltration (5 patterns)
  496. | ID | Pattern | Severity | Description |
  497. |----|---------|----------|-------------|
  498. | E1 | External Transmission | MEDIUM | Sending data to external URLs |
  499. | E2 | Env Variable Harvesting | HIGH | Enumerating, copying, or searching environment data to collect secrets. A copy traced only to a child process's `env=` is reported LOW |
  500. | E3 | File System Enumeration | MEDIUM | Scanning directories for sensitive files |
  501. | E4 | Context Leakage | HIGH | Transmitting conversation context externally |
  502. | E5 | Cloud Storage Exfiltration | MEDIUM | Uploading data through cloud storage SDKs or CLIs |
  503. Within bounded, fully observed context, E5 distinguishes literal AWS/GCS downloads
  504. from uploads. Simple remote-to-local `cp`, AWS `sync`, and `gsutil rsync` commands do not produce E5
  505. findings. Moves, deletion options, unknown flags, dynamic operands, streams and
  506. compound shell commands retain conservative findings. This direction check does
  507. not change SDK upload detection or the CLI's exit-code policy. Direction proofs
  508. require the complete preceding context to fit within 4,096 characters. Only
  509. blank/comment lines, literal `set` flags (`-e`, `-u`, `-f`, and `-o pipefail`),
  510. and simple directory changes may precede a proved download. Other setup,
  511. including sourcing, autoloading, variable assignments, and earlier transfers,
  512. retains the original finding. Relative destinations after directory changes
  513. remain unproved; literal absolute file destinations are still eligible.
  514. ### Privilege Escalation (3 patterns)
  515. | ID | Pattern | Severity | Description |
  516. |----|---------|----------|-------------|
  517. | PE1 | Excessive Permissions | LOW | Requesting access beyond stated functionality |
  518. | PE2 | Sudo/Root Execution | MEDIUM | Invoking elevated system privileges |
  519. | PE3 | Credential Access | HIGH | Reading SSH keys, tokens, passwords |
  520. ### Supply Chain (10+ patterns)
  521. | ID | Pattern | Severity | Description |
  522. |----|---------|----------|-------------|
  523. | SC1 | Unpinned Dependencies | LOW | No version constraints on packages |
  524. | SC2 | External Script Fetching | HIGH | curl \| bash and remote code execution |
  525. | SC3 | Obfuscated Code | HIGH | Base64/hex encoded execution |
  526. | SC4 | Known Vulnerable Dependencies | HIGH | Dependencies with known CVEs (live OSV.dev lookup) |
  527. | SC5 | Abandoned Dependencies | MEDIUM | Unmaintained packages without security updates |
  528. | SC6 | Typosquatting | HIGH | Package names similar to popular packages |
  529. | SC8 | Shipped Python Bytecode | HIGH | `__pycache__` / `.pyc` present (discovery skips; malicious bytecode bypass) |
  530. | SC9 | Concealed Executable Artifact | HIGH | Executable nested in a document container or hidden/disguised artifact; root-level visible source helpers in manifested `.agents/skills/<name>/` and `.claude/skills/<name>/` folders are exempted but remain local-only and are marked as not LLM-reviewed |
  531. | SC10 | Dependency Source Redirection | HIGH | Package-manager source added, replaced, or unresolved |
  532. ### Excessive Agency (5 patterns)
  533. | ID | Pattern | Severity | Description |
  534. |----|---------|----------|-------------|
  535. | EA1 | Unrestricted Tool Access | HIGH | Unfettered tool access without constraints |
  536. | EA2 | Autonomous Decision Making | HIGH | High-impact decisions without human-in-the-loop |
  537. | EA3 | Scope Creep | MEDIUM | Capabilities extending beyond stated purpose |
  538. | EA4 | Unbounded Resource Access | MEDIUM | No rate limits or quotas on resource consumption |
  539. | EA5 | External Model or Provider Selection | MEDIUM/HIGH | Model/provider pins or coding-CLI shell-outs that can switch billing accounts |
  540. ### Output Handling (3 patterns)
  541. | ID | Pattern | Severity | Description |
  542. |----|---------|----------|-------------|
  543. | OH1 | Unvalidated Output Injection | HIGH | Model output used without sanitization |
  544. | OH2 | Cross-Context Output | MEDIUM | Output flows across trust boundaries without validation |
  545. | OH3 | Unbounded Output | MEDIUM | No limits on output size or generation rate |
  546. ### System Prompt Leakage (3 patterns)
  547. | ID | Pattern | Severity | Description |
  548. |----|---------|----------|-------------|
  549. | P6 | Direct Leakage | HIGH | Instructions that expose system prompts or internal rules |
  550. | P7 | Indirect Extraction | MEDIUM | Extraction via rephrasing, translation, or side-channels |
  551. | P8 | Tool-Based Exfiltration | HIGH | System prompts exfiltrated via file writes or network requests |
  552. ### Memory Poisoning (3 patterns)
  553. | ID | Pattern | Severity | Description |
  554. |----|---------|----------|-------------|
  555. | MP1 | Persistent Context Injection | HIGH | Content designed to persist across interactions |
  556. | MP2 | Context Window Stuffing | MEDIUM | Filler content displacing safety constraints |
  557. | MP3 | Memory Manipulation | HIGH | Tampering with agent memory or stored state |
  558. ### Tool Misuse (3 patterns)
  559. | ID | Pattern | Severity | Description |
  560. |----|---------|----------|-------------|
  561. | TM1 | Tool Parameter Abuse | HIGH | Crafted parameters for unintended behavior (shell=True, --force) |
  562. | TM2 | Chaining Abuse | HIGH | Tool chains that bypass individual safety checks |
  563. | TM3 | Unsafe Defaults | MEDIUM | Overly permissive defaults (disabled TLS, no auth) |
  564. ### Rogue Agent (2 patterns)
  565. | ID | Pattern | Severity | Description |
  566. |----|---------|----------|-------------|
  567. | RA1 | Self-Modification | CRITICAL | Modifying own code or configuration at runtime |
  568. | RA2 | Session Persistence | HIGH | Unauthorized persistence via cron jobs or startup scripts |
  569. ### Trigger Abuse (3 patterns)
  570. | ID | Pattern | Severity | Description |
  571. |----|---------|----------|-------------|
  572. | TR1 | Overly Broad Trigger | MEDIUM | Trigger patterns matching common words |
  573. | TR2 | Shadow Command Trigger | HIGH | Triggers that shadow built-in commands or other skills |
  574. | TR3 | Keyword Baiting Trigger | MEDIUM | Generic triggers designed to maximize activation |
  575. ### Behavioral AST (9 patterns)
  576. | ID | Pattern | Severity | Description |
  577. |----|---------|----------|-------------|
  578. | AST1 | exec() Call | CRITICAL | Direct exec() enabling arbitrary code execution |
  579. | AST2 | eval() Call | HIGH | Direct eval() evaluating arbitrary expressions |
  580. | AST3 | Dynamic Import | HIGH | \_\_import\_\_() loading arbitrary modules at runtime |
  581. | AST4 | subprocess Call | HIGH | External command execution via subprocess |
  582. | AST5 | os.system / exec-family | HIGH | Shell commands via os module |
  583. | AST6 | compile() Call | MEDIUM | Code object creation from strings |
  584. | AST7 | Dynamic getattr() | MEDIUM | Arbitrary attribute access with non-literal names |
  585. | AST8 | Dangerous Execution Chain | CRITICAL | exec/eval combined with dynamic source (network, encoded data) |
  586. | AST9 | Reflective getattr() Sink | HIGH | Reflective exec via `getattr(os,'system')` / `getattr(builtins,'exec')` that evades AST1/AST5 |
  587. ### Taint Tracking (5 patterns)
  588. | ID | Pattern | Severity | Description |
  589. |----|---------|----------|-------------|
  590. | TT1 | Direct Taint Flow | HIGH | Data flows directly from a source to a sink without sanitization |
  591. | TT2 | Variable-Mediated Taint Flow | MEDIUM | Data flows from source to sink through intermediate variables |
  592. | TT3 | Credential Exfiltration Chain | CRITICAL | Credentials (env vars, secrets) flow to network output sinks |
  593. | TT4 | File Read to Network Exfiltration | HIGH | File contents flow to network output sinks |
  594. | TT5 | External Input to Code Execution | CRITICAL | Network or user input flows to exec/eval/subprocess sinks |
  595. ### YARA Signatures (4 patterns)
  596. | ID | Pattern | Severity | Description |
  597. |----|---------|----------|-------------|
  598. | YR1 | Malware Match | CRITICAL | YARA rule match for known malware signatures |
  599. | YR2 | Webshell Match | CRITICAL | YARA rule match for webshell patterns |
  600. | YR3 | Cryptominer Match | HIGH | YARA rule match for crypto mining indicators |
  601. | YR4 | Hack Tool / Exploit Match | HIGH | YARA rule match for hack tools or exploit code |
  602. ### MCP Least Privilege (4 patterns)
  603. | ID | Pattern | Severity | Description |
  604. |----|---------|----------|-------------|
  605. | LP1 | Underdeclared Capability | HIGH | Code uses capabilities not listed in declared permissions |
  606. | LP2 | Wildcard Permission | MEDIUM | Permission list contains wildcards (\*, all, full, any) |
  607. | LP3 | Missing Permission Declaration | MEDIUM | No permissions field but code has detectable capabilities |
  608. | LP4 | Overdeclared Permission | LOW | Permission declared but no corresponding code capability found |
  609. ### MCP Tool Poisoning (4 patterns)
  610. | ID | Pattern | Severity | Description |
  611. |----|---------|----------|-------------|
  612. | TP1 | Hidden Instructions | HIGH | Hidden directives in metadata (HTML comments, zero-width chars, base64, data URIs) |
  613. | TP2 | Unicode Deception | HIGH | Homoglyphs, RTL overrides, mixed-script identifiers in tool metadata |
  614. | TP3 | Parameter Description Injection | MEDIUM | Injection patterns in parameter definitions (overrides, system tokens, malicious defaults) |
  615. | TP4 | Description-Behavior Mismatch | MEDIUM | Declared tool description does not match actual code behavior (LLM-powered) |
  616. All detected patterns are listed in the tables above.
  617. ## Risk Scoring
  618. ### Score Calculation
  619. - **CRITICAL issues**: +50 points
  620. - **HIGH issues**: +25 points
  621. - **MEDIUM issues**: +10 points
  622. - **LOW issues**: +5 points
  623. - **Executable scripts**: 1.3x multiplier
  624. ### Severity Levels
  625. | Score | Severity | Recommendation |
  626. |-------|----------|----------------|
  627. | 0-20 | LOW | SAFE |
  628. | 21-50 | MEDIUM | CAUTION |
  629. | 51-80 | HIGH | DO NOT INSTALL |
  630. | 81-100 | CRITICAL | DO NOT INSTALL |
  631. ## Example Output
  632. ### Terminal Output
  633. ```
  634. SkillSpector Security Report v2.0.0
  635. Skill: suspicious-skill
  636. Source: ./suspicious-skill/
  637. Scanned: 2026-01-29 10:30:00 UTC
  638. Risk Assessment
  639. Metric Value
  640. Score 78/100
  641. Severity HIGH
  642. Recommendation DO NOT INSTALL
  643. Components (3)
  644. File Type Lines Executable
  645. SKILL.md markdown 142 No
  646. scripts/sync.py python 87 Yes
  647. requirements.txt text 3 No
  648. Issues (2)
  649. HIGH: Env Variable Harvesting (E2)
  650. Location: scripts/sync.py:23
  651. Finding: for key, val in os.environ.items():...
  652. Confidence: 94%
  653. Explanation: This code collects environment variables containing
  654. API keys and secrets, then sends them to an external server.
  655. HIGH: External Transmission (E1)
  656. Location: scripts/sync.py:45
  657. Finding: requests.post("https://api.skill.io/env"...
  658. Confidence: 89%
  659. Explanation: Data is being sent to an external server. Combined
  660. with env harvesting above, this indicates credential exfiltration.
  661. ```
  662. ## Configuration
  663. ### Environment Variables
  664. | Variable | Description | Required |
  665. |----------|-------------|----------|
  666. | `SKILLSPECTOR_PROVIDER` | Active LLM provider: `openai`, `anthropic`, `anthropic_proxy`, `bedrock`, `minimax`, `nv_build`, `gemini`, `ollama`, `azure_openai`, `openai_compatible`, `claude_cli`, `gemini_cli`, or `opencode_cli`. Hosted providers use bundled `model_registry.yaml` defaults; CLI providers fall back to the local runtime's default model unless `SKILLSPECTOR_MODEL` is set. Defaults to `nv_build`. | Optional |
  667. | `GOOGLE_CLOUD_PROJECT` | Google Cloud project ID for the `gemini` provider. Authenticates via Google Cloud Application Default Credentials (ADC) or GKE Workload Identity. | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=gemini` |
  668. | `GOOGLE_CLOUD_LOCATION` | Google Cloud location for the `gemini` provider endpoint (e.g. `global`, `us`, `eu`, `us-central1`). Defaults to `global`. | Optional (used when `SKILLSPECTOR_PROVIDER=gemini`) |
  669. | `GOOGLE_APPLICATION_CREDENTIALS` | Optional path to ADC credential/config file (e.g. Workload or Workforce Identity Federation config; exported service account keys are discouraged). For local development, use `gcloud auth application-default login`; for GKE, use Workload Identity. | Optional (used when `SKILLSPECTOR_PROVIDER=gemini`) |
  670. | `NVIDIA_INFERENCE_KEY` | Credential for the `nv_build` provider (build.nvidia.com). | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=nv_build` |
  671. | `OPENAI_API_KEY` | Credential for the OpenAI provider (`SKILLSPECTOR_PROVIDER=openai`). Also serves as the tier-2 fallback in the credential waterfall when the active provider returns no credentials; the fallback then uses the `openai` default model (`gpt-5.4`) for any slot without a model override. Claude Opus or Sonnet 5.5 gateway IDs are not supported through the fallback, because it keeps the active provider's structured-output method; select `SKILLSPECTOR_PROVIDER=openai` for them. | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=openai` |
  672. | `OPENAI_BASE_URL` | Override the OpenAI endpoint (e.g. point at Ollama). | Optional |
  673. | `SKILLSPECTOR_REASONING_EFFORT` | Optional provider- and model-dependent reasoning-effort setting. Non-empty values are trimmed and passed through unchanged. When unset or blank, SkillSpector sends `high` for `nv_build` with `z-ai/glm-5.3-flash`; other provider/model combinations keep their endpoint defaults. The value applies to every model slot, so the `anthropic` `meta_analyzer` default receives the same effort as the analyzers. `gpt-6.1-sol` accepts only `low`, `medium`, `high`, `xhigh`, or `max`; any other value stops a scan before analysis (exit code 2). | Optional |
  674. | `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, severity values, paths, code, and other machine-readable values remain unchanged. Unset, blank, or invalid values preserve the default output language. | Optional |
  675. | `SKILLSPECTOR_TEMPERATURE` | Optional sampling temperature from `0` to `1` for hosted providers. Unset or blank preserves the provider default. Lower values can reduce run-to-run variation but do not guarantee identical output. `gpt-6.1-sol` rejects every explicit temperature, including `1`. Claude Opus 4.7 and later, Sonnet 5, Fable 5, Mythos 5 and Haiku 5 models (for example `claude-opus-5-5`, `claude-fable-5-1`, `claude-haiku-5-5`) accept only `1.0` on the native Anthropic endpoint ([API compatibility rule](https://platform.claude.com/docs/en/api/messages/create)); gateways, proxies, and Bedrock still reject every explicit value for these models. Unsupported settings on active LLM slots stop a scan before analysis (exit code 2). Static scans (`--no-llm`) skip provider initialization and control validation. A Bedrock application-inference-profile ARN hides the model name, so declare `sampling: rejected` for it in the model registry. | Optional |
  676. | `SKILLSPECTOR_SEED` | Optional integer sampling seed for OpenAI-compatible and Azure OpenAI providers. Other hosted providers and CLI providers do not receive it. Provider support remains model-dependent; `gpt-6.1-sol` receives it, but OpenAI treats `seed` as best-effort, so output can still differ between runs. | Optional |
  677. | `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 values are `1`, `true`, and `yes` (case-insensitive; surrounding whitespace is trimmed). Unset or any other value keeps the default zero-padded format. | Optional |
  678. | `ANTHROPIC_API_KEY` | Credential for the Anthropic provider (`SKILLSPECTOR_PROVIDER=anthropic`). | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=anthropic` |
  679. | `ANTHROPIC_BASE_URL` | Override the native Anthropic endpoint (default: `https://api.anthropic.com`). | Optional |
  680. | `MINIMAX_API_KEY` | Credential for the MiniMax provider (`SKILLSPECTOR_PROVIDER=minimax`). | Required when `SKILLSPECTOR_PROVIDER=minimax` |
  681. | `MINIMAX_REGION` | MiniMax regional endpoint: `global_en` (default) or `cn_zh`. | Optional |
  682. | `MINIMAX_BASE_URL` | Override the selected MiniMax regional endpoint. | Optional |
  683. | `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 |
  684. | `ANTHROPIC_PROXY_ENDPOINT_URL` | Full endpoint URL for the Anthropic proxy provider (Vertex-style raw-predict). | Required when `SKILLSPECTOR_PROVIDER=anthropic_proxy` |
  685. | `ANTHROPIC_PROXY_API_KEY` | Bearer token for the Anthropic proxy provider. | Required when `SKILLSPECTOR_PROVIDER=anthropic_proxy` |
  686. | `ANTHROPIC_PROXY_API_VERSION` | `anthropic_version` value sent in the request body (default: `vertex-2023-10-16`). | Optional |
  687. | `AWS_PROFILE` | Named AWS profile for the Bedrock provider — authenticates via SigV4 through boto3. When unset, the standard boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves. | Optional (used when `SKILLSPECTOR_PROVIDER=bedrock`) |
  688. | `AWS_REGION` | AWS region for the Bedrock Runtime endpoint. Defaults to `us-west-2`. | Optional (used when `SKILLSPECTOR_PROVIDER=bedrock`) |
  689. | `OLLAMA_BASE_URL` | Ollama OpenAI-compatible endpoint. Defaults to `http://localhost:11434/v1`. | Optional (used when `SKILLSPECTOR_PROVIDER=ollama`) |
  690. | `AZURE_OPENAI_API_KEY` | API key for the Azure OpenAI provider. | Required when `SKILLSPECTOR_PROVIDER=azure_openai` |
  691. | `AZURE_OPENAI_ENDPOINT` | Azure resource endpoint for the Azure OpenAI provider. | Required when `SKILLSPECTOR_PROVIDER=azure_openai` |
  692. | `AZURE_OPENAI_DEPLOYMENT` | Azure deployment name. Defaults to the selected model label. | Optional |
  693. | `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version. Defaults to `2024-06-01`. | Optional |
  694. | `SKILLSPECTOR_COMPAT_API_KEY` | API key for a generic OpenAI-compatible provider. | Required when `SKILLSPECTOR_PROVIDER=openai_compatible` |
  695. | `SKILLSPECTOR_COMPAT_BASE_URL` | Base URL for a generic OpenAI-compatible provider. | Required when `SKILLSPECTOR_PROVIDER=openai_compatible` |
  696. | `SKILLSPECTOR_MODEL` | Override the active provider model. For hosted providers, this replaces the bundled default from the LLM Analysis table. For CLI providers, this is forwarded as `--model` instead of using the local runtime fallback. | Optional |
  697. | `SKILLSPECTOR_MODEL_<SLOT>` | Override the model for one analyzer slot (for example `SKILLSPECTOR_MODEL_META_ANALYZER`). It takes precedence over `SKILLSPECTOR_MODEL`, which in turn replaces provider slot defaults such as the `anthropic` `meta_analyzer` default. See [model provenance](docs/INFERENCE_USAGE.md#model-provenance) for the full precedence. | Optional |
  698. | `SKILLSPECTOR_MODEL_REGISTRY` | Override the bundled per-provider YAML registry (`src/skillspector/providers/<provider>/model_registry.yaml`) with a custom path. | Optional |
  699. | `SKILLSPECTOR_LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `WARNING`). | Optional |
  700. | `SKILLSPECTOR_MAX_WORKFLOW_SECONDS` | Aggregate scan deadline in seconds; defaults to `1080` (18 minutes). Accepts a positive finite number. Invalid values warn and retain the default. Set before starting the process; caller-supplied budgets and external tool timeouts still apply. | Optional |
  701. | `SKILLSPECTOR_TP4_MAX_BATCHES` | Maximum description-behavior review batches per TP4 analyzer execution; defaults to `256`. Accepts an integer from `1` to `4096`. Unset or blank uses the default; invalid values warn and retain it. Set before starting the process; file, byte, finding, concurrency, and workflow-time limits still apply. | Optional |
  702. | `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`, 1080 seconds by default) still caps the effective value; values above that remaining time have no effect. Invalid, zero, negative, infinite, and NaN values 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](docs/ANALYSIS_RESOURCE_BOUNDS.md#configuring-the-dependency-source-deadline). | Optional |
  703. > **Disabled provider:** `codex_cli` remains registered but cannot run LLM analysis because its read-only sandbox allows host-file reads. Existing users should select an HTTP API provider or another supported CLI provider.
  704. > **CLI providers** (`claude_cli`, `gemini_cli`, `opencode_cli`): No API key is needed. Authentication is managed entirely by the agent CLI's own login session. SkillSpector never reads or forwards API keys when these providers are active. The subprocess is run with capabilities restricted, and untrusted skill content is delivered only via stdin.
  705. >
  706. > `opencode_cli` currently fails closed unless the installed OpenCode version is one of the individually verified releases (`1.18.31`, `1.18.32`, `1.18.33`, `1.18.34`, `1.18.35`, `1.19.0`, `1.19.1`, `1.19.2`, `1.19.3`, `1.19.4`), whose configuration precedence and deny-all semantics are verified by this release; every other version, including prereleases, still fails closed.
  707. ### CLI Options
  708. ```bash
  709. skillspector scan --help
  710. Options:
  711. -f, --format [terminal|json|markdown|sarif] Output format [default: terminal]
  712. -o, --output PATH Output file path
  713. --no-llm Skip LLM analysis (static only)
  714. --yara-rules-dir PATH Extra YARA rules directory (includes disabled)
  715. -b, --baseline PATH Suppress findings listed in a baseline
  716. --show-suppressed List baseline-suppressed findings
  717. -V, --verbose Show detailed progress
  718. --help Show this message and exit
  719. # Generate a baseline of all current findings (see docs/SUPPRESSION.md)
  720. skillspector baseline <path> [-o FILE] [--no-llm] [--reason TEXT]
  721. ```
  722. Report files and new baselines use private permissions (0600). Existing baselines
  723. retain their access metadata when safely replaced; updates requiring in-place
  724. writes are refused. All file output uses atomic replacement. The parent directory
  725. must be writable; symlinked
  726. parents and non-regular destinations such as devices are refused. On macOS,
  727. ancestor directories must also be readable. File output requires POSIX no-follow
  728. directory operations and is unavailable on Windows. Unsupported file output fails
  729. before analysis. Omit `--output` for scan/batch stdout, or use
  730. `skillspector baseline <path> -o -` for JSON on stdout, then redirect only to a
  731. trusted destination. Run Docker with your user ID as above so you can read its files.
  732. ## Integrating SkillSpector
  733. 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.
  734. ### Exit codes
  735. `skillspector scan` exits with:
  736. | Code | Meaning |
  737. |------|---------|
  738. | `0` | Scan completed, `risk_score` ≤ 50 (recommendation `SAFE` or `CAUTION`), and no enabled strict gate fired |
  739. | `1` | Scan completed and either `risk_score` > 50, `--fail-on-findings` found an active finding, `--fail-on-incomplete` found partial/incomplete analysis, or `--min-coverage` found coverage below its threshold |
  740. | `2` | Error (bad input, unreadable source, internal failure) |
  741. > By default, the exit code collapses `SAFE` and `CAUTION` into `0`. Use `--fail-on-findings` to gate on any active finding, `--fail-on-incomplete` to gate on incomplete coverage, `--min-coverage PERCENT` to gate on a coverage floor, or read the JSON `recommendation` field for custom policy.
  742. ### Machine-readable output
  743. `--format json` produces a JSON report; with no `--output`/`-o` it is written to stdout:
  744. ```bash
  745. skillspector scan ./my-skill/ --format json
  746. ```
  747. The top-level shape is (this example shows a full LLM-backed scan; with `--no-llm`, `metadata.llm_requested` is `false`):
  748. ```json
  749. {
  750. "skill": { "name": "...", "source": "...", "scanned_at": "<ISO 8601>" },
  751. "risk_assessment": { "score": 0, "severity": "LOW", "recommendation": "SAFE" },
  752. "components": [ { "path": "...", "type": "...", "lines": 0, "executable": false, "size_bytes": 0 } ],
  753. "issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 }, "surface": "code" } ],
  754. "metadata": {
  755. "has_executable_scripts": false,
  756. "skillspector_version": "...",
  757. "llm_requested": true,
  758. "llm_available": true,
  759. "inference_usage": [
  760. {
  761. "node": "semantic_security_discovery",
  762. "request_kind": "structured_output",
  763. "provider": "nv_inference",
  764. "model": "azure/anthropic/claude-opus-4-6",
  765. "model_source": "provider_response",
  766. "usage_source": "provider_response",
  767. "prompt_tokens": 1000,
  768. "completion_tokens": 100,
  769. "cached_tokens": 400,
  770. "cache_write_tokens": 50,
  771. "total_tokens": 1100
  772. }
  773. ]
  774. }
  775. }
  776. ```
  777. - `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
  778. - `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mapped from severity: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
  779. - `issues[].surface` and `suppressed[].surface` are advisory, heuristic labels for where a finding landed:
  780. `code | instructions | docs | tests | comments | config`. JSON expands compacted groups into one `issues[]` entry
  781. per occurrence, each with its own `surface`; SARIF emits `properties.surface` on each result. The label is
  782. path/line-based and the scanned author can influence it, so do not use it as the sole suppression or security signal.
  783. - `metadata.llm_error` appears only when LLM analysis was requested but unavailable.
  784. - Archive-member components retain their virtual `path` and include `outer_path`, `nested_path`,
  785. and container provenance. Virtual paths identify in-memory members, not on-disk files; see
  786. [JSON component locations](docs/NESTED_ARTIFACT_INSPECTION.md#json-component-locations).
  787. - AE1 findings use **Incomplete referenced artifact analysis**. Their source
  788. location identifies the reference; `evidence` identifies the affected target,
  789. analyzer reasons, and available bounds. Review the target's completeness
  790. ledger when `reasons_truncated` is true. See
  791. [referenced-artifact diagnostics and Perl help text](docs/ANALYSIS_RESOURCE_BOUNDS.md#diagnosing-incomplete-referenced-artifacts)
  792. for interpretation and corrective actions.
  793. - `metadata.inference_usage` contains one sanitized record per LLM response when the
  794. provider exposes token counters. It is an empty list when usage is unavailable;
  795. SkillSpector never estimates missing tokens. Prompt totals are inclusive of cache
  796. reads and writes so downstream pricing can separate those partitions safely.
  797. `model_source` distinguishes an independently identified provider model from
  798. the exact requested model used when response identity is absent or ambiguous.
  799. SkillSpector does not currently send Anthropic prompt-cache controls, so its
  800. scan requests cannot select the separate 5-minute or 1-hour cache-write tiers;
  801. TTL-specific response fields are normalized defensively into the aggregate
  802. cache-write counter.
  803. - See [Inference usage telemetry](docs/INFERENCE_USAGE.md) for the complete
  804. provenance, cache-accounting, privacy, fail-closed ingestion, and downstream
  805. pricing contract.
  806. - The full per-issue shape is defined by `Finding.to_dict()` in [models.py](src/skillspector/models.py); rely on the fields above and treat any additional fields as best-effort.
  807. For CI/IDE tooling, `--format sarif` emits SARIF 2.1.0. Each result carries its
  808. security severity; rule descriptors carry a score only when all of their results
  809. share that severity. Mixed-severity rules remain unannotated, so consumers that
  810. read only rule-level severity cannot distinguish their result severities.
  811. Recursive scans chain each percent-encoded skill-directory URI through an
  812. absolute scan-root file URI. External dependency locations retain their source
  813. provenance instead of being rebased into the local skill directory.
  814. ### Recommended gate mapping
  815. When using SkillSpector as an install gate, map the recommendation to an action:
  816. | `recommendation` | Suggested action |
  817. |------------------|------------------|
  818. | `SAFE` | allow |
  819. | `CAUTION` | prompt / warn the user |
  820. | `DO_NOT_INSTALL` | block |
  821. 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.
  822. ## Development
  823. ### Setup
  824. This is the canonical setup recipe for contributing from this checkout. Use
  825. **Python 3.12-3.15** (`>=3.12,<3.16`, as defined in [pyproject.toml](pyproject.toml)),
  826. Git, and `make`. A release tag can have a different Python range; check that
  827. tag's metadata. The commands below use Bash or Zsh.
  828. With **uv** installed:
  829. ```bash
  830. git clone https://github.com/NVIDIA/skillspector.git
  831. cd skillspector
  832. uv venv --python 3.12 .venv
  833. source .venv/bin/activate
  834. make install-dev
  835. ```
  836. If uv is not installed, clone the repository and enter it as above, then use
  837. an installed supported Python interpreter with `venv` and pip:
  838. ```bash
  839. python3.12 -m venv .venv
  840. source .venv/bin/activate
  841. make install-dev
  842. ```
  843. Create and activate the virtual environment before running any `make` target.
  844. `make install-dev` uses `uv sync --all-extras` when uv is available, otherwise
  845. `pip install -e ".[dev]"`.
  846. Start with these local checks:
  847. ```bash
  848. make test-unit
  849. make lint
  850. make format-check
  851. ```
  852. `make test-unit` excludes tests marked `integration` or `provider`. This selection
  853. does not cover every CI job or guarantee network isolation.
  854. Some unit tests start loopback HTTP servers and local multiprocessing sockets.
  855. Restricted agent sandboxes can deny these operations. Keep the failing
  856. command and traceback, and use an appropriately permitted environment for a
  857. diagnostic rerun. Report that result separately; a passing subset does not make
  858. the original full target pass. See the
  859. [contributor onboarding check](docs/validation/CONTRIBUTOR_ONBOARDING.md).
  860. Before submitting a PR, [CONTRIBUTING.md](CONTRIBUTING.md#how-to-contribute)
  861. requires `make test`. It runs both `test-unit` and `test-integration`; integration
  862. tests invoke the full graph and may send test content to a configured LLM provider.
  863. Review the [provider configuration](docs/DEVELOPMENT.md#10-environment-and-configuration)
  864. and credentials or local-service prerequisites before running it:
  865. ```bash
  866. make test
  867. ```
  868. `make test-provider` makes live provider requests and requires the corresponding
  869. provider configuration; see [Live provider tests](docs/DEVELOPMENT.md#live-provider-tests).
  870. `make test-cov` runs the same marker-filtered selection as `test-unit`, with coverage.
  871. `make format` applies lint fixes and formats files **in place**. Run it before
  872. committing when changes are needed, review the diff, then recheck with `make lint`
  873. and `make format-check`.
  874. ## How It Works
  875. SkillSpector uses a two-stage detection pipeline:
  876. ### Stage 1: Static Analysis
  877. - Fast regex-based pattern matching across 11 static analyzers
  878. - AST-based behavioral analysis detecting dangerous calls (exec, eval, subprocess, etc.)
  879. - Live vulnerability lookups via OSV.dev for known CVEs in dependencies
  880. - Scans all analyzer-eligible files in the skill
  881. - High recall (catches most issues)
  882. - Moderate precision (some false positives)
  883. OpenSSF Model Signing / DSSE bundles remain in content analysis, regardless of
  884. filename. Static and LLM analyzers inspect decoded JSON payloads, readable DER
  885. certificate/signature content, and all unknown wrapper fields. Strictly parsed
  886. binary fields are projected rather than treated as executable base64; canonical
  887. bytes remain available to YARA and fingerprints. Unsupported encodings (including
  888. environments without the optional `cryptography` dependency) retain raw fields
  889. and produce an explicit incomplete-analysis warning. Findings in decoded content
  890. point to the original bundle and label their projection in evidence. None of this
  891. verifies signatures, certificate chains, transparency logs, or signer identity.
  892. ### Stage 2: LLM Semantic Analysis (Optional)
  893. - Evaluates context and intent
  894. - Confirmed findings may gain an explanation and higher confidence, never lower
  895. - Every deterministic finding stays in the report whether the model confirms it, disputes it, or does not address it
  896. - Findings the model reviews but does not confirm (disputed, low-confidence, or unaddressed) are tagged `llm-unconfirmed` in JSON and SARIF output
  897. - Findings whose review fails are kept without that tag; `evidence.llm_review_outcome` distinguishes `confirmed`, `disagreed`, `low-confidence`, `missing`, and `failed` in JSON and SARIF output
  898. - Results depend on the configured model and prompt context; Stage 2 does not replace
  899. deterministic findings or guarantee a particular precision rate
  900. The LLM prompt includes anti-jailbreak protections to prevent malicious skills from manipulating the analysis.
  901. ## Live Vulnerability Lookups (SC4)
  902. SC4 uses the [OSV.dev](https://osv.dev) API to check dependencies against the full Open Source Vulnerabilities database — covering tens of thousands of advisories across PyPI and npm.
  903. - **No API key required** — OSV.dev is free and unauthenticated.
  904. - **Batch queries** — all dependencies are checked in a single HTTP call.
  905. - **Automatic fallback** — if OSV.dev is unreachable (air-gapped/offline), a small built-in fallback list is used.
  906. - **Caching** — results are cached in-memory for 1 hour to avoid redundant API calls during a session.
  907. - **Pipenv** — reads `Pipfile` package tables and the direct/transitive packages in
  908. `Pipfile.lock`, including development and custom categories. Exact lock versions
  909. can resolve unpinned manifest dependencies. Malformed entries and unsupported
  910. VCS/local sources are reported as incomplete dependency checks.
  911. The tool requires outbound HTTPS access to `api.osv.dev` for live vulnerability data. When that is not available, findings are limited to the static fallback list.
  912. ## Locked npm dependency contents (opt-in)
  913. Use `--inspect-dependencies` to statically inspect exact public npm tarballs from
  914. `package-lock.json` or `npm-shrinkwrap.json` v2/v3, including recorded transitive,
  915. development, and optional dependencies:
  916. ```bash
  917. skillspector scan ./my-skill --inspect-dependencies --no-llm --fail-on-incomplete
  918. ```
  919. Artifacts must match their locked SHA-512 integrity hashes. A disposable Linux
  920. worker inspects supported source files and decoded npm scripts without installing
  921. packages or executing their code. Dependency findings include package coordinates,
  922. an artifact digest, and source locations. Missing artifacts, unsupported sources
  923. or formats, unavailable isolation, and exhausted budgets remain incomplete;
  924. `--fail-on-incomplete` prevents them from passing the scan. Reports also show when
  925. inspection was not requested.
  926. This first version supports the public npm registry and Linux x86-64/AArch64
  927. seccomp isolation. Dependency analysis stays local and uses existing static
  928. data-exfiltration, privilege-escalation, and supply-chain patterns. See
  929. [supported content, resource limits, and coverage boundaries](docs/DEPENDENCY_CONTENT_INSPECTION.md).
  930. ## Trust model and data egress
  931. SkillSpector is defense-in-depth, not a sandbox. Know what it does and does not do before relying on it:
  932. - **It never executes the scanned skill.** All analysis is static (regex, Python AST, YARA) plus optional LLM evaluation of file *contents* — the skill's code is never run.
  933. - **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. DSSE payloads and readable signing metadata are included. Use `--no-llm` to keep contents local (static analysis only).
  934. - **SC4 sends dependency names to OSV.dev.** The supply-chain check queries [OSV.dev](https://osv.dev) with the package names and versions 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.
  935. - **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.
  936. ## Limitations
  937. - **Non-English content**: May miss patterns in other languages
  938. - **Image-based attacks**: Cannot analyze text in images
  939. - **Encrypted/binary code**: Cannot analyze compiled or encrypted content
  940. - **Runtime behavior**: Static analysis only, no dynamic execution
  941. - **Offline SC4**: Without network access to `api.osv.dev`, SC4 uses a small static fallback list
  942. ## Research Background
  943. Based on research from "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026):
  944. - **Dataset**: 42,447 skills from major marketplaces; 31,132 were analyzed for the following rates
  945. - **Vulnerable**: 26.1% of the analyzed subset contain at least one vulnerability
  946. - **High-severity**: 5.2% of the analyzed subset show likely malicious intent
  947. - **Key finding**: Skills with executable scripts are 2.12x more likely to be vulnerable
  948. ## Python API Integration
  949. ```python
  950. from skillspector import graph
  951. # Invoke the LangGraph workflow
  952. result = graph.invoke({
  953. "input_path": "/path/to/skill",
  954. "output_format": "json", # terminal, json, markdown, or sarif
  955. "use_llm": True, # False for static-only analysis
  956. })
  957. # Access results
  958. print(f"Risk Score: {result['risk_score']}/100")
  959. print(f"Severity: {result['risk_severity']}")
  960. print(f"Recommendation: {result['risk_recommendation']}")
  961. for finding in result["filtered_findings"]:
  962. print(f"[{finding['severity']}] {finding['rule_id']}: {finding['message']}")
  963. ```
  964. ## License
  965. Apache License 2.0 - see [LICENSE](LICENSE) for details.
  966. ## Contributing
  967. Report suspected security vulnerabilities, including vulnerabilities in SkillSpector
  968. itself, privately to NVIDIA PSIRT by following [SECURITY.md](SECURITY.md). Do not
  969. report them through GitHub issues, pull requests, or Discussions.
  970. Contributions are welcome! Please read our contributing guidelines and submit pull requests.
  971. ## Support
  972. - **Security vulnerabilities**: Follow [SECURITY.md](SECURITY.md) to report privately
  973. to NVIDIA PSIRT. Do not report them through GitHub issues, pull requests, or Discussions.
  974. - **Issues**: [GitHub Issues](https://github.com/NVIDIA/skillspector/issues) for
  975. non-security bugs, false positives, and feature requests. Use minimal, sanitized reproductions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.