Network External Processing Service (proto)

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

The Network External Processing filter allows an external service to dynamically interact with and modify L4 network traffic passing through Envoy. Unlike the HTTP External Processing filter, this service operates at the TCP/UDP level, providing access to raw network data.

The filter communicates with an external gRPC service that can: * Inspect network traffic in both directions (client->server and server->client) * Modify the payload data * Control connection lifecycle (continue, close gracefully, or reset)

Use cases include: * Custom protocol inspection and modification * Advanced traffic manipulation * Security scanning and filtering * Dynamic connection management

The service uses a bidirectional gRPC stream, maintaining state throughout the connection lifetime while allowing asynchronous processing.

service.network_ext_proc.v3.Data

[service.network_ext_proc.v3.Data proto]

The payload data from network layer

{
  "data": ...,
  "end_of_stream": ...
}

data: (bytes) The raw payload data

end_of_stream: (bool) Indicates whether this is the last data frame in the current direction. The external processor should still respond to this message even if there is no more data expected in this direction.

service.network_ext_proc.v3.ProcessingRequest

[service.network_ext_proc.v3.ProcessingRequest proto]

ProcessingRequest contains data sent from Envoy to the external processing server. Each request contains either read data (from client) or write data (to client) along with optional metadata.

{
  "read_data": {...},
  "write_data": {...},
  "metadata": {...}
}

read_data: (service.network_ext_proc.v3.Data) ReadData contains the network data intercepted in the request path (client to server). This is sent to the external processor when data arrives from the downstream client. If this is set, write_data should not be set.

write_data: (service.network_ext_proc.v3.Data) WriteData contains the network data intercepted in the response path (server to client). This is sent to the external processor when data arrives from the upstream server. If this is set, read_data should not be set.

metadata

(config.core.v3.Metadata) Optional metadata associated with the request. This can include connection properties, filter configuration, and any other contextual information that might be useful for processing decisions.

The metadata is not automatically propagated from request to response. The external processor must include any needed metadata in its response.

service.network_ext_proc.v3.ProcessingResponse

[service.network_ext_proc.v3.ProcessingResponse proto]

ProcessingResponse contains the response from the external processing server to Envoy. Each response corresponds to a ProcessingRequest and indicates how the network traffic should be handled.

{
  "read_data": {...},
  "write_data": {...},
  "data_processing_status": ...,
  "connection_status": ...,
  "dynamic_metadata": {...}
}

read_data: (service.network_ext_proc.v3.Data) The processed ReadData containing potentially modified data for the request path. This should be sent in response to a ProcessingRequest with read_data, and the previous data in ProcessingRequest will be replaced by the new data in Envoy’s data plane. If this is set, write_data should not be set.

write_data: (service.network_ext_proc.v3.Data) The processed WriteData containing potentially modified data for the response path. This should be sent in response to a ProcessingRequest with write_data, and the previous data in ProcessingRequest will be replaced by the new data in Envoy’s data plane. If this is set, read_data should not be set.

data_processing_status: (service.network_ext_proc.v3.ProcessingResponse.DataProcessedStatus) Indicates whether the data was modified or not. This is mandatory and tells Envoy whether to use the original or modified data.

connection_status: (service.network_ext_proc.v3.ProcessingResponse.ConnectionStatus) Optional: Determines the connection behavior after processing. If not specified, CONTINUE is assumed, and the connection proceeds normally. Use CLOSE or CLOSE_RST to terminate the connection based on processing results.

dynamic_metadata

(Struct) Optional metadata associated with the request. This can include connection properties, filter configuration, and any other contextual information that might be useful for processing decisions.

The metadata is not automatically propagated from request to response. The external processor must include any needed metadata in its response.

Enum service.network_ext_proc.v3.ProcessingResponse.DataProcessedStatus

[service.network_ext_proc.v3.ProcessingResponse.DataProcessedStatus proto]

DataProcessedStatus indicates whether the data was modified by the external processor.

UNKNOWN: (DEFAULT) ⁣The data processed status is unknown.

UNMODIFIED: ⁣The data remains unchanged. Envoy will use the original data. This is useful when the processor only wants to inspect but not modify the traffic.

MODIFIED: ⁣The data has been modified. Envoy will use the modified data provided in the response. This allows the processor to transform the network traffic as needed.

Enum service.network_ext_proc.v3.ProcessingResponse.ConnectionStatus

[service.network_ext_proc.v3.ProcessingResponse.ConnectionStatus proto]

ConnectionStatus determines what happens to the connection after processing.

CONTINUE: (DEFAULT) ⁣Continue normal processing of the connection. This is the default behavior and allows traffic to flow normally.

CLOSE: ⁣Close the connection with normal TCP FIN. This allows for clean connection termination with a normal close sequence. Any buffered data will be sent before closing.

CLOSE_RST: ⁣Immediately reset the connection with TCP RST. This forcibly terminates the connection without a clean shutdown, discarding any buffered data. Use this for security-critical situations or when immediate termination is required.