ghidra-cli/schemas/v1/protocol-request.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AdapterRequest",
  "description": "Strict adapter request.",
  "type": "object",
  "properties": {
    "analysis_path": {
      "description": "Private Ghidra project or staging directory when required.",
      "anyOf": [
        {
          "$ref": "#/$defs/WorkerPath"
        },
        {
          "type": "null"
        }
      ]
    },
    "arguments": {
      "description": "Operation-specific validated arguments.",
      "$ref": "#/$defs/RequestArguments"
    },
    "invocation_id": {
      "description": "Random 128-bit identifier echoed by the response.",
      "$ref": "#/$defs/InvocationId"
    },
    "limits": {
      "description": "Selected limits.",
      "$ref": "#/$defs/Limits"
    },
    "operation": {
      "description": "Operation echoed by the response.",
      "$ref": "#/$defs/Operation"
    },
    "protocol_version": {
      "type": "integer",
      "const": 1
    },
    "staged_sample": {
      "description": "Private staged Sample path, absent for non-Sample operations.",
      "anyOf": [
        {
          "$ref": "#/$defs/WorkerPath"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "protocol_version",
    "invocation_id",
    "operation",
    "limits",
    "arguments"
  ],
  "$defs": {
    "Address": {
      "description": "A Ghidra address with an explicit, case-sensitive address space.",
      "type": "object",
      "properties": {
        "offset": {
          "description": "Canonical lowercase, `0x`-prefixed, even-width hexadecimal offset.",
          "type": "string"
        },
        "space": {
          "description": "Exact Ghidra address-space name.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "space",
        "offset"
      ]
    },
    "CollectionLimit": {
      "description": "An optional item bound, explicit when unbounded.",
      "oneOf": [
        {
          "description": "At most the enclosed number of items.",
          "type": "object",
          "properties": {
            "bounded": {
              "$ref": "#/$defs/PositiveU64"
            }
          },
          "additionalProperties": false,
          "required": [
            "bounded"
          ]
        },
        {
          "description": "Every item, still subject to the serialized-byte budget.",
          "type": "string",
          "const": "all"
        }
      ]
    },
    "FunctionSelector": {
      "description": "Exactly one explicit Function Selector.",
      "oneOf": [
        {
          "description": "Exact, case-sensitive Ghidra function name.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "name"
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "value"
          ]
        },
        {
          "description": "Exact function entry address.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "address"
            },
            "value": {
              "$ref": "#/$defs/Address"
            }
          },
          "required": [
            "kind",
            "value"
          ]
        }
      ]
    },
    "InvocationId": {
      "description": "A random 128-bit invocation identifier encoded as 32 lowercase hex digits.",
      "type": "string"
    },
    "Limits": {
      "description": "Resource policy selected for one invocation.",
      "type": "object",
      "properties": {
        "analysis_timeout_seconds": {
          "description": "Native analysis timeout.",
          "$ref": "#/$defs/PositiveU64"
        },
        "child_watchdog_seconds": {
          "description": "Derived process watchdog.",
          "$ref": "#/$defs/PositiveU64"
        },
        "decompile_timeout_seconds": {
          "description": "Optional native decompilation timeout.",
          "anyOf": [
            {
              "$ref": "#/$defs/PositiveU64"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_cpu": {
          "description": "Maximum Ghidra analysis CPU count.",
          "$ref": "#/$defs/PositiveU64"
        },
        "max_heap_mib": {
          "description": "Maximum Java heap, in MiB.",
          "$ref": "#/$defs/PositiveU64"
        },
        "max_inline_bytes": {
          "description": "Maximum serialized successful stdout size.",
          "$ref": "#/$defs/PositiveU64"
        },
        "max_sample_bytes": {
          "description": "Maximum accepted Sample size.",
          "$ref": "#/$defs/PositiveU64"
        }
      },
      "additionalProperties": false,
      "required": [
        "max_heap_mib",
        "max_cpu",
        "analysis_timeout_seconds",
        "child_watchdog_seconds",
        "max_sample_bytes",
        "max_inline_bytes"
      ]
    },
    "Operation": {
      "description": "Version 0.1 operation identifier shared with Java.",
      "oneOf": [
        {
          "description": "Installation diagnosis.",
          "type": "string",
          "const": "doctor"
        },
        {
          "description": "Sample metadata inspection.",
          "type": "string",
          "const": "inspect"
        },
        {
          "description": "Stable Function collection.",
          "type": "string",
          "const": "functions"
        },
        {
          "description": "Targeted Function decompilation.",
          "type": "string",
          "const": "decompile"
        },
        {
          "description": "Explicit Analysis Store cleanup.",
          "type": "string",
          "const": "clean"
        }
      ]
    },
    "PageRequest": {
      "description": "A normalized collection page request.",
      "type": "object",
      "properties": {
        "limit": {
          "description": "Selected item bound.",
          "$ref": "#/$defs/CollectionLimit"
        },
        "offset": {
          "description": "Number of items skipped in stable order.",
          "type": "integer",
          "format": "uint64",
          "minimum": 0
        }
      },
      "additionalProperties": false,
      "required": [
        "offset",
        "limit"
      ]
    },
    "PositiveU64": {
      "description": "A validated positive integer accepted by resource-limit flags.",
      "type": "integer",
      "format": "uint64",
      "minimum": 1
    },
    "RequestArguments": {
      "description": "Operation-specific request arguments.",
      "oneOf": [
        {
          "description": "Installation probe.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "doctor"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind"
          ]
        },
        {
          "description": "Program metadata extraction.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "inspect"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind"
          ]
        },
        {
          "description": "Stable Function page extraction.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "functions"
            },
            "page": {
              "description": "Explicit page bound.",
              "$ref": "#/$defs/PageRequest"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "page"
          ]
        },
        {
          "description": "Targeted decompilation.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "decompile"
            },
            "selector": {
              "description": "Explicit Function Selector.",
              "$ref": "#/$defs/FunctionSelector"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "selector"
          ]
        },
        {
          "description": "Store cleanup does not cross into Ghidra; reserved for parity.",
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "clean"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind"
          ]
        }
      ]
    },
    "WorkerPath": {
      "description": "A validated UTF-8 absolute path owned by the trusted harness.",
      "type": "string"
    }
  }
}