agentburp

README

[!NOTE] Strict Scope & Authorization Requirement: Only use agentburp against targets you are explicitly authorized to test. The engine refuses all traffic not listed in scope.yml's allow_hosts.

⚡ agentburp

A CLI-first, agent-native HTTP intercepting proxy and bug bounty toolkit.

Burp Suite's core workflow — proxy, history, repeater, intruder/fuzzer, diffing, heuristic scanning, and PoC reporting — re-engineered so AI agents and terminal power-users can drive security testing entirely through JSON output and an MCP stdio server, with no heavy GUI required.

Developed by JOJIN JOHN

Quick Launch

# 1. Download prebuilt agentburp.exe from Releases (No Go or Git needed!)
# https://github.com/jojin1709/agentburp/releases

# 2. Or build from source
go build -o agentburp ./cmd/agentburp

# 3. Start proxy
./agentburp proxy start --addr 127.0.0.1:8888

_{Capture, replay, fuzz, and report directly from your command line or Claude / Cursor / MCP agents.}

---

[!TIP] AI Agents and LLMs: Run ./agentburp mcp-serve to connect agentburp directly to Claude, Cursor, or any Model Context Protocol (MCP) compatible AI agent over newline-delimited JSON-RPC stdio.

---

Table of Contents

• Table of Contents
• What is agentburp?
  • Why agentburp Exists
  • Why "agentburp"?
  • Designed for Agents and Human Researchers
• agentburp in Action
• Quick Start
  • Prerequisites
  • 1. Build agentburp
  • 2. Configure Scope
  • 3. Start the Proxy
  • 4. Intercept, Replay, and Fuzz
• Key Capabilities
• Command Reference
• MCP / Agent Integration
• Architecture
• Safety Rails & Scope Guard
• Roadmap
• Common Questions
• Author & License

---

What is agentburp?

agentburp brings the core capabilities of web security testing suites into a lightweight, headless, JSON-native CLI. Built with Go and SQLite, it acts as both a high-performance terminal tool for security engineers and a native stdio tool-server for autonomous LLM security agents.

Why agentburp Exists

Traditional GUI interception proxies like Burp Suite Professional and OWASP ZAP are designed for manual human clicks. When pairing with AI coding assistants, autonomous agents, and scriptable CI/CD workflows, GUIs introduce friction, heavyweight memory overhead, and clunky extension APIs.

agentburp strips away the heavyweight UI and provides pure JSON stdout, fast SQLite persistence, strict YAML scope enforcement, and an MCP server out of the box.

Why "agentburp"?

It mirrors the indispensable workflow security researchers rely on in Burp Suite (Proxy -> HTTP History -> Repeater -> Intruder -> Scanner -> Report), but designed from the ground up for Agents: deterministic outputs, machine-parsable JSON, rate-limited execution, and MCP stdio integration.

Designed for Agents and Human Researchers

Whether you are an ethical hacker hunting bug bounties from your terminal, or configuring an autonomous AI pentester in a CI/CD pipeline, agentburp provides the exact tools needed to discover, isolate, and document vulnerabilities reliably.

---

agentburp in Action

Every operation outputs clean, structured JSON formatted for machine-consumption and human readability:

Tool Module	CLI Command	Purpose
Proxy	agentburp proxy start	Intercepts HTTP traffic and writes full request/response pairs into SQLite
History	agentburp hist list / show	Query and filter captured traffic by host, method, status code, or body text
Repeater	agentburp repeat <id>	Replay stored requests with modified headers, auth tokens, or payloads
Fuzzer	agentburp fuzz <id>	Parameter fuzzing against baselines with automated anomaly detection
Diff	agentburp diff <a> <b>	Structural diff of status codes, headers, and bodies between two requests
Scanner	agentburp scan <id>	Heuristic candidate checks (IDOR, open redirect, CORS, JWT, SSRF hints)
Report	agentburp report <id>	Generates ready-to-submit HackerOne, Bugcrowd, or Markdown PoC writeups
MCP Server	agentburp mcp-serve	Exposes full toolkit to AI agents over JSON-RPC stdio protocol

