proxy

Documentation

Overview

Package proxy implements the HTTPS AiTM (adversary-in-the-middle) reverse proxy.

Connection lifecycle

Every inbound TCP connection goes through the same sequence:

1. Wrapped in a [peekedConn] that tees the first TLS record into a buffer, so the raw ClientHello bytes are available for JA4 fingerprinting before the handshake consumes them.

2. TLS handshake completes. GetCertificate selects the right phishing certificate by SNI. mTLS (RequireAndVerifyClientCert) is applied only when the ClientHello SNI matches the configured secret management hostname — phishing victims are never prompted for a client certificate.

3. A connection is created via newConnection. The constructor sets up immutable TLS-level state (JA4 hash, TLS connection state). The initSession method then processes the first HTTP request to perform connection-level setup: IP extraction, bot detection, blacklist check, phishlet/lure resolution, and session creation.

4. HTTP/1.1 requests are read in a keep-alive loop by [connection.serve]. Each request is handled by [connection.handleRequest], which runs the per-request logic, forwards to upstream, and processes the response.

Connection setup (initSession)

These checks run once per connection during initSession:

• JA4 hash computed from ClientHello bytes
• Client IP extracted from socket or trusted CDN headers
• Bot guard check (L1) — JA4 signature lookup; spoofs or blocks known bots
• Blacklist check — spoofs blocked IPs
• Phishlet/lure resolution from hostname
• Lure validation (paused, UA filter)
• Session creation or loading from tracking cookie
• Puppet override lookup

Per-request handling (handleRequest)

All response writing is centralized in handleRequest. Handler methods only make decisions or mutate the request/response in place.

• Completed session redirect — 302 to lure redirect URL if session is done
• Intercept — returns static response for matching paths
• Lure path rewrite — rewrites lure URL to login path
• Telemetry score check (L2) — spoofs high-scoring sessions
• URL rewrite — rewrites Host, URL, Origin, Referer to upstream domain
• Credential extraction — captures username/password from POST bodies
• Force POST injection — injects/overrides POST parameters

After forwarding upstream:

• Security header stripping — removes CSP, HSTS, X-Frame-Options, etc.
• Token extraction — captures auth cookies, headers, and body tokens
• Cookie rewriting — rewrites Set-Cookie domains; injects tracking cookie
• Sub-filter application — regex search/replace on response bodies
• JS injection — telemetry, redirect, puppet override, and custom scripts
• JS obfuscation — transforms injected scripts via Node.js sidecar

Post-capture redirect flow

When token extraction marks a session complete it publishes [sdk.EventSessionCompleted]. The redirect notifier (see internal/redirect) subscribes to this event and fans the redirect URL out to all WebSocket connections waiting on that session ID. On the next request, handleRequest detects the completed session and returns a 302 redirect to the lure's redirect URL.

A fallback polling endpoint GET /t/{sessionID}/done is also available for environments where WebSocket connections are not reliable.

Index

• Constants
• type Server
  • func (s *Server) ListenAndServe(ctx context.Context) error

Constants

const SessionCookieName = "__ss"

SessionCookieName is the name of the session tracking cookie set on victims.

Types

type Server

type Server struct {
	// Addr is the TCP address to listen on, e.g. ":443".
	Addr string

	// CertSource provides TLS certificates for incoming connections.
	// The GetCertificate callback is invoked during each TLS handshake
	// with the SNI hostname from the ClientHello.
	CertSource certSource

	// APICertificate is the TLS certificate served for the management API
	// (SecretHostname). It is signed by the API CA so clients that trust
	// only the API CA can verify the connection.
	APICertificate *tls.Certificate

	// ClientCAs specifies the certificate authority pool used to verify
	// client certificates for the management API. Only connections to
	// SecretHostname require a client certificate; phishing victims are
	// never prompted.
	ClientCAs *x509.CertPool

	// SecretHostname is the SNI hostname that triggers mTLS for the
	// management API. Requests to this hostname are routed to APIHandler
	// instead of the phishing pipeline. If empty, mTLS is disabled.
	SecretHostname string

	// UpstreamTransport optionally specifies the http.RoundTripper used
	// for requests to upstream (legitimate) servers. If nil, Serve creates
	// a default http.Transport with sensible timeouts and TLS verification
	// enabled. Set this in tests to intercept or stub upstream traffic
	// without making real network calls.
	UpstreamTransport http.RoundTripper

	// Notifier delivers session-completion signals to victim browsers,
	// triggering the post-capture redirect.
	Notifier redirectNotifier

	// APIHandler serves management API requests on SecretHostname.
	APIHandler http.Handler

	// Logger is used for structured logging throughout the proxy.
	// If nil, the server will panic on first log call.
	Logger *slog.Logger

	// ScoreThreshold is the bot detection score above which a connection
	// is spoofed. Telemetry scores are accumulated per-session and checked
	// on each request. Values typically range from 0.0 (human) to 1.0 (bot).
	ScoreThreshold float64

	// TrustedCIDRs lists upstream proxy/CDN networks whose X-Forwarded-For
	// and True-Client-IP headers are trusted for client IP extraction.
	// If empty, the client IP is taken from the TCP connection's remote address.
	TrustedCIDRs []*net.IPNet

	// Services
	BotGuard     botEvaluator
	Blacklist    ipBlocker
	Spoofer      spoofer
	PhishletSvc  phishletResolver
	SessionSvc   sessionManager
	LureSvc      lureParamDecryptor
	PuppetSvc    puppetOverrideSource
	TelemetrySvc telemetryScorer
	Obfuscator   bodyObfuscator
	// contains filtered or unexported fields
}

Server is a reverse-proxy HTTPS server. It accepts raw TCP connections on port 443, peeks at the TLS ClientHello to capture bytes for JA4 fingerprinting, completes the TLS handshake using the SNI hostname to select the right certificate, then creates a connection for each victim and handles HTTP requests.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context) error

ListenAndServe listens on s.Addr and blocks until ctx is cancelled.