Crate soth_mitm 

soth-mitm

Rust intercepting proxy crate with deterministic handler/event contracts.

soth-mitm provides a MITM (man-in-the-middle) proxy that intercepts HTTP/1.1, HTTP/2, WebSocket, gRPC, and SSE traffic over TLS. It exposes a trait-based handler API that lets you inspect, allow, or block requests in real time.

Quick Start

use bytes::Bytes;
use soth_mitm::{
    HandlerDecision, InterceptHandler, MitmConfig, MitmProxyBuilder, RawRequest,
};

struct MyHandler;

impl InterceptHandler for MyHandler {
    async fn on_request(&self, request: &RawRequest) -> HandlerDecision {
        if request.path.contains("/blocked") {
            return HandlerDecision::Block {
                status: 403,
                body: Bytes::from_static(b"blocked"),
            };
        }
        HandlerDecision::Allow
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = MitmConfig::default();
    config
        .interception
        .destinations
        .push("api.example.com:443".to_string());

    let _proxy = MitmProxyBuilder::new(config, MyHandler).build()?;
    Ok(())
}

Feature Flags

Flag	Default	Description
openssl-backend	off	Enables OpenSSL-based CA material validation on cert load
__internal	off	Exposes internal modules for integration tests — not stable API

Minimum Supported Rust Version

This crate requires Rust 1.88 or later.

License

Licensed under the Mozilla Public License 2.0.

Structs

BodyConfig

Bytes

A cheaply cloneable and sliceable chunk of contiguous memory.

CertificateAuthority

A certificate authority used for TLS interception.

ConnectionMeta

Metadata about the downstream connection (socket, TLS, process attribution).

ConnectionPoolConfig

FlowId

Newtype wrapping a u64 flow identifier for type-safe flow tracking.

FlowRuntimeConfig

HandlerConfig

HeaderMap

A specialized multimap for header names and values.

InterceptionScope

MitmConfig

Top-level proxy configuration.

MitmProxy

The intercepting proxy instance, ready to run or start as a background task.

MitmProxyBuilder

Builder for constructing a MitmProxy instance.

MitmProxyHandle

Handle to a running proxy, providing shutdown, config reload, and metrics access.

ProcessAttributionConfig

ProcessInfo

Information about the local process that owns the downstream socket.

ProxyMetrics

Point-in-time snapshot of proxy operational metrics.

RawRequest

An intercepted HTTP request passed to the handler.

RawResponse

An intercepted HTTP response passed to the handler.

StreamChunk

A streaming data frame (SSE, NDJSON, gRPC, or WebSocket) delivered to the handler.

TlsConfig

TlsInfo

TLS metadata for the downstream connection.

UpstreamConfig

Uuid

A Universally Unique Identifier (UUID).

Enums

CaError

Error returned by certificate authority operations (generate, load, trust install).

FrameDirection

Direction of a WebSocket frame.

FrameKind

Discriminant for streaming frame types delivered via StreamChunk.

H2ResponseOverflowMode

HandlerDecision

Decision returned by InterceptHandler::on_request.

InterceptMode

Controls whether the proxy runs in observe-only or store-and-forward mode.

MitmError

Top-level error returned by proxy lifecycle operations.

SocketFamily

Socket address family for the downstream connection.

TlsVersion

TLS protocol version.

Traits

InterceptHandler

Trait for intercepting and inspecting proxy traffic.

Functions

generate_ca

Generates a new self-signed CA keypair for TLS interception.

install_ca_system_trust

Installs the CA into the system trust store (platform-specific).

is_ca_trusted

Checks whether a CA with the given fingerprint is installed in the system trust store.

load_ca

Loads a CA from in-memory PEM-encoded certificate and key bytes.

load_ca_from_files

Loads a CA from PEM files on disk.

uninstall_ca_system_trust

Removes the soth-mitm CA from the system trust store.