---

Quick Start

Prerequisites

• Go 1.22+ installed on your system
• An authorized test environment or target

1. Installation

Option A: Prebuilt Executable (Fastest — No Go or Git required)

Download the standalone executable directly from the Releases page:

• Windows: agentburp.exe / agentburp-windows-amd64.exe
• Linux: agentburp-linux-amd64 / agentburp-linux-arm64
• macOS: agentburp-darwin-arm64 (Apple Silicon) / agentburp-darwin-amd64 (Intel)

Option B: Build from Source

git clone https://github.com/jojin1709/agentburp.git
cd agentburp
go mod tidy
go build -o agentburp ./cmd/agentburp

2. Configure Scope

[!WARNING] By design, agentburp blocks all requests by default unless explicitly allowed in scope.yml.

Copy the example scope configuration and define your authorized targets:

cp examples/scope.yml ./scope.yml

Edit scope.yml to specify your in-scope hosts:

workspace: mytarget

allow_hosts:
  - "target.com"
  - "*.target.com"

deny_hosts:
  - "payments.target.com"

rate_limit_per_sec: 10
safe_mode: true

3. Start the Proxy

# Switch to or create a named workspace
./agentburp workspace use mytarget

# Start the intercepting proxy listener
./agentburp proxy start --addr 127.0.0.1:8888

Configure your browser, mobile device, or HTTP client to route traffic through http://127.0.0.1:8888.

4. Intercept, Replay, and Fuzz

# View captured HTTP history
./agentburp hist list --host target.com --limit 20

# View request/response details for entry #12
./agentburp hist show 12

# Replay entry with an updated authorization token
./agentburp repeat 12 --set "Authorization: Bearer ATTACKER_TOKEN"

# Fuzz an ID parameter over numeric range 1..100
./agentburp fuzz 12 --param id --range-from 1 --range-to 100 --confirm

# Diff two requests to inspect authorization bypass or state differences
./agentburp diff 12 13

# Run heuristic vulnerability scans
./agentburp scan 12

# Generate a professional HackerOne PoC report
./agentburp report 12 --format hackerone

---

Key Capabilities

• CLI-First & Agent-Native: No browser or GUI required. Works seamlessly over SSH, in scripts, CI pipelines, and with AI agents.
• Strict Scope Guard: Host matching with wildcard support (*.target.com), regex support, explicit deny lists, and default-deny safety.
• Safe Mode & Audit Logging: Destructive fuzzing or active operations are barred without explicit confirmation (--confirm), and all actions are recorded in the SQLite audit log.
• Built-in Rate Limiting: Global request throttling protects target servers and prevents rate-limit bans during automated scans.
• Zero Heavy Dependencies: Pure Go with SQLite storage. Single binary deployment with instant startup.
• Automated Bug Bounty Reporting: Directly outputs formatted Markdown reports structured specifically for HackerOne and Bugcrowd submissions.
• Native MCP Protocol: Plug directly into AI agent workflows (Claude Code, Cursor, Windsurf, custom LLMs) via stdio JSON-RPC.

---

Command Reference

Usage:
  agentburp proxy start [--addr 127.0.0.1:8888] [--scope scope.yml]
  agentburp hist list [--host H] [--method M] [--status N] [--body S] [--limit N]
  agentburp hist show <id>
  agentburp repeat <id> [--set "Header: value"]... [--body B]
  agentburp fuzz <baseline_id> --param NAME (--wordlist FILE | --range-from N --range-to N) [--anomalies] [--confirm]
  agentburp diff <id_a> <id_b>
  agentburp scan <entry_id>
  agentburp report <entry_id> [--format hackerone|bugcrowd|generic] [--finding-id N]
  agentburp workspace use <name>
  agentburp workspace current
  agentburp mcp-serve [--scope scope.yml]

Global:
  --scope PATH   path to scope.yml (default "scope.yml"), accepted by any subcommand

---

MCP / Agent Integration

