gRPC Configuration

Introduction

gRPC is an open-source framework developed by Google for building high-performance, scalable, and efficient microservices. It uses Protocol Buffers as its data serialization format, and HTTP/2 as its transport protocol. gRPC applications are becoming increasingly popular due to their performance benefits and ease of use. However, like any other application, gRPC applications are also susceptible to security vulnerabilities. Therefore, it is important to test gRPC applications for security vulnerabilities using a dynamic application security scanner like Hawkscan.

Configuring Hawkscan for scanning gRPC applications

To scan a gRPC application using Hawkscan, you need to configure the scanner with the appropriate options. The following yaml configuration can be used to configure Hawkscan for scanning a gRPC application:

stackhawk.yml

app:
  grpcConf:
    path: 'localhost:9001'
    customVariables:
      - field: name
        values:
          - customValue1
          - customValue2

The above example uses reflection to obtain the schema for the application via the path field. This value is usually the same as the appHost without the prefix. If the target application does not have reflection enabled, a file descriptor set can also be supplied to Hawkscan via the filePath field. This file must be generated before the scan takes place. In order to generate this file, generateDescriptorSet must be enabled in the build spec and a path should be supplied that you can point the scanner to. It is worth noting that at this time, not all frameworks/languages support generating the descriptor set for gRPC, and reflection will need to be used. Once the descriptor set file has been generated, it can be supplied to the scanner as such:

stackhawk.yml

app:
  grpcConf:
    filePath: '/resources/main/descriptor_set.pb'
    customVariables:
      - field: name
        values:
          - customValue1
          - customValue2

Currently TLS/auth is not supported for gRPC applications, but could be in the future.

Using Custom Variable Injection

You can configure HawkScan to use custom values for any parameters that exist in your gRPC schema. Using custom values allows you to scan operations that can potentially access real data and exercise more branches of your application’s code than default static values that may not exist in the context of your application. To provide custom values for your gRPC schema’s params, include the app.grpcConf.customVariables parameter in your stackhawk.yml file.

The following is an example configuration using custom values:

# in the "app" config...
app:
  grpcConf:
    filePath: '/resources/main/descriptor_set.pb'
    customVariables:
    # List of custom variables and a list of possible values to use for each of them.
    customVariables:
      - field: firstName
        values:
          - customFirstName1
          - customFirstName2
      - field: lastName
        values:
          - customLastName1
          - customLastName2
      - field: username
        values:
          - customUsername1
          - customUsername2
          - customUsername3

If you provide a list of values for a custom variable, the scanner will select one randomly for each operations that the custom variable belongs to. If you provide a single value in the list for a variable, that value will be used. For any parameters in the gRPC schema that you do not provide custom values for in the stackhawk.yml file, HawkScan will fall back on default logic and use static values based on their type.

Generating Smart Values for Parameters

By leveraging the Java Faker library, HawkScan can generate smarter values when the proper information is supplied in the gRPC schema. You can then configure which parameters will get generated smart values in the stackhawk.yml file in the graphqlConf section, by using the faker prefix ($faker) and a format as a custom value for a given parameter. For example:

# in the "app" config...
app:
  grpcConf:
    filePath: '/resources/main/descriptor_set.pb'
    customVariables:
    # List of custom variables and a list of possible values to use for each of them.
    customVariables:
      - field: customerEmail
        values:
          - $faker:email
      - field: customerPhone
        values:
          - $faker:phone
      - field: customerId
        values:
          - $faker:uuid

This configuration will randomly generate a properly formatted and random email address for customerEmail, phone number for customerPhone, and uuid for customerId.

Below is a list of all the formats supported by HawkScan:

- email
- phone
- uuid
- url
- uri
- hostname
- ipv4 
- ipv6
- date-time
- date
- float
- double
- boolean
- word
- sentence
- paragraph
- sha256
- sha512
- md5
- yoda (Yoda quotes)

Running the scan

Once the scanner is configured with the appropriate options, you can run the scan like another other application type using the following command:

hawk scan

The scanner will connect to the gRPC endpoint specified in the configuration and scan for security vulnerabilities.