chadcox/corvus
GitHub: chadcox/corvus
Corvus 是一个离线端点取证审查平台，支持多平台证据导入、自动威胁检测和多视图关联分析，帮助分析师高效完成事件溯源。
Stars: 0 | Forks: 0
# Corvus
[](LICENSE)
[](https://github.com/chadcox/corvus/actions/workflows/codeql.yml)
[](https://github.com/chadcox/corvus/actions/workflows/api-migrations.yml)
用于端点调查的离线取证审查平台。导入 Windows、macOS 和 Linux 证据包，通过源适配器和取证解析器规范化解析的及原始的 artifacts，使用检测引擎追踪威胁，并通过相互关联的 **Timeline**、**Object**、**Disk** 和 **Browser** 视图进行调查。
## 架构
```
apps/api/ FastAPI + PostgreSQL — REST API and ingest orchestration
apps/worker/ Celery — source adapters, forensic parsers, Sigma/Chainsaw detection, Hindsight
apps/web/ React + Vite — case management and investigation UI
packages/corvus_core/ Shared Pydantic schemas and constants
```
服务包括：`api`、`worker`、`beat`（Sigma 规则同步调度程序）、`web`、`postgres`、`redis`、`opensearch`，以及用于容器化 Web 端到端运行的可选 `playwright`。
## 快速开始
```
cp .env.example .env
./scripts/rebuild-stack.sh
```
| 服务 | URL |
|---------|-----|
| Web UI | http://localhost:5173 |
| API | http://localhost:8000 |
| API 文档 | http://localhost:8000/docs |
| 就绪状态 | http://localhost:8000/health/ready |
| OpenSearch | http://localhost:9200 |
## 身份验证（本地开发）
Corvus 现在默认强制执行 API 和 UI 身份验证，使用本地用户名/密码以及 JWT bearer token。
- 公开路由：`/health`、`/health/ready`、`/api/v1`、`/api/v1/auth/login`、文档端点。
- 需身份验证的路由：`POST /api/v1/auth/logout`、`GET /api/v1/auth/me`，以及 `/api/v1/*` 下的分析师工作流路由。
- 仅限管理员的路由：用户管理身份验证路由、`/api/v1/admin/*`、`/api/v1/validation/*` 和 `/api/v1/containers/*`。
- 角色：
- `administrator`：完整工作流 + 用户管理
- `analyst`：常规取证工作流（无用户管理）
### 初始化引导管理员
在启动前设置以下变量：
```
AUTH_BOOTSTRAP_ADMIN_USERNAME=admin
AUTH_BOOTSTRAP_ADMIN_PASSWORD=''
AUTH_SECRET_KEY=''
```
在 API 启动时，如果该用户名尚不存在，将创建一个处于活跃状态的 `administrator`。
`.env.example` 在发布时 `AUTH_BOOTSTRAP_ADMIN_PASSWORD` 为**空**，因此在您将其设置为高强度密码之前，不会自动创建管理员。代码中未硬编码任何凭据。
### 当前提供程序及未来的 OIDC 管道
- 当前提供程序：`LocalAuthProvider`（`apps/api/app/auth/providers.py`），使用 bcrypt 进行密码哈希处理。
- Token 和身份验证依赖：`apps/api/app/auth/service.py`。
- 未来提供程序钩子：在同一 provider 模块中预留了 `OidcAuthProvider` 占位符。可以通过实现相同的身份验证提供程序契约并保持角色检查/依赖项不变来添加 Entra/OIDC。
## 前置条件
- Docker Engine 24+ 和 Docker Compose v2
- 最低 16 GB 内存（建议 32 GB）
- 至少 500 GB SSD 用于存储证据
对于 Linux 与 Windows Server 的选择，请先运行解析器冒烟测试 —— 参见[部署](#deployment)。
## 证据包
Corvus 可导入包含端点证据的文件夹或 ZIP 文件。数据包可以包含预解析的工具输出、原始 artifacts、文件系统路径，以及可选的 Windows、macOS 或 Linux 来源元数据。支持 KAPE 采集结果，但它只是兼容的数据包格式之一，而非唯一的目标来源。
**推荐的数据包结构：**
```
WKS-042_20250528/
manifest.json ← optional but recommended
C/ ← raw target files
EvidenceOfExecution/ ← parser/module output (pre-parsed CSVs)
Registry/
EventLogs/
...
```
**导入优先级：**
1. 解析器 CSV/JSON —— EvtxECmd、MFTECmd、PECmd、RECmd、AmcacheParser、日志导出以及 source-adapter 输出
2. 原始 artifacts —— `.evtx`、注册表配置单元、预读取文件、`$MFT`、浏览器配置文件、日志及其他受支持的 artifacts
3. 采集的文件 —— 包含路径和时间戳的文件系统节点
有关完整的格式参考，请参阅 [docs/EVIDENCE-PACKAGE.md](docs/EVIDENCE-PACKAGE.md)。
## 调查视图
| 视图 | 内容 |
|------|---------|
| **Timeline** | 涵盖所有 artifact 来源按时间顺序排列的事件，支持日期范围和事件类型过滤器 |
| **Object** | 提取的实体 —— 用户、进程、文件、主机、IP 地址 —— 带有跨视图链接 |
| **Disk** | 根据采集的路径和文件元数据生成的逻辑文件系统树 |
| **Browser** | 通过 [Hindsight](https://github.com/obsidianforensics/hindsight) 获取的 Chromium 历史记录、下载记录和 cookies |
## 检测（Chainsaw + Sigma）
在导入期间，Corvus 会对受支持的事件/日志 artifacts 运行自动检测：
1. **Chainsaw** —— [WithSecure Chainsaw](https://github.com/WithSecureLabs/chainsaw) 使用原生规则和 Sigma 规则以并行批次追踪原始 Windows `.evtx` 文件。
2. **进程内 Sigma** —— 基于 EvtxECmd CSV 字段的 Python 匹配器（在 `CHAINSAW_INCLUDE_SIGMA=false` 时作为回退方案）。
检测命中会以徽章形式显示在时间轴行、事件详情面板以及来源统计侧边栏中。每次匹配的行会显示是由哪个引擎（Chainsaw 或 Sigma）产生的命中。
**Chainsaw EVTX 策略：**
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| `CHAINSAW_EVTX_MODE` | `priority` | 优先处理 Security/Sysmon/PowerShell 日志，然后再处理其他日志 |
| `CHAINSAW_EVTX_MAX` | `64` | 每次导入的最大 EVTX 文件数 |
| `CHAINSAW_EVTX_PARALLEL` | `4` | 并行追踪批次数 |
| `CHAINSAW_EVTX_BATCH_SIZE` | `16` | 每批次包含的 EVTX 文件数 |
| `CHAINSAW_HUNT_BATCH_TIMEOUT_SECONDS` | `300` | 每批次超时时间 |
| `CHAINSAW_SIGMA_PROFILE` | `dfir` | 规则层级：`dfir`（约 1400 条规则）、`full` 或 `off` |
**规则包管理：**
| 引擎 | 刷新 | 状态 |
|--------|---------|--------|
| Sigma | `POST /api/v1/sigma/rules/refresh` | `GET /api/v1/sigma/rules` |
| Chainsaw | `POST /api/v1/chainsaw/rules/refresh` | `GET /api/v1/chainsaw/rules` |
| 两者 | — | `GET /api/v1/detection-rules` |
Sigma 刷新也会按照计划自动运行（`SIGMA_REFRESH_INTERVAL_HOURS`，默认 24 小时）。
仅包含采集日志而没有解析或原始 EVTX 数据的数据包不会产生检测命中。在添加事件日志 artifacts 或解析器输出后，请上传新的源数据包。
## 验证
```
# Readiness probe (postgres + redis + celery)
curl -sf http://localhost:8000/health/ready
# 使用 sample-ingest helpers 时启用 validation API
ENABLE_VALIDATION_API=true docker compose up -d api
# Fast validation 示例（约 3 个 events，跳过 heavyweight detection/indexing）
./scripts/validate-ingest.sh --sample kape-minimal
# 更大的 endpoint 集合（samples/c.zip，约 185 MB — 最多需要 15 分钟）
MIN_FILESYSTEM_NODES=1 ./scripts/validate-ingest.sh --sample c --max-wait 900
# 验证 detection rule engine
./scripts/sigma-self-test.sh
```
### 数据库迁移检查
```
docker compose exec -T api bash /app/apps/api/scripts/check_migrations.sh
docker compose exec -T api pytest -q tests/test_migration_integrity.py tests/test_database_migrations.py
```
有关编写和部署的指导，请参见 [docs/ALEMBIC_WORKFLOW.md](docs/ALEMBIC_WORKFLOW.md)。
### 导入结果 API
用于 CI 自动化：
1. `POST /api/v1/validation/ingest-sample?sample=c&ingest_mode=fast|full` —— 将内置的示例 ZIP 加入队列，并返回 `job_id` 以及 `outcome_path`
2. 轮询 `GET /api/v1/jobs/{job_id}/outcome` 直到返回 `success: true` 或 `job_status: failed`
3. 响应包含 `checks[]`（每一步的通过/失败状态）以及 `stats`
`POST /api/v1/validation/ingest-upload?ingest_mode=fast|full` 为任意上传的 ZIP 提供相同的流程。验证路由需要经过身份验证的管理员权限，并且要求 `ENABLE_VALIDATION_API=true`。
## API 参考
`GET /api/v1` —— API 发现，包含指向所有端点组的链接。
### 管理员端点（`ENABLE_ADMIN_API=true`）
管理员路由默认禁用。仅针对受信任的操作员或开发环境启用它们。
| 端点 | 用途 |
|----------|---------|
| `GET /api/v1/admin/overview` | 就绪状态、Alembic 版本、数据库计数、作业直方图、磁盘使用情况、规则同步状态、身份验证安全性及搜索可观测性 |
| `GET /api/v1/admin/jobs?status=failed&error_code=...&error_stage=...&limit=20` | 最近的导入作业及结构化故障过滤器 |
| `GET /api/v1/admin/evidence-sources` | 包含最新作业状态的来源 |
| `GET /api/v1/admin/routes` | 路由目录 |
| `GET /api/v1/admin/config` | 安全配置快照（不含凭据） |
| `POST /api/v1/admin/search/reindex` | 根据规范的数据库行重建 OpenSearch 文档 |
| `GET /api/v1/admin/cases/purge-preview` | 删除所有案例之前的试运行预览 |
| `DELETE /api/v1/admin/cases?confirm=true` | 删除所有案例和证据 |
| `POST /api/v1/admin/cases/bulk-delete` | 删除指定的案例 ID |
| `DELETE /api/v1/admin/cases/validation?confirm=true` | 清除自动验证生成的案例 |
| `POST /api/v1/admin/evidence/wipe` | 从磁盘删除所有证据目录 |
在生产环境中设置 `ENABLE_ADMIN_API=false` 以禁用这些路由。
## 配置
关键环境变量（常见默认值见 [`.env.example`](.env.example)；高级设置在应用配置和 compose 配置中定义）：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SIGMA_PROFILE` | `dfir` | 加载时的 Sigma 规则层级（`dfir` 或 `full`） |
| `SIGMA_REFRESH_INTERVAL_HOURS` | `24` | 计划规则更新间隔（0 = 禁用） |
| `SEARCH_BACKEND` | 在 Docker Compose 中为 `opensearch` | 搜索后端（`opensearch` 或 `postgres`） |
| `OPENSEARCH_URL` | 在 Docker Compose 中为 `http://opensearch:9200` | 用于索引和搜索的 OpenSearch endpoint |
| `CHAINSAW_ENABLED` | `true` | 启用 Chainsaw EVTX 追踪 |
| `CHAINSAW_INCLUDE_SIGMA` | `true` | 将 Sigma 规则应用于 Chainsaw |
| `HINDSIGHT_ENABLED` | `true` | 启用 Chromium 浏览器取证 |
| `HINDSIGHT_MAX_PROFILES` | `8` | 每个数据包最多处理的浏览器配置文件数量 |
| `HINDSIGHT_TIMEOUT_SECONDS` | `900` | 每次执行 Hindsight 处理的超时时间 |
| `INSTALL_OPEN_FORENSICS` | `false` | 构建带有可选 Plaso/mac_apt/Volatility3 工具的 worker |
| `PLASO_ENABLED` | `true` | 安装后使用 Plaso 适配器 |
| `PLASO_PARALLEL_ENABLED` | `true` | 将 Plaso 拆分为针对性的解析器系列运行并合并输出 |
| `PLASO_PARALLEL_JOBS` | `2` | 最大并发解析器系列 Plaso 作业数 |
| `MAC_APT_ENABLED` | `true` | 安装后使用 mac_apt 适配器 |
| `VOLATILITY3_ENABLED` | `true` | 针对 Windows 内存转储启用 Volatility3 适配器 |
| `VOLATILITY3_BIN` | `vol` | Volatility3 CLI 路径/名称 |
| `VOLATILITY3_PLUGINS` | `windows.info,windows.pslist,windows.netscan,windows.cmdline` | 每个内存镜像要执行的逗号分隔插件列表 |
| `AUTH_TRUSTED_PROXIES` | *(空)* | 允许为身份验证限流提供可信 `X-Forwarded-For` 值的 CIDR/IP |
| `AUTH_REVOCATION_FAIL_CLOSED` | `false` | 当 Redis 不可用时，将撤销的 token 检查视为拒绝 |
| `ADMIN_DISK_USAGE_CACHE_SECONDS` | `30` | 高开销的管理员证据磁盘使用情况扫描的缓存 TTL |
| `ENVIRONMENT` | `development` | 在 `staging` / `production` 环境中强制执行更严格的身份验证密钥校验 |
`DELETE_EVIDENCE_AFTER_INGEST` | `false` | 在导入完成后删除解压出的证据文件 |
| `ENABLE_ADMIN_API` | `false` | 暴露管理员/开发端点 |
| `ENABLE_VALIDATION_API` | `false` | 暴露自动化测试端点 |
| `AUTH_SECRET_KEY` | `change-me-dev-auth-secret` | 用于本地身份验证的 JWT 签名密钥 |
| `AUTH_TOKEN_EXP_MINUTES` | `480` | JWT 过期时间窗口 |
| `AUTH_BOOTSTRAP_ADMIN_USERNAME` | *(空)* | 启动时自动创建的本地管理员用户名 |
| `AUTH_BOOTSTRAP_ADMIN_PASSWORD` | *(空)* | 启动时自动创建的本地管理员密码 |
| `UPLOAD_MAX_BYTES` | `10737418240` | 上传的数据包最大大小 |
| `EXTRACTED_MAX_FILES` | `250000` | ZIP 解压后的最大文件数 |
| `EXTRACTED_MAX_BYTES` | `536870912000` | ZIP 解压后的最大未压缩大小 |
`DELETE_EVIDENCE_AFTER_INGEST` 默认设为 `false`，因此除非显式更改，否则证据在导入后将予以保留。
## 来源元数据
证据来源包含供适配器和 UI 使用的一等元数据：
| 字段 | 用途 |
|-------|---------|
| `platform` | `windows`、`macos`、`linux` 或 `unknown` |
| `collector` / `collector_version` | 采集或导出工具标识 |
| `source_type` | 端点、服务器、云导出或其他来源系列 |
| `os_version`、`architecture`、`timezone`、`collected_at` | 用于解析和时间轴审查的上下文 |
## 开源解析器集成
为了扩展 macOS/Linux 支持以及进行 Windows 内存分析，Corvus 包含了针对 Plaso/log2timeline、mac_apt、UAC 包、Volatility3 内存转储以及 Velociraptor 采集导入的适配器钩子。在设置 `INSTALL_OPEN_FORENSICS=true` 后，可将宽松许可的工具安装到 worker 镜像中；由于 AGPL 许可证限制，Velociraptor 仅支持导入。
### Plaso 策略
Plaso 的配置优先考虑取证分流导入：
1. 每个平台（`linux`、`macos`、`unknown`）使用特定范围的解析器集，而不是广泛的解析器自动检测。
2. 将解析工作拆分为针对性的 artifact 系列（例如：日志、数据库、浏览器、文件系统元数据）。
3. 并行运行解析器系列（并发数可配置），并将它们的 JSONL 输出合并到一个导入流中。
这使得 Plaso 能够作为通用的时间轴适配器，同时减少大型端点数据包端到端的导入延迟。
参见 [docs/OPEN-SOURCE-PARSERS.md](docs/OPEN-SOURCE-PARSERS.md)。
## 部署
### Linux（默认）
```
./scripts/smoke-test-eztools.sh # verify all critical parsers pass
docker compose up -d --build
```
EZ Tools 在镜像构建时安装到 `/opt/eztools`。SHA-256 校验锁定位于 `scripts/eztools-checksums.sha256` 中；使用 `scripts/capture-eztools-checksums.sh` 重新生成。
**最低配置要求：**
| 资源 | 最低要求 | 推荐配置 |
|----------|---------|-------------|
| CPU | 4 核 | 8 核+ |
| 内存 | 16 GB | 32 GB |
| 磁盘 | 500 GB SSD | 1 TB+ 专用证据卷 |
### Windows Server（备选方案）
如果关键解析器（EvtxECmd、MFTECmd、RECmd、AmcacheParser、PECmd）在 Linux 上运行失败，请在 Windows Server 2022 上使用原生 EZ Tools 二进制文件原生部署 Celery worker。API 和 Web 端仍可保留在 Docker 中运行。
完整说明请参见 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。
## 开发
```
# Fast default loop（live-mounted source，无需 full stack rebuild）
./scripts/rebuild-stack.sh
# Fast loop + 预构建的 heavy worker image
./scripts/build-worker-tools.sh
./scripts/rebuild-stack.sh --tools
# 显式 full image rebuild 路径（Dockerfile/dependency 变更）
./scripts/rebuild-stack.sh --full
# 在 full mode 下仅重新构建一个已变更的 service
docker compose up -d --build api
docker compose up -d --build worker
# 运行 worker 单元测试（无需 Docker）
cd apps/worker && python -m pytest tests/
# 运行 API 测试
cd apps/api && python -m pytest tests/
# 构建 web（通过 Docker，避免宿主机 npm 问题）
docker build -f apps/web/Dockerfile -t ff-web-test .
docker run --rm ff-web-test npm run build
# 在 stack 中运行 mocked Playwright flows
docker compose run --rm playwright bash -lc 'npm install && npm run test:e2e:ci'
# 运行 backend-backed Playwright analyst flow
docker compose run --rm playwright bash -lc 'npm install && FF_E2E_ADMIN_USERNAME=admin FF_E2E_ADMIN_PASSWORD=admin FF_E2E_API_URL=http://api:8000 npm run test:e2e:backend'
```
### Docker Compose 模式
- `dev-fast` 配置（通过 `./scripts/rebuild-stack.sh` 默认启用）：
- 将 `postgres`、`redis` 和 `opensearch` 保留在 Docker 中
- 运行 `api`、`worker`、`beat` 和 `web`，并使用绑定挂载以实现即时代码更新
- 使用 `uvicorn --reload` 进行 API 代码重载
- `dev-tools` 配置（`./scripts/rebuild-stack.sh --tools`）：
- 复用预构建的 `WORKER_TOOLS_IMAGE`（默认为 `corvus-worker:tools`）
- 避免在日常开发中重复构建 Plaso/mac_apt
- 完全重建模式（`./scripts/rebuild-stack.sh --full`）：
- 根据 `docker-compose.yml` 重建原始技术栈
- 在 Dockerfile/基础层或依赖项发生变更时使用
## 文档
- [docs/PROJECT.md](docs/PROJECT.md) —— 目标、范围、路线图
- [docs/EVIDENCE-PACKAGE.md](docs/EVIDENCE-PACKAGE.md) —— 证据包格式
- [docs/OPEN-SOURCE-PARSERS.md](docs/OPEN-SOURCE-PARSERS.md) —— 解析器集成与许可
- [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) —— Linux 与 Windows Server
- [docs/PARSER-COMPAT.md](docs/PARSER-COMPAT.md) —— EZ Tools 冒烟测试矩阵
## 许可证
应用程序代码基于 [MIT License](LICENSE) 发布。
Corvus 可以选择下载、安装第三方工具、解析器、检测引擎和规则内容，或与其进行集成，这些内容仍受其各自的许可证和条款约束。此类组件不会根据 MIT 重新授权。
| 工具 | 许可证 | 集成状态 |
|------|---------|--------------------|
| [Eric Zimmerman EZ Tools](https://ericzimmerman.github.io/) | 第三方许可条款 | 安装在 worker 镜像中，用于解析 Windows artifacts |
| [WithSecure Chainsaw](https://github.com/WithSecureLabs/chainsaw) | GPL-3.0 | 安装在 worker 镜像中，用于 EVTX 追踪 |
| [Sigma rules](https://github.com/SigmaHQ/sigma) | 遵循上游项目条款的检测规则 | 打包/同步以提供检测逻辑 |
| [Hindsight](https://github.com/obsidianforensics/hindsight) | Apache-2.0 | 安装在 worker 镜像中，用于处理 Chromium 浏览器 artifacts |
| [Plaso / log2timeline](https://github.com/log2timeline/plaso) | Apache-2.0 | 可选安装，用于广泛的日志时间轴提取 |
| [mac_apt](https://github.com/ydkhatri/mac_apt) | MIT | 可选安装/导入，用于处理 macOS artifacts |
| [UAC](https://github.com/tclahr/uac) | Apache-2.0 | 兼容导入的数据包/来源格式 |
| [Velociraptor](https://github.com/Velocidex/velociraptor) | AGPL-3.0 | 仅支持导入；未打包在程序内 |
有关集成和打包的详细信息，请参见 [docs/OPEN-SOURCE-PARSERS.md](docs/OPEN-SOURCE-PARSERS.md)。
 Timeline |
 Object |
 Disk |
 Browser |
标签：Python, React, Syscalls, 安全, 搜索引擎查询, 无后门, 测试用例, 端点取证, 请求拦截, 超时处理, 逆向工具