flying-space-turtles/Sandcastle

# Sandcastle [](https://github.com/Matteoverzotti/Sandcastle/actions/workflows/ci.yml) [](https://sandcastle.matteoverz.xyz/) [](LICENSE)   

Sandcastle 是一个基于 Docker 的本地攻防 CTF 竞技场，用于在真实的安全游戏循环中测试自主软件智能体。 它为每支队伍提供了一个可变的 Linux 工作区、一个故意留有漏洞的服务、稳定的网络目标、由 checker 驱动的回合、经过身份验证的 flag 提交、确定性的评分系统、实时的操作员控制台，以及用于挑战生成和攻防智能体的 AI Lab。 该项目的构建旨在进行这样的实验：智能体需要做的不仅仅是解决静态难题。它们必须检查陌生的代码、修补自己的服务、保持其运行、攻击对手、提交 flag，并在明确的基础设施和凭证边界内进行操作。 ## 实时部署 当前的公共 staging 部署可在 [sandcastle.matteoverz.xyz](https://sandcastle.matteoverz.xyz/) 访问。 Staging 环境是一次性的，并且由 PR 驱动。它旨在合并之前，针对真实的 VPS 部署验证操作员控制台、路由、生成的挑战以及 bot-controller 工作流。部署路径记录在 [Staging 部署](docs/staging-deploy.md) 中。 ## 快速开始 要求： - 安装了 Docker Engine 和 Docker Compose 插件的 Linux 主机。 - 用于后端脚本和测试的 Python 3.12。 - 用于构建 visualizer 的 Node.js 22。 生成本地竞技场并启动它： ``` ./scripts/setup.sh ./scripts/arena.sh up ./scripts/arena.sh status ``` 在 [http://127.0.0.1:4173](http://127.0.0.1:4173) 打开 visualizer。 有关操作员凭证、团队 SSH 访问、bot 命令和故障排除，请参阅[操作员指南](docs/operator-guide.md)。 ## Sandcastle 提供的内容 - 根据 `config/arena.env` 生成的可重现的多团队 CTF 竞技场。 - 每个团队专属的 SSH 网关、易受攻击的机器和服务容器。 - 用于比赛、回合、flag、提交、评分和恢复的持久化 gameserver。 - 具有 PUT、GET 和 CHECK 操作的强类型服务 checker。 - 确定性的攻击、防御和 SLA 评分事件。 - 用于团队间流量可见性和源地址伪装的防火墙/代理层。 - 用于比赛控制、记分板、拓扑结构、流量事件、bot 部署和 AI 智能体工作流的 React visualizer。 - 具有有限规划、受限凭证、脱敏记忆和遥测功能的脚本化 bot 和基于模型的攻防智能体。 - 一条挑战生成路径，其中模型选择已注册的工具，而本地代码负责渲染、验证和发布。 ## 存在的原因 Sandcastle 是一个面向安全严苛环境中智能体软件工程的实验平台。它旨在探索以下问题： - 智能体能否在不破坏其 checker 的情况下修补易受攻击的服务？ - 智能体能否在攻击不断变化的对手的同时防御自己的系统？ - 当执行是强类型的、受限的、经过审计的，并且与提供商凭证隔离时，基于模型的工具能否发挥作用？ - CTF 基础设施能否为评分、行为和成本生成可重放的证据？ ## 总体概述 ### 基础设施架构 部署视图展示了主机、Docker runtime、gameserver、防火墙、visualizer、bot controller 和重复的团队槽位是如何组合在一起的。

### 回合流程 回合流程遵循一个从 flag 创建到 checker 操作、持久化结果、分数核对以及仪表板更新的完整评分周期。

### CI/CD 和 Staging CI/CD 视图总结了所需的质量门禁，以及通过标签控制的通往一次性 VPS 竞技场的 staging 部署路径。

### AI 智能体 智能体视图展示了挑战生成、攻防规划、提供商网关、受限凭证、记忆和团队本地工具之间的分离。

