mitmproxy_rules

Description

This project aims to centralize and organize custom rules for use with mitmproxy, a powerful tool for intercepting, inspecting, modifying, and replaying HTTP(S) traffic.

Key Features:

• Project-based Grouping: Organize rules into different projects.
• SQLite Storage: Rules are stored in a local SQLite database for persistence and easy management.
• Clone Feature: Quickly duplicate projects and their rules.
• Real-time Interception: Automate request and response manipulations for testing and debugging.

Screenshots

Home	New Rule

Edit Rule	New Project

Installation

1. Clone the repository:

   git clone git@github.com:ViniciusAlberkovics/mitmproxy_rules.git
   cd mitmproxy_rules

2. Install uv (if not already installed):

   pip install uv

3. Install project dependencies using uv and pyproject.toml:

   uv pip install -r pyproject.toml

   Or, to install in editable/development mode:

   uv pip install -e .

   Note: This project uses the uv project structure with pyproject.toml and uv.lock for dependency management. There is no requirements.txt.

4. Install mitmproxy:

   Follow the official instructions at mitmproxy installation guide.

Running the Project

You can run each component separately. Use the provided Makefile for convenience.

1. Run the mitmproxy Addon

This will start mitmweb with the custom interceptor addon and load rules from the SQLite database:

make addon

Or manually:

DB_FILE=$(pwd)/rules.db mitmweb -s addon/interceptor.py --listen-port 9000

2. Run the Backend API

This will start the FastAPI backend for managing rules:

make backend

Or manually:

DB_FILE=$(pwd)/rules.db uv run -- fastapi dev backend/api_server.py

3. Run the Frontend

This will start a simple HTTP server to serve the frontend:

make frontend

Or manually:

python -m http.server 8001 --directory frontend

Project Structure

mitmproxy_rules/
├── addon/         # Addon scripts for mitmproxy (automate the rules)
├── backend/       # Backend API to manage rules (FastAPI)
├── frontend/      # Web interface to create/edit rules
├── shared/        # Utilities shared between backend and addon
├── rules.db       # SQLite database containing projects and rules
├── README.md      # Main project documentation

Purpose of Each Folder

• addon/: Contains scripts that are loaded as addons in mitmproxy, applying the defined rules to intercepted traffic.
• backend/: Implements an API (using FastAPI) for reading, writing, and editing rules, facilitating integration with the frontend.
• frontend/: Web interface for viewing, creating, and editing rules in a user-friendly way.
• shared/: Utility functions and modules shared between the backend and addon, such as database interaction.
• README.md: This documentation file.