hizir777/sussy_pdf

# 🔬 Sussy PDF — 逆向工程选修项目 - 可疑 PDF 分析平台 ## 📑 目录 - [🏗️ 架构](#️-mimari) - [🚀 安装](#-kurulum) - [📋 使用方法](#-kullanım) - [📊 检测到的威胁标签](#-tespit-edilen-tehdit-etiketleri) - [🎯 MITRE ATT&CK 映射](#-mitre-attck-eşlemeleri) - [📁 项目结构](#-proje-yapısı) - [🔒 安全与身份验证](#-güvenlik--kimlik-doğrulama-v110) - [👥 贡献指南](#-katkı-yapın) - [📖 文档](#-dokümantasyon) - [📄 许可证](#-lisans) ## 🎬 演示 您可以通过以下录制视频查看项目在 Docker 上的运行情况和分析过程： 1. *完整版 YouTube 测试视频：* https://youtu.be/WRyvFiTWzvM ##  ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────┐ │ 📥 Ingestion │ │ Hash • Magic Bytes • Metadata │ ├─────────────────────────────────────────────────────┤ │ 🔍 Static Analysis │ │ PDF Parser • Object Tree • Tag Scanner • XRef │ ├─────────────────────────────────────────────────────┤ │ 🔓 De-obfuscation │ │ Stream Decode • String Decode • JS Deobf • AST │ ├─────────────────────────────────────────────────────┤ │ ⚡ Dynamic Analysis │ │ JS Emulation • Sandbox • Anti-Evasion │ ├─────────────────────────────────────────────────────┤ │ 📊 Scoring & Intel │ │ YARA • Heuristic Score • MITRE ATT&CK • Features │ ├─────────────────────────────────────────────────────┤ │ 📄 Reporting │ │ IOC • HTML Report • JSON • Markdown │ └─────────────────────────────────────────────────────┘ ``` ## 🚀 安装 ### 前提条件 - Python 3.10+ - Docker（可选，用于隔离分析） ### 快速开始 ``` # 克隆仓库 git clone https://github.com/hizir777/sussy_pdf.git cd sussy_pdf # 创建虚拟环境 python -m venv .venv .venv\Scripts\activate # Windows # source .venv/bin/activate # Linux/macOS # 安装依赖 pip install -r requirements.txt # 设置环境变量 copy .env.example .env # 通过编辑 .env 文件输入 API 密钥 # 创建测试 fixture python tests/fixtures/generate_fixtures.py ``` ### 使用 Docker 运行 ``` # Build docker-compose -f docker/docker-compose.yml build # 运行 docker-compose -f docker/docker-compose.yml up ``` ## 📋 使用方法 ### CLI 分析 ``` # 完整分析 python -m src.main analyze suspicious_file.pdf # 特定格式输出 python -m src.main analyze file.pdf --format json python -m src.main analyze file.pdf --format html # 指定输出文件 python -m src.main analyze file.pdf -o report.html ``` ### Web 仪表板 ``` # 启动 Dashboard 服务器 python -m src.main serve --port 8443 # 在浏览器中打开: http://localhost:8443 ``` ### API ``` # 使用 POST 分析 PDF curl -X POST http://localhost:8443/api/analyze \ -F "file=@suspicious.pdf" ``` ## 📊 检测到的威胁标签 | 标签 | 级别 | 描述 | |--------|--------|----------| | `/OpenAction` | 🔴 严重 | 自动操作触发器 | | `/JS` / `/JavaScript` | 🔴 严重 | 嵌入的 JavaScript 代码 | | `/Launch` | 🔴 严重 | 外部应用程序启动器 | | `/EmbeddedFiles` | 🟡 高 | 嵌入的文件 | | `/URI` | 🟡 高 | 外部 URL 引用 | | `/XFA` | 🟠 中 | XML 表单架构 | | `/JBIG2Decode` | 🟠 中 | JBIG2 漏洞利用向量 | ## 🎯 MITRE ATT&CK 映射 - **T1059.007** — JavaScript 执行 - **T1204.002** — 用户执行：恶意文件 - **T1566.001** — 网络钓鱼：鱼叉式附件 - **T1027** — 混淆文件或信息 - **T1105** — 入口工具传输 ## 📁 项目结构 ``` sussy_pdf/ ├── src/ # Analiz motoru kaynak kodu │ ├── ingestion/ # Dosya alımı ve hash hesaplama │ ├── static_analysis/ # PDF parser, tag scanner │ ├── deobfuscation/ # Stream/string decode, JS deobf │ ├── dynamic_analysis/ # JS emülasyon, sandbox │ ├── scoring/ # YARA, heuristic, MITRE │ └── reporting/ # IOC, rapor üretici ├── dashboard/ # Web arayüzü ├── docker/ # Docker yapılandırması ├── specs/ # YARA kuralları, puanlama matrisi ├── tests/ # Unit testler └── docs/ # Dokümantasyon ``` ## 🔒 安全与身份验证 (v1.1.0+) ### API 身份验证 Web 仪表板和 API 端点受 JWT token 或 API key 保护： ``` # 使用 JWT Token curl -X POST http://localhost:8443/api/analyze \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -F "file=@suspicious.pdf" # 使用 API Key curl -X POST http://localhost:8443/api/analyze \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@suspicious.pdf" ``` ### 安全特性 ✅ **内置**：输入验证、速率限制、CORS 保护 ✅ **加密**：AES-128/256 PDF 解密支持 ✅ **日志记录**：结构化 JSON 审计跟踪 ✅ **Docker**：无 root 容器、只读文件系统 详情请见：[SECURITY.md](SECURITY.md) ## 📊 开源发展 (v1.1.0+) - ✅ CONTRIBUTING.md 和开发者指南 - ✅ GitHub Issue/PR 模板 - ✅ 全面测试套件 (pytest) - ✅ CI/CD 工作流 (GitHub Actions) - ✅ 路线图和里程碑 - ✅ 安全策略和最佳实践 - ✅ PDF 加密支持 - ✅ 异步处理能力（即将推出） - ✅ 机器学习基础（计划中） ## 👥 贡献指南 如果您愿意帮助开发、编写测试或文档： 1. 阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 指南 2. 查看 [ROADMAP.md](ROADMAP.md) 了解未来计划 3. 在 GitHub Issues 中提交 [功能请求](https://github.com/hizir777/sussy_pdf/issues/new?template=02_feature_request.yml) 4. 提交 Pull request（无需 CLA） 所有贡献均受 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 管理。 ## 📖 文档 - [README.md](README.md) — 本文件 - [CONTRIBUTING.md](CONTRIBUTING.md) — 开发者指南 - [SECURITY.md](SECURITY.md) — 安全与最佳实践 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — 故障排除 - [ROADMAP.md](ROADMAP.md) — 开发计划 - [docs/methodology.md](docs/methodology.md) — 分析方法论 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — 社区规则 ## 🐛 问题报告 发现 bug 了？请在 [GitHub Issues](https://github.com/hizir777/sussy_pdf/issues) 页面上报告： - 🔴 **严重：** 安全漏洞 → 请参阅 [SECURITY.md](SECURITY.md) 事件报告部分 - 🟠 **高：** 崩溃或数据丢失 - 🟡 **普通：** 功能请求或改进 - 🔵 **低：** 文档修复、拼写错误 ## 💬 社区 - **讨论：** [GitHub Discussions](https://github.com/hizir777/sussy_pdf/discussions) - **问题：** [功能请求和错误报告](https://github.com/hizir777/sussy_pdf/issues) - **电子邮件：** maintainers@sussy-pdf.dev ## 🔒 安全说明 - 分析工具在 Docker 容器中隔离运行 - 无 root 容器（最小权限原则） - `.env` 文件永不提交到仓库 - 支持 VirusTotal API 免费层（4 请求/分钟） ## 📄 许可证 MIT License — 详情请参阅 [LICENSE](LICENSE) 文件。

标签：DAST, Docker, Dropper检测, PDF安全, Python, URL收集, 云安全监控, 云资产清单, 多层次分析, 威胁情报, 安全防御评估, 开发者工具, 恶意文档检测, 恶意软件分析, 文件安全检测, 无后门, 沙箱分析, 深度学习检测, 漏洞分析, 网络安全, 请求拦截, 路径探测, 逆向工程, 隐私保护, 静态分析