Configuring gRPC proxy deployments

You can configure the Next-Gen WAF agent as a proxy for gRPC traffic to allow inspection of protobuf-based gRPC messages (Content-Type: application/grpc). You can create rules for gRPC traffic.

Configuring the agent

To configure sigsci-agent as a proxy for gRPC traffic, you'll need to edit the agent configuration.

Setting the maximum gRPC message length

You should adjust the maximum gRPC message length to limit the size of messages that are proxied.

inspection-max-content-length = 307200

The reverse proxy returns a Received message larger than maxsize error if the gRPC message size exceeds the configured value.

Creating the reverse proxy gRPC listener

Here's an example reverse proxy listener proxying gRPC from port 9000 to 9001 with TLS.

1
2
3
4
5
6
7
8
9
10

[revproxy-listener.9000]
inspection-debug = true
listener = "https://127.0.0.1:9000"
upstreams = "https://127.0.0.1:9001"
tls-key = "/etc/sigsci/key.pem"
tls-cert = "/etc/sigsci/cert.pem"
tls-ca-roots = "/etc/sigsci/cert.pem"
grpc = true
tls-verify-servername = "test.signalsciences-dev.net"
#tls-insecure-skip-verify = true

You can enable gRPC mode by setting grpc to true.

grpc = true

Only one upstream is supported for gRPC. The upstream server should support HTTP/2.

Both HTTPS and HTTP are supported for the listener and upstream, but we recommend using HTTPS. If you use HTTPS for the listener, you must specify tls-key and tls-cert. If you want to verify the HTTPS certificate of the upstream, you must specify tls-ca-roots.

Troubleshooting configuration errors

Try using the following troubleshooting tips if you run into errors:

• certificate signed by unknown authority: If the request hostname doesn't match the one specified in the upstream certificate, then the connection will fail (e.g., you connected with an IP address instead of a hostname). Set tls-verify-servername to a hostname that's valid for the certificate. If all else fails, try using tls-insecure-skip-verify = true to get TLS validation working.
• remote error: tls: bad certificate or cannot validate certificate for [ip address] because it doesn't contain any IP SANs: If you're having issues, you can enable HTTP/2 debug output. Start the agent with the GODEBUG variable set to one of the following: GODEBUG="http2debug=1" provides basic connection and frame debugging information, and GODEBUG="http2debug=2" provides verbose data.

Using rules

You can create rules for gRPC traffic. For gRPC traffic that uses protobuf-encoding, PostArgs will be populated with a set of key-value pairs representing the arguments. The key will be an index (1-N) for the message field assigned in the proto file. Only string types are added to PostArgs.

For example, consider this proto file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

syntax = "proto3";
package grpctest;
service TestService {
    rpc Send (Request) returns (Response) {}
}
message Request {
    string message = 1;
    bool test = 2;
    int32 int1 = 3;
    float float1 = 4;
    uint64 uint1 = 5;
    message EmbeddedMessage {
        string message = 1;
    }
    EmbeddedMessage emsg = 6;
    SubRequest submsg = 7;
}
message SubRequest {
    repeated string message = 1;
    uint64 uint1 = 3;
}
message Response {
    string message = 1;
    bool test = 2;
}

For every Send call, there is a Request message that will be parsed. Only string types are extracted. Repeated fields will appear as duplicate named entries. Embedded and sub-messages will be appended to the path based indexes. Only indexes will be used as field names don't appear in the wire protocol.

Example parser extractions

Here's an example of how name-based path fields (similar to JSON/XML) are translated to index parsed for gRPC.

• /message = "test": /1 = "test"
• /emsg/message = "test 2": /6/1 = "test 2"
• /submsg/message = "test 3": /7/1 = "test 3"

These extracted PostArgs fields will be inspected with SmartParse, but can also be inspected with custom rules like JSON/XML values. Additionally, the Path field will contain the gRPC path (typically /package.ServiceName/Method).

Example rule

1
2
3
4
5
6
7
8
9
10
11

Type: request

Conditions:
* all of
  * Path equals `/grpctest.TestService/Send`
  * Post Parameter exists where
    * all of
      * Name equals: `/1/6/1`
      * Value equals: `block me`

Actions: Block request