heimdall-agent - 用于授权CT的自主AI代理框架

项目说明

<p align="center">
<img src="console/public/mark.jpg" alt="Heimdall logo" width="80" height="80">
</p>

<h1 align="center">Heimdall</h1>

<p align="center">
<strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
</p>

<p align="center">
<strong>An autonomous AI agent framework for authorized CTF and security labs</strong><br>
Circle of Circles · Execute, observe, and keep exploring
</p>

<p align="center">
<a href=" src=" alt="GitHub Actions CI"></a>
<a href="LICENSE"><img src=" alt="License: MIT"></a>
<a href="#quick-start"><img src=" alt="Docker: linux/amd64"></a>
</p>

<p align="center">
<a href="#design-philosophy">Design Philosophy</a> ·
<a href="#system-architecture">System Architecture</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="
</p>

Heimdall brings task scheduling, an AI solver, an observer, and a toolkit together in a self-hosted workspace. Add a target, launch a task from your browser, inspect exploration paths, execution logs, and node e, and track result . The current CTF sol the design; broader authorized lab capabilities will follow in future iterations.

> Only test systems you own or ha permission to assess. Stay within the authorized scope.

Results: Heimdall placed in the Top 2 in both Baidu's Agent+ online attack-and-defense challenge and Tencent Cloud TSecBench, with the lowest token usage on both leaderboards.

![Tencent Cloud TSecBench leaderboard: Heimdall ranks second with an o score of 96.89]()

Design Philosophy

Circle of Circles: carry what each round learns into the next round's system prompt.

The name draws on Hegel's “Circle of Circles.” Heimdall organizes execution and obser into two loops: the inner Executor follows Thought → Action → Obser; the outer Obser execution records, distills explored paths, constraints, and directions to test into a compact map, and injects it into the solver's next system prompt.

<p align="center">
<img src="docs/heimdall-article-assets/circle-of-circles.png" width="420" alt="Circle of Circles: the inner loop thinks, acts, and observes; the outer loop feeds a map into the next round">
</p>

For CTF tasks, a primary sol hypotheses sequentially while an obser alongside it to maintain the broader picture. This keeps the context focused on the current target, concrete e, and the next decision, helping sol quickly with fewer tokens.

<p align="center">Observer demo: a multistage challenge</p>

System Architecture


The control plane recei and schedules tasks. Pi handles the Regular phase while the obser reads sessions, tool results, and HTTP records, feeding a map back to the solver. Depending on the scheduling policy, unfinished tasks enter goal mode: a Pi summarizer first summarizes the previous run, then the Claude Agent SDK continues the task.

Code Structure

The backend uses TypeScript + Node.js, and the operator desk uses React + Vite + Ant Design. The control plane manages task lifecycles, the Agent executes tasks, and the Obser exploration e and feedback. Scheduling policies, platform integrations, and runtime resources are maintained separately.

Quick Start

Requirements: Docker Engine / Docker Desktop and Docker Compose ≥ 2.24.4. We recommend at least 4 CPUs and 8 GB of RAM. Allow 25 GB of disk space when deploying a prebuilt image, or 50 GB when building from source.

The current image has been built and tested end to end on Ubuntu (linux/amd64). If you encounter issues on another en, please open an issue.

Build from source:

The current has no login mechanism. Bind it to 127.0.0.1 and do not expose it to the public internet.

Once it starts, open

1. In Settings, enter your model gateway URL, model name, and API key. Loop requires an Anthropic-compatible API.
2. Create a project, add an authorized challenge URL or platform code, select a workspace type, and start the task.
3. Inspect the exploration graph and execution logs in the desk. Expand nodes to review e and results.

Report bugs and compatibility issues through Issues.

License

Heimdall's source code is licensed under the MIT License. Third-party tools and templates in the image remain subject to their own licenses and terms.

项目信息

开发语言：TypeScript

Star 数：107

技术要点

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

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

使用与学习建议

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

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

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

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

免责声明

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