-
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 as a response to the client's requests. Server may send more than one response to one request. Client may send new requests without waiting for the response for the previous request.
The request must 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 init request is sent to initiate a session. Client must not send any requests before the init request.
Server must respond to this request with error or capabilities message.
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 a Server to a 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"}
},
"image" : {
"description" : "binary container description"
},
"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"]
},
"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" : {
"basic" : {
"title" : "Basic Instruction",
"description" : "Target agnostic machine instruction",
"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" : ["basic"]
}
}
}