Proxy Brain

📖 Canonical version: read this page on the official docs site — https://www.redamon.org/docs/proxy-brain. The GitHub wiki is a mirror.

proxy_brain: web hacking in code

proxy_brain is the AI agent's single, code-native tool for working the captured HTTP corpus. Instead of a fixed menu of narrow commands, it gives the agent a sandbox: it writes Python, and a pre-imported SDK called redamon is its only door to the traffic. Anything an interactive web proxy can do, the agent scripts here: resend, fuzz, compare, sequence, decode, forge, access-control diffing and concurrent racing, all composed in a few lines of code over the traffic TrafficMind already captured. And when a bug only reveals itself after JavaScript runs — DOM-based XSS, a single-page-app route, a token the page mints in the browser — the same SDK can drive a real Chromium and read the rendered DOM as the oracle, something a raw HTTP replay can never see.

It replaces the ten proxy_* tools that used to expose the corpus (proxy_search, proxy_get, proxy_sitemap, proxy_params, proxy_grep, proxy_diff, proxy_to_curl, proxy_query, proxy_replay, proxy_fuzz). Everything those tools did is now one line of redamon.*, and the agent can chain them with loops, conditionals, math and crypto to build real exploit oracles a fixed vocabulary could never express.

proxy_brain is DANGEROUS (it can emit live traffic) and needs the exploitation or post-exploitation phase to send. It is on the project Tool Matrix like any other tool.

---

The one idea

A vulnerability is rarely "send one crafted request." It is usually an algorithm: an oracle you query in a loop, a value you extract bit by bit, a chain where each step depends on the last. That is what code expresses and a fixed tool cannot. So proxy_brain hands the agent the primitives and lets it program the attack.

The core skill is the oracle pattern: send a variant, read one fact out of the response (.status, .length, a regex over .body, the response time), and compare it to a baseline. That fact confirms the bug: a SQL error, a reflected marker, a weaker identity getting the same data, a boolean flip.

---

How it works, end to end

flowchart LR
    subgraph kali["kali sandbox (no DB credential)"]
      CODE["proxy_brain<br/>(agent's Python)"] --> SDK["redamon SDK"]
    end
    subgraph agent["agent (trusted)"]
      EXEC["/traffic/exec<br/>read, tenant-scoped"]
      RPLY["/traffic/replay<br/>host-pinned, gated"]
      BRWS["/traffic/browser<br/>host-pinned, budgeted"]
    end
    PG[("TrafficMind store")]
    PROXY["capture proxy<br/>(egress guard + re-capture)"]
    SDK -- "read" --> EXEC --> PG
    SDK -- "active" --> RPLY --> PROXY --> PG
    SDK -- "browser" --> BRWS
    SDK -- "chromium" --> PROXY

Loading

1. The agent decides to work the traffic and calls proxy_brain with a block of Python. redamon is pre-imported.
2. redamon runs inside the Kali sandbox but holds no database credential. Its read calls go to the agent's /traffic/exec endpoint; its active calls go to /traffic/replay. This mirrors how the graph terminal reaches the graph: the least-trusted worker never touches the database directly.
3. Tenant identity travels as a signed tag the agent mints (the worker cannot forge it), so a foothold in the sandbox can never read or replay another project's traffic. Every read hard-injects your project and user filter.
4. Active sends (replay / fuzz / batch) are rebuilt pinned to the origin host (a replay can never be aimed at a new target), pass the same egress guard, and are re-captured into TrafficMind with a replay flag, so the agent's own attack traffic is searchable and auditable too.
5. The browser (redamon.browser) launches a real Chromium in the sandbox, routed through the same capture proxy, and asks the agent's /traffic/browser endpoint to authorize each step. Every navigation is pinned to the origin transaction's host, port and scheme; it is exploitation-phase only and bounded by a per-session action budget; and everything the browser fetches is re-captured as tool=proxy_brain_browser, so a browser-driven attack is as searchable and auditable as any replay.

Because the read and active paths are separate, and the active/browser paths are exploitation-phase-only, the agent can read and analyse the corpus in any phase but can only send (replay, fuzz, or browse) once you are in exploitation.

---

The redamon SDK