Launch agentburp as an MCP server to provide security tools directly to your LLM agent:

./agentburp mcp-serve --scope scope.yml

The server communicates via newline-delimited JSON-RPC over stdin/stdout:

{"id": 1, "method": "history.search", "params": {"host": "target.com", "limit": 10}}
{"id": 2, "method": "fuzz", "params": {"baseline_id": 12, "param": "id", "range_from": 1, "range_to": 100}}
{"id": 3, "method": "diff", "params": {"a": 12, "b": 13}}
{"id": 4, "method": "scan", "params": {"entry_id": 12}}

Wire agentburp into Claude Desktop, Cursor, or any MCP client by adding it to your MCP configuration:

{
  "mcpServers": {
    "agentburp": {
      "command": "/path/to/agentburp",
      "args": ["mcp-serve", "--scope", "/path/to/scope.yml"]
    }
  }
}

---

Architecture

flowchart TD
    CLIENT["Target Traffic / Browser / Client"] --> PROXY["agentburp Intercepting Proxy"]
    PROXY --> GUARD["Scope Guard & Rate Limiter<br/>(scope.yml)"]
    GUARD -- "In-Scope" --> TARGET["Authorized Target Host"]
    TARGET --> PROXY
    PROXY -- "Store Req/Resp" --> DB[("SQLite Database<br/>~/.agentburp/history.db")]

    DB --> HIST["History Filter & Search"]
    DB --> REP["Repeater Engine"]
    DB --> FUZZ["Intruder / Fuzzer Engine"]
    DB --> DIFF["Diffing Engine"]
    DB --> SCAN["Heuristic Scanner"]

    SCAN --> REPORT["PoC Report Generator<br/>HackerOne · Bugcrowd · Markdown"]
    
    REP --> MCP["MCP Server (JSON-RPC stdio)"]
    FUZZ --> MCP
    HIST --> MCP
    SCAN --> MCP
    DIFF --> MCP
    MCP --> AGENT["AI Agents<br/>Claude · Cursor · Autonomous Scripts"]

---

Safety Rails & Scope Guard

1. Default-Deny Policy: Nothing is proxied, repeated, fuzzed, or scanned unless the host matches an entry in allow_hosts.
2. Deny Overrides: deny_hosts always overrides allow rules (useful for blacklisting sensitive payment or auth endpoints).
3. Safe Mode: Enabled by default in scope.yml. Blocks active attacks and fuzzing unless explicitly invoked with --confirm.
4. Audit Trail: Every active scan and fuzz operation is timestamped and recorded in the SQLite audit_log table with explicit reason metadata.
5. Rate Limiting: Built-in token bucket ensures requests never exceed the specified rate_limit_per_sec.

---

Roadmap

• Full HTTPS MITM with auto-generated and installable CA certificates
• GraphQL-aware query parsing and mutation fuzzing
• Built-in OOB Collaborator (DNS/HTTP callback listener for blind SSRF/XXE)
• Secrets and credential leak detector for response bodies & JS bundles
• Autonomous crawler/spider for sitemaps, robots.txt, and endpoints
• WAF & rate-limit auto-detection with exponential backoff

---

Common Questions

Can an AI agent run agentburp completely autonomously?

Yes. All commands output standard JSON, and mcp-serve implements a stdio JSON-RPC interface designed specifically for agents like Claude or custom LLM frameworks to execute scans, analyze responses, and replay attacks without human intervention.

How does agentburp isolate different penetration tests?

Via workspaces (agentburp workspace use <name>). Each workspace segments traffic, history, findings, and audit logs so multi-target testing never cross-contaminates data.

Does agentburp require Burp Suite to be installed?

No. agentburp is completely standalone, written in Go with an embedded SQLite engine. It has zero dependency on Burp Suite or Java.

---

Author & License

Developed with ❤️ by JOJIN JOHN

This project is open-source software provided under the MIT License.

Disclaimer: Use responsibly and only against systems you are explicitly authorized to test. The author assumes no liability for unauthorized or illegal use of this software.