JSON-RPC Protocol for Plugins

RootCause uses the JSON-RPC 2.0 protocol for communication between the host and plugins. This document details the complete protocol, including all methods, data structures, and communication flows.

Communication occurs via the stdin and stdout of the invoked process (the plugin).

JSON-RPC 2.0 Protocol

Base message structure

All messages follow the JSON-RPC 2.0 standard:

{
  "jsonrpc": "2.0",
  "id": "unique-identifier",
  "method": "method-name",
  "params": { }
}

Successful responses

{
  "jsonrpc": "2.0",
  "id": "unique-identifier",
  "result": { }
}

Error responses

{
  "jsonrpc": "2.0",
  "id": "unique-identifier",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": { }
  }
}

Detailed analysis flow

Protocol methods

1. plugin.init

Initialises the plugin and sets the working session.

Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "plugin.init",
  "params": {
    "api_version": "1.x",
    "session_id": "unique-session-id",
    "workspace_root": "/path/to/workspace",
    "rules_root": "/path/to/rules",
    "capabilities_requested": ["transform", "analyze"],
    "options": {
      "mode": "aggressive",
      "timeout": 5000
    },
    "limits": {
      "cpu_ms": 10000,
      "mem_mb": 64
    },
    "env": {
      "PATH": "/usr/bin:/bin",
      "LANG": "en_GB.UTF-8"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "ok": true,
    "capabilities": ["transform"],
    "plugin_version": "1.0.0"
  }
}

2. plugin.ping

Checks plugin availability.

Request

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "plugin.ping",
  "params": null
}

Response

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "pong": true
  }
}

3. file.transform

Requests file transformation (for plugins with transform capability).

Request

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "file.transform",
  "params": {
    "files": [
      {
        "path": "src/main.py",
        "sha256": "abc123...",
        "language": "python",
        "content_b64": "aW1wb3J0IG9zCg==",
        "size": 1024
      }
    ]
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "files": [
      {
        "path": "src/main.py",
        "actions": ["decoded:base64"],
        "content_b64": "aW1wb3J0IG9zCg==",
        "notes": ["blocks:3"]
      }
    ],
    "metrics": {
      "decoded": 1,
      "ms": 150
    }
  }
}

4. file.analyze

Requests file analysis (for plugins with analyze capability).

Request

{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "file.analyze",
  "params": {
    "files": [
      {
        "path": "src/main.py",
        "sha256": "abc123...",
        "language": "python",
        "content_b64": "aW1wb3J0IG9zCg==",
        "size": 1024
      }
    ]
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "findings": [
      {
        "message": "Hardcoded password detected",
        "file": "src/main.py",
        "line": 15,
        "column": 10,
        "severity": "high",
        "rule_id": "hardcoded-password"
      }
    ],
    "metrics": {
      "files_processed": 1,
      "ms": 200
    }
  }
}

5. scan.report

Requests generation of custom reports (for plugins with report capability).

Request

{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "scan.report",
  "params": {
    "findings": [
      {
        "message": "Hardcoded password detected",
        "file": "src/main.py",
        "line": 15,
        "column": 10,
        "severity": "high",
        "rule_id": "hardcoded-password"
      },
      {
        "message": "SQL injection vulnerability",
        "file": "src/db.py",
        "line": 42,
        "column": 5,
        "severity": "critical",
        "rule_id": "sql-injection"
      }
    ],
    "metrics": {
      "files_scanned": 150,
      "total_findings": 25,
      "scan_duration_ms": 5000,
      "plugins_used": ["decodebase64", "ts-eval"]
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "summary": {
      "critical": 1,
      "high": 1,
      "medium": 0,
      "low": 0,
      "info": 0
    },
    "files_generated": [
      {
        "path": "report.json",
        "size": 1024,
        "format": "json"
      }
    ],
    "metrics": {
      "processing_time_ms": 150
    }
  }
}

6. plugin.shutdown

Requests plugin shutdown.

Request

{
  "jsonrpc": "2.0",
  "id": "6",
  "method": "plugin.shutdown",
  "params": null
}

Response

{
  "jsonrpc": "2.0",
  "id": "6",
  "result": {
    "ok": true
  }
}