Decepticon runs an autonomous red team as a LangGraph state machine
Decepticon, an autonomous red-team agent built on LangChain and LangGraph, reached #13 on GitHub Trending for Python with 5,825 stars and 1,100 forks. Its write-up details how a state machine runs offensive tools end to end while leaving an audit trail.
The Engineer · Build desk
What happened
- The agent works in three phases: reconnaissance runs nmap and identifies services, exploitation matches those services to Metasploit modules and checks for shells, and post-exploitation escalates privileges and pivots to other hosts.
- Each tool runs in a sandboxed subprocess with a timeout, so a hung tool is killed and logged and a crashed one does not stall the rest of the graph.
- LangGraph persists the run's state in memory or a database, so an agent that crashes resumes from the last checkpoint instead of repeating reconnaissance.
- The agent cannot issue arbitrary shell commands. It is restricted to an allowlist of approved tools such as nmap and Metasploit, each carrying a schema of valid arguments.
- The agent moves to the next phase only when the current one succeeds, and a failure can backtrack, retry with new parameters, or hand off to a human operator.
Why it matters
- constraint Offensive tools can cause unintended lateral movement, data loss or compliance violations, per the author. An agent that runs them unattended is only as safe as the boundaries enforced in code.
- capability The shared state records which exploits were tried, which worked and the live session handles. The same structure that drives the agent's decisions also produces the audit trail compliance work needs.
- decision Tool output is treated as untrusted, and an unreachable Metasploit shell is marked failed. The next move rests on verified state, and one false success does not steer the rest of an unattended run.
- precedent The problems the write-up names, keeping context across tool calls, recovering from failures and maintaining an audit trail, are generic to any tool-running agent. The pattern transfers well beyond security.
LangGraph is a stateful orchestration layer on top of LangChain. It models a workflow as a directed graph: nodes are functions, edges are conditional transitions, and state flows through the graph, picking up context as the run proceeds [4]. Decepticon maps its phases straight onto that structure, with each node a phase and each edge firing on what the previous tool returned [3].
The choice worth examining is where the limits live. Decepticon checks each tool's argument schema at call time, so keeping the agent in scope does not depend on the model's instructions [10]. For nmap, the schema permits a predefined IP range and refuses anything wider, so the agent cannot aim a scan at the whole internet even if its reasoning heads that way [11]. We think that is the right place for the limit. Put it in a schema and the agent cannot exceed it whatever the model decides; put it in the prompt and staying in bounds depends on the model behaving.
Two caveats temper what the ranking invites. The GitHub stars measure attention. They say nothing about whether the agent works against a hardened target [2]. And the account is a design walkthrough; it does not print code or benchmark numbers, so what it describes is the intended behavior, not a measured one [16]. Set against the process it replaces, the gain is plain enough. In that process a human runs a tool, reads the output, picks the next step and keeps the whole state in their head [14]. In Decepticon the state lives in a structure the agent and a reviewer can both read.
What to watch
- Whether the maintainers publish logs or benchmarks showing the agent succeeding against a real or hardened target, which the current write-up does not provide.
- Whether the state schema and the checkpoint store are documented well enough for an outside reviewer to audit a run after the fact.
- Whether the allowlist-and-schema model holds its guarantees as more tools and more phases are added to the graph.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence30
- Adoption25
- Hype gap+30
- Incentives
- Insufficient
- Confidence30
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
Decepticon is an autonomous red-team agent built on LangChain and LangGraph that chains reconnaissance, exploitation and privilege-escalation tools without human intervention.
- [2]
Decepticon reached #13 on GitHub Trending for Python with 5,825 stars and 1,100 forks.
- [3]
Decepticon uses LangGraph to model its workflow as a state machine in which each node is a phase and each edge is a transition triggered by tool output.
- [4]
LangGraph is a stateful orchestration layer on top of LangChain that models workflows as directed graphs where nodes are functions, edges are conditional transitions, and state flows through the graph accumulating context.
- [5]
Decepticon's graph has three primary phases: reconnaissance (run nmap, parse open ports, identify services), exploitation (match services to exploits, run Metasploit modules, check for shells), and post-exploitation (escalate privileges, pivot to other hosts, exfiltrate data).
- [6]
The agent transitions to the next phase only if the current phase succeeds; if a tool fails, the graph can backtrack, retry with different parameters, or escalate to a human operator.
- [7]
The LangGraph state object carries target metadata, tool results, exploit history (which exploits were attempted and which succeeded), and session handles such as active shells, credentials and pivot points.
- [8]
LangGraph persists the state in memory or a database, so if the agent crashes it can resume from the last checkpoint without re-running reconnaissance.
- [9]
Each tool runs in a sandboxed subprocess with input via stdin, output via stdout and a timeout; if a tool hangs the agent kills it and logs the failure, and if a tool crashes the agent logs the error and moves to the next phase.
- [10]
The agent does not execute arbitrary shell commands; it is limited to an allowlist of approved tools such as nmap, Metasploit and custom scripts, each with a schema that defines valid arguments.
- [11]
nmap's schema allows only a predefined IP range, so the agent cannot run nmap -A 0.0.0.0/0 against the whole internet; the schema enforces the constraint at runtime.
- [12]
The agent treats tool output as untrusted and parses it with a strict schema; malformed nmap XML is logged and retried, and a Metasploit module that reports a shell the agent cannot reach is marked as failed.
- [13]
The article states that offensive security tools are dangerous and that an agent running arbitrary commands can cause unintended lateral movement, data loss or compliance violations.
- [14]
Traditional penetration testing is a linear, human-driven process in which the operator runs a tool, reads the output, picks the next step and holds the state in their head.
- [15]
The article lists the hard problems an autonomous agent must solve: execute tools in sequence without losing context, parse output and decide the next action, handle failures and dead-end paths, and maintain an audit trail for compliance and post-mortem analysis.
- [16]
The write-up is a design walkthrough of Decepticon's architecture and does not include code listings or performance benchmarks.
Get this ledger inside ChatGPT. Ask about any of our stories and the answer brings its figure, each claim’s verdict and the sources. Free, no account.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toDecepticon: Autonomous Red Team Orchestration with LangGraph
1 article · October 10, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.