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. There are three ways to provide method discovery:

Option 1: Hosted OpenRPC Specification

Point HawkScan at a hosted OpenRPC specification served by your application. The path is relative to your app.host:

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

Option 2: Local OpenRPC Schema File

Provide a local OpenRPC schema file that describes your API’s methods and parameters:

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

Option 3: Automatic Discovery

If you don’t have an OpenRPC schema, HawkScan will attempt to discover methods automatically via rpc.discover or system.listMethods:

# 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
path	string		Host path to a hosted OpenRPC specification, 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.