huynhtrungcsc/local-llm-security-engine

## 概述 本仓库包含两个紧密集成的服务，用于本地 AI 辅助的安全运营： | 组件 | 路径 | 语言 | 用途 | |-----------|------|----------|---------| | **LLM Security Engine** | `llm-security-engine/` | Python 3.10+ / FastAPI | 通过 Ollama 运行本地 LLM 推理；将安全事件分类为结构化 JSON | | **SOC Backend** | `soc-backend/` | TypeScript / Express | 接收原始安全警报，调用引擎，并将归一化后的分析结果返回给下游消费者 | `openapi/` 目录包含两个服务共同遵循的共享 OpenAPI 3.1 契约。 所有 LLM 推理均通过 [Ollama](https://ollama.ai) 在您的本地机器上运行。不会将任何事件数据发送给云 LLM 提供商。 ## 快速开始 **前置条件：** Python 3.10+，Node.js 20+，已拉取模型并正在运行的 [Ollama](https://ollama.com)。 ``` # 拉取默认模型 ollama pull phi4-mini # 1. 启动 LLM Security Engine cd llm-security-engine pip install -r requirements.txt cp .env.example .env # edit OLLAMA_MODEL, API key, etc. uvicorn app.main:app --host 0.0.0.0 --port 8000 # 2. 启动 SOC Backend（需要单独的终端，需要 Node.js 20+ 和 pnpm） cd soc-backend pnpm install cp .env.example .env.local # PORT=3000 + LOCAL_LLM_ENGINE_BASE_URL already set pnpm run dev ``` 完整设置指南：[`llm-security-engine/docs/getting_started.md`](llm-security-engine/docs/getting_started.md) ## 架构 ``` [Security alert source] | v +------------------+ POST /api/analyze +----------------------------+ | SOC Backend |---------------------->| LLM Security Engine | | (TypeScript) | | (Python / FastAPI) | | soc-backend/ |<----------------------| llm-security-engine/ | +------------------+ structured analysis | -> Ollama (local model) | +----------------------------+ ``` 引擎对外提供稳定的 REST API。SOC Backend 在将响应转发给下游之前，会根据 OpenAPI 契约验证每个响应——任何违反契约的情况都会被标记为 `fallback_used` 事件，而不是被静默接受。 当引擎在 Cloudflare Tunnel 后面运行时，远程机器上的 SOC Backend 可以通过加密的 HTTPS 连接访问它，同时将所有 LLM 推理保留在本地 Ollama 主机上。 ## API 端点 ### LLM Security Engine (`http://localhost:8000`) | 方法 | 路径 | 认证 | 描述 | |--------|------|------|-------------| | `POST` | `/analyze-event` | 可选 | 对归一化的安全事件进行分类 | | `POST` | `/analyze-context` | 可选 | 对 SOC 上下文摘要进行分类 | | `POST` | `/raw-ollama-test` | 可选 | 调试：向 Ollama 发送原始 prompt | | `GET` | `/health` | 无 | 服务健康检查 | | `GET` | `/debug/ping-ollama` | 无 | Ollama 连通性探测 | 所有分析端点都返回相同且稳定的 `AnalysisResponse` schema。Ollama 故障会产生一个结构化的降级响应并带有 `fallback_used: true`，而不是直接返回 HTTP 错误。 ### SOC Backend (`http://localhost:3000`) | 方法 | 路径 | 认证 | 描述 | |--------|------|------|-------------| | `POST` | `/api/analyze` | 可选 | 接收安全警报并返回引擎分析结果 | | `GET` | `/api/healthz` | 无 | 存活检查——始终返回 `{"status":"ok"}` | | `GET` | `/api/provider-health` | 无 | 引擎连通性探测，包含模型和延迟信息 | ## 文档 | 文档 | 描述 | |----------|-------------| | [入门指南](llm-security-engine/docs/getting_started.md) | 针对所有平台的分步本地设置指南 | | [架构详解](llm-security-engine/docs/architecture_walkthrough.md) | 代码路径、数据流和组件角色 | | [实战使用指南](llm-security-engine/docs/real_usage_guide.md) | 带注释的请求/响应示例 | | [端到端集成](llm-security-engine/docs/end_to_end_integration.md) | 通过 Cloudflare Tunnel 连接两个服务 | | [故障排除](llm-security-engine/docs/troubleshooting.md) | 常见错误及其修复方法 | | [使用真实日志](llm-security-engine/docs/using_real_logs.md) | 适配 Suricata / Zeek / Syslog 输出 | | [Wazuh 集成](llm-security-engine/docs/integration_wazuh.md) | 将 Wazuh 警报连接到引擎；将结果写回 Elasticsearch | | [Elastic SIEM 集成](llm-security-engine/docs/integration_elk.md) | 连接 Elastic SIEM 检测警报；Logstash pipeline 选项 | | [Splunk 集成](llm-security-engine/docs/integration_splunk.md) | 轮询脚本、HEC 输出以及 Splunk Custom Alert Action 适配器 | | [集成契约](llm-security-engine/docs/integration_contract.md) | 服务之间的字段级 API 契约 | | [生产环境差距](llm-security-engine/docs/production_gap.md) | 在生产环境 SOC 部署之前还缺少什么 | ## 测试 ``` # Python engine — 126 个单元测试（无需 Ollama） cd llm-security-engine pip install -r requirements-dev.txt python -m pytest tests/ -v # SOC Backend — 92 个单元测试 cd soc-backend pnpm install pnpm run test ``` 所有测试均使用 mock——无需运行 Ollama 实例。 ## 配置 引擎通过环境变量进行配置（将 `llm-security-engine/` 中的 `.env.example` 复制为 `.env`）： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama API URL | | `OLLAMA_MODEL` | `phi4-mini` | 用于推理的模型名称 | | `OLLAMA_TIMEOUT` | `60` | 请求超时时间（秒） | | `LOCAL_LLM_API_KEY` | *(未设置)* | 用于所有引擎端点的可选入站 API 密钥 | | `RATE_LIMIT_ENABLED` | `true` | 启用基于 IP 的滑动窗口速率限制 | | `RATE_LIMIT_REQUESTS` | `60` | 每个窗口的最大请求数 | | `RATE_LIMIT_WINDOW_SECONDS` | `60` | 窗口大小（秒） | 完整配置参考：[`llm-security-engine/README.md`](llm-security-engine/README.md) ## 仓库结构 ``` local-llm-security-engine/ ├── llm-security-engine/ # Python FastAPI inference service │ ├── app/ │ │ ├── main.py # FastAPI app, middleware registration │ │ ├── config.py # Pydantic settings from environment │ │ ├── middleware/ # Auth, rate limiting, request ID │ │ ├── models/schemas.py # Request/response Pydantic models │ │ ├── routes/ # /analyze-event, /analyze-context, /health │ │ └── services/ # Ollama client, prompt builder, parser, validator │ ├── docs/ # Full documentation set (8 guides) │ ├── tests/ # 126 unit tests │ ├── samples/ # curl and Python examples │ └── README.md # Engine-specific reference ├── soc-backend/ # TypeScript Express SOC integration layer │ ├── src/ │ │ ├── routes/analyze.ts # POST /api/analyze │ │ ├── providers/ # Local engine client + contract validation │ │ └── middleware/ # Auth, rate limiting, request ID │ └── tests/ # 92 unit tests ├── openapi/ # OpenAPI 3.1 contract (shared by both services) └── README.md # This file ``` ## 许可证 本项目基于 MIT 许可证授权——详情请参阅 [LICENSE](LICENSE)。 ## 安全 如需报告安全漏洞，请遵循 [SECURITY.md](SECURITY.md) 中的流程。请勿针对安全相关的发现发起公开的 GitHub issue。

标签：AV绕过, DLL 劫持, FastAPI, LLM评估, Ollama, SOC, 大语言模型, 威胁分析, 安全运营, 扫描框架, 本地部署, 自动化侦查工具, 风险评估