> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

Decepticon: How Persistent Tmux Sessions Solve the Interactive Shell Problem for Autonomous Hacking Agents

[ View on GitHub ]

Decepticon: How Persistent Tmux Sessions Solve the Interactive Shell Problem for Autonomous Hacking Agents

Hook

Most AI pentesting tools fail the moment they hit an interactive shell. Decepticon solves this with tmux sessions and regex-based prompt detection—no wrapper scripts, no shell escape hacks, just real tool execution.

Context

Autonomous penetration testing has a dirty secret: nearly every LLM-powered security tool breaks when it encounters interactive prompts. Tools like msfconsole, sqlmap, and evil-winrm don't just execute and exit—they drop you into stateful shells where follow-up commands depend on previous context. Simple subprocess wrappers can't handle this. You end up writing brittle shell escape sequences, maintaining dozens of tool-specific adapters, or just avoiding interactive tools entirely and settling for nmap-and-report theater.

Decepticon approaches this differently. Built by BitterSecurity as an autonomous red team agent, it treats shell persistence as a first-class architectural concern. Instead of fighting against interactive tools, it executes everything inside persistent tmux sessions with automatic prompt detection. This architectural choice—combined with a two-network container design that separates orchestration from execution—enables actual kill-chain automation. The orchestrator can spawn msfconsole, execute a search command, wait for the msf prompt, fire an exploit, catch the callback, and pivot through post-exploitation modules without losing session state. The difference between this and typical LLM pentesting wrappers is the difference between driving a car and pushing one.

Technical Insight

Sandbox Plane (sandbox-net)

Management Plane (decepticon-net)

Model request

Provider fallback

HIGH/MID/LOW tiers

Persist objectives

ops_start command

Execute in named session

Command output

Prompt detection

Execution results

Attack chain findings

Sync graph data

Query attack paths

LangGraph Orchestrator

LiteLLM Router

PostgreSQL State

Neo4j Knowledge Graph

Tmux Session Manager

Kali Container

BloodHound/Sliver/Metasploit

Neo4j Dual-Homed

System architecture — auto-generated

The core innovation lives in the sandbox execution layer. Decepticon runs a persistent Kali Linux container on the sandbox-net network with a tmux server that never dies. When an agent needs to execute a command, it doesn't spawn a subprocess—it sends the command to a named tmux session and watches for prompt patterns that signal completion.

Here's how the execution flow works in practice:

# Simplified from Decepticon's tool execution layer
class TmuxExecutor:
    def __init__(self, session_name="decepticon-main"):
        self.session = session_name
        self.prompt_patterns = [
            r'msf6 >',  # Metasploit
            r'\[\*\] Meterpreter session',  # Meterpreter callbacks
            r'Evil-WinRM shell',  # Evil-WinRM
            r'kali@.*:\~\$',  # Default bash
        ]
    
    def execute(self, command, timeout=30):
        # Send command to tmux pane
        subprocess.run([
            'tmux', 'send-keys',
            '-t', f'{self.session}:0',
            command, 'C-m'
        ])
        
        # Capture output until prompt detected
        start = time.time()
        while time.time() - start < timeout:
            output = subprocess.check_output([
                'tmux', 'capture-pane',
                '-t', f'{self.session}:0',
                '-p'
            ]).decode()
            
            for pattern in self.prompt_patterns:
                if re.search(pattern, output.split('\n')[-1]):
                    return self._clean_output(output)
            time.sleep(0.5)
        
        raise TimeoutError(f"No prompt detected within {timeout}s")

This approach unlocks something most AI security tools can't do: multi-stage interactive workflows. An agent can execute msfconsole, wait for the msf6 > prompt, then run search type:exploit platform:windows, parse the results, select an exploit, configure LHOST/RHOST, execute, and handle the callback—all without losing context or spawning new processes.

The orchestration layer uses LangGraph to coordinate 16 specialist agents across the kill chain: reconnaissance, vulnerability assessment, exploitation, post-exploitation, lateral movement, credential harvesting, persistence, exfiltration, and cleanup. Each agent gets a fresh context window per objective, preventing the context pollution that plagues single-agent architectures. The reconnaissance agent doesn't carry exploitation noise, and the post-exploitation agent starts clean rather than inheriting hallucinated findings.

