Kaademos/kademos-yggdrasil

## 📖 概述 **Yggdrasil 项目** 将 OWASP Top 10:2025 变成了一次远征。你攀登的不再是一张漏洞清单，而是世界树 —— 十个以北欧神话为主题的神域，每个都是一个包含一类现实世界缺陷的独立 Web 应用。攻破神域，夺取 flag，彩虹桥（Bifröst）将为你通向下一关而开启。 它像是一款精心打造的产品，而不是实验室的堆砌：一个经过加固的控制平面守护着十个故意留下漏洞的神域，每个神域都封闭在各自隔离的 Docker 网络中，因此你破坏的任何东西都不会波及不该触碰的区域。只需一条命令即可启动整个平台。 | | | |---|---| | 🎯 **在破坏中学习** | 动手利用真实的漏洞类别，与 OWASP Top 10:2025 一一对应 | | 🧗 **渐进式攀登** | 神域按顺序解锁 —— 从 Niflheim 冰冻的根部到 Asgard 金色的城堡 | | 🛡️ **架构安全** | 易受攻击的代码仅存在于网络隔离的神域容器内；控制平面的目标符合 ASVS Level 2 | | 🏆 **游戏化** | 全球排行榜、各神域独立计分，以及用于首发破旗和完成挑战的可选 Discord 广播 | | 🧭 **永不卡壳** | 渐进式提示（会扣除分数）可在不阻碍进度的情况下为你提供帮助 | | ⚡ **一键设置** | `make yggdrasil` —— 环境、依赖和完整技术栈，几分钟内准备就绪 | ## 🗺️ 十大神域 攀登从地下开始，向光明处进发。每个神域都是一个展示某个 OWASP 类别的独特环境 —— 难度也会随着海拔的升高而增加。 | 神域 | 顺序 | OWASP 类别 | 挑战内容 | |-------|:-----:|----------------|---------------| | 👑 **Asgard** | `01` · 最终关 | [A01:2025](https://owasp.org/Top10/) 失效的访问控制 | 金色城堡 —— HR 金库中的 IDOR 和 SQLi | | ✨ **Alfheim** | `02` | [A02:2025](https://owasp.org/Top10/) 安全配置错误 | 云端神域 —— SSRF → IMDS → S3 | | 🌍 **Midgard** | `03` | [A03:2025](https://owasp.org/Top10/) 供应链故障 | 大市场 —— 被入侵的包仓库 | | 🔐 **Vanaheim** | `04` | [A04:2025](https://owasp.org/Top10/) 加密机制失效 | 商人神域 —— 弱 PRNG 和损坏的加密 | | ⚒️ **Nidavellir** | `05` | [A05:2025](https://owasp.org/Top10/) 注入 | 矮人熔炉 —— SQL 注入 | | 🔥 **Muspelheim** | `06` | [A06:2025](https://owasp.org/Top10/) 不安全的设计 | 火焰神域 —— DeFi 竞态条件 | | ❄️ **Jotunheim** | `07` | [A07:2025](https://owasp.org/Top10/) 身份验证失效 | 冰巨人大本营 —— 会话固定 | | ⚙️ **Svartalfheim** | `08` | [A08:2025](https://owasp.org/Top10/) 软件与数据完整性故障 | 地下矿井 —— 不安全的反序列化 | | ☠️ **Helheim** | `09` | [A09:2025](https://owasp.org/Top10/) 日志记录与监控失效 | 纪念论坛 —— 死亡之域中的 LFI | | 🌫️ **Niflheim** | `10` · 入门关 | [A10:2025](https://owasp.org/Top10/) 异常情况 | 冷冻休眠设施 —— SCADA 面板中的 SSRF |

The landing page renders the OWASP Top 10 as a literal climb — Asgard at the crown, Niflheim at the roots.

