soth-mitm 0.1.0

Rust intercepting proxy crate with deterministic handler/event contracts for SOTH.
Documentation

soth-mitm

Public Rust crate for the SOTH intercepting proxy contract.

What You Get

  • Stable handler decisions: Allow / Block { status, body }
  • Deterministic request/response/stream contracts:
    • RawRequest
    • RawResponse
    • StreamChunk
    • ConnectionMeta
  • Proxy lifecycle APIs:
    • MitmProxyBuilder
    • MitmProxy
    • MitmProxyHandle (reload, current_config, metrics, shutdown)
  • TLS CA helpers:
    • generate_ca, load_ca, load_ca_from_files
    • trust install/uninstall/check helpers
  • Runtime metrics snapshot API (ProxyMetrics)

Scope Boundary

soth-mitm is transport/proxy core. Product-specific bundle logic or provider semantics are intentionally outside this crate.

Minimal Integration Example

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

struct ForwardOnly;

impl InterceptHandler for ForwardOnly {
    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, ForwardOnly).build()?;
    Ok(())
}

Compilable example:

  • crates/soth-mitm/examples/soth_proxy_integration.rs

Key Types

  • Config:
    • MitmConfig, InterceptionScope, ProcessAttributionConfig, TlsConfig
    • UpstreamConfig, ConnectionPoolConfig, BodyConfig, HandlerConfig
  • Runtime metadata:
    • ConnectionMeta, SocketFamily, ProcessInfo, TlsInfo, TlsVersion
  • Runtime streams:
    • FrameKind::{SseData, NdjsonLine, GrpcMessage, WebSocketText, WebSocketBinary, WebSocketClose}

Note: All public config structs are marked #[non_exhaustive] — construct them via Default::default() and field assignment rather than struct literal syntax to remain forward-compatible.

Feature Flags

Flag Default Description
openssl-backend off Enables OpenSSL-based CA material cross-validation when loading certificates from disk. On non-Windows platforms the OpenSSL crate is always present for downstream TLS fingerprinting, but this feature activates the CA validation code path.
__internal off Exposes internal sub-crate modules (test_engine, test_policy, etc.) for integration tests and benchmarks. Not part of the stable API.

Minimum Supported Rust Version

This crate requires Rust 1.88 or later (rust-version = "1.88" in Cargo.toml).

License

Licensed under the Mozilla Public License 2.0. See LICENSE for the full text.

Repository