Ap6pack/ai_tabletop_world_builder

# 网络安全兵棋推演平台 一个**开源** (Apache-2.0)、基于 AI 的桌面兵棋推演平台，专为 IT/安全团队培训设计。生成逼真的网络安全场景，运行 AI 主持的事件模拟，并生成事后报告 —— 兼容 MITRE ATT&CK，基于 FastAPI + Streamlit 技术栈并使用 PostgreSQL 存储。 ## 概述 该平台改编了 AI 桌面 RPG 框架，以创建用于培训目的的**定制化网络安全演练**。它不再使用奇幻世界，而是生成具有 IT 基础设施、漏洞和威胁场景的逼真组织，供安全团队练习技能。 ### 核心功能 - **分层场景生成**：创建具有完整 IT 基础设施的逼真组织 - 组织 -> 部门 -> 系统 -> 漏洞/威胁 - 特定行业的配置（金融、医疗、科技等） - 可定制的复杂度和范围 - **交互式兵棋推演**：实时事件响应模拟 - 基于 AI 的威胁行为者行为 - 逼真的事件时间线 - 工具和访问权限管理 - 决策后果模拟 - **多团队桌面演练**：基于团队的协同演练 - 蓝/红/白队角色，基于轮询的协调机制 - MITRE ATT&CK 集成（涵盖 14 种战术的 93 种技术） - 带有 20 个模板和 6 种启发式算法的危机注入引擎 - 实时演练编排 - **高管与合规仪表板**：战略性报告 - 带有 Ponemon 校准财务指标的高管仪表板 - 针对 NIST CSF、PCI DSS 和 HIPAA 框架的合规评分 - 生成带有 PDF 导出功能的行动后回顾 (AAR) - 决策质量分析和备选路径建议 - **灵活的内容策略**：多级培训标准 - **防御性 (Defensive)**：仅限安全监控和防御措施 - **教育性 (Educational)**：以防御为重点的逼真场景 - **高级 (Advanced)**：面向经验丰富团队的红队战术 - **无限制 (Unrestricted)**：面向专家培训的完全真实性 - **性能跟踪**：监控与改进 - 实时事件仪表板 - 决策跟踪和评分 - 行动后回顾 (AAR) - 团队绩效分析 ## 架构 ### 后端 (FastAPI) ``` api/ ├── models/ # Pydantic data models ├── providers/ # LLM provider abstraction (OpenAI, Anthropic, Ollama) ├── services/ # 37 business logic services ├── routers/ # 12 API routers (81 routes) ├── middleware/ # Auth middleware └── main.py # FastAPI application ``` ### 前端 (Streamlit) ``` app/ ├── Home.py # Main dashboard with full navigation ├── config.py # Centralized configuration ├── constants.py # UI <-> API value mappings └── pages/ ├── 1_Scenario_Builder.py # Generate training scenarios ├── 2_War_Game.py # Interactive war gaming ├── 3_Settings.py # Platform configuration ├── 4_Session_Manager.py # Manage game sessions ├── 5_Scenario_Editor.py # Customize generated scenarios ├── 6_Analytics.py # Performance analytics ├── 7_After_Action_Review.py # AAR review and PDF export ├── 8_Login.py # Authentication ├── 9_Scenario_Library.py # Scenario library browser ├── 10_Exercise_Setup.py # Multi-team exercise setup ├── 11_Exercise_Play.py # Live exercise play └── 12_Executive_Dashboard.py # Executive metrics dashboard ``` ### 数据模型 **组织层级结构：** ``` Organization ├── Departments (Finance, IT, HR, etc.) │ └── Systems (Servers, Applications, Networks) │ └── Vulnerabilities & Security Controls └── Threat Actors (APT, Ransomware, Insider, etc.) ``` **游戏状态：** - 玩家角色和权限 - 可用的安全工具 - 事件时间线 - 目标和评分 ## 快速开始 ### 前置条件 - Python 3.11+ - 至少一个 LLM 提供商的 API 密钥： - OpenAI（推荐） - Anthropic Claude - Ollama（本地，免费） ### 安装 1. **克隆代码仓库** ``` git clone https://github.com/Ap6pack/ai_tabletop_world_builder.git cd ai_tabletop_world_builder ``` 2. **创建虚拟环境** ``` python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. **安装依赖项** ``` pip install -r requirements.txt ``` 4. **配置环境** ``` cp .env.example .env # 使用你的 API 密钥和偏好编辑 .env ``` ### 配置 使用您的设置编辑 `.env` 文件： ``` # 选择你的 LLM provider DEFAULT_LLM_PROVIDER=openai # or anthropic, ollama # 添加 API 密钥 OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... # 设置内容策略 DEFAULT_CONTENT_POLICY=educational # defensive, educational, advanced, unrestricted ``` ### 运行平台 **选项 1：分别运行两个服务** 终端 1 - 启动 FastAPI 后端： ``` python main.py # API 将在 http://localhost:8000 上运行 # API 文档：http://localhost:8000/docs ``` 终端 2 - 启动 Streamlit 前端： ``` cd app streamlit run Home.py # Web UI 将在 http://localhost:8501 打开 ``` **选项 2：Docker (基于 PostgreSQL)** ``` docker-compose up ``` Compose 技术栈会自动运行 API 并连接内置的 **PostgreSQL** 和 Redis 服务（它会为您设置 `DATABASE_URL`/`REDIS_URL`）。可以通过 `POSTGRES_DB`、`POSTGRES_USER` 和 `POSTGRES_PASSWORD` 覆盖数据库凭据。 ## 数据库 可变的应用程序状态 —— 用户、游戏会话、演练、API 密钥和 webhook —— 通过 SQLAlchemy 存储。后端完全由 `DATABASE_URL` 环境变量决定，因此相同的代码可以运行在以下任一环境中： - **本地开发（默认）：SQLite** —— 零配置，文件位于 `./data/app.db`。 - **生产环境：PostgreSQL**（推荐）。指向托管实例： DATABASE_URL=postgresql+psycopg://user:password@host:5432/dbname `psycopg` 驱动程序已包含在 `requirements.txt` 中。API 是无状态的， 因此您可以在负载均衡器后针对单个 Postgres 运行多个实例。 **Schema 迁移：**使用 [Alembic](https://alembic.sqlalchemy.org) 管理。 对于全新的数据库，在启动应用程序之前运行 `alembic upgrade head`；在 后续更改 schema 时，使用 `alembic revision --autogenerate -m "describe change"` 生成迁移脚本，并使用 `alembic upgrade head` 应用它。（为了方便本地/开发使用，应用程序在启动时也会创建任何缺失的 表。） **Redis（可选）：**实时多团队演练可以使用 Redis 作为低延迟 快速通道 —— 设置 `REDIS_URL=redis://host:6379/0`。如果没有它，演练状态将 直接从数据库提供。审计日志在设计上即为只追加的 JSONL。 ## 使用指南 ### 1. 配置 LLM 提供商 进入 **Settings** 页面并配置您的 LLM 提供商： - 选择提供商（OpenAI、Anthropic 或 Ollama） - 输入 API 密钥 - 测试连接 - 设置内容策略级别 ### 2. 生成场景 进入 **Scenario Builder** 页面： - 选择行业（金融、医疗、科技等） - 选择组织规模 - 设置复杂度和难度 - 定义重点领域（勒索软件、APT、内部威胁等） - 选择玩家角色（SOC Analyst、CISO 等） - 点击“生成场景” ### 3. 开始兵棋推演 从生成的场景中： - 查看组织详情 - 检查威胁态势 - 点击“开始兵棋推演” - 实时响应事件 - 使用可用的安全工具 - 做出决策并查看后果 ### 4. 运行多团队演练 进入 **Exercise Setup** 页面： - 配置蓝/红/白队 - 设置演练参数和 MITRE ATT&CK 技术 - 加载危机注入模板 - 启动演练并进行多轮对抗 ### 5. 查看表现 完成场景后： - 在 Analytics 页面上查看事件时间线 - 生成带有 PDF 导出功能的行动后回顾 - 查看高管仪表板以了解财务影响 - 检查针对 NIST/PCI/HIPAA 的合规评分 ## 培训场景 ### 示例场景 **初级：网络钓鱼调查** - 时长：30 分钟 - 角色：SOC Analyst - 重点：电子邮件分析、用户教育 - 工具：SIEM、电子邮件网关 **中级：勒索软件响应** - 时长：90 分钟 - 角色：事件响应人员 - 重点：遏制、恢复、沟通 - 工具：EDR、防火墙、备份系统 **高级：APT 威胁狩猎** - 时长：180 分钟 - 角色：安全工程师 - 重点：威胁检测、横向移动、取证 - 工具：完整的安全技术栈 ## API 文档 ### FastAPI 端点（涵盖 12 个路由的 81 条路径） **LLM 服务：** - `POST /llm/complete` - 生成 LLM 补全 - `GET /llm/providers` - 检查提供商可用性 **内容策略：** - `POST /content-policy/check` - 验证内容安全性 - `GET /content-policy/policies` - 列出可用策略 **场景：** - `POST /scenarios/generate` - 生成培训场景 - `GET /scenarios/list` - 列出所有已保存的场景 - `GET /scenarios/industries` - 列出支持的行业 - `GET /scenarios/industries/{industry}` - 获取行业详情 - `GET /scenarios/{filename}` - 按文件名加载场景 - `DELETE /scenarios/{filename}` - 删除已保存的场景 **游戏：** - `POST /game/start` - 开始新的兵棋推演会话 - `POST /game/action` - 处理玩家动作 - `GET /game/state/{session_id}` - 获取当前游戏状态 - `POST /game/hint` - 请求上下文提示 - `POST /game/end` - 结束游戏会话 - `GET /game/sessions` - 列出所有会话（可选过滤） - `DELETE /game/sessions/{session_id}` - 删除游戏会话 - `POST /game/objective` - 标记目标为已完成/失败 **MITRE ATT&CK：** - `GET /mitre/techniques` - 按战术列出技术 - `GET /mitre/matrix` - 完整的 ATT&CK 矩阵 **演练：** - `POST /exercise/create` - 创建多团队演练 - `POST /exercise/advance` - 推进演练回合 - `GET /exercise/state` - 获取演练状态 **分析与报告：** - `GET /analytics/session/{session_id}` - 会话分析 - `POST /analytics/aar` - 生成行动后回顾 **设置：** - `GET /settings/current` - 获取当前配置 - `POST /settings/update` - 更新设置并持久化到 .env - `GET /settings/storage/stats` - 实时存储统计信息 - `POST /settings/export` - 将配置导出为 JSON - `DELETE /settings/data/clear` - 删除所有数据 - `POST /settings/reset/defaults` - 重置为默认值 API 文档位于：`http://localhost:8000/docs` ## 开发 ### 项目结构 ``` ai_tabletop_world_builder/ ├── api/ # FastAPI backend │ ├── models/ # Data schemas │ ├── providers/ # LLM provider implementations │ ├── services/ # 37 business logic services │ ├── routers/ # 12 API routers │ ├── middleware/ # Auth middleware │ └── utils/ # Shared utilities ├── app/ # Streamlit frontend │ ├── Home.py # Main page │ └── pages/ # 12 pages ├── tests/ # 25 test files (245 tests) ├── docs/ # Phase completion & planning docs ├── scripts/ # Shell scripts and utilities ├── config/ # Configuration ├── scenarios/ # Generated scenarios ├── data/ # Storage ├── monitoring/ # Observability configs ├── main.py # FastAPI entry point ├── Dockerfile # Container build ├── docker-compose.yml # Multi-service orchestration ├── requirements.txt # Python dependencies └── README.md # This file ``` ### 运行测试 ``` pytest --tb=short -q # 244 个通过，1 个跳过 # 测试是封闭的 —— 不需要 API 密钥或网络（一个假的 LLM provider 通过 # tests/conftest.py 注入）。测试位于 tests/ 目录中。 ``` ## 内容策略级别 | 级别 | 描述 | 用例 | 包含 | 排除 | |-------|-------------|----------|----------|----------| | **防御性 (Defensive)** | 仅限防御性安全 | 初级团队，对合规敏感 | 监控、事件响应、控制措施 | 漏洞利用代码、攻击性技术 | | **教育性 (Educational)** | 以防御为重点的逼真场景 | SOC 培训，安全意识 | 漏洞概念、威胁建模 | 真实的漏洞利用、真实的凭据 | | **高级 (Advanced)** | 逼真的攻防对抗 | 经验丰富的团队，红蓝对抗演练 | 红队战术、漏洞利用理论 | 生产级漏洞利用、非法活动 | | **无限制 (Unrestricted)** | 完全的逼真度 | 专家级研究员，受控环境 | 详细的漏洞利用、高级 TTP | 非法活动 | ## 安全考量 - **API 密钥**：切勿提交 API 密钥。请使用 `.env` 文件。 - **内容策略**：为您的团队技能水平设置适当的策略。 - **数据隐私**：场景和游戏数据存储在本地。 - **审计日志**：所有操作均通过 SHA256 哈希记录，以确保合规。 - **身份验证**：基于 JWT 的身份验证，使用 Argon2id 密码哈希。设置 `REQUIRE_AUTH=true`（以及强健的 `JWT_SECRET_KEY`）以强制执行验证：产品 端点随后将要求有效的 bearer token，而破坏性的管理员操作 （`/settings/data/clear`、`/settings/update`、配置写入）则需要 `admin` 角色。在禁用身份验证的情况下（本地/开发默认设置），端点是开放的。 注意：Streamlit UI 尚未附加 token，因此请在禁用了身份验证的 API 上运行它，或者 将其置于身份验证网关之后。 - **速率限制**：所有 API 端点均具有固定窗口限制，以每个 已验证用户（或匿名时的客户端 IP）为键，以保护基于 LLM 的 端点免受滥用。通过 `RATE_LIMIT_ENABLED`、`RATE_LIMIT_REQUESTS` 和 `RATE_LIMIT_WINDOW_SECONDS` 进行配置；使用 Redis (`REDIS_URL`) 以实现跨实例的共享限制， 否则使用进程内计数器。 ## 许可证 版权所有 2026 Adam Rhys Heaton (Ap6pack) 及其贡献者。 基于 **Apache License, Version 2.0** 授权。这是免费的开源 软件 —— 您可以根据该许可证的条款（其中还包括明确的 专利授权）使用、修改和分发它，包括用于商业 目的。有关全文，请参阅 [LICENSE](LICENSE) 文件。 ## 资源 - [API 文档](http://localhost:8000/docs) - [FastAPI 文档](https://fastapi.tiangolo.com/) - [Streamlit 文档](https://docs.streamlit.io/) ## 故障排除 **API 连接失败：** - 检查 `.env` API 密钥是否设置正确 - 验证提供商是否可用（在 `/llm/providers` 测试） - 检查网络连接 **Ollama 不工作：** - 确保 Ollama 正在运行：`ollama serve` - 拉取所需的模型：`ollama pull llama3` - 检查设置中的 base URL **Streamlit 页面未加载：** - 确保您位于 `/app` 目录中 - 检查 FastAPI 后端是否正在运行 - 清除 Streamlit 缓存：`streamlit cache clear` ## 支持 对于问题和疑问： - 在 [GitHub](https://github.com/Ap6pack/ai_tabletop_world_builder/issues) 上提出 issue - 查看文档 **版本**：1.0.0 **状态**：积极开发中 —— 核心平台功能正常且 CI 为通过状态。可变 状态（用户、会话、演练、API 密钥、webhook）通过 SQLAlchemy 存储 （默认为 SQLite，通过 `DATABASE_URL` 可支持 Postgres）。当 `REQUIRE_AUTH=true` 时强制执行身份验证（产品端点需要 token；管理 端点需要 `admin` 角色） —— 有关生产环境设置，请参阅 [DEPLOY.md](DEPLOY.md)。 **最后更新**：2026-07-18 有关完整详细信息，请参阅 [CHANGELOG.md](CHANGELOG.md)。

标签：AI模拟, AI风险缓解, AV绕过, FastAPI, Kubernetes, Petitpotam, PostgreSQL, Streamlit, 战争演习, 搜索引擎查询, 桌面演练, 测试用例, 网络安全, 访问控制, 请求拦截, 逆向工具, 隐私保护