## ✨ 特性 ### 🏗️ 平台 - **🔐 加固的控制平面** —— Gatekeeper 遵循 OWASP ASVS Level 2 处理身份验证、会话、CSRF、安全头和反向代理。 - **🎯 集中式 flag 验证** —— Flag Oracle 验证提交并强制执行线性进度；只有前一个神域的 flag 才能解锁下一个。 - **🔒 网络隔离** —— 每个神域都在自己的 Docker 网络中运行，只能通过 Gatekeeper 访问，从而防止横向移动。 - **🏆 排行榜与评分** —— 采用 Redis 有序集合构建的“英灵殿”，具有隐私遮盖的用户标识和不断升级的单个神域得分。 - **🧭 渐进式提示** —— 由神域编写的提示，虽然会扣除分数但绝不阻挡你的脚步；在 UI 中以“Mimir 的忠告”形式呈现。 - **📣 Discord 广播** *（可选）* —— 通过 webhook 实时广播攻破、首发破旗和全部完成的通知。 - **📊 可观测性** *（可选）* —— 完整的 Prometheus / Loki / Grafana 技术栈，采用解耦设计，确保默认启动依然快速。 ### 🤖 AI 与安全研究 - **🎓 攻击轨迹生成** —— 请求/响应活动日志采用的格式可直接用于 LLM 微调。 - **📊 扫描器基准测试** —— 在已知的易受攻击基线上测试 Nuclei、ZAP 和自定义扫描器。 - **📋 漏洞清单** —— 包含所有十个神域的 CWE/CVSS 文档，并在 CI 中进行验证。 - **🔬 研究工具** —— 用于扫描器评估的示例 notebook 和记分卡生成。 ## 🚀 快速开始 ### 前置条件 - **Docker** 20.10+ 和 **Docker Compose** 2.0+（[安装](https://docs.docker.com/get-docker/)） - **Make**（推荐）和 **Git** - 仅当需要在 Docker *之外* 进行本地开发时，才需要 Node.js 20+ ### 一键设置 ``` git clone https://github.com/Kaademos/kademos-yggdrasil.git cd kademos-yggdrasil # 生成环境，安装依赖，并启动每个服务 make yggdrasil ``` 大功告成 —— 平台已在 **http://localhost:8080/** 上线。打开它，点击 **INITIATE ASCENSION**，从 Niflheim 开始你的旅程。 ### 验证健康状态 ``` make quick-test # health checks for gatekeeper, flag-oracle, landing page, realms API curl http://localhost:8080/health # {"status":"ok","service":"gatekeeper"} ``` 新来的？[**快速入门指南**](QUICKSTART.md) 将在五分钟内带你完成首次攀登。 ## 🏛️ 架构 艺术图不仅仅是装饰 —— 世界树 *就是* 架构本身。Bifröst 是入口网关，树干是承载“数据树液”向上的 Gatekeeper 代理，每个分支都是一个网络隔离的神域，而树冠则是最终的挑战。 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Internet / Player │ └───────────────────────────────┬─────────────────────────────────┘ │ ┌───────────▼───────────┐ │ Yggdrasil Gatekeeper │ Port 8080 │ ──────────────────── │ │ • Cinematic landing │ │ • Auth & sessions │ │ • Reverse proxy │ │ • Progression gating │ └──┬─────────────────┬───┘ │ │ ┌─────────────▼──────┐ ┌──────▼──────────────────┐ │ Flag Oracle │ │ Realms (10 isolated) │ │ Port 3001 │ │ ───────────────────── │ │ • Flag validation │ │ Niflheim → … → Asgard │ │ • Progression │ │ each in its own │ │ • Scoring & hints │ │ Docker network, │ │ (Redis + backup) │ │ reachable only via │ └────────────────────┘ │ the Gatekeeper │ └─────────────────────────┘ ``` ### 组件 | 组件 | 技术栈 | 职责 | |-----------|-------|----------------| | **Gatekeeper** | Node.js · Express · TypeScript · React | 落地页、身份验证、会话、CSRF、安全头、反向代理、进度控制 | | **Flag Oracle** | Node.js · Express · TypeScript · Redis | flag 验证、进度状态、评分、提示；Redis 为主，具备基于文件的兜底方案 | | **神域** (×10) | Node.js · Python · Java | 每个神域都实现一个蓄意设计的漏洞，并隔离在其专属网络中 | | **可观测性** *(可选)* | Prometheus · Loki · Promtail · Grafana | 指标、日志聚合、仪表盘 | ### 网络拓扑 ``` yggdrasil_main (bridge) ├── gatekeeper ← the only service attached to every realm network ├── flag-oracle └── redis niflheim_net (isolated) └── niflheim helheim_net (isolated) └── helheim … (8 more isolated realm networks) asgard_net (isolated) ├── asgard └── asgard-db (PostgreSQL) ``` ## 📁 项目结构 ``` kademos-yggdrasil/ ├── gatekeeper/ # Control plane: auth, proxy, progression gating │ ├── frontend/ # React + Tailwind landing page (Hero, RealmMap, Leaderboard…) │ ├── src/ # config · middleware · routes · services · utils │ └── tests/ # Jest unit, integration & regression tests ├── flag-oracle/ # Flag validation, scoring, hints (Redis + file fallback) ├── realms/ # Ten challenge environments + shared infra & template │ ├── niflheim/ … asgard/ │ ├── _shared/ # Shared styles, error middleware & templates │ └── _template/ # Scaffold for new realms ├── tests/ # Cross-service E2E, security & integration suites ├── scripts/ # Setup, smoke tests, secret scanning, journey tests ├── config/ # Observability configs (loki, promtail, prometheus, grafana) ├── docs/ # Developer, operator, workflow & per-realm documentation ├── docker-compose.yml # Core stack ├── docker-compose.observability.yml # Optional monitoring stack └── Makefile # Developer commands (make help) ``` ## 🛠️ 开发 运行 `make help` 获取完整列表。以下是基础命令： | 命令 | 描述 | |---------|-------------| | `make yggdrasil` | 设置 **并** 启动所有内容（首次运行） | | `make up` / `make down` | 启动 / 停止所有服务 | | `make logs` | 查看所有服务的日志 | | `make dev-gatekeeper` | 在后端 + 前端热重载模式下运行 Gatekeeper | | `make test` | 单元 + 集成测试 | | `make test-all` | 完整测试套件：单元 + 集成 + E2E + 安全测试 | | `make info` / `make urls` | 服务状态 / 所有可访问的 URL | | `make clean` | 停止服务，移除卷，清理构建产物 | ### 添加新神域 1. 从模板构建：`cp -r realms/_template realms/your-realm` 2. 配置 `package.json`、`src/config/index.ts`，并将其 flag 添加到 `.env` 中 3. 在 `docker-compose.yml` 中注册服务及其隔离的网络 4. 将元数据添加到 `gatekeeper/src/config/realms-metadata.ts`（名称、顺序、OWASP 类别、主题、徽标） 5. 实现漏洞，编写其 `manifest.json`（提示 + CWE/CVSS），并添加测试 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解编码规范和 PR（Pull Request）流程。 ## 🧪 测试 Yggdrasil 提供了一套分层的测试套件，在你的机器和 CI 上运行的方式完全相同，因此本地运行通过就意味着流水线也会通过。 | 层级 | 覆盖范围 | 运行命令 | |-------|----------------|--------| | **单元测试** | Gatekeeper 与 Flag Oracle 逻辑、神域元数据不变量、React 组件 (jsdom) | `make test-unit` | | **集成测试** | API 契约、神域访问与 flag 生成、冒烟测试 | `make test-integration` | | **E2E** | 完整的 Niflheim → Asgard 旅程和落地页攀登 (Playwright) | `make test-e2e` | | **安全测试** | 安全头、速率限制、机密扫描 | `make test-security` | ``` make test # unit + integration (fast inner loop) make test-all # everything ``` 控制平面（Gatekeeper 和 Flag Oracle）的测试覆盖率通过 Jest 阈值强制要求在 **≥70%**。CI 还会额外运行 ESLint、Prettier、清单验证、依赖/机密扫描以及 Snyk 门禁 —— 参见 [`.circleci/config.yml`](.circleci/config.yml)。 ## 🔒 安全 **切勿** 部署到生产环境、在未隔离的情况下暴露给公共互联网，或在你在乎的机器上运行。**务必** 在隔离的网络或专用的训练主机上运行。 **控制平面**（Gatekeeper 和 Flag Oracle）遵循不同的标准，目标为 OWASP ASVS Level 2：安全的会话 cookie、对更改状态的路由进行 CSRF 保护、全套安全响应头、对身份验证和 flag 提交进行速率限制、输入验证、基于环境的机密管理以及 Docker 网络隔离。 在 **控制平面** 中发现了缺陷（而不是故意的神域漏洞）？请私下报告 —— 参见 [SECURITY.md](SECURITY.md)。 ## 📚 文档 | 文档 | 描述 | |----------|-------------| | [QUICKSTART.md](QUICKSTART.md) | 五分钟设置与首次攀登 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献指南与规范 | | [SECURITY.md](SECURITY.md) | 漏洞披露政策与范围 | | [CHANGELOG.md](CHANGELOG.md) | 版本发布历史 | | [docs/guides/DEVELOPER.md](docs/guides/DEVELOPER.md) | 开发者入职指南 | | [docs/guides/OPERATOR_GUIDE.md](docs/guides/OPERATOR_GUIDE.md) | 生产部署与运维 | [docs/workflows/QUICK_REFERENCE.md](docs/workflows/QUICK_REFERENCE.md) | 命令、API 和配置 | | [docs/workflows/ASVS_COMPLIANCE.md](docs/workflows/ASVS_COMPLIANCE.md) | 安全控制矩阵 | | [docs/AI-TRAINING.md](docs/AI-TRAINING.md) | 攻击轨迹生成与 AI 研究 | 每个神域在 [`docs/realms/`](docs/realms/) 下都有自己的指南（漏洞、利用路径、flag 位置、学习目标）—— 例如 [`docs/realms/10-niflheim.md`](docs/realms/10-niflheim.md)。 ## 🗺️ 路线图 **已完成** - ✅ 所有十个神域均已实现、主题化并经过测试 - ✅ 全球排行榜与各神域计分 - ✅ 渐进式提示（“Mimir 的忠告”） - ✅ 可选的 Discord 广播 - ✅ 可选的可观测性技术栈 (Prometheus / Loki / Grafana) - ✅ 攻击轨迹生成与扫描器基准测试 - ✅ WCAG AA 级、支持移动端响应的 UI **计划中** - [ ] 针对每个神域的难度模式（简单 / 普通 / 困难） - [ ] 用于协作解题的团队模式 - [ ] 成就与速通徽章 - [ ] 各神域完成情况分析 - [ ] 为每个神域提供讲师教学指南 - [ ] 国际化 (i18n) ## 📄 许可证 基于 **MIT License** 发布 —— 参见 [LICENSE](LICENSE)。 **免责声明：** 本平台包含出于教育目的的故意设置的漏洞代码。请负责任地使用，且仅在受控环境中运行。 ## 📞 支持与联系 - **问题：** [GitHub Issues](https://github.com/Kaademos/kademos-yggdrasil/issues) - **讨论：** [GitHub Discussions](https://github.com/Kaademos/kademos-yggdrasil/discussions) - **社区：** [Discord](https://discord.gg/y82Hg9CnSk) - **控制平面安全报告：** 参见 [SECURITY.md](SECURITY.md)

标签：Docker, JS文件枚举, MITM代理, OWASP Top 10, 安全培训, 安全实战, 安全防御评估, 搜索引擎查询, 测试用例, 漏洞靶场, 网络安全, 自动化攻击, 自定义请求头, 请求拦截, 逆向工具, 防御检测, 隐私保护