sltcnb/citadel

Citadel 负责将取证 artifact 从获取阶段一路推进至完成、可搜索且检测丰富的案例 —— 获取 → 接收 → 解析 → 标准化 → 检测 → 分析 → 富化 → 调查 → 报告。每个阶段都是一个拥有独立 CLI 的 **standalone 工具**；该平台通过 **shared contracts** 将它们串联起来。 ``` Talon ─▶ Sluice ─▶ Babel ─▶ Rosetta ─▶ ┬─▶ store (timeline · search) acquire route parse →ECS ├─▶ Sigil (detections) ├─▶ Anvil (analyzers) └─▶ Augur (intel) Pilot drives the tools · Scribe writes the report ``` **Open-core / source-available。** 整个代码库基于 PolyForm Noncommercial License 开源可用 —— 你可以出于任何非商业目的运行、修改和自行托管。高级 *runtime* 层级通过 license key 解锁；无 key → Community 层级。详见 [授权许可](#licensing)。 ## 快速开始 `./foctl` 驱动所有部署 —— 它会生成密钥、创建 `.env`、构建镜像并分配资源，因此首次安装只需一条命令。 ``` git clone https://github.com/sltcnb/citadel.git && cd citadel ./foctl deploy docker # single host · or: ./foctl (interactive menu) ``` 打开 **http://localhost** —— 默认登录凭据为 `admin` / `CitadelAdmin1!`（首次登录时将强制要求设置新密码）。 | 模式 | 命令 | 最适用于 | |------|---------|----------| | **Docker Compose** | `./foctl deploy docker` | 笔记本电脑、单台服务器、评估测试、air-gapped 环境 | | **Kubernetes** (原始 manifests) | `./foctl deploy k8s` | 由 Citadel 同时 provision ES/Redis/MinIO 的集群 | | **Kubernetes** (新建本地 k3d) | `./foctl deploy k8s-new` | 开发、CI、离线实验室 | | **Helm** (仅 app) | `./foctl deploy helm` | 已运行 ES/Redis/MinIO + ingress 的集群 | **运维操作** — `./foctl status` · `./foctl logs api` · `./foctl update` (重新构建 + 重新部署) · `./foctl destroy` · `./foctl config`。如果省略模式，`foctl` 会自动检测。 **独立运行单个工具**（无需平台）： ``` babel parse Security.evtx -o events.jsonl # parse one artifact rosetta normalize events.jsonl --ecs 8.11 -o ecs.jsonl # → ECS v8 + OSSEM augur enrich iocs.json -o enriched.stix.json # enrich IOCs python tools/sigil/sigil_validate.py # validate detection rules ``` **Compose profiles**（手动操作 Docker）：`edge` (Talon) · `pipeline` (Sluice+Babel+Rosetta+store) · `full` (所有组件)。

手动部署 Helm / Kubernetes、ingress 及 SSO

Umbrella chart `charts/citadel` **仅部署 app**（api + processor + frontend）；将其指向已有的 Elasticsearch / Redis / MinIO，或设置 `--set elasticsearch.enabled=true`（等等）由 Helm 进行部署。 ``` # build（native arch）+ 使镜像对集群可见 docker build -t citadel-api:1.0.0 -f api/Dockerfile . docker build -t citadel-processor:1.0.0 -f tools/sluice/worker/Dockerfile . docker build -t citadel-frontend:1.0.0 -f frontend/Dockerfile frontend # 从真实主机设置 requests/limits（可选） python3 scripts/allocate_resources.py # → charts/citadel/values-resources.generated.yaml # 针对现有 substrate 进行安装 helm upgrade --install citadel charts/citadel -n citadel --create-namespace \ -f charts/citadel/values-resources.generated.yaml \ --set-string config.elasticsearchUrl=http://elasticsearch.:9200 \ --set-string config.redisUrl=redis://redis-service.:6379/0 \ --set-string config.minioEndpoint=minio-service.:9000 \ --set ingress.enabled=true --set-string ingress.fqdn=citadel.example.com \ --set-string ingress.className=traefik ``` **Ingress** — `ingress.className`：`traefik`（默认；包含 TLS + http→https 重定向） · `tailscale` (`--set ingress.tls.enabled=false`) · `nginx`/其他（自动跳过仅适用于 Traefik 的部分） · 或者设置 `--set ingress.enabled=false`，将你自己的 Ingress 路由至 `citadel-frontend:80` (`/`) 和 `citadel-api:8000` (`/api`)。 **SSO (Google / Microsoft)** — 在配置前保持关闭。设置 provider 的 client id/secret 以及 `SSO_REDIRECT_BASE`，可选配置 `SSO_ALLOWED_DOMAINS`、`SSO_DEFAULT_ROLE`、`SSO_AUTO_PROVISION`，然后重新部署。注册重定向 URI `{SSO_REDIRECT_BASE}/api/v1/auth/sso/{google|microsoft}/callback`。平台在签发 session 之前，会针对其 JWKS 验证 provider 的 `id_token`。 **前置条件** — Docker (Compose v2)；针对 k8s/Helm 模式需要 kubectl + 集群以及 Helm 3；`foctl` 需要 Python 3。 **故障排查** — Elasticsearch 首次启动转为健康状态约需 1–2 分钟；Pod 处于 pending/crashlooping 状态 → 执行 `kubectl -n describe pod

`；通过 `./foctl logs api` 或 `GET /api/v1/admin/logs/{service}` 查看服务日志。

## 工具套件 每个工具都是独立的产品 (`tools/`)，拥有自己的 CLI 和 `brick.yaml`。你可以单独运行某个工具，或者接入整个平台。完整索引：[`tools/README.md`](tools/README.md) · [`tools/SUITE.yaml`](tools/SUITE.yaml)。 | 工具 | 角色 | Standalone CLI | 文档 | |------|------|----------------|------| | **Talon** | 获取 agent — 宿主机/磁盘/挂载点 → artifact bundle | `talon collect --out case.bundle` | [README](tools/talon/README.md) | | **Sluice** | 接收与路由 — bundle/文件/目录 → 路由后的事件 | `sluice ingest case.bundle` | [README](tools/sluice/README.md) | | **Babel** | 解析器库 — artifact → `ForensicEvent` (40+ packs) | `babel parse Security.evtx` | [README](tools/babel/README.md) | | **Rosetta** | 标准化器 — `ForensicEvent` → ECS v8 + OSSEM | `rosetta normalize ev.jsonl` | [README](tools/rosetta/README.md) | | **Sigil** | 检测引擎 — ECS + 规则 → 检测结果 | `sigil validate ./rules/` | [README](tools/sigil/README.md) | | **Anvil** | 分析运行器 — artifact + module → 发现的结果 | `anvil run volatility3 -a mem.raw` | [README](tools/anvil/README.md) | | **Augur** | 情报富化 — IOCs → 带评分的 STIX / MISP | `augur enrich iocs.json` | [README](tools/augur/README.md) | | **Pilot** | 调查 agent — 案例 → 自主生成报告 (LLM) | `pilot investigate --case ID` | [README](tools/pilot/README.md) | | **Scribe** | 报告引擎 — 案例 → HTML/PDF/Markdown/DOCX | `scribe report --case ID -f pdf` | [README](tools/scribe/README.md) | | **citadel_contracts** | 每个工具都会导入的 Shared contract 包 | — | [README](tools/citadel_contracts/README.md) | | **Citadel** | 平台 / 整合器 — 案例 · 时间线 · 搜索 · 控制台 | `docker compose --profile full up` | 当前 README | ### 自描述工具 每个工具都会附带一个 `capabilities.yaml` 文件，按平台声明其具备的功能以及各项操作所需的输入。Citadel **根据该声明渲染 UI** —— 包括表单、选项和校验逻辑 —— 然后将用户的输入路由给工具，并将工具的输出返回。只需修改工具的 `capabilities.yaml`（例如为 Talon 添加一项收集功能），Citadel 的 UI 就会随之改变，而**无需修改任何 orchestrator 代码**；`foctl deploy` 会自动将 manifest 注册到 Redis (`fo:capabilities:`) 中，因此仅更改工具**无需重新构建 API**。自定义解析器（Studio）和自定义模块（Anvil registry）会**实时**整合进来 —— 它们无需编辑任何 manifest 即可出现。 ## 功能 | 领域 | 内容 | |------|------| | **获取** | Talon 实时 + 死机收集 (Windows/Linux/macOS/server)；应用内 **Harvest**（从挂载的磁盘映像 / 路径在服务器端进行 Talon 收集）；可断点续传的加密上传；gRPC 远程 agent (mTLS) | | **接收** | 自动识别 40+ 解析器、80+ 取证格式（EVTX, MFT, Registry, Prefetch, LNK, PCAP, Plaso, syslog, Zeek, Suricata, 浏览器, Android/iOS, 磁盘映像） | | **检测** | 1 666 条内置规则（1 487 条覆盖 13 项 ATT&CK 战术的 Sigma 规则 + 179 条原生 ES 查询）；Sigma→ES 转换；ATT&CK 覆盖矩阵；SigmaHQ 导入；运行时可选择关闭 Sigma（支持全局 + 按案例设置） | | **分析** | Hayabusa, RegRipper, YARA, Volatility3, capa/FLOSS, oletools, PE/strings, CTI IOC 匹配 —— 类型化的 `BaseModule` + DAG pipelines | | **搜索** | Elasticsearch 全文搜索 + facets、保存的查询、时间线、CSV 导出、跨案例搜索 | | **标准化** | `ForensicEvent → ECS v8` + OSSEM ATT&CK；对 IP 字段进行 GeoIP / ASN / reverse-DNS 富化 | | **调查** | 由告警触发的自动调查 · 实体图谱（主机↔用户↔IP 横向移动） · 基线 / 稀有 artifact 堆叠 · 逆向杀伤链组装 · 跨案例 Pilot 记忆 · 持续的 co-pilot 监控 · 可编辑的调查模板 | | **AI 辅助** | LLM providers（Anthropic, OpenAI, Ollama, OpenRouter）驱动的 Pilot agent —— 它可以在调查过程中驱动实体图谱 / 稀有 artifact 堆叠 / 跨案例记忆工具 —— 规则生成、摘要总结；成本追踪；**prompt 注入防御**（对不受信任的 evidence 进行净化处理，并作为数据隔离）以及**置信度校准的判定** | | **威胁情报** | STIX/TAXII, MISP, YETI, OTX/URLhaus/AbuseIPDB/Shodan/GreyNoise 富化；受 SSRF 防护的 feed 拉取（针对内部/自签名服务器可按 feed 选择关闭 TLS 验证） | | **认证** | JWT（短时效 SSE 流 tokens） · MFA/TOTP · **通过 Google & Microsoft OIDC 进行 SSO**（自动 provision、域名白名单） · 强制密码轮换关闭默认设置 · 登录速率限制 | | **授权 (RBAC)** | 细粒度权限 + 角色预设（admin/analyst/developer/guest） · **群组**（角色 + 权限 + 公司范围 + 成员） · 按用户直接授权 · 按公司的多租户隔离（受 IDID 防护） · 分级授权 | | **证据完整性** | 防篡改、哈希链的 **审计日志** + 签名的 **证据保管链** manifests（符合法庭标准，支持 HMAC 签名）；API 返回时会脱敏处理 BitLocker 密钥 | | **可观测性** | 结构化 JSON 日志、Prometheus `/metrics`、`/healthz`/`/readyz`、管理员日志查看器、持久化审计追踪 | ## 使用案例控制台 在案例内部，顶部工具栏是命令操作区域，你生成的所有内容 都会流向 **同 一个** 地方 —— **Findings**。每个控制项的功能如下（从左到右）： | 控件 | 功能说明 | |---------|--------------| | **Ingest** | 上传 artifacts（文件、bundles、磁盘映像）或从 S3 拉取。打开接收面板，实时显示每个任务的进度。 | | **AI** | 打开 Pilot —— 自主 AI 调查员。它会读取案例（事件、检测结果**以及 Findings 存储**），运行 tool-calls 并撰写报告。 | | **⚡ Auto-AI: ON/OFF** | 切换开关。当开启 (**ON**) 时，AI 调查会在接收完成的**瞬间自动**启动 —— 无需点击。当关闭 (**OFF**) 时，你需要手动点击 **AI** 按钮来启动。 | | **Findings** | 统一的输出存储库。案例生成的所有内容都会汇总到这里（见下文）。支持按类型/严重程度过滤、导出 CSV、重新接收选中的内容、删除，以及追溯至源事件。 | | **Detect ▾** | 菜单：**Detection Rules** (Sigma/EQL 库)、**Anomalies** (z-score 突发扫描)、**Baseline / 有 artifacts**、**MITRE 覆盖情况**。 | | **Investigate ▾** | 菜单：**IOCs**（观察到的指标 + 威胁情报匹配）、**Process Tree**、**Entity graph** (主机↔用户↔IP)、**Kill chain**、**Co-Pilot**（新增内容 + 跨案例记忆）。 | | **Case ▾** | 菜单：**Notes**、**Templates**、**Report**（导出 MD/HTML/PDF/DOCX）、**Evidence chain**（已签名的证据保管链）。 | | **Modules** | 启动分析模块（Hayabusa、YARA、CAPA、Volatility…）。选择 module → 选择文件 → 启动。**Run status** 链接会显示进度/失败/重试情况；**结果将汇入 Findings**。 | | **🗑 Delete** | 删除案例（需两次点击确认）。 | ### Findings —— 统一的输出 每个分析界面的数据都会自动以统一的格式写入这里 —— 因此你可以通过相同的方式 查询、导出、报告并重新接收它们： - **Modules** 在完成时会将其检测结果写入 Findings。 - **IOC 威胁匹配**、**异常扫描**、**MITRE 覆盖情况**会自动保存到 Findings（无需“保存”按钮 —— 这些面板是实时的浏览器；Findings 是持久化的记录）。 - **Pilot (AI)** 可以读取存储库，并将其得出的结论保存为 findings。 在 Findings 面板中，你可以： - 按 *kind*（ioc / anomaly / mitre / module / killchain / …）和 *severity*（严重程度）进行**过滤**。 - **导出 CSV** 当前视图的内容。 - **重新接收选中项** —— 将部分内容（或整个类别）作为新的接收任务推回案例中（支持局部或全部）。 - **删除**，或者**追溯**至得出该 finding 的原始事件源。 Findings 本质上是普通的时间线事件 (`artifact_type:finding`)，因此它们同样 可以在时间线中被搜索到，包含在**报告**中，并保留在 `.citadel` 归档导出文件里 —— 没有任何独立的路径。 ### 运行状态与输出对比 启动一个 module 会打开 **Module run status**（进度 / 失败 / 重试 / 日志） —— 这仅代表*状态*，而非输出。只要运行过程发现任何内容，这些结果就会 成为 findings。状态回答了“它是否在运行 / 是否失败了”；而**Findings** 回答了 “我们发现了什么”。这两者被刻意分离开来。 ## 架构 Citadel 是一个由 standalone 工具组装而成的端到端 DFIR pipeline。工具之间之所以能保持独立，是因为它们仅通过 **contracts** 进行通信 —— 而绝不互相干涉内部逻辑。 ``` Talon → Sluice → Babel → Rosetta → {store, Sigil, Anvil, Augur} → timeline → Pilot → Scribe → console ``` - **Standalone 优先 / contract 优先** —— 工具之间互不导入；它们只交换 `ForensicEvent → ECS`、artifact bundles 以及 `brick.yaml` manifests。Contracts 存放在 [`contracts/`](contracts/) + 可通过 pip 安装的 [`citadel_contracts`](tools/citadel_contracts) 包中。 - **单一职责** —— 一个工具只做一项工作；替换规则包、解析器或索引完全不会影响相邻组件。 - **无状态计算，有状态基座** —— 状态数据保存在 Elasticsearch、MinIO、Redis 中；workers 根据队列深度进行扩展。 ### 三大共享层 1. **`ForensicEvent`** —— Babel 解析器输出的内容：必填的 `timestamp`（ISO-8601 **Z**）+ `message`；`artifact_type`（约 90 个条目的路由分类键）；结构化类型包含其 `raw` 原始记录。Rosetta 会将其映射为 **ECS v8 + OSSEM** —— 即时间线、搜索、Sigil 和 Scribe 共同读取的 schema。 2. **Artifact bundle** —— Talon 移交给 Sluice 的便携式单元：`bundle/ manifest.json | events.jsonl | blobs/ | bundle.sha256`。 3. **`brick.yaml`** —— 每个工具的 manifest（包含 `name`、`kind`、`version`、`consumes`、`produces`、`dependencies`、`health`、`status`）。Standalone 使用时完全不需要它。 ### Bus topics 异步 pipeline 基于消息总线运行（默认为 **Redis Streams**；可插拔支持 NATS/Kafka）。每个阶段都是一个 consumer group；消息传递保证为**至少一次**（at-least-once），因此 consumers 会根据 event sha256 / doc id 进行去重。 ``` artifacts.received → events.parsed → events.normalized → {events.indexed, detections.matched, modules.completed, intel.enriched} ``` | Topic | Producer | Consumers | |-------|----------|-----------| | `artifacts.received` | Talon / upload API | Sluice | | `events.parsed` | Babel (via Sluice) | Rosetta | | `events.normalized` | Rosetta | store, Sigil, Anvil, Augur | | `events.indexed` | store | timeline | | `detections.matched` | Sigil | Citadel, webhooks | | `modules.completed` | Anvil | Citadel | | `intel.enriched` | Augur | Citadel | 完整 contract：[`contracts/bus_topics.md`](contracts/bus_topics.md) · schemas：[`contracts/`](contracts/)。 ### 传输（按边缘节点） Pipeline 数据平面使用 Redis Streams · Talon 远程 agent 使用 gRPC + S3/MinIO (mTLS) · 在 Sluice→Babel 的高频调用路径中则通过 `citadel_contracts` 进行进程内通信。 | 组件 | 技术 | |-----------|------| | Frontend | React 18 + Vite + Tailwind (nginx) | | API | FastAPI / Python 3.11 (Uvicorn) | | Workers | Celery (接收 + 模块队列) | | 搜索 | Elasticsearch 8 | | Broker/state | Redis 7 | | Artifacts | MinIO (S3) | | Ingress | Traefik (TLS, host 路由) | ### 代码库布局 - `api/` + `frontend/` — Citadel 平台（整合器）。 - `tools/` — standalone 套件工具 + `citadel_contracts`（shared contract）。 - `contracts/` — 所有工具交互所需的 schemas。 - `charts/citadel/` — Helm · `config/` — 运行时配置 · `k8s/` — 原始 manifests。 ## 运维 - **资源分配** — `scripts/allocate_resources.py` 会检测宿主机的**真实** RAM/CPU，应用 `config/resources.yaml` 中的策略（`max_pct_of_host` 管理员上限，`headroom_pct`，按服务的 `weights`/`storage_weights`），并写入 Helm values overlay。绝对不会过度分配 —— 如果配置申请的资源超过宿主机本身，将被限制并给出警告。可以通过 `scripts/allocate_resources.py --print` 查看分配方案。 - **可观测性** — 每个 worker 都会暴露结构化的 JSON 日志、Prometheus `/metrics` endpoint，以及 `/healthz` + `/readyz`。 - **管理员日志查看器** — 工具会将受限的按服务 JSON 日志流发送至 Redis（`citadel:logs:`）；通过 `GET /api/v1/admin/logs/services` 和 `GET /api/v1/admin/logs/?limit=&level=` 读取。Anvil 每次运行的日志存放在 `fo:module_log:`。 - **锁定工具版本** — `tools/versions.yaml` 会将每个工具锁定到特定的 ref；`scripts/fetch_tools.sh` 会在部署时克隆/检出它们（并能干净地跳过已 vendored 或无法访问的工具）。 ## 开发、测试与贡献 ``` ./scripts/run_tests.sh # 16 suites + Babel→Rosetta→Sigil integration (stdlib-only gate) ``` 测试门禁仅使用标准库（无需 pytest/ES/Redis），并在 CI 中的 Python 3.11 和 3.12 环境下强制运行；如果存在相关依赖，还会在此之上运行一个更丰富的可选 `pytest` 任务。`tests/integration/test_pipeline_e2e.py` 会离线驱动一个真实的 artifact 穿过三个工具边界（`access.log → Babel → Rosetta → Sigil → detection`）。Babel 解析器拥有 golden-file 测试（位于 `tools/babel/tests/golden/`；可通过设置 `BABEL_REGEN_GOLDEN=1` 重新生成）。`citadel_contracts.validate_forensic_event` 负责在运行时强制执行 ForensicEvent contract。 **添加解析器**（常见情况） — 从 cookiecutter 生成脚手架，实现 `parse()`，将 package 放置在 `tools/babel/` 下；loader 会自动发现它，无需注册： ``` cookiecutter tools/babel/template # → manifest.yaml + _plugin.py + test ``` **添加完整的工具** — 新建 `tools//`，仅依赖 `citadel_contracts` + `contracts/` 中的 schemas；提供 `brick.yaml`；输出 `ForensicEvent`；并将其注册到 `tools/versions.yaml` + `tools/SUITE.yaml` 中。**规则：**绝不 `import` 其他工具的内部逻辑 —— 只能通过 contracts 进行交叉交互。时间戳格式必须是 ISO-8601 **Z**；结构化的 artifact 类型必须包含 `raw`；添加测试并保持 `scripts/run_tests.sh` 通过。详见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 CI (`.github/workflows/`) 会运行 lint、测试门禁、多架构镜像构建 + Trivy/SBOM。 ## 授权许可 **Source-available，非商业用途。** 源代码基于 **PolyForm Noncommercial License 1.0.0**（[`LICENSE`](LICENSE)）授权 —— 你可以出于任何**非商业用途**（个人、研究、教育、非盈利组织、政府机构）运行、修改和自行托管。**任何商业用途均需事先获得版权持有人的书面授权**（任何已签署的书面授权书 —— 信件或协议均可） —— 未经授权，严禁用于商业用途。此规定适用于整个代码库，包括 `tools/` 下的 standalone 工具以及共享的 `contracts/`。除许可证外，高级 runtime 层级（pro / enterprise / mssp）需要通过 license key 解锁；无 key → Community 层级。详情：[`LICENSING.md`](LICENSING.md)。

标签：ECS, Elasticsearch, Python, Python工具, React, Syscalls, Terraform, 子域名突变, 安全运营, 扫描框架, 搜索引擎查询, 数字取证, 无后门, 版权保护, 自动化脚本