minidu-lab/cybershield-oss

CyberShield OSS
AI-Assisted Cybersecurity Scanner & Developer Education Platform

## 什么是 CyberShield OSS？ CyberShield OSS 是一款**免费、开源**的网络安全扫描器，利用 AI 让每个人都能理解漏洞报告。它扫描 Web 应用程序中的常见漏洞，并使用 **Claude by Anthropic** 生成清晰、通俗易懂的英文说明以及可操作的修复指导。 ### 适用人群 - **独立开发者**，负担不起 Snyk、Burp Suite 或 Veracode 等企业级安全工具 - **网络安全学生**，需要进行真实漏洞的实践练习 - **开源项目维护者**，希望保持其项目的安全性 ## 功能特性 | 功能 | 描述 | |---------|-------------| | **XSS Scanner** | 检测反射型和存储型跨站脚本攻击 (XSS) 漏洞 | | **SQL Injection Scanner** | 识别查询参数和表单中的 SQL 注入点 | | **CSRF Scanner** | 检查缺失或弱 CSRF token 防护 | | **Auth Scanner** | 检测失效的身份认证模式（弱会话、缺失头部） | | **API Key Scanner** | 查找源代码和响应中暴露的 API key、token 和机密信息 | | **AI Explanations** | Claude 驱动的通俗易懂的漏洞报告 | | **Security Tutor** | 用于学习安全概念的交互式聊天界面 | | **HTML/JSON Reports** | 以多种格式导出扫描结果 | | **CI/CD Integration** | 用于自动化扫描的 GitHub Actions 工作流 | ## 快速开始 ### 安装 ``` # 克隆 repository git clone https://github.com/minidu-lab/cybershield-oss.git cd cybershield-oss # 创建 virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # 安装 dependencies pip install -r requirements.txt # 以 development mode 安装 pip install -e . ``` ### 配置 在项目根目录下创建一个 `.env` 文件： ``` ANTHROPIC_API_KEY=your_api_key_here CYBERSHIELD_LOG_LEVEL=INFO CYBERSHIELD_MAX_CONCURRENT=5 CYBERSHIELD_TIMEOUT=30 ``` ### 使用方法 #### 命令行扫描器 ``` # 基础 scan cybershield scan https://example.com # 使用所有 modules 进行完整 scan cybershield scan https://example.com --modules all # Scan 特定 vulnerabilities cybershield scan https://example.com --modules xss,sqli,csrf # 生成包含 AI 解释的 HTML report cybershield scan https://example.com --report html --ai-explain # 导出 JSON report cybershield scan https://example.com --report json -o results.json ``` #### Security Tutor (交互模式) ``` # 启动 interactive security tutor cybershield tutor # 询问特定 vulnerability cybershield tutor --topic "SQL injection" ``` #### Python API ``` from cybershield import CyberShield # 初始化 scanner scanner = CyberShield(api_key="your_anthropic_api_key") # 运行 scan results = scanner.scan("https://example.com", modules=["xss", "sqli", "csrf"]) # 获取 AI 驱动的解释 for vuln in results.vulnerabilities: explanation = vuln.explain() # Uses Claude API print(f"[{vuln.severity}] {vuln.title}") print(f" → {explanation.summary}") print(f" → Fix: {explanation.remediation}") ``` ## 系统架构 ``` cybershield-oss/ ├── cybershield/ # Main package │ ├── __init__.py # Package init & version │ ├── cli.py # CLI entry point (Click) │ ├── core.py # Core scanner orchestrator │ ├── config.py # Configuration management │ ├── scanners/ # Vulnerability scanner modules │ │ ├── __init__.py │ │ ├── base.py # Base scanner class │ │ ├── xss.py # XSS detection │ │ ├── sqli.py # SQL injection detection │ │ ├── csrf.py # CSRF detection │ │ ├── auth.py # Authentication issues │ │ └── api_keys.py # Exposed secrets detection │ ├── ai/ # Claude AI integration │ │ ├── __init__.py │ │ ├── client.py # Anthropic API client wrapper │ │ ├── explainer.py # Vulnerability explanation pipeline │ │ └── tutor.py # Interactive security tutor │ ├── reports/ # Report generation │ │ ├── __init__.py │ │ ├── base.py # Base report class │ │ ├── html.py # HTML report generator │ │ └── json_report.py # JSON report generator │ └── utils/ # Utilities │ ├── __init__.py │ ├── http.py # HTTP request helpers │ ├── logger.py # Logging configuration │ └── validators.py # Input validation ├── tests/ # Test suite │ ├── __init__.py │ ├── conftest.py # Pytest fixtures │ ├── test_scanners.py # Scanner unit tests │ ├── test_ai.py # AI integration tests │ └── test_cli.py # CLI tests ├── examples/ # Usage examples │ ├── basic_scan.py │ └── custom_scanner.py ├── docs/ # Documentation │ └── SECURITY.md # Security policy ├── .github/ # GitHub configuration │ ├── workflows/ │ │ └── ci.yml # CI/CD pipeline │ └── ISSUE_TEMPLATE/ │ ├── bug_report.md │ └── feature_request.md ├── .env.example # Environment variable template ├── .gitignore # Git ignore rules ├── LICENSE # MIT License ├── CONTRIBUTING.md # Contribution guidelines ├── CODE_OF_CONDUCT.md # Code of conduct ├── pyproject.toml # Project metadata & build config ├── requirements.txt # Python dependencies └── setup.py # Setup script ``` ## 漏洞严重性级别 | 级别 | 颜色 | 描述 | |-------|-------|-------------| | **CRITICAL** | 🔴 | 存在立即被利用的风险，极有可能发生数据泄露 | | **HIGH** | 🟠 | 风险较高，应在部署前修复 | | **MEDIUM** | 🟡 | 风险中等，应在下一个版本中解决 | | **LOW** | 🟢 | 风险较低，属于最佳实践改进 | | **INFO** | 🔵 | 信息性发现，无直接风险 | ## Claude AI 集成 CyberShield 使用 **Claude by Anthropic** 实现两个核心功能： ### 1. 漏洞解释流水线 原始扫描器输出 → Claude API → 开发者友好的报告 ``` Scanner finds: "Reflected XSS in parameter 'q' at /search?q=" ↓ Claude generates: "Your search page at /search is vulnerable to Cross-Site Scripting (XSS). An attacker could inject malicious JavaScript through the 'q' parameter, which gets reflected back in the page without sanitization. This could allow session hijacking, credential theft, or defacement. To fix this: 1. Sanitize the 'q' parameter using html.escape() before rendering 2. Add Content-Security-Policy headers 3. Use a templating engine with auto-escaping (e.g., Jinja2)" ``` ### 2. Security Tutor Chat 一种交互式学习模式，学生可以询问有关漏洞的问题： ``` Student: "Why is SQL injection dangerous even with a firewall?" Claude: "Great question! A firewall protects your network perimeter, but SQL injection happens at the application layer — inside the firewall. When a user submits data through a form, it goes directly to your database query. If that input isn't sanitized, an attacker can modify the query itself..." ``` ## 贡献指南 我们欢迎各种形式的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ### 开发环境设置 ``` # 安装 development dependencies pip install -r requirements.txt pip install -e ".[dev]" # 运行 tests pytest tests/ -v # 运行 linting flake8 cybershield/ black cybershield/ --check # 运行 type checking mypy cybershield/ ``` ## 路线图 - [x] 核心漏洞扫描器 (XSS, SQLi, CSRF, Auth, API Keys) - [x] Claude AI 解释流水线 - [x] CLI 界面 - [x] HTML/JSON 报告生成 - [x] 交互式安全辅导聊天 - [ ] 用于实时扫描的浏览器扩展 - [ ] REST API 服务器模式 - [ ] Docker 容器支持 - [ ] 用于自定义扫描器的插件系统 - [ ] Dashboard Web UI ## 更新日志 ### v0.2.0 (2026年3月) - 由 Claude 驱动的交互式 Security Tutor，支持多轮对话 - 真实的 XSS payload 注入测试，包含表单字段和 header 扫描 - 真实的 SQL 注入检测（基于错误、基于布尔、基于时间盲注） - 专业的深色主题 HTML 报告输出，包含发现结果表格 - 改进的 CLI 用户体验，带有按严重性着色的输出 - 更好的 API 超时错误处理 ### v0.1.0 (2026年3月) - 包含核心架构的初始版本 - Claude AI 解释流水线 - 带有 scan 和 tutor 命令的 CLI 界面 - 5 个漏洞扫描器 (XSS, SQLi, CSRF, Auth, API Keys) - HTML 和 JSON 报告生成 ## 许可证 本项目采用 MIT 许可证授权 —— 详见 [LICENSE](LICENSE) 文件。 ## 致谢 - **[Anthropic](https://anthropic.com)** — 提供 AI 驱动解释的 Claude API - **[OWASP](https://owasp.org)** — 漏洞分类标准 - 开源安全社区

用 ❤️ 为全世界的开发者和网络安全学生构建
_{特别献给那些身处发展中地区、访问安全工具受限的朋友们}

标签：API密钥泄露, CISA项目, Claude API, CSRF, Homebrew安装, LNA, Python, Web安全, XSS检测, 人工智能, 加密, 多模态安全, 安全规则引擎, 开发者教育, 开源安全工具, 无后门, 漏洞扫描器, 用户模式Hook绕过, 网络安全, 蓝队分析, 逆向工具, 逆向工程平台, 防御指南, 隐私保护