macbere/nexus-ir

# NEXUS-IR — 自主事件响应代理 一个取证AI，接收日志文件夹并提供威胁评估、攻击叙述、MITRE映射模式、提取的IoC及遏制措施。无需人工介入。可在Android手机上运行。 ## 我构建它的原因 这里有一个实际问题：凌晨2点，勒索软件感染开始蔓延。值班分析师收到警报。他们打开笔记本电脑，VPN登录，拉取日志，试图弄清情况。与此同时，蠕虫正在横向移动。当专业事件响应团队抵达时，已经过去了45分钟。 移动端的限制是有意为之。事件响应发生在没有工作站的地方。物理隔离的工控网络。偏远站点。医院楼层。如果它能在手机上运行，就能在任何地方运行，而且支持离线运行——当你分析的网络可能正是你依赖的网络时，这点至关重要。 ## 它实际做什么 7个代理在LangGraph状态机中运行： 1. **分类代理** — 发现所有可处理文件，为每个文件生成SHA-256哈希用于监管链，关键词扫描25+个关键指标，设置优先级 2. **日志代理** — 仅使用正则表达式提取IoC（IPv4、SHA-256、MD5、base64、文件路径、主机名、用户名、进程ID、GrantedAccess十六进制值），通过deflate/zlib/UTF-8/UTF-16LE自动解码base64载荷 3. **磁盘代理** — 恶意软件投放区域检测、持久化路径扫描、双扩展名伪装检测、LOLBIN文件名匹配 4. **内存代理** — 进程注入特征（VirtualAllocEx、WriteProcessMemory、CreateRemoteThread、Sysmon事件ID 8/10）、凭据转储指标、可疑父子进程对 5. **网络代理** — C2信标模式、DNS隧道、ICMP隐蔽通道、可疑端口检测、TLS证书异常 6. **关联代理** — 交叉引用所有5个代理的输出，运行APT特征匹配、Sysmon事件ID链检测（1+10+8 = 确认注入），使用时间乘数计算威胁评分 7. **修正代理** — 魔鬼代言人。质疑自身输出。捕获矛盾。自动修复缺失模式。将修正反馈回循环。 测试了10种案例类型：混淆恶意软件、金融数据泄露、APT杀伤链、勒索软件、暴力破解、LOLBIN入侵、防御盲化、ICMP隧道、隐蔽规避、内部威胁。 ## 架构 我反复思考的设计是：如果代理能捕获自己的错误呢？ 这是循环过程： ``` Triage > Log > Disk > Memory > Network > Correlation > Correction | [problems found?] / YES NO | | Increment Report iteration | Correlation (re-run with fixed state) ``` 修正代理运行我称为“魔鬼代言人”的检查。它查看关联代理的结论并自问：根据分类代理的发现，这合理吗？具体检查包括： - 如果分类代理发现PowerShell隐蔽关键词但模式中缺少POWERSHELL_OBFUSCATION，这就是矛盾。标记它，注入缺失模式，设置forced_reeval = True。 - 如果IoC中存在0x1FFFFF GrantedAccess但模式中缺少PROCESS_INJECTION，则注入它。 - 如果高信号特征触发但评分低于85，则提升评分。 当forced_reeval为true时，LangGraph条件边会路由回关联节点而非前进到报告节点。最多3次迭代防止无限循环。注入的模式通过NexusState TypedDict中的injected_patterns: list字段在迭代间持久化，因此它们在重新运行时仍然有效。 这是耗时最长才找到的bug。修正代理正在将模式注入关联报告字典，但重新运行时的关联代理正在从all_reports重建所有内容，覆盖了修正。解决方案是将注入模式作为一等字段通过LangGraph状态线程化，并在每次关联节点执行开始时重新应用它们。 ### 安全防护 安全防护措施位于tools/mcp_server.py的Python代码中： ``` FORBIDDEN_COMMANDS = ["rm", "dd", "shred", "wget", "curl", "ssh", "mkfs"] ``` 此检查在任何命令执行前运行。AI无法通过提示操作覆盖它，因为它不在提示中。这是一个Python if语句。没有模型输出能使cmd.split()[0]中的"rm"返回False。 IoC提取仅使用正则表达式。没有LLM猜测IP、哈希或路径。威胁叙述使用LLM，但这明确标记为推理。硬性取证事实是确定性的。 ### Android／Termux 在Android手机上的Termux中运行于ARM64环境。这不是演示环境，这是实际的开发和测试机器。在Android占用后，每个代理必须在约2GB可用RAM内工作。 热节流很烦人。在20次快速连续运行下，执行时间从0.4秒漂移到0.7秒。花了我一段时间才弄清楚这只是ARM Cortex降低时钟频率，不是代码问题。冷却测试证实了这一点：运行间间隔3秒，零漂移。在实际使用中，每次调查都是冷启动，所以在操作上这不重要。但我想理解它，而不只是接受它。 ## 它有效的证明 我不要求你仅凭我的话相信这些。 单元测试：78/78通过。每个代理独立测试加端到端测试。 压力测试：10种案例类型共63/63通过。零误报（暴力破解保持HIGH，内部威胁保持HIGH，两者均未升级为CRITICAL）。 取证验证：运行4个案例各两次，哈希化结构化输出，跨运行比较哈希值。零语义漂移。 ``` [STABLE] obfuscated_malware hash: 0db5c92b5cd735e0 [STABLE] financial_breach hash: 0c096616feb0a75f [STABLE] apt_attack hash: 0817d380ec38ff7c [STABLE] brute_force hash: 347f8684ee8843e4 VERDICT: FORENSICALLY RELIABLE -- zero semantic drift ``` 容量压力测试：各阶段共43/43通过。并行加速已确认（3个并发调查快于3倍顺序执行）。 完整详情见submission/BENCHMARK_SUMMARY.md和submission/DETERMINISM_PROOF.md。 ## 黑客松评分标准 ### 自主执行质量（25分） LangGraph循环是这里的关键。代理检测自身输出中的错误，修复它们，并决定重新运行还是继续。这一切都发生在输入和输出之间无需人工干预。 具体而言：运行python3 main.py ~/cases/obfuscated_malware并观察修正代理在时间戳[HH:MM:SS] D [修正代理] 魔鬼代言人：PowerShell混淆被遗漏！时触发，随后是* 自动修复：已注入POWERSHELL_OBFUSCATION模式。这就是循环在工作。代理捕获了自己的错误。 每个JSON报告中的执行跟踪（execution_trace字段）记录每个节点的执行时间戳和迭代次数。评委可以将任何发现审计回产生它的具体工具调用。 ### 事件响应准确性（25分） 64/64取证验证检查。IoC提取零幻觉，因为IoC通过正则表达式提取，而非LLM。每个发现都通过路径和SHA-256哈希前缀引用特定工件文件。 确定性证明在tests/verify_forensic.py中。运行它。在任何具有相同证据文件的机器上，它将产生相同的哈希输出。 ### 分析的广度和深度（25分） 7个专业代理。10个MITRE ATT&CK技术映射。10种案例类型，涵盖从脚本小子暴力破解到具有进程注入和LSASS凭据转储的多阶段APT的全部范围。该系统处理JSON、CSV、日志、evtx、XML、syslog和pcap工件。 SPL查询目录（submission/SPL_QUERY_CATALOG.md）有9个已验证的查询映射到特定MITRE技术。这些查询是从与分析相同的正则表达式验证IoC生成的。 ### 约束实现（25分） tools/mcp_server.py包含作为Python代码的禁止命令列表。agents/log_agent.py仅包含用于IoC提取的静态方法正则表达式函数。没有LLM输出直接执行命令或识别IP地址的代码路径。 SHA-256监管链位于每个代理的_hash_file()中。它在加载时运行，在分析之前。哈希存储在chain_of_custody[filepath]中，并嵌入到引用该文件的每个发现的finding[file_hash]中。 ## 演示流程 前置条件： - Python 3.10+ - pip install langgraph langchain anthropic langchain-groq fpdf2 python-dotenv requests rich - 对于LLM叙述生成：将GROQ_API_KEY=your_key添加到.env（免费获取于console.groq.com）。没有它，系统仍然工作——它对3句攻击摘要使用基于模板的叙述。 克隆并设置： ``` git clone https://github.com/macbere/nexus-ir.git cd nexus-ir pip install -r requirements.txt ``` 最快的演示是混淆恶意软件案例。它展示了包括魔鬼代言人在内的完整循环： python3 main.py ~/cases/obfuscated_malware 你将看到LangGraph节点按顺序触发。注意魔鬼代言人部分： ``` [HH:MM:SS] D [CorrectionAgent] DEVIL ADVOCATE: PowerShell obfuscation missed! [HH:MM:SS] * [CorrectionAgent] AUTO-FIX: Injected POWERSHELL_OBFUSCATION pattern ``` 对于金融数据泄露案例，它展示了所有7个代理发现不同内容： ``` python3 main.py ~/cases/financial_breach ``` 内存代理将发现lsass、golden ticket、mimikatz。网络代理将发现反向shell、端口4444、数据外泄。磁盘代理将发现恶意软件投放区域和恶意文件名。所有这些都作为伪关键词馈送到关联代理。 要运行完整测试套件： ``` python3 tests/test_nexus.py 2>/dev/null python3 tests/stress_test.py 2>/dev/null python3 tests/verify_forensic.py 2>/dev/null ``` 报告以JSON、TXT和PDF形式生成在reports/output/中。JSON包含完整执行跟踪。PDF设计用于呈现给非技术利益相关者。 要测试你自己的证据：将任何日志、JSON、CSV或EVTX文件放入文件夹并将工具指向它： ``` python3 main.py /path/to/your/case/folder ``` ## 提交工件 submission/目录中的四份文档支持本README中的声明： - BENCHMARK_SUMMARY.md — 完整压力测试结果及表格。吞吐量、并行加速、突发漂移分析和黑客松评分对齐的逐阶段分解。 - DETERMINISM_PROOF.md — 加密输出验证方法、混淆恶意软件案例的监管链文件哈希，以及来自2次独立运行的实际[STABLE]哈希输出。 - SPL_QUERY_CATALOG.md — 9个映射到MITRE技术的SPL查询，包括从index=*重构为scoped index=wineventlog OR index=sysmon的apt_attack查询的前后对比。每个查询都针对测试案例验证。 - MOBILE_FORENSICS_JUSTIFICATION.md — Android/Termux部署的技术原理，包括扩展性预测（相同代码在服务器硬件上约快10倍）、物理隔离和现场环境的操作优势，以及内存约束如何改进代码库的分析。 ## 诚实限制 代码库中存在三个存根代理（disk_agent.py、memory_agent.py、network_agent.py），它们已完全实现但未集成到旧版orchestrator.py中。它们已连接到LangGraph编排器，但旧的线性编排器仍仅使用4个代理。如果你使用main.py（使用LangGraph），你将获得全部7个代理。如果某些情况通过回退路由，你将获得4个代理。 该系统很好地处理可文本导出的工件。它不直接解析原始二进制内存转储、PCAP文件或Windows注册表配置单元。对于这些，你需要一个预处理步骤首先提取文本表示。 LLM叙述生成是可选的，目前使用Groq免费层的llama-3.3-70b-versatile。没有API密钥时，攻击叙述回退到模板。模板还不错但不如LLM输出具体。 PDF生成器使用Courier字体，因为fpdf2的Unicode支持自定义字体需要我不想捆绑的字体文件。PDF可读且专业但不美观。 如果有更多时间，我会为网络代理构建适当的PCAP解析，为非CLI用户添加Web UI，实现适当的LangGraph持久化以使调查可以暂停和恢复，并添加Splunk HEC集成，以便代理可以查询实时数据而不仅仅是分析导出的日志。 ## 致谢 SANS Institute举办Find Evil活动。黑客松前提完全正确——在“发生了什么”和“我们知道发生了什么”之间，防御者处于劣势。能更快弥合这一差距的工具很重要。 LangGraph团队提供的文档真正解释了状态归约器。fpdf2维护者提供的库无需修改即可在ARM Android上工作。 还有Android热管理系统，它让我对ARM时钟频率缩放有了超出预期的了解。 *NEXUS-IR v4.5.0 — Find Evil! 黑客松，SANS Institute 2026* *在Termux中构建。凌晨2点测试。原样交付。*

标签：Homebrew安装, 逆向工具