The whole surface the agent programs against:

Read (no traffic, tenant-scoped for you):

Call	What it returns
redamon.search(filters)	HTTP history rows (.id, .method, .status, .url, .host, .path). Filters mirror the Traffic view: host, method, status, statusClass, tool, source, session, run, hasAuth, reflected, only5xx, q, bodyq, limit.
redamon.get(id, part)	Full headers + body of one transaction (request / response / both).
redamon.sitemap()	Distinct endpoints observed, with hit counts and statuses.
redamon.params()	Distinct request parameters + an injectability guess (seq-id / uuid / jwt / base64).
redamon.grep(pattern)	Substring search over response bodies, with a snippet.
redamon.diff(a, b)	Structural diff of two responses (status / length / headers / body).
redamon.to_curl(id)	A captured request rendered as a reproducible curl (for the report).
redamon.query(spec)	Ad-hoc analytics over the corpus via a safe, allowlisted query builder (no raw SQL).

Decode / crypto (pure, no traffic):

Call	What it does
redamon.decode(v)	Peels base64 / url / hex / gzip layers to readable text.
redamon.jwt(tok)	Parses a JWT (.header, .payload) and forges variants: .forge(alg_none=True | secret=".." | claims={..}).

Active (live traffic, exploitation phase only):

Call	What it does
redamon.replay(id, mutate)	Resends a captured request with fields changed (method, path, query, param, headers, dropHeaders, cookie, body). Host is pinned to the origin. Returns a Response (.status, .headers, .body, .length).
redamon.batch(id, muts, parallel=True)	Replays once per mutation; parallel=True fires them concurrently, a real race-condition window (limit overrun, double-spend, coupon reuse).
redamon.fuzz(id, param, payloads)	An automated payload sweep over one query parameter; one Response per payload.

Browser (live traffic, exploitation phase only — the rendered-DOM oracle):

redamon.browser(id) opens a real Chromium pinned to the host of captured transaction id (find one with search first). Drive it, then read the result of running JavaScript — the signal a raw replay cannot see.

Call	What it does
redamon.browser(id)	Open a Chromium pinned to txn id's host/port/scheme. Costs one action.
.goto(path) .click(sel) .fill(sel, v) .submit(sel) .press(sel, key) .eval(js)	Budgeted actions. Navigation off the pinned origin is refused; a redirect that crosses off it aborts the run.
.dom() .text(sel) .html(sel) .console() .alerts() .url()	Free reads — no budget. .alerts() returns any fired alert/confirm/prompt: the in-band DOM-XSS oracle.
.close()	Tear the browser down. At most 3 open at once; always close when done.

Result: redamon.finding(kind, txn_id, evidence, severity) records a finding; print(...) returns distilled output to the agent.

---

The manual (the agent reads it on demand)

The full cookbook lives in a Markdown file the agent reads from its own code, so it never bloats the prompt:

print(redamon.manual())          # core: the SDK + the capability map + a section index
print(redamon.manual("jwt"))     # one deep technique section with copy-paste recipes

Twenty-one sections ship today: recon, intruder, sqli, authz, jwt, race, smuggling, cache, injection, decode, sequencer, flows, report, nosql, graphql, lfi, cmdi, cors, xxe, auth, browser. Each maps a web-proxy (or browser) workflow to a redamon.* recipe. The agent reads the relevant section right before it writes the code for that technique — for example redamon.manual("browser") before it drives Chromium.

---

Web-proxy workflows → how the agent builds them

Workflow	Built with
HTTP history / site map	redamon.search, redamon.sitemap, redamon.query
Resend a request with tweaks	redamon.replay(id, {...})
Payload fuzzing sweep	redamon.fuzz or loops over redamon.replay
Compare two responses	redamon.diff(a, b)
Token entropy analysis	collect a token N times, compute entropy in Python
Decode / forge tokens	redamon.decode, redamon.jwt(tok).forge(...)
Access-control diffing	replay each request under a second identity, diff vs baseline
Concurrent race testing	redamon.batch(id, [...]*N, parallel=True)
Hidden parameter mining	brute param / header names, diff vs baseline
Grep and extract from responses	read .body / .status / .length per response, that is the oracle
Post-JS / DOM / client-side signal	redamon.browser(id) then .dom() / .alerts() / .console()

