Nikita27koli/Elf-Malware-Analysis-Agent

# StaticElf Batch Agent    ## 功能介绍 StaticElf Batch Agent 会扫描包含 ELF 二进制文件的文件夹，并使用混合流水线自动识别恶意文件： 1. **Python** 在每个二进制文件上运行 ElfAnalyzer —— 测量熵值、IOC 指标、安全标志、可疑字符串和恶意软件家族签名 2. **Claude（AI agent）** 接收分类结果，并自主决定需要去 VirusTotal 查询哪些二进制文件，哪些需要深入分析，并为每个确认的威胁撰写一份完整的 7 个部分的威胁评估报告 3. **结果** 实时显示在桌面 GUI 中，包含可搜索的二进制文件表格、分类详情面板、最终威胁报告和实时文件统计信息 ## 架构 ``` ┌─────────────────────────────────────────────────────────┐ │ Stage 1 — Python (zero Claude calls) │ │ Discover ELF files → ElfAnalyzer triage → triage table │ └────────────────────────┬────────────────────────────────┘ │ triage table sent once ┌────────────────────────▼────────────────────────────────┐ │ Stage 2 — Claude Agent Loop │ │ check_virustotal(all suspicious) │ │ → deep_analyze(MALICIOUS / NOT_IN_VT) │ │ → write_binary_analysis(each threat) │ │ → write_risk_report(summary) │ └────────────────────────┬────────────────────────────────┘ │ ┌────────────────────────▼────────────────────────────────┐ │ Stage 3 — Python │ │ Fallback for missed analyses → assemble report → GUI │ └─────────────────────────────────────────────────────────┘ ``` ### 为什么这是一个真正的 Agent Claude 不是一个报告生成器 —— 它在引导整个调查过程。接收到分类表格后，它会决定： - 哪些二进制文件需要进行 VirusTotal 查询 - VT 的判定是否足够有说服力以至于需要深入分析 - 哪些二进制文件是确认的威胁，哪些是误报 - 每个确认的威胁在运行时会做什么，以及分析师应该如何处理 Python 只在 Claude 调用工具时才会执行它们。 ## 特性 - 递归扫描文件夹 —— 通过魔数而非扩展名查找 ELF 文件 - 每个批处理最多 20 个二进制文件，最多并行运行 3 个 agent - VirusTotal 集成 —— 针对 70 多个杀毒引擎进行 MD5 哈希查询 - 恶意软件家族匹配 —— Mirai、Gafgyt、XorDDoS、Tsunami、Rekoobe、Mozi - 针对每个确认的恶意二进制文件提供 7 个部分的 Claude 威胁分析 - 实时统计面板 —— 总文件数、发现的 ELF 文件、可疑文件、恶意文件、干净文件 - 所有二进制文件选项卡 —— 带有 VT 判定、Claude 判定和分类详情面板的可排序表格 - 最终报告选项卡 —— 每个二进制文件的可折叠部分，支持全部展开/折叠 - CSV 导出 —— 包含 VT 检测和 Claude 判定在内的全部 35 列 - 实际 token 用量追踪 —— 读取每次 API 调用的 `response.usage` ## 环境要求 ### 系统 | 要求 | 版本 | 备注 | |---|---|---| | Python | 3.12+ | 3.10+ 可能可用，但未经测试 | | pip | 任何最新版本 | 随 Python 附带 | | 操作系统 | Windows / Linux / macOS | 在 Windows 10/11 上测试通过 | ### Python 包 ``` anthropic pyelftools tkinter # included in standard Python on Windows/macOS # linux: sudo apt install python3-tk ``` 安装命令： ``` pip install anthropic pyelftools ``` ### 所需文件 这两个文件必须位于**同一文件夹**中： ``` your_folder/ ├── batch_agent.py ← this tool └── elfanalyzer.py ← ElfAnalyzer library (provided by course) ``` ### API 密钥 | 密钥 | 是否必需 | 获取地址 | |---|---|---| | Anthropic API 密钥 | **是** | [console.anthropic.com](https://console.anthropic.com) | | VirusTotal API 密钥 | 可选 | [virustotal.com/gui/join-us](https://www.virustotal.com/gui/join-us) — 免费套餐：每天 500 次查询 | ## 安装说明 ``` # 1. Clone 或下载该 repository git clone https://github.com/your-username/staticelf-batch-agent.git cd staticelf-batch-agent # 2. （推荐）创建 virtual environment python -m venv .venv # Windows .venv\Scripts\activate # Linux / macOS source .venv/bin/activate # 3. 安装 dependencies pip install anthropic pyelftools # 4. 将 elfanalyzer.py 放置在与 batch_agent.py 相同的目录中 ``` ### 可选步骤 —— 将 API 密钥存储在 .env 中 在与 `batch_agent.py` 相同的文件夹中创建一个 `.env` 文件： ``` ANTHROPIC_API_KEY=sk-ant-... VT_API_KEY=your_vt_key_here ``` 密钥将在启动时自动加载。 ## 运行 Agent ``` python batch_agent.py ``` GUI 将会打开。请按照以下步骤操作： **1. 输入你的 Anthropic API 密钥** 将你的密钥粘贴到 `ANTHROPIC API KEY` 字段中。点击 `SHOW / HIDE` 进行验证。 **2. 输入你的 VirusTotal API 密钥（可选）** 将你的免费 VT 密钥粘贴到 `VIRUSTOTAL API KEY` 字段中。如果省略，agent 将跳过 VT 查询，仅依赖 ElfAnalyzer + Claude 的静态分析。 **3. 选择目标文件夹** 点击 `BROWSE` 并选择包含你的 ELF 二进制文件的文件夹。agent 将递归扫描子文件夹。 **4. 调整批处理设置（可选）** | 设置 | 默认值 | 描述 | |---|---|---| | 批处理大小 | 20 | 每个 agent 处理的最大二进制文件数（硬性上限：20） | | 并行 agent 数 | 3 | 同时运行的 agent 数量 | 对于大型数据集（50 个以上的二进制文件），请将并行 agent 数量减少到 1–2 个，以避免触发 Claude API 频率限制。 **5. 点击 `START BATCH AGENT`** 进度将实时显示在三个选项卡中： - **Agent 日志** —— 每一个 Claude 推理步骤和工具调用，右侧带有实时统计数据 - **所有二进制文件** —— 所有已扫描文件的表格；点击任意行可查看完整的分类详情 - **最终报告** —— 已确认恶意二进制文件的可折叠威胁分析 ## 输出说明 ### 文件统计面板（Agent 日志选项卡，右侧） | 计数器 | 含义 | |---|---| | TOTAL FILES | 在文件夹中找到的所有文件 | | ELF FOUND | 包含 ELF 魔数的文件 | | ANALYZED | 已由 ElfAnalyzer 处理的二进制文件 | | SUSPICIOUS | 被 ElfAnalyzer 标记的文件（ioc_severity ≥ 0.25 或 MEDIUM+） | | MALICIOUS | 被 Claude 确认为恶意的文件 | | CLEAN | 经 VT 确认安全或 ElfAnalyzer 未标记的文件 | ### 所有二进制文件表格列 | 列 | 描述 | |---|---| | IOC Verdict | ElfAnalyzer 严重程度：CLEAN / LOW / MEDIUM / HIGH / CRITICAL | | VT Verdict | VirusTotal 判定：MALICIOUS / LIKELY_MALICIOUS / CLEAN / NOT_IN_VT | | VT Detections | 检出率，例如 41/63 | | Claude Verdict | Claude 的最终评估：Malicious / Suspicious / Clean | ### Claude 判定逻辑 ``` VT = MALICIOUS → Claude verdict: Malicious VT = CLEAN → Claude verdict: Clean (no deep analysis performed) VT = NOT_IN_VT → Claude performs deep analysis, uses static signals VT = unavailable → Claude uses ElfAnalyzer signals only ``` ### 最终报告部分 每个确认的恶意二进制文件都会获得一份 7 个部分的分析： 1. **总体判定** —— Malicious（恶意）/ Suspicious（可疑）/ Benign（良性）附带置信度百分比 2. **严重性评级** —— Critical（严重）/ High（高）/ Medium（中）/ Low（低）/ Informational（ informational） 3. **威胁分类** —— 特定的家族名称或行为类别 4. **关键指标** —— 作为证据引用的确切字符串、导入项、VT 引擎名称 5. **行为评估** —— 二进制文件在运行时的行为 6. **攻击者目标** —— 推断出的攻击目的 7. **建议操作** —— 遏制和调查步骤 ## Token 用量和成本 该 agent 会从每次 API 调用的 `response.usage` 中追踪实际的 token 使用情况。显示在 Agent 日志统计面板中： ``` Est. tokens used: 4,832 in: 3,241 out: 1,591 ``` 每批次的大致成本（基于 Sonnet 定价）： | 场景 | Claude 调用次数 | ~Token 数 | ~成本 | |---|---|---|---| | 3 个二进制文件，2 个恶意 | 8 | 5,000 | $0.03 | | 20 个二进制文件，8 个恶意 | 22 | 18,000 | $0.10 | | 50 个二进制文件，15 个恶意 | 45 | 40,000 | $0.22 | ## 项目结构 ``` staticelf-batch-agent/ ├── batch_agent.py Main application ├── elfanalyzer.py ELF analysis library (course-provided) ├── .env API keys (optional, not committed to git) ├── README.md This file └── requirements.txt Python dependencies ``` ### batch_agent.py 中的关键函数 | 函数 | 阶段 | 描述 | |---|---|---| | `discover_elf_files()` | 1 | 遍历文件夹，检查 ELF 魔数 | | `_tool_triage()` | 1 | 运行 ElfAnalyzer，存储至缓存 | | `_tool_deep_analyze()` | 2 | 从缓存中进行字符串和家族匹配 | | `_tool_virustotal()` | 2 | 向 VT API v3 发起 HTTPS 查询 | | `_build_analysis_prompt()` | 后备方案 | 为直接调用 Claude 组装证据提示词 | | `run_agent()` | 2 | 完整的 agent 循环 —— 分类 → VT → 深入 → 写入 | | `run_batch_scan()` | 所有阶段 | 编排器 —— 发现、分批、并行、报告 | | `BatchAgentApp` | GUI | Tkinter 桌面界面 | ## 局限性 - **仅限 ELF** —— 专为 Linux/IoT ELF 二进制文件设计。不分析 PE（Windows .exe）、Mach-O（macOS）或脚本。 - **仅限静态分析** —— 不执行二进制文件。动态行为（实际的网络连接、运行时解密）是通过字符串和结构推断出来的，而非实际观察到的。 - **VirusTotal 免费套餐** —— 限制为每天 500 次查询和每分钟 4 次请求。agent 会在两次 VT 调用之间自动休眠 16 秒以遵守频率限制。 - **恶意软件家族签名** —— 家族匹配器涵盖 6 个家族（Mirai、Gafgyt、XorDDoS、Tsunami、Rekoobe、Mozi）。未知家族将改为按行为类别进行分类。 - **批处理大小上限** —— 每个 agent 硬性限制为 20 个二进制文件，以保持 token 用量的可预测性。 ## 故障排除 **`ModuleNotFoundError: No module named 'elfanalyzer'`** `elfanalyzer.py` 必须与 `batch_agent.py` 位于同一目录中。 **`ModuleNotFoundError: No module named 'tkinter'`** 在 Linux 上运行：`sudo apt install python3-tk` **VT 对已知恶意软件返回 NOT_IN_VT** 检查 Agent 日志中的 `VT lookup: filename md5=xxxxxxxx... (N chars)` 行。如果 N 不是 32，说明 MD5 被截断了。这是当前版本中已修复的一个已知 bug。 **频率限制错误 (429)** 在侧边栏中将并行 agent 数量减少到 1。agent 会以指数退避（20 秒、40 秒、60 秒、80 秒）进行重试，但持续的并行工作负载仍然可能超出 Anthropic 免费套餐每分钟 30,000 个 token 的限制。 **Claude 判定对所有二进制文件均显示 `—`** agent 循环可能在写完所有分析之前就达到了 60 次调用的迭代限制。Python 后备机制会自动处理 MALICIOUS（恶意）二进制文件。如果 `—` 持续出现，请检查 Agent 日志中的 `Fallback:` 行。 ## 许可证 MIT ## 致谢 基于 [Anthropic Python SDK] 和 [VirusTotal API v3] 构建

标签：Ask搜索, Claude, CVE检测, DAST, DeepSeek, ELF文件分析, IOC提取, Linux恶意软件, Python, VirusTotal, 二进制文件分析, 云安全监控, 云资产清单, 人工智能安全, 合规性, 后门检测, 威胁情报, 威胁报告生成, 开发者工具, 恶意软件分析, 无后门, 桌面GUI, 沙箱分析, 熵值分析, 病毒检测, 网络安全, 自动化安全分析, 逆向工程, 隐私保护, 静态分析