## 项目地图 | 区域 | 用途 | |---|---| | `gameserver/` | 比赛状态、回合、flag、提交、评分、checker 和 API。 | | `visualizer/` | 操作员 UI、记分板、拓扑视图、bot 控制和 AI Lab。 | | `bot/` | 脚本化 bot runtime、部署控制器、模型规划、智能体记忆和防御工具。 | | `firewall/` | 用于团队间流量的透明代理和活动流。 | | `services/example-vuln/` | 内置的易受攻击的 Flask 服务、checker 和参考漏洞利用。 | | `scripts/` | 竞技场设置、生命周期、doctor、冒烟测试、清理和 staging 助手。 | | `docs/` | 架构、威胁模型、评分、回合引擎、隔离、staging 和编写指南。 | | `diagrams/` | 本 README 中使用的高级系统图表。 | ## 开发检查 常见的本地验证命令： ``` docker compose config --quiet python3 -B tests/gameserver_test.py python3 -B tests/agent_plan_api_test.py python3 -B tests/openai_provider_test.py ./tests/staging_deploy_test.sh ``` 完整的快速套件可通过以下方式使用： ``` ./scripts/run-tests.sh --fast ``` 当 `config/arena.env` 更改时，重新生成并提交生成的 Compose 文件： ``` ./scripts/setup.sh git diff -- docker-compose.yml config/arena.env ``` CI 强制要求 `docker-compose.yml` 与 `config/arena.env` 保持同步。 ## 部署和机密 Staging 部署由 GitHub Actions 和 `deploy:staging` pull request 标签管理。工作流会检出 PR 的 head，将其同步到 VPS，应用仅用于 staging 的竞技场配置，运行 Docker-in-Docker 冒烟部署，并留下一个运行中的竞技场以供审查。 提供商密钥永远不会被提交。对于基于模型的挑战生成和 AI 智能体，请为 staging 配置这些 GitHub 环境机密： | 机密 | 用途 | |---|---| | `OPENAI_API_KEY` | 启用由 OpenAI 支持的挑战生成和智能体。 | | `GEMINI_API_KEY` | 启用由 Gemini 支持的挑战生成和智能体。 | | `STAGING_OPERATOR_TOKEN` | 授权在操作员控制台进行比赛控制。 | | `STAGING_CHECKER_SECRET` | 服务 checker 使用的主密钥。 | | `STAGING_TEAM_TOKEN_PATTERN` | 包含 `{team}` 的每队提交 token 模式。 | bot controller 仅在部署时通过容器环境变量接收提供商密钥。如果某个提供商在 UI 中显示为 `key not detected`，请检查 staging 工作流机密和 `bot-controller` 的 runtime 环境。 ## 文档 - [操作员指南](docs/operator-guide.md) - 本地设置、竞技场生命周期、团队访问、bot、故障排除和开发检查。 - [架构](docs/architecture.md) - 容器拓扑、生成的服务、持久化、提交、评分和操作员控制台行为。 - [威胁模型](docs/THREAT_MODEL.md) - 信任边界、特权资源、逃逸路径以及针对共享或公开事件的控制。 - [回合引擎](docs/round-engine.md) - 比赛控制、持久化回合、checker 阶段、恢复和单步行为。 - [评分](docs/scoring.md) - 攻击、防御、SLA、重放、幂等性和平局排序。 - [隔离](docs/isolation.md) - 可信、过滤代理和 Docker-in-Docker 操作模式。 - [编写 checker](docs/writing-checkers.md) - checker 插件契约和服务编写规范。 - [Staging 部署](docs/staging-deploy.md) - 通过 PR 标签控制的部署到一次性 staging VPS。 - [产品方向](VISION.md) - 长期目标和产品定位。 - [审计和待办事项](docs/PROJECT_AUDIT_AND_BACKLOG.md) - 当前的优先级和面向智能体的实施任务。 ## 状态和安全 Sandcastle 是一个本地研究和原型设计平台。原生 Linux Docker Engine 是最受支持的 runtime，对于不受信任的参与者，Docker-in-Docker 模式是当前最接近生产环境的选项。 在运行共享、公开或云暴露的活动之前，请阅读[威胁模型](docs/THREAT_MODEL.md)。默认的可信本地模式适用于受控的开发环境，而不是作为安全边界。 ## 许可证 Sandcastle 在 MIT 许可证下发布。请参阅 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, CISA项目, Docker, OPA, XXE攻击, 安全攻防, 安全防御评估, 版权保护, 自动化安全代理, 靶场