agents.md

Agents

Decepticon combines stable specialist capabilities with selected business workflows. Decepticon owns execution OPPLAN, Soundwave is an optional standalone planner, and the optional Vulnresearch plugin retains its separate legacy pipeline. Blue Cell investigates local sensor evidence; the broader Offensive Vaccine loop remains planned. See the extension contract. Each agent starts with a fresh context window per objective — no accumulated noise, no context degradation. Findings persist to disk (workspace/) and the knowledge graph, not agent memory.

---

Agent Roster

Orchestrators

Agent	Role
Decepticon	Main red-team orchestrator. Reads the OPPLAN, dispatches objectives to specialist sub-agents, and tracks status transitions. Sub-agents: recon, exploit, postexploit, analyst, reverser, contract_auditor, cloud_hunter, ad_operator, phisher, mobile_operator, wireless_operator, osint_operator, iot_operator, ics_operator, forensicator, supply_chain_operator, finding_verifier, finding_reporter.
Vulnresearch	Vulnerability research orchestrator — runs the five-stage pipeline (scanner → detector → verifier → patcher → exploiter) with state passed between stages exclusively through the knowledge graph.
Soundwave	Engagement planner. Standalone graph (not a sub-agent of Decepticon). Uses an optional planning workflow to discuss and prepare seven documents alongside the operator-provisioned, read-only RoE. Publication does not switch to Red. The execution orchestrator builds OPPLAN.

Additional standard and optional graphs

• autohunt is a separately registered bootstrap planner, reusing Soundwave's document-only contracts. It is not a mandatory precondition for normal Red.
• finding_verifier independently adjudicates findings using reproduction and equivalent negative controls. finding_reporter writes the canonical report after verification; it has no shell tool.
• Blue mode selects the external AutoBot autobot graph when its package and sensor are configured. It is not a built-in Decepticon blue_cell factory.

The current graph registry and package entry points define availability; a fixed historical agent count is not a discovery API.

Reconnaissance

Agent	Role
Recon	Port scanning, service enumeration, DNS, subdomain discovery, OSINT. Populates the knowledge graph with hosts and services.

Vulnerability Research Pipeline

Sub-agents of the Vulnresearch orchestrator. State flows between stages via the knowledge graph; each stage runs with fresh context.

Stage	Agent	Output
Discovery	Scanner	Vulnerability candidates with CVE/CVSS
Analysis	Detector	Confidence-rated findings, detection rules
Confirmation	Verifier	Verified findings (2+ methods for CRITICAL/HIGH)
Exploitation	Exploiter	Working proof-of-concept
Remediation	Patcher	Patch code or configuration fix

Exploitation & Post-Exploitation

Agent	Role
Exploit	Initial access and exploitation tactics. Web/AD attacks (SQLi, SSTI, Kerberoasting, ADCS abuse, credential attacks).
Post-Exploit	Privilege escalation, lateral movement, credential harvesting, persistence. Operates via C2 sessions once initial access is established.

Domain Specialists

