SkillSpector 详细部署教程

SkillSpector 是 NVIDIA 开源的一款 AI Agent 技能安全扫描器，用于在安装 Claude Code、Codex 等 Agent 技能前检测漏洞、恶意模式、提示注入和数据外泄风险。本教程将涵盖三种部署方式：uv 工具安装、源码安装和 Docker 部署。

一、环境准备

前置条件

  • Python 3.12+（Docker 方式无需本地 Python）
  • uv 包管理器（推荐）或 pip
  • Docker（仅 Docker 方式需要）

安装 uv（如未安装）

1
2
3
4
5
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

二、方式一：uv 工具安装（推荐，最简洁）

这种方式将 SkillSpector 作为全局 CLI 工具安装，适合日常快速扫描使用。

纯 CLI 安装

1
uv tool install git+https://github.com/NVIDIA/skillspector.git

安装完成后可直接使用 skillspector 命令。

含 MCP 支持的安装

如果你计划将 SkillSpector 作为 MCP 服务器运行（供 Claude Code 等 Agent 调用），需要安装 mcp 附加依赖：

1
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

更新工具

1
uv tool update skillspector

验证安装

1
skillspector scan --help

三、方式二：源码安装（适合开发与定制）

源码安装适合需要修改代码、扩展分析器或进行二次开发的场景。

1. 克隆仓库并创建虚拟环境

1
2
3
4
5
6
7
8
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# 使用 uv 创建虚拟环境
uv venv .venv && source .venv/bin/activate

# 或使用标准 venv
python3 -m venv .venv && source .venv/bin/activate

2. 安装依赖

1
2
3
4
5
# 生产使用
make install

# 开发使用（含测试、lint 等工具）
make install-dev

Makefile 会优先使用 uv，若不可用则回退到 pip。

3. 验证

1
skillspector scan --help

四、方式三：Docker 部署（无需 Python）

Docker 方式适合不希望在本机安装 Python 环境的场景，也适合 CI/CD 流水线集成。

1. 构建镜像

1
2
3
make docker-build
# 或
docker build -t skillspector .

镜像基于官方 python:3.12-slim-bookworm 构建。

2. 基础扫描（仅静态分析）

将当前目录挂载到容器的 /scan 工作目录：

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

3. 带 LLM 分析的扫描

方式 A：使用 .env 文件

1
2
3
4
5
6
7
8
9
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/

方式 B：直接传递环境变量

1
2
3
4
5
docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

4. 输出报告到宿主机

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

报告文件 report.json 将写入当前目录。

5. 创建别名（可选）

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

6. 边缘/资源受限环境优化

在资源受限设备上运行时，可限制资源并禁用 LLM：

1
2
3
4
5
6
7
8
docker run --rm \
  --memory=512m \
  --cpus=1 \
  -v "$PWD:/scan" \
  skillspector scan ./skill-directory/ \
  --no-llm \
  --format json \
  --output report.json

五、LLM 分析配置（可选但推荐）

启用 LLM 语义分析后，SkillSpector 能过滤误报并提供人类可读的解释，精度可提升至约 87%。

选择 Provider

SkillSpector 支持多种 LLM 提供商，通过 SKILLSPECTOR_PROVIDER 环境变量切换：

Provider 凭证环境变量 默认模型
openai OPENAI_API_KEY gpt-5.4
anthropic ANTHROPIC_API_KEY claude-opus-4-6
ollama 无需 llama3.1:8b
nv_build NVIDIA_INFERENCE_KEY z-ai/glm-5.2
claude_cli 使用本地 CLI 登录 本地 Claude 运行时

常用配置示例

使用 Anthropic：

1
2
3
export SKILLSPECTOR_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
skillspector scan ./my-skill/

使用本地 Ollama（完全离线）：

1
2
3
export SKILLSPECTOR_PROVIDER=ollama
export SKILLSPECTOR_MODEL=llama3.1:8b
skillspector scan ./my-skill/

使用 Claude CLI（无需 API Key）：

1
2
3
# 需先安装并登录 claude CLI：claude auth login
export SKILLSPECTOR_PROVIDER=claude_cli
skillspector scan ./my-skill/

跳过 LLM 分析

如果只需要快速静态扫描：

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

六、MCP 服务器部署（用于 Agent 运行时防护）

将 SkillSpector 作为 MCP 服务器运行，让 Agent 在安装技能前自动调用扫描，实现运行时防护。

1. 安装 MCP 支持

1
uv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

2. 启动 MCP 服务器

stdio 传输（本地 CLI Agent）：

1
skillspector mcp

HTTP 传输（远程调用）：

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

安全提醒：HTTP 传输默认无认证。任何能访问该端口的调用者都可执行扫描。如需暴露到网络，务必置于认证反向代理之后。HTTP 模式会自动拒绝本地路径和 file:// URL，仅接受远程 Git 和 .zip URL。

3. 注册到 Claude Code

1
claude mcp add skillspector -- skillspector mcp

七、CI/CD 集成

SkillSpector 的退出码和 JSON/SARIF 输出是稳定契约，便于集成到流水线中。

退出码含义

退出码 含义
0 扫描完成，风险分 ≤ 50（SAFE 或 CAUTION）
1 扫描完成，风险分 > 50（DO_NOT_INSTALL）
2 错误（输入无效、源不可读等）

GitHub Actions 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
name: Security Scan
on:
  push:
    paths: ['skills/**']
  pull_request:
    paths: ['skills/**']

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install SkillSpector
        run: pip install git+https://github.com/NVIDIA/SkillSpector

      - name: Scan skills
        run: |
          skillspector scan ./skills --no-llm \
            --format sarif --output skillspector.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: skillspector.sarif

八、常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 扫描本地目录
skillspector scan ./my-skill/

# 扫描单个文件
skillspector scan ./SKILL.md

# 扫描 Git 仓库
skillspector scan https://github.com/user/my-skill

# 扫描 zip 文件
skillspector scan ./my-skill.zip

# JSON 输出
skillspector scan ./my-skill/ --format json --output report.json

# Markdown 输出
skillspector scan ./my-skill/ --format markdown --output report.md

# SARIF 输出（CI/IDE 集成）
skillspector scan ./my-skill/ --format sarif --output report.sarif

# 仅静态分析（快，离线可用）
skillspector scan ./my-skill/ --no-llm

# 生成基线（抑制已知误报）
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml

# 基于基线扫描（仅报告新问题）
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

九、故障排查

问题 可能原因 解决方案
skillspector: command not found PATH 未包含 uv 工具目录 运行 uv tool update-shell 或手动添加 ~/.local/bin 到 PATH
MCP 初始化挂起 FastMCP stdio 传输已知问题 检查 issue #199
LLM 分析返回空结果 API Key 无效或额度耗尽 检查环境变量，或临时使用 --no-llm
Docker 扫描时找不到文件 挂载路径不正确 确保使用 -v "$PWD:/scan" 并扫描 /scan 下的相对路径
SC4 漏洞查询失败 无法访问 api.osv.dev 离线环境会自动回退到内置列表，无网络时仍可用静态分析

以上三种部署方式可根据实际场景灵活选择：日常使用推荐 uv 工具安装，开发定制选源码安装，隔离环境或 CI 流水线用 Docker。部署完成后，建议先对已有的技能目录执行一次 --no-llm 快速扫描，了解当前技能生态的安全状况，再根据需要配置 LLM 分析和 CI 集成。