cac0ns3c/Raptorscope

# Raptorscope **macOS DFIR 分析 —— 将 Velociraptor 主机采集数据转化为 ECS 规范化、** 检测增强、AI 分诊的事件证据。** Raptorscope 摄取 macOS 采集数据，将每个 artifact 规范化为 Elastic Common Schema，运行 38 对 Sigma 检测，并通过 FastAPI 后端将其提供给专门构建的 React/TypeScript 调查 UI 和由 Claude 驱动的 分诊。**离线优先** —— 捆绑的示例案例无需任何基础设施即可运行 —— 并且**具备扩展能力** —— 支持具有原生检测、聚合和深度分页的 Elasticsearch。 `38 项检测` · `318 项测试` · `双检测引擎，零差异一致性` · `Claude 驱动的分诊` · `RBAC + 审计 + 指标` · `CI: 单元测试 · 实时 ES · 端到端测试 ·` 供应链检测` 设计规范：`docs/superpowers/specs/2026-07-03-raptorscope-design.md` · 安装说明：`docs/INSTALL.md` · 演示：`docs/DEMO.md` · Kibana：`docs/KIBANA.md` · 架构：见下文 ## 核心亮点 - **双检测引擎，已证明等效** —— 进程内 Sigma 评估器 (离线/演示) 和 ES 原生 Lucene 路径 (扩展)，在实时 Elasticsearch 上验证了 **0/38 差异**。 - **38 对检测，经 agent 审查** —— 每个规则均提供命中 + 良性 样本并受到防漂移保护；规则集由编排的多 agent 工作流设计并经过*对抗性 审查*，随后进行了端到端验证。 - **位于可测试接口后方的 Claude 驱动分诊** —— 每个警报的分诊， 带时间戳的事件叙述 (流式传输)，自然语言 → 查询，带有实时工具调用追踪的 agentic **copilot**，以及结构化 IOC 提取。 可注入的 `AIClient` 允许整套测试在无密钥或网络的情况下运行，并且 可配置为任何兼容 Anthropic 的 endpoint。强化了 Prompt 注入防护。 - **跨主机 IOC 搜寻** —— 在一次 查询中关联整个集群的指示器，直接从 AI 提取的 IOC 进行跳转。 - **生产环境加固** —— 签名 token 中的 RBAC (viewer/analyst/admin)， 仅追加的审计日志，按客户端的速率限制，Prometheus `/metrics`， `X-Request-ID` 关联，以及 TLS 反向代理覆盖层。 - **真实保真度** —— 针对真实 Velociraptor schema 协调的规范化器， 在无内置项时使用自定义 VQL (配置 profiles，BTM，签名 增强)，时间戳来源 (mtime 对比 event)，以及记录在案的 合成数据与真实数据之间的差异。 - **工程严谨性** —— 268 个 Python + 60 个 Web 测试，包括属性/模糊测试；CI 运行单元测试、**实时 Elasticsearch 集成**任务、**Playwright 端到端测试**，以及 **供应链扫描** (pip-audit · npm-audit · SBOM · Trivy)。 ## 架构 ``` flowchart LR VR["Velociraptor
macOS collection
(zip / dir)"] --> N["normalizers → ECS
10 mappers + custom VQL"] N -->|"raptorscope-*"| ES[("Elasticsearch")] N -.->|"offline demo"| MEM[("in-memory store")] RULES["38 Sigma detections
paired hit + benign"] --> DET ES --> DET{{"detection engine
in-process · ES-native Lucene"}} MEM --> DET DET --> API["FastAPI API
RBAC · audit · rate-limit · metrics"] ES --> API MEM --> API API --> SPA["React / TS SPA
overview · timeline · alerts
search · fleet hunt"] API <--> AI["Claude AI
triage · summary · NL-query
copilot · IOC extraction"] AI --> SPA ES --> KB["Kibana dashboard"] ``` ## 截图 分诊 SPA 的引导之旅 —— 案例选择器 → 全集群 IOC 搜寻 → 概览 仪表板 → 触发的检测 → 时间线 → 搜索。无论是演练 GIF 还是下方的 静态图像，均由 CI Playwright 任务 (即 `spa-screenshots` artifact) 自动捕获，因此随着 UI 的演进，它们始终保持最新。  各独立视图： | 概览仪表板 | 全集群 IOC 搜寻 | |---|---| | [](docs/img/03-overview.png) | [](docs/img/02-fleet-hunt.png) | | **触发的检测** | **时间线** | | [](docs/img/04-alerts.png) | [](docs/img/05-timeline.png) | ## 快速开始 ``` make setup # venv + Python deps + web npm install make demo # serve the bundled sample case on :8000 (no ES needed) make web # in another shell: SPA on http://localhost:5173 ``` 打开 http://localhost:5173，选择 `mac-victim` 案例，并跟随警报 跳转至证据。完整导览请见 `docs/DEMO.md`。 或者运行**整个 Docker 应用** (Elasticsearch + Kibana + API + SPA)： ``` make stack # docker compose --profile app up -d --build # SPA → http://localhost:8080 · API → :8000 · Kibana → :5601 · ES → :9200 ``` ## 采集与检测内容 六个 ECS 数据集解答了第一小时的 macOS 分诊问题，每个都配有 Sigma 检测。每个规则均提供一个恶意 + 良性 fixture，并通过 `detect/pairing.py` 防止漂移。 | ECS 数据集 | Velociraptor 来源 | 分诊问题 | 检测数量 | |--------------------|----------------------------------------------------------|-----------------------|:----------:| | `macos.persistence`| `MacOS.Detection.Autoruns` (launchd/login/cron/BTM) + 配置 profiles (自定义 VQL) | 谁在进行持久化 | 10 | | `macos.process` | `MacOS.Sys.Pslist` (+ 签名增强 VQL) | 运行了什么 | 12 | | `macos.quarantine` | `MacOS.System.QuarantineEvents` (LSQuarantine) | 什么进入了系统 | 5 | | `macos.tcc` | `MacOS.System.TCC` | 什么获得了权限 | 6 | | `macos.inventory` | `MacOS.System.Packages` | 安装了什么 | 3 | | `macos.network` | `netstat` (自定义 VQL) — 监听器 + 连接 | 与谁进行通信 | 2 | 检测覆盖了 ATT&CK 矩阵 (初始访问 → 执行 → 持久化 → 权限提升 → 防御规避 → 凭据访问 → 收集 → C2)，带有精确到子技术的 MITRE 标签。持久化家族共享一个数据集， 通过 `raptorscope.persistence.type` 进行区分。当现有的 Velociraptor artifact 缺少某个字段 (代码签名信任、配置 profile/BTM 枚举) 时， `profile/custom-vql/` 提供了补足该字段的 artifact —— 因此基于签名的 规则能在真实捕获数据上触发，而不仅限于 fixture。 ## 用法 ``` # dev 设置 python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # 运行测试 PYTHONPATH=src .venv/bin/python -m pytest tests/ -v # 导入 Velociraptor 收集包（目录或 zip）—— dry run 会打印 doc 数量 PYTHONPATH=src .venv/bin/python -m raptorscope ingest # ...并 index 到 Elasticsearch PYTHONPATH=src .venv/bin/python -m raptorscope ingest --es http://localhost:9200 # 运行检测并报告每条 rule 的触发数量（用于误报调优）—— # 将其指向一个良性收集包，以查看哪些 rule 会在干净数据上触发 PYTHONPATH=src .venv/bin/python -m raptorscope detect PYTHONPATH=src .venv/bin/python -m raptorscope detect --json # 提供 query API 服务 —— 离线覆盖单个收集包（demo）或覆盖实时的 ES PYTHONPATH=src .venv/bin/python -m raptorscope serve --collection --port 8000 PYTHONPATH=src .venv/bin/python -m raptorscope serve --es http://localhost:9200 # 要求登录（bearer token）：客户端 POST /login 获取 token，然后发送它 PYTHONPATH=src .venv/bin/python -m raptorscope serve --collection \ --auth-user analyst --auth-pass s3cret # or RAPTORSCOPE_AUTH_USER/PASS env ``` **Auth** 默认关闭 (演示保持零设置)。启用后，`/health` 和 `/docs` 保持开放，`/login` 签发**限时签名 bearer token** (默认 8 小时，`RAPTORSCOPE_AUTH_TTL`)，并且每个 `/cases/*` 请求都必须携带 `Authorization: Bearer `。SPA 在收到 `401` 时会自动显示登录界面，并在验证身份后显示**登出**按钮。多用户支持： `RAPTORSCOPE_AUTH_USERS="alice:pw1,bob:pw2"`。 **速率限制** (按客户端，60 秒窗口) 保护 `/login` 和 AI endpoint： `RAPTORSCOPE_LOGIN_RATE` (默认 20) 和 `RAPTORSCOPE_AI_RATE` (默认 60)； `/ai/status` 轮询豁免。超出限制将返回 `429`。 **角色 (RBAC)。** 每个用户都有一个角色 —— `viewer`、`analyst` (默认) 或 `admin` —— 内置于签名 token 中。使用以下方式设置： `RAPTORSCOPE_AUTH_ROLES="alice:admin,bob:viewer"`。`viewer` 是只读的 (案例、 概览、时间线、artifacts、搜索)；**活跃/高成本**操作 —— 所有 AI endpoint 和集群 `/hunt` —— 需要 `analyst` 或更高权限 (否则返回 `403`)。 **审计 + 可观测性。** 每个案例数据、AI 和搜寻请求都会连同 用户、方法、路径和状态一起写入 `raptorscope.audit` 日志；每个响应 都带有一个 `X-Request-ID`；`GET /metrics` 暴露 Prometheus 计数器。 ### 查询 API `create_app(store)` (`api/app.py`) 通过 `Store` 抽象提供 JSON 服务 —— 测试/离线演示使用 `InMemoryStore`，实时 Elasticsearch 使用 `ESStore`。*案例* 即一个已采集的主机。警报是读取时查询：针对该案例的文档，在进程中评估 Sigma YAMLs (`detect/evaluate.py`)。 | Endpoint | 返回内容 | |----------|---------| | `GET /health` | 存活状态 | | `GET /cases`, `GET /cases/{case}` | 带有文档计数和数据集的案例 | | `GET /cases/{case}/overview` | 第一小时计数、持久化类型 + 已签名/未签名明细 | | `GET /cases/{case}/artifacts/{dataset}` | 分页文档 (`?limit=&offset=`) | | `GET /cases/{case}/timeline` | 跨数据集事件，最新优先 | | `GET /cases/{case}/alerts` | 触发的检测，带有 `doc_id` 跳转到证据 | | `GET /cases/{case}/search` | 自由文本 (`?q=`) + 可选的 `?dataset=`/`?field=&op=&value=` 跨案例文档查询 | | `GET /docs`, `GET /docs/{id}` | 面向用户的文档 (概览/安装/演示/Kibana/Profile)，在 SPA 的 **Docs** 面板中渲染 | | `GET /ai/status` · `POST /cases/{case}/ai/{triage,summary,nl-query,copilot}` | Claude 支持的 AI 功能 (未设置 `ANTHROPIC_API_KEY` 时关闭) | ### AI 功能 (可选) 在 API 进程上设置 `ANTHROPIC_API_KEY` 以启用 Claude 驱动的分诊 (`claude-opus-4-8`)。配置后，SPA 将显示：在每个警报上的 **AI 分诊** 按钮 (触发原因 / MITRE / 评估 / 后续步骤)，概览中的**总结案例**，搜索中的**用自然语言提问**栏 (自然语言 → 查询 过滤器)，以及 **Copilot** 标签页 —— 这是一个 agentic 工具循环，查询该案例自有的 endpoint 并返回带有引用的有据可查的结论。所有 AI 代码都位于 可注入的 `AIClient` 接口之后，因此测试套件在无密钥且无 网络的情况下运行。模型输出 (源自采集的 artifact) 在渲染前使用 DOMPurify 进行净化处理。 **可配置** —— 将其指向任何兼容 Anthropic-API 的 endpoint (如 LiteLLM / Cloudflare AI Gateway 等网关， 或自托管路由器)，任何模型，任何密钥： | 环境变量 | 用途 | |---------|---------| | `RAPTORSCOPE_AI_KEY` (或 `ANTHROPIC_API_KEY`) | API 密钥 —— **启用 AI 必需** | | `RAPTORSCOPE_AI_MODEL` (或 `ANTHROPIC_MODEL`) | 模型 ID (默认 `claude-opus-4-8`) | | `RAPTORSCOPE_AI_BASE_URL` (或 `ANTHROPIC_BASE_URL`) | 用于代理/网关的 endpoint 覆盖 | ``` # 默认（Anthropic） ANTHROPIC_API_KEY=sk-ant-… raptorscope serve --collection # 通过使用不同 model 的 gateway RAPTORSCOPE_AI_KEY=… RAPTORSCOPE_AI_BASE_URL=https://gateway/v1 \ RAPTORSCOPE_AI_MODEL=claude-sonnet-5 raptorscope serve --collection ``` ### 图形界面 (`web/`) 一个使用查询 API 的 Vite + React + TypeScript SPA。它仅与通过 context 提供的 强类型 `ApiClient` 通信，因此每个组件/交互测试都在 内存中的模拟客户端上运行 —— 无需网络。 选择一个案例，然后在标签式工作区中操作 —— **概览 · Artifacts · 时间线 · 警报 · 搜索 · Copilot** (配置密钥后会出现 AI 标签页)： - **警报** 是一个以严重性为先的分诊队列 (高 → 中 → 低)，提供每个警报的 确认 / 驳回 / 备注以及一键 AI 分诊。 - **概览** 是一个启动平台：数据集 KPI 磁贴和未签名的进程/应用 计数可直接深入到相关的 Artifacts 中，旁边是按类型划分的持久化明细 和签名完整性面板。 - 任何**警报、搜索命中、时间线事件或 KPI 磁贴**都可以跳转到 Artifacts 表，并高亮显示证据行；**详情抽屉**将文档 平铺为 ECS 字段，并提供逐字段的复制到剪贴板功能。 - **浅色/深色主题**，区域设置格式的计数，以及一致的加载 / 空 / 错误状态，并提供**重试**功能。 **无障碍访问是一等公民**：全程支持键盘操作 —— 具有 Escape 关闭和焦点恢复功能的焦点陷阱 模态框，键盘激活的行和可排序的表头，跳转至内容链接，以及带有 有效 ARIA 的拉伸链接警报卡片 —— 外加用于异步/流式传输结果的 `aria-live` 区域以及对 `prefers-reduced-motion` 的支持。 ``` cd web npm install npm run dev # Vite dev server; proxies /api -> http://127.0.0.1:8000 npm test # Vitest component + interaction tests npm run build # tsc typecheck + production bundle # 在另一个终端中，提供 SPA 调用的 API 服务： PYTHONPATH=../src ../.venv/bin/python -m raptorscope serve --collection --port 8000 ``` ### Kibana (可选前端) 由于 Elasticsearch 中的所有内容都是 ECS，你可以 在 Kibana 中探索相同的数据，以代替 (或伴随) SPA —— `make kibana` 启动 ES + Kibana 并 配置 `raptorscope-*` 数据视图 + 保存的搜索。设置 `VITE_KIBANA_URL` 以 在 SPA 标题栏中添加一个“在 Kibana 中打开 ↗”链接 (深度链接到案例主机)。 完整指南：`docs/KIBANA.md`。 一次采集是一个目录 (或 zip 文件)，包含 `.json` 文件以及用于 `host.*`/`user.*` 上下文的可选 `host.json`。文件可以按内部 标识 (`cli._NORMALIZERS`) 命名，**或者**按真实的 Velociraptor artifact 名称 (`MacOS.System.TCC.json`, …) 命名 —— 后者在 `collection.ARTIFACT_ALIASES` 中进行了别名处理。文档被路由到按数据集划分的 `raptorscope-*` 索引。 精选的 artifact 集合 —— 即**采集契约** —— 位于 `profile/raptorscope-macos.yaml` (`profile/README.md` 涵盖了构建采集器 或运行搜寻的内容)。`samples/mac-victim/` 是由 `raptorscope demo` 提供服务的一个完整示例。 许可证：GPL-3.0-or-later

标签：AI分析, AMSI绕过, AV绕过, Elasticsearch, FastAPI, React, Syscalls, 威胁检测, 安全运营, 扫描框架, 特征检测, 自定义请求头, 请求拦截, 越狱测试, 逆向工具