Agent	Role
AD Operator	Active Directory attacks — Kerberoasting, AS-REP roasting, ADCS ESC1-ESC15, DCSync, BloodHound path analysis.
Cloud Hunter	Cloud infrastructure attacks — IAM privilege escalation, S3 bucket exposure, Kubernetes RBAC escapes, metadata service abuse.
Contract Auditor	Solidity / EVM smart contract audits — reentrancy, oracle manipulation, flash loan abuse, access control.
Reverser	Binary analysis and reverse engineering — ELF/PE/Mach-O triage, packer detection, ROP gadget inventories, and REA/Ghidra static analysis when its optional workload is configured. REA reversing.
Analyst	Vulnerability research and reporting — source code review, static analysis (semgrep/bandit/gitleaks), dependency CVE sweeps, multi-hop exploit chain construction.
Phisher	Initial-access via phishing / social engineering (MITRE T1566.*) — GoPhish campaigns, evilginx2 MFA-bypass token capture, M365/O365 OAuth device-code harvest, lookalike domains, pretext engineering. Mandatory lure deconfliction with the blue team before sending.
Mobile Operator	Android / iOS application attacks — static analysis (apktool/jadx/class-dump), dynamic instrumentation (frida/objection), SSL pinning + root/jailbreak bypass, exported-component abuse, WebView JS bridge exploitation, MobSF.
Wireless Operator	Wi-Fi / BLE / Zigbee / sub-GHz attacks — WPA2 handshake / PMKID capture, WPA3-SAE downgrade, WPA-Enterprise evil-twin, KARMA / Mana, deauth, WPS Pixie Dust, BLE GATT, Zigbee Touchlink, sub-GHz replay. Requires hardware passthrough or an SSH dropbox.
OSINT Operator	Passive open-source intelligence — domain/email/employee/breach/code-leak/infra footprinting. Read-only; feeds Recon and Exploit.
IoT Operator	IoT / embedded device attacks — firmware acquisition + binwalk extraction, hardcoded credentials, U-Boot / /dev/mem, and BLE/Zigbee/Z-Wave/sub-GHz/LoRaWAN radios.
ICS Operator	ICS / OT / SCADA attacks (Modbus, DNP3, S7comm, BACnet, OPC-UA). RoE-gated; read-only enumeration first, lab/canary-only for writes.
Forensicator	DFIR / purple-team validation — disk/memory/log/network timeline analysis, IOC extraction, attack→detection mapping.
Supply Chain Operator	Software supply-chain attacks — dependency confusion, typosquatting, malicious packages (npm/PyPI/crates), CI/CD + build-step compromise.

---

Fresh Context Model

Every specialist agent runs with a clean context window for each objective:

• The orchestrator picks the next pending objective from the OPPLAN
• A new agent instance is spawned with only what it needs: the objective, RoE guard rails, and relevant findings from disk
• The agent executes, writes findings to workspace/, and returns a PASSED or BLOCKED signal
• The orchestrator updates the OPPLAN and moves to the next objective

This prevents context window bloat and token accumulation across a long engagement.

---

Middleware Stack

Each agent assembles its middleware stack from a fixed set of named slots (MiddlewareSlot). The enum declaration order is the canonical assembly order — every factory walks the enum top-to-bottom and instantiates only the slots its role opts into via SLOTS_PER_ROLE. Plugins replace or disable slots by name (PluginBundle.replaced_middleware / disabled_middleware); slot definitions and the per-role mapping live in decepticon_core.contracts.slots, the langchain-bound factories in decepticon.agents.middleware_slots.

Safety stack (every agent)

These slots are part of the base set every role receives — they are the engagement guard rails:

Middleware	Slot	Purpose
RoEGuardrailMiddleware	roe-guardrail	Legal/safety gate on tool calls — extracts the target, evaluates it against the Rules of Engagement, and appends to a chained audit log (<workspace>/audit/roe-decisions.jsonl, or DECEPTICON_ROE_AUDIT_PATH). A best-effort command-parse gate plus a separate egress-policy provisioning attempt. Verify applied daemon policy; provisioning failures do not stop the run. The class/enum compatibility aliases remain in source; no removal at 2.0.0 occurred. Missing machine configuration is refused; legacy audit/warn mode keys are ignored.
UntrustedOutputMiddleware	untrusted-output	Quarantines attacker-influenceable tool output (bash stdout, file reads, KG queries) inside a <UNTRUSTED_TOOL_OUTPUT> envelope so hostile content can't re-author the agent's instructions.
PromptInjectionShieldMiddleware	prompt-injection-shield	Deny-list wrap of attacker-controlled tool output (HTTP bodies, banners, file reads); dedups against UNTRUSTED_OUTPUT and does not re-inject the system policy.
EventLogMiddleware	event-log	Structured event logging for every model and tool call.
BudgetEnforcementMiddleware	budget	Enforces per-engagement spend caps (no-op when caps ≤ 0).

Bash-executing agents and the orchestrator additionally get:

Middleware	Slot	Purpose
EngagementContextMiddleware	engagement-context	Injects engagement metadata (slug, workspace) and per-challenge state (target URL, tags, flag format, mission brief) into every model call. Carries RoE scope into tool calls — it is safety-critical.
SandboxNotificationMiddleware	sandbox-notification	Tracks background-job completion and emits the CLI's Background command event. Bash agents only.
HITLApprovalMiddleware	hitl-approval	Operator-approval gate for high-impact actions (credential dumping, destructive ops). Opt-in — skipped unless DECEPTICON_HITL__ENABLED is set to a truthy value (off by default so engagements don't freeze waiting on a human).

Framework middleware

Middleware	Slot	Purpose
SkillsMiddleware	skills	Loads SKILL.md frontmatter, filters by agent role, and injects matching skill descriptions into the system prompt. Full skill content is fetched on demand via the load_skill tool — read_file / bash cat do not resolve /skills/* (that tree is served in-process by a local FilesystemBackend, not the sandbox).
FilesystemMiddleware	filesystem	Provides read_file, write_file, edit_file, ls, glob, grep tools backed by the sandbox filesystem. Execute is intentionally stripped — agents use the dedicated bash tool for command execution.
SubAgentMiddleware	subagent	Allows orchestrators (Decepticon, Vulnresearch) to delegate objectives to specialist sub-agents via the task() tool.
OPPLANMiddleware	opplan	Injects the current OPPLAN progress table into every LLM call and provides CRUD tools for objective management.
ModelOverrideMiddleware	model-override	Session/per-objective model selection; included in the common tail slots.
ModelFallbackMiddleware	model-fallback	Switches to a fallback model on provider outage, rate limit, or context overflow. Conditional — skipped when no fallback chain is configured.
SummarizationMiddleware	summarization	Auto-compacts conversation history when the context window approaches capacity.
AnthropicPromptCachingMiddleware	prompt-caching	Caches static system prompt content for Anthropic models to reduce token costs. Silently no-ops on non-Anthropic providers.
PatchToolCallsMiddleware	patch-tool-calls	Sanitizes and normalizes tool call formats for compatibility across model providers (e.g. repairs dangling tool calls).

Safety-critical slots

SAFETY_CRITICAL_SLOTS — engagement-context, roe-guardrail, untrusted-output, prompt-injection-shield, sandbox-notification, opscontrol-notification, hitl-approval — can only be replaced or disabled by a plugin when DECEPTICON_ALLOW_SAFETY_OVERRIDES=1 is set in the environment. The gate is enforced by build_middleware in decepticon.agents.build; without it, an override raises SafetyOverrideViolation. Replacement is fine if the new middleware honours the same contract — the gate exists so an accidentally-installed plugin can't silently subvert the safety story.

Assembly and role differences

The slot map and default factories are the current assembly contract. Older diagrams omitted KG, opscontrol notifications, proxy-key overrides and model overrides on specialists.

Role family	Distinct slots/behavior
Decepticon	Engagement context, subagent dispatch, OPPLAN, optional HITL and opscontrol notifications
Bash specialists	Engagement context, sandbox notifications and optional HITL
Analyst, AD Operator, Contract Auditor	Bash specialist stack plus conditional KG middleware
Soundwave and finding reporter	Engagement context without bash/HITL/sandbox notifications
Vulnresearch	Common stack plus subagent dispatch and OPPLAN
Detector	Common read-only stack without bash/engagement context

Common tail slots include model override/fallback, per-run proxy-key override, summarization, prompt caching and tool-call repair. Individual factories may add middleware such as StepBudget beyond slot assembly. Skillogy normally replaces the local SkillsMiddleware through maybe_install_skillogy; an explicit opt-out retains local skill reads. See Skillogy.

The legacy blue_cell slot definition is not proof of an installed Blue graph; current Blue runtime ownership is AutoBot. Runtime tool availability, workflow pins and authorization must be checked on the actual role.