The network architecture enforces hard isolation. The management plane (decepticon-net) runs LiteLLM for model routing, PostgreSQL for state, Neo4j for attack graphs, and the LangGraph orchestrator. The sandbox plane (sandbox-net) executes untrusted commands and runs specialist workloads like BloodHound CE, Sliver C2, and the REA/Ghidra reverse engineering container. These workloads don't run continuously—they spawn on-demand via ops_start() calls when the orchestrator needs them, then tear down when idle.

Neo4j is the bridge. It's dual-homed across both networks, allowing agents on the management plane to persist attack-chain findings written from inside the sandbox. When an exploitation agent compromises a host and dumps credentials, that data flows into the knowledge graph. The lateral movement agent queries that same graph to identify pivot opportunities, without ever touching the compromised execution context directly.

The model routing layer handles provider diversity through a tier-based fallback chain. You configure credentials for Anthropic, OpenAI, Gemini, DeepSeek, xAI, or local Ollama models during onboarding, then map agents to HIGH/MID/LOW priority tiers:

# Model routing configuration (simplified)
model_profiles:
  max:
    HIGH: anthropic/claude-opus-3.5
    MID: openai/gpt-4
    LOW: deepseek/deepseek-chat
  eco:
    HIGH: openai/gpt-4o-mini
    MID: google/gemini-1.5-flash
    LOW: ollama/llama3.1:8b

agent_priorities:
  exploiter: HIGH
  post_exploitation: HIGH
  reconnaissance: MID
  cleanup: LOW

If Claude Opus hits rate limits during exploitation, the orchestrator falls back to GPT-4 without manual intervention. If you're running on a budget, the eco profile drops everything to cheaper models or local Ollama instances. The orchestrator handles failures transparently—agents don't know or care which model answered their request.

The REA (Reverse Engineering Agent) integration deserves special mention. When exploitation requires understanding a custom binary or unfamiliar protocol, the orchestrator spawns a dedicated Ghidra container, decompiles the target, and generates a structured analysis report. This evidence-backed approach prevents hallucination during exploitation—the agent works from actual decompiled code rather than guessing at binary behavior.

Gotcha

The tmux prompt detection is clever but fragile. It works beautifully for known tools with predictable prompts—msfconsole, sqlmap, nmap—but falls apart when tools output unexpected patterns. Multi-factor authentication flows, tools with dynamic ASCII art banners, or applications that redraw the terminal can deadlock the executor. The regex patterns are hardcoded, so adding support for a new interactive tool means modifying the executor code and rebuilding containers.

The sandbox isolation isn't as strong as it appears. Decepticon exposes the Docker socket to containers for dynamic workload spawning, which means a container escape from the Kali sandbox could pivot to the Docker daemon and compromise the host. The dual-homed Neo4j becomes a lateral movement vector if an attacker compromises the sandbox network—they could write malicious data to the graph that poisons orchestrator decisions. The architecture assumes trusted binaries and authorized engagements. If you're analyzing malware samples or testing untrusted code, the sandbox won't contain a determined adversary.

The SDK/infrastructure split creates deployment friction. Running pip install decepticon gives you the Python SDK with agent definitions and tool wrappers, but you still need Docker Compose to run LiteLLM, PostgreSQL, Neo4j, and the Kali sandbox. The demo videos show a polished web console with attack-chain visualizations and real-time agent logs—that's Decepticon Cloud, the commercial SaaS offering. The OSS version only includes a terminal CLI. You're deploying a distributed system with six containers, multiple networks, and persistent volumes, not a self-contained pentesting tool.

Verdict

Use if: You're running authorized red team engagements that require realistic kill-chain automation beyond simple vulnerability scanning. You have mature container infrastructure and understand the security implications of Docker socket exposure. You value execution realism—actually driving msfconsole and evil-winrm through multi-stage workflows—over ease of deployment. You need attack-chain knowledge graphs and per-phase agent isolation to prevent context pollution across long campaigns. Skip if: You're building a product on top of the SDK rather than using it for engagements—the client library requires the full Docker stack and won't embed cleanly. You need a polished web interface without paying for commercial software. You're analyzing untrusted malware samples where the sandbox isolation isn't strong enough. You want simple point-and-shoot pentesting without container orchestration overhead. For those cases, stick with manual Metasploit workflows or simple subprocess wrappers like PentestGPT.