adnandudhwala010/SentinelPDF

# 🛡️ SentinelPDF **企业级 PDF 恶意软件分析与威胁情报平台** SentinelPDF 是一个专业的基于 Web 的平台，用于**静态 PDF 恶意软件分析**。它允许 SOC 分析师、DFIR 团队和安全研究人员上传 PDF 文档并接收详细的威胁评估 —— **全程无需执行该文件**。 ## ✨ 核心功能 - 🔍 **深度静态分析** — 结合 PyMuPDF、pikepdf 和 pdfminer.six，检查完整的 PDF 对象图、流和元数据。 - 🐛 **YARA 签名检测** — 精选的规则集可标记已知的漏洞利用模式、混淆的 JavaScript、嵌入式可执行文件和 shellcode 特征。 - 📊 **熵与启发式评分** — 结合 Shannon 熵分析与透明、可解释的 0–100 加权风险评分引擎。 - 🌐 **威胁情报丰富化** — 可选的 VirusTotal 和 URLHaus 查询（hash/URL 信誉），在没有 API 密钥时可优雅降级。 - 📄 **多格式报告** — 导出适用于 DFIR 的报告，支持 PDF (ReportLab)、JSON、CSV 或 TXT 格式。 - 🔐 **安全加固平台** — CSRF 防护、凭证哈希、账户锁定、IDOR 防护、magic-byte 文件验证、随机化存储文件名。 - 📈 **分析师仪表板** — 基于 Chart.js 的判定结果分布和扫描历史记录。 ## 🧱 技术栈 | 层级 | 技术 | |---|---| | 前端 | HTML5, CSS3, Bootstrap 5, JavaScript (ES6), Chart.js, Font Awesome, AOS | | 后端 | Python 3.12+, Flask, Flask Blueprints, Flask-SQLAlchemy, Flask-WTF, Flask-Login | | 数据库 | SQLite (开发环境) → PostgreSQL (生产环境，零代码修改) | | PDF 分析 | PyMuPDF (fitz), pdfminer.six, pikepdf | | 恶意软件检测 | YARA (yara-python), Shannon 熵分析, 启发式评分引擎 | | 威胁情报 | VirusTotal API v3, URLHaus API (均为可选) | | 报告生成 | ReportLab, JSON, CSV, TXT | | 部署 | Docker, Gunicorn, Nginx | ## 📁 项目结构 ``` sentinelpdf/ ├── app/ │ ├── __init__.py # Application factory │ ├── extensions.py # db, login_manager, csrf, migrate │ ├── models/ # User, Scan, ScanFinding, Report │ ├── auth/ # Registration, login, logout │ ├── dashboard/ # Analyst dashboard & landing page │ ├── scanner/ # Upload, analysis engines, results │ ├── reports/ # PDF/JSON/CSV/TXT report generation │ ├── rules/ # YARA ruleset │ ├── static/ # CSS, JS │ ├── templates/ # Jinja2 templates │ └── utils/ # File validation, decorators ├── tests/ # Pytest suite ├── docker/ # Dockerfile, compose, nginx ├── docs/ # Documentation ├── requirements.txt ├── config.py ├── run.py # Local dev entry point └── wsgi.py # Production entry point (Gunicorn) ``` 请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 了解有关分析 pipeline 和数据流的详细说明。 ## 🚀 快速开始（本地开发） ### 1. 克隆并设置虚拟环境 ``` git clone sentinelpdf cd sentinelpdf python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate ``` ### 2. 安装系统依赖（YARA 和 pikepdf 必需） **Ubuntu/Debian:** ``` sudo apt-get install -y libyara-dev yara qpdf ``` **macOS (Homebrew):** ``` brew install yara qpdf ``` ### 3. 安装 Python 依赖 ``` pip install -r requirements.txt ``` ### 4. 配置环境变量 ``` cp .env.example .env # 编辑 .env 并设置一个强 SECRET_KEY。 # VIRUSTOTAL_API_KEY / URLHAUS_API_KEY 是可选的。 ``` ### 5. 运行应用程序 ``` python run.py ``` 访问 **http://localhost:5000** — 数据库和必需的文件夹将在首次运行时自动创建。 ### 6. 运行测试套件 ``` pytest ``` ## 🐳 使用 Docker 运行 ``` docker compose -f docker/docker-compose.yml up --build ``` 这将在 Nginx 反向代理后面于 **http://localhost** 启动 Flask 应用程序 (Gunicorn)。有关迁移到 PostgreSQL 的详细信息，请参阅 [`docker/docker-compose.yml`](docker/docker-compose.yml)。 ## 🔒 安全亮点 | 关注点 | 缓解措施 | |---|---| | CSRF | 全局启用 Flask-WTF `CSRFProtect` | | 密码存储 | PBKDF2-SHA256 哈希 (Werkzeug)，绝不使用明文 | | 暴力破解 | 5 次登录失败后锁定账户（15 分钟冷却） | | 用户枚举 | 未知用户与密码错误时显示相同的通用错误信息 | | 文件类型伪造 | 服务端 magic-byte (`%PDF-`) 验证，而不仅仅是扩展名 | | 路径遍历 / 覆盖 | 使用 UUID4 随机化存储文件名，原始名称绝不作为路径使用 | | IDOR | `@scan_owner_required` 装饰器在每个扫描/报告路由上强制执行用户所有权检查（返回 404，而非 403） | | 会话劫持 | Flask-Login `session_protection = "strong"` | | 超大文件上传 | 在客户端 (UX)、服务端 (`MAX_CONTENT_LENGTH`) 以及 Nginx 边缘节点同时强制执行限制 | ## 📜 许可证与免责声明 本项目专为教育和防御性安全研究目的而构建。SentinelPDF 仅执行**静态分析** —— 任何被分析的文档都不会被执行、渲染活动内容，或在具有漏洞的阅读器中打开。在做出最终的应急响应决策之前，检测结果应由合格的分析师进行审核。

标签：请求拦截, 逆向工具