gRPC Protection settings
Use this reference to look up the settings available for gRPC Protection and gRPC Error Response in an F5 WAF for NGINX security policy. Both sections are available under API Protection in the security policy wizard. To open the wizard, create a new policy or edit an existing one. See Create a security policy or Update a security policy.
The gRPC Protection section contains gRPC Profiles and gRPC Violations. A gRPC profile controls how the policy inspects traffic for one gRPC service. gRPC violation actions apply to the whole policy, not to an individual profile. Select Reset All Fields in the gRPC Protection section to reset every profile and violation action to its default state.
gRPC Error Response is a separate, policy-wide section. It controls the response that F5 NGINX Instance Manager sends to a client when it blocks a gRPC request.
A gRPC profile describes how the policy inspects traffic for one gRPC service. A policy can have more than one gRPC profile. The gRPC Profiles table lists each profile’s name, description, and status for Interface Definition Language (IDL) files and attack signatures. It also includes Edit and Remove actions for each profile.
To add a profile, select Add Item. To change an existing profile, select its name, or select Edit from the Actions menu. The default values in the following tables apply to a new profile. When you edit an existing profile, its displayed values can differ from these defaults.
| Name | Required | Default | Description |
|---|---|---|---|
| Profile Name | Yes | None | A name for the profile. It must be unique among the policy’s gRPC profiles. |
| Description | No | None | A description of the profile’s purpose. |
| Name | Required | Default | Description |
|---|---|---|---|
| Enable attack signatures | No | On | Detects attack signatures and threat campaigns in gRPC traffic for this profile. When you turn on this setting, you can configure attack signature overrides. |
| Associate URLs | No | On | Associates URLs derived from the .proto package and service names. |
| Check for illegal meta characters | No | On | Detects disallowed metacharacters in gRPC string fields. |
| Decode String Values as Base64 | No | Enabled | Decodes string values as Base64 before inspection. Select Disabled or Enabled based on your service’s traffic. |
| Name | Required | Default | Description |
|---|---|---|---|
| Allow unknown fields | No | Off | Allows request fields that aren’t defined in the IDL. Leave this setting off when requests must follow the IDL strictly. |
| Maximum Data Length | No | 4194304 bytes (4 MiB) |
Sets the maximum size, in bytes, of a gRPC message the profile accepts. Enter a positive byte value, or any for no limit. |
Upload the IDL definitions that describe your gRPC service and its imports. You can drag and drop files, or select to browse for them. The wizard accepts .proto, .tar, .tgz, and .tar.gz files.
| Name | Required | Default | Description |
|---|---|---|---|
| Primary / Set as Primary | Yes, for one file in the profile | The first accepted file | Identifies the main IDL file or archive for the profile. Exactly one file must be primary. If you remove the primary file, the first remaining file becomes primary. |
| Import Path | No | None | Sets the import location for a non-primary file. |
| Primary entry file name | Yes, for an archive | None | Names the primary .proto file inside an uploaded archive, not the name of the archive itself. |
| Remove | n/a | n/a | Removes a file from the profile. |
Keep the following in mind:
- Each uploaded
.protofile must declaresyntax = "proto3";. - You can save a profile without any IDL files, but supply the definitions and imports your service needs before you compile the policy.
- The wizard doesn’t inspect the contents of an archive. Make sure the archive includes the primary file and its dependencies, then check the policy compilation results.
- If an uploaded file has the same name as a file already used elsewhere in the policy, rename it and upload it again. The wizard also rejects duplicate names within a single profile or upload batch.
- Some existing file references display as read-only. You can remove a read-only entry, but you can’t edit it in the file list.
Use Attack Signature Overrides to change detection settings for individual attack signatures in this profile. This section is available when you turn on Enable attack signatures.
| Name | Required | Default | Description |
|---|---|---|---|
| Add Item | n/a | n/a | Opens the Add Attack Signature Overrides dialog, where you select individual signatures to override for this profile. The dialog lists each signature’s name, ID, attack type, accuracy, and risk. |
| Enabled control | No | Off | Turns an existing override on or off for this profile. |
| Remove | n/a | n/a | Removes an override from the list when you no longer need it. |
A new override is off by default. If you turn off a signature for this profile, you reduce detection. Review overrides carefully before you turn one off.
After you add or edit a profile, select Save Changes (or Add Profile for a new profile) to apply your changes. Select Cancel to discard unsaved changes. Select Remove from the Actions menu to remove a profile entirely.
Select Edit Configuration in the gRPC Violations section to choose an enforcement action for each violation type. This setting applies to the whole policy, not to an individual profile.
| Violation type | Default | Description |
|---|---|---|
| gRPC data does not comply with format settings | Alarm | Detects content that doesn’t comply with profile restrictions, such as message length or unknown fields. |
| Malformed gRPC data | Alarm and Block | Detects malformed or unparsable gRPC content. |
| Illegal gRPC method | Alarm | Detects a request for a gRPC service method that isn’t defined in the IDL. |
Set each violation type’s enforcement action to one of the following:
| Action | Description |
|---|---|
| Alarm | Reports the violation. Doesn’t block the request. |
| Alarm and Block | Reports the violation and blocks the request. |
| Disabled | Doesn’t enforce the violation. |
Whether NGINX Instance Manager blocks a request also depends on the policy’s enforcement mode and deployment configuration. For example, a policy in transparent mode doesn’t block a request, even if you set its violation action to Alarm and Block.
See Supported Violations for additional details.
Under API Protection > gRPC Error Response, configure the single, policy-wide response NGINX Instance Manager returns for a blocked gRPC request. All three fields are optional. If you clear all three, NGINX Instance Manager removes the configured gRPC error response.
| Name | Required | Default | Description |
|---|---|---|---|
| gRPC Status Code | No | None | A named status code to return to the client. Search the list, or select Clear Selection to remove a chosen code. Accepted values: ABORTED, ALREADY_EXISTS, CANCELLED, DATA_LOSS, DEADLINE_EXCEEDED, FAILED_PRECONDITION, INTERNAL, INVALID_ARGUMENT, NOT_FOUND, OK, OUT_OF_RANGE, PERMISSION_DENIED, RESOURCE_EXHAUSTED, UNAUTHENTICATED, UNAVAILABLE, UNIMPLEMENTED, and UNKNOWN. |
| gRPC Status Message | No | None | A message to accompany the status. Avoid exposing internal security or service details in this message. |
| Response Content | No | None | Content to return in the response body for the blocked request. |