浑乡 - 浑象 AI代理CTF 靶场竞赛平台

项目说明

中文文档 | English

浑象 - 开源版 (Benchmark Platform)

A CTF challenge platform for security capability e — the open-source e infrastructure for AI agents and security teams. Dynamically manages challenge instances Compose, with Web UI, REST API and MCP Ser.

Features

Screenshots

| Dashboard | Challenges |
|-----------|-----------|
| !Dashboard | !Challenges |

| Challenge Store | Prebuild |
|----------------|----------|
| !Store | !Prebuild |

Quick Start

Requirements

Install

Prepare Challenge Data

Start the platform and na to "靶场管理" (Challenge Store) in the Web UI sidebar to browse and download challenges.

Alternatively, set up manually:

Run

Options:

| Flag | Description | Default |
|------|-------------|---------|
| --benchmark-folder | Challenge directory (can be repeated) | required |
| --benchmark-id / -i | Load only specific IDs | all |
| --challenges-dir | Root directory for store downloads | ./challenges |
| --admin-token | Admin token for Web UI login (random if omitted) | random |
| --host | Host to bind to | 0.0.0.0 |
| --port | Server port | 8088 |
| --public-accessible-host | Public hostname for challenges | localhost |
| --no-le | Disable le unlock | false |

The --admin-token can also be set via the ADMIN_TOKEN en . On startup the ser the acti token to the console.

To hide public repository links, the powered by wgpsec footer, and the import/authoring guidance in the Challenge Store, start the server with:

A :

Access

Open in your browser. You will be redirected to the login page — enter the admin token printed in the console to get full access. Team observers log in with their own Agent-Token and see a read-only scoreboard.

Project Structure

API

Web UI

| Route | Description |
|-------|-------------|
| GET /web/login | Login page |
| GET /web/scoreboard | Obser (read-only) |
| GET /web/dashboard | Dashboard |
| GET /web/challenges | Challenge list |
| GET /web/history | Submission history |
| GET /web/status | Instance status |
| GET /web/store | Challenge store (download / import) |
| GET /web/prebuild | Image pre-build |
| GET /web/teams | Team management |
| GET /web/settings | Platform settings |

REST API

All endpoints require Agent-Token header. Endpoints marked with 🔒 require the admin (default team) token.

| Route | Description |
|-------|-------------|
| GET /api/challenges | List all challenges |
| POST /api/start_challenge | Start instance {code} |
| POST /api/stop_challenge | Stop instance {code} |
| POST /api/submit | Submit flag {code, flag} |
| POST /api/hint | Get hint {code} |
| GET /api/challenges/{code}/progress | Query flag progress |
| POST /api/stop_all | 🔒 Stop all instances |
| POST /api/challenges/reload | 🔒 Hot-reload newly downloaded challenges |
| POST /api/start_level | 🔒 Start all challenges at a level |
| POST /api/stop_level | 🔒 Stop all challenges at a level |
| GET /api/instance_statuses | 🔒 Batch query instance statuses |

Store API (🔒 Admin only)

| Route | Description |
|-------|-------------|
| GET /api/store/manifest | Fetch remote challenge manifest |
| POST /api/store/download | Download a challenge by ID |
| POST /api/store/download-all | Download all challenges in a category |
| POST /api/store/delete | Delete a downloaded challenge |
| POST /api/store/import | Import a local zip file |

Prebuild API (🔒 Admin only)

| Route | Description |
|-------|-------------|
| POST /api/prebuild/start | Start image pre-build (supports selective {codes: [...]}) |
| POST /api/prebuild/stop | Stop pre-build |
| GET /api/prebuild/status | Query pre-build progress |
| POST /api/prebuild/remove | Remove a pre-built image |
| POST /api/prebuild/remo | Remo pre-built images {codes: [...]} |
| POST /api/prebuild/remo | Remove all pre-built images |

MCP Server

The platform exposes an MCP (Model Context Protocol) endpoint at /mcp/ using Streamable HTTP transport, allowing AI agents to interact with challenges directly.

Tools:

| Tool | Description | Parameters |
|------|-------------|------------|
| list_challenges | Get challenge list with team progress | — |
| start_challenge | Start a challenge instance | code |
| stop_challenge | Stop a running instance | code |
| submit_flag | Submit flag answer | code, flag |
| | View challenge hint (10% score penalty) | code |

Authentication: Authorization: Bearer <agent_token> header.

Claude Code example:

JSON config (Cursor, Cline, Windsurf, etc.):

Agent Integration

The platform supports two integration methods for AI agents:

1. MCP (recommended) — Connect HTTP at /mcp/, AI agents call tools directly without writing HTTP code. See MCP Server section above.

2. REST API — Standard HTTP endpoints at /api/*. Authenticate with Agent-Token: <token> header. See REST API section above.

For complete API/MCP protocol documentation and integration examples (LangChain, openai-agents, Python native), see the Tsec-Hackathon documentation.

Challenge Format

Each challenge is a directory containing:

The platform injects a unique flag{uuid} into each instance at startup — challenge source code should read the flag from the FLAG en rather than hardcoding it.

> Contributing challenges: This repo is the platform only. Challenge source code lives in benchmark-challenges. To add or modify challenges, submit PRs there.

Tech Stack

References

WgpSec Agentic Ecosystem

benchmark-platform is the e layer of the WgpSec Agentic Ecosystem — measuring how well AI agents perform in real offensi scenarios.

| Project | Role |
|---------|------|
| AboutSecurity | Structured pentest knowledge base (Skills, Dic, Payload, Vuln) |
| context1337 | MCP Server — turns AboutSecurity into a searchable API for AI agents |
| tchkiller | Autonomous pentest agent with multi-round decision-making and team collaboration |
| benchmark-platform | HunXiang CTF challenge platform for e agent offensi |
| benchmark-challenges | Challenge data repository — packed & distributed Releases |
| PoJun | General-purpose AI problem-solving engine (private) |

FAQ

"all predefined address pools have been fully subnetted"

When starting many challenges simultaneously, Docker may run out of network address space. This is because Docker allocates a /16 subnet per network by default, which limits the total number of networks.

Fix: Add default-address-pools to your Docker daemon config (Docker Desktop → Settings → Docker Engine):

Click Apply & Restart. This allocates /24 per network (254 IPs each, more than enough for a challenge), allowing 4000+ concurrent networks.

License

MIT

项目信息

开发语言：Python

Star 数：128

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕浑象 AI agent CTF 靶场竞赛平台展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。