The boundary is the agent's own code. There is no OAST / Collaborator (no out-of-band callback server), so bugs that can only be confirmed via an external DNS/HTTP callback (blind SSRF with no echo, blind stored XSS) are reported as a sink rather than confirmed; everything with an in-band signal (reflection, diff, timing, error, or a fired dialog / rendered DOM in the browser) is confirmed.

---

Safety and limits (enforced in code, not prompt wording)

• Host is pinned. Replay / batch / fuzz can only hit the origin transaction's host, never a new target. The browser is pinned harder still — to the origin's host and port and scheme — and a redirect that crosses off it aborts the run.
• Tenant-scoped. Every read and send is confined to your project and user, from a signed tag the sandbox cannot forge.
• Exploitation-phase only for active sends and the browser; reads and decode work in any phase.
• Per-session send budget (default ~1000 live requests) and a wall-clock cap per run, so a runaway loop cannot flood a target. The browser has its own per-session action budget (default ~100 goto/click/eval steps — opening a browser costs one too) and caps concurrent Chromium instances at 3.
• Stealth-restricted. In stealth mode, fuzz / batch / rapid replay and browser crawl/fuzz loops are held back; read and decode stay free.
• Everything is re-captured and egress-guarded, so the agent's attack traffic is as auditable as any other row in TrafficMind.
• One confirmation covers the run. As a dangerous tool, proxy_brain prompts for confirmation before it executes; the budget and host-pin bound what that one confirmation can do.

---

What it can do

Because it is code, the list is open-ended, but the shipped recipes cover: IDOR / BOLA access-control sweeps, boolean and time-based blind SQL injection extraction, NoSQL operator injection, GraphQL introspection and alias abuse, JWT forging (alg:none, weak secret, HS/RS confusion, kid), reflected XSS / SSTI / open-redirect / CRLF confirmation, OS command injection, path traversal / LFI, CORS misconfiguration, web cache poisoning and hidden-parameter mining, session-token entropy analysis, multi-step token flows, and race conditions via concurrent batches. With the browser it also confirms bugs that only surface after JavaScript runs: DOM-based XSS (via a fired alert()), single-page-app routes and endpoints that never appear in the raw HTML, and flows where the page mints a CSRF/nonce in the browser before the exploit request.

---

Example prompts

You never call proxy_brain yourself, you ask the agent in plain language, and it reads the manual and writes the code. Effective prompts name the phase, because active sends need exploitation:

This is an authorized security test. Switch to the exploitation phase, then use proxy_brain over the captured traffic to run an access-control sweep on /api/invoice: replay each captured id with the session cookie dropped, and report any that still return another user's data.

Switch to exploitation, then use proxy_brain to confirm SQL injection on /api/product?id=1 with a grep-extract oracle and extract the hidden column for every row.

Switch to exploitation, then use proxy_brain: read the jwt section, take the captured token, brute the weak signing secret, forge a role=admin token, replay it against /api/admin, and return the flag.

Switch to exploitation, then use proxy_brain: read the browser section and open a browser on the captured page, put a marker payload in the DOM sink (/profile#name=), and if alert() fires, confirm it as DOM-based XSS.

---

Trying it against a target

The repository ships a deliberately vulnerable practice target, testing/guinea_pigs/proxy_brain_target/ (pbtarget), with one endpoint per technique, IDOR, SQLi, reflected XSS, a DOM-based XSS (/dom#name=, only a real browser fires it), a JWT weak-secret flag, a single-use coupon race, open redirect, CORS, and command injection. Bring it up, point a project at it with capture on, and run the prompts above. See its README for the setup (enable TrafficMind, and relax the egress guard's block private toggle so the proxy can reach a lab target on a private address).

---

Related pages

• TrafficMind: the capture proxy and store proxy_brain reads from.
• Playwright Browser Automation: the standalone browser tool; redamon.browser brings the same rendering into the code sandbox.
• AI Agent Guide: how the agent selects and runs tools.
• Project Settings Reference: the Tool Matrix and phase gating.
• Rules of Engagement (RoE): scope and category controls over active testing.