JSON-RPC Configuration

Introduction

JSON-RPC is a stateless, lightweight remote procedure call protocol that uses JSON as its data format. JSON-RPC APIs expose named methods with structured parameters over HTTP, and are commonly used in blockchain platforms, IoT systems, and microservice architectures. HawkScan can discover and scan JSON-RPC 2.0 endpoints for security vulnerabilities by enumerating methods and fuzzing their parameters.

Configuring HawkScan for scanning JSON-RPC applications

To scan a JSON-RPC application using HawkScan, configure the app.jsonRpcConf section in your stackhawk.yml. You can provide an OpenRPC schema file that describes your API’s methods and parameters:

# stackhawk.yml
app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc
    filePath: '/path/to/openrpc.json'

If you don’t have an OpenRPC schema file, you can point HawkScan at the JSON-RPC endpoint and it will attempt to discover methods automatically:

# stackhawk.yml
app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc

Configuration Options

Option	Type	Default	Description
enabled	boolean	false	Enable JSON-RPC scan support
endpoint	string	/	The JSON-RPC endpoint path relative to the target host
filePath	string		Path to a local OpenRPC schema file (JSON format)
maxDepth	int	3	Maximum depth for generated nested objects
fakerEnabled	boolean	false	Enable faker for generating realistic parameter values
requestTimeout	int	30000	HTTP request timeout in milliseconds
excludeMethods	list	[]	Regex patterns for method names to exclude from scanning

Using Custom Variable Injection

Custom variables let you specify values for specific method parameters. This is useful when your API requires valid data formats or specific values that random fuzzing wouldn’t produce.

# stackhawk.yml
app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc
    filePath: '/path/to/openrpc.json'
    customVariables:
      - field: userId
        values:
          - user-123
          - user-456
      - field: user.address.city
        values:
          - Denver
          - Boulder

Use dot notation to target nested object fields (e.g., user.address.city).

Filtering by Method Name

You can restrict custom variables to specific methods using the path field with a regex pattern:

app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc
    customVariables:
      - field: accountId
        path: "accounts\\..*"
        values:
          - acct-001
          - acct-002

In this example, the accountId variable is only injected for methods matching accounts.* (e.g., accounts.get, accounts.update).

Generating Smart Values for Parameters

By enabling faker, HawkScan can generate realistic values for parameters when the OpenRPC schema includes format hints or when you specify faker expressions in custom variables. Use the $faker prefix with a format type:

app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc
    fakerEnabled: true
    customVariables:
      - field: customerEmail
        values:
          - $faker:email
      - field: customerPhone
        values:
          - $faker:phone
      - field: transactionId
        values:
          - $faker:uuid

Excluding Methods from Scanning

Use excludeMethods to skip methods that shouldn’t be scanned, such as admin-only or destructive operations:

app:
  jsonRpcConf:
    enabled: true
    endpoint: /jsonrpc
    excludeMethods:
      - "admin\\..*"
      - "system\\.shutdown"

Running the Scan

Once configured, run the scan like any other application type:

hawk scan

HawkScan will connect to the JSON-RPC endpoint, discover available methods, and scan them for security vulnerabilities.