Python Scripting

RelayCraft allows you to extend its functionality using Python scripts. These scripts are standard mitmproxy addons, giving you full control over the traffic interception process.

Managing Scripts

The Script Manager allows you to create, edit, and toggle scripts.

1. Create: Click the + button to create a new script.
2. Edit: Use the built-in editor to write your Python code.
3. Enable/Disable: Toggle scripts on or off using the switch next to the script name.
4. Restart: Because scripts are loaded into the core engine, you must restart the proxy for any changes (edits or toggles) to take effect. RelayCraft will prompt you when a restart is needed.

Writing Scripts

Scripts in RelayCraft follow the standard mitmproxy addon structure.

Basic Structure

A basic script looks like this:

from mitmproxy import http

class Addon:
    def request(self, flow: http.HTTPFlow):
        # Called when a client request is received
        if "example.com" in flow.request.pretty_host:
            flow.request.headers["X-Custom-Header"] = "RelayCraft"

    def response(self, flow: http.HTTPFlow):
        # Called when a server response is received
        if flow.response.status_code == 404:
            flow.response.status_code = 200
            flow.response.text = "Fixed by RelayCraft!"

addons = [Addon()]

Key Events

• request(flow): Modify the request before it is sent to the server.
• response(flow): Modify the response before it is returned to the client.
• error(flow): Handle connection errors.

AI Script Assistant

RelayCraft includes an AI Script Assistant to help you write code.

1. Open the Script Editor.
2. Click the AI button or use the Command Center.
3. Describe what you want to do (e.g., “Modify all JSON responses from api.test.com to add a ‘debug’: true field”).
4. The AI will generate the Python code for you.

Examples

1. Log Requests to File

from mitmproxy import http

class Logger:
    def request(self, flow: http.HTTPFlow):
        with open("/tmp/requests.log", "a") as f:
            f.write(f"{flow.request.method} {flow.request.url}\n")

addons = [Logger()]

2. Random Delay (Chaos Engineering)

import time
import random
from mitmproxy import http

class RandomDelay:
    def request(self, flow: http.HTTPFlow):
        if random.random() < 0.3: # 30% chance
            time.sleep(2) # Delay for 2 seconds

addons = [RandomDelay()]