docdyhr/malwarespotter

# MalwareSpotter PDF 分析器

[](https://github.com/docdyhr/malwarespotter/releases/tag/v1.2.6) [](LICENSE) [](https://www.python.org/) [](https://github.com/docdyhr/malwarespotter/issues) [](https://github.com/docdyhr/malwarespotter/actions/workflows/ci.yml) [](https://codecov.io/gh/docdyhr/malwarespotter) [](https://github.com/docdyhr/malwarespotter/actions/workflows/security.yml) 一款专为安全研究人员和 IT 专业人员打造的全面 PDF 分析和恶意软件检测工具。 ## 更新时间：2025 年 5 月 11 日 ## v1.2.5 的新特性 ### 改进 - 添加了 Codecov 徽章，用于跟踪和显示测试覆盖率指标 - 修复了 pathlib 导入和异常处理，提高了可靠性 - 添加了缺失的测试固件，确保所有测试成功通过 - 使用 `test_improvements.py` 改进了 JavaScript 解码测试 ## v1.2.4 的新特性 ### 版本管理与 CI 改进 - 添加了 GitHub Actions 工作流，用于版本验证和持续集成 - 实现了用于版本完整性验证的 pre-commit 钩子 - 在 `VERSION_MANAGEMENT.md` 中添加了详细的文档 - 为 `version.py` 添加了 dry-run（模拟运行）模式，用于预览更改 - 增强了 `version.py` 以支持 CI/CD 集成 - 改进了 `README.md` 中的版本管理文档 - 修复了 pre-commit 钩子中版本验证的问题 - 添加了 GitHub 社区标准文件 - 扩展了用于版本管理的测试套件 ## 功能 - 🔍 **快速扫描**，使用关键词模式匹配查找可疑元素 - 🔎 **深度结构分析**，针对 PDF 组件和对象层级 - 🔒 **沙盒查看**，在隔离环境中查看可疑文件以防止恶意软件执行 - 🌐 **集成 VirusTotal API**，实现基于云的恶意软件检测 - 📁 **目录监控**，提供实时保护 - 📜 **提取和分析**嵌入的代码（JavaScript，shell 脚本） - 🔬 **反混淆**，针对常见的 JavaScript 混淆技术 - 🖨️ **详细输出**，通过美化打印展示深度分析结果 - 📊 **风险评分**，用于对可疑文件进行优先级排序 - 📝 **全面的日志系统**，具有可配置的日志级别和输出位置 ## v1.0.5 的新特性 ### v1.0.3 的安全性改进 - 添加了 `security_utils.py` 模块，用于集中管理安全功能 - 实现了粒度权限控制，对文件操作采用严格的访问控制 - 增强了命令行参数验证，并提供详细的错误信息 - 添加了分层的沙盒安全级别 (1-3)，以实现更安全的 PDF 查看 - 添加了全面的文件扩展名限制和验证 - 使用安全的 open/write 操作改进了文件处理 - 根据安全级别和平台增强了沙盒查看器的选择 - 使用更强大的安全检查更新了文件路径验证 - 修复了文件写入操作中的潜在安全问题 - 改进了提取代码和分析结果的隔离机制 ## v1.0.4 的新特性 ### CI/CD 与测试改进 - 实现了 pre-commit 钩子，用于自动格式化代码 - 集成了 Dependabot，用于自动更新依赖项 - 创建了 GitHub 工作流，在提交时自动格式化代码 - 修复了 `test_logging.py`，使其使用断言而不是返回值 - 修复了代码中的代码检查错误，确保 CI 流水线整洁 - 更新了 mypy 配置，使用了正确的导入路径 ## v1.0.3 的新特性 ### 安全性改进 - 添加了包含全面安全指南和最佳实践的 `SECURITY.md` - 实现了安全的文件路径验证，以防止路径遍历攻击 - 增强了子进程处理，明确设置 `shell=False` 并进行输入验证 - 通过适当的日志记录改进了整个代码库的错误处理 - 通过强大的安全检查增强了 VirusTotal API 集成 - 添加了路径遍历保护，进行了适当的路径验证和清理 - 实现了在上传到外部服务之前的文件大小验证 - 修复了 SHA256 哈希计算中的问题，并增强了错误处理 ### 测试改进 - 为路径遍历安全功能添加了广泛的测试套件 - 为 VirusTotal API 错误处理创建了全面的测试 - 在 CI/CD 中设置测试和 linting 检查为阻断性步骤 - 提高了安全关键代码路径的测试覆盖率 - 为边界条件和错误场景添加了专门的测试用例 ### 代码质量改进 - 添加了带有 mypy 支持的全面类型注解 - 修复了模块导入处理，具备适当的错误回退机制 - 改进了重定义类的命名和处理方式 - 通过适当的类型检查增强了错误处理 - 修复了字符串/字节处理，提高了类型安全性 - 添加了用于静态类型检查的 mypy 配置 ### 开发者工具 - 添加了带有 `version.py` 的自动版本控制脚本 - 使用版本徽章增强了 GitHub 工作流 - 添加了包含优先级任务列表的 `TODO.md` - 改进了 `README` 中的状态徽章信息 ## 安装 ``` # Clone 仓库 git clone https://github.com/docdyhr/malwarespotter.git cd malwarespotter # 创建并激活 virtual environment（推荐） python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # 安装依赖 pip install -r requirements.txt ``` ### YARA 安装（可选） YARA 是可选的，即使不安装应用程序也能正常运行。如果您想使用 YARA 进行基于规则的扫描： ``` # 安装 yara-python（在 macOS 上可能需要特殊配置） pip install yara-python ``` 如果您在 macOS 上安装 YARA 时遇到问题： 1. 尝试在 conda 环境中通过 pip 安装（这通常能更好地处理 C 依赖项） 2. 考虑使用 Docker 将应用程序容器化 3. 请记住，即使没有 YARA，应用程序也会继续正常运行 ## 沙盒安全 MalwareSpotter 在查看可疑 PDF 时提供了真正的进程隔离。沙盒可防止恶意 PDF 访问敏感数据、建立网络连接或在您的系统上执行代码。 ### 平台支持 | 平台 | 沙盒技术 | 要求 | |----------|-------------------|--------------| | macOS | sandbox-exec | 内置（无需额外设置） | | Linux | firejail 或 bubblewrap | `sudo apt install firejail` | | Windows | Windows Sandbox | Windows 10/11 专业版/企业版 | ### 安全级别 | 级别 | 网络 | 敏感目录 | 写入权限 | 子进程 | |-------|---------|----------------|--------------|------------| | none | 允许 | 允许 | 允许 | 允许 | | basic | **已阻止** | 允许 | 允许 | 允许 | | strict | **已阻止** | **已阻止** | **受限** | 允许 | | paranoid | **已阻止** | **已阻止** | **已阻止** | **已阻止** | **在 STRICT（严格）级别受保护的敏感目录：** - `~/.ssh`、`~/.gnupg`、`~/.aws`、`~/.kube`、`~/.docker` - `~/Library/Keychains` (macOS) - `~/Documents`、`~/Desktop`、`~/Downloads`（受写入保护） ### 沙盒示例 ``` # 在具有默认（严格）安全性的 sandbox 中打开 PDF python pdf_analyzer.py -s -o suspicious.pdf # 使用 basic 级别（仅阻止网络） python pdf_analyzer.py -o --sandbox-level basic suspicious.pdf # Maximum isolation（可能会导致某些 PDF 功能失效） python pdf_analyzer.py -o --sandbox-level paranoid suspicious.pdf # 使用特定的 PDF 查看器 python pdf_analyzer.py -o --viewer Skim suspicious.pdf # macOS python pdf_analyzer.py -o --viewer okular suspicious.pdf # Linux ``` ### Linux 沙盒设置 ``` # Debian/Ubuntu sudo apt install firejail # Fedora sudo dnf install firejail # Arch Linux sudo pacman -S firejail ``` ### Windows 沙盒设置 Windows Sandbox 需要 Windows 10/11 专业版或企业版： ``` # 启用 Windows Sandbox 功能（以管理员身份运行） Enable-WindowsOptionalFeature -FeatureName "Containers-DisposableClientVM" -All -Online ``` ## 用法 ### 基本用法 ``` python pdf_analyzer.py [file_or_directory] [options] ``` ### 命令行选项 ``` Usage: pdf_analyzer.py [options] [file] Options: -h, --help Show this help message and exit --version Show version information and exit -s, --scan Quick scan for suspicious elements -a, --analyze Deep analysis of PDF structure -v, --virustotal Check with VirusTotal -o, --open Open in sandbox after analysis --sandbox-level=LVL Sandbox security level (none, basic, strict, paranoid) --viewer=APP Specify PDF viewer application -m, --monitor Monitor directory for new PDFs -r DIR, --recursive=DIR Recursively scan all PDFs in directory -e, --extract-code Extract embedded code (JavaScript, shell scripts, etc.) --highlight Highlight syntax in extracted code (requires pygments) --save-code Save extracted code to files --save-output[=LOC] Save output to a file (LOC: same, desktop, or downloads) --json Output results in JSON format -d DIR, --directory=DIR Directory to monitor (default: Downloads) --debug Enable debug output (equivalent to --log-level DEBUG) --verbose Enable verbose output with status indicators Logging Options: --log-level=LEVEL Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) --log-file=FILE Log to this file (default: temp directory) --log-console Log to console in addition to file Sandbox Levels: none No sandboxing (not recommended for untrusted files) basic Network access blocked strict Network blocked + sensitive directories protected (default) paranoid Maximum isolation (may break some PDF features) ``` ### 示例 **快速扫描单个文件：** ``` python pdf_analyzer.py -s suspicious.pdf ``` **执行深度分析并进行 VirusTotal 检查：** ``` python pdf_analyzer.py -a -v suspicious.pdf ``` **监控目录以查找新的 PDF 文件：** ``` python pdf_analyzer.py -m -d ~/Downloads ``` **提取并分析嵌入的代码：** ``` python pdf_analyzer.py -e suspicious.pdf ``` **递归扫描目录中的所有 PDF：** ``` python pdf_analyzer.py -r ~/Documents ``` **将分析输出保存到文件：** ``` python pdf_analyzer.py -s --save-output same suspicious.pdf # Save to same directory python pdf_analyzer.py -a --save-output desktop suspicious.pdf # Save to Desktop python pdf_analyzer.py -s -v --save-output downloads suspicious.pdf # Save to Downloads ``` **以 JSON 格式输出结果：** ``` python pdf_analyzer.py -s --json suspicious.pdf # Standard JSON to terminal python pdf_analyzer.py -a -v --json suspicious.pdf # Multiple scan types in JSON python pdf_analyzer.py -s --json --save-output desktop suspicious.pdf # Save to Desktop ``` **配置日志：** ``` python pdf_analyzer.py -s --log-level DEBUG suspicious.pdf # Enable debug logging python pdf_analyzer.py -s --log-file ./analysis.log suspicious.pdf # Log to specific file python pdf_analyzer.py -s --log-console --log-level WARNING suspicious.pdf # Warning logs ``` ## 环境变量 - `VIRUSTOTAL_API_KEY`：您的 VirusTotal API 密钥，用于恶意软件检查 - `MONITOR_DIRECTORY`：用于监控新 PDF 文件的默认目录（默认为 `~/Downloads`） ## 依赖项 - Python 3.9+ - 核心依赖： - `requests`：用于 VirusTotal API 集成 - `watchdog`：用于目录监控 - `pygments`：用于提取代码的语法高亮 - 可选依赖： - `yara-python`：用于 YARA 规则匹配（即使不安装应用程序也能正常运行） ## 许可证 本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 安全提示 本工具仅用于合法的安全研究和分析。请务必谨慎处理可疑的 PDF 文件，并始终在隔离环境中进行操作。 ## 开发 ### 版本管理 MalwareSpotter 使用语义化版本控制。要更新版本，请使用 `version.py` 脚本： ``` # Bump patch 版本号 (1.2.6 -> 1.2.7) python version.py --type patch # Bump minor 版本号 (1.2.6 -> 1.3.0) python version.py --type minor # Bump major 版本号 (1.2.6 -> 2.0.0) python version.py --type major # 创建 git 标签并更新 changelog python version.py --type patch --tag --changelog # 执行所有操作，包括一次 commit python version.py --type patch --tag --changelog --commit ``` 此脚本会自动更新所有相关文件中的版本号，创建变更日志条目，并可选择创建 git 标签。 ### 开发环境设置 #### Pre-commit 钩子 对于开发者，我们添加了 pre-commit 钩子，以便在提交更改时自动格式化代码： ``` # 安装 pre-commit pip install pre-commit # 安装 git hooks pre-commit install ``` 这将在您提交更改时自动运行代码格式化工具（black 和 isort）。 #### 测试文件生成 要在没有真实恶意软件样本的情况下测试 PDF 分析器，您可以使用内置的生成工具： ``` # 生成包含无害但可疑元素的测试 PDF python generate_test_pdf.py ``` 这会创建一个包含 JavaScript（包括混淆代码）和 shell 脚本内容的测试 PDF， 该文件会触发警报，但其本身是完全无害的。 ### 项目结构 - `pdf_analyzer.py` - 主应用程序文件 - `security_utils.py` - 用于文件操作的安全功能和实用程序 - `pdf_logging.py` - 日志配置和实用程序 - `logging_setup.py` - 日志系统设置 - `version.py` - 自动版本控制脚本 - `SECURITY.md` - 安全指南和最佳实践 - `TODO.md` - 优先级任务列表 - `CONTRIBUTING.md` - 贡献者指南 - `CHANGELOG.md` - 详细的变更历史记录

标签：GitHub Actions, Go语言工具, IT安全工具, JavaScript解码, MalwareSpotter, MIT许可, PDF分析, Python, 代码覆盖率, 恶意文档识别, 搜索语句（dork）, 数字取证, 文件格式分析, 无后门, 漏洞分析, 自动化分析, 自动化脚本, 自动笔记, 跨站脚本, 路径探测, 逆向工具