interceptor

Module: interceptor

Contents

Modules

• grpc - gRPC hook interceptor.
• http - HTTP proxy interceptor.
• unix_socket - Unix domain socket interceptor.

Enums

• InterceptorError - An error that can occur on an [Interceptor].

Traits

• Interceptor - Entry point that captures outbound agent traffic before it reaches external systems.

---

firma_sidecar::interceptor::Interceptor

Trait

Entry point that captures outbound agent traffic before it reaches external systems.

Every outbound agent call must pass through an [Interceptor] before reaching the target. The interceptor converts transport-specific input into a RawRequest, runs it through the [RequestHandler], and serializes the resulting HandledResponse at the transport level.

Three interception modes are supported today:

Mode	Description
HTTP proxy	Listens on a configurable TCP port (default 8080). The agent sets HTTP_PROXY=http://localhost:<port>.
gRPC hook	Programmatic interceptor registered within the agent process — no port binding required.
Unix socket	Listens on a local Unix domain socket, avoiding port conflicts in containers.

An eBPF kernel-level capture mode is on the roadmap but out of scope for V1.

Contract

• The implementor must build a RawRequest from the incoming transport data and call RequestHandler::handle.
• If a request cannot be parsed into a valid RawRequest, the implementor must reply to the caller with a structured DENY carrying reason MALFORMED_REQUEST (fail-closed).
• On allow or passthrough, the implementor serializes the dispatched response returned by the handler.
• On deny, the implementor returns a structured denial to the caller.
• The implementor must stop accepting new connections and drain in-flight work when cancel is triggered, then return Ok(()).

Errors

Returns [InterceptorError] if the interceptor encounters an unrecoverable error.

Methods:

• run: Starts the interceptor loop, handling each request via handler.

firma_sidecar::interceptor::InterceptorError

Enum

An error that can occur on an [Interceptor].

Variants:

• BindFailed(String) - The interceptor failed to bind to the configured address or socket path.
• ServerError(String) - An unrecoverable server error occurred while the interceptor was running.

Traits: Error

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

Module: grpc

gRPC hook interceptor.

Implements the Interceptor trait as a Tonic gRPC server. The agent process registers this interceptor programmatically and calls the Intercept RPC for every outbound action — no port binding or proxy environment variable is required.

The service converts each InterceptRequest proto message into a RawRequest, passes it to the shared RequestHandler, and returns an InterceptResponse with the ALLOW / DENY result.

Module: http

HTTP proxy interceptor.

Implements the Interceptor trait using a TCP HTTP/1.1 proxy endpoint. The agent sets HTTP_PROXY=http://localhost:<port> and all outbound HTTP traffic flows through this interceptor before reaching external systems.

The interceptor parses each inbound request into a RawRequest, passes it to the shared RequestHandler, and writes the handled response downstream.

HTTPS CONNECT is supported in two modes:

• Transparent TCP tunneling (default, no MITM).
• Optional TLS MITM interception for configured hosts.

Module: unix_socket

Unix domain socket interceptor.

Implements the Interceptor trait over a Unix domain socket (UDS). The interceptor owns the full socket lifecycle: it removes any stale socket file, binds a [tokio::net::UnixListener], accepts connections, and unlinks the socket on shutdown.

Requests arrive as plain HTTP over the UDS and are parsed with hyper into RawRequest values — the same parsing logic used by the HTTP proxy mode. This mode avoids TCP port binding, making it well suited for containerized environments.