Zaid-Ahmed-Ansari/Argus

# Argus — SOC 分析师助手 [](https://argus-gules.vercel.app/) [](https://nextjs.org/) [](https://react.dev/) [](https://www.typescriptlang.org/) [](https://www.prisma.io/) [](https://www.postgresql.org/) [](https://ai.google.dev/) [](LICENSE) [](https://argus-gules.vercel.app/research) **Argus** 是一个 AI 辅助的安全运营中心 (SOC) 平台，它将嘈杂的身份验证和安全日志转换为结构化的事件记录 —— 包括攻击分类、MITRE ATT&CK 映射、调查时间线以及与 playbook 对齐的建议 —— 并由一个可复现的研究实验室提供支持，用于评估基于 LLM 的分诊。 **在线应用：** [https://argus-gules.vercel.app](https://argus-gules.vercel.app) **源代码：** [github.com/Zaid-Ahmed-Ansari/Argus](https://github.com/Zaid-Ahmed-Ansari/Argus) ## 目录 - [概述](#overview) - [截图](#screenshots) - [核心功能](#key-capabilities) - [架构](#architecture) - [技术栈](#tech-stack) - [研究平台](#research-platform) - [快速开始（本地）](#quick-start-local) - [数据库：Docker 对比 Supabase](#database-docker-vs-supabase) - [环境变量](#environment-variables) - [运行实验](#running-experiments) - [项目结构](#project-structure) - [API 参考](#api-reference) - [部署](#deployment) - [安全](#security) - [文档](#documentation) - [作者](#author) - [许可证](#license) ## 概述 SOC 分析师在归类事件或决定后续步骤之前，会花费大量时间解析原始日志行。Argus 通过统一的工作流解决了这一瓶颈： 1. **上传** SSH、VPN、Web 服务器或 SIEM 日志导出文件（粘贴或文件上传）。 2. **分析** 使用 Google Gemini，可选择性地通过基于 MITRE ATT&CK 和 SOC playbook 知识的 hybrid RAG 进行增强。 3. **调查** 在带有时间线、严重性统计、日志搜索和交互式调查工作区的持久化 dashboard 上进行。 4. **评估** 涵盖 10 个标记攻击场景和 15 个研究问题的可复现基准测试。 Argus 既是一个**生产级分析工具**（包含身份验证、持久化事件、上传 pipeline），也是一个**研究工具**（包含真值数据集、批量实验运行器和公开的 metrics dashboard）。 | 受众 | 获得的功能 | |----------|--------------| | **访客和分析人员** | 在线演示、注册、上传示例日志、查看结构化的分诊输出 | | **开发者** | 可以使用 Docker Postgres 在本地运行或部署到 Vercel + Supabase 的全栈 Next.js 应用 | | **研究人员** | 10 个场景的语料库、4 个活跃实验维度、10 个评估 metrics、位于 `/research` 的基准结果 | ## 截图 ### 产品 | 首页 | 调查工作区 | |----------|-------------------------| |  |  | | 攻击链图 | MITRE ATT&CK 映射 | |--------------------|----------------------| |  |  | ### 研究实验室 | 研究指挥中心 | 实验对比 | |-------------------------|----------------------| |  |  | ## 核心功能 ### 分析师工作流 - **AI 事件分析** — 对攻击模式进行分类，分配严重性（`LOW` → `CRITICAL`），并从原始日志行构建事件时间线。 - **Hybrid RAG** — 通过 PostgreSQL 全文搜索、向量相似度（JSONB embeddings）或倒数排名融合（reciprocal-rank fusion，`RAG_RETRIEVER_MODE=hybrid`）检索 MITRE 和 playbook 片段。 - **SOC 就绪输出** — 结构化摘要、MITRE 风格的技术标签以及可操作的调查建议。 - **日志搜索** — 跨存储日志内容和事件历史记录进行全文搜索。 - **持久化记录** — 每次上传和分析都会按账户保存，并附带元数据、时间线和便于审计的存储。 - **PII 脱敏** — 电子邮件、IP、用户名和 token 在存储前以及向 LLM 发送 prompt 之前会被屏蔽（`src/utils/redact-pii.ts`）。 ### 研究与评估 - **10 个标记场景** — 从暴力破解到内部威胁，每个都包含 `sample.log` + `ground-truth.json`。 - **4 个活跃实验** — RAG 对比无 RAG、原始对比结构化输入、跨场景基准测试、2×2 因子矩阵。 - **10 个 metrics** — 准确率、攻击类型/严重性/MITRE 准确率、调查质量、建议质量、幻觉率、延迟等。 - **公开研究 UI** — `/research`（概述）、`/research/questions`、`/research/results`、`/research/datasets`、`/research/experiments`、`/research/reports`。 ## 架构 Argus 是一个**单一的 Next.js 16 应用程序**（App Router）。所有服务端逻辑都在 Route Handlers 中运行 —— 没有独立的 Python 或 FastAPI 服务。 ``` flowchart TB subgraph Client UI[Landing · Dashboard · Investigation · Research] end subgraph NextJS["Next.js 16 (App Router)"] API[API Route Handlers] Auth[Better Auth] Orch[Analysis Orchestrator] RAG[Hybrid RAG Retriever] Eval[Experiment Evaluator] end subgraph Data PG[(PostgreSQL)] UT[UploadThing] end subgraph External Gemini[Google Gemini API] end UI --> API API --> Auth API --> Orch Orch --> RAG Orch --> Gemini RAG --> PG API --> PG API --> UT Eval --> Orch ``` ### 分析 pipeline ``` Upload logs → validate + redact PII → persist LogFile (PostgreSQL FTS indexed) → AnalysisOrchestrator → [optional] Hybrid RAG: FTS + vector retrieval over DocumentChunk → GeminiProvider.complete() → persist Analysis (attackType, severity, timeline, recommendations) → Investigation workspace ``` ### 分层代码库 ``` ┌─────────────────────────────────────────────────────────┐ │ Presentation (src/app, src/components, src/features) │ ├─────────────────────────────────────────────────────────┤ │ API Routes (validate → delegate → respond) │ ├─────────────────────────────────────────────────────────┤ │ Services (AI, RAG, repositories, search, eval) │ ├─────────────────────────────────────────────────────────┤ │ Prisma ORM → PostgreSQL │ └─────────────────────────────────────────────────────────┘ ``` 有关 SOLID 映射、扩展点和提供者抽象，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 技术栈 | 层级 | 技术 | |-------|------------| | 框架 | Next.js 16, React 19, TypeScript 5 | | 样式 | Tailwind CSS 4, shadcn/ui, Framer Motion | | 数据库 | 通过 Prisma 7 的 PostgreSQL 16 | | 身份验证 | Better Auth（Postgres 中的 session） | | AI | Google Gemini (`gemini-2.5-flash`, `gemini-embedding-001`) | | RAG | PostgreSQL FTS + JSONB 向量 embeddings（无需 pgvector） | | 上传 | 本地磁盘（开发）· UploadThing（Vercel 生产环境） | | 状态/数据 | TanStack Query, Zustand, Recharts, React Flow | | 托管 | Vercel（应用）+ Supabase 或 Docker（数据库） | ## 研究平台 Argus 为基于 LLM 的 SOC 分诊提供了一个**可复现的评估框架**。研究人员可以在实时网站上探索结果，或者在本地复现实验。 ### 研究问题 (RQ1–RQ15) | ID | 问题 | |----|----------| | **RQ1** | Hybrid RAG 是否能提高基于 LLM 的 SOC 分诊在多种攻击场景下的准确率？ | | **RQ2** | 与原始日志相比，结构化的安全事件是否能改善攻击分类？ | | **RQ3** | LLM 能否根据稀疏的日志证据，将事件可靠地映射到 MITRE ATT&CK 技术？ | | **RQ4** | 对于建议质量，混合（FTS + 语义）检索是否优于无检索？ | | **RQ5** | 幻觉率如何随场景难度变化？ | | **RQ6** | LLM 能否仅使用身份验证日志区分密码喷洒和暴力破解？ | | **RQ7** | 结合 RAG 和结构化输入是否会产生叠加增益？ | | **RQ8** | LLM 生成的调查时间线是否足够完整，可以交给分析师处理？ | | **RQ9** | 与 playbook 对齐的建议在真值评估中得分是否更高？ | | **RQ10** | 哪些攻击场景产生的攻击类型准确率最低？ | | **RQ11** | 严重性分类是否比攻击类型分类更可靠？ | | **RQ12** | 在困难场景下，RAG 是否减少了捏造的攻击类型？ | | **RQ13** | 每个场景下混合检索的延迟成本是多少？ | | **RQ14** | 分析师效用得分能否作为人工评判分诊质量的代理指标？ | | **RQ15** | 在相同的测试夹具上重新运行时，跨场景基准测试的稳定性如何？ | 实验的完整映射：[`src/lib/research-catalog.ts`](src/lib/research-catalog.ts) · 在线 UI：[/research/questions](https://argus-gules.vercel.app/research/questions) ### 场景语料库（10 个测试夹具） | 场景 | MITRE | 难度 | |----------|-------|------------| | 暴力破解 | T1110.001 | 简单 | | 密码喷洒 | T1110.003 | 简单 | | 撞库 | T1110.004 | 中等 | | 权限提升 | T1548 | 中等 | | 横向移动 | T1021 | 困难 | | 可疑管理员活动 | T1078.004 | 中等 | | 账户接管 | T1078 | 困难 | | 数据渗出 | T1041 | 困难 | | Web Shell 活动 | T1505.003 | 中等 | | 内部威胁 | T1530 | 困难 | 每个场景都位于 `datasets//` 下，包含 `sample.log` 和 `ground-truth.json`（攻击类型、严重性、MITRE ID、必需/禁止的关键词、时间线预期、playbook 主题）。 ### 活跃实验 | ID | 名称 | 对比内容 | |----|------|------------------| | **exp-002** | RAG 对比 无 RAG | `usedRag: false` 对比开启 hybrid RAG | | **exp-003** | 原始对比结构化 | 原始日志行对比解析后的安全事件 | | **exp-004** | 跨场景基准测试 | 在所有 10 个测试夹具上进行 Hybrid RAG | | **exp-005** | RAG × 输入矩阵 | 2×2 因子设计（RAG × 输入格式） | ### 评估 metrics | Metric | 描述 | |--------|-------------| | `accuracy` | 加权综合得分 | | `attack_type_accuracy` | 与标记的攻击类型匹配 | | `severity_accuracy` | 精确的严重性枚举匹配 | | `mitre_mapping_accuracy` | 输出中包含预期的技术 ID | | `investigation_quality` | 时间线深度、关键词、实体召回率 | | `recommendation_quality` | SOC playbook 主题重叠度 | | `triage_completeness` | 所有输出字段均已填充 | | `analyst_utility_score` | 人工代理综合指标 | | `hallucination_rate` | 禁止词条命中数（越低越好） | | `latency_ms` | 分析实际耗时 | 实现：[`src/services/eval/metrics.ts`](src/services/eval/metrics.ts) ### 论文大纲（研究产出） `/research/reports` 部分遵循标准的学术结构：摘要、引言、相关工作、方法论、实验设计、结果、讨论、局限性、未来工作 — 请参阅 [`src/lib/research-catalog.ts`](src/lib/research-catalog.ts)（`PAPER_SECTIONS`）。 ### 生产环境的基准结果 提交在 `experiments/baseline/` 下的基准 JSON 为 Vercel 上的图表提供数据支持（临时的 serverless 文件系统无法持久化批量运行结果）。如需刷新： ``` npm run experiment:all npm run experiment:baseline git add experiments/baseline/ ``` ## 快速开始（本地） ### 前置条件 - **Node.js** 20.x 或 22.x - **npm** 10+ - **PostgreSQL** — 通过 [Docker](#option-a-docker-recommended-for-local-dev) 或本地安装 - **Google AI Studio** API key（[在此获取](https://aistudio.google.com/apikey)） ### 1. 克隆并安装 ``` git clone https://github.com/Zaid-Ahmed-Ansari/Argus.git cd Argus npm install ``` ### 2.置环境 ``` cp .env.example .env ``` 编辑 `.env` — 至少设置 `DATABASE_URL`、`DIRECT_URL`、`BETTER_AUTH_SECRET` 和 `GEMINI_API_KEY`。请参阅 [环境变量](#environment-variables)。 ### 3. 启动 PostgreSQL **Docker（推荐）：** ``` docker compose up -d ``` **或者**将 `DATABASE_URL` / `DIRECT_URL` 指向现有的 Postgres 实例。 ### 4. 初始化数据库 ``` npm run db:migrate # apply Prisma migrations npm run db:seed:knowledge # seed MITRE + playbook knowledge npm run db:embed # generate Gemini embeddings (requires GEMINI_API_KEY) ``` 或者使用单个命令运行所有生产环境设置步骤： ``` npm run db:setup:prod ``` ### 5. 运行开发服务器 ``` npm run dev ``` 打开 [http://localhost:3000](http://localhost:3000) → **注册** → **上传** → 粘贴或上传 `datasets/brute_force/sample.log` → 运行分析。 ## 数据库：Docker 对比 Supabase Argus **仅使用 PostgreSQL** 进行持久化。身份验证由 **Better Auth** 处理（而不是 Supabase Auth）。你可以使用任何 Postgres 主机。 ### 选项 A：Docker（推荐用于本地开发） 使用附带的 `docker-compose.yml` — 无需云账户。 ``` # 启动 Postgres 16 docker compose up -d # 验证健康状态 docker compose ps ``` 在 `.env` 中将两个 URL 都设置为 Docker 连接字符串： ``` DATABASE_URL="postgresql://postgres:postgres@localhost:5432/argus" DIRECT_URL="postgresql://postgres:postgres@localhost:5432/argus" DATABASE_POOL_MAX=10 UPLOAD_DIR=storage ``` 然后进行迁移并填充种子数据： ``` npm run db:setup:prod npm run dev ``` **停止/重置：** ``` docker compose down # stop container docker compose down -v # stop + delete data volume (full reset) ``` | Docker | Supabase（生产环境） | |--------|------------------------| | `localhost:5432` | 事务池化器（Transaction pooler）端口 **6543** (`?pgbouncer=true`) | | `DATABASE_URL` 和 `DIRECT_URL` 使用相同的 URL | `DIRECT_URL` 使用会话池化器（Session pooler）端口 **5432** 进行迁移 | | 本地文件上传 (`UPLOAD_DIR=storage`) | Vercel 上必须使用 UploadThing | | 不需要 SSL | 默认启用 SSL | ### 选项 B：Supabase（推荐用于生产环境） Supabase 提供带有备份、连接池和 dashboard 的托管 PostgreSQL。Argus **不**使用 Supabase Auth — 仅使用数据库连接字符串。 1. 在 [supabase.com](https://supabase.com) 创建一个项目。 2. 复制 **Transaction pooler** (6543) → 设置为带有 `?pgbouncer=true` 的 `DATABASE_URL`。 3. 复制 **Session pooler** (5432) → 设置为 `DIRECT_URL`。 4. 针对远程数据库运行一次 `npm run db:setup:prod`。 5. 使用 [docs/supabase-setup.md](docs/supabase-setup.md) 中的环境变量部署到 Vercel。 完整的分步指南：**[docs/supabase-setup.md](docs/supabase-setup.md)** ### 为什么使用 Better Auth + Postgres（而不是 Supabase Auth）？ Argus 是服务端优先的：Prisma 拥有 schema，API 路由实施访问控制，Gemini 密钥永远不会到达浏览器。Better Auth 将用户和 session 存储在与事件和 RAG 数据相同的 Postgres 数据库中 —— 这与这种架构非常契合。 ## 环境变量 复制 [`.env.example`](.env.example) 并进行配置： | 变量 | 必需 | 描述 | |----------|----------|-------------| | `DATABASE_URL` | 是 | Postgres 连接（应用 runtime） | | `DIRECT_URL` | 是 | Postgres 连接（Prisma 迁移） | | `BETTER_AUTH_SECRET` | 是 | 随机密钥，至少 32 个字符 (`openssl rand -base64 32`) | | `BETTER_AUTH_URL` | 是 | 应用 origin，例如 `http://localhost:3000` | | `NEXT_PUBLIC_APP_URL` | 是 | 与 `BETTER_AUTH_URL` 相同（用于元数据/链接） | | `GEMINI_API_KEY` | 是* | Google Gemini，用于分析和 embeddings | | `UPLOADTHING_TOKEN` | 生产环境 | Vercel 上必需（没有持久化磁盘） | | `UPLOAD_DIR` | 本地 | `storage` — 本地上传目录 | | `RAG_RETRIEVER_MODE` | 否 | `fts` · `vector` · `hybrid`（默认：`hybrid`） | | `GEMINI_MODEL` | 否 | 默认：`gemini-2.5-flash` | | `GEMINI_EMBEDDING_MODEL` | 否 | 默认：`gemini-embedding-001` | | `DATABASE_POOL_MAX` | 否 | 默认：`10` | \*如果没有 `GEMINI_API_KEY`，分析将返回一个占位符 stub。 ## 运行实验 ``` # 单个 scenario (brute_force default) npm run experiment:run # 全部 10 个 scenarios × 所有 experiment configs npm run experiment:all # 特定 scenarios npm run experiment:scenario -- brute_force password_spray # 仅 RAG vs no-RAG (exp-002) npm run experiment:rag # 导出 Vercel /research charts 的 baseline npm run experiment:baseline ``` | 输出 | 位置 | |--------|----------| | 临时运行结果 | `experiments/results/*.json`（gitignored） | | 提交的基准结果 | `experiments/baseline/`（随部署提供） | | 公开 API | `GET /api/experiments/results` | | 研究 UI | [localhost:3000/research](http://localhost:3000/research) | 请参阅 [docs/experiments.md](docs/experiments.md) 和 [datasets/README.md](datasets/README.md)。 ## 项目结构 ``` argus/ ├── src/ │ ├── app/ # Next.js routes (pages + API) │ ├── components/ # Shared UI (layout, shadcn) │ ├── features/ # Feature modules │ │ ├── landing/ # Marketing home page │ │ ├── incidents/ # Incident list & cards │ │ ├── investigation/ # Investigation workspace │ │ ├── research/ # Research lab UI │ │ └── experiments/ # Public experiments page │ ├── services/ # AI, RAG, eval, repositories │ └── lib/ # Auth, metadata, research catalog ├── prisma/ # Schema, migrations, seed scripts ├── datasets/ # 10 labeled attack scenarios + knowledge ├── experiments/ │ ├── configs/ # Experiment JSON configs │ ├── baseline/ # Committed baseline results │ └── results/ # Local run output (gitignored) ├── scripts/ # Batch experiment runner ├── docs/ # Architecture, API, deployment guides ├── public/ │ └── screenshots/ # README screenshots └── docker-compose.yml # Local PostgreSQL ``` ## API 参考 | Endpoint | 身份验证 | 描述 | |----------|------|-------------| | `POST /api/analyze` | 是 | 对上传的日志运行 AI 分析 | | `POST /api/upload` | 是 | 上传日志文件 | | `GET /api/incidents` | 是 | 列出用户的事件 | | `GET /api/search/logs` | 是 | 全文日志搜索 | | `POST /api/evaluate` | 是 | 对预测结果与真值进行评分 | | `GET /api/experiments/results` | 公开 | 汇总实验 metrics | 完整参考：[docs/api.md](docs/api.md) ## 部署 生产技术栈：**GitHub → Vercel (Next.js) → Supabase (PostgreSQL) → Gemini + UploadThing** ``` # Vercel build (自动运行 migrations) npm run vercel-build ``` 清单和环境变量：**[docs/production-deployment.md](docs/production-deployment.md)** 发布前质量保证：**[docs/LAUNCH_CHECKLIST.md](docs/LAUNCH_CHECKLIST.md)** | 生产 URL | 值 | |----------------|-------| | 应用 | `https://argus-gules.vercel.app` | | `BETTER_AUTH_URL` | 相同的 HTTPS origin | | `NEXT_PUBLIC_APP_URL` | 相同的 HTTPS origin | ## 安全 - 通过 Better Auth 进行 session 管理（HTTP-only cookies）；受保护的路由位于 `src/proxy.ts` - 对 analyze、upload、search 和 evaluate endpoint 施加速率限制 - middleware 中的安全 header（CSP, `X-Frame-Options`） - 在存储和 LLM prompt 之前进行 PII 脱敏 - 密钥仅存在于环境变量中 — 永不提交到代码库 私下报告漏洞：[SECURITY.md](SECURITY.md) ## 文档 | 文档 | 主题 | |----------|-------| | [docs/architecture.md](docs/architecture.md) | 系统设计、RAG pipeline、扩展点 | | [docs/api.md](docs/api.md) | REST route handlers | | [docs/data-model.md](docs/data-model.md) | Prisma schema 和 enums | | [docs/experiments.md](docs/experiments.md) | 实验方法论 | | [docs/research-roadmap.md](docs/research-roadmap.md) | 研究平台概述 | | [docs/rag-roadmap.md](docs/rag-roadmap.md) | RAG 检索 pipeline | | [docs/supabase-setup.md](docs/supabase-setup.md) | Supabase PostgreSQL 设置 | | [docs/production-deployment.md](docs/production-deployment.md) | Vercel 生产环境部署 | ## 作者 **Zaid Ahmed Ansari** — [GitHub](https://github.com/Zaid-Ahmed-Ansari) · [Argus 代码库](https://github.com/Zaid-Ahmed-Ansari/Argus) 作为一个网络安全研究和作品集项目构建：一个面向分析师的 SOC 助手，并配有一个用于基于 LLM 的日志分诊的可复现评估实验室。 ## 许可证 [MIT](LICENSE) — 详情请参阅 [LICENSE](LICENSE)。

标签：DLL 劫持, LLM评估, Ollama, 大语言模型, 威胁情报, 安全运营, 开发者工具, 扫描框架, 自动化攻击