ishitaacharya2005/ai-log-incident-agent

# AI 日志与事件分析 Agent 这是一个端到端的安全日志分析系统，能够摄取原始 SSH、web server 和 firewall 日志，通过结合基于规则启发式算法和无监督机器学习来检测异常行为，并利用由 LangChain + Hugging Face 驱动的 agent，对照 MITRE ATT&CK 风格的战术分类法对检测结果进行分诊，生成可直接供分析师使用的事件报告，并通过 FastAPI 后端和实时 web 仪表板进行展示。 ## 为什么开发这个项目 大多数“AI 日志分析”演示要么 只是使用正则表达式匹配已知的攻击签名，要么 只是直接将原始日志输入到 LLM 中然后祈祷结果。这两种方式在深入推敲时都站不住脚。这个项目特意叠加了三种不同的技术，从而让前一种技术的局限性可以由后一种技术来弥补： 1. **基于规则的检测器** 能捕获已知的攻击签名（暴力破解、端口扫描、目录枚举），具有完全的可解释性，并且在为什么会触发标记这一点上没有任何歧义。 2. **Isolation Forest（无监督 ML）** 对基于 IP 构建的行为特征进行分析，能够捕获与任何已知签名都不匹配的异常，也就是说，它可以标记*未知的*可疑行为，而不仅仅是教科书式的攻击。 3. **LangChain + Hugging Face LLM agent** 接收这两个检测层的结构化输出，并执行它们都无法完成的任务：上下文判断（考虑到目标，这是否真的有风险？）、严重性推理、映射到公认的威胁框架，以及撰写人类分析师真正会阅读的报告。 ## 架构 ``` raw log files (.log / .txt) │ ▼ ┌─────────────────────┐ │ log_parser.py │ regex-based extraction → structured LogEvent objects │ (SSH / web / FW) │ reports parsing coverage % as a quality metric └─────────┬────────────┘ ▼ ┌─────────────────────┐ │ anomaly_detector.py │ rule-based: brute force, port scan, dir enum │ │ ML-based: Isolation Forest over behavioral features └─────────┬────────────┘ ▼ list[Incident] ┌─────────────────────┐ │ triage_agent.py │ LangChain (ChatOpenAI) + Hugging Face Inference │ (LangChain + HF) │ Providers router: MITRE tactic classification, │ │ severity refinement, false-positive flagging, │ │ plain-English analyst summary └─────────┬────────────┘ ▼ list[TriageResult] ┌─────────────────────┐ │ report_agent.py │ synthesizes an executive summary + structured │ │ incident report (JSON) └─────────┬────────────┘ ▼ ┌─────────────────────┐ │ FastAPI (main.py) │ /api/analyze, /api/sample-report, dashboard UI └──────────────────────┘ ``` ## 技术栈 - **后端**：FastAPI, Python 3.11 - **ML**：scikit-learn (Isolation Forest), 用于特征工程的 NumPy - **GenAI**：LangChain (`langchain-openai`), Hugging Face Inference Providers（通过 `router.huggingface.co` 路由，目前配置为 DeepSeek-V3，可无缝切换至 Hub 上具有活跃推理 provider 的任何模型） - **前端**：原生 HTML/CSS 仪表板（无框架依赖） - **测试**：pytest，用于解析和检测逻辑的单元测试 ## 值得在面试中探讨的关键设计决策 - **默认开启 Mock 模式。** 依赖 LLM 的 agent（`triage_agent.py`，`report_agent.py`）在未设置 Hugging Face API token 时会回退到确定性逻辑，因此整个流水线——解析、检测、API 和仪表板——都可以在没有任何 API 成本或外部依赖的情况下完全运行和测试。这是在演示可靠性和“始终调用真实模型”之间做出的有意识的权衡。 - **双检测范式，而非单一。** 仅靠基于规则的检测会漏掉任何未知的攻击；纯粹的 ML/LLM 检测则会牺牲可解释性，并且每行日志的处理速度更慢/成本更高。将两者结合意味着，廉价、快速、可解释的层负责处理已知模式，而统计层只需捕获规则遗漏的部分。 - **LLM 失败时的优雅降级。** 分诊和报告 agent 将整个 LLM 调用（而不仅仅是 JSON 解析）封装在异常处理中，因此*任何*故障模式——格式错误的 JSON、无法访问的 endpoint、auth 错误、模型不可用——都会回退到基于规则得出的结果，而不是导致流水线崩溃。在测试发现最初的实现只能捕获 JSON 解析错误而不能捕获网络故障后，这一点得到了加强；在异常处理范围被扩大到包裹整个调用之前，真正无法访问的 LLM endpoint 会导致整个报告步骤崩溃。 - **从已弃用的 Hugging Face endpoint 迁移。** 该项目最初通过 `langchain_huggingface` 直接调用 `api-inference.huggingface.co`。Hugging Face 后来弃用了该 endpoint，转而采用位于 `router.huggingface.co` 的统一且兼容 OpenAI 的 router，该 router 可代理到 15 个以上的后端推理 provider。目前的集成使用了 `langchain-openai` 的 `ChatOpenAI`，并设置了指向该 router 的自定义 `base_url`——这使得 LangChain 的 prompt 模板和链组合（`ChatPromptTemplate`，LCEL `prompt | chat`）保持不变，同时与处于维护状态的 endpoint 进行通信。 - **将解析覆盖率作为一项持续追踪的指标。** 系统不会静默丢弃无法解析的日志行，而是会报告成功结构化的日志行百分比。在捆绑的示例数据集（混合了 SSH、web 访问和 firewall 日志行）上，解析器实现了 **68.1%** 的结构化覆盖率——这是一个真实测量出的数据，而不是未经证实的声明。未解析的部分主要集中在与这三种已知格式都不匹配的日志行上；进一步改进这一点是下文待办事项之一。 ## 设置 ``` git clone cd ai-log-incident-agent python -m venv venv source venv/bin/activate # venv\Scripts\activate on Windows pip install -r requirements.txt cp .env.example .env # optional: add your HF token to enable real LLM calls ``` ## 运行 ``` uvicorn app.main:app --reload ``` 然后打开 `http://127.0.0.1:8000`，上传你自己的日志文件，或者点击 **Try it with an example**，以查看流水线针对捆绑示例数据集（`data/sample_logs/`）的运行情况，该数据集包括模拟的暴力破解攻击、端口扫描和目录枚举尝试。 ## 运行测试 ``` pytest tests/ -v ```

标签：AI安全分析, AV绕过, CISA项目, DLL 劫持, FastAPI, IaC 扫描, 大语言模型, 安全规则引擎, 安全运营中心, 异常检测, 插件系统, 网络映射, 逆向工具