IcebergAI/IcebergTTX

# IcebergTTX [](https://github.com/IcebergAI/IcebergTTX/actions/workflows/ci.yml)   一个用于运行网络安全事件和业务韧性场景的桌面演练 (TTX) 平台。  ## 关于 IcebergTTX 帮助团队通过引导式的、基于场景的桌面演练，排练他们应对网络攻击事件及 其他中断事件的响应。**引导者** 可以构建或导入分支场景，然后实时向 **参与者** 发布注入内容；参与者记录决策和自由文本形式的 响应，这些响应会驱动场景走向不同的分支，同时 **观察者** 以只读模式跟进。该平台模拟事件通信（监管机构、 新闻界、高管），并可以使用 Claude API 评估参与者的决策并 建议后续的注入内容。它是 API 优先的 (FastAPI)，带有服务端渲染的 UI，并且 自带 Docker Compose 和 Kubernetes 部署清单。 ## 功能 - **场景库** — 在可视化场景构建器中构建分支注入树（或线性链式流程），或者将其作为 JSON 导入/导出 - **实时演练** — 引导者通过 WebSocket 推送实时发布注入内容 - **参与者响应** — 支持自由文本和多项选择，用于驱动场景分支 - **团队评论主题** — 参与者在群组范围内的评论主题中讨论已发布的注入内容 - **模拟通信** — 双面板收件箱/发件箱，用于监管、媒体和高管通信 - **LLM 评估** — Claude 评估参与者的决策并建议后续注入内容 - **基于角色的访问** — 引导者、参与者和观察者角色（自我注册始终创建为参与者；权限提升需通过频外操作） - **角色预览** — 引导者可以在不切换帐户的情况下以参与者或观察者的身份查看应用 - **安全加固** — 在启动时强制要求设置 SECRET_KEY，安全 cookie + CSRF 来源检查，登录速率限制，以及带有主机外 SIEM 转发（syslog / HTTP / 文件）的结构化审计日志 - **示例模板** — 可以从“设置”加载可选的内置场景；默认情况下数据库保持为空 - **导出** — 完整演练记录 (JSON) 或响应表格 (CSV) ## 截图 上面的主图是 **引导者控制台** — 一个包含按团队分组的注入树的实时演练，支持逐个发布和参与者响应。 | 指挥中心 | 场景注入树 | |---|---| |  |  | | **模拟通信** | **参与者视图** | |  |  | UI 自带浅色/深色主题切换功能（感知系统设置）：  ## 技术栈 - **后端**: Python 3.14+, FastAPI (全异步), SQLModel + 异步 SQLAlchemy, PostgreSQL (asyncpg) - **前端**: Jinja2 模板, Tailwind CSS v4 (通过 CLI 编译), Alpine.js - **实时**: WebSockets (FastAPI 原生) - **认证**: JWT token (httpOnly cookie + localStorage) - **LLM**: 可插拔的 AI 后端 — Anthropic (直连), Amazon Bedrock, OpenAI, Ollama 或 Gemini，通过 `LLM_PROVIDER` 选择 (异步；在 Anthropic 路径上支持 prompt 缓存) ## 设置 _*请注意，此方式已弃用且需要在本地实例化 Postgres，建议使用 Docker*_ ``` # 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 安装依赖。dev extra 包含了所有的 AI-provider SDK，因此所有的 # LLM_PROVIDER 选项都可以在本地开箱即用。 pip install -e ".[dev]" # 对于生产环境安装（`pip install -e .`，不包含 dev），默认不包含任何 LLM SDK — # 请添加与你的 LLM_PROVIDER 匹配的 extra（此处所有 provider 均同等对待）： # pip install -e ".[llm-anthropic]" # anthropic (direct) # pip install -e ".[llm-bedrock]" # bedrock (pulls boto3) # pip install -e ".[llm-openai]" # openai | ollama | gemini # pip install -e ".[llm-all]" # every provider SDK # 配置环境 cp .env.example .env # 编辑 .env： # SECRET_KEY 必需 — 生成命令：python -c "import secrets; print(secrets.token_hex(32))" # DEV_MODE=true 用于本地 HTTP 开发（放宽 SECRET_KEY 检查和 Secure cookie 标志） # LLM_PROVIDER anthropic (默认) | bedrock | openai | ollama | gemini | none — 请参阅 .env.example # 以了解各 provider 的 key/model/endpoint 变量 # 在 DEV_MODE 之外，如果 SECRET_KEY 未设置或强度不够，或者所选的 # LLM_PROVIDER 缺少其凭据，应用将拒绝启动（设置 LLM_PROVIDER=none 可在没有 LLM 的情况下运行）。 # 运行开发服务器 uvicorn app.main:app --reload ``` 打开 [http://localhost:8000](http://localhost:8000)。自我注册始终创建为 **参与者**；特权角色通过频外方式分配。使用 bootstrap 命令创建您的第一个管理员/引导者： ``` # 创建一个 global-admin facilitator（如果省略 --password，则会提示输入密码）。 python -m app.bootstrap_admin --email you@example.com --name "You" ``` 该命令是幂等的 — 重新运行它可以提升或重新启用现有帐户，添加 `--reset-password` 可以设置新密码（撤销现有会话），或者添加 `--no-admin` 将其设为没有全局管理员标志的普通引导者。在容器中，请加上 `docker compose exec app` 或 `kubectl exec -n iceberg-ttx deploy/iceberg-ttx-app --` 作为前缀（参见下文的部署章节）。 作为引导者，创建场景和演练。为了快速试用应用，请打开“设置”并加载示例场景或演示演练。应用内帮助位于 [/help](http://localhost:8000/help)。 ## Docker 部署 提供了一个 `docker-compose.yml` 用于单机部署。它运行应用、PostgreSQL 17 以及作为反向代理的 **Caddy**，并支持 **自动 HTTPS**。 ``` # 复制并填写 secrets（POSTGRES_PASSWORD 和 SECRET_KEY 是必需的） cp .env.example .env # 对于公开部署，请将 SITE_ADDRESS 设置为你的域名（见下文）。 # 构建并启动 docker compose up -d # 检查所有三个服务是否健康 docker compose ps ``` Caddy 通过 **端口 443 上的 HTTPS** 提供应用服务（并重定向 `:80`）。它直接提供编译好的静态文件，并将其他所有请求（包括 `/ws/` 上的 WebSocket 升级）代理到 uvicorn。在 `.env` 中将 `SITE_ADDRESS` 设置为您的公共域名以获取自动的 Let's Encrypt 证书；默认的 `localhost` 使用 Caddy 的 **内部自签名 CA**，因此执行 `docker compose up` 即可立即通过 HTTPS 进行本地测试（您的浏览器会警告证书不受信任 — 这是预期的）。 等栈启动后，创建您的第一个管理员帐户： ``` docker compose exec app python -m app.bootstrap_admin --email you@example.com --name "You" ``` 要在不丢失数据的情况下停止： ``` docker compose down # keeps named volumes (postgres_data, uploads) docker compose down -v # also deletes volumes — permanent data loss ``` ## Kubernetes 部署 部署清单位于 `k8s/` 目录。按顺序应用： ``` kubectl apply -f k8s/namespace.yaml kubectl apply -f k8s/secrets.yaml -f k8s/configmap.yaml # 在应用之前，请替换 k8s/secrets.yaml 中的占位符值， # 替换以下文件中的 'your-registry/iceberg-ttx:latest'： # k8s/app/deployment.yaml # k8s/caddy/deployment.yaml (copy-static initContainer 使用 app 镜像) # （在生产环境中通过摘要锁定 — image@sha256:… — 以实现可重现的发布； # Dependabot 的 docker updater 会保持 base-image 摘要保持最新），并设置 # k8s/caddy/ingress.yaml 中的 hostname/issuer/ingressClassName 占位符。 kubectl apply -f k8s/postgres/ kubectl rollout status statefulset/postgres -n iceberg-ttx kubectl apply -f k8s/app/ kubectl rollout status deployment/iceberg-ttx-app -n iceberg-ttx kubectl apply -f k8s/caddy/ # Deployment + ClusterIP Service + TLS Ingress kubectl rollout status deployment/caddy -n iceberg-ttx # 限制 east-west 流量（需要支持 NetworkPolicy 的 CNI）： kubectl apply -f k8s/networkpolicy.yaml # 创建第一个 admin 账户（幂等）： kubectl exec -n iceberg-ttx deploy/iceberg-ttx-app -- \ python -m app.bootstrap_admin --email you@example.com --name "You" ``` ## 备份和恢复 所有持久化状态都存在于两个位置：**PostgreSQL 数据库**（用户、 场景、演练、注入、响应、通信、审计事件）以及 **`uploads/` 卷**（注入文件附件）。请对两者进行备份 — 仅有数据库转储会引用已不存在的附件文件。定期执行备份；如果没有备份，丢失卷或 PVC 就意味着丢失演练记录。 Alembic 会在启动时自动迁移，因此从 **较旧** 应用版本中获取的转储可以干净地恢复到 **较新** 的版本中 — 架构将在下次启动时自动升级到最新版本。不支持将转储恢复到比获取该转储更 **旧** 的应用中。 ### Docker Compose ``` # --- Database --- # 将数据库（custom 格式）导出到主机上的文件： docker compose exec -T db \ pg_dump -U iceberg_ttx -d iceberg_ttx -Fc \ > "iceberg_ttx-$(date -u +%Y%m%dT%H%M%SZ).dump" # 还原到一个正在运行且为空的数据库中（--clean 会先删除现有对象）： docker compose exec -T db \ pg_restore -U iceberg_ttx -d iceberg_ttx --clean --if-exists \ < iceberg_ttx-YYYYMMDDTHHMMSSZ.dump # --- Uploads volume (inject attachments) --- # 将名为 uploads 的 named volume 打包为主机上的文件： docker run --rm \ -v deep_thought_uploads:/data:ro -v "$PWD":/backup alpine \ tar czf /backup/uploads-"$(date -u +%Y%m%dT%H%M%SZ)".tar.gz -C /data . # 还原它（到同名的 named volume 中）： docker run --rm \ -v deep_thought_uploads:/data -v "$PWD":/backup alpine \ sh -c 'tar xzf /backup/uploads-YYYYMMDDTHHMMSSZ.tar.gz -C /data' ``` ### Kubernetes ``` # --- Database --- # 从 postgres pod 导出到你工作站上的文件： kubectl exec -n iceberg-ttx statefulset/postgres -- \ pg_dump -U iceberg_ttx -d iceberg_ttx -Fc \ > "iceberg_ttx-$(date -u +%Y%m%dT%H%M%SZ).dump" # 还原（将本地 dump 流式传输回 pod）： kubectl exec -i -n iceberg-ttx statefulset/postgres -- \ pg_restore -U iceberg_ttx -d iceberg_ttx --clean --if-exists \ < iceberg_ttx-YYYYMMDDTHHMMSSZ.dump # --- Uploads volume --- # 从 app pod 中拷出 attachments： kubectl cp -n iceberg-ttx \ "$(kubectl get pod -n iceberg-ttx -l app.kubernetes.io/name=iceberg-ttx-app \ -o jsonpath='{.items[0].metadata.name}')":/app/uploads ./uploads-backup ``` #### 计划内的数据库备份（可选） `k8s/postgres/backup-cronjob.yaml` 是一个可直接适配的 `CronJob`，它每日运行一次 `pg_dump`，将数据存入专用的 `postgres-backups` PVC，并具有简单的基于时间的保留策略： ``` kubectl apply -f k8s/postgres/backup-cronjob.yaml ``` 这只是一个 **起点**，而不是完整的备份策略 — 这些转储文件位于集群内的 PVC 上（与数据库处于同一故障域）。为了实现真正的持久化，请将它们复制到集群外（例如存入对象存储），同时备份 `uploads/` PVC，并定期 **测试您的恢复流程**；一份您从未恢复过的备份算不上是真正的备份。 ## 将安全事件转发至您的 SIEM 审计事件（登录、授权拒绝、特权/角色变更、注入 发布/删除、导出、配置变更等）可以发送到主机外的 SIEM，以便 即使 pod 重启或应用遭到破坏，这些事件也能集中化、被保留并可触发警报 (#24)。**应用本身就是转发器** — 无需运行 Vector/Fluent Bit sidecar。 - **实时启用**，位于 `/admin/audit`（仅限管理员）：勾选 *启用审计*， 选择方法，设置最低严重级别，然后点击 **发送测试事件** 以 端到端验证连接性。 - **方法**（任意组合）： - `stdout` — `iceberg_ttx.audit` logger 上始终开启的 JSON 基线；您需要 提供节点级的转发器（Filebeat/Fluentd/Vector）来捕获它。 - `file` — 将 JSON 行追加到文件路径（适用于文件追踪转发器）。 - `syslog` — 基于 UDP/TCP 的 RFC 5424 协议；将 TCP 指向 TLS syslog 收集器以实现 安全传输。 - `http` — 向 Splunk HEC / Elastic / 通用 webhook endpoint 发送 JSON `POST` 请求， 通过 bearer token 进行身份验证。 - **机密处理**：HTTP bearer token **只能** 通过 `SIEM_HTTP_TOKEN` 环境变量 / Secret 进行设置 — 它永远不会存储在数据库中，永远不会 被 API 返回，也不会被记录到日志中。 - **可靠性**：缓慢或不可达的 SIEM（5秒超时）**绝不会阻塞 或导致请求失败** — 每个 sink 都是故障隔离的，并且持久化的 `AuditEvent` 表（`AUDIT_PERSIST=true`）依然是持久的记录。确保 主机时间通过 NTP 同步到 UTC，以便 SIEM 的关联分析准确无误。 从 `SIEM_*` 环境变量中注入默认值（参见 `.env.example`）；随后路由规则 可在 `/admin/audit` 实时修改。在 Kubernetes 中，非机密的路由配置位于 `k8s/configmap.yaml`，而 token 位于 `k8s/secrets.yaml`。 **示例警报规则**（暴力破解检测，关联到登录速率限制器 #11）— 针对已发送事件的 Splunk SPL： ``` index=iceberg_ttx action="auth.login" result="fail" | bin _time span=5m | stats count by _time, source_ip | where count >= 5 ``` 当单个 `source_ip` 在 5 分钟窗口内产生 ≥ 5 次 `auth.login` 失败事件时触发警报。对于 `authz.denied` 激增、`audit.settings_updated` / 角色变更以及意外的 `*.export` 事件，配置类似的规则也是很有必要的。 请将 SIEM 存储视为仅追加模式，并限制其读/写权限，同时设置一个满足您法律/合同要求的保留期限。 ## 单点登录 (OIDC / SSO) IcebergTTX 可以针对外部 OpenID Connect 身份提供者 对用户进行身份验证，以代替或同时使用内置的邮箱/密码存储。此 流程为 **Authorization Code + PKCE**：`GET /api/auth/oidc/{provider}/login` 重定向到 IdP；`GET /api/auth/oidc/{provider}/callback` 验证 响应（`state`、`nonce`，以及通过 IdP 的 JWKS 验证 ID token 的签名/颁发者/受众/有效期），随后发放正常的应用会话 cookie — 这样一来，所有现有的 角色/授权检查均保持不变。 - **`AUTH_MODE`** — `local`（仅密码），`oidc`（仅 SSO；禁用本地登录/注册），或者 `both`（默认）。启用的每个提供者都会在登录页面上渲染一个 “Sign in with …” 按钮；多个提供者可以同时运行。 - **配置** — 首次使用 SSO 的用户会被即时创建为 **参与者**（IdP 永远无法自行分配特权角色）。返回的 身份会通过其稳定的 `sub` 进行匹配；如果经过验证的 *verified* 邮箱与现有的本地帐户匹配，则会将两者关联（保留该帐户的角色）。被禁用的 帐户（`is_active=false`）无论 IdP 如何设置都会被拒绝。 - **角色映射（可选，默认关闭）** — 设置 `OIDC__ROLE_CLAIM` 和 `OIDC__ROLE_MAP`（`group=role,…`）以提升特定 IdP 组成员的权限。未映射的用户仍保持为参与者。 - **机密** — 客户端机密仅从环境中读取 （`OIDC_*_CLIENT_SECRET`）；它们从不存储在数据库中或被记录到日志中。SSO 登录/关联/JIT 配置事件均会被审计（`auth.oidc_login`、`auth.oidc_link`、 `auth.jit_provision`），且不包含 token 或 code。 将 `OIDC_REDIRECT_BASE_URL` 设置为应用公共的 `https://` 源（末尾不要加斜杠），以便回调 URL 与您在 IdP 中注册的相匹配。 ### Microsoft Entra ID 1. **Entra 管理中心 → 应用注册 → 新注册。** 添加一个 **Web** 重定向 URI：`https:///api/auth/oidc/entra/callback`。 2. **证书与机密 → 新客户端机密**；复制其值。 3. 复制 **应用程序(客户端) ID** 和 **目录(租户) ID**。使用 特定的租户 ID — 切勿使用 `common`/`organizations` — 以确保颁发者验证是 精确的。 4. （可选角色）**应用角色** → 定义角色，分配用户/组；它们将包含在`roles` 声明中。设置 `OIDC_ENTRA_ROLE_CLAIM=roles` 并对它们进行映射。 5. 配置： AUTH_MODE=both OIDC_ENTRA_ENABLED=true OIDC_ENTRA_TENANT_ID= OIDC_ENTRA_CLIENT_ID= OIDC_ENTRA_CLIENT_SECRET= # OIDC_ENTRA_ROLE_CLAIM=roles # OIDC_ENTRA_ROLE_MAP=ttx-facilitators=facilitator ### Authentik (可自托管 — 一个很好的测试 IdP) 1. **提供者 → 创建 → OAuth2/OpenID 提供者。** 客户端类型选 **Confidential**； 添加重定向 URI `https:///api/auth/oidc/authentik/callback`。复制 **Client ID** 和 **Client Secret**。 2. **应用程序 → 创建**，选择一个 **slug**，并绑定该提供者。 发现 URL 为 `https:///application/o//.well-known/openid-configuration`。 3. （可选角色）确保提供者启用了 `groups` 作用域；组名将包含在 `groups` 声明中。 4. 配置： AUTH_MODE=both OIDC_AUTHENTIK_ENABLED=true OIDC_AUTHENTIK_BASE_URL=https:// OIDC_AUTHENTIK_APP_SLUG= OIDC_AUTHENTIK_CLIENT_ID= OIDC_AUTHENTIK_CLIENT_SECRET= # OIDC_AUTHENTIK_ROLE_MAP=ttx-facilitators=facilitator ### Auth0 1. **Auth0 控制台 → 应用程序 → 创建应用程序 → 常规 Web 应用程序。** 将 `https:///api/auth/oidc/auth0/callback` 添加到 **允许的回调 URL** 中。复制 **域名**、**Client ID** 和 **Client Secret**。 2. （可选角色）Auth0 默认不发送角色。添加一个 **Action** （登录流程），在 ID token 上设置一个 *带有命名空间* 的自定义声明，例如 `api.idToken.setCustomClaim("https://ttx.example.com/roles", event.authorization?.roles)`， 并将 `OIDC_AUTH0_ROLE_CLAIM` 指向该确切的 URI。 3. 配置： AUTH_MODE=both OIDC_AUTH0_ENABLED=true OIDC_AUTH0_DOMAIN=your-tenant.us.auth0.com OIDC_AUTH0_CLIENT_ID= OIDC_AUTH0_CLIENT_SECRET= # OIDC_AUTH0_ROLE_CLAIM=https://ttx.example.com/roles # OIDC_AUTH0_ROLE_MAP=ttx-facilitators=facilitator ### Okta 1. **Okta 管理员 → 应用程序 → 创建应用集成 → OIDC / Web 应用程序。** 添加 `https:///api/auth/oidc/okta/callback` 作为 **登录重定向 URI**。复制 **Client ID** 和 **Client Secret**，以及 您的 Okta **域名**。 2. 选择授权服务器：将 `OIDC_OKTA_AUTH_SERVER` 留空以使用 **组织(org)** 服务器，或者将其设置为 `default`（或自定义授权服务器 ID）。 发现 URL 为 `https:///oauth2//.well-known/openid-configuration`（组织服务器 省略 `/oauth2/`）。 3. （可选角色）在选定的 授权服务器上向 token 添加 **groups 声明**，以便组名包含在 `groups` 声明中。 4. 配置： AUTH_MODE=both OIDC_OKTA_ENABLED=true OIDC_OKTA_DOMAIN=dev-12345.okta.com OIDC_OKTA_AUTH_SERVER=default OIDC_OKTA_CLIENT_ID= OIDC_OKTA_CLIENT_SECRET= # OIDC_OKTA_ROLE_MAP=ttx-facilitators=facilitator ## 运行测试 ``` pytest pytest tests/ --ignore=tests/test_ui.py # skip live Playwright tests ``` ## 重新构建 CSS 共享的 Iceberg 设计系统（冷灰色 oklch token、青色强调色，以及 `.rail`/`.workspace` 组件词汇表）位于 `static/css/iceberg.css` 中， `input.css` 会将其与 Tailwind 一起导入。在编辑模板或 设计系统后，请重新构建 Tailwind 输出： ``` tailwindcss -i static/css/input.css -o static/css/output.css ``` ## 项目结构 ``` app/ ├── main.py # App factory + lifespan (settings validation, middleware) ├── config.py # Settings (pydantic-settings, reads .env) + startup validation ├── middleware.py # Audit request context + CSRF origin checks ├── database.py # Async Postgres engine + get_session dependency ├── dependencies.py # FastAPI dependencies (auth, role guards) ├── models/ # SQLModel table definitions (incl. AuditEvent, AuditSettings) ├── schemas/ # Pydantic request/response schemas ├── routers/ # FastAPI routers (one per resource, incl. audit) + ui.py (Jinja2 pages) ├── services/ # Business logic (auth, scenario, exercise, inject, inject_comment, response, comms, llm, ws_manager, access_control, audit_service, siem_service, audit_settings_service, rate_limit) ├── samples/ # Bundled quick-start scenario templates (loaded only on demand) └── templates/ # Jinja2 HTML templates ├── base.html # App shell (dark rail + breadcrumb topbar), shared JS helpers ├── dashboard.html # Command center ├── help.html # In-app help & documentation ├── settings.html # Profile, theme, role preview, and sample loader ├── auth/ # login.html, register.html ├── scenarios/ # list, detail, editor ├── exercises/ # list, facilitator console, participant view └── communications/ # inbox tests/ # Pytest test suite (conftest.py + one file per resource) static/css/ # input.css + iceberg.css (shared design system) → output.css (Tailwind CLI compiled) static/fonts/ # Self-hosted Archivo · JetBrains Mono · Spectral (woff2) + fonts.css static/img/ # Iceberg brand marks (SVG) docs/ # README screenshots Dockerfile # Multi-stage build (Tailwind compile + Python runtime) docker-compose.yml # app + postgres:17 + caddy (auto-HTTPS, non-root) docker/Caddyfile # Caddy reverse proxy (automatic HTTPS) + static serving k8s/ # Kubernetes manifests (namespace, secrets, postgres, app, caddy) ``` ## 快速工作流 1. **创建场景** — 场景 → 新建，或导入 JSON 文件 2. **创建演练** — 演练 → 新建，选择一个场景，可选择是否启用 LLM 3. **招募参与者** — 引导者控制台 → 参与者面板，搜索并添加用户 4. **启动并发布注入** — 点击启动，然后在准备好后发布每个注入 5. **审查响应** — 中间面板；选择接下来要发布哪个分支 6. **完成并导出** — 完成按钮，然后从右侧面板导出演练记录/响应 请参阅 [/help](/help) 获取完整的文档，包括场景的 JSON schema。 ## 贡献 欢迎您的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解 开发工作流和提交 PR 的期望，并参阅 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 了解社区标准。安全问题应根据 [SECURITY.md](SECURITY.md) 私下报告。 ## 许可证 基于 Apache License, Version 2.0 授权。有关完整的 文本，请参见 [LICENSE](LICENSE)。版权所有 2026 IcebergAI。

标签：AV绕过, DLL 劫持, FastAPI, 业务连续性, 大语言模型, 子域名突变, 库, 应急响应, 桌面推演, 测试用例, 网络安全, 请求拦截, 逆向工具, 隐私保护