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.

HawkScan also supports scanning MCP (Model Context Protocol) servers. MCP is built on JSON-RPC 2.0 and is used by AI applications to expose tools and resources. See Scanning MCP Servers below for details.

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"

Scanning MCP Servers

Model Context Protocol (MCP) is an open standard for connecting AI applications to external tools and data sources. MCP servers expose tools via JSON-RPC 2.0 using the Streamable HTTP transport. HawkScan can discover and scan MCP server tools for security vulnerabilities like SQL injection, SSRF, and data exposure.

How MCP Scanning Works

When the mcp configuration block is present, HawkScan performs an MCP protocol handshake to discover tools:

Initialize — Sends an initialize request to establish a session with the MCP server
Confirm — Sends a notifications/initialized notification to complete the handshake
Discover tools — Sends a tools/list request to enumerate available tools and their input schemas
Scan — For each discovered tool, generates fuzzed payloads from the tool’s inputSchema and sends them as tools/call requests, analyzing responses for vulnerability indicators

Basic MCP Configuration

To scan an MCP server, add the mcp block under jsonRpcConf:

# stackhawk.yml
app:
  host: http://localhost:3000
  jsonRpcConf:
    mcp:
      endpoint: /mcp

The presence of the mcp block enables MCP scanning mode. No enabled: true or filePath is needed — HawkScan discovers tools automatically via the MCP handshake.

MCP Configuration Options

Option	Type	Default	Description
`endpoint`	string	`/mcp`	The MCP server endpoint path relative to the target host
`excludeTools`	list	`[]`	MCP tool names to exclude from scanning
`customValues`	list	`[]`	Custom variable values for specific tools and parameters

Excluding Tools from Scanning

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

app:
  host: http://localhost:3000
  jsonRpcConf:
    mcp:
      endpoint: /mcp
      excludeTools:
        - delete_database
        - admin_reset

Using Custom Values for MCP Tools

Custom values let you provide specific parameter values for MCP tools. This is useful when tools require valid IDs, specific formats, or realistic data:

app:
  host: http://localhost:3000
  jsonRpcConf:
    mcp:
      endpoint: /mcp
      customValues:
        - tool: get_user
          param: user_id
          values:
            - "123"
            - "456"
        - tool: search_documents
          param: query
          values:
            - "annual report"
            - "security policy"

Use dot notation for nested parameters (e.g., filter.category).

MCP with Other JSON-RPC Options

MCP scanning mode works with the general JSON-RPC options for timeout, depth, and faker:

app:
  host: http://localhost:3000
  jsonRpcConf:
    requestTimeout: 60000
    maxDepth: 4
    fakerEnabled: true
    mcp:
      endpoint: /mcp
      excludeTools:
        - dangerous_operation

What HawkScan Detects in MCP Servers

HawkScan runs the same active and passive security checks against MCP tools that it runs against any other API:

SQL Injection — Detects SQL errors in tool responses caused by injected payloads
Cross-Site Scripting (XSS) — Identifies reflected content in tool output
Server-Side Request Forgery (SSRF) — Tests URL parameters for internal network access
Prompt Injection — Detects when crafted inputs can manipulate LLM behavior through tool responses
Information Disclosure — Finds sensitive data exposure in tool responses
Security Headers — Checks HTTP response headers for missing security controls

MCP tool responses use the result.content format with text entries. HawkScan extracts text content from these responses for vulnerability analysis, including error messages that may indicate injection vulnerabilities.

Running the Scan

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

hawk scan

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