Cairn: A Blackboard-Based State-Space Search Engine That Treats Pentesting as a Graph Problem

What Problem Cairn Solves and Who It Is For

Cairn addresses a specific class of problems: those with a clear origin, a defined goal, and an unknown path between them. The README names penetration testing as the first validated domain, but it also lists vulnerability research, mathematical proof, and CTF challenges as sharing the same shape. The intended user is a security engineer or researcher who wants an AI agent that does not require predefined roles, workflows, or domain-specific tools. Instead of orchestrating a fixed pipeline of scanners and exploits, Cairn treats the task as a search over a state space. The origin might be a target IP, the goal a shell or flag, and the path is something the engine must discover. This framing is useful for open-ended problems where the steps are not known in advance, which is typical of black-box pentesting. The project's own competition result, solving 54 of 54 problems at a Tencent Cloud hackathon, suggests the approach works in a controlled setting, but that result comes from a single event and should not be taken as a general guarantee.

Blackboard Architecture with Facts, Intents, and Hints

The core mechanism is a Blackboard Architecture, which is a shared repository where agents post findings and read the state of others. Cairn defines three primitives: Facts, which are confirmed objective findings; Intents, which are declared directions of exploration not yet executed; and Hints, which are human judgments injected at any time and absorbed by agents on the next read. The graph grows from origin toward goal. Every new Fact is a stepping stone, and every Intent is a step into the unknown. This is a clear departure from agent frameworks that rely on predefined roles or task lists. Workers have no fixed roles. They run an OODA loop: Observe the full graph, Orient to the current state, Decide on next intents, and Act to explore. They then write findings back as new Facts. Coordination happens exclusively through the shared board, a mechanism the README calls stigmergy. There is no direct communication between workers, which avoids information silos but also means that the quality of coordination depends entirely on how well the board represents the state. The graph is the only shared memory, so if a Fact is ambiguous or an Intent is too vague, workers may waste effort on dead ends.

Server, Dispatcher, and Worker Containers: A Concrete Data Flow

The architecture separates concerns into three components. The Cairn Server maintains graph consistency only. It holds the facts, intents, and hints, and exposes a read/write API. The Cairn Dispatcher reads the graph, schedules tasks, and manages worker containers. It is the sole writer to the protocol. Each project gets its own Worker Container, and multiple Agent Workers run concurrently inside it. Agent Workers receive a prompt and return structured output. This design means that the dispatcher controls the lifecycle of workers, spinning them up and tearing them down as needed. The server does not execute any search logic; it only ensures the graph remains consistent. Workers do not talk to each other directly, which simplifies the protocol but places all reasoning burden on the graph state. The README shows that three task types are executed by the same Worker: Bootstrap, which attempts to solve the problem directly at project start; Reason, which reads the full graph to decide if the goal is met and what to explore next; and Explore, which claims one Intent, executes the exploration, and reports a single Fact. This is a clean separation of concerns, but it also means that the system's efficiency depends on the Reason task correctly identifying which intents are worth exploring. If the model behind Reason is weak, the search can become aimless.

Getting Cairn Running: Commands and Configuration

The README provides concrete setup steps. You need macOS or Linux, Python 3.12 or higher, and Docker only for container execution. Local mode does not require Docker, which is a significant relief for developers who want to test without pulling heavy images. First, pull the worker container image: docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest. Then create your local dispatcher configuration by copying the example: cp dispatch.example.yaml dispatch.yaml. You must fill in your LLM endpoints and API keys in that file. For Docker Compose, which is the recommended method, you also need to pull the base image used to build Cairn: docker pull ghcr.io/astral-sh/uv:python3.13-trixie. Then run docker compose up --build. This starts the cairn-server on port 8000 and cairn-dispatcher once the server passes its health check. The dispatcher mounts dispatch.yaml from the project root. The README also mentions that workers can run directly on the dispatcher host in local mode, which avoids Docker entirely. Supported worker backends are Claude Code, Codex, and Pi. The configuration file is the central control point, so getting the LLM endpoints right is the first hurdle. The README does not show the full dispatch.yaml schema, so you may need to inspect the example file to understand available keys.

