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).

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.