ezeeranieri/LogAI-Analyst

# LogAI-Analyst [](https://sonarcloud.io/summary/new_code?id=ezeeranieri_LogAI-Analyst) [](https://codecov.io/github/ezeeranieri/LogAI-Analyst) 使用 Python 和 FastAPI 构建的专业 AI 驱动安全分析工具，用于主动检测系统日志（Syslog / Auth.log）中的威胁。 ## 要求 - Python 3.10+ - Docker（推荐） - `pip install -r requirements.txt` ## 生产环境功能 - **身份验证（新增）**：通过每个请求中的 `X-API-KEY` 标头强制执行安全。 - **Docker 强化**：使用非特权用户（`appuser`）安全执行。 - **UUID 脱敏**：为最大安全性和路径遍历预防生成唯一的临时文件名。 - **启发式与 AI 检测**：4 层分析（暴力破解、时序异常、用户探测、IA）。 - **安全配额**：10MB 文件上传限制以防止存储耗尽或拒绝服务攻击。 ## 安装与部署 ### 环境配置 在根目录创建 `.env` 文件并填入以下变量： ``` DATA_DIR=data API_KEY=your_super_secure_secret LOG_FILE=app_production.log APP_HOST=127.0.0.1 APP_PORT=8000 ``` ### 初始模型训练（新增） 首次运行 API 前，必须训练 AI 异常检测模型： **注意：** `train_model.py` 必须在项目根目录运行： ``` python train_model.py ``` 这将生成合成数据并保存预训练的 `IsolationForest` 模型到 `data/model.pkl`。 ### 使用 Docker 运行（推荐） ``` docker build -t logai-analyst . docker run -p 8000:8000 --env-file .env logai-analyst ``` ## API 使用（/analyze） 与分析端点的所有交互都需要在标头中提供 API Key。 **使用 `curl` 的示例（认证文件上传）：** ``` curl -X POST "http://localhost:8000/analyze" \ -H "X-API-KEY: your_super_secure_secret" \ -H "Accept: application/json" \ -F "file=@path/to/log/auth.log" ``` ### 响应结构（JSON） API 返回检测到的威胁详细报告： ``` { "status": "success", "total_threats": 1, "data": [ { "timestamp": "Oct 11 10:00:00", "ip_origin": "192.0.2.1", "user": "root", "action": "Failed password for root", "status": "FAIL", "datetime": "2026-10-11 10:00:00", "reason": "Brute Force (>5 fails per min)" } ] } ``` ## 质量与测试（QA） 项目包含集成测试套件，用于验证身份验证流程和检测引擎。 ### 运行测试： ``` python -m pytest ``` ## 工程决策 该项目实现了多种架构与安全模式，以确保可靠性和可扩展性： - **FastAPI 替代 Flask**：选择 FastAPI 是因为其高性能和对异步操作的原生支持。它通过 Pydantic 提供强大的数据验证，并自动生成 OpenAPI（Swagger）文档，这对维护生产级安全 API 至关重要。 - **用于异常检测的 Isolation Forest**：不同于传统基于规则的系统，Isolation Forest 在检测未知威胁（类似零日）方面非常有效。它通过隔离异常点而非对正常数据建模来工作，非常适合模式随时间演化的日志高维数据。 - **用于临时文件的 UUID**：为防止路径遍历攻击并确保文件唯一性，所有上传的日志在处理前会被重命名为版本 4 UUID。此脱敏步骤确保应用程序从不信任客户端提供的文件名。 - **模块化规则（抽象基类）**：检测引擎采用基于继承的架构。通过实现 `DetectionRule` 抽象类，开发人员可以在不修改核心处理逻辑的前提下添加新的启发式或 AI 规则（遵循开闭原则）。 ## 常见问题（FAQ） ### 它能检测哪些类型的攻击？ LogAI-Analyst 识别四种主要威胁类型： - **暴力破解**：来自单个 IP 的失败登录尝试过多（> 每分钟 5 次）。 - **时序异常**：在非工作时间（上午 8 点至下午 6 点）发生的成功登录。 - **用户探测**：单个 IP 在 10 分钟内尝试访问超过 3 个不同用户账户。 - **AI 异常**：机器学习检测到的不符合正常系统行为的异常模式。 ### 使用它需要安全知识吗？ 不需要。该工具设计为开发者与系统管理员均可使用。每个检测结果都包含 JSON 响应中的清晰“原因”字段，解释为何某事件被标记为威胁。 ### 什么是 Isolation Forest，它在这里做什么？ Isolation Forest 是一种用于异常检测的无监督机器学习算法。在此项目中，它分析登录元数据（时间、IP 哈希值、状态）以隔离可能代表复杂攻击的异常点，而这些异常点不会触发传统启发式规则。 ### API 如何受到保护？ API 通过强制性的 `X-API-KEY` 标头身份验证进行加固。每个请求都会根据环境变量中定义的密钥进行验证，确保只有授权用户可执行日志分析。 ### 它接受哪种日志格式？ 它原生支持标准 UNIX 认证日志（`auth.log` 和 `syslog`）。这包括由 `sshd` 及其他遵循经典 syslog 格式的系统服务生成的日志。 ## 挑战与收获 构建生产级日志分析 API 暴露了一些非平凡的工程问题。以下列出遇到的具体挑战及每个问题带来的收获。 ### 1. Syslog 解析比看起来更复杂 编写能可靠处理真实 `auth.log` 条目的正则表达式（其中 `sshd`、`sudo`、`PAM` 和 `cron` 的写入格式略有不同）需要采用两阶段方法：主正则表达式提取 syslog 信封（`timestamp`、`hostname`、`process`），次级正则表达式分别提取自由格式动作字段中的 IP 和用户名。单一的大正则表达式被证明过于脆弱。 **收获**：组合小型、单一用途的正则表达式并合并结果，比试图在一个模式中捕获所有内容更具可维护性。 ### 2. 在 Pandas 索引上使用滚动时间窗口 暴力破解规则需要统计 IP 在滑动 1 分钟窗口内的失败登录次数。`DataFrame.rolling()` 仅适用于 `DatetimeIndex`，这要求在分组前设置索引、在每组内排序，然后重置索引。遗漏任何一步都会导致静默的错误计数。 **收获**：基于时间的 Pandas 滚动操作有严格前提条件。在开发过程中，始终验证中间 DataFrame 形状和索引类型。 ### 3. 机器学习训练与请求周期解耦 原始的 `IADetectorRule` 在没有模型文件时在线训练 `IsolationForest`，这意味着冷启动后的第一个请求可能需要数秒，并且模型是在它本应评估的数据上训练的——导致异常检测循环且不可靠。将训练分离到带有合成数据的 `train_model.py` 中解决了延迟和逻辑问题。 **收获**：用待评估数据训练的 ML 模型无法可靠地标记异常。训练数据必须与推理数据独立。 ### 4. 特征工程必须在训练与推理中完全一致 IP 到数字的编码使用 `zlib.adler32` 进行确定性哈希。`train_model.py` 计算特征与 `IADetectorRule.evaluate()` 计算特征之间的任何差异都会静默地产生无意义的异常分数。两个代码路径必须共享完全相同的哈希逻辑和 `status` 映射，并且此契约必须手动强制执行。 **收获**：特征提取逻辑应位于共享工具函数中，而非重复。训练与推理流水线之间的不匹配是最难诊断的 ML 错误之一。 ### 5. SonarCloud 安全热点要求明确意图 硬编码的 IP 字符串——即使在命名清晰的测试常量中——都会被标记为安全热点。修复方法是将所有测试 IP 迁移到 IANA RFC 5737 的 `192.0.2.x` 文档保留范围，该范围被全球公认为不可路由且非生产用途。 **收获**：IP 地址字面量是一种公认的安全异味，无论上下文如何。使用 IANA 保留的 `TEST-NET-1` 范围（`192.0.2.0/24`）能明确传达意图，同时帮助静态分析工具和人工评审者理解。 ### 6. 跨 Python 版本的模糊日期解析 使用格式 `%b %d %H:%M:%S`（标准 syslog 格式，不含年份）的 `pd.to_datetime()` 在 Python 3.14+ 中会引发 `DeprecationWarning`，因为闰日行为未定义。解析器通过将默认年份为 `1900` 的日期修正为当前年份来规避此问题，但 Pandas 在 3.15 中的行为正在改变。 **收获**：不包含年份的时间戳格式本质上是模糊的。年份推断应尽早添加到解析流水线中，而不是在下游打补丁。

标签：AI安全, AMSI绕过, Apex, API密钥, AV绕过, Brute Force, BurpSuite集成, Chat Copilot, Docker, FastAPI, GitHub Advanced Security, Heuristic, Isolation Forest, LogAI-Analyst, Production Features, Python, Security Quotas, Syslog, TCP/UDP协议, Time Anomalies, User Probing, UUID Sanitization, Web截图, 威胁检测, 安全加固, 安全部署, 安全配额, 安全防御评估, 容器安全, 异常检测, 文件上传限制, 无后门, 机器学习, 认证鉴权, 请求拦截, 路径遍历防护, 逆向工具, 速率限制