Agentic Security Orchestrator

An AI‑driven, containerized, multi‑agent cyber‑security framework built using LangGraph, Ollama, and a modular supervisor/worker/executor architecture.

This project provides a controlled environment where AI agents autonomously perform:

• Reconnaissance
• Scanning
• Service fingerprinting
• CVE association
• (Active development) Exploitation workflows
• Final Report Generation

All operations occur inside a fully isolated Docker network using a hardened Kali engine.

---

🚀 Overview

The system uses LangGraph subgraphs to coordinate separate reasoning loops for:

• Reconnaissance — network scanning, host discovery, port mapping, service versioning.
• CVE lookups — CVE lookups in NVD v2.0.
• Vulnerability mapping — CVE to exploit mapping via ExploitDB.
• (WIP) Exploitation — safe, controlled follow-up actions based on recon findings.
• Report — Final report summarizing the whole execution and the results found.

A central Supervisor Agent coordinates the workflow:

User → Supervisor → Recon Subgraph → Supervisor → CVE Subgraph → Supervisor → Vuln Map Subgraph → Supervisor → Exploit Subgraph → Supervisor → Report → Supervisor → User

Graphic representation

graph TD
    classDef ai fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
    classDef container fill:#e1f5fe,stroke:#0277bd,stroke-width:2px,color:#000;
    classDef external fill:#fff3e0,stroke:#e65100,stroke-width:2px,stroke-dasharray: 5 5,color:#000;
    classDef state fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000;

    User(["👤 User Input"]) <--> Supervisor

    subgraph "🛡️ LangGraph Orchestrator"
        Supervisor[("🧠 Supervisor")]:::state
        
        subgraph "Reconnaissance Subgraph"
            ReconPlanner["Recon Planner"]
            ReconExec["Recon Executor"]
        end

        subgraph "CVE Subgraph"
            CvePlanner["CVE Planner"]
            CveExec["CV Executor"]
        end

        subgraph "Vuln Mapping Subgraph"
            VulnMapPlanner["Vuln Map Planner"]
            VulnMapExec["Vuln Map Executor"]
        end
        
        subgraph "Exploitation Subgraph"
            ExploitPlanner["Exploit Planner"]
            ExploitExec["Exploit Executor"]
        end

        Supervisor --"Next step: Recon"--> ReconPlanner
        Supervisor --"Next step: CVE"--> CvePlanner
        Supervisor --"Next step: VulnMap"--> VulnMapPlanner
        Supervisor --"Next step: Exploit"--> ExploitPlanner
        
        ReconPlanner --"Recon findings"--> Supervisor
        CvePlanner --"CVE findings"--> Supervisor
        VulnMapPlanner --"Exploit findings"--> Supervisor
        ExploitPlanner --"Exploit results"--> Supervisor
        
        ReconPlanner --"Plan action"--> ReconExec
        CvePlanner --"Plan action"--> CveExec
        VulnMapPlanner --"Plan action"--> VulnMapExec
        ExploitPlanner --"Plan action"--> ExploitExec
        
        ReconExec --"Results & State Update"--> ReconPlanner
        CveExec --"Results & State Update"--> CvePlanner
        VulnMapExec --"Results & State Update"--> VulnMapPlanner
        ExploitExec --"Results & State Update"--> ExploitPlanner

        ReportNode["Report"]
        ReportLogs[("📂 Report logs")]
        Supervisor <--"Final state"--> ReportNode
        ReportNode --> ReportLogs
    end

    subgraph "🤖 Local AI Inference Engine"
        Ollama[("🦙 Ollama Server")]:::ai
    end

    Supervisor <.-> Ollama
    ReconPlanner <.-> Ollama
    CvePlanner <.-> Ollama
    VulnMapPlanner <.-> Ollama
    ExploitPlanner <.-> Ollama

    subgraph "🐉 Kali Linux Tools Container"
        KaliAPI["FastAPI Engine"]:::container
        Nmap[("Nmap")]
        NVDSearch["NVD Search Script"]
        ExploitSearch["Searchsploit"]
        Logs[("📂 Persistent Logs")]
        ExploitDB(("EploitDB"))
    end

    ReconExec <--"POST /recon"--> KaliAPI
    CveExec <--"POST /cve_lookup"--> KaliAPI
    VulnMapExec <--"POST /search_exploit"--> KaliAPI
    ExploitExec <--"POST /mock_exploit (planned)"--> KaliAPI

    KaliAPI <--> Nmap
    KaliAPI <--> NVDSearch
    KaliAPI <--> ExploitSearch
    KaliAPI --> Logs

    Target["🎯 Target Network (10.255.255.0/24)"]:::external
    NVD_API(("☁️ NIST NVD API")):::external

    Nmap <--"SYN/Version Scan"--> Target
    NVDSearch <--"HTTPS Query (CVSS)"--> NVD_API
    ExploitSearch <--"Query"--> ExploitDB

Loading

---

🧱 Architecture

1. Orchestrator (main agent environment)

Runs:

• LangGraph supervisor
• Worker planner(s)
• Message/step routing
• Nmap summary parsing
• Structured LLM calls to perform recon/exploit decisions
• Subgraphs for autonomous internal reasoning and executions
• Final report generation with findings

2. Kali Engine (Recon + Exploit tools)

A hardened container that:

• Executes Nmap, DNS, banner-grabs, CVE lookups, exploit searches
• Applies dynamic egress firewalling to ensure:
  • Only target hosts are reachable
  • Gateway and self are blocked
• Receives tool execution requests via REST (/run) (Soon)

3. Vulnerable Targets

Isolated inside attack_net:

