Compare commits

...
11 changed files with 1948 additions and 44 deletions
+1
View File
@@ -23,6 +23,7 @@ All notable changes to this project are documented in this file. The format is b
- **`ask_operator` target warning**: a request whose question names a host or URL outside the goal targets is tagged as containing target-derived text (#197).
- **Opt-in update banner**: `ARTEX_UPDATE_CHECK` makes the backend check the latest GitHub release at most once per 24 hours and the UI show a banner; off by default (#202).
- **Release provenance**: release archives carry GitHub build provenance attestations and a CycloneDX SBOM (`gh attestation verify <zip> --repo BaaRai/ARTEX`); release notes are the matching `CHANGELOG.md` section (#219, #201).
- **Opt-in SOCKS5 UDP ASSOCIATE & raw UDP recording (P4.1c)**: when traffic capture is enabled, setting `ARTEX_SOCKS5_UDP_ENABLED=1` enables RFC 1928 `UDP ASSOCIATE` (`0x03`, IPv4 first) on the SOCKS5 listener (off by default: with flags off no listener starts; with SOCKS5 TCP on and UDP off, `UDP ASSOCIATE` returns `0x07` and no UDP socket is opened). Enforces per-datagram destination policy before forwarding using the existing target gate (`intercept.Interceptor.ResolveUDP4` / `intercept.PinnedUDP4Resolver`) and egress governor (`egress.Do`), dropping denied datagrams without passthrough; bounds associations (`UDPMaxDatagrams`, `UDPMaxBytes`, `UDPIdleTimeout`) and tears them down with the TCP control connection; drops `FRAG != 0` with no fragmentation reassembly; and records each forwarded datagram individually in SQLite `raw_udp_datagrams` with capped previews and atomic `_blobs` refs without writing HTTP `exchanges` rows or PG migrations. Transparent UDP (`IP_RECVORIGDSTADDR`) is deferred to C2. See `docs/traffic-socks5-udp.md`.
- **Opt-in Linux transparent TCP inbound & raw TCP recording (P4.1b)**: on Linux when traffic capture is enabled, setting `ARTEX_TRANSPARENT_TCP_ENABLED=1` (loopback `127.0.0.1:1081` by default) or `ARTEX_TRANSPARENT_TCP_ADDR=<ipv4:port>` starts an IPv4 transparent TCP listener fed by operator-managed `iptables`/`nftables` `REDIRECT` rules (off by default; ARTEX never touches the host firewall; root/`CAP_NET_ADMIN` is required only for the operator's redirect rules; IPv6 is not covered). Recovers original IPv4 destinations via `SO_ORIGINAL_DST` with self-redirect loop protection, reuses the P4.1a target gate (`intercept.Interceptor.DialSOCKS5`), egress governor (`egress.Do`), half-close relay bounds, and SQLite `raw_tcp_streams` store (atomic `_blobs` spill, no HTTP `exchanges` row, no PostgreSQL migration). See `docs/traffic-transparent.md`.
- **Opt-in SOCKS5 inbound proxy & raw TCP recording (P4.1a)**: when traffic capture is enabled, setting `ARTEX_SOCKS5_ENABLED=1` (loopback `127.0.0.1:1080` by default) or `ARTEX_SOCKS5_ADDR=<addr>` starts an RFC 1928 SOCKS5 `CONNECT` listener alongside the HTTP recording proxy (off by default; HTTP proxy and agent proxy env vars are unchanged; listener does not start if traffic recording is disabled). Accepts loopback no-auth and RFC 1929 username/password without verifying credentials (carrying `artex-pace` in the username; binding to a non-loopback address therefore exposes an unauthenticated proxy, though the target gate and governor still apply), rejects `BIND`/`UDP ASSOCIATE` with `0x07`, enforces the existing target gate (`intercept.Interceptor.DialSOCKS5` / `intercept.PinnedDialer`) and egress governor (`egress.Do`) before dialing, relays half-close-aware TCP with concurrency/byte/idle/handshake bounds, and records one row per connection in SQLite `raw_tcp_streams` with capped directional previews and atomic (temp+rename) `_blobs` refs without writing HTTP `exchanges` rows. See `docs/traffic-socks5.md`.
- **Opt-in worker cache-prefix split (P3.5 Phase C)**: setting `ARTEX_CACHE_PREFIX=1` (off by default) splits the `worker` system prompt at `DynamicBoundary = 1` into a sibling-shareable static prefix (`body + untrustedContentTail + workerTrafficBlock`) and a per-intent dynamic suffix (`workerArtifactSpec(runDir)` through `<available-deferred-tools>`) without reordering sections or altering the visible joined prompt text. Planner, mainagent, chat, and goals are unchanged; custom worker prompts referencing `{{.Now}}` remain volatile in the static segment. See `docs/context-telemetry.md`.
+63
View File
@@ -0,0 +1,63 @@
# Opt-in SOCKS5 UDP ASSOCIATE & Raw UDP Recording (P4.1c)
ARTEX extends the opt-in SOCKS5 inbound listener with **RFC 1928 `UDP ASSOCIATE` (`0x03`)**, **IPv4 first**, enforcing per-datagram destination policy and recording forwarded datagrams separately from HTTP traffic in SQLite. Transparent UDP (`IP_RECVORIGDSTADDR`) is out of scope here and planned separately (C2).
## Opt-in Configuration (Off by Default)
| Environment Variable | Default | Behavior |
|---|---|---|
| `ARTEX_SOCKS5_UDP_ENABLED` | unset (off) | Set to `1` / `true` / `on` / `yes` to enable RFC 1928 `UDP ASSOCIATE` on the SOCKS5 listener (starting the SOCKS5 listener on `ARTEX_SOCKS5_ADDR` or `127.0.0.1:1080` unless `ARTEX_SOCKS5_ENABLED` is explicitly `0`/`false`/`off`/`no`). |
| `ARTEX_SOCKS5_ENABLED` | unset (off) | Explicit `0` / `false` / `off` / `no` disables the entire SOCKS5 listener (TCP and UDP) even if `ARTEX_SOCKS5_UDP_ENABLED` is set. |
| `ARTEX_SOCKS5_ADDR` | `127.0.0.1:1080` | Bind address for the SOCKS5 TCP control listener; per-association IPv4 UDP relay sockets bind on the same local IPv4 interface on an ephemeral port (`:0`). |
- **Flag off means no listener**:
- With all SOCKS5 flags unset/off, no SOCKS5 listener and no UDP relay socket are started.
- With SOCKS5 TCP enabled and `ARTEX_SOCKS5_UDP_ENABLED` off, `UDP ASSOCIATE` (`0x03`) is refused with RFC 1928 reply `0x07` (*Command not supported*) and no UDP socket is opened.
- **Requires traffic recorder**: like P4.1a and P4.1b, the server only starts the SOCKS5 listener when the traffic recorder is enabled (inside the traffic proxy block in `server/manager.go`).
- **Non-loopback warning**: the same authentication caveat from [docs/traffic-socks5.md](traffic-socks5.md) applies—RFC 1929 username/password accepts any credentials, so keep the listener bound to loopback (`127.0.0.1`) or restrict access at the host firewall.
## Protocol Scope & Lifetime
- **IPv4 first**:
- `UDP ASSOCIATE` accepts IPv4 (`0x01`) and domain (`0x03`) requests (including `0.0.0.0:0` per RFC 1928 §4). IPv6 (`0x04`) `UDP ASSOCIATE` requests return `0x08` (*Address type not supported*); IPv6 UDP datagram destinations are dropped.
- Each client UDP datagram header (`RSV=0x0000`, `FRAG=0x00`, `ATYP=0x01` IPv4 or `ATYP=0x03` domain resolved to IPv4) is parsed individually.
- **No fragmentation reassembly**:
- Per RFC 1928 §7, datagrams with `FRAG != 0` are dropped without reassembly.
- Each forwarded `FRAG == 0` datagram (and each upstream reply datagram) is recorded as it arrives without cross-datagram reassembly.
- **Client source pinning**:
- Incoming client UDP datagrams on the ephemeral relay port are accepted only from the expected IPv4 client address (the `DST.ADDR`/`DST.PORT` given in `UDP ASSOCIATE`, or the TCP control connection's peer IP pinned on the first valid datagram).
- Upstream reply datagrams are accepted only from destinations (`ip:port`) to which the association previously forwarded an allowed datagram.
- **Tied to the TCP control connection**:
- Closing the SOCKS5 TCP control connection immediately closes both UDP sockets and terminates the association.
- Exceeding `UDPIdleTimeout`, `UDPMaxDatagrams`, or `UDPMaxBytes`, or calling `Traffic.Close()`, also closes the association and its TCP control connection cleanly.
## Policy Enforcement Per Datagram Destination
Before forwarding **every** client-to-server UDP datagram to `(host, port)`:
1. **Target gate (`intercept.Interceptor.ResolveUDP4` / `intercept.PinnedUDP4Resolver`)**: enforces global asset block rules (domain, IP, and CIDR, before and after fresh IPv4 DNS resolution) and any enabled `intercept.TargetScope` pins/exemptions, returning the verified IPv4 `*net.UDPAddr`.
2. **Egress governor (`egress.Do(egress.Current(), ...)`)**: enforces the active noise profile (`PaceTimeout`, default `30s`) before sending.
3. **Fail-closed drop (no silent passthrough)**: any datagram whose destination is denied by the target gate, fails DNS/IPv4 resolution, or is refused by the egress governor is **dropped** without sending bytes upstream and without recording a forwarded datagram. Subsequent allowed datagrams on the same association continue normally.
## Raw UDP Storage (SQLite)
Each forwarded datagram writes one row to the `raw_udp_datagrams` table in the SQLite traffic index (`traffic/traffic.go`, `indexSchema` — no PostgreSQL migration):
- Columns: `id` (`udp-<ms>-<seq>`), `association_id` (`udpa-<ms>-<seq>`), `protocol` (`'udp'`), `host`, `port`, `direction` (`'c2s'` | `'s2c'`), `ts` (unix milliseconds), `size`, `preview`, `blob`.
- **No HTTP exchange row**: raw UDP datagrams never insert into `exchanges`.
- **Preview & atomic blob spilling**:
- Payloads up to `UDPPreviewBytes` (default `8 KiB`) stay inline in `preview`.
- Payloads above `UDPPreviewBytes` keep the leading `UDPPreviewBytes` inline and spill the full datagram payload atomically (temp file + rename) into `_blobs/sha256/` with a reference registered in `blob_refs` under the datagram's `udp-*` ID.
## Operational Bounds
| Parameter | Default |
|---|---|
| `MaxConcurrent` | `64` active TCP streams + UDP associations combined |
| `UDPMaxDatagrams` | `1000` forwarded datagrams (`c2s` + `s2c`) per association |
| `UDPMaxBytes` | `4 MiB` forwarded payload bytes (`c2s` + `s2c`) per association |
| `UDPPreviewBytes` | `8 KiB` inline preview per datagram before blob spill |
| `UDPIdleTimeout` | `2m` inactivity timeout per association |
| `HandshakeTimeout` | `10s` for greeting, auth, and `UDP ASSOCIATE` request |
| `DialTimeout` | `30s` per-datagram target gate / DNS lookup bound |
| `PaceTimeout` | `30s` per-datagram egress governor wait bound |
+1 -1
View File
@@ -16,7 +16,7 @@ ARTEX ships an opt-in **RFC 1928 SOCKS5 `CONNECT`** inbound listener in `traffic
## Protocol Scope (P4.1a)
- **Commands**: `CONNECT` (`0x01`) only. `BIND` (`0x02`), `UDP ASSOCIATE` (`0x03`, planned for P4.1c), and unknown commands return RFC 1928 reply `0x07` (*Command not supported*).
- **Commands**: `CONNECT` (`0x01`) by default. `BIND` (`0x02`) and unknown commands return RFC 1928 reply `0x07` (*Command not supported*). `UDP ASSOCIATE` (`0x03`) also returns `0x07` unless `ARTEX_SOCKS5_UDP_ENABLED=1` is set (see [docs/traffic-socks5-udp.md](traffic-socks5-udp.md)).
- **Addressing**: IPv4 (`0x01`), domain name (`0x03`), and IPv6 (`0x04`). Unknown address types return `0x08` (*Address type not supported*).
- **Authentication**:
- Loopback peers (`net.IP.IsLoopback()`) may connect with **No Auth** (`0x00`). Non-loopback peers offering only `0x00` are rejected with `0x05 0xFF`.
+138 -2
View File
@@ -116,9 +116,9 @@ func (i *Interceptor) dialTarget(ctx context.Context, scope TargetScope, toolNam
// the URL.
func addrTarget(network, addr string) (Target, error) {
switch network {
case "tcp", "tcp4", "tcp6":
case "tcp", "tcp4", "tcp6", "udp", "udp4", "udp6":
default:
return Target{}, fmt.Errorf("network %q is not tcp", network)
return Target{}, fmt.Errorf("network %q is not tcp or udp", network)
}
host, port, err := net.SplitHostPort(addr)
if err != nil {
@@ -237,3 +237,139 @@ func (i *Interceptor) DialSOCKS5(ctx context.Context, network, addr string) (net
}
return i.dialAddrs(ctx, network, ct.ips, t.Port)
}
// PinnedUDP4Resolver returns a per-datagram IPv4 destination resolver that
// enforces the platform's target gate identically to PinnedDialer. When scoped
// is true, a missing or incomplete TargetScope fails closed with
// TARGET_GATE_UNAVAILABLE.
func PinnedUDP4Resolver(toolName string, scoped bool) func(ctx context.Context, addr string) (*net.UDPAddr, error) {
return func(ctx context.Context, addr string) (*net.UDPAddr, error) {
scope, ok := TargetScopeFromContext(ctx)
switch {
case !ok && scoped:
return nil, &dialError{code: TargetGateUnavailable, target: addr, reason: "the target scope of the session did not reach the connection"}
case !ok:
return resolvePlainUDP4(ctx, addr)
case scope.Enabled == nil || !scope.Enabled():
if scope.Interceptor != nil {
return scope.Interceptor.ResolveUDP4(ctx, addr)
}
return resolvePlainUDP4(ctx, addr)
case scope.Interceptor == nil:
return nil, &dialError{code: TargetGateUnavailable, target: addr, reason: "the session's target scope carries no gate"}
}
return scope.Interceptor.resolveTargetUDP4(ctx, scope, toolName, addr)
}
}
// ResolveUDP4 enforces the platform's target gate before forwarding a SOCKS5
// UDP ASSOCIATE datagram, reusing the exact same asset block rules, fresh DNS
// resolution, and TargetScope pin/exemption logic as DialSOCKS5 / PinnedDialer.
// Returns the first verified IPv4 *net.UDPAddr.
func (i *Interceptor) ResolveUDP4(ctx context.Context, addr string) (*net.UDPAddr, error) {
if i == nil {
return resolvePlainUDP4(ctx, addr)
}
if scope, ok := TargetScopeFromContext(ctx); ok && scope.Enabled != nil && scope.Enabled() {
return i.resolveTargetUDP4(ctx, scope, "socks5-udp", addr)
}
t, err := addrTarget("udp4", addr)
if err != nil {
return nil, &dialError{code: TargetGateUnavailable, target: addr, reason: "the address of the datagram could not be read (" + err.Error() + ")"}
}
if i.targets == nil {
return resolvePlainUDP4(ctx, addr)
}
rules, err := i.targets.BlockRules(db.TargetScopeRef{})
if err != nil {
return nil, &dialError{code: TargetGateUnavailable, target: t.String(), reason: "the asset rules could not be read: " + err.Error()}
}
ct := &checkedTarget{Target: t}
if t.Kind != TargetDomain {
ct.ips, ct.resolver, ct.resolvedAt = []string{t.Host}, literalResolver, time.Now().UTC()
}
if rule, hit := blockRule(rules, ct); hit {
return nil, &dialError{code: TargetRuleBlocked, target: t.String(), reason: fmt.Sprintf("%s is blocked by an asset rule. %s", t, rule.Reason())}
}
if t.Kind == TargetDomain {
c := &targetCheck{i: i, ctx: ctx, tool: "socks5-udp", fresh: true}
c.resolve(ct, true)
if ct.err != nil {
return nil, ct.err
}
if rule, hit := blockRule(rules, ct); hit {
return nil, &dialError{code: TargetRuleBlocked, target: t.String(), reason: fmt.Sprintf("%s is blocked by an asset rule. %s", t, rule.Reason())}
}
}
return firstIPv4UDPAddr(ct.ips, t.Port)
}
func (i *Interceptor) resolveTargetUDP4(ctx context.Context, scope TargetScope, toolName, addr string) (*net.UDPAddr, error) {
input, _ := json.Marshal(map[string]string{"udp": addr})
ctx = WithCall(ctx, toolName, input)
t, err := addrTarget("udp4", addr)
if err != nil {
res := undeterminedTarget(ctx, scope, toolName, input, "the address of the datagram could not be read ("+err.Error()+")")
return nil, &dialError{code: res.Code, target: addr, reason: res.Reason}
}
blocked := func(res TargetResult) error {
return &dialError{code: res.Code, target: t.String(), reason: res.Reason}
}
c := &targetCheck{i: i, ctx: ctx, scope: scope, tool: toolName, input: input, fresh: true}
unpinned, res := c.run([]Target{t})
if res.Code != "" {
return nil, blocked(res)
}
if len(unpinned) > 0 {
scope.WaitBound = 0
res = i.RequestTargets(ctx, scope, toolName, input, unpinned, nil)
if res.Code == TargetApprovalPending {
res.Reason = notCovered(unpinned[0], scope)
}
return nil, blocked(res)
}
switch ct := c.checked[0]; ct.cover {
case coverDerived, coverNameOnly:
return resolvePlainUDP4(ctx, addr)
default:
return firstIPv4UDPAddr(ct.ips, t.Port)
}
}
func firstIPv4UDPAddr(ips []string, port int) (*net.UDPAddr, error) {
for _, raw := range ips {
a, err := netip.ParseAddr(raw)
if err == nil && a.Is4() {
return &net.UDPAddr{IP: net.IP(a.AsSlice()), Port: port}, nil
}
}
return nil, &net.AddrError{Err: "no IPv4 address found", Addr: strings.Join(ips, ", ")}
}
func resolvePlainUDP4(ctx context.Context, addr string) (*net.UDPAddr, error) {
host, portStr, err := net.SplitHostPort(addr)
if err != nil {
return nil, err
}
port, err := strconv.Atoi(portStr)
if err != nil || port <= 0 || port > 65535 {
return nil, fmt.Errorf("invalid udp port %q", portStr)
}
if ip := net.ParseIP(strings.Trim(host, "[]")); ip != nil {
ip4 := ip.To4()
if ip4 == nil {
return nil, &net.AddrError{Err: "IPv6 UDP destination not supported", Addr: addr}
}
return &net.UDPAddr{IP: ip4, Port: port}, nil
}
ips, err := net.DefaultResolver.LookupIP(ctx, "ip4", host)
if err != nil {
return nil, err
}
for _, ip := range ips {
if ip4 := ip.To4(); ip4 != nil {
return &net.UDPAddr{IP: ip4, Port: port}, nil
}
}
return nil, &net.AddrError{Err: "no IPv4 address found", Addr: addr}
}
+3
View File
@@ -465,8 +465,11 @@ func NewManager(dir, proxyAddr string) (*Manager, error) {
m.reloadRewriteRules() // in place before the proxy accepts a connection
if scfg, ok := traffic.SOCKS5ConfigFromEnv(); ok {
scfg.DialContext = m.interceptor.DialSOCKS5
scfg.ResolveUDP4 = m.interceptor.ResolveUDP4
if bound, serr := tr.StartSOCKS5(scfg); serr != nil {
log.Printf("[traffic/socks5] disabled: %v", serr)
} else if scfg.EnableUDP {
log.Printf("[traffic/socks5] opt-in SOCKS5 CONNECT + UDP ASSOCIATE listener on %s", bound)
} else {
log.Printf("[traffic/socks5] opt-in SOCKS5 CONNECT listener on %s", bound)
}
+180
View File
@@ -0,0 +1,180 @@
package server
import (
"encoding/binary"
"fmt"
"io"
"net"
"sync/atomic"
"testing"
"time"
"github.com/Autumn-27/artex/db"
"github.com/Autumn-27/artex/traffic"
)
func TestManagerSOCKS5UDPOptInAndAssetBlockRuleDropsDatagram(t *testing.T) {
// 1. Both flags off: NO SOCKS5 listener and UDP disabled.
t.Setenv(traffic.SOCKS5EnabledEnv, "")
t.Setenv(traffic.SOCKS5AddrEnv, "")
t.Setenv(traffic.SOCKS5UDPEnabledEnv, "")
mOff, err := NewManager(t.TempDir(), "127.0.0.1:0")
if err != nil {
db.SkipPGUnavailable(t, err)
}
t.Cleanup(func() { _ = mOff.Close() })
if mOff.traffic.SOCKS5Addr() != "" || mOff.traffic.SOCKS5UDPEnabled() {
t.Fatalf("flags off: addr=%q udp=%v, want empty/false", mOff.traffic.SOCKS5Addr(), mOff.traffic.SOCKS5UDPEnabled())
}
// 2. SOCKS5 on with UDP flag off: UDP ASSOCIATE refused with 0x07.
t.Setenv(traffic.SOCKS5AddrEnv, "127.0.0.1:0")
t.Setenv(traffic.SOCKS5UDPEnabledEnv, "")
mTCPOnly, err := NewManager(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = mTCPOnly.Close() })
if mTCPOnly.traffic.SOCKS5UDPEnabled() {
t.Fatal("expected UDP disabled when ARTEX_SOCKS5_UDP_ENABLED is unset")
}
// 3. UDP flag on: listener accepts UDP ASSOCIATE and enforces global asset
// block rules per datagram destination (drop denied, forward allowed).
t.Setenv(traffic.SOCKS5AddrEnv, "127.0.0.1:0")
t.Setenv(traffic.SOCKS5UDPEnabledEnv, "1")
mOn, err := NewManager(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = mOn.Close() })
socksAddr := mOn.traffic.SOCKS5Addr()
if socksAddr == "" || !mOn.traffic.SOCKS5UDPEnabled() {
t.Fatalf("expected SOCKS5+UDP enabled, got addr=%q udp=%v", socksAddr, mOn.traffic.SOCKS5UDPEnabled())
}
// Block 127.0.0.2 via global asset intercept rule; leave 127.0.0.1 allowed.
rule, err := mOn.pg.CreateAssetInterceptRule(
"exact_ip",
"127.0.0.2",
fmt.Sprintf("p41c-udp-block-%d", time.Now().UnixNano()),
true,
)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = mOn.pg.DeleteAssetInterceptRule(rule.ID) })
startEcho := func(bind string) (*net.UDPConn, *atomic.Int32) {
t.Helper()
ua, err := net.ResolveUDPAddr("udp4", bind)
if err != nil {
t.Fatal(err)
}
ln, err := net.ListenUDP("udp4", ua)
if err != nil {
t.Fatal(err)
}
var n atomic.Int32
go func() {
buf := make([]byte, 4096)
for {
rn, from, rerr := ln.ReadFromUDP(buf)
if rerr != nil {
return
}
n.Add(1)
_, _ = ln.WriteToUDP(append([]byte("OK:"), buf[:rn]...), from)
}
}()
t.Cleanup(func() { _ = ln.Close() })
return ln, &n
}
blockedLn, blockedCount := startEcho("127.0.0.2:0")
allowedLn, allowedCount := startEcho("127.0.0.1:0")
blockedAddr := blockedLn.LocalAddr().(*net.UDPAddr)
allowedAddr := allowedLn.LocalAddr().(*net.UDPAddr)
// Open SOCKS5 UDP ASSOCIATE control connection.
ctrl, err := net.DialTimeout("tcp4", socksAddr, 3*time.Second)
if err != nil {
t.Fatal(err)
}
defer ctrl.Close()
_ = ctrl.SetDeadline(time.Now().Add(5 * time.Second))
if _, err := ctrl.Write([]byte{0x05, 0x01, 0x00}); err != nil {
t.Fatal(err)
}
var sel [2]byte
if _, err := io.ReadFull(ctrl, sel[:]); err != nil || sel != [2]byte{0x05, 0x00} {
t.Fatalf("method selection = %v err=%v", sel, err)
}
// CMD=0x03 (UDP ASSOCIATE), ATYP=0x01, 0.0.0.0:0
if _, err := ctrl.Write([]byte{0x05, 0x03, 0x00, 0x01, 0, 0, 0, 0, 0, 0}); err != nil {
t.Fatal(err)
}
var rep [10]byte
if _, err := io.ReadFull(ctrl, rep[:]); err != nil {
t.Fatal(err)
}
if rep[1] != 0x00 {
t.Fatalf("UDP ASSOCIATE rep = 0x%02x, want 0x00", rep[1])
}
relayAddr := &net.UDPAddr{
IP: net.IPv4(rep[4], rep[5], rep[6], rep[7]),
Port: int(binary.BigEndian.Uint16(rep[8:10])),
}
_ = ctrl.SetDeadline(time.Time{})
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
buildPkt := func(dst *net.UDPAddr, msg string) []byte {
p := make([]byte, 10+len(msg))
p[3] = 0x01
copy(p[4:8], dst.IP.To4())
binary.BigEndian.PutUint16(p[8:10], uint16(dst.Port))
copy(p[10:], msg)
return p
}
// Send datagram to blocked 127.0.0.2 (must be dropped by asset rule), then to allowed 127.0.0.1.
_, _ = cliUDP.WriteToUDP(buildPkt(blockedAddr, "blocked-udp"), relayAddr)
_, _ = cliUDP.WriteToUDP(buildPkt(allowedAddr, "allowed-udp"), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
buf := make([]byte, 2048)
rn, _, err := cliUDP.ReadFromUDP(buf)
if err != nil {
t.Fatalf("read allowed udp reply: %v", err)
}
if got := string(buf[10:rn]); got != "OK:allowed-udp" {
t.Fatalf("reply = %q, want OK:allowed-udp", got)
}
if blockedCount.Load() != 0 {
t.Fatalf("blocked 127.0.0.2 received %d datagrams, want 0", blockedCount.Load())
}
if allowedCount.Load() != 1 {
t.Fatalf("allowed 127.0.0.1 received %d datagrams, want 1", allowedCount.Load())
}
// Wait briefly for SQLite writes and verify raw_udp_datagrams has 127.0.0.1 only, 0 HTTP exchanges.
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
n, err := mOn.traffic.CountRawUDPDatagrams("", "127.0.0.1")
if err == nil && n >= 2 {
break
}
time.Sleep(20 * time.Millisecond)
}
if nBlocked, err := mOn.traffic.CountRawUDPDatagrams("", "127.0.0.2"); err != nil || nBlocked != 0 {
t.Fatalf("blocked host recorded %d rows (err=%v), want 0", nBlocked, err)
}
if nAllowed, err := mOn.traffic.CountRawUDPDatagrams("", "127.0.0.1"); err != nil || nAllowed != 2 {
t.Fatalf("allowed host recorded %d rows (err=%v), want 2", nAllowed, err)
}
}
+214
View File
@@ -0,0 +1,214 @@
package traffic
import (
"database/sql"
"fmt"
"strings"
"time"
)
// RawUDPDatagram is one recorded UDP datagram relayed by opt-in SOCKS5 UDP
// ASSOCIATE (P4.1c). It never creates an HTTP exchanges row.
type RawUDPDatagram struct {
ID string `json:"id"`
AssociationID string `json:"association_id"`
Protocol string `json:"protocol"`
Host string `json:"host"`
Port int `json:"port"`
Direction string `json:"direction"` // "c2s" | "s2c"
Timestamp int64 `json:"ts"` // unix milliseconds
Size int64 `json:"size"`
Preview []byte `json:"preview,omitempty"`
Blob string `json:"blob,omitempty"`
}
// RawUDPFilter narrows ListRawUDPDatagrams queries.
type RawUDPFilter struct {
AssociationID string
Host string
Port int
Direction string
Limit int
Offset int
}
func (t *Traffic) newRawUDPDatagramID(ts time.Time) string {
n := t.seq.Add(1)
return fmt.Sprintf("udp-%d-%04d", ts.UnixMilli(), n%10000)
}
// RecordRawUDPDatagram persists one forwarded UDP datagram into
// raw_udp_datagrams and registers any spilled payload blob in blob_refs.
// Payloads above previewBytes are spilled atomically via spillRawDir.
// It never writes to the HTTP exchanges table.
func (t *Traffic) RecordRawUDPDatagram(rec RawUDPCapture, previewBytes int) (string, error) {
if t == nil || t.db == nil {
return "", fmt.Errorf("traffic store unavailable")
}
dir := strings.ToLower(strings.TrimSpace(rec.Direction))
if dir != "c2s" && dir != "s2c" {
return "", fmt.Errorf("invalid raw udp direction %q", rec.Direction)
}
ts := rec.Timestamp.UTC()
if ts.IsZero() {
ts = time.Now().UTC()
}
preview, blobHash := t.spillRawDir(rec.Payload, previewBytes)
t.wmu.Lock()
defer t.wmu.Unlock()
id := t.newRawUDPDatagramID(ts)
tx, err := t.db.Begin()
if err != nil {
return "", fmt.Errorf("begin raw udp tx: %w", err)
}
defer tx.Rollback() //nolint:errcheck
if _, err := tx.Exec(`
INSERT INTO raw_udp_datagrams(
id, association_id, protocol, host, port, direction, ts, size, preview, blob
) VALUES(?, ?, 'udp', ?, ?, ?, ?, ?, ?, ?)`,
id, strings.TrimSpace(rec.AssociationID),
strings.ToLower(strings.TrimSpace(rec.Host)), rec.Port,
dir, ts.UnixMilli(), int64(len(rec.Payload)),
preview, nullIfEmpty(blobHash),
); err != nil {
return "", fmt.Errorf("insert raw_udp_datagrams: %w", err)
}
if blobHash != "" {
if _, err := tx.Exec(`INSERT OR IGNORE INTO blob_refs(hash, exchange_id) VALUES(?, ?)`, blobHash, id); err != nil {
return "", fmt.Errorf("register raw udp blob ref: %w", err)
}
}
if err := tx.Commit(); err != nil {
return "", fmt.Errorf("commit raw udp tx: %w", err)
}
return id, nil
}
// GetRawUDPDatagram fetches one recorded UDP datagram by ID. Returns nil, nil
// when not found.
func (t *Traffic) GetRawUDPDatagram(id string) (*RawUDPDatagram, error) {
if t == nil || t.db == nil {
return nil, fmt.Errorf("traffic store unavailable")
}
var d RawUDPDatagram
var blob sql.NullString
err := t.db.QueryRow(`
SELECT id, association_id, protocol, host, port, direction, ts, size, preview, blob
FROM raw_udp_datagrams WHERE id = ?`, id).Scan(
&d.ID, &d.AssociationID, &d.Protocol, &d.Host, &d.Port,
&d.Direction, &d.Timestamp, &d.Size, &d.Preview, &blob,
)
if err == sql.ErrNoRows {
return nil, nil
}
if err != nil {
return nil, err
}
d.Blob = blob.String
return &d, nil
}
// ListRawUDPDatagrams returns recorded UDP datagrams newest-first along with
// the total count matching the filter.
func (t *Traffic) ListRawUDPDatagrams(f RawUDPFilter) ([]RawUDPDatagram, int, error) {
if t == nil || t.db == nil {
return nil, 0, fmt.Errorf("traffic store unavailable")
}
var conds []string
var args []any
if a := strings.TrimSpace(f.AssociationID); a != "" {
conds = append(conds, "association_id = ?")
args = append(args, a)
}
if h := strings.ToLower(strings.TrimSpace(f.Host)); h != "" {
conds = append(conds, "host = ?")
args = append(args, h)
}
if f.Port > 0 {
conds = append(conds, "port = ?")
args = append(args, f.Port)
}
if dir := strings.ToLower(strings.TrimSpace(f.Direction)); dir != "" {
conds = append(conds, "direction = ?")
args = append(args, dir)
}
where := ""
if len(conds) > 0 {
where = " WHERE " + strings.Join(conds, " AND ")
}
var total int
if err := t.db.QueryRow(`SELECT COUNT(*) FROM raw_udp_datagrams`+where, args...).Scan(&total); err != nil {
return nil, 0, err
}
limit := f.Limit
if limit <= 0 {
limit = 50
}
if limit > 500 {
limit = 500
}
offset := f.Offset
if offset < 0 {
offset = 0
}
qArgs := append(append([]any{}, args...), limit, offset)
rows, err := t.db.Query(`
SELECT id, association_id, protocol, host, port, direction, ts, size, preview, blob
FROM raw_udp_datagrams`+where+`
ORDER BY ts DESC, id DESC
LIMIT ? OFFSET ?`, qArgs...)
if err != nil {
return nil, 0, err
}
defer rows.Close()
out := []RawUDPDatagram{}
for rows.Next() {
var d RawUDPDatagram
var blob sql.NullString
if err := rows.Scan(
&d.ID, &d.AssociationID, &d.Protocol, &d.Host, &d.Port,
&d.Direction, &d.Timestamp, &d.Size, &d.Preview, &blob,
); err != nil {
return nil, 0, err
}
d.Blob = blob.String
out = append(out, d)
}
return out, total, rows.Err()
}
// CountRawUDPDatagrams returns the number of recorded raw UDP datagrams
// optionally filtered by association_id and/or exact host.
func (t *Traffic) CountRawUDPDatagrams(assocID, host string) (int, error) {
if t == nil || t.db == nil {
return 0, fmt.Errorf("traffic store unavailable")
}
var conds []string
var args []any
if a := strings.TrimSpace(assocID); a != "" {
conds = append(conds, "association_id = ?")
args = append(args, a)
}
if h := strings.ToLower(strings.TrimSpace(host)); h != "" {
conds = append(conds, "host = ?")
args = append(args, h)
}
q := `SELECT COUNT(*) FROM raw_udp_datagrams`
if len(conds) > 0 {
q += " WHERE " + strings.Join(conds, " AND ")
}
var n int
err := t.db.QueryRow(q, args...).Scan(&n)
return n, err
}
+131 -41
View File
@@ -31,15 +31,26 @@ const (
// Setting a non-empty address also enables the listener unless
// ARTEX_SOCKS5_ENABLED is explicitly false/0/off/no.
SOCKS5AddrEnv = "ARTEX_SOCKS5_ADDR"
// SOCKS5UDPEnabledEnv turns on RFC 1928 UDP ASSOCIATE (IPv4 first) on the
// SOCKS5 listener when set to 1/true/on/yes. Off by default: when off,
// UDP ASSOCIATE is refused with reply 0x07 and no UDP relay socket is opened.
// Setting ARTEX_SOCKS5_UDP_ENABLED=1 also enables the SOCKS5 listener on
// ARTEX_SOCKS5_ADDR (or DefaultSOCKS5Addr) unless ARTEX_SOCKS5_ENABLED is
// explicitly false/0/off/no.
SOCKS5UDPEnabledEnv = "ARTEX_SOCKS5_UDP_ENABLED"
DefaultSOCKS5Addr = "127.0.0.1:1080"
DefaultSOCKS5MaxConcurrent = 64
DefaultSOCKS5MaxBytesPerDir = 4 * 1024 * 1024
DefaultSOCKS5PreviewBytes = blobPreview
DefaultSOCKS5IdleTimeout = 2 * time.Minute
DefaultSOCKS5HandshakeTimeout = 10 * time.Second
DefaultSOCKS5DialTimeout = 30 * time.Second
DefaultSOCKS5PaceTimeout = paceWaitMax
DefaultSOCKS5Addr = "127.0.0.1:1080"
DefaultSOCKS5MaxConcurrent = 64
DefaultSOCKS5MaxBytesPerDir = 4 * 1024 * 1024
DefaultSOCKS5PreviewBytes = blobPreview
DefaultSOCKS5IdleTimeout = 2 * time.Minute
DefaultSOCKS5HandshakeTimeout = 10 * time.Second
DefaultSOCKS5DialTimeout = 30 * time.Second
DefaultSOCKS5PaceTimeout = paceWaitMax
DefaultSOCKS5UDPMaxDatagrams = 1000
DefaultSOCKS5UDPMaxBytes = 4 * 1024 * 1024
DefaultSOCKS5UDPIdleTimeout = 2 * time.Minute
DefaultSOCKS5UDPMaxDatagramSize = 65535
)
// RFC 1928 / RFC 1929 protocol constants.
@@ -97,6 +108,24 @@ type SOCKS5Config struct {
// OnRecord, when non-nil, receives each completed raw TCP capture.
// When nil and attached to a Traffic store, the store's raw-TCP recorder runs.
OnRecord func(RawTCPCapture)
// EnableUDP opts into RFC 1928 UDP ASSOCIATE (IPv4 first, P4.1c).
// Off by default: when false, UDP ASSOCIATE returns 0x07.
EnableUDP bool
// UDPMaxDatagrams caps total forwarded datagrams (c2s + s2c) per UDP association (default 1000).
UDPMaxDatagrams int
// UDPMaxBytes caps total forwarded payload bytes (c2s + s2c) per UDP association (default 4 MiB).
UDPMaxBytes int64
// UDPIdleTimeout closes a UDP association after no forwarded datagrams move (default 2m).
UDPIdleTimeout time.Duration
// UDPPreviewBytes caps inline preview per stored UDP datagram before blob spill (default PreviewBytes / 8 KiB).
UDPPreviewBytes int
// ResolveUDP4 enforces the target gate and resolves each UDP datagram destination
// to a verified IPv4 *net.UDPAddr before forwarding. Defaults to intercept.PinnedUDP4Resolver("socks5-udp", false).
ResolveUDP4 func(ctx context.Context, addr string) (*net.UDPAddr, error)
// OnRecordUDP, when non-nil, receives each forwarded UDP datagram capture.
// When nil and attached to a Traffic store, the store's raw-UDP recorder runs.
OnRecordUDP func(RawUDPCapture)
}
// RawTCPCapture is the completed metadata and bounded directional payloads of
@@ -114,11 +143,22 @@ type RawTCPCapture struct {
Paced bool
}
// SOCKS5ConfigFromEnv parses ARTEX_SOCKS5_ENABLED and ARTEX_SOCKS5_ADDR.
// Returns (cfg, false) when disabled (the default).
// SOCKS5ConfigFromEnv parses ARTEX_SOCKS5_ENABLED, ARTEX_SOCKS5_ADDR, and
// ARTEX_SOCKS5_UDP_ENABLED. Returns (cfg, false) when disabled (the default).
func SOCKS5ConfigFromEnv() (SOCKS5Config, bool) {
rawEnabled := strings.ToLower(strings.TrimSpace(os.Getenv(SOCKS5EnabledEnv)))
rawAddr := strings.TrimSpace(os.Getenv(SOCKS5AddrEnv))
rawUDP := strings.ToLower(strings.TrimSpace(os.Getenv(SOCKS5UDPEnabledEnv)))
enableUDP := false
switch rawUDP {
case "", "0", "false", "off", "no":
enableUDP = false
case "1", "true", "on", "yes":
enableUDP = true
default:
log.Printf("[traffic] %s=%q is not a boolean; leaving SOCKS5 UDP disabled", SOCKS5UDPEnabledEnv, rawUDP)
}
switch rawEnabled {
case "0", "false", "off", "no":
@@ -128,12 +168,16 @@ func SOCKS5ConfigFromEnv() (SOCKS5Config, bool) {
if addr == "" {
addr = DefaultSOCKS5Addr
}
return SOCKS5Config{Addr: addr}, true
return SOCKS5Config{Addr: addr, EnableUDP: enableUDP}, true
case "":
if rawAddr == "" {
if rawAddr == "" && !enableUDP {
return SOCKS5Config{}, false
}
return SOCKS5Config{Addr: rawAddr}, true
addr := rawAddr
if addr == "" {
addr = DefaultSOCKS5Addr
}
return SOCKS5Config{Addr: addr, EnableUDP: enableUDP}, true
default:
log.Printf("[traffic] %s=%q is not a boolean; leaving SOCKS5 disabled", SOCKS5EnabledEnv, rawEnabled)
return SOCKS5Config{}, false
@@ -168,6 +212,21 @@ func (c SOCKS5Config) withDefaults() SOCKS5Config {
if c.DialContext == nil {
c.DialContext = intercept.PinnedDialer("socks5", false)
}
if c.UDPMaxDatagrams <= 0 {
c.UDPMaxDatagrams = DefaultSOCKS5UDPMaxDatagrams
}
if c.UDPMaxBytes <= 0 {
c.UDPMaxBytes = DefaultSOCKS5UDPMaxBytes
}
if c.UDPIdleTimeout <= 0 {
c.UDPIdleTimeout = DefaultSOCKS5UDPIdleTimeout
}
if c.UDPPreviewBytes <= 0 {
c.UDPPreviewBytes = c.PreviewBytes
}
if c.ResolveUDP4 == nil {
c.ResolveUDP4 = intercept.PinnedUDP4Resolver("socks5-udp", false)
}
return c
}
@@ -181,10 +240,10 @@ type socks5Server struct {
wg sync.WaitGroup
mu sync.Mutex
active map[net.Conn]struct{}
active map[io.Closer]struct{}
}
// StartSOCKS5 binds and starts the opt-in RFC 1928 SOCKS5 CONNECT listener on t.
// StartSOCKS5 binds and starts the opt-in RFC 1928 SOCKS5 listener on t.
// Returns the actual bound address (useful when cfg.Addr uses port 0).
func (t *Traffic) StartSOCKS5(cfg SOCKS5Config) (string, error) {
cfg = cfg.withDefaults()
@@ -198,7 +257,7 @@ func (t *Traffic) StartSOCKS5(cfg SOCKS5Config) (string, error) {
ln: ln,
sem: make(chan struct{}, cfg.MaxConcurrent),
stop: make(chan struct{}),
active: map[net.Conn]struct{}{},
active: map[io.Closer]struct{}{},
}
t.socksMu.Lock()
if t.socks != nil {
@@ -224,6 +283,14 @@ func (t *Traffic) SOCKS5Addr() string {
return t.socks.ln.Addr().String()
}
// SOCKS5UDPEnabled reports whether the running SOCKS5 listener accepts RFC 1928
// UDP ASSOCIATE requests.
func (t *Traffic) SOCKS5UDPEnabled() bool {
t.socksMu.Lock()
defer t.socksMu.Unlock()
return t.socks != nil && t.socks.cfg.EnableUDP
}
func (s *socks5Server) Close() error {
var closeErr error
s.once.Do(func() {
@@ -248,7 +315,7 @@ func (s *socks5Server) stopping() bool {
}
}
func (s *socks5Server) trackConn(c net.Conn) bool {
func (s *socks5Server) trackConn(c io.Closer) bool {
s.mu.Lock()
defer s.mu.Unlock()
if s.stopping() {
@@ -258,7 +325,7 @@ func (s *socks5Server) trackConn(c net.Conn) bool {
return true
}
func (s *socks5Server) untrackConn(c net.Conn) {
func (s *socks5Server) untrackConn(c io.Closer) {
s.mu.Lock()
delete(s.active, c)
s.mu.Unlock()
@@ -302,11 +369,15 @@ func (s *socks5Server) handleConn(client net.Conn) {
return
}
host, port, rep := readSOCKS5Request(client)
cmd, atyp, host, port, rep := readSOCKS5Request(client, s.cfg.EnableUDP)
if rep != socks5RepSuccess {
_ = writeSOCKS5Reply(client, rep, nil)
return
}
if cmd == socks5CmdUDPAssociate {
s.handleUDPAssociate(client, atyp, host, port)
return
}
// 2. Enforce max concurrent streams before touching policy or dialing.
select {
@@ -458,16 +529,16 @@ func readSOCKS5UserPass(conn net.Conn) (paced bool, ok bool) {
return string(uname) == egress.PaceUser, true
}
func readSOCKS5Request(conn net.Conn) (host string, port int, rep byte) {
func readSOCKS5Request(conn net.Conn, enableUDP bool) (cmd byte, atyp byte, host string, port int, rep byte) {
var hdr [4]byte
if _, err := io.ReadFull(conn, hdr[:]); err != nil {
return "", 0, socks5RepGeneralFailure
return 0, 0, "", 0, socks5RepGeneralFailure
}
if hdr[0] != socks5Version || hdr[2] != 0x00 {
return "", 0, socks5RepGeneralFailure
return 0, 0, "", 0, socks5RepGeneralFailure
}
cmd := hdr[1]
atyp := hdr[3]
cmd = hdr[1]
atyp = hdr[3]
// Read the address + port before rejecting unsupported commands so the stream
// stays cleanly framed if the peer reads our reply.
@@ -475,56 +546,75 @@ func readSOCKS5Request(conn net.Conn) (host string, port int, rep byte) {
case socks5AtypIPv4:
var ip [4]byte
if _, err := io.ReadFull(conn, ip[:]); err != nil {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
host = net.IP(ip[:]).String()
case socks5AtypDomain:
var l [1]byte
if _, err := io.ReadFull(conn, l[:]); err != nil {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
if l[0] == 0 {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
dom := make([]byte, int(l[0]))
if _, err := io.ReadFull(conn, dom); err != nil {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
host = strings.TrimSpace(string(dom))
if host == "" {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
case socks5AtypIPv6:
var ip [16]byte
if _, err := io.ReadFull(conn, ip[:]); err != nil {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
host = net.IP(ip[:]).String()
default:
return "", 0, socks5RepAtypNotSupported
return cmd, atyp, "", 0, socks5RepAtypNotSupported
}
var pbuf [2]byte
if _, err := io.ReadFull(conn, pbuf[:]); err != nil {
return "", 0, socks5RepGeneralFailure
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
port = int(binary.BigEndian.Uint16(pbuf[:]))
if cmd != socks5CmdConnect {
return "", 0, socks5RepCmdNotSupported
switch cmd {
case socks5CmdConnect:
if port <= 0 || port > 65535 {
return cmd, atyp, "", 0, socks5RepGeneralFailure
}
return cmd, atyp, host, port, socks5RepSuccess
case socks5CmdUDPAssociate:
if !enableUDP {
return cmd, atyp, "", 0, socks5RepCmdNotSupported
}
// P4.1c covers IPv4 first; IPv6 UDP ASSOCIATE is rejected explicitly.
if atyp == socks5AtypIPv6 {
return cmd, atyp, "", 0, socks5RepAtypNotSupported
}
return cmd, atyp, host, port, socks5RepSuccess
default:
return cmd, atyp, "", 0, socks5RepCmdNotSupported
}
if port <= 0 || port > 65535 {
return "", 0, socks5RepGeneralFailure
}
return host, port, socks5RepSuccess
}
func writeSOCKS5Reply(conn net.Conn, rep byte, bindAddr net.Addr) error {
var bndIP net.IP
var bndPort int
if tcpAddr, ok := bindAddr.(*net.TCPAddr); ok && tcpAddr != nil {
bndIP = tcpAddr.IP
bndPort = tcpAddr.Port
switch a := bindAddr.(type) {
case *net.TCPAddr:
if a != nil {
bndIP = a.IP
bndPort = a.Port
}
case *net.UDPAddr:
if a != nil {
bndIP = a.IP
bndPort = a.Port
}
}
var out []byte
if ip4 := bndIP.To4(); ip4 != nil {
+445
View File
@@ -0,0 +1,445 @@
package traffic
import (
"context"
"encoding/binary"
"errors"
"fmt"
"log"
"net"
"net/url"
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/Autumn-27/artex/egress"
)
var (
errSOCKS5UDPShortPacket = errors.New("short SOCKS5 UDP packet")
errSOCKS5UDPBadReserved = errors.New("non-zero SOCKS5 UDP RSV field")
errSOCKS5UDPFragmented = errors.New("SOCKS5 UDP fragmentation (FRAG != 0) is not supported")
errSOCKS5UDPUnsupportedAtyp = errors.New("unsupported SOCKS5 UDP address type (IPv4/domain only)")
errSOCKS5UDPBadDestination = errors.New("invalid SOCKS5 UDP destination address or port")
)
var fallbackUDPAssocSeq atomic.Int64
// RawUDPCapture holds one forwarded UDP datagram observed on a SOCKS5 UDP
// ASSOCIATE relay. Each datagram is recorded individually as it arrives with
// no fragmentation reassembly.
type RawUDPCapture struct {
AssociationID string
Host string
Port int
Direction string // "c2s" | "s2c"
Timestamp time.Time
Payload []byte
}
// parseSOCKS5UDPHeader parses an RFC 1928 §7 UDP request header.
//
// +----+------+------+----------+----------+----------+
// |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA |
// +----+------+------+----------+----------+----------+
// | 2 | 1 | 1 | Variable | 2 | Variable |
// +----+------+------+----------+----------+----------+
//
// Fragmentation reassembly is intentionally unsupported: any datagram with
// FRAG != 0 returns errSOCKS5UDPFragmented and must be dropped per RFC 1928 §7.
// P4.1c covers IPv4 destinations (ATYP=0x01) and domain names resolved to IPv4
// (ATYP=0x03); IPv6 (ATYP=0x04) is rejected with errSOCKS5UDPUnsupportedAtyp.
func parseSOCKS5UDPHeader(pkt []byte) (atyp byte, host string, port int, payload []byte, err error) {
if len(pkt) < 4 {
return 0, "", 0, nil, errSOCKS5UDPShortPacket
}
if pkt[0] != 0x00 || pkt[1] != 0x00 {
return 0, "", 0, nil, errSOCKS5UDPBadReserved
}
if pkt[2] != 0x00 {
return 0, "", 0, nil, errSOCKS5UDPFragmented
}
atyp = pkt[3]
off := 4
switch atyp {
case socks5AtypIPv4:
if len(pkt) < off+4+2 {
return atyp, "", 0, nil, errSOCKS5UDPShortPacket
}
ip := net.IPv4(pkt[off], pkt[off+1], pkt[off+2], pkt[off+3]).To4()
if ip == nil || ip.IsUnspecified() {
return atyp, "", 0, nil, errSOCKS5UDPBadDestination
}
host = ip.String()
off += 4
case socks5AtypDomain:
if len(pkt) < off+1 {
return atyp, "", 0, nil, errSOCKS5UDPShortPacket
}
domLen := int(pkt[off])
off++
if domLen == 0 || len(pkt) < off+domLen+2 {
return atyp, "", 0, nil, errSOCKS5UDPShortPacket
}
host = strings.TrimSpace(string(pkt[off : off+domLen]))
if host == "" {
return atyp, "", 0, nil, errSOCKS5UDPBadDestination
}
off += domLen
default:
return atyp, "", 0, nil, errSOCKS5UDPUnsupportedAtyp
}
port = int(binary.BigEndian.Uint16(pkt[off : off+2]))
off += 2
if port <= 0 || port > 65535 {
return atyp, "", 0, nil, errSOCKS5UDPBadDestination
}
return atyp, host, port, pkt[off:], nil
}
// buildSOCKS5UDPPacket wraps an IPv4 upstream reply datagram in an RFC 1928 §7
// UDP header (RSV=0x0000, FRAG=0x00, ATYP=0x01).
func buildSOCKS5UDPPacket(srcIP net.IP, srcPort int, payload []byte) ([]byte, error) {
ip4 := srcIP.To4()
if ip4 == nil || srcPort <= 0 || srcPort > 65535 {
return nil, errSOCKS5UDPBadDestination
}
out := make([]byte, 10+len(payload))
out[0] = 0x00
out[1] = 0x00
out[2] = 0x00
out[3] = socks5AtypIPv4
copy(out[4:8], ip4)
binary.BigEndian.PutUint16(out[8:10], uint16(srcPort))
copy(out[10:], payload)
return out, nil
}
func (s *socks5Server) newUDPAssociationID(started time.Time) string {
var n int64
if s.t != nil {
n = s.t.seq.Add(1)
} else {
n = fallbackUDPAssocSeq.Add(1)
}
return fmt.Sprintf("udpa-%d-%04d", started.UnixMilli(), n%10000)
}
func (s *socks5Server) handleUDPAssociate(client net.Conn, reqAtyp byte, reqHost string, reqPort int) {
// 1. Enforce max concurrent sessions before allocating UDP sockets.
select {
case s.sem <- struct{}{}:
defer func() { <-s.sem }()
default:
_ = writeSOCKS5Reply(client, socks5RepGeneralFailure, nil)
return
}
// 2. Bind client-facing IPv4 UDP relay socket on the TCP local interface IP.
bindIP := net.IPv4(127, 0, 0, 1)
if ltcp, ok := client.LocalAddr().(*net.TCPAddr); ok && ltcp != nil {
if ip4 := ltcp.IP.To4(); ip4 != nil && !ip4.IsUnspecified() {
bindIP = ip4
}
}
relayConn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: bindIP, Port: 0})
if err != nil {
_ = writeSOCKS5Reply(client, socks5RepGeneralFailure, nil)
return
}
if !s.trackConn(relayConn) {
_ = relayConn.Close()
_ = writeSOCKS5Reply(client, socks5RepGeneralFailure, nil)
return
}
defer s.untrackConn(relayConn)
defer relayConn.Close()
// 3. Bind upstream IPv4 UDP socket for forwarding to verified targets.
upstreamConn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4zero, Port: 0})
if err != nil {
_ = writeSOCKS5Reply(client, socks5RepGeneralFailure, nil)
return
}
if !s.trackConn(upstreamConn) {
_ = upstreamConn.Close()
_ = writeSOCKS5Reply(client, socks5RepGeneralFailure, nil)
return
}
defer s.untrackConn(upstreamConn)
defer upstreamConn.Close()
// Clear handshake deadline and send BND.ADDR + BND.PORT on TCP control conn.
_ = client.SetDeadline(time.Time{})
relayAddr := relayConn.LocalAddr().(*net.UDPAddr)
if err := writeSOCKS5Reply(client, socks5RepSuccess, relayAddr); err != nil {
return
}
// Determine allowed client UDP source IP/port.
var expectedClientIP net.IP
expectedClientPort := 0
if reqAtyp == socks5AtypIPv4 {
if ip := net.ParseIP(reqHost).To4(); ip != nil && !ip.IsUnspecified() {
expectedClientIP = ip
}
if reqPort > 0 && reqPort <= 65535 {
expectedClientPort = reqPort
}
}
if expectedClientIP == nil {
if rtcp, ok := client.RemoteAddr().(*net.TCPAddr); ok && rtcp != nil {
expectedClientIP = rtcp.IP.To4()
}
}
assocID := s.newUDPAssociationID(time.Now().UTC())
baseCtx := context.Background()
if s.cfg.BaseContext != nil {
if ctx := s.cfg.BaseContext(); ctx != nil {
baseCtx = ctx
}
}
assocCtx, assocCancel := context.WithCancel(baseCtx)
var closeOnce sync.Once
closeAssoc := func() {
closeOnce.Do(func() {
assocCancel()
_ = relayConn.Close()
_ = upstreamConn.Close()
_ = client.Close()
})
}
defer closeAssoc()
// Close association when server stops.
stopWatchDone := make(chan struct{})
go func() {
select {
case <-s.stop:
closeAssoc()
case <-assocCtx.Done():
}
close(stopWatchDone)
}()
defer func() { <-stopWatchDone }()
// Idle timer bounds inactive associations.
var idleTimer *time.Timer
if s.cfg.UDPIdleTimeout > 0 {
idleTimer = time.AfterFunc(s.cfg.UDPIdleTimeout, closeAssoc)
defer idleTimer.Stop()
}
touchIdle := func() {
if idleTimer != nil {
idleTimer.Reset(s.cfg.UDPIdleTimeout)
}
}
var (
assocMu sync.Mutex
clientUDPAddr *net.UDPAddr
allowedPeers = map[string]string{} // resolved "ip:port" -> logical dst host
datagramCount int
byteCount int64
)
// consumeBudget reserves one datagram + payload length against the
// association's bounds. Returns false if either limit would be exceeded.
consumeBudget := func(payloadLen int) bool {
assocMu.Lock()
defer assocMu.Unlock()
if datagramCount+1 > s.cfg.UDPMaxDatagrams || byteCount+int64(payloadLen) > s.cfg.UDPMaxBytes {
return false
}
datagramCount++
byteCount += int64(payloadLen)
return true
}
var wg sync.WaitGroup
wg.Add(3)
// Goroutine 1: tie association lifetime strictly to the TCP control connection.
go func() {
defer wg.Done()
var discard [64]byte
for {
if _, err := client.Read(discard[:]); err != nil {
closeAssoc()
return
}
}
}()
// Goroutine 2: client -> upstream UDP relay (c2s).
go func() {
defer wg.Done()
buf := make([]byte, DefaultSOCKS5UDPMaxDatagramSize)
for {
n, from, err := relayConn.ReadFromUDP(buf)
if err != nil {
return
}
if !s.acceptClientUDPSource(from, expectedClientIP, expectedClientPort, &assocMu, &clientUDPAddr) {
continue
}
_, dstHost, dstPort, payload, err := parseSOCKS5UDPHeader(buf[:n])
if err != nil {
// Malformed header, FRAG != 0, or unsupported ATYP: drop datagram.
continue
}
// Copy payload before forwarding/recording so buf can be reused safely.
payloadCopy := append([]byte(nil), payload...)
targetAddr := net.JoinHostPort(dstHost, strconv.Itoa(dstPort))
// Enforce per-datagram destination policy (target gate + egress governor)
// BEFORE forwarding. A denied destination drops that datagram cleanly.
dstUDPAddr, err := s.resolveAndPaceUDP4(assocCtx, targetAddr)
if err != nil {
continue
}
if !consumeBudget(len(payloadCopy)) {
closeAssoc()
return
}
assocMu.Lock()
allowedPeers[dstUDPAddr.String()] = dstHost
assocMu.Unlock()
if _, err := upstreamConn.WriteToUDP(payloadCopy, dstUDPAddr); err != nil {
if assocCtx.Err() != nil {
return
}
continue
}
touchIdle()
s.recordUDPCapture(RawUDPCapture{
AssociationID: assocID,
Host: dstHost,
Port: dstPort,
Direction: "c2s",
Timestamp: time.Now().UTC(),
Payload: payloadCopy,
})
}
}()
// Goroutine 3: upstream -> client UDP relay (s2c).
go func() {
defer wg.Done()
buf := make([]byte, DefaultSOCKS5UDPMaxDatagramSize)
for {
n, from, err := upstreamConn.ReadFromUDP(buf)
if err != nil {
return
}
assocMu.Lock()
origHost, allowed := allowedPeers[from.String()]
cli := clientUDPAddr
assocMu.Unlock()
if !allowed || cli == nil {
// Drop unsolicited UDP packets from destinations this association
// has not sent an allowed datagram to.
continue
}
payloadCopy := append([]byte(nil), buf[:n]...)
if !consumeBudget(len(payloadCopy)) {
closeAssoc()
return
}
wrapped, err := buildSOCKS5UDPPacket(from.IP, from.Port, payloadCopy)
if err != nil {
continue
}
if _, err := relayConn.WriteToUDP(wrapped, cli); err != nil {
if assocCtx.Err() != nil {
return
}
continue
}
touchIdle()
s.recordUDPCapture(RawUDPCapture{
AssociationID: assocID,
Host: origHost,
Port: from.Port,
Direction: "s2c",
Timestamp: time.Now().UTC(),
Payload: payloadCopy,
})
}
}()
wg.Wait()
}
func (s *socks5Server) acceptClientUDPSource(from *net.UDPAddr, expectedIP net.IP, expectedPort int, mu *sync.Mutex, pinned **net.UDPAddr) bool {
if from == nil || from.IP == nil {
return false
}
fromIP4 := from.IP.To4()
if fromIP4 == nil {
return false
}
if expectedIP != nil && !fromIP4.Equal(expectedIP) {
return false
}
if expectedPort > 0 && from.Port != expectedPort {
return false
}
mu.Lock()
defer mu.Unlock()
if *pinned == nil {
*pinned = &net.UDPAddr{IP: append(net.IP(nil), fromIP4...), Port: from.Port}
return true
}
return (*pinned).IP.Equal(fromIP4) && (*pinned).Port == from.Port
}
func (s *socks5Server) resolveAndPaceUDP4(assocCtx context.Context, targetAddr string) (*net.UDPAddr, error) {
// 1. Target gate + fresh DNS resolution (IPv4).
resCtx, resCancel := context.WithTimeout(assocCtx, s.cfg.DialTimeout)
defer resCancel()
dstAddr, err := s.cfg.ResolveUDP4(resCtx, targetAddr)
if err != nil {
return nil, err
}
if dstAddr == nil || dstAddr.IP == nil || dstAddr.IP.To4() == nil || dstAddr.Port <= 0 {
return nil, errSOCKS5UDPBadDestination
}
// 2. Egress governor (same egress.Do path as HTTP / SOCKS5 TCP / transparent TCP).
govCtx, govCancel := context.WithTimeout(assocCtx, s.cfg.PaceTimeout)
defer govCancel()
targetURL := &url.URL{Scheme: "udp", Host: targetAddr}
_, err = egress.Do(egress.Current(), govCtx, targetURL, func() (struct{}, error) {
return struct{}{}, nil
})
if err != nil {
return nil, err
}
return dstAddr, nil
}
func (s *socks5Server) recordUDPCapture(rec RawUDPCapture) {
if s.cfg.OnRecordUDP != nil {
s.cfg.OnRecordUDP(rec)
return
}
if s.t != nil && s.t.db != nil {
if _, err := s.t.RecordRawUDPDatagram(rec, s.cfg.UDPPreviewBytes); err != nil {
log.Printf("[traffic/socks5-udp] failed to record datagram assoc=%s dst=%s:%d: %v",
rec.AssociationID, rec.Host, rec.Port, err)
}
}
}
+750
View File
@@ -0,0 +1,750 @@
package traffic
import (
"bytes"
"context"
"encoding/binary"
"errors"
"io"
"net"
"os"
"path/filepath"
"runtime"
"strconv"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/Autumn-27/artex/egress"
"github.com/Autumn-27/artex/intercept"
)
func startUDPEchoServer(t *testing.T, addr string) (*net.UDPConn, *atomic.Int32) {
t.Helper()
uaddr, err := net.ResolveUDPAddr("udp4", addr)
if err != nil {
t.Fatalf("resolve udp %s: %v", addr, err)
}
conn, err := net.ListenUDP("udp4", uaddr)
if err != nil {
t.Fatalf("listen udp %s: %v", addr, err)
}
var received atomic.Int32
done := make(chan struct{})
go func() {
defer close(done)
buf := make([]byte, 65535)
for {
n, from, err := conn.ReadFromUDP(buf)
if err != nil {
return
}
received.Add(1)
reply := append([]byte("UDP-ECHO:"), buf[:n]...)
_, _ = conn.WriteToUDP(reply, from)
}
}()
t.Cleanup(func() {
_ = conn.Close()
<-done
})
return conn, &received
}
func socks5UDPAssociate(t *testing.T, proxyAddr string, useAuth bool, atyp byte, dstHost string, dstPort int) (net.Conn, *net.UDPAddr, byte) {
t.Helper()
c, err := net.DialTimeout("tcp4", proxyAddr, 2*time.Second)
if err != nil {
t.Fatalf("dial socks5 %s: %v", proxyAddr, err)
}
_ = c.SetDeadline(time.Now().Add(5 * time.Second))
if useAuth {
if _, err := c.Write([]byte{socks5Version, 1, socks5AuthUserPass}); err != nil {
t.Fatal(err)
}
var sel [2]byte
if _, err := io.ReadFull(c, sel[:]); err != nil || sel != [2]byte{socks5Version, socks5AuthUserPass} {
t.Fatalf("auth selection = %v err=%v", sel, err)
}
user := egress.PaceUser
authReq := []byte{socks5UserPassVer, byte(len(user))}
authReq = append(authReq, []byte(user)...)
authReq = append(authReq, 0)
if _, err := c.Write(authReq); err != nil {
t.Fatal(err)
}
var ares [2]byte
if _, err := io.ReadFull(c, ares[:]); err != nil || ares != [2]byte{socks5UserPassVer, 0x00} {
t.Fatalf("auth reply = %v err=%v", ares, err)
}
} else {
if _, err := c.Write([]byte{socks5Version, 1, socks5AuthNone}); err != nil {
t.Fatal(err)
}
var sel [2]byte
if _, err := io.ReadFull(c, sel[:]); err != nil || sel != [2]byte{socks5Version, socks5AuthNone} {
t.Fatalf("no-auth selection = %v err=%v", sel, err)
}
}
req := []byte{socks5Version, socks5CmdUDPAssociate, 0x00, atyp}
switch atyp {
case socks5AtypIPv4:
ip4 := net.ParseIP(dstHost).To4()
if ip4 == nil {
ip4 = net.IPv4zero.To4()
}
req = append(req, ip4...)
case socks5AtypIPv6:
ip16 := net.ParseIP(dstHost).To16()
if ip16 == nil {
ip16 = net.IPv6zero
}
req = append(req, ip16...)
case socks5AtypDomain:
req = append(req, byte(len(dstHost)))
req = append(req, []byte(dstHost)...)
}
var p [2]byte
binary.BigEndian.PutUint16(p[:], uint16(dstPort))
req = append(req, p[:]...)
if _, err := c.Write(req); err != nil {
t.Fatal(err)
}
var head [4]byte
if _, err := io.ReadFull(c, head[:]); err != nil {
t.Fatalf("read reply head: %v", err)
}
var bndIP net.IP
switch head[3] {
case socks5AtypIPv4:
var ip [4]byte
if _, err := io.ReadFull(c, ip[:]); err != nil {
t.Fatal(err)
}
bndIP = net.IP(ip[:])
case socks5AtypIPv6:
var ip [16]byte
if _, err := io.ReadFull(c, ip[:]); err != nil {
t.Fatal(err)
}
bndIP = net.IP(ip[:])
default:
t.Fatalf("unexpected reply atyp 0x%02x", head[3])
}
var bp [2]byte
if _, err := io.ReadFull(c, bp[:]); err != nil {
t.Fatal(err)
}
_ = c.SetDeadline(time.Time{})
return c, &net.UDPAddr{IP: bndIP, Port: int(binary.BigEndian.Uint16(bp[:]))}, head[1]
}
func makeClientUDPPacketIPv4(ip net.IP, port int, frag byte, payload []byte) []byte {
out := make([]byte, 10+len(payload))
out[0] = 0x00
out[1] = 0x00
out[2] = frag
out[3] = socks5AtypIPv4
copy(out[4:8], ip.To4())
binary.BigEndian.PutUint16(out[8:10], uint16(port))
copy(out[10:], payload)
return out
}
func makeClientUDPPacketDomain(domain string, port int, payload []byte) []byte {
out := make([]byte, 0, 4+1+len(domain)+2+len(payload))
out = append(out, 0x00, 0x00, 0x00, socks5AtypDomain, byte(len(domain)))
out = append(out, []byte(domain)...)
var p [2]byte
binary.BigEndian.PutUint16(p[:], uint16(port))
out = append(out, p[:]...)
out = append(out, payload...)
return out
}
func waitForUDPDatagrams(t *testing.T, tr *Traffic, want int) []RawUDPDatagram {
t.Helper()
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
rows, total, err := tr.ListRawUDPDatagrams(RawUDPFilter{Limit: 100})
if err != nil {
t.Fatalf("ListRawUDPDatagrams: %v", err)
}
if total >= want {
return rows
}
time.Sleep(20 * time.Millisecond)
}
rows, total, _ := tr.ListRawUDPDatagrams(RawUDPFilter{Limit: 100})
t.Fatalf("timed out waiting for %d raw UDP datagrams (got %d: %+v)", want, total, rows)
return nil
}
func TestSOCKS5UDPHeaderParsingAndBuild(t *testing.T) {
t.Run("ipv4_roundtrip", func(t *testing.T) {
payload := []byte("dns-query-bytes")
pkt, err := buildSOCKS5UDPPacket(net.IPv4(198, 51, 100, 53), 53, payload)
if err != nil {
t.Fatalf("buildSOCKS5UDPPacket: %v", err)
}
atyp, host, port, got, err := parseSOCKS5UDPHeader(pkt)
if err != nil {
t.Fatalf("parseSOCKS5UDPHeader: %v", err)
}
if atyp != socks5AtypIPv4 || host != "198.51.100.53" || port != 53 || !bytes.Equal(got, payload) {
t.Fatalf("got (%d, %q, %d, %q)", atyp, host, port, got)
}
})
t.Run("domain_valid", func(t *testing.T) {
pkt := makeClientUDPPacketDomain("udp.example.test", 5353, []byte("hi"))
atyp, host, port, got, err := parseSOCKS5UDPHeader(pkt)
if err != nil {
t.Fatalf("parse domain: %v", err)
}
if atyp != socks5AtypDomain || host != "udp.example.test" || port != 5353 || string(got) != "hi" {
t.Fatalf("got (%d, %q, %d, %q)", atyp, host, port, got)
}
})
t.Run("fragmented_rejected", func(t *testing.T) {
pkt := makeClientUDPPacketIPv4(net.IPv4(127, 0, 0, 1), 53, 0x01, []byte("frag"))
if _, _, _, _, err := parseSOCKS5UDPHeader(pkt); !errors.Is(err, errSOCKS5UDPFragmented) {
t.Fatalf("err = %v, want errSOCKS5UDPFragmented", err)
}
})
t.Run("bad_rsv_short_ipv6_bad_dst", func(t *testing.T) {
if _, _, _, _, err := parseSOCKS5UDPHeader([]byte{0, 0, 0}); !errors.Is(err, errSOCKS5UDPShortPacket) {
t.Fatalf("short err = %v", err)
}
badRsv := makeClientUDPPacketIPv4(net.IPv4(127, 0, 0, 1), 53, 0, nil)
badRsv[1] = 0x01
if _, _, _, _, err := parseSOCKS5UDPHeader(badRsv); !errors.Is(err, errSOCKS5UDPBadReserved) {
t.Fatalf("bad rsv err = %v", err)
}
ipv6Pkt := make([]byte, 22)
ipv6Pkt[3] = socks5AtypIPv6
ipv6Pkt[19] = 1
ipv6Pkt[21] = 53
if _, _, _, _, err := parseSOCKS5UDPHeader(ipv6Pkt); !errors.Is(err, errSOCKS5UDPUnsupportedAtyp) {
t.Fatalf("ipv6 err = %v", err)
}
portZero := makeClientUDPPacketIPv4(net.IPv4(127, 0, 0, 1), 0, 0, nil)
if _, _, _, _, err := parseSOCKS5UDPHeader(portZero); !errors.Is(err, errSOCKS5UDPBadDestination) {
t.Fatalf("port 0 err = %v", err)
}
unspec := makeClientUDPPacketIPv4(net.IPv4zero, 53, 0, nil)
if _, _, _, _, err := parseSOCKS5UDPHeader(unspec); !errors.Is(err, errSOCKS5UDPBadDestination) {
t.Fatalf("0.0.0.0 err = %v", err)
}
})
}
func TestSOCKS5UDPFlagOffMeansNoListenerAndRefusesAssociate(t *testing.T) {
// 1. All flags off -> no listener.
t.Setenv(SOCKS5EnabledEnv, "")
t.Setenv(SOCKS5AddrEnv, "")
t.Setenv(SOCKS5UDPEnabledEnv, "")
if cfg, ok := SOCKS5ConfigFromEnv(); ok || cfg.EnableUDP {
t.Fatalf("all off = (%+v, %v), want disabled", cfg, ok)
}
// 2. Explicit ARTEX_SOCKS5_ENABLED=0 overrides ARTEX_SOCKS5_UDP_ENABLED=1 (no listener).
t.Setenv(SOCKS5EnabledEnv, "0")
t.Setenv(SOCKS5UDPEnabledEnv, "1")
if cfg, ok := SOCKS5ConfigFromEnv(); ok {
t.Fatalf("explicit socks5=0 with udp=1 = (%+v, %v), want disabled", cfg, ok)
}
// 3. ARTEX_SOCKS5_UDP_ENABLED=1 alone enables SOCKS5 on DefaultSOCKS5Addr with EnableUDP=true.
t.Setenv(SOCKS5EnabledEnv, "")
t.Setenv(SOCKS5AddrEnv, "")
t.Setenv(SOCKS5UDPEnabledEnv, "1")
if cfg, ok := SOCKS5ConfigFromEnv(); !ok || !cfg.EnableUDP || cfg.Addr != DefaultSOCKS5Addr {
t.Fatalf("udp=1 = (%+v, %v), want (EnableUDP=true, Addr=%s)", cfg, ok, DefaultSOCKS5Addr)
}
// 4. SOCKS5 enabled with EnableUDP=false refuses UDP ASSOCIATE with 0x07.
trOff, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer trOff.Close()
addrOff, err := trOff.StartSOCKS5(SOCKS5Config{Addr: "127.0.0.1:0", EnableUDP: false})
if err != nil {
t.Fatal(err)
}
if trOff.SOCKS5UDPEnabled() {
t.Fatal("expected SOCKS5UDPEnabled=false")
}
c, _, rep := socks5UDPAssociate(t, addrOff, false, socks5AtypIPv4, "0.0.0.0", 0)
_ = c.Close()
if rep != socks5RepCmdNotSupported {
t.Fatalf("UDP ASSOCIATE with flag off rep = 0x%02x, want 0x%02x", rep, socks5RepCmdNotSupported)
}
// 5. With EnableUDP=true, IPv6 UDP ASSOCIATE is rejected with 0x08 (IPv4 first).
trOn, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer trOn.Close()
addrOn, err := trOn.StartSOCKS5(SOCKS5Config{Addr: "127.0.0.1:0", EnableUDP: true})
if err != nil {
t.Fatal(err)
}
if !trOn.SOCKS5UDPEnabled() {
t.Fatal("expected SOCKS5UDPEnabled=true")
}
c6, _, rep6 := socks5UDPAssociate(t, addrOn, false, socks5AtypIPv6, "::", 0)
_ = c6.Close()
if rep6 != socks5RepAtypNotSupported {
t.Fatalf("IPv6 UDP ASSOCIATE rep = 0x%02x, want 0x%02x", rep6, socks5RepAtypNotSupported)
}
}
func TestSOCKS5UDPAssociateRelayStoreAndControlConnClose(t *testing.T) {
prev := egress.CurrentProfile()
t.Cleanup(func() { egress.SetProfile(prev) })
egress.SetProfile(egress.Profile{Name: "off"})
echo, received := startUDPEchoServer(t, "127.0.0.1:0")
echoAddr := echo.LocalAddr().(*net.UDPAddr)
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
baseG := runtime.NumGoroutine()
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
})
if err != nil {
t.Fatal(err)
}
ctrl, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, true, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("UDP ASSOCIATE rep = 0x%02x, want 0x00", rep)
}
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
// 1. Send a FRAG != 0 datagram first: must be dropped silently (no fragmentation reassembly).
fragPkt := makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x01, []byte("fragment-must-drop"))
if _, err := cliUDP.WriteToUDP(fragPkt, relayAddr); err != nil {
t.Fatal(err)
}
// 2. Send a valid IPv4 datagram and verify echoed reply.
msg1 := []byte("hello-socks5-udp-ipv4")
if _, err := cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, msg1), relayAddr); err != nil {
t.Fatal(err)
}
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
buf := make([]byte, 4096)
n, _, err := cliUDP.ReadFromUDP(buf)
if err != nil {
t.Fatalf("read udp reply 1: %v", err)
}
_, repHost, repPort, repPayload, err := parseSOCKS5UDPHeader(buf[:n])
if err != nil {
t.Fatalf("parse reply 1 header: %v", err)
}
want1 := append([]byte("UDP-ECHO:"), msg1...)
if repHost != "127.0.0.1" || repPort != echoAddr.Port || !bytes.Equal(repPayload, want1) {
t.Fatalf("reply 1 = (%s:%d, %q), want (127.0.0.1:%d, %q)", repHost, repPort, repPayload, echoAddr.Port, want1)
}
// 3. Send a valid domain-addressed datagram ("localhost") and verify echoed reply.
msg2 := []byte("hello-socks5-udp-domain")
if _, err := cliUDP.WriteToUDP(makeClientUDPPacketDomain("localhost", echoAddr.Port, msg2), relayAddr); err != nil {
t.Fatal(err)
}
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
n, _, err = cliUDP.ReadFromUDP(buf)
if err != nil {
t.Fatalf("read udp reply 2: %v", err)
}
_, _, _, repPayload2, err := parseSOCKS5UDPHeader(buf[:n])
if err != nil {
t.Fatalf("parse reply 2 header: %v", err)
}
want2 := append([]byte("UDP-ECHO:"), msg2...)
if !bytes.Equal(repPayload2, want2) {
t.Fatalf("reply 2 = %q, want %q", repPayload2, want2)
}
// Only the 2 valid datagrams reached upstream (fragmented datagram was dropped).
if got := received.Load(); got != 2 {
t.Fatalf("upstream received %d datagrams, want 2", got)
}
// Verify 4 SQLite raw_udp_datagrams rows (2 c2s + 2 s2c), same association_id, 0 HTTP exchanges.
rows := waitForUDPDatagrams(t, tr, 4)
if len(rows) != 4 {
t.Fatalf("want 4 raw UDP datagram rows, got %d", len(rows))
}
assocID := rows[0].AssociationID
if !strings.HasPrefix(assocID, "udpa-") {
t.Fatalf("unexpected association_id %q", assocID)
}
var c2sCount, s2cCount int
for _, r := range rows {
if r.AssociationID != assocID || r.Protocol != "udp" || r.Port != echoAddr.Port || r.Timestamp <= 0 {
t.Fatalf("unexpected row metadata: %+v", r)
}
switch r.Direction {
case "c2s":
c2sCount++
case "s2c":
s2cCount++
default:
t.Fatalf("unexpected direction %q", r.Direction)
}
}
if c2sCount != 2 || s2cCount != 2 {
t.Fatalf("direction counts = (c2s=%d, s2c=%d), want (2, 2)", c2sCount, s2cCount)
}
var httpRows int
if err := tr.DB().QueryRow(`SELECT COUNT(*) FROM exchanges`).Scan(&httpRows); err != nil || httpRows != 0 {
t.Fatalf("HTTP exchanges rows = (%d, %v), want 0", httpRows, err)
}
// 4. Closing TCP control connection must tear down the UDP association promptly.
_ = ctrl.Close()
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
if runtime.NumGoroutine() <= baseG+6 {
break
}
time.Sleep(25 * time.Millisecond)
}
beforeAfterClose := received.Load()
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("after-close")), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(150 * time.Millisecond))
if _, _, rerr := cliUDP.ReadFromUDP(buf); rerr == nil {
t.Fatal("expected no UDP reply after TCP control connection closed")
}
if received.Load() != beforeAfterClose {
t.Fatal("datagram was forwarded after TCP control connection closed")
}
}
func TestSOCKS5UDPPolicyPerDestinationTargetGateAndGovernor(t *testing.T) {
t.Run("target_gate_drops_denied_destination_without_passthrough", func(t *testing.T) {
prev := egress.CurrentProfile()
t.Cleanup(func() { egress.SetProfile(prev) })
egress.SetProfile(egress.Profile{Name: "off"})
deniedEcho, deniedCount := startUDPEchoServer(t, "127.0.0.1:0")
allowedEcho, allowedCount := startUDPEchoServer(t, "127.0.0.1:0")
deniedAddr := deniedEcho.LocalAddr().(*net.UDPAddr)
allowedAddr := allowedEcho.LocalAddr().(*net.UDPAddr)
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
deniedKey := net.JoinHostPort(deniedAddr.IP.String(), strconv.Itoa(deniedAddr.Port))
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
ResolveUDP4: func(ctx context.Context, addr string) (*net.UDPAddr, error) {
if addr == deniedKey {
return nil, errors.New("blocked by target gate")
}
return net.ResolveUDPAddr("udp4", addr)
},
})
if err != nil {
t.Fatal(err)
}
ctrl, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, false, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("rep = 0x%02x", rep)
}
defer ctrl.Close()
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
// Datagram to denied destination must be dropped cleanly.
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(deniedAddr.IP, deniedAddr.Port, 0x00, []byte("denied")), relayAddr)
// Subsequent datagram to allowed destination on the SAME association succeeds.
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(allowedAddr.IP, allowedAddr.Port, 0x00, []byte("allowed")), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
buf := make([]byte, 2048)
n, _, err := cliUDP.ReadFromUDP(buf)
if err != nil {
t.Fatalf("allowed destination reply failed: %v", err)
}
_, _, gotPort, gotPayload, err := parseSOCKS5UDPHeader(buf[:n])
if err != nil || gotPort != allowedAddr.Port || string(gotPayload) != "UDP-ECHO:allowed" {
t.Fatalf("unexpected reply: port=%d payload=%q err=%v", gotPort, gotPayload, err)
}
if deniedCount.Load() != 0 {
t.Fatalf("denied target received %d datagrams, want 0", deniedCount.Load())
}
if allowedCount.Load() != 1 {
t.Fatalf("allowed target received %d datagrams, want 1", allowedCount.Load())
}
rows := waitForUDPDatagrams(t, tr, 2)
for _, r := range rows {
if r.Port == deniedAddr.Port {
t.Fatalf("denied destination recorded in store: %+v", r)
}
}
})
t.Run("pinned_udp_resolver_fails_closed_without_interceptor", func(t *testing.T) {
prev := egress.CurrentProfile()
t.Cleanup(func() { egress.SetProfile(prev) })
egress.SetProfile(egress.Profile{Name: "off"})
echo, count := startUDPEchoServer(t, "127.0.0.1:0")
echoAddr := echo.LocalAddr().(*net.UDPAddr)
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
BaseContext: func() context.Context {
return intercept.WithTargetScope(context.Background(), intercept.TargetScope{
TaskID: "77",
Enabled: func() bool { return true },
})
},
ResolveUDP4: intercept.PinnedUDP4Resolver("socks5-udp", true),
})
if err != nil {
t.Fatal(err)
}
ctrl, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, false, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("rep = 0x%02x", rep)
}
defer ctrl.Close()
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("gated-out")), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(200 * time.Millisecond))
buf := make([]byte, 512)
if _, _, rerr := cliUDP.ReadFromUDP(buf); rerr == nil {
t.Fatal("expected gated datagram to be dropped")
}
if count.Load() != 0 {
t.Fatalf("gated target received %d datagrams, want 0", count.Load())
}
})
t.Run("egress_governor_drops_datagram_before_forwarding", func(t *testing.T) {
prev := egress.CurrentProfile()
t.Cleanup(func() { egress.SetProfile(prev) })
egress.SetProfile(egress.Profile{Name: "tight", RPS: 0.01, Burst: 1, MaxPerHost: 1, MaxGlobal: 1})
echo, count := startUDPEchoServer(t, "127.0.0.1:0")
echoAddr := echo.LocalAddr().(*net.UDPAddr)
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
PaceTimeout: 40 * time.Millisecond,
})
if err != nil {
t.Fatal(err)
}
ctrl, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, true, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("rep = 0x%02x", rep)
}
defer ctrl.Close()
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
// 1st datagram consumes the single burst token.
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("first")), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
buf := make([]byte, 512)
if _, _, err := cliUDP.ReadFromUDP(buf); err != nil {
t.Fatalf("first datagram failed: %v", err)
}
// 2nd datagram exceeds PaceTimeout and is dropped before forwarding.
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("second-paced-out")), relayAddr)
_ = cliUDP.SetReadDeadline(time.Now().Add(200 * time.Millisecond))
if _, _, rerr := cliUDP.ReadFromUDP(buf); rerr == nil {
t.Fatal("expected governor-refused 2nd datagram to be dropped")
}
if got := count.Load(); got != 1 {
t.Fatalf("upstream received %d datagrams, want 1", got)
}
})
}
func TestSOCKS5UDPAssociationBoundsAndBlobSpill(t *testing.T) {
prev := egress.CurrentProfile()
t.Cleanup(func() { egress.SetProfile(prev) })
egress.SetProfile(egress.Profile{Name: "off"})
echo, _ := startUDPEchoServer(t, "127.0.0.1:0")
echoAddr := echo.LocalAddr().(*net.UDPAddr)
t.Run("blob_spill_and_max_datagrams", func(t *testing.T) {
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
UDPMaxDatagrams: 2, // 1 c2s + 1 s2c
UDPPreviewBytes: 64,
})
if err != nil {
t.Fatal(err)
}
ctrl, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, false, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("rep = 0x%02x", rep)
}
defer ctrl.Close()
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
big := bytes.Repeat([]byte("UDPBLOB!"), 64) // 512 bytes > 64 preview
if _, err := cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, big), relayAddr); err != nil {
t.Fatal(err)
}
_ = cliUDP.SetReadDeadline(time.Now().Add(2 * time.Second))
buf := make([]byte, 4096)
if _, _, err := cliUDP.ReadFromUDP(buf); err != nil {
t.Fatalf("read reply: %v", err)
}
rows := waitForUDPDatagrams(t, tr, 2)
var c2sRow *RawUDPDatagram
for i := range rows {
if rows[i].Direction == "c2s" {
c2sRow = &rows[i]
}
}
if c2sRow == nil || c2sRow.Size != 512 || len(c2sRow.Preview) != 64 || c2sRow.Blob == "" {
t.Fatalf("expected 512-byte datagram with 64-byte preview and blob hash, got %+v", c2sRow)
}
blobFile := filepath.Join(tr.dir, "_blobs", "sha256", c2sRow.Blob[:2], c2sRow.Blob+".bin")
blobData, err := os.ReadFile(blobFile)
if err != nil || !bytes.Equal(blobData, big) {
t.Fatalf("blob read %s: len=%d err=%v", blobFile, len(blobData), err)
}
var refs int
if err := tr.DB().QueryRow(`SELECT COUNT(*) FROM blob_refs WHERE exchange_id = ?`, c2sRow.ID).Scan(&refs); err != nil || refs != 1 {
t.Fatalf("blob_refs for %s = (%d, %v), want 1", c2sRow.ID, refs, err)
}
// 3rd datagram exceeds UDPMaxDatagrams=2 and closes the association (and TCP control conn).
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("over-limit")), relayAddr)
_ = ctrl.SetReadDeadline(time.Now().Add(2 * time.Second))
one := make([]byte, 1)
if _, rerr := ctrl.Read(one); rerr == nil {
t.Fatal("expected TCP control conn to close when UDPMaxDatagrams exceeded")
}
})
t.Run("max_bytes_and_idle_timeout", func(t *testing.T) {
tr, err := Open(t.TempDir(), "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer tr.Close()
proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{
Addr: "127.0.0.1:0",
EnableUDP: true,
UDPMaxBytes: 16,
UDPIdleTimeout: 150 * time.Millisecond,
})
if err != nil {
t.Fatal(err)
}
// Idle timeout closes association without any datagrams.
ctrlIdle, _, rep := socks5UDPAssociate(t, proxyAddr, false, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("idle rep = 0x%02x", rep)
}
_ = ctrlIdle.SetReadDeadline(time.Now().Add(2 * time.Second))
one := make([]byte, 1)
if _, rerr := ctrlIdle.Read(one); rerr == nil {
t.Fatal("expected idle UDP association to close after UDPIdleTimeout")
}
_ = ctrlIdle.Close()
// MaxBytes=16 rejects a 32-byte datagram and closes the association.
ctrlBytes, relayAddr, rep := socks5UDPAssociate(t, proxyAddr, false, socks5AtypIPv4, "0.0.0.0", 0)
if rep != socks5RepSuccess {
t.Fatalf("bytes rep = 0x%02x", rep)
}
defer ctrlBytes.Close()
cliUDP, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
if err != nil {
t.Fatal(err)
}
defer cliUDP.Close()
_, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, bytes.Repeat([]byte("A"), 32)), relayAddr)
_ = ctrlBytes.SetReadDeadline(time.Now().Add(2 * time.Second))
if _, rerr := ctrlBytes.Read(one); rerr == nil {
t.Fatal("expected UDP association to close when UDPMaxBytes exceeded")
}
})
}
+22
View File
@@ -136,6 +136,28 @@ CREATE TABLE IF NOT EXISTS raw_tcp_streams (
);
CREATE INDEX IF NOT EXISTS idx_raw_tcp_host ON raw_tcp_streams(host);
CREATE INDEX IF NOT EXISTS idx_raw_tcp_started ON raw_tcp_streams(started_at DESC, id DESC);
-- Raw UDP datagrams relayed through opt-in SOCKS5 UDP ASSOCIATE (P4.1c).
-- Stored separately from HTTP exchanges: a UDP datagram never creates a row
-- in exchanges. No fragmentation reassembly is performed: each forwarded
-- datagram is recorded individually as it arrives. Oversized payloads spill
-- atomically to _blobs/sha256 and register their hashes in blob_refs under
-- the datagram's udp-* id.
CREATE TABLE IF NOT EXISTS raw_udp_datagrams (
id TEXT PRIMARY KEY,
association_id TEXT NOT NULL,
protocol TEXT NOT NULL DEFAULT 'udp',
host TEXT NOT NULL,
port INTEGER NOT NULL,
direction TEXT NOT NULL, -- 'c2s' | 's2c'
ts INTEGER NOT NULL, -- unix milliseconds
size INTEGER NOT NULL DEFAULT 0, -- datagram payload bytes
preview BLOB,
blob TEXT
);
CREATE INDEX IF NOT EXISTS idx_raw_udp_assoc ON raw_udp_datagrams(association_id, ts);
CREATE INDEX IF NOT EXISTS idx_raw_udp_host ON raw_udp_datagrams(host);
CREATE INDEX IF NOT EXISTS idx_raw_udp_ts ON raw_udp_datagrams(ts DESC, id DESC);
`
// ftsSchema is applied separately from indexSchema: a driver build without FTS5