Where Cairn Falls Short: Limitations and Wrong Use Cases

Cairn is not a plug-and-play penetration testing tool. It does not come with a library of exploits, scanners, or predefined attack patterns. The README is explicit that it defines no roles and no workflows. That means if you expect to point it at a target and get a report, you will be disappointed. The engine relies on the underlying LLM workers to generate useful intents and execute explorations. If the model lacks security knowledge, the search will produce trivial facts or get stuck. Another limitation is the reliance on a shared board for coordination. Stigmergy works when the state representation is rich enough to guide agents, but the README does not describe how facts are structured or how the graph handles conflicting information. In a real pentest, you often have false positives or incomplete data, and there is no mention of how Cairn handles uncertainty. The competition result is impressive, but it was a CTF-style challenge with clear flags. Real-world penetration testing involves noisy environments, evasive targets, and legal constraints. Cairn may be the wrong tool for continuous security monitoring, where you need scheduled scans and fixed reports. It is also not suited for teams that need explainability, since the reasoning is distributed across multiple LLM calls and the blackboard state may not be easy to audit.

Comparing Cairn to Role-Based Agent Frameworks

The most direct alternative to Cairn is a role-based AI agent framework, such as AutoGPT or MetaGPT, where you define agents with specific responsibilities like scanner, analyzer, and reporter. The difference in approach is fundamental. Role-based frameworks assign a persona and a set of tools to each agent, and they often use a planner to decompose a task into subtasks. Cairn does none of that. It uses a single type of worker that reads the graph and decides what to do next. There is no central planner. The graph itself acts as the plan, with intents representing possible next steps. This means Cairn is more flexible for novel problems, because it does not require you to anticipate all possible actions. However, it also means that the system can explore in many directions at once, which may be wasteful. Role-based frameworks give you more control over what each agent does, which is useful when you know the domain well. For example, in a standard pentest, you might want a dedicated port scanner agent that runs nmap, and a separate agent that analyzes the results. Cairn would treat port scanning as just another intent, and the worker might or might not choose to run nmap. That is a trade-off: generality versus predictability. If your problem is well understood, a role-based framework may be more efficient. If the problem is open-ended, Cairn's approach has merit.

Maintenance, Upgrade Cost, and License Implications

Cairn is licensed under AGPL-3.0, which is a strong copyleft license. If you modify the code and offer it as a network service, you must release your modifications under the same license. That is a critical consideration for a security tool that might be integrated into a commercial SaaS offering. The README does not mention any commercial licensing, so you should assume AGPL applies to any derivative work. On maintenance, the project has seen recent releases, with v0.2.1 from May 2026 and a last push in September 2026. That suggests active development, but it is a young project. The version numbers are low, and the README describes a competition result from a system that had never been tested before the event. There is no documentation of long-term stability or upgrade paths. The dependency on Docker images and specific Python versions means that upgrades may require rebuilding containers. The dispatcher configuration is in YAML, which is easy to version control, but the project does not list a schema or migration guide. If you adopt Cairn, you should expect to invest time in understanding the internals, because the README is more of a vision statement than a user manual. The lack of a homepage or detailed API documentation is a red flag for enterprise adoption. You will likely need to read the source code to customize behavior.

Editorial conclusion

Cairn suits security researchers and red teams who want a role-free, coordination-light AI agent for structured problems like CTF or pentesting, especially those who can accept its AGPL-3.0 license and who have the LLM API budget for iterative exploration. It is not for teams needing a turnkey pentesting tool with predefined workflows, nor for those who require a permissive open-source license or who cannot run Docker or manage container images. Before adopting, verify that your target environment matches the supported worker backends (Claude Code, Codex, Pi), that your LLM endpoints support the required API shapes, and that you can reproduce the competition results on your own network range, since the README reports performance only from a single event and does not document failure modes or long-running stability.

Official sources

1. Issues
2. License: AGPL-3.0
3. oritera/Cairn on GitHub
4. README
5. Releases