• Reached only by Kali
• Never visible to orchestrator
• Discoverable by recon subgraph

4. LangGraph Subgraphs

• Recon Subgraph

  • Planner → Executor loop
  • Step-by-step scanning
  • Tool selection enforced by structured schema
  • Handles full cycle:
    • CIDR → host discovery → port map → version scans → summary

• CVE Subgraph

  • Planner → Executor loop
  • Step-by-step searches
  • CVE lookup based on Recon findings (services and versions of each target)

• Vuln Map Subgraph

  • Planner → Executor loop
  • Step-by-step searches
  • Vulnerability to Exploit mapping based on Recon findings and found CVEs (services and versions of each target)

• Exploit Subgraph (actively working)

  • Planner → Executor loop
  • Planner selects exploit vectors
  • Executor performs exploits selecting available tools
  • Produces structured findings

---

🔍 Recon Capabilities

• Full network scan
• Automatic exclusion of gateway & self
• Structured parsing of Nmap XML into JSON
• Planner-driven version scanning
• Full reasoning loop until no pending hosts
• Clean recon summary output to user

---

🛡️ Security Model

• Two-network separation:

  • mgmt_net → orchestrator ↔ kali
  • attack_net → kali ↔ targets

• Internal-only attack net:
  Orchestrator cannot reach targets directly.

• Nmap exclusion system:
  Recon engine auto-excludes:

  • Gateway
  • Kali’s IP
    Prevents scan noise & delays.

---

🔧 Development Roadmap

✔ Completed

• Recon subgraph with planner/executor loop
• LangGraph integration
• Supervisor loop implementation
• Host mapping and version scanning
• Final Summary Node to generate report of findings
• Exploit search by Exploit Subgraph
• Graph refactoring to modularize nodes
• Knowledge persistence integration
• Human-in-the-Loop integration
• Automatic mitigation suggestions

🚧 In Progress

• "Would exploit" planning
• Exploit usage
• More thorough testing on various targets

🔜 Future plans

• Dedicated GUI
• Multi-vector exploit reasoning
• Safe-mode vs aggressive-mode flags
• Interactive chain-of-thought debugging
• Attack graph generation

---

🛠 Prerequisites

Before running the orchestrator, ensure your environment meets the following requirements:

🖥 Operating System

• Linux: Recommended for native Docker performance.
• Windows: Must have WSL2 (Windows Subsystem for Linux) installed and configured as the default Docker backend.

🐳 Containerization

• Docker Desktop (Windows/Mac) or Docker Engine (Linux).
• Docker Compose v2.0+: Essential for managing the multi-container architecture (Orchestrator, Kali Engine, and Database).

🧠 Local AI (LLM)

The system uses Ollama to run models locally, ensuring data privacy and zero API costs.

1. Install Ollama: Follow instructions at ollama.com.
2. Pull Required Models: Run the following command in your terminal:

ollama pull qwen2.5:7b  # Or the specific model configured in your .env

🧰 Optional Tooling

For convenience, a Makefile is provided to simplify deployment and lifecycle management.

3. Service Status: Ensure Ollama is running on the host. The orchestrator connects via http://host.docker.internal:11434.

📂 File System & Permissions

The orchestrator requires write permissions to persist intelligence data:

• Reports Directory: /data/reports/ for automated security assessments.
• Logging Directory: /data/logs/ for automated security assessments.
• Note: If running on Linux, ensure the user has UID 1000 permissions or use chmod to allow container writes.

🌐 Network Configuration

• The system creates a dedicated internal bridge network (10.255.255.0/24). Ensure no local firewall rules (like iptables or Windows Firewall) block traffic between Docker containers and the host's Ollama port (11434).

---

▶️ Deployment Modes

The project supports multiple execution modes depending on your needs, from lightweight operation to full observability.

🔹 Core Engine Only

Command:

make core

Starts the minimal system required to operate the orchestrator:

• Orchestrator API
• Kali execution engine

No vulnerable targets and no monitoring stack are deployed.

✅ Lowest resource usage
✅ Recommended for development and lightweight environments
✅ Suitable for machines with limited RAM / VRAM

---

🔹 Core + Vulnerable Targets

Command:

make lab

Starts the core system plus intentionally vulnerable targets for attack simulation.

Includes:

• Core services (orchestrator, kali-engine)
• Vulnerable containers (e.g. Metasploitable2) attached to the internal attack network

✅ Enables end-to-end attack simulation
✅ Useful for testing recon, exploitation and reporting phases
✅ Still lightweight — no monitoring infrastructure

---

🔹 Core + Targets + Monitoring

Command:

make full

Starts the complete stack, including observability and monitoring.

Includes:

• Core services
• Vulnerable targets
• Langfuse monitoring stack (web, worker, database, queue, storage)

✅ Full execution visibility and trace analysis
✅ Recommended for debugging, benchmarking and prompt tuning
⚠️ Higher resource consumption (RAM and storage)

Monitoring components are optional and not required for normal operation.

---

⛔ Stopping and Cleanup

make down

Stops all running containers.

make clean

Stops and removes containers, networks and orphaned services.
Recommended when changing execution modes or network topology.

Controlling the execution

Send an HTTP POST request to http://localhost:8000/chat. Example using the client provided:

python .\client.py "Please scan the network 10.255.255.0/24 for vulnerabilities" -f

Or you can use the Swagger UI deployed in http://localhost:8000/docs, where there are more options to try.

The system currently stops before each subgraph. You can ask questions to the model to analyze the current state, or you can continue the execution by sending "approve" to the model:

python .\client.py "approve"

---

📄 License

MIT License.