nlink-jp/ir-tracker

# ir-tracker 实时事件响应追踪器 — 持续摄取、分段分析和时间线可视化，用于 ongoing IR 对话。 [日本語版 README はこちら](README.ja.md) ## 概念 虽然 [ai-ir](https://github.com/nlink-jp/ai-ir) 在事件**解决后**进行分析（事后复盘），ir-tracker 在事件**进行中**提供实时态势感知。 ``` [During the incident] [After the incident] stail export → ir-tracker ingest stail export → aiir ingest → ir-tracker analyze → aiir report → ir-tracker status ↻ (repeat every 15-30 min) "What's happening now?" "What happened and what did we learn?" ``` ## 功能特性 - **增量分析** — 仅将新的/变更的片段发送至 LLM - **事件摘要** — 自动生成的整场事件执行层概览 - **活动密度图** — 随时间变化的消息活动热力图 - **双栏 Web UI** — 时间线 + 浮动状态面板，深色/浅色主题 - **消息深入** — 点击任意片段以查看原始对话 - **多语言支持** — 英文分析，翻译覆盖任意语言（例如日语） - **态势导出** — 可将当前态势以 Markdown 格式下载（Web UI + CLI） - **上下文链式传递** — 压缩的先前上下文以保证 LLM 在片段间连续性 - **提示注入防御** — 带 nonce 标签的 XML 包装用户消息 - **安全头部** — CSP、X-Frame-Options、X-Content-Type-Options ## 快速开始 ``` # 安装 git clone https://github.com/nlink-jp/ir-tracker.git cd ir-tracker uv sync # 配置 export GOOGLE_CLOUD_PROJECT="your-project-id" gcloud auth application-default login # 摄入 → 分析 → 查看 ir-tracker ingest export.json ir-tracker analyze --lang ja ir-tracker serve # 打开 http://127.0.0.1:8080 ``` ## CLI ``` ir-tracker ingest [--channel name] # Import messages (dedup, auto-segment) ir-tracker analyze [-v] [--lang ja] # Analyze pending segments + translate ir-tracker translate --lang ja [-v] # Translate analyses only ir-tracker status [--format json|markdown] [--lang ja] # Output timeline ir-tracker situation [--lang ja] [-o file.md] # Current situation as Markdown ir-tracker export [--lang ja] [-o timeline.html] # Static HTML report (no server needed) ir-tracker segments # List segments and states ir-tracker serve [--port 8080] [--host 127.0.0.1] # Start Web UI ir-tracker reset # Clear analyses (keep messages) ``` 所有命令均接受 `--db <路径>` 以指定 SQLite 数据库（默认：`tracker.db`）。 ## Web UI | 页面 | URL | 描述 | |------|-----|------| | 时间线 | `/` | 事件摘要、密度图、片段时间线、状态面板 | | 片段 | `/segments` | 带状态的片段列表 | | API：时间线 | `/api/timeline` | JSON 时间线数据 | | API：态势 | `/api/situation.md` | Markdown 态势下载 | | API：消息 | `/api/segments/{id}/messages` | 片段消息（JSON） | 所有页面均支持 `?lang=ja` 以启用翻译覆盖。 ## 静态 HTML 导出 生成一个无需服务器即可运行的独立 HTML 文件 — 非常适合通过邮件或文件共享： ``` ir-tracker export -o timeline.html # English ir-tracker export --lang ja -o timeline-ja.html # Japanese ``` 两个文件均包含语言切换链接。请将它们放在同一目录中以实现无缝切换。 ## 配置 配置按以下优先级顺序解析： 1. **环境变量**（最高优先级） 2. **配置文件**（`~/.config/ir-tracker/config.toml`） 3. **默认值** ### 配置文件 复制示例并编辑： ``` mkdir -p ~/.config/ir-tracker cp config.example.toml ~/.config/ir-tracker/config.toml ``` 请参考 [`config.example.toml`](config.example.toml) 了解可用字段。 ### 环境变量 ``` export GOOGLE_CLOUD_PROJECT="your-project-id" # Required export GOOGLE_CLOUD_LOCATION="us-central1" # Optional (default: us-central1) export IR_TRACKER_PROJECT="your-project-id" # Tool-specific override for project export IR_TRACKER_LOCATION="us-central1" # Tool-specific override for location export IR_TRACKER_MODEL="gemini-2.5-pro" # Optional (default: gemini-2.5-pro) export IR_TRACKER_TZ="Asia/Tokyo" # Optional (auto-detected from system) ``` `IR_TRACKER_PROJECT` / `IR_TRACKER_LOCATION` 优先于 `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION`。 身份验证方式：`gcloud auth application-default login` 或服务账户密钥。 ## 安全 - 所有数据保留在本地（仅 SQLite 文件）。仅 Vertex AI API 端点接收数据。 - Web UI 仅绑定到 `127.0.0.1`。使用 `--host 0.0.0.0` 时会显示警告。 - Web UI 无需身份验证 — 仅部署在可信网络。 - 通过 nonce 标签的 XML 包装进行提示注入防御（``）。 - 安全头部：`Content-Security-Policy`、`X-Frame-Options: DENY`、`X-Content-Type-Options: nosniff`。 - 所有 SQL 查询使用参数化语句（无字符串插值）。 - DOM 渲染（JavaScript 中不使用 `innerHTML`）用于用户提供的内容。 - 为所有模板启用 Jinja2 自动转义。 ## 架构 ``` ir_tracker/ cli.py — CLI entry point (argparse subcommands) ingest.py — Parse stail/scat export, dedup by ts segmenter.py — Time-window + gap detection + entropy-based splitting analyzer.py — Gemini 2.5 Pro segment analysis + incident summary translator.py — Gemini Flash parallel translation with caching timeline.py — Markdown/JSON timeline + situation export export_html.py — Self-contained static HTML report generator storage.py — SQLite schema with migration support web.py — FastAPI app (timeline, segments, API endpoints) templates/ — Jinja2 HTML (base, timeline, segments) static/ — CSS (light/dark themes) ``` ## 设计文档 - [架构](docs/design/architecture.md) — 组件、数据流、CLI、安全 - [分段](docs/design/segmentation.md) — 时间窗口 + 间隔检测算法 - [分析](docs/design/analysis.md) — LLM 流水线、上下文链式传递、输出模式 ## 与 ai-ir 的关系 | 方面 | ai-ir | ir-tracker | |---|---|---| | 时机 | 事后 | 进行中 | | 输入 | 单次导出 | 持续重新摄取 | | 分析 | 完整对话 | 分段、增量 | | 输出 | 最终报告 | 增长的时间线 | | LLM | OpenAI 兼容 | Vertex AI Gemini（1M 上下文） | | 存储 | 无状态（文件） | 有状态（SQLite） | 两者使用相同的 stail/scat 导出格式。 ## 属于 cybersecurity-series ir-tracker 属于 [cybersecurity-series](https://github.com/nlink-jp/cybersecurity-series) — AI 增强工具，用于威胁情报、事件响应和安全运营。

标签：CSP, gcloud, Google Cloud, IPv6支持, LLM辅助分析, Markdown导出, TCP SYN 扫描, Web UI, X-Content-Type-Options, X-Frame-Options, 上下文链式, 事件摘要, 事件跟踪, 分段分析, 双栏Web界面, 增量分析, 多语言分析, 安全头, 安全标准, 实时事件响应, 情况导出, 情境感知, 持续监控, 提示注入防御, 时间线可视化, 时间线+状态面板, 活动密度图, 消息钻取, 深色浅色主题, 源代码安全, 翻译覆盖, 逆向工具