Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidRootCA is returned when the root CA PEM file does not // contain both a certificate and a matching RSA private key. ErrInvalidRootCA = errors.New("proxy: invalid root CA file") // ErrCircuitOpen is returned by cbTransport.RoundTrip when the // per-host circuit breaker is open for the target host. ErrCircuitOpen = errors.New("proxy: circuit open") // ErrUpstreamNotAllowed is returned when a CONNECT target resolves to a // loopback/link-local/private address and is not present in the // operator-configured --allow-host allowlist (SEC-0074, NEW-10). apimap // is a forward+CONNECT proxy that will otherwise dial any upstream host // an unauthenticated client asks for, which is a textbook SSRF pivot // into cloud metadata endpoints, kube-internal services, or the host's // own loopback surface. ErrUpstreamNotAllowed = errors.New("proxy: upstream host not permitted") )
Sentinel errors. Kept at package level per repo conventions.
Functions ¶
func NewTestHandler ¶
NewTestHandler exposes an http.Handler for tests without starting a server or a real proxy.Run listener. It exists purely to test the reverse-proxy/capture pipeline (Rewrite, ModifyResponse, sampling, body capture) against a local httptest.Server backend -- it never goes through Run's --allow-host wiring, so it allows every upstream host (the "*" glob) rather than applying the loopback/link-local/private SEC-0074 gate: proxying to a loopback httptest server is exactly what these tests do, and is not itself a use of the real apimap binary's network surface.
Types ¶
type CapturePolicy ¶
type CapturePolicy struct {
AllowedRequestHeaders []string
AllowedResponseHeaders []string
CaptureBodyValues bool
CaptureBodies bool
MaxBodyBytes int64
SampleRate float64
WSMaxFrames int // default 0
RedactJSONFields []string // JSON fields to mark as redacted (supports dot.paths for nested)
RedactHeaders []string // header names whose values should be treated as redacted (names still listed)
HashJSONFields []string // JSON fields to hash (SHA-256 hex truncated) instead of full value; applied after redaction
HashHeaders []string // Header names whose values should be hashed (per request/response) and stored in Event.Hashed with key header:<Name>
}
CapturePolicy configures what the proxy captures and how privacy-sensitive it is: which request/response header names are recorded (allow-lists; empty means all names), whether/how much of JSON bodies are captured (CaptureBodies gates structure capture, CaptureBodyValues additionally keeps literal primitive values), the per-body byte cap (MaxBodyBytes), the fraction of requests sampled for capture (SampleRate, 0..1), a cap on WebSocket frames captured per connection (WSMaxFrames, 0 = unlimited), and which JSON fields/headers get redacted (RedactJSONFields/RedactHeaders) or hashed instead of stored raw (HashJSONFields/HashHeaders).
type Mode ¶
type Mode int
Mode selects how the proxy handles a connection: plain passthrough tunneling/reverse-proxying (ModePassthrough) or TLS-terminating inspection/MITM capture (ModeInspect, only actually engaged for CONNECT when TLSConfig.EnableMITM is also set).
const ( // ModePassthrough forwards traffic without TLS termination: CONNECT // requests are tunneled byte-for-byte and plain requests are reverse // proxied, with capture applied only to what's visible in cleartext. ModePassthrough Mode = iota // ModeInspect enables TLS-terminating (MITM) inspection of CONNECT // tunnels when TLSConfig.EnableMITM is also set and a root CA is // available, decrypting HTTPS traffic so it can be captured like plain // HTTP. ModeInspect )
type Proxy ¶
type Proxy interface {
// Run starts the proxy listener. allowHosts is the operator-configured
// upstream allowlist (SEC-0074): a CONNECT target that resolves to a
// loopback/link-local/private address is refused unless it matches an
// entry here (exact host or glob). A nil/empty allowHosts still permits
// ordinary public hosts -- it only narrows the private ranges.
Run(ctx context.Context, addr string, mode Mode, pol CapturePolicy, tls TLSConfig, allowHosts []string) error
}
Proxy is the forward/CONNECT/MITM capture proxy built by New, NewWith, and NewWithRecorder. It is an unauthenticated proxy by design (see the package's SEC-0074 upstream-allowlist notes on Run) -- callers are responsible for network placement and the allowHosts gate.
func New ¶
func New() Proxy
New returns a Proxy with no recorder callback and no gRPC decoder: it still proxies/captures per the CapturePolicy passed to Run, but every captured Event is discarded (never handed to a recorder) and gRPC bodies are never decoded into structural schemas.
func NewWith ¶
NewWith returns a Proxy that invokes rec with every captured Event and additionally uses dec to decode gRPC request/response bodies into structural schemas (populating Event.GRPC.ReqSchema/ResSchema) when the service/method can be resolved.
func NewWithRecorder ¶
NewWithRecorder returns a Proxy that invokes rec with every captured Event (e.g. to append it to a recorder.WAL). rec's error is propagated back through the response-capture path. gRPC bodies are not decoded (equivalent to New plus a recorder).
type TLSConfig ¶
TLSConfig controls the proxy's TLS-terminating MITM capability: EnableMITM turns it on for CONNECT tunnels handled under ModeInspect, and RootCAPath names the root CA certificate (with a sibling private key file, or a legacy combined file -- see ensureRootCA/loadRootCA) used to mint per-host leaf certificates on the fly. Leaving EnableMITM false means CONNECT traffic is always tunneled untouched regardless of Mode.
Source Files