1. The Core Bottleneck: What Engineering Flaws Does It Smash?

Most open-source AI pentesting tools remain shallow shells. Developers feed a target IP into an LLM, the system calls nmap for port scanning, and it spits out a PDF filled with standard vulnerability ratings and generic remediation advice. This pipeline-style operation fails to simulate the complete tactical maneuvers of real threat actors. Actual penetration testing requires maintaining stateful sessions, handling multi-stage interactive prompts, and dynamically adjusting attack paths across complex internal network topologies.

Decepticon completely discards this toy-like script scanning paradigm. It defines itself as an autonomous red team agent, introducing operational constraints as rigorous as real-world red team engineering. Before a single packet leaves the wire, the system automatically generates a complete engagement package, including Rules of Engagement (RoE), Concept of Operations (ConOps), Deconfliction Plans, and engagement plans (OPPLAN) mapped directly to the MITRE ATT&CK framework.

💡 Core Architectural Insight: Decepticon replaces the free-form LLM loop with a heavily constrained operational planner, forcefully converging the divergent thinking of AI into compliant and lethal attack chain topologies.

2. Core Architecture and Underlying Data Flow

Decepticon's core architecture revolves around multi-service collaboration and stateful state machines. The entire runtime stack consists of a LiteLLM proxy, PostgreSQL state backend, Neo4j knowledge graph, LangGraph workflow engine, and isolated sandboxes. When a user triggers a target task via CLI, the request first enters the gateway parser, builds the attack surface topology inside the knowledge graph, and finally hands off to the dynamic execution engine.

[ Client / CLI ] ---> [ Gateway / Parser ] ---> [ Memory Layer (Neo4j/Postgres) ]
                                 │
                                 ▼
                     [ Dynamic Execution Engine ]
                                 │
                                 ▼
                    [ Isolated Sandbox / Tmux ]

At the execution layer, this architecture solves the pain point where traditional AI tools fail to handle interactive shells. Real offensive tools like msfconsole and sliver-client rely heavily on interactive prompts. Decepticon runs every command inside persistent tmux sessions with automatic prompt detection, allowing the agent to precisely capture and automatically send follow-up commands when a tool drops into an interactive prompt.

3. Technology Selection and Hardcore Benchmarking

Selection Dimension This Solution (Decepticon) Traditional Paradigm Typical Competitor Production Benefit
Execution Runtime Persistent tmux + auto prompt detection Stateless single-API calls Ephemeral containers or raw subprocesse Full support for interactive tools like msfconsole
Attack Planning OPPLAN constraints + MITRE ATT&CK Hardcoded static scripts Unconstrained LLM hallucinations Reduced operational risk, realistic attacks
Knowledge Graph Neo4j attack path correlation Flat file storage No structured graph support Doubles internal lateral movement path discovery
Environment Setup Docker Compose stack / SDK embedding Complex manual local setup Cloud SaaS dependency only Smooth migration across dev/test/prod
Benchmark Results XBOW 102/104 (98.08% pass rate) Lacks standardized validation High false-positive and hallucination rate Industrial-grade pentesting reliability

Decepticon abandons lightweight but fragile stateless scripts in favor of a heavyweight control plane centered around graph databases and process management. This trade-off yields exceptional environmental stability, enabling resumable execution and state rollback for complex exploitation chains.

4. Minimal Production Closed-Loop: Hands-On Guide

On macOS, Linux, or WSL2 environments, initialize the core management stack using the official installation script.

# Download and execute the official installation script
curl -fsSL https://decepticon.red/install | bash

# Launch the interactive setup wizard for providers, API keys, and model profiles
decepticon onboard

# Start the core management stack and enter the terminal CLI
decepticon

To integrate the agent into coding assistants like Claude Code or Codex, register the server via the MCP protocol:

# Register Decepticon as an MCP server for Claude Code
claude mcp add --scope user decepticon -- decepticon mcp serve

# Install the operator guide to external agents
decepticon skill install

Developers can also install the SDK via PyPI to embed agent logic into custom workflows:

from decepticon.sdk import AgentFactory, PluginBundle

# Initialize the core agent and load Neo4j attack chain plugins
agent = AgentFactory.create(
    model="gpt-4o",
    plugins=[PluginBundle.neo4j_attack_chain()]
)

# Run automated reconnaissance and engagement
result = agent.run_engagement(target="192.168.1.100", scope="strict")
print(f"Engagement completed with status: {result.status}")

5. Production Gotchas and Avoidance Strategies

When deploying Decepticon in production or high-intensity red team engagements, resource consumption and cold-start latency require careful engineering tuning.

⚠️ Gotcha Warning [Service Cold-Start Latency]: Because the stack simultaneously boots LiteLLM, Neo4j, Postgres, and specialist workloads, container health checks can cause a delay of several seconds upon the first execution of decepticon. Never dispatch tasks before containers are fully healthy; verify service responsiveness via docker compose logs before entering the CLI.

⚠️ Gotcha Warning [Token Consumption Spikes]: During long-running penetration tasks, frequent LangGraph context replays and knowledge graph interactions generate massive token throughput. Configure strict model quota limits during decepticon onboard and enable response caching at the gateway layer to prevent hitting rate limits during infinite loops.