-
Notifications
You must be signed in to change notification settings - Fork 274
Public API [draft]
This is a draft for a public API for BAP Server. The BAP server is an application that can provide BAP as a service to the third party applications, written in any language. We will refer to a BAP server as SERVER, and to third party application as a CLIENT. This document describes only the application protocol, the underlying transport protocol is out of the scope of the document.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .
The transport layer should provide a reliable message delivery facilities. Messages must be sent and received in an atomic way. The order of messages must not shuffle. Also, transport layer should provide authentication and ensure the security of the channel, in assumptions that the transported information can be evaluated.
Session consists of a series of interactions. Each interaction must consist of at one request and at least one response. Request and response are messages. Client must be an initiator of the session. Client must not send responses, and server must not send requests. Server must send messages only in response to the client's requests. Server may send more than one response to one request.
The request should be a JSON object of the following schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Request",
"description": "A request from Client to Server",
"type": "object",
"properties": {
"id" : {
"description" : "unique for the client side identifier",
"type" : "integer",
},
"init" : {
"title" : "initialize",
"description" : "initialize a session",
"type" : {"$ref" : "#definitions/init"}
},
"use-file" : {
"title": "Command use-file",
"description": "Target BAP onto specified path",
"type" : {"$ref" : "#/definitions/use-file"},
},
"use-string" : {
"title": "Command use-string",
"description": "Target BAP onto specified data represented by a string",
"type" : {"$ref" : "#/definitions/use-string"},
},
"set-position" : {
"title": "Command set-position",
"description": "Target BAP onto specified position in the data",
"type" : {"$ref" : "#/definitions/set-position"},
},
"disassemble" : {
"title" : "Disassemble command",
"description": "Disassemble the specified region",
"type" : {"$ref" : "#/definitions/disassemble"},
}
},
"required" : ["id"],
"minProperties" : 1,
"maxProperties" : 2,
"definitions" : {
"init" : {
"type" : "object",
"propeties" : {
"version" : "string"
}
},
"use-file" : {
"type" : "object",
"properties": {
"path" : {
"description" : "file path",
"type" : "string",
},
"loader" : {
"description" : "what backend to use",
"type" : "string",
}
},
"required" : ["path"]
},
"use-string" : {
"type": "object",
"properties": {
"data" : {
"description" : "actual data",
"type" : "string",
},
"format" : {
"description" : "how to interpret the string",
"type" : "string",
"oneOf" : ["escaped-ascii"]
},
"arch" : {
"description" : "target architecture",
"type" : "string",
}
},
"required" : ["data", "format", "arch"],
},
"set-position" : {
"type": "object",
"properties": {
"offset" : {
"description" : "offset in octets from the start of the data",
"type" : "integer",
"minimum" : 0,
},
"size" : {
"description" : "maximum offset",
"type" : "integer",
"minimum" : 1,
}
},
"required" : ["offset"]
},
"disassemble" : {
"type": "object",
"properties": {
"stop-conditions" : {
"description" : "A set of stop conditions",
"type" : "stringArray",
}
}
}
}
}The use-file request is sent to direct the server to use the specified file as a target of analysis. Server must respond to this request with either of this responses:
errorimage
The server may react with additional responses, like symbols or sections.
Example of the request
{
"id" : 12,
"use-file" : {
"path" : "/bin/ls",
"loader" : "bap-elf",
}
}The use-string may be used instead of use-file request if the calling side want to provide an arbitrary data for analyzing. The data shouldn't contain any meta data, and it wouldn't be parsed as a binary container.
Since no meta data exists, a client side must define an instruction set, using arch property.
The server must respond to this request with the error or empty responses.
Example:
{
"id" : 15,
"use-string" : {
"format" : "escaped-ascii",
"arch" : "arm",
"data" : "\\x10\\x12"
}
}The set-position message is used to target Server at the specific point in the data. It can be also used to limit the extent of data.
Example:
{
"id" : 255,
"set-position" : {
"offset" : "0",
"size" : "1024"
}
}The disassemble command is used to start the disassembling of the specified data. The data must be specified before this command by a client side with either use-file or use-string command.
The server must respond with insns or error messages. The server may still response with insns message even when the error has occurred. In that case insns message should be sent before the error command.
Example:
{
"id" : 17,
"disassemble" : {
"stop-conditions" : ["isCall()"]
}
}Response message must be a JSON with the following schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Response",
"description": "A reply from Server to Client",
"type": "object",
"properties": {
"id" : {
"description" : "identifier unique for the server side",
"type" : "integer",
},
"request" : {
"description": "An id of the request to which we're replying",
"type" : "interger",
},
"error" : {
"description" : "the request cannot be satisfied",
"type" : {"$ref" : "#/definitions/error"}
},
"capabilities" : {
"description" : "a set of capabilities support by Server",
"type" : {"$ref" : "#/definitions/capabilities"}
},
"image" : {
"description" : "binary container description",
"type" : {"$ref" : "#/definitions/image"}
},
"symbols" : {
"description" : "the array of symbols",
"type" : "array",
"minItems" : 1,
"uniqueItems" : true,
"items" : {"type" : {"$ref" : "#/definitions/symbol"}}
},
"sections" : {
"description" : "the array of sections",
"type" : "array",
"minItems" : 1,
"uniqueItems" : true,
"items" : {"type" : {"$ref" : "#/definitions/section"}}
},
"insns" : {
"description" : "the array of insns",
"type" : "array",
"minItems" : 1,
"uniqueItems" : true,
"items" : {"type" : {"$ref" : "#/definitions/insn"}}
},
},
"required" : ["id", "request"],
"minProperties" : 2,
"maxProperties" : 3,
"definitions" : {
"error" : {
"type" : "object",
"properties" : {
"description" : {"type" : "string"},
"severity" : {
"type" : "string",
"oneOf" : ["critical", "error", "warning"]
}
},
"required" : ["description", "severity"]
},
"capabilities" : {
"type" : "object",
"properties" : {
"versions" : {
"description" : "a set of supported protocol versions",
"type" : "stringArray"
},
"loaders" : {
"description" : "a set of supported file loaders",
"type" : "array",
"minItems" : 1,
"uniqueItems" : true,
"items" : {"type" : {"$ref" : "#/definitions/loader"}}
},
"disassemblers" : {
"description" : "a set of supported disassemblers backend",
"type" : "array",
"minItems" : 1,
"uniqueItems" : true,
"items" : {"type" : {"$ref" : "#/definitions/disassembler"}}
}
},
"required" : ["versions", "loaders", "disassemblers"]
},
"symbol" : {
"type" : "object",
"properties" : {
"name" : {"type" : "string"},
"addr" : {"type" : "integer"},
"size" : {"type" : "integer"},
"is_function" : {"type" : "boolean"},
},
"required" : ["addr"]
},
"section" : {
"type" : "object",
"properties" : {
"name" : {"type" : "string"},
"addr" : {"type" : "integer"},
"size" : {"type" : "integer"},
"off" : {"type" : "integer"},
"perm" : {
"type" : "array",
"minItems" : 1,
"maxItems" : 3,
"uniqueItems" : true,
"items" : {"type" : "string", "oneOf" : ["r", "w", "x"]}
},
},
"required" : ["addr", "off", "perm", "size"]
},
"image" : {
"type" : "object",
"properties" : {
"arch" : {"type" : "string"},
"entry_point" : {"type" : "integer"},
"addr_size" : {
"type" : "integer",
"oneOf" : [32, 64],
},
"endian" : {
"type" : "string",
"oneOf" : ["LittleEndian()", "BigEndian()"]
}
}
},
"insn" : {
"type" : "object",
"properties" : {
"name" : {
"title" : "Instruction name",
"description" : "Name accroding to the disassembler backend in use",
"type" : "string",
},
"size" : {
"description" : "Instruction size in bytes",
"type" : "integer"
},
"addr" : {
"description" : "Address of the first byte of the instruction",
"type" : "integer"
},
"asm" : {
"description" : "Instruction representation in a target assembler",
"type" : "string"
},
"ops" : {
"descrption" : "An array of operators, according to the disassembler",
"type" : "array",
"minItems" : 0,
"items" : {"type" : "string"}
},
"kinds" : {
"descrption" : "A set of kinds appropriate for the instruction",
"type" : "array",
"minItems" : 0,
"uniqueItems" : true,
"items" : {"type" : "string"}
},
"target" : {
"title" : "Target Instruction",
"description" : "Target specific machine instruction",
"type" : "string"
},
"bil" : {
"description" : "BIL Instructions",
"type" : "array",
"minItems" : 0,
"items" : {"type" : "string"}
}
},
"required" : ["size", "addr", "asm"]
},
"loader" : {
"description" : "Capabilities of binary container parser",
"type" : "object",
"properties" : {
"formats" : {
"description" : "Set of supported file formats",
"type" : "stringArray"
},
"architectures" : {
"description" : "Set of supported architectures",
"type" : "stringArray",
},
"symbols" : {
"description" : "Capability to read symbol information",
"type" : "array",
"minItems" : 0,
"items" : {
"type" : "string",
"anyOf" : ["symtab", "debug"],
}
}
}
},
"disassembler" : {
"description" : "capabilities of disassembler",
"type" : "object",
"properties" : {
"kinds" : {
"description" : "set of understandable kinds",
"type" : "array",
"items" : {"type" : "string"},
"minItems" : 1,
"uniqueItems" : true
},
"has-name" : {
"description" : "can provide instruction name",
"type" : "boolean",
},
"has-ops" : {
"description" : "can provide instruction operands",
"type" : "boolean",
},
"has-target" : {
"description" : "can provide lifted target instruction",
"type" : "boolean",
},
"has-bil" : {
"description" : "can provide BIL",
"type" : "boolean",
},
}
}
}
}