MockMini: building a small, fuzzed proxy core for macOS in ~2,600 lines

#opensource #macos #networking #swift

MockMini is a small, auditable proxy core in C and Swift. It speaks Shadowsocks AEAD, VMess, Trojan and VLESS over TCP, TLS or WebSocket, on top of its own bounded userspace TCP/IP endpoint. It is about 2,600 lines, fuzzed, and licensed under Apache-2.0. v0.1.0 is the first tagged release.

Repo: https://github.com/yezicheng2011/mockmini · Site: https://mockmini.com/

Why write one from scratch

Most proxy apps ship a large third-party kernel such as mihomo, Clash or sing-box, often with a Go runtime. MockMini is deliberately different: no vendored proxy kernel, no third-party TCP/IP stack, no Go runtime, and it is not based on mihomo, Clash, sing-box, gVisor or WireGuard. The goal is a core small enough that one person can read and review all of it.

Protocols and transports


Protocols	Shadowsocks AEAD (aes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305), VMess (legacy + AEAD), Trojan (TCP and UDP), VLESS (TCP and UDP)
Transports	TCP, TLS, WebSocket (RFC 6455)
Packet engine	IPv4/IPv6 TCP + UDP, fragment reassembly, up to 1024 flows; portable C
Platforms	macOS 13+ (Network.framework, CryptoKit); the packet engine builds anywhere

A layered design

Each connection is a stack of independent layers: protocol (ProxySession), framing (raw or WebSocket), security (none or system TLS) and dial (TCP or UDP). A new protocol is a new ProxySession; a new transport is a new plan case. The portable core also builds on Linux with swift-crypto.

Embedding

#include "wlp.h"

wlp_callbacks cb = { on_connect, on_data, on_close, on_packet, on_eof };
wlp_engine *engine = wlp_new(cb, ctx);

wlp_tick(engine, now_ms());                 // then at least every 100 ms
wlp_input(engine, ip_packet, length);       // raw IP packet from your tun device
wlp_remote_open(engine, flow);
wlp_remote_data(engine, flow, bytes, n);    // upstream -> client

Or add it with Swift Package Manager:

.package(url: "https://github.com/yezicheng2011/mockmini.git", branch: "main")
// products: "MockMiniPacket" (C packet engine), "MockMiniVPN" (protocols and transports)

Testing

A stateful, checksum-aware fuzzer builds valid traffic so it reaches the TCP state machine, reassembly, fragment cache and flow limit, with about 99% line coverage of the packet engine, and checks byte-exact in-order delivery on every run. CI runs it on Linux (gcc and clang) under ASan/UBSan, as a libFuzzer smoke test, and on macOS with the Swift protocol tests. On macOS CI, a pinned, checksum-verified Xray release serves every supported protocol on loopback and MockMini pushes verified TCP streams and UDP datagrams through each one.

Known limits (honest)

The packet engine is a small TCP/UDP proxy endpoint, not a general IP stack: up to 1024 concurrent flows; MSS and window scaling only (no SACK, timestamps or ECN); no ICMP or PMTUD. There is no gRPC transport, no Reality or uTLS fingerprinting, and no VLESS flow control yet. Throughput is still behind mature kernels; that gap is expected while MockMini stays original and small.

Try it

MockMini is young and actively developed. Reviews, issues and pull requests are very welcome: https://github.com/yezicheng2011/mockmini

DEV Community