superduperpiyuxh/narrator-ai

## 🚀 快速开始 ### 前置条件 - **Go** 1.26+ - **Node.js** 18+ - **npm** 或 **yarn** ### 1. 克隆与配置 ``` git clone https://github.com/superduperpiyuxh/narrator-ai.git cd narrator-ai # 创建你的 config cp .env.example backend/.env # 编辑 backend/.env 并添加你的 OpenRouter API key ``` ### 2. 启动后端 ``` cd backend go build -o narrator-ai . ./narrator-ai # Backend 运行在 http://localhost:8080 ``` ### 3. 启动前端 ``` cd frontend npm install npm run dev # Frontend 运行在 http://localhost:3000 ``` ### 4. 打开并登录 访问 **http://localhost:3000** 并登录： | 字段 | 值 | |-------|-------| | Email | `admin@nexus.ai` | | Password | `admin123` | ## 🎯 功能简介 Nexus 会提取原始安全事件日志（SIEM 数据），将它们分组为事件，映射到 MITRE ATT&CK 技术，并使用 AI 生成通俗易懂的攻击叙述 —— 这样您的 SOC 团队无需解析 500 行 JSON 就能了解发生了什么。 ### 痛点问题 安全分析师花费数小时在各种仪表板之间关联事件，手动编写事件报告，并试图向非技术背景的利益相关者解释技术告警。 ### 解决方案 Nexus 会自动完成关联、分组、技术映射和叙述生成。只需输入事件，即可获得故事。 ## ✨ 功能 ### 核心 - **AI 叙述生成** — LLM 读取数百个事件，并编写带有来源追踪的按时间顺序排列的攻击故事 - **MITRE ATT&CK 映射** — 自动识别技术并可视化杀伤链 - **事件分组** — 根据源 IP 和时间窗口自动对相关事件进行分组 - **严重性评分** — 严重 / 高 / 中 / 低 分类 - **实时流** — 基于 SSE 的实时事件摄取，支持自动重连 - **BYOK（自带密钥）** — 使用您自己的 OpenRouter API 密钥进行 LLM 访问 ### 仪表板 - **全宽垂直布局** — 统计卡片、热力图、实时流、事件网格 - **MITRE ATT&CK 热力图** — 跨战术的可视化技术覆盖范围 - **杀伤链视图** — 跨阶段的可视化攻击进程 - **时间线视图** — 带有可展开详情的按时间顺序排列的事件浏览器 - **命令面板** — `Ctrl+K` 即时搜索事件 - **键盘快捷键** — `j/k` 导航，`Enter` 打开，`g+h` 回到主页 ### 安全性 - **JWT 身份验证** — 基于 token 的会话，使用 bcrypt 进行密码哈希处理 - **用户级范围界定** — 每个用户只能看到自己的数据 - **4 层 LLM 安全流水线** — 模式检测 → XML 封装 → 输出验证 → 置信度评分 - **速率限制** — 每个用户每分钟生成 5 次叙述 - **输入净化** — 防止 SQL 注入和 XSS ### 排版 - **Space Grotesk** — 用于 UI 文本的几何无衬线字体 - **Fira Code** — 带有连字功能的等宽字体，用于代码/数据视图 - **CSS 变量系统** — 18+ 个语义 token 用于主题化 ## 🛠️ 技术栈 ### 后端 | 组件 | 技术 | |-----------|-----------| | 语言 | Go 1.26 | | HTTP 框架 | Gin | | 数据库 | SQLite (WAL 模式) | | 认证 | JWT + bcrypt | | LLM 提供商 | OpenRouter (免费模型轮换) | | 速率限制器 | 内存级用户独立限制 | | 实时 | Server-Sent Events (SSE) | ### 前端 | 组件 | 技术 | |-----------|-----------| | 框架 | Next.js 16 (App Router) | | 语言 | TypeScript 5 | | 样式 | Tailwind CSS 4 | | 状态 | SWR + React hooks | | 图标 | Lucide React | | 通知 | React Hot Toast | ### 关键库 - **gin-gonic/gin** — HTTP 框架 - **golang-jwt/jwt** — JWT token - **mattn/go-sqlite3** — SQLite 驱动 - **joho/godotenv** — .env 文件加载 - **swr** — 带有缓存的数据获取 - **tailwind-merge** — Class 去重 - **lucide-react** — 图标系统 ## 📁 项目结构 ``` narrator-ai/ ├── backend/ │ ├── main.go # Entry point, route registration │ ├── internal/ │ │ ├── auth/ │ │ │ ├── service.go # User/Claims, Signup, Login │ │ │ ├── middleware.go # JWT auth middleware │ │ │ └── ratelimit.go # Per-user rate limiter │ │ ├── config/ │ │ │ └── config.go # Environment config │ │ ├── database/ │ │ │ ├── queries.go # Event CRUD, search │ │ │ └── incidents.go # Incident CRUD │ │ └── handler/ │ │ ├── handler.go # Health, events, search │ │ ├── incident_handler.go # Incidents, techniques │ │ ├── narrative_handler.go # LLM narrative generation │ │ ├── feedback_handler.go # User feedback │ │ ├── ingest_handler.go # Event ingestion │ │ └── stream_handler.go # SSE real-time streaming │ ├── Dockerfile │ └── go.mod ├── frontend/ │ ├── src/ │ │ ├── app/ │ │ │ ├── page.tsx # Dashboard (main) │ │ │ ├── layout.tsx # Root layout + fonts │ │ │ ├── globals.css # CSS variables + tokens │ │ │ ├── login/page.tsx # Login │ │ │ ├── signup/page.tsx # Signup │ │ │ ├── settings/page.tsx # API key management │ │ │ └── incidents/[id]/ # Incident detail │ │ ├── components/ │ │ │ ├── CommandPalette.tsx # Cmd+K search │ │ │ ├── TechniqueHeatmap.tsx # MITRE heatmap │ │ │ ├── KillChain.tsx # Kill chain view │ │ │ ├── TimelineView.tsx # Event timeline │ │ │ ├── LiveEventStream.tsx # SSE event ticker │ │ │ ├── IncidentCard.tsx # Incident cards │ │ │ ├── StoryCard.tsx # Narrative display │ │ │ ├── NarrativeSentence.tsx # Sentence with source links │ │ │ └── ... (15+ components) │ │ ├── hooks/ │ │ │ ├── useSSE.ts # SSE with auto-reconnect │ │ │ └── useCommandPalette.ts │ │ └── lib/ │ │ ├── api.ts # Auth-aware API client │ │ ├── types.ts # TypeScript interfaces │ │ └── utils.ts # cn(), formatters │ ├── Dockerfile │ └── package.json ├── data/ # Sample JSON datasets ├── scripts/ # Import utilities ├── docker-compose.yml ├── start.sh # Start backend ├── stop.sh # Stop backend └── .env.example # Configuration template ``` ## 🐳 Docker 设置 ``` # 复制并配置环境 cp .env.example .env # 编辑 .env 并填入你的 OPENROUTER_API_KEY # 构建并运行 docker-compose up --build # 访问 # Frontend: http://localhost:3000 # Backend: http://localhost:8080 ``` ### Docker 服务 | 服务 | 端口 | 描述 | |---------|------|-------------| | `backend` | 8080 | 带有 SQLite 的 Go API 服务器 | | `frontend` | 3000 | Next.js 仪表板 | ## ⚙️ 配置 所有配置都在 `backend/.env` 中（启动时自动加载）： ``` # 必需：用于 LLM 叙述的 OpenRouter API key OPENROUTER_API_KEY=sk-or-v1-your-key-here # 安全：用于 session token 的 JWT secret JWT_SECRET=your-random-secret-here # 认证：默认管理员密码 ADMIN_PASSWORD=changeme-in-production # Server PORT=8080 # Database DATABASE_PATH=./narratorai.db # 示例数据 DATA_DIR=../data/sample_json_20260301 ``` ### 获取 OpenRouter API 密钥 1. 前往 [openrouter.ai/keys](https://openrouter.ai/keys) 2. 创建一个免费账户 3. 生成 API 密钥 4. 将其添加到 `backend/.env` Nexus 使用带有自动轮换机制的免费模型： - `gpt-4o-mini` - `llama-4-maverick:free` - `nemotron-70b:free` ## 📡 API 参考 ### 公共端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/health` | 健康检查 | | `POST` | `/api/auth/signup` | 创建账户 | | `POST` | `/api/auth/login` | 登录 | ### 受保护的端点（需要 `Authorization: Bearer `） | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/api/auth/me` | 当前用户信息 | | `GET` | `/api/auth/settings` | 获取 API 密钥 | | `PUT` | `/api/auth/settings` | 更新 OpenRouter 密钥 | | `GET` | `/api/events` | 列出事件 | | `GET` | `/api/events/search?q=` | 搜索事件 | | `GET` | `/api/stats` | 事件统计 | | `POST` | `/api/import` | 导入本地数据 | | `GET` | `/api/incidents` | 列出事件 | | `GET` | `/api/incidents/:id` | 事件详情 | | `GET` | `/api/incidents/:id/events` | 事件相关的事件 | | `GET` | `/api/incidents/stats` | 事件统计 | | `GET` | `/api/techniques` | 所有 MITRE 技术 | | `GET` | `/api/techniques/counts` | 技术计数 | | `POST` | `/api/incidents/:id/narrative` | 生成 AI 叙述 | | `GET` | `/api/incidents/:id/narrative` | 获取叙述 | | `POST` | `/api/feedback` | 提交反馈 | | `POST` | `/api/v1/ingest` | 摄取事件 (JSON) | | `POST` | `/api/v1/ingest/file` | 从文件摄取 | | `GET` | `/api/v1/stream` | SSE 事件流 | | `POST` | `/api/v1/stream` | 通过 SSE 批量摄取 | | `POST` | `/api/v1/event` | 摄取单个事件 | | `POST` | `/api/v1/auto-group` | 自动分组事件 | ### 示例：生成叙述 ``` curl -X POST http://localhost:8080/api/incidents/1/narrative \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" ``` 响应： ``` { "narrative": { "id": 1, "summary": "Attacker gained initial access via brute force...", "sentences": [...], "confidence": 0.87, "model_used": "gpt-4o-mini", "tokens_used": 1247, "generation_time_ms": 2341 } } ``` ### 示例：摄取事件 ``` curl -X POST http://localhost:8080/api/v1/ingest \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "timestamp": "2026-03-01T10:30:00Z", "event_type": "authentication", "hostname": "dc01.corp.local", "source_ip": "10.0.0.5", "user_name": "admin", "severity": "high" } ]' ``` ## 🧪 测试 ### 后端测试 ``` cd backend go test ./... -v ``` ### 前端构建 ``` cd frontend npm run build ``` ### 运行所有检查 ``` # Backend cd backend && go test ./... -count=1 && go build -o narrator-ai . # Frontend cd frontend && npm run build ``` ## 🎹 键盘快捷键 | 键位 | 操作 | |-----|--------| | `Ctrl+K` | 打开命令面板 | | `/` | 聚焦搜索输入框 | | `j` | 向下移动至下一个事件 | | `k` | 向上移动至上一个事件 | | `Enter` | 打开所选事件 | | `g` 然后 `h` | 前往主页 | | `g` 然后 `s` | 前往设置 | | `?` | 显示键盘快捷键 | | `Escape` | 关闭模态框 / 清除搜索 | ## 📊 样本数据 Nexus 包含一个包含跨多台主机的 **442,982 个安全事件** 的样本数据集： - 身份验证事件（登录、失败、锁定） - 进程活动（命令执行、进程创建） - 网络活动（连接、DNS、防火墙） - 文件活动（创建、修改、删除） 事件被自动分组为 **28,231 个安全事件**，并识别出 **15 种 MITRE ATT&CK 技术**。 ### 导入您自己的数据 ``` # 通过 API curl -X POST http://localhost:8080/api/v1/ingest \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '[{"timestamp":"...", "event_type":"...", ...}]' # 通过文件 curl -X POST http://localhost:8080/api/v1/ingest/file \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@your_events.json" ``` ### 事件 Schema ``` { "timestamp": "2026-03-01T10:30:00Z", "event_type": "authentication|process_activity|network_activity|file_activity", "hostname": "dc01.corp.local", "source_ip": "10.0.0.5", "dest_ip": "10.0.0.1", "user_name": "admin", "process_name": "powershell.exe", "command_line": "powershell -enc ...", "file_path": "C:\\Windows\\temp\\payload.exe", "protocol": "TCP", "port": 443, "log_type": "windows-security", "session_id": "0x3E7", "parent_process": "explorer.exe", "severity": "critical|high|medium|low" } ``` ## 🏗️ 架构 ``` ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ Frontend │────▶│ Backend │────▶│ SQLite │ │ Next.js 16 │ │ Go + Gin │ │ (WAL) │ │ Port 3000 │ │ Port 8080 │ │ │ └─────────────┘ └──────┬───────┘ └──────────────┘ │ ┌──────▼───────┐ │ OpenRouter │ │ LLM API │ └──────────────┘ ``` ### 数据流 1. **摄取** → 事件存储在 SQLite 中 2. **分组** → 相关事件自动聚类为事件 3. **分析** → 映射 MITRE ATT&CK 技术 4. **叙述** → LLM 生成按时间顺序排列的攻击故事 5. **展示** → 仪表板显示带有来源追踪的叙述 ## 🔒 安全性 - **JWT token**，带有可配置的 secret - **bcrypt 密码哈希**（成本因子为 10） - **用户级数据隔离** — 用户只能看到自己的事件 - **4 层 LLM 安全流水线** — 防止 prompt 注入 - **速率限制** — 每个用户每分钟生成 5 次叙述 - **输入净化** — 防止 SQL 注入和 XSS - **CORS 配置** — 可配置的允许来源 ## 🤝 贡献 1. Fork 该仓库 2. 创建一个功能分支 (`git checkout -b feature/amazing`) 3. 提交您的更改 (`git commit -m 'Add amazing feature'`) 4. 推送到该分支 (`git push origin feature/amazing`) 5. 发起一个 Pull Request ## 📄 许可证 该项目基于 MIT 许可证授权 — 详见 [LICENSE](LICENSE) 文件。 ## 🙏 致谢 - [MITRE ATT&CK](https://attack.mitre.org/) — 威胁情报框架 - [OpenRouter](https://openrouter.ai/) — LLM API 聚合 - [Gin](https://gin-gonic.com/) — Go HTTP 框架 - [Next.js](https://nextjs.org/) — React 框架 - [Tailwind CSS](https://tailwindcss.com/) — 实用优先的 CSS - [Space Grotesk](https://fonts.google.com/specimen/Space+Grotesk) — 展示字体 - [Fira Code](https://fonts.google.com/specimen/Fira+Code) — 等宽字体

**由 [superduperpiyuxh](https://github.com/superduperpiyuxh) 用 💪 构建** *如果这个项目对您有帮助，请给它一个 ⭐*

标签：DLL 劫持, EVTX分析, Go, Ruby工具, SOC仪表盘, 大语言模型, 安全运营, 扫描框架, 日志审计, 请求拦截