huynhtrungcsc/local-llm-security-engine

## 概述 This repository contains two tightly integrated services for on-premise AI-assisted security operations: | Component | Path | Language | Purpose | |-----------|------|----------|---------| | **LLM Security Engine** | `llm-security-engine/` | Python 3.10+ / FastAPI | Runs local LLM inference via Ollama; classifies security events into structured JSON | | **SOC Backend** | `soc-backend/` | TypeScript / Express | Receives raw security alerts, calls the engine, returns normalised analysis to downstream consumers | The `openapi/` directory contains the shared OpenAPI 3.1 contract that both services conform to. All LLM inference runs locally on your machine via [Ollama](https://ollama.ai). No event data is sent to cloud LLM providers. ## 快速开始 **Prerequisites:** Python 3.10+, Node.js 20+, [Ollama](https://ollama.com) running with a model pulled. ``` # 拉取默认模型 ollama pull phi4-mini # 1. 启动 LLM 安全引擎 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 后端（独立终端，需要 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 ``` Full setup guide: [`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) | +----------------------------+ ``` The engine exposes a stable REST API. The SOC backend validates every response against the OpenAPI contract before forwarding downstream — any contract violation is flagged as a `fallback_used` event rather than silently accepted. When the engine is running behind a Cloudflare Tunnel, the SOC backend on a remote machine can reach it over an encrypted HTTPS connection while keeping all LLM inference on the local Ollama host. ## API 端点 ### LLM 安全引擎 (`http://localhost:8000`) | Method | Path | Auth | Description | |--------|------|------|-------------| | `POST` | `/analyze-event` | Optional | Classify a normalized security event | | `POST` | `/analyze-context` | Optional | Classify a SOC context summary | | `POST` | `/raw-ollama-test` | Optional | Debug: send a raw prompt to Ollama | | `GET` | `/health` | None | Service health check | | `GET` | `/debug/ping-ollama` | None | Ollama connectivity probe | All analysis endpoints return the same stable `AnalysisResponse` schema. Ollama failures produce a structured fallback with `fallback_used: true` rather than an HTTP error. ### SOC 后端 (`http://localhost:3000`) | Method | Path | Auth | Description | |--------|------|------|-------------| | `POST` | `/api/analyze` | Optional | Receive a security alert and return engine analysis | | `GET` | `/api/healthz` | None | Liveness check — always returns `{"status":"ok"}` | | `GET` | `/api/provider-health` | None | Engine connectivity probe with model and latency info | ## 文档 | Document | Description | |----------|-------------| | [Getting started](llm-security-engine/docs/getting_started.md) | Step-by-step local setup for all platforms | | [Architecture walkthrough](llm-security-engine/docs/architecture_walkthrough.md) | Code paths, data flow, and component roles | | [Real usage guide](llm-security-engine/docs/real_usage_guide.md) | Annotated request/response examples | | [End-to-end integration](llm-security-engine/docs/end_to_end_integration.md) | Connecting both services over a Cloudflare Tunnel | | [Troubleshooting](llm-security-engine/docs/troubleshooting.md) | Common errors and how to fix them | | [Using real logs](llm-security-engine/docs/using_real_logs.md) | Adapting Suricata / Zeek / Syslog output | | [Wazuh integration](llm-security-engine/docs/integration_wazuh.md) | Connect Wazuh alerts to the engine; write results back to Elasticsearch | | [Elastic SIEM integration](llm-security-engine/docs/integration_elk.md) | Connect Elastic SIEM detection alerts; Logstash pipeline option | | [Splunk integration](llm-security-engine/docs/integration_splunk.md) | Polling script, HEC output, and Splunk Custom Alert Action adapter | | [Integration contract](llm-security-engine/docs/integration_contract.md) | Field-level API contract between services | | [Production gap](llm-security-engine/docs/production_gap.md) | What is missing before production SOC deployment | ## 测试 ``` # Python 引擎 — 126 个单元测试（无需 Ollama） cd llm-security-engine pip install -r requirements-dev.txt python -m pytest tests/ -v # SOC 后端 — 92 个单元测试 cd soc-backend pnpm install pnpm run test ``` All tests use mocks — no running Ollama instance required. ## 配置 The engine is configured via environment variables (copy `.env.example` to `.env` inside `llm-security-engine/`): | Variable | Default | Description | |----------|---------|-------------| | `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama API URL | | `OLLAMA_MODEL` | `phi4-mini` | Model name for inference | | `OLLAMA_TIMEOUT` | `60` | Request timeout in seconds | | `LOCAL_LLM_API_KEY` | *(unset)* | Optional inbound API key for all engine endpoints | | `RATE_LIMIT_ENABLED` | `true` | Enable per-IP sliding-window rate limiting | | `RATE_LIMIT_REQUESTS` | `60` | Max requests per window | | `RATE_LIMIT_WINDOW_SECONDS` | `60` | Window size in seconds | Full configuration reference: [`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 ``` ## 许可证 This project is licensed under the MIT License — see [LICENSE](LICENSE) for details. ## 安全 To report a security vulnerability, please follow the process in [SECURITY.md](SECURITY.md). Do not open a public GitHub issue for security-related findings.

标签：AI安全运维, AI风险缓解, AMSI绕过, AV绕过, Express, FastAPI, LLM安全分析, LLM评估, Ollama, Python, SOC团队, TypeScript, 事件结构化JSON, 大语言模型安全, 威胁检测, 安全事件分类, 安全插件, 安全运营中心, 开源安全工具, 攻击分类, 数据不离开网络, 无云API, 无后门, 本地大模型安全引擎, 本地推理, 本地部署, 机密管理, 深度包检测, 离线安全分析, 网络安全分析, 网络映射, 逆向工具, 逆向工程平台, 风险评分, 风险量化