Reaper MITM Proxy

Reaper is a CLI-based MITM HTTPS proxy for application security testing. It intercepts, logs, and allows inspection of HTTP/HTTPS traffic flowing through it. Use it to capture live request/response pairs for security validation.

Prerequisites

Before using any reaper command, make sure the latest version of the binary is installed:

curl -sfL https://raw.githubusercontent.com/ghostsecurity/reaper/main/scripts/install.sh | bash

All reaper commands in this document should be invoked as ~/.ghost/bin/reaper unless ~/.ghost/bin is on PATH .

Quick Reference

Command Purpose

reaper start --domains example.com

Start proxy (foreground)

reaper start --domains example.com -d

Start proxy (daemon)

reaper logs

Show recent captured entries

reaper search --method POST --path /api/*

Search captured traffic

reaper get <id>

Show full request + response

reaper req <id>

Show raw HTTP request only

reaper res <id>

Show raw HTTP response only

reaper stop

Stop the daemon

Starting the Proxy

Start reaper scoped to the target domain(s). At least one --domains or --hosts flag is required.

Intercept all traffic to example.com and its subdomains

reaper start --domains example.com

Multiple domains

reaper start --domains example.com,api.internal.co

Exact hostname matching

reaper start --hosts api.example.com

Both domain suffix and exact host matching

reaper start --domains example.com --hosts special.internal.co

Custom port (default: 8443)

reaper start --domains example.com --port 9090

Run as background daemon

reaper start --domains example.com -d

Scope behavior:

• --domains : Suffix match. example.com matches example.com , api.example.com , sub.api.example.com

• --hosts : Exact match. api.example.com matches only api.example.com

• Traffic outside scope passes through transparently without logging

Routing Traffic Through the Proxy

Configure the HTTP client to use the proxy. The default listen address is localhost:8443 .

curl

curl -x http://localhost:8443 -k https://api.example.com/endpoint

Environment variables (works with many tools)

export http_proxy=http://localhost:8443 export https_proxy=http://localhost:8443

Python requests

import requests requests.get("https://api.example.com/endpoint", proxies={"http": "http://localhost:8443", "https": "http://localhost:8443"}, verify=False)

The -k / verify=False flag is needed because reaper generates its own CA certificate at startup for MITM TLS interception.

Viewing Captured Traffic

Recent Entries

Show last 50 entries (default)

reaper logs

Show last 200 entries

reaper logs -n 200

Output columns: ID , METHOD , HOST , PATH , STATUS , MS , REQ (request body size), RES (response body size).

Searching

By HTTP method

reaper search --method POST

By host (supports * wildcard)

reaper search --host *.api.example.com

By domain suffix

reaper search --domains example.com

By path prefix (supports * wildcard)

reaper search --path /api/v3/transfer

By status code

reaper search --status 200

Combined filters

reaper search --method POST --path /api/v3/* --status 200 -n 50

Inspecting Individual Entries

Full request and response (raw HTTP)

reaper get 42

Request only

reaper req 42

Response only

reaper res 42

Output is raw HTTP/1.1 format including headers and body, suitable for analysis or replay.

Stopping the Proxy

reaper stop

Common Workflows

Validate a Security Finding

When used with the validate skill (may need to collaborate with the user to setup the test environment):

• Start reaper scoped to the application domain

• Verify traffic is being captured by running reaper logs — at least one entry should appear after routing a test request through the proxy

• If no entries appear, verify proxy settings and domain scope match the target

• Authenticate (or ask the user to authenticate) as a normal user and exercise the vulnerable endpoint legitimately

• Search for the captured request to understand the expected request format

• Craft and send a malicious request that exercises the exploit described in the finding

• Inspect the response to determine if the exploit succeeded

• Use reaper get <id> to capture the full request/response as evidence

Data Storage

All data is stored in ~/.reaper/ :

• reaper.db

• SQLite database with captured entries

• reaper.sock

• Unix socket for CLI-to-daemon IPC

• reaper.pid

• Daemon process ID

The CA certificate is generated fresh in memory on each start and is not persisted.