Cairn - A AI general-purpose state-space search engine, va

项目说明

<di="center">

<img src="./README/banner.png" alt="Cairn Banner"/>

Cairn

More Than Just AI Penetration Testing — Towards General State-Space Search

<p>
<a href=" target="_blank" rel="noopener noreferrer">
<img src="./README/tencent.png" alt="Tencent" height="55" />
</a>
<a href=" target="_blank" rel="noopener noreferrer">
<img src="./README/tch.png" alt="TCH" height="55" />
</a>
<a href=" target="_blank" rel="noopener noreferrer">
<img src="./README/c.png" alt="ChainReactors" height="45" />
</a>
</p>

Cairn is a general-purpose problem-solving engine. <br/>It defines no roles, no workflows. Given an origin and a goal, it searches for a path through an unknown state space. <br/>AI Penetration Testing is one such problem — and a proven one.

<p>
<a href=" target="_blank" rel="noopener noreferrer">
<img src=" alt="Discord" />
</a>
<a href=" target="_blank" rel="noopener noreferrer">
<img src=" alt="X" />
</a>
</p>

</div>

<p align="center">
<a href=" target="_blank" rel="noopener noreferrer">
<img src="./README/cairn.png" alt="Cairn runtime screenshot" width="900" />
</a>
</p>

What is Cairn?

Penetration testing is fundamentally a directed search through a near-infinite state space:

This structure is not unique to penetration testing. research, mathematical proof, CTF challenges — any problem with a clear starting point, a clear success condition, and an unknown path in between shares the same shape.

Cairn is built for this class of problems. Penetration testing is the first domain it has been on.

The engine is built on a Blackboard Architecture with an explicit fact-intent graph. Three primitives are all it needs:

| Concept | Meaning |
|---------|---------|
| Fact | A confirmed, objecti written to the board |
| Intent | A declared direction of exploration, not yet executed |
| Hint | Human judgment injected at any time; absorbed by agents on the next read |

The graph grows from origin toward goal. Every new Fact is a stepping stone; every Intent is a step into the unknown.

Agent Workers run an OODA loop — Observe the full graph, Orient to the current state, Decide on next intents, Act to explore — and write their findings back as new Facts. Workers have no fixed roles. Tasks are generated at runtime from the graph's current state, not from predefined job descriptions.

Agents coordinate exclusively through the shared board (Stigmergy). No direct communication. No information silos.

Cairn in Action

How It Works

Three task types, all executed by the same Worker:

| Task | What it does | Output |
|------|-------------|--------|
| Bootstrap | At project start, attempts to solve the problem directly | Fact + possible Complete |
| Reason | Reads the full graph: is the goal met? What should be explored next? | Complete / new Intents / no-op |
| Explore | Claims one Intent, executes the exploration, reports findings | One Fact |

System architecture:

Cairn Server maintains graph consistency only.

Cairn Dispatcher reads the graph, schedules tasks, spins up and tears down worker containers, and is the sole writer to the protocol. Each project gets its own Worker Container; multiple Agent Workers run concurrently inside it. Agent Workers only receive a prompt and return structured output.

Workers can also run directly on the dispatcher host instead of in per-project containers — local mode, no Docker required. See Local mode below.

Supported worker backends: Claude Code, Codex, and Pi.

Results

Tencent Cloud Hackathon · AI Penetration Testing Challenge · 2nd Edition

610 teams · 1,345 participants · top uni and security firms across China

| Metric | Value |
|--------|-------|
| Problems solved | 54 / 54 — only team to AK |
| Final ranking | 3rd |

> The system had never been tested before the competition. The full pipeline came online for the first time at 4 AM on race day. No training, no tuning, no domain-specific tooling. Zero MCP tools, zero RAG, zero predefined agent roles.

Further Reading

Getting Started

Prerequisites

Pull required images

Both setup methods require the worker container image:

Create your local dispatcher configuration and fill in your LLM endpoints and API keys:

Docker Compose (recommended)

Pull the base image used to build Cairn:

This starts cairn-server on port 8000 and cairn-dispatcher once the ser its health check. The dispatcher mounts dispatch.yaml from the project root and connects to Docker via the host socket. Data is persisted to ./datas/cairn/.

Manual

Local mode (no Docker)

Instead of one container per project, workers can run directly on the dispatcher host, reusing the machine's already-configured claude / codex / pi CLIs — no Docker, and no API keys in the config.

Local mode is selected by runtime.execution: local (see dispatch.local.example.yaml). On startup the dispatcher checks each configured worker CLI is installed and runnable, and reminds you they must already be logged in. Each project gets an isolated working directory under local.workspace_root (default: the dispatcher's current directory). Run the dispatcher directly on the host — not inside Docker — since the agents run with your user's permissions and no sandbox.

Tests

Run the fast regression suite without Docker or li endpoints:

Disclaimer

Cairn is a general-purpose problem-solving engine. Although it supports penetration testing, CTF solving, security assessment, and research workflows, it is intended to be used only in en where you ha authorization to operate.

You are solely responsible for how you use this project. Do not use Cairn against systems, networks, applications, or data without clear prior permission from the owner or operator. Unauthorized security testing, exploitation, or data access may be illegal and may cause harm.

The de and contributors of this project do not endorse or accept responsibility for any misuse, abuse, damage, loss, or legal consequences arising from its use. By using this project, you agree to ensure that your acti comply with all applicable laws, regulations, contractual obligations, and professional or organizational policies in your jurisdiction.

Star History

<a href=" target="_blank" rel="noopener noreferrer">
<img src=" alt="Star History Chart" />
</a>

⚖️ License

Commercial Use: If you wish to use this project in a commercial or proprietary en without the AGPL-3.0 open-source obligations, please contact me to obtain a commercial license.

Contributions: By submitting a Pull Request, you agree that your contributions may be used under both the AGPL-3.0 and the project's commercial license.

项目信息

开发语言：Python

Star 数：3215

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A AI general-purpose state-space search engine, validated first on autonomous penetration testing.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

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

使用与学习建议

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

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

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

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

免责声明

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