Security analysis is fundamentally a directed search through a large state space:

• Origin: known (repository, commit, source package, system description)
• Goal: defined (find and evidence high-impact vulnerabilities, produce an audit conclusion)
• Path: unknown

This structure is not unique to penetration testing. Code audit, vulnerability research, mathematical proof, CTF challenges, and many other problems with a clear starting point, success condition, and unknown path share the same shape.

Orant is built for this class of problems. The current worker image is oriented toward authorized code audit and vulnerability analysis: source checkout, initial threat modeling, static analysis, dependency and secret checks, and evidence-oriented reporting.

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

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.

Three task types, all executed by the same Worker:

System architecture:

          ┌──────────────────────────────────┐
          │           Orant Server           │
          │    Facts + Intents + Hints       │
          └─────────────────┬────────────────┘
                            │
                     Read / Write API
                            │
          ┌─────────────────┴────────────────┐
          │             Dispatcher           │
          │   Schedules tasks, manages       │
          │   containers, writes protocol    │
          └──────────┬───────────────┬───────┘
                     │               │
     ┌───────────────┴──┐     ┌──────┴──────────────┐
     │  Worker Container│     │  Worker Container   │
     │   (Project A)    │     │   (Project B)       │
     │  ┌────┐  ┌────┐  │     │  ┌────┐  ┌────┐     │
     │  │ W. │  │ W. │  │     │  │ W. │  │ W. │     │
     │  └────┘  └────┘  │     │  └────┘  └────┘     │
     └──────────────────┘     └─────────────────────┘

Orant Server maintains graph consistency only.

Orant 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.

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

The worker image in container/ is a lightweight Python/Debian-based code-audit environment. It includes common source navigation and audit tools such as rg, fd, jq, yq, semgrep, bandit, pip-audit, detect-secrets, gitleaks, shellcheck, and the Claude Code / Codex / Pi agent CLIs.

It also preinstalls the threat-modeling skill from https://github.com/fr33d3m0n/threat-modeling into both local skill paths:

/home/kali/workspace/.agents/skills/threat-modeling
/home/kali/workspace/.claude/skills/threat-modeling

The worker is intended for authorized static analysis and local, minimal validation only. Complex dynamic validation, especially for kernels, memory corruption, VM-specific targets, or multi-service environments, should be handled by an external validation system and written back to Orant as facts or hints. See docs/specs/external-dynamic-validation.md.

The upstream Orant architecture was first validated in an AI penetration testing competition. This repository keeps that background for context, while the worker image and setup instructions above are now tuned for code audit.

Prerequisites

• macOS or Linux
• Python ≥ 3.12
• Docker
• uv

Build the local code-audit worker image first:

docker build ./container -t orant-worker-container:latest

To pin the bundled threat-modeling skill to a tag or commit, pass a build argument:

docker build ./container \
  -t orant-worker-container:latest \
  --build-arg THREAT_MODELING_SKILL_REF=<tag-or-commit>

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

cp dispatch.example.yaml dispatch.yaml

The example config uses the local worker image:

container:
  image: "orant-worker-container:latest"

For a first code-audit run, keep concurrency conservative:

runtime:
  max_workers: 3
  max_running_projects: 2
  max_project_workers: 1

Pull the base image used to build Orant:

docker pull ghcr.io/astral-sh/uv:python3.13-trixie

Generate the local self-signed certificate and Basic Auth file before starting the stack:

./deploy/nginx/generate-self-signed-cert.sh
BASIC_AUTH_PASSWORD='change-me' ./deploy/nginx/generate-basic-auth.sh

docker compose up --build

This starts orant-nginx on HTTPS port 8888, orant-server on the internal Compose network, and orant-dispatcher once the server passes 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/orant/.

Open the UI at:

https://127.0.0.1:8888

# Start the server
uv run --project orant orant serve
 
# Run the dispatcher
uv run --project orant orant dispatch --config dispatch.yaml
 
# Run startup health checks only
uv run --project orant orant dispatch --config dispatch.yaml --startup-healthcheck-only

Use Origin to describe the source material:

Repository: https://github.com/example/project.git
Ref: main
Target path: /home/kali/workspace/target

Target path is the requested source placement location. If it is a generic placeholder such as /home/kali/workspace/target, workers should clone under the workspace using the repository project name, for example /home/kali/workspace/project, and record that actual source path.

Use Goal to make the bootstrap expectations explicit:

Perform an authorized code audit of this repository.
First clone the repository into the requested workspace using the repository project name, then
record the actual source path and commit.
Then perform initial threat modeling, including technology stack, entry points, trust boundaries,
high-risk modules, sensitive data flows, and priority audit directions.
After that, continue the first static audit pass based on the threat model.

The goal is met only when at least one critical or otherwise high-impact vulnerability is identified
and deeply validated through static analysis. A qualifying finding must be an engineering
implementation weakness, bug, or design defect in the target code, not a default configuration
issue or generic hardening gap. For each qualifying finding, provide the affected files/functions,
source-to-sink or control-flow path, attacker-controlled inputs, required preconditions,
exploitability reasoning, security impact, confidence level, and concrete code evidence. Include a
minimal non-destructive validation idea or external dynamic-validation plan when runtime proof
requires a separate environment.

Do not treat keyword matches or generic risky patterns as completed findings. If no qualifying
critical/high-impact issue is confirmed before the bootstrap task times out, summarize the source
path, commit, threat-modeling findings, audited areas, rejected hypotheses, partial findings, and
recommended next audit directions.

Hints can narrow the scope, for example:

Prioritize server-side authorization, SSRF, file upload, deserialization, command injection,
secret leakage, and dependency risks. Do not perform external scanning or destructive testing.

Bootstrap is expected to run longer for code audit because repository checkout, initial threat modeling, and the first audit pass happen in the same project container. The default dispatch.example.yaml therefore uses a longer bootstrap timeout.

Run the fast regression suite without Docker or live model endpoints:

uv run --project Orant --group dev pytest

Orant is a general-purpose problem-solving engine. Although it supports penetration testing, CTF solving, security assessment, and vulnerability research workflows, it is intended to be used only in environments where you have explicit authorization to operate.

You are solely responsible for how you use this project. Do not use Orant 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 developers 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 activities comply with all applicable laws, regulations, contractual obligations, and professional or organizational policies in your jurisdiction.