overcuriousity/Vestigo

vestigo (拉丁语) — 我追踪痕迹；我进行调查。

一个取证级别的后期事后日志调查平台。 Vestigo 能够大规模摄取兼容 Timesketch 的时间线，让分析师通过类似 ELK 的 Web 界面探索事件，并通过将每一行日志嵌入到向量数据库中，以统计和向量的方式发现异常。它的构建在需要时可以在气隙隔离环境下运行——在每一步都保证可重现、可审计的处理过程。 ## 为什么开发 事件响应人员和取证分析师处理的是海量基于时间线的数据集（Plaso 输出、Windows 事件日志、端点遥测、云审计跟踪）。通常的选项迫使人们进行权衡：完整的 SIEM 昂贵、嘈杂且非时间线原生；笔记本脚本灵活但不可重现且不利于团队协作；[Timesketch](https://github.com/google/timesketch) 功能强大但运维负担重。Vestigo 旨在成为一个专注的中间选择——摄取海量日志，像 ELK stack 一样探索它们，让经典的统计检测器和本地嵌入技术都能大海捞针，而无需运行集群。 ## 功能 ### 摄取 - 针对于 Plaso CSV/JSONL 和通用 CSV/JSONL 的流式解析器，可处理数十 GB 的数据，而无需将所有内容加载到内存中。 - 每个摄取的文件（**Source**）都经过 SHA-256 哈希处理，并按内容寻址保留以供重新下载——从架构上保证了取证来源和不可变性。 - 支持命令行（`vestigo ingest`），因此摄取过程可在 Web UI 之外进行脚本化和可重现操作。对于非常大的文件（几十 GiB 及以上），优先使用 CLI 而不是 Web 上传：它直接从磁盘流式读取——没有 HTTP 上传，没有临时副本，也没有 `VESTIGO_MAX_UPLOAD_BYTES` 的限制——并提供实时进度/预计完成时间(ETA)以及用于保管链的每用户 Source 归属。请参阅 `vestigo ingest --help`。 - 一个独立的、由用户触发的嵌入任务（`vestigo embed` / 嵌入向导）在摄取后计算向量——除非您主动要求，否则摄取本身保持快速且无嵌入状态。 - 可下载的转换器脚本（nginx, filterlog, suricata, cloudtrail, pcap 等）在客户端将特定供应商的日志格式解析为强类型的列式 **Parquet**，服务器随后通过 Arrow record batch 进行批量插入——在处理多 GB 的日志时，这比逐行处理 CSV 快一个数量级，同时保留相同的逐行取证来源。请参阅 [`docs/TECH_STACK.md`](docs/TECH_STACK.md) §3.4a。 ### 探索器 - 虚拟化的、类似 ELK 的事件网格：可调整大小/可选择的列，舒适/紧凑的密度，对眼睛友好的明/暗主题。 - 全文和结构化过滤（artifact 类型、来源、标签、任意字段的相等/排除），下推到 ClickHouse 中执行，而不是在客户端解析。 - 带有异常覆盖标记的时间直方图，具有跳转时间功能的双向键集分页。 - 标签/评论注释，支持批量应用，可点击的包含/排除标签分面，以及保存的视图。 - 遵循活动过滤器的流式 CSV/JSONL 导出，包含取证列（`source_id`, `artifact`, `content_hash`, `file_hash`）。 ### 异常检测 - **九种统计检测器**，灵感来源于 [`ait-aecid/logdata-anomaly-miner`](https://github.com/ait-aecid/logdata-anomaly-miner) 并 直接针对 ClickHouse 运行——无需嵌入：值新颖性、频率激增/静默、时间戳顺序、数值范围、字符集新颖性、熵异常、比例偏移、间隔节奏以及从未见过的事件序列。 - 基于本地计算嵌入 (Qdrant) 的**语义相似性搜索**：跨不同的字面内容，查找与已知恶意行*含义*相同的事件。 - 显式的**基线与嫌疑窗口对比**：每个检测器都可以将已知良好时期与调查中的窗口进行比较，而不是仅仅进行自我基线比对。 - 调查结果带有统一的处理流程（确认/驳回），手动确认的调查结果在重新扫描后依然保留。 - 请参阅[异常检测](docs/ANOMALY_DETECTION.md)以获取每个检测器的通俗语言解释——它能捕捉什么、如何评分，以及它的调节参数。 ### 身份验证、访问控制和审计 - 针对本地账户的 Session-cookie 身份验证，具有预设的一次性引导管理员账户，并为已经拥有身份提供程序的团队提供可选的 OIDC SSO。 - 案件级别的 RBAC：个人案件（仅限所有者）或团队案件（成员/经理角色），在每个案件范围内的 endpoint 上进行集中强制执行。 - 仅追加的审计跟踪，涵盖每一个变更操作和身份验证事件，支持自助查询/导出和全局管理员查询/导出。 - 通过 Server-Sent Events 进行实时协作：查看同一个案件的分析师无需手动刷新，就能看到彼此的注释和标签出现。 ### 取证严谨性 - 不可变的、经过哈希处理的 Sources；解析器和嵌入配置也经过哈希处理，因此更改其中任何一个都会改变其身份（一个新的 Qdrant collection，一个新的可重现性边界），而不是在不经意间直接篡改结果。 - 气隙隔离/默认离线操作是一个硬性设计目标——没有代码路径会无条件访问网络（OIDC SSO 是唯一的、经过深思熟虑且有文档记录的、由操作员主动启用的例外）。 ## 架构 - **后端**：Python 3.13+，FastAPI/Uvicorn，使用 `uv` 管理。它与三个外部服务通信——PostgreSQL（元数据）、ClickHouse（事件，主要日志数据存储）和 Qdrant（向量）。它们都不在应用程序内部运行。 - **前端**：React 19 + Vite + TypeScript，作为静态构建版本直接由 Uvicorn 提供服务（无需单独的 Web 服务器）。 - **CLI**：基于 Typer 的 `vestigo` 命令映射了 API/UI，用于支持脚本化和对离线友好的使用场景。 ## 快速开始 ### 1. 提供后端支持服务 原生运行 PostgreSQL、ClickHouse 和 Qdrant，或者使用参考的 Docker/Podman Compose 配置： ``` docker compose up -d ``` 该 compose 文件仅在 `127.0.0.1` 上发布这三个服务——它们以默认或无凭据状态运行，因此故意使其无法从局域网访问。应用程序的默认设置（`.env.example`）通过这些 localhost 端口进行连接。 ### 2. 安装并运行应用程序 ``` uv sync uv run vestigo-web ``` 基础安装不包含本地嵌入 stack（约 2 GB 的 torch + sentence-transformers）。要使用本地嵌入（`vestigo embed`，语义搜索），请安装额外组件：`uv sync --extra embeddings`。或者，将 `VESTIGO_EMBEDDING_API_BASE_URL` 指向兼容 OpenAI 的远程 endpoint——不需要额外安装。如果两者都不配置，嵌入 endpoint 将返回明确的 503 错误，并且 `/api/health` 会报告 `embeddings_available: false`；其他一切功能正常。 API 可在 `http://localhost:8080` 访问（OpenAPI 文档位于 `/api/docs`），提供从 `frontend/dist` 构建的前端（首次运行时自动构建）。 对于活跃的前端开发，请在 `frontend/` 目录下运行 `npm install && npm run dev` 并同时运行 `uv run vestigo-web`——请参阅 `frontend/README.md`。配置由环境变量驱动（`VESTIGO_*` 变量）；完整列表请参阅 `.env.example`。 ### Docker/Podman Compose（可选的容器化应用） 已发布的应用程序镜像已发布到 GitHub Container Registry： ``` docker pull ghcr.io/overcuriousity/vestigo:latest ``` `docker-compose.yml` 附带了一个**被注释掉的** `app` 服务，该服务从本地检出（`Dockerfile`）构建镜像，并通过 compose 内部网络连接到支持服务。取消注释，然后执行 `docker compose up -d`（或 `podman compose up -d`），即可通过一条命令启动整个技术栈。 **此 compose 文件是参考/评估部署，不是生产环境加固指南。** 它附带固定的、众所周知的默认设置，因此开箱即用：`postgres`/`vestigo` 数据库凭据，无 ClickHouse/Qdrant 身份验证，以及一次性的 `VESTIGO_ADMIN_PASSWORD` 引导密钥（首次登录时强制轮换）。对于任何允许超出个人范围访问的部署——以及通常对于实际生产环境的使用——请优先使用原生的 `uv run vestigo-web` 安装方式，配合具有适当凭据且受网络限制的后端服务，并设置您自己的 `VESTIGO_ADMIN_PASSWORD`/`VESTIGO_*_PASSWORD`/`VESTIGO_QDRANT_API_KEY` 值，而不是使用 compose 默认值。 ### 气隙隔离安装 Vestigo 的应用层（后端 + 前端）可以完全离线安装。**这三个后端服务——PostgreSQL、ClickHouse、Qdrant——不在此过程的范围内**：请在气隙隔离网络中按照您通常处理离线服务部署的方式配置它们（例如对预拉取的镜像使用 `podman load`，或使用原生软件包）。 在**有互联网连接的**机器上： 1. 克隆或复制仓库。 2. 安装并构建所有内容，以便在本地解析并缓存所有依赖项： uv sync --extra embeddings cd frontend && npm install && npm run build && cd .. 这将填充 `.venv/`（所有 Python 依赖项，包括用于本地嵌入的 CPU PyTorch wheels——如果部署环境不需要本地嵌入，请移除 `--extra embeddings`）和 `frontend/dist/`（已构建的静态前端）。 3. 将整个仓库——包括 `.venv/`、`uv.lock` 和 `frontend/dist/`——复制到便携式驱动器上。 在**气隙隔离机器**上： 1. 从便携式驱动器复制仓库。 2. 将 `.env`（从 `.env.example` 复制而来）中的 `VESTIGO_POSTGRES_URL`、`VESTIGO_CLICKHOUSE_URL` 和 `VESTIGO_QDRANT_URL` 指向隔离网络上已在运行的后端服务。 3. 直接从携带的虚拟环境运行应用程序——不需要 `uv sync` 或 `npm install`，因为两者都已在联网机器上解析完毕： .venv/bin/vestigo-web 因为 `frontend/dist/` 已经被携带过来，并且应用程序是通过 `.venv` 入口点直接启动的（而不是 `uv run`，因为它会尝试重新解析环境），所以在气隙隔离机器上的任何环节都不需要网络访问。`VESTIGO_ALLOW_ONLINE=false`（默认值）此外还防止了嵌入 pipeline 访问任何远程 endpoint。 4. 适用与任何离线 Python 部署相同的二进制兼容性要求：在匹配的操作系统/架构上构建和运行（例如，在您将要运行的相同 Linux 发行版/glibc 版本上构建），因为 `.venv/` 携带的是已编译的 wheels（PyTorch, onnxruntime 等）。 ## 稳定性和升级 1.0 版本系列保证的内容，以及它不保证的内容： - **PostgreSQL 元数据 schema** 由 Alembic 管理；应用程序在启动时自动迁移到当前最新版本。升级 1.0.x 部署的步骤是：停止、更新代码/镜像、启动。 - **Parquet 交换格式 v1**（转换器输出）是稳定的：由任何 1.0 转换器脚本生成的文件都可以被任何 1.0 服务器摄取。重命名前（`*2tracesignal.py`）的转换器编写的文件仍然被接受。 - **取证身份是仅追加的**：解析器/嵌入配置哈希（`config_hash()`）标识处理配置；在 1.0.x 版本内，现有的哈希含义永远不会改变。 - **ClickHouse 和 Qdrant schema** 目前还没有原地迁移方案：在 1.0.x 版本内它们不会更改；未来的更改将在发布说明中附带明确的重新摄取/重新嵌入指南，绝不会进行无提示的更改。 - REST API 由应用程序自身进行版本控制（`/api/health` 报告版本）；破坏性的 API 更改将保留到 2.0 版本中进行。 **从 1.0 之前版本 (TraceSignal) 部署升级：**该项目在 1.0 版本时进行了重命名——CLI `tsig` → `vestigo`，环境变量 `TS_*` → `VESTIGO_*`，并且默认的后端存储名称现在更改为 `vestigo`。现有数据保留在原处：重命名您的环境变量，并通过 `VESTIGO_POSTGRES_URL`、`VESTIGO_CLICKHOUSE_DATABASE` 和 `VESTIGO_QDRANT_COLLECTION_PREFIX` 固定旧名称。请参阅 [CHANGELOG.md](CHANGELOG.md)。 ## 灵感来源 Vestigo 的设计借鉴了两个项目： - **[Timesketch](https://github.com/google/timesketch)**——借鉴以时间线为中心的调查模型（兼容 Plaso 的摄取、类似 ELK 的探索、保存的视图、协作注释），Vestigo 旨在使其更轻量且更易于自托管。 - **[ait-aecid/logdata-anomaly-miner](https://github.com/ait-aecid/logdata-anomaly-miner)**——借鉴其基于统计、非机器学习的日志异常检测方法（稀有值和频率检测器），Vestigo 的 `db/anomaly_stats.py` 引擎对其进行了改造，使其能够直接在 ClickHouse 上运行，并与基于向量的相似性搜索并存。 其目标是在两者之间找到落脚点：将 Timesketch 的调查用户体验与 aminer 轻量级、可解释的异常检测相结合，逐步演变为最适合小型、自托管团队的取证日志分析系统。 ## 文档 - [概念](docs/CONCEPT.md) - [输入格式](docs/INPUT_FORMATS.md) — CSV/JSONL/Parquet 字段级规范化规范 - [异常检测](docs/ANOMALY_DETECTION.md) — 每个统计检测器的通俗语言解释 - [技术栈](docs/TECH_STACK.md) - [模型优化](docs/MODEL_REFINEMENT.md) — 已批准的 Case / Source / Timeline / Artifact 重新设计 - [路线图](docs/ROADMAP.md) - [进度](docs/PROGRESS.md) - [更新日志](CHANGELOG.md) ## 许可证 GPL-3.0 — 请参阅 [LICENSE](LICENSE)。

标签：向量检索, 异常检测, 数字取证, 数据分析平台, 测试用例, 自动化脚本, 请求拦截, 逆向工具