AntiGravity / CyberBot Orchestration Framework

1. Executive Summary

CyberBot (AntiGravity) is an advanced, LLM-powered agentic orchestration framework designed to automate complex cybersecurity engagements, reconnaissance, and forensic analysis. Using a highly modular blackboard architecture, it dynamically schedules tasks, parses output from standard security tools, and conducts intelligent, multi-step exploits or security audits.

Primary Use Case: Automating the workflows of penetration testing, CTF (Capture The Flag) challenges, and forensic investigations. It seamlessly handles everything from initial network reconnaissance to final reporting, utilizing Large Language Models (LLMs) to make intelligent routing and parsing decisions on the fly.

Problem Solved: Security testing and forensic analysis typically require significant manual effort transitioning between tools (e.g., Nmap, LinPEAS), parsing their outputs, and deciding the next logical step. CyberBot bridges this gap by providing an intelligent orchestration layer that aggregates facts, analyzes evidence ("loot"), dynamically verifies goals, and generates comprehensive engagement reports without human intervention.

---

2. System Architecture

The project utilizes a state-driven, multi-agent architecture built heavily around the Blackboard Design Pattern. This allows various specialized modules to post intermediate findings and read global state asynchronously.

High-Level Design

1. The Brain (Orchestrator): The central nervous system (agent.py, router.py, scheduler.py) evaluates the current system state and determines which operator should act next.
2. Knowledge State (Blackboard): A centralized repository (blackboard.py, fact_manager.py) storing current facts, discovered credentials, open ports, and context.
3. Execution Layer (Operators): Specialized execution modules (recon_operator.py, forensic_operator.py) that perform direct interactions with the target environment.
4. Data Ingestion (Parsers & Loot): Extractors (linpeas.py, web.py, loot_analyzer.py) that convert raw command outputs and packet captures into structured intelligence (loot_manager.py).

Core Infrastructure Modules

• Orchestrator: Defines the agent loop and task delegation.
• Blackboard / Fact Manager: Maintains the "source of truth" throughout the engagement to prevent redundant operations and maintain context.
• Operators: Pluggable modules that encapsulate domain-specific knowledge (e.g., how to conduct a web scan vs. how to analyze forensic traces).
• Goal Verifier: Continuously checks if the high-level objectives (e.g., "Retrieve the root flag") have been met to gracefully terminate the operation.

---

3. Tech Stack & Dependencies

The system is built on modern Python and embraces containerization for isolated microservices and testing.

Languages:

• Python 3.10+

LLM / AI Functionality:

• openai, groq, google-genai (Multi-provider LLM support)
• instructor (Structured LLM outputs)

Data Validation & Structuring:

• pydantic (Robust typing and data validation)

Web & Networking:

• flask (API/microservice endpoints)
• requests (HTTP interactions)
• OpenVPN (Secure network tunneling infrastructure)

Infrastructure / Execution:

• Docker & docker-compose (Containerized service environments and execution sandboxes)

---

4. Directory Structure

.
├── machines_sg-1.ovpn          # VPN configuration for accessing target networks
├── requirements.txt            # Main Python dependencies
├── run_graduation.py           # Execution script for final full-system test run
├── mvt/                        # Microservice/Validation Tool environment
│   ├── app.py                  # Flask service
│   ├── Dockerfile              # Docker container definition
│   ├── docker-compose.yml      # Container orchestration
│   └── recon.txt               # Sample/seed recon data
├── orchestrator/               # Core Agent Logic
│   ├── agent.py                # Main agent loop and state tracking
│   ├── blackboard.py           # Shared data and state manager
│   ├── fact_manager.py         # Extracted facts and assertions repository
│   ├── operators.py            # Base definitions for execution units
│   ├── recon_operator.py       # Reconnaissance-specific agent tasks
│   ├── forensic_operator.py    # Forensic investigation tasks
│   ├── router.py               # Routes tasks to appropriate operators/LLMs
│   ├── scheduler.py            # Task queuing and prioritization
│   ├── parsers/                # Log and output parsers
│   │   ├── linpeas.py          # Parser for LinPEAS output
│   │   └── web.py              # Parser for web enumeration tools
│   ├── loot_manager.py         # File and packet capture management
│   ├── goal_verifier.py        # Termination condition logic
│   ├── reporter.py             # Generates final markdown reports
│   └── profiles.json           # Agent persona/configuration profiles
├── reports/                    # Aggregated execution traces (Markdown logs)
├── scans/                      # Target-specific output directories
│   ├── 10.129.242.203/         # Example Target
│   │   ├── ENGAGEMENT_REPORT.md# Final generated engagement summary
│   │   ├── facts.json          # Target-specific distilled facts
│   │   └── loot/               # Discovered files, pcaps, etc.
└── tests/                      # Unit and integration test suite
    ├── run_certification.py    # Test runner for specific validation
    └── verify_*.py             # Verifiers for blackboards, sessions, SDKs

---

5. Setup & Installation

Prerequisites

• Python 3.10 or higher
• Docker & Docker Compose
• OpenVPN (if connecting to external CTF/testing environments)

Step 1: Clone the Repository

git clone https://github.com/mrvenom17/CyberBot.git
cd CyberBot

Step 2: Network Configuration

If testing against isolated environments (like HackTheBox), initialize the VPN connection.

sudo openvpn --config machines_sg-1.ovpn

Step 3: Environment Setup

Create a virtual environment and install the required dependencies.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r orchestrator/requirements.txt

Step 4: API Keys & Environment Variables

Create a .env file in the root directory to store your LLM provider keys.

OPENAI_API_KEY="sk-..."
GROQ_API_KEY="gsk_..."
GEMINI_API_KEY="AIzaSy..."

---

6. Core Data Flow / Logic

1. Initialization (session_manager.py & agent.py) A new engagement session is instantiated. The target IP/hostname and primary goals are loaded into the blackboard.py.

2. Task Scheduling (scheduler.py) The scheduler determines the first logical action (typically an initial Nmap/Recon pass) and queues the task.

3. Routing & Execution (router.py & *_operator.py) The router passes the task to the appropriate operator (e.g., recon_operator.py). The operator securely executes the required tools against the target.

4. Data Ingestion & Parsing (parsers/ & loot_analyzer.py) Raw outputs (stdout, pcaps, files) are passed to the parsers. For example, linpeas.py will extract CVE vulnerabilities and misconfigurations from a raw LinPEAS dump.

5. State Update (fact_manager.py) Parsed insights are translated into structured facts via pydantic models and stored in the blackboard.

6. Verification & Loop (goal_verifier.py) The goal_verifier.py checks the blackboard to see if the main objectives (e.g., root access confirmed, flag captured) have been fulfilled. If not, the loop returns to Step 2 with the newly gained context.

7. Reporting (reporter.py) Upon completion, the reporter ingests the entire execution trace and blackboard state to generate a human-readable ENGAGEMENT_REPORT.md.

---

7. Testing & Deployment

Running the Test Suite

The continuous integration and integration tests are located in the tests/ directory. You can run individual verifications directly:

python tests/verify_blackboard.py
python tests/verify_sessions.py
python tests/run_certification.py

Executing a Local Microservice

To bring up the standalone validation tool / web microservice located in the mvt/ folder:

cd mvt
docker-compose up --build -d

This will build the Flask application using the provided Dockerfile and expose it locally based on the compose configuration.

Running the Main Orchestrator

To kick off a full orchestration run or a "graduation" evaluation spanning multiple simulated layers:

python run_graduation.py

Traces for the agent logic will automatically be logged in the reports/ directory with a timestamp.