ida-swarm-technical-reference

name	IDA Swarm Technical Reference
description	Technical reference for using IDA Swarm MCP tools. Covers system constraints, architecture, TRUE CONTEXT principle, result interpretation, and debugging. Use when analyzing binaries via IDA Swarm or troubleshooting sessions.

IDA Swarm Technical Reference

Critical Constraints

ONE pending message per session

• Cannot send second message while first is processing
• Error: "session is still processing previous message"
• Use get_session_messages() to poll or wait_for_response() to block

Sessions are deterministic

• session_id = "session_" + SHA256(binary_path)[:16]
• Same binary always gets same session_id
• Prevents duplicate sessions
• Must close existing session before creating new one for same binary

Results are in response text

• start_analysis_session() and send_message() return synthesized findings
• Orchestrator collects all agent work and returns coherent response

extract_results.sh is DEBUG ONLY

• Creates HUGE raw dump of all agent data
• Only use when debugging "why did orchestrator conclude X?"
• Not part of normal workflow
• Normal results come from response text

TRUE CONTEXT Principle

Why This Matters

Orchestrator spawns specialized agents based on task description. Task quality determines:

• What types of agents spawn (network analysis? crypto? vulnerability research?)
• How agents prioritize work
• Analysis depth
• Whether findings meet actual needs

Deriving Effective Task Descriptions

Reason through what orchestrator needs to understand:

1. What is the actual objective?

• Not "analyze network code" → WHY: Extracting C2? Understanding protocol? Finding vulnerabilities?
• Objective determines agent specialization

2. What form should results take?

• Not "provide analysis" → Addresses with annotations? IOC list? Pseudocode? Detection signatures?
• Output format affects what agents extract

3. What would make results unusable?

• Missing function addresses? No proof? Incomplete spec?
• Understanding failure modes clarifies success criteria

Cognitive Process

Before sending task:

• If agents only knew what I've written, could they derive what's actually needed?
• What decisions will agents make based on this description?
• Am I describing surface task ("find X") or underlying goal ("because I need Y")?

Example reasoning:

"Find network functions" → Agents don't know:

• WHY needed (IOC extraction vs protocol RE require different approaches)
• Platform specifics (WinSock vs POSIX)
• What constitutes completeness

Derive:

• WHY: C2 infrastructure for threat intel → Agents prioritize: IOCs, destinations, protocol patterns, evasion
• CONTEXT: Windows PE, APT, encrypted custom protocol → Agents look for: WinINet/WinSock, crypto on network data, DGA
• OUTPUT: IOC table, protocol structure, signatures → Agents extract: IPs/domains/ports, message format, detection patterns

Result: Agents spawn with APT C2 specialization, focus on actionable IOCs, extract detection-relevant patterns.

Framework as Scaffold

WHAT - Technical task WHY - Actual objective determining approach CONTEXT - Information constraining/focusing analysis OUTPUT - Form making results usable

Not rules. Questions to reason through what enables effective agent spawning.

Orchestrator can't read your mind. It derives agent strategy from task description.

Architecture Essentials

Communication flow:

Claude Code → MCP Server → Orchestrator (IDA) → Agents (IDA instances)

Two workspace locations:

/tmp/ida_swarm_sessions/{session_id}/

• IPC files: request.json, response.json, sequence files
• ida.err - check this for IDA errors
• ida.out - IDA stdout

/tmp/ida_swarm_workspace/{binary_name}/

• agents/agent_N/ - agent databases, logs, memories
• orchestrator.log - check for orchestrator errors
• profiling/ - performance metrics (if enabled)
• extract_results.sh - debug tool (raw agent dump)

File-based IPC

• Orchestrator polls sequence files for changes
• Atomic writes via tmp+rename
• Response text contains orchestrator's synthesis

Agent coordination

• Agents work on isolated database copies
• IRC for conflict resolution when agents disagree
• Orchestrator merges findings after agents complete
• Response text contains merged result

Tool Usage Patterns

start_analysis_session

• Spawns IDA
• Returns session_id and initial findings in response text
• run_in_background=true returns immediately (use for parallel analysis)

send_message

• Orchestrator maintains full context from previous messages
• Can reference previous findings naturally
• Returns synthesized response text
• run_in_background=true requires retrieving response later

close_session

• 60-second graceful shutdown (IDA database save)
• Cleans workspace directory
• Orphaned files (created by orchestrator) remain where they were written

get_session_messages

• Non-blocking poll for background mode
• Returns empty if still processing
• Clears message queue when retrieved

wait_for_response

• Blocking wait for background mode
• Returns when response available
• Use for parallel analysis coordination

Background Mode (Parallel Analysis)

When to use run_in_background=true:

• Analyzing multiple binaries simultaneously
• Long analysis + other work needed

Pattern:

s1 = start_analysis_session(bin1, task1, run_in_background=true)
s2 = start_analysis_session(bin2, task2, run_in_background=true)
s3 = start_analysis_session(bin3, task3, run_in_background=true)

r1 = wait_for_response(s1)
r2 = wait_for_response(s2)
r3 = wait_for_response(s3)

Orchestrator Capabilities

File writing

• Can create files (scripts, reports, configs)
• Default location: next to binary
• Can specify custom paths in request

Binary patching

• Agents can modify binaries via Keystone assembler
• Patches applied to both IDA database and actual binary file

Multi-agent decomposition

• Orchestrator spawns specialized agents based on task
• Quality of task description determines agent specialization
• Agents work in parallel, findings merged

Common Issues

"Session started but no response"

• Check /tmp/ida_swarm_sessions/{session_id}/ida.err
• Verify IDA process: ps aux | grep ida64
• Check orchestrator log: tail /tmp/ida_swarm_workspace/{binary}/orchestrator.log

"Cannot send message: still processing"

• ONE pending message constraint
• Use get_session_messages() to check status
• Wait for response before next message

Optimization

Reuse sessions

• Multiple follow-up questions in same session
• Much faster than closing and reopening

Debugging Checklist

• IDA process running? ps aux | grep ida64
• IDA errors? cat /tmp/ida_swarm_sessions/{session_id}/ida.err
• Orchestrator errors? grep -i error /tmp/ida_swarm_workspace/{binary}/orchestrator.log
• Agent logs? ls /tmp/ida_swarm_workspace/{binary}/agents/
• Sequence files? cat /tmp/ida_swarm_sessions/{session_id}/*_seq

Configuration

MCP Server: ~/.ida_swarm_mcp/server_config.json

{
    "max_sessions": 25,
    "ida_path": "/Applications/IDA Professional 9.0.app/Contents/MacOS/ida64"
}

Orchestrator: ~/.idapro/llm_re_config.json

{
    "api": {"auth_method": "api_key", "api_key": "sk-ant-..."},
    "profiling": {"enabled": true}
}

Key Takeaways

1. Sessions are deterministic (same binary = same session_id)
2. Results in response text, not extract_results.sh (debug only)
3. ONE pending message per session at a time
4. TRUE CONTEXT determines agent spawning quality
5. 10+ minutes is normal, not hung
6. Two workspace directories for debugging
7. extract_results.sh = debug tool for raw agent data
8. 60-second shutdown is graceful IDA database save