Decepticon

Decepticon engagements (over MCP)

Drive Decepticon — an autonomous multi-agent red-team framework — as if its CLI were in this chat. Run an authorized engagement end to end (recon → exploitation → post-exploitation → reporting) across web, API, network, Active Directory, cloud, mobile, smart-contract, and binary targets, then watch it progress and steer it as it runs.

You interact through the decepticon_* MCP tools (listed below). The heavy work runs inside the Decepticon server; you are the operator at the console.

Mental model — read this first

• An engagement is a thread. decepticon_start_engagement returns a thread_id. That is the handle for every other tool — there are no run ids to track.
• The orchestrator (decepticon graph) builds an OPPLAN and delegates to specialist sub-agents (recon, exploit, postexploit, analyst, reverser, cloud_hunter, ad_operator, mobile_operator, …) via a task() tool. You watch that narrative and nudge it.
• Engagements are long and asynchronous (minutes to hours). start returns immediately; you poll and narrate. Never block waiting for completion.

Authorization — non-negotiable

• Only start engagements against assets the user has explicitly confirmed are in scope. If scope is unclear or missing, ask before starting — do not guess a target.
• ALWAYS pass scope + rules of engagement in instruction: name the in-scope hosts/domains/paths and the explicit out-of-scope items. The orchestrator enforces RoE on every tool call, but you are responsible for giving it correct scope.
• Decline targets that are plainly not the user's to test.

Prerequisites (verify on first failure)

• A Decepticon LangGraph server must be running and reachable (DECEPTICON_API_URL, default http://localhost:2024). If a tool errors with a connection failure, tell the user to start it (langgraph dev or the Docker stack) — don't retry blindly.
• The decepticon MCP server must be registered and launched with DECEPTICON_SKIP_BOOT=1 (fast start). See the integration docs.

Tools

Full parameters, defaults, clamps, and return schemas are in reference.md. Worked end-to-end runs are in examples.md.

The core loop

1. Pick a graph. Usually decepticon (full kill chain). Use recon for recon-only, soundwave for planning. decepticon_list_graphs() if unsure.
2. Start. decepticon_start_engagement(targets=[…], instruction="In scope: …; Out of scope: …", scan_mode="standard"). Save thread_id and engagement_name.
3. Watch + narrate. Loop decepticon_transcript(thread_id, after_index=<previous next_index>); summarise only the NEW messages for the user (coordinator decisions, task(<specialist>) delegations, results). For a live burst use decepticon_watch(thread_id). Check decepticon_engagement_status(thread_id, engagement_name); stop polling when status is terminal or findings_available is true.
4. Steer when useful: decepticon_send_message(thread_id, "skip the staging host, focus on the API"), answer the coordinator, or switch models with /model anthropic/claude-opus-4-8.
5. Report. When findings exist: decepticon_engagement_findings(engagement_name, include_sarif=true) → present severity, counts, and reproduction. decepticon_engagement_state for the OPPLAN/phase.
6. Resume later. decepticon_list_engagements() → reuse any thread_id.

Polling cadence (phone / chat friendly)

• Don't spam tools. While running, poll the transcript every ~15–30s and give the user a 1–2 line update per poll, not raw dumps.
• Use the returned next_index as your cursor so each update covers only new activity.
• decepticon_watch blocks up to max_seconds (≤45) — use it for a quick live glimpse, not as your main loop.

Interpreting results (fast guide)

• transcript.messages: role is user/assistant/tool. tool_calls like task(recon) means a specialist was dispatched. tool messages carry results.
• status: pending/running = working; success = finished; error/timeout/interrupted = stopped (say why; offer resume/restart); none = no run yet.
• findings: available=false → not persisted yet, keep polling. level_counts maps SARIF level → count (error = critical/high, warning = medium, note = low). Pass include_sarif=true to mine reproduction details.
• engagement_state.values: OPPLAN, objectives, scope, phase, working files.

Errors & recovery

• Connection failure → the Decepticon server isn't up at DECEPTICON_API_URL. Ask the user to start it; don't loop.
• findings_available=false for a while → normal early on; keep watching the transcript and report progress.
• status=error/timeout → read the last transcript messages for the cause, summarise it, and offer to send_message a fix or start fresh.
• No active run on watch/cancel → the engagement is idle/finished; use transcript/findings instead.

See reference.md and examples.md for depth.