birdman4512/talkIR
GitHub: birdman4512/talkIR
TalkIR 是一款基于 LLM 的智能日志分析平台，通过自然语言交互降低安全事件调查和日志分析的门槛。
Stars: 0 | Forks: 0
# TalkIR — 安全日志智能分析
使用本地或云端 LLM 与您的日志进行对话。将 JSON 日志文件放入 `./logs/` 目录，在侧边栏选择索引，然后用自然语言提出问题。TalkIR 会将您的问题翻译为 Elasticsearch 查询，获取相关事件，并流式传回分析结果——还可以选择对发现的任何 IP 地址进行威胁情报丰富。
## 功能特性
- **智能查询生成** — LLM 使用您实际的索引字段名称和类型，将自然语言生成为 Elasticsearch Query DSL。如果 LLM 失败，会回退到关键词搜索。
- **流式响应** — 结果和 LLM 分析通过 SSE 逐 token 流式传输；无需等待完整响应。
- **思维模型** — DeepSeek R1 及类似模型会在回答前在可折叠的块中展示其推理链。
- **聚合分析** — 支持 `terms`、`composite`、nested 和 date histogram 聚合；结果会被平铺为可读的表格。
- **威胁情报** — 可选择通过 AbuseIPDB 和/或 VirusTotal 对结果中发现的 IP 地址进行信息丰富。
- **角色切换** — 在网络安全分析师、数据分析师、DevOps/SRE 和通用助手系统提示词之间切换。
- **云端 LLM 支持** — 将查询路由到 Claude (Anthropic) 或 OpenAI，而不是本地模型。
- **模型目录** — 在 UI 中浏览、下载和删除 Ollama 模型；可按 RAM、速度或名称排序。
- **对话历史** — 包含最近 20 轮对话作为上下文，使后续问题的交互更自然。
## 系统架构
```
./logs/*.json ──► Fluent Bit ──► Elasticsearch (single-node, HTTPS)
│
Kibana :5601
│
Browser :3000 ◄── nginx / frontend
│
FastAPI :8000
/ \
Ollama Claude / OpenAI
(local LLM) (cloud LLM, optional)
```
| 服务 | 用途 | 默认端口 |
|---------------|--------------------------------------|-----------------|
| elasticsearch | 启用 TLS 的单节点 ES | 9200 |
| kibana | 日志可视化仪表板 | 5601 |
| fluent-bit | 从 `./logs/` 摄取 JSON 日志 | — |
| ollama | 本地 LLM 推理 (CPU 或 GPU) | 11434 |
| api | 聊天 / 搜索后端 (FastAPI) | 8000 (内部) |
| frontend | 由 nginx 提供服务的聊天 UI | 3000 |
## 前置条件
- Docker ≥ 24 和 Docker Compose ≥ 2.20
- 为 `qwen2.5:7b`（默认模型）预留 5 GB 可用内存；为 `llama3.2:3b` 备用模型预留 2 GB
- 约 2–5 GB 磁盘空间用于存储模型权重（首次启动时下载）
### 仅限 Linux — 增加 `vm.max_map_count`
Elasticsearch 需要此内核参数。如果没有它，ES 节点将在启动时崩溃。
```
sudo sysctl -w vm.max_map_count=262144
# 重启后保持生效:
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
```
## 快速开始
### 1. 克隆并配置
```
git clone https://github.com/birdman4512/talkIR.git
cd talkIR
cp .env.example .env
```
生成凭据并将其写入 `.env` 文件：
```
ELASTIC_PASS=$(openssl rand -hex 20)
KIBANA_PASS=$(openssl rand -hex 20)
KIBANA_KEY=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
sed -i "s/^ELASTIC_PASSWORD=.*/ELASTIC_PASSWORD=${ELASTIC_PASS}/" .env
sed -i "s/^KIBANA_PASSWORD=.*/KIBANA_PASSWORD=${KIBANA_PASS}/" .env
sed -i "s/^KIBANA_ENCRYPTION_KEY=.*/KIBANA_ENCRYPTION_KEY=${KIBANA_KEY}/" .env
sed -i "s/^JWT_SECRET=.*/JWT_SECRET=${JWT_SECRET}/" .env
```
### 2. 启动堆栈
```
docker compose up -d
```
首次运行需要 **3–5 分钟**，期间会下载 LLM。查看进度：
```
docker compose logs -f api # ready when: "Application startup complete."
```
### 3. 打开 UI
```
http://localhost:3000
```
Kibana 地址为 `http://localhost:5601` — 使用 `elastic` / 您的 `ELASTIC_PASSWORD` 登录。
### 4. 放入日志文件
```
cp /path/to/your/events.json ./logs/
```
Fluent Bit 会在大约 10 秒内提取它。在侧边栏刷新索引列表，然后开始提问。
## 日志文件格式
每一行必须是一个有效的 JSON 对象 (NDJSON)：
```
{"timestamp":"2024-01-15T08:23:11Z","event_type":"login_failure","src_ip":"203.0.113.5","user":"admin"}
{"timestamp":"2024-01-15T08:23:12Z","event_type":"login_success","src_ip":"198.51.100.2","user":"jsmith"}
```
索引名称派生自文件名：
- `./logs/auth_events.json` → 索引 `auth_events-YYYY.MM.DD`
- `./logs/firewall.json` → 索引 `firewall-YYYY.MM.DD`
## 配置说明
所有设置均位于 `.env` 文件中。主要变量：
| 变量 | 用途 | 默认值 |
|---|---|---|
| `ELASTIC_PASSWORD` | Elasticsearch `elastic` 用户密码 | — (必填) |
| `KIBANA_PASSWORD` | Kibana 系统密码 | — (必填) |
| `KIBANA_ENCRYPTION_KEY` | 已保存对象加密 (32 个字符以上) | — (必填) |
| `JWT_SECRET` | 会话 token 签名密钥 (32 个字符以上) | — (必填) |
| `OLLAMA_MODEL` | 默认 Ollama 模型 | `qwen2.5:7b` |
| `ANTHROPIC_API_KEY` | 启用 Claude 作为提供商 | — (可选) |
| `OPENAI_API_KEY` | 启用 OpenAI 作为提供商 | — (可选) |
| `ABUSEIPDB_API_KEY` | IP 威胁情报 (免费：每天 1千次) | — (可选) |
| `VIRUSTOTAL_API_KEY` | IP 威胁情报 (免费：每天 500次) | — (可选) |
| `MEM_LIMIT` | 单 ES 节点内存限制 (字节) | `1073741824` (1 GB) |
## 模型选择
在侧边栏打开 **[ cfg ]** 以浏览模型目录。可以在 UI 中下载和删除模型。
| 模型 | RAM | 速度 | 备注 |
|---|---|---|---|
| `llama3.2:1b` | 1.3 GB | 快 | 最小资源占用 — 快速分类排查 |
| `deepseek-r1:1.5b` | 1.1 GB | 快 | 思维模型 — 展示推理过程，低 RAM |
| `llama3.2:3b` | 2.0 GB | 快 | **最佳默认选择** — 快速、可靠的查询生成 |
| `qwen2.5:7b` | 4.4 GB | 中 | 最适合表格、计数和聚合查询 |
| `llama3.1:8b` | 4.9 GB | 中 | 强大的多步推理能力 |
| `deepseek-r1:7b` | 4.7 GB | 慢 | 完整思维模型 — 逐步推理 |
| `deepseek-r1:8b` | 4.9 GB | 慢 | 针对复杂调查的最佳推理质量 |
若要在不受本地 RAM 限制的情况下获得快速响应，请将 **provider**（提供商）下拉菜单切换为 `claude` 或 `openai`，并在 `.env` 中输入您的 API 密钥。
## 角色设定
使用侧边栏的 **// persona** 下拉菜单来改变 LLM 构建其分析框架的方式：
| 角色 | 最适用场景 |
|---|---|
| 网络安全分析师 | SIEM 日志、威胁狩猎、MITRE ATT&CK 映射 |
| 数据分析师 | 通用模式分析、趋势、异常检测 |
| DevOps / SRE | 应用日志、错误率、服务健康状况 |
| 通用助手 | 任何结构化数据 |
## 威胁情报
在发送查询之前启用 **threat intel**（威胁情报）复选框。TalkIR 将会：
1. 从 ES 结果中提取唯一的公网 IP 地址
2. 并发查询 AbuseIPDB 和/或 VirusTotal（取决于配置了哪些密钥）
3. 将丰富后的结果流式传输到 UI（按风险等级进行颜色编码）
4. 将丰富数据包含在 LLM 提示词中，以便分析时可以引用它
在 `.env` 中配置 API 密钥。两项服务均提供免费额度（AbuseIPDB：每天 1,000 次查询；VirusTotal：每天 500 次查询）。
## GPU 加速 (NVIDIA)
1. 安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
2. 在 `docker-compose.yml` 中取消 `ollama` 服务下 `deploy:` 块的注释
3. 重启：`docker compose up -d ollama`
## 开发说明
```
# 运行 API 单元测试（无需 Docker — ES 和 Ollama 已被 mock）
cd api
pip install -r requirements-dev.txt
pytest tests/ -v
# 带 coverage 运行
pytest tests/ --cov=app --cov-report=term-missing
# 代码变更后重新构建一个服务
docker compose build api && docker compose up -d --no-deps api
# 然后重启 frontend，以便 nginx 重新解析 API hostname：
docker compose restart frontend
# 跟踪查看日志
docker compose logs -f api
docker compose logs -f fluent-bit
# 验证 compose 文件
docker compose config --quiet
# 检查 Lua 语法
luac5.4 -p fluent-bit/extract_index.lua
# 完全重置（销毁所有 ES 数据和 model cache）
docker compose down -v
```
### 常见任务文件映射
| 任务 | 文件 |
|---|---|
| 更改角色的系统提示词 | `api/app/routes/chat.py` → `PERSONAS` dict |
| 添加新角色 | `api/app/routes/chat.py` → `PERSONAS` + `frontend/html/index.html` |
| 更改 ES 查询生成提示词 | `api/app/routes/chat.py` → `QUERY_GEN_PROMPT` |
| 向目录添加模型 | `api/app/routes/models.py` → `CATALOGUE` |
| 更改文件名到索引名称的映射方式 | `fluent-bit/extract_index.lua` |
| 添加 nginx 路由 | `frontend/nginx.conf` |
| 添加 CI 任务 | `.github/workflows/ci.yml` |
## 故障排除
**ES 无法启动 (退出代码 78 / "max virtual memory areas")**
→ 运行 `sudo sysctl -w vm.max_map_count=262144` (仅限 Linux)
**`setup` 容器不断重启**
→ 检查凭据是否已设置：`grep PASSWORD .env`
**"Kibana server is not ready yet" 持续数分钟**
→ 首次启动时属于正常现象 — Kibana 正在等待 `setup` 设置 `kibana_system` 密码。检查：`docker compose logs setup`
**重启 API 后登录返回 502**
→ API 获得了新的 Docker IP，而 nginx 缓存了旧的 IP。修复方法：`docker compose restart frontend`
**运行查询时出现 OOM (内存溢出) 错误**
→ 切换到 `low mem`（低内存）模型 (`llama3.2:1b` 或 `deepseek-r1:1.5b`) 或减小结果滑块。关闭其他应用程序以释放 RAM。
**"does not support thinking" 错误**
→ 选定的模型不支持 thinking API。思维模式仅发送给 DeepSeek R1、QwQ 及类似模型 — 请切换模型，或者系统已自动处理此问题。
**放入日志文件后索引未出现**
→ 检查 `docker compose logs fluent-bit`。文件的每一行都必须是有效的 JSON 对象（不能是 JSON 数组）。
**查询回退到关键词搜索**
→ LLM 未能生成有效的 Elasticsearch JSON。检查 UI 中的 "ES query" 块以查看生成了什么内容。尝试使用不同的模型或换个说法提问。
## CI/CD
GitHub Actions 会在每次推送到 `main` 分支和 PR 时运行：
1. **Lint Dockerfiles** — hadolint
2. **验证 compose** — `docker compose config`
3. **API 单元测试** — 带有 mocked ES + Ollama 的 pytest
4. **Lua 语法检查** — luac
5. **容器扫描** — Trivy (CRITICAL/HIGH CVEs)
6. **机密扫描** — gitleaks
标签：AI安全助手, AI风险缓解, AV绕过, ChatGPT, Claude, CVE检测, DLL 劫持, Elasticsearch, FastAPI, Fluent Bit, IR, JSON日志解析, LLM评估, Ollama, Promptflow, rizin, Seccop, SecOps, SSE流式传输, 云安全架构, 入侵检测系统, 向安全日志提问, 大语言模型, 威胁情报, 子域名变形, 安全事件调查, 安全数据湖, 安全日志智能分析, 安全运营, 开发者工具, 开源安全工具, 扫描框架, 数据聚合分析, 日志可视化, 网络威胁狩猎, 自动化安全分析, 自然语言查询, 请求拦截, 越狱测试, 逆向工具, 逆向工程平台