Documentation
¶
Index ¶
- Constants
- func BoundedRedirects(maxHops int) func(*http.Request, []*http.Request) error
- func ContextWithSessionID(ctx context.Context, id string) context.Context
- func HTTPSOnlyRedirects(maxHops int) func(*http.Request, []*http.Request) error
- func IsPublicIP(ip net.IP) bool
- func LocalhostOnlyRedirects(maxHops int) func(*http.Request, []*http.Request) error
- func NewHTTPClient(ctx context.Context, opts ...Opt) *http.Client
- func NewSSRFSafeTransport() *http.Transport
- func NewSafeClient(timeout time.Duration, unsafe bool) *http.Client
- func SSRFDialControl(_, address string, _ syscall.RawConn) error
- func SessionIDFromContext(ctx context.Context) string
- func SetOTelEnabled(enabled bool)
- func TracedClient(opts ...func(*http.Client)) *http.Client
- func TracedDefaultClient() *http.Client
- func WrapWithOTel(rt http.RoundTripper) http.RoundTripper
- type HTTPOptions
- type Opt
Constants ¶
const DefaultToolHTTPTimeout = 30 * time.Second
DefaultToolHTTPTimeout is the HTTP client timeout used by the built-in HTTP-based toolsets (`fetch`, `api`, `openapi`, `a2a`) when the operator does not override it via `timeout:` in the agent config.
Centralised so the four toolsets agree on a single default — changing this value uniformly affects every HTTP-based built-in tool.
Variables ¶
This section is empty.
Functions ¶
func BoundedRedirects ¶ added in v1.55.0
BoundedRedirects returns an http.Client.CheckRedirect that limits a redirect chain to maxHops. SSRF on each redirect target is enforced by the transport's dialer; this only prevents infinite loops.
func ContextWithSessionID ¶ added in v1.55.0
ContextWithSessionID returns a new context carrying the given session ID. When set, [userAgentTransport.RoundTrip] forwards it as the `X-Cagent-Session-Id` header — but only on gateway-bound requests (those already carrying `X-Cagent-Forward`), to keep the identifier out of direct provider calls and unrelated outbound HTTP.
func HTTPSOnlyRedirects ¶ added in v1.55.0
HTTPSOnlyRedirects returns an http.Client.CheckRedirect that limits the redirect chain to maxHops AND rejects redirects whose Location is not https://. Use this when the original request is required to be HTTPS and a TLS downgrade through a Location header must be prevented.
func IsPublicIP ¶ added in v1.55.0
IsPublicIP reports whether ip is a routable public address. It rejects loopback (127/8, ::1), RFC1918 private ranges, link-local (incl. the 169.254.169.254 cloud metadata endpoint), multicast, the unspecified address (0.0.0.0, ::), CGNAT (100.64.0.0/10), IPv6 6to4, NAT64, and site-local prefixes.
func LocalhostOnlyRedirects ¶ added in v1.78.0
LocalhostOnlyRedirects returns an http.Client.CheckRedirect that limits the redirect chain to maxHops AND requires every redirect target to be an http://localhost URL. This prevents a localhost service from redirecting to internal network addresses (e.g. cloud metadata endpoints), which would bypass SSRF protection.
func NewSSRFSafeTransport ¶ added in v1.55.0
NewSSRFSafeTransport returns an http.Transport whose dialer enforces SSRFDialControl on every connection.
When http.DefaultTransport is a plain *http.Transport (the default), the returned transport is a Clone() of it, inheriting proxy, TLS, idle-pool and HTTP/2 settings. When DefaultTransport has been replaced by a wrapper (e.g. an application that swapped in otelhttp.NewTransport for global observability) the clone is not possible; the function falls back to a minimal transport with proxy support and emits a warning via log/slog. In either case the SSRF dial guard is active.
Use this for outbound HTTP that may follow attacker-influenced URLs (OpenAPI specs whose servers[] list is taken from the spec body, user-configured API endpoints, etc.). It does not enforce HTTPS — callers that require it must validate the request URL themselves and/or supply a CheckRedirect on the surrounding *http.Client.
As an exception, the explicitly-configured HTTP/HTTPS/ALL proxy is always dialable, even if it lives on a private address. Refusing to dial the operator-configured proxy adds no SSRF protection (the proxy enforces destination policy itself) and breaks sandboxes — like docker-agent's — whose mandatory egress proxy is on an RFC1918 IP.
func NewSafeClient ¶ added in v1.55.0
NewSafeClient returns the HTTP client used by built-in tools that issue outbound calls to URLs the operator (or a fetched OpenAPI spec) supplies.
The default refuses connections to non-public IPs at dial time — defeating DNS rebinding to loopback / RFC1918 / link-local incl. cloud metadata at 169.254.169.254 — and bounds the redirect chain at 10 hops.
When unsafe is true the client uses http.DefaultTransport. This branch exists ONLY for tests, which use [httptest.NewServer] (binds to 127.0.0.1) and therefore cannot pass the SSRF check.
func SSRFDialControl ¶ added in v1.55.0
SSRFDialControl is invoked by net.Dialer after DNS resolution but before the TCP handshake. It rejects addresses that are not safe to fetch from over the public internet.
Performing the check post-resolution defeats DNS rebinding: an attacker cannot point a public hostname at 127.0.0.1 or 169.254.169.254 to bypass us, because we re-validate the resolved IP itself.
func SessionIDFromContext ¶ added in v1.55.0
SessionIDFromContext returns the session ID stored on ctx by ContextWithSessionID, or the empty string if none is set.
func SetOTelEnabled ¶ added in v1.86.0
func SetOTelEnabled(enabled bool)
SetOTelEnabled toggles the gate consulted by WrapWithOTel. Called by `initOTelSDK` after providers and the propagator are wired so HTTP clients start injecting `traceparent` only once the rest of the SDK can actually use the resulting spans.
func TracedClient ¶ added in v1.86.0
TracedClient returns a configurable `http.Client` with the default transport already wrapped via `WrapWithOTel`. The supplied options (timeout, redirect policy, jar, etc.) are applied after construction. Convenience wrapper for short-lived clients with custom timeouts.
func TracedDefaultClient ¶ added in v1.86.0
TracedDefaultClient returns an `http.Client` equivalent to `http.DefaultClient` but with the default transport wrapped via `WrapWithOTel`. Use as a drop-in replacement at call sites that previously did `http.DefaultClient.Do(req)` so OAuth metadata fetches, fetch-tool requests, registry probes, and similar one-off HTTP calls chain into the active trace.
func WrapWithOTel ¶ added in v1.55.0
func WrapWithOTel(rt http.RoundTripper) http.RoundTripper
WrapWithOTel returns rt wrapped with otelhttp when OpenTelemetry has been enabled via `SetOTelEnabled` (called by `initOTelSDK`), or rt unchanged otherwise. Gating avoids per-request span allocation on the no-OTel path and stops sending a `traceparent` header to upstream LLM providers that have no use for it. Exposed so callers that build their own transports outside of `NewHTTPClient` can opt into the same gating without duplicating the check.
Types ¶
type Opt ¶
type Opt func(*HTTPOptions)
Source Files