MojeebAlmahmoudi/webguard-scanner

# 🛡️ WebGuard Scanner [](https://www.python.org/) [](https://flask.palletsprojects.com/) [](https://sqlite.org/) [](https://opensource.org/licenses/MIT) 一款完全基于 **Python 3.11+** 从头构建的先进、模块化且高性能的 Web 漏洞扫描器。它具备全面的基于终端的命令行界面 (CLI) 和一个时尚、响应式的深色主题仪表板（Flask Web 应用程序），用于管理漏洞审计生命周期。 أداة فحص أمنية متقدمة، نموذجية، وعالية الأداء تم تطويرها بالكامل باستخدام لغة **بايثون 3.11+**. تتميز الأداة بوجود واجهة سطر أوامر تفاعلية (CLI) وواجهة مستخدم ويب حديثة (Flask) لمتابعة وإدارة دورة حياة الفحص واكتشاف الثغرات الأمنية بشكل فوري. ## 📖 目录 * [项目描述](#project-description--وصف-المشروع) * [合规与负责任的使用声明](#responsible-use--الاستخدام-المسؤول-والتعهد-القانوني) * [功能与模块](#features--modules--المميزات-والوحدات) * [技术栈](#tech-stack--التقنيات-المستخدمة) * [项目结构](#project-tree--شجرة-المجلدات) * [安装与配置](#installation--التثبيت-والتهيئة) * [通过命令行使用 (CLI)](#cli-usage--الاستخدام-عبر-سطر-الأوامر) * [通过 Web 界面使用](#web-app-usage--الاستخدام-عبر-واجهة-الويب) * [通过 Docker 运行](#docker-containerization--التشغيل-عبر-docker) * [经验总结](#lessons-learned--الدروس-المستفادة) * [开源许可](#license--الترخيص-المعتمد) ## 📝 项目描述 开发 **WebGuard Scanner** 旨在展示应用于网络安全工具的专业软件设计原则。它利用了标准的异步工作流、数据库 ORM 模型、清晰的模板和模块化的设计模式。它可以帮助开发人员和工程师审计其目标应用程序中属于 OWASP 类别的顶级安全漏洞。 تم تطوير **WebGuard Scanner** ليكون نموذجًا برمجيًا احترافيًا يبرز كيفية تصميم البرمجيات وهندسة الأدوات الأمنية. يعتمد المشروع على أساليب البرمجة المتزامنة (Asynchronous Execution)، ونموذج طبقة البيانات (ORM) الحديث، وفصل الكود البرمجي بمرونة نموذجية لتسهيل الصيانة والتطوير. يتيح لك فحص تطبيقات الويب الخاصة بك واكتشاف أهم الثغرات الموصى بها في معايير OWASP العالمية. ## ⚠️ 合规与负责任的使用声明 ## ✨ 功能与模块 扫描流水线按以下顺序协调审计执行： التسلسل البرمجي لتنفيذ عمليات الفحص يتبع الترتيب الآتي: $$\text{Crawler} \longrightarrow \text{HTTP Headers} \longrightarrow \text{XSS Scanner} \longrightarrow \text{SQL Injection} \longrightarrow \text{Port Scanner} \longrightarrow \text{Database} \longrightarrow \text{HTML Report}$$ 1. **Web 爬虫与表单发现器**：使用标准的广度优先搜索 (BFS) 来映射域名页面，并发现所有输入框和表单字段。 2. **HTTP Headers 审计器**：检查响应头的合规性（标记缺失的 `Content-Security-Policy`、`X-Frame-Options`、`Strict-Transport-Security` 等）并评估严重性等级。 3. **反射型 XSS 扫描器**：使用独特的检测标记和验证签名，对发现的输入参数进行安全注入检查。 4. **基于错误的 SQL 注入**：执行非破坏性的数据库审计检查，寻找 SQL 语法引擎错误（支持 MySQL、PostgreSQL、Oracle、SQLite、MSSQL）。 5. **开放端口扫描器**：使用 `python-nmap` 封装行业标准工具 **Nmap** 来审计服务、开放的 TCP 端口和版本名称。 6. **SQLite 持久化**：使用 SQLAlchemy ORM 安全地保存扫描日志、持续时间、状态变更和发现的漏洞。 7. **HTML 报告生成器**：使用 Jinja2 模板生成详细的响应式可视化报告文档，并将其存储在 `reports/output/` 目录下。 ## 🛠️ 技术栈 - **核心逻辑**：Python 3.11+、Socket 编程、SSL 库、Beautiful Soup 4、Requests。 - **数据库 (ORM)**：SQLAlchemy 2.0+（声明式基类、作用域 Session）。 - **Web 应用 UI**：Flask（Blueprints、Request Contexts、多线程）。 - **样式设计**：原生 CSS、Bootstrap 5（响应式深色 UI 布局）。 - **系统集成**：Python-Nmap、WeasyPrint PDF 转换。 - **测试套件**：Pytest（目标测试覆盖率为 100%，拥有超过 **390+ 个通过的单元测试**）。 - **容器化**：Docker（最小化的 Debian slim 占用空间）。 ## 📁 项目结构 ``` webguard-scanner/ ├── core/ # Security scanner modules │ ├── __init__.py │ ├── crawler.py # BFS Crawler and form parser │ ├── sql_injection.py # Error-based SQLi scanner │ ├── xss_scanner.py # Reflected XSS scanner │ ├── header_checker.py # Security headers compliance checker │ ├── port_scanner.py # python-nmap targeted port scanner │ ├── ssl_checker.py # SSL/TLS validation & fallback parser │ └── orchestrator.py # Sequential pipeline coordinator ├── database/ # Database persistence layer │ ├── __init__.py │ ├── db.py # Engine connection & scoped session context │ └── models.py # Scan and Finding ORM models ├── reports/ # Visual report generation │ ├── __init__.py │ ├── templates/ # Jinja2 HTML design template │ │ └── report.html │ └── report_generator.py # HTML to disk builder & PDF stub ├── web/ # Dashboard Web Interface │ ├── app.py # Flask app factory, blueprints & background threads │ ├── templates/ # Layout views (scan, results, history, error) │ │ ├── base.html │ │ ├── scan.html │ │ ├── results.html │ │ ├── history.html │ │ └── error.html │ └── static/ # Assets (CSS styles, JS polling scripts) ├── tests/ # Standard testing directory (390+ test cases) ├── Dockerfile # Production deployment image settings ├── requirements.txt # PIP dependencies ├── .gitignore # Git ignored configurations └── main.py # CLI client entrypoint ``` ## 📥 安装与配置 ### 前置条件 * Python 3.11 或更高版本。 * 在本地操作系统的 PATH 中安装 Nmap 二进制文件。 * *Windows:* 从 [nmap.org](https://nmap.org/download.html) 安装 Nmap，并将其添加到系统的 PATH 环境变量中。 * *Linux:* `sudo apt-get install nmap` ### 步骤设置 ``` # Clone 仓库 git clone https://github.com/your-username/webguard-scanner.git cd webguard-scanner # 创建并激活 virtual environment python -m venv .venv # 在 Windows 上 .venv\Scripts\activate # 在 Linux & macOS 上 source .venv/bin/activate # 安装依赖 pip install -r requirements.txt ``` ## 💻 通过命令行使用 (CLI) 使用 `main.py` 入口点从终端运行标准审计。 قم بتشغيل الفحص التفاعلي مباشرة من شاشة الـ Terminal: ``` # 使用默认参数（depth=2，output=html）进行标准运行 python main.py --target https://example.com # 自定义 crawler 深度并启用详细日志记录（DEBUG 输出） python main.py --target https://example.com --depth 3 --verbose # 将输出报告格式更改为 json python main.py --target https://example.com --output json ``` ## 🌐 通过 Web 界面使用 在本地启动 Flask 仪表板服务器： ابدأ تشغيل لوحة التحكم وواجهة المستخدم للويب محلياً: ``` # 启动 Flask 服务器 python web/app.py ``` * 在浏览器中访问：**`http://localhost:5000`** * **新建扫描**：输入目标 URL，选择模块，然后启动。 * **结果视图**：使用客户端 JavaScript 轮询实时自动更新。 * **扫描历史**：查看过去的审计记录，并直接下载最终的 HTML 报告。 ## 🐳 通过 Docker 运行 无需任何系统依赖。Nmap 已预先打包在 Docker 容器中。 لا يتطلب هذا الخيار تثبيت أي أدوات في جهازك، حيث يتم تشغيل Nmap تلقائياً بداخل بيئة الحاوية: ``` # 1. 构建 Docker image docker build -t webguard-scanner . # 2. 运行映射 Flask 端口 5000 的 Container docker run -d -p 5000:5000 --name webguard-running webguard-scanner ``` 访问 `http://localhost:5000` 立即开始扫描。 ## 🧪 测试覆盖率 运行综合测试套件以验证应用程序逻辑： ``` python -m pytest tests/ -v ``` ## 💡 经验总结 1. **C 扩展中的后备逻辑**：在审计 SSL/TLS endpoint 时，不受信任/自签名的证书会导致标准 Python 握手失败。使用内部 C 扩展 `_ssl` 实现后备 DER 字节提取，可确保诊断检查程序即使在验证失败的情况下也能提取信息。 2. **多线程中的作用域事务**：如果未进行隔离，Flask 中的后台扫描线程可能会导致数据库句柄泄漏。实现 SQLAlchemy 作用域上下文管理器 `get_session` 可以保证数据库的提交/回滚安全地清理句柄。 3. **优雅的 Nmap 验证**：由于 Nmap 作为外部 OS 二进制文件运行，封装器会事先检查系统 PATH 的可用性，并以信息性警告作为后备优雅地处理，而不是直接崩溃。 ## 📄 开源许可 本项目基于 MIT License 开源 - 详情请参阅 [LICENSE](LICENSE) 文件。 جميع الأكواد تخضع لترخيص MIT المفتوح المصدر.

标签：CISA项目, DOE合作, Flask, Python, SQLite, Web漏洞扫描器, 无后门, 请求拦截, 逆向工具