BCheck definition reference

metadata: language: v1-beta name: "Simple SQLi" description: "Tests insertion points for basic SQLi" author: "Peter Wiener" tags: "sql", "active", "sql-injection"

Property	Description	Type
language*	The version of the BCheck definition language used.	enum [v1-beta]
name*	The BCheck's name. This is displayed in the Burp Suite UI when the check reports an issue.	String
description	A description of the BCheck.	String
author	The author's name.	String
tags	Identifying tags.	List of strings

Defines when the check runs, based on the content being audited.

given [response|request|host] | [ [any|query|header|body|cookie]* + insertion point] then

Each BCheck must have a given / then statement containing:

EITHER one of the following:

• given response then - The check runs once for each response audited.
• given request then - The check runs once for each request audited.
• given host then - The check runs once for each host audited.

OR one of the following insertion point keywords:

• given any insertion point then - The check runs once for each insertion point (of any type) audited. Burp Scanner also uses this default option if you do not specify an insertion point type (i.e. you use given insertion point).
• given query insertion point then - The check runs once for each query audited.
• given header insertion point then - The check runs once for each header audited.
• given body insertion point then - The check runs once for each set of body content audited.
• given cookie insertion point then - The check runs once for each cookie audited.

You can use the or keyword to combine insertion points. For example:

• given query or body insertion point then - The check runs once for each query or set of body content audited.
• given header or cookie insertion point then - The check runs once for each header or cookie audited.

Defines variables that have global scope.

define: variable_name = "variable_content"

Declares an array variable that can be iterated over. When the variable is called the check runs once for each item in the array.

run for each: variable_name = "variable value 1", "variable value 2", etc.

Executes an action if a set condition is met. Requires the following:

• A condition.
• An action.
• An end if keyword.

if [condition] then [action] end if

Used within an if statement. Executes an action if the preceding condition is false and the else if condition is true. You can use multiple else if statements within a BCheck.

if [condition 1] then [action 1] else if [condition 2] then [action 2] end if

Used within an if statement. Executes an action if the statement's condition and the condition of any preceding else / if statements are not met.

if [condition] then [action] else then [action 2] end if

Denotes the end of an if statement.

if [condition] then [action] end if

Sends a request including the specified information. Can be used with all scan check modes except given response.

send request [called request_name]: [appending|replacing] headers: "name_of_header1": "value of header1", "name_of_header2": "value of header2" removing headers: "name_of_header1":, "name_of_header2":" [appending|replacing] queries: "name_of_query_1=http://portswigger.net", "name_of_query_2=https://portswigger.net" removing queries: "name_of_query_1", "name_of_query_2" [appending|replacing] path: "/test" removing path [appending|replacing] method: "GET" removing method [appending|replacing] body: "contents of body" removing body

Keyword	Description	Example
called (string)	Names the request so that it can be referred to later in the check	"Example request"
appending headers: (1-n name:value pairs)	Adds the specified header(s) to the request. If a header with the same name already exists in the request then a second header with the new value is added. You can list multiple header / value pairs	"Origin": "http://example.com"
replacing headers: (1-n name:value pairs)	Replaces the value of the specified header(s) with a new value. If there are no headers with the specified name then a new header is appended. You can list multiple header / value pairs	"Origin": "http://example.com"
removing headers: (1-n name:value pairs)	Removes the specified header(s) from the request. You can list multiple header names	"Origin": "http://example.com"
appending queries: (1-n query names and values)	Adds the specified query parameter(s) to the request URL. If a query with the same name already exists in the request then a second header with the new value is added. You can list multiple queries	"title=example_query"
replacing queries: (1-n query names and values)	Replaces the value of the specified query parameter(s) with a new value. If there are no queries with the specified name then a new query is appended. You can list multiple queries	"title=example_query"
removing queries: (1-n query names)	Removes the specified query parameter(s) from the request. You can list multiple queries	"title"
appending path: (string)	Adds the specified path parameter(s) to the request URL	"/admin"
replacing path: (string)	Replaces the path parameters in the URL with the specified values. Any query parameters are preserved	"/admin"
removing path	Removes all path parameters from the request.
appending method: (string)	Adds the specified HTTP method to the request	"GET"
replacing method: (string)	Replaces the request method with the specified value	"GET"
removing method	Removes the request method
appending body: (string)	Appends the specified body content to the request	"body content"
replacing body: (string)	Replaces the request body with the specified content	"body content"
removing body	Removes the request body

Sends a request including the specified information as a raw HTTP request. Can be used with all scan check modes except given response.

Sends a new request with the specified payload data appended or replaced. Can be used with given insertion point only.

send payload [called payload_name]: appending: "payload1", "payload2" replacing: "payload1", "payload2"

Property	Description	Type
appending:	Appends the specified content to the request's payload set.	String / multi variable
replacing:	Replaces the request's existing payload set with the specified content.	String / multi variable

Causes Burp Scanner to report an issue. All issues reported by BChecks have an issue type of Declarative Scan Check Generated. The displayed name of the issue is taken from the BCheck's name metadata property.

report issue: severity: confidence: remediation: detail:

Property	Description	Type
severity*	The severity of the issue	[info|low|medium|high]
confidence*	The level of confidence that the issue is present	[certain|firm|tentative]
remediation	Remediation advice	String
detail	Further information on the issue	String

These keywords refer to specific request or response properties. You can refer to either:

• base - The request sent and response received by Burp Scanner for the specified scan mode during crawling.
• latest - The most recent request / response pair for this scan mode.
• {request_name} - A specific request / response pair, named using the called keyword.

base|latest|{request_name} { response { status_code headers body http_version } request { method url { protocol host port path file query } http_version headers body } }

Response

Property	Description
response	Returns the entire content of the response.
response.status_code	Returns the response's HTTP status code.
response.headers	Returns a list of the response's headers.
response.body	Returns the body content of the response.
response.http_version	Returns the HTTP version used in the response.

Request

Property	Description
request	Returns the entire content of the request.
request.method	Returns the HTTP method used in the request.
request.url	Returns the URL that the request was sent to.
request.url.protocol	Returns the request URL's protocol.
request.url.host	Returns the host that the request was sent to.
request.url.port	Returns the port that the request was sent over.
request.url.path	Returns the request URL path.
request.url.file	Returns the URL file (that is, the portion of the URL after the initial slash).
request.url.query	Returns the query string used in the request URL.
request.http_version	Returns the HTTP version used in the request.
request.headers	Returns a list of request headers.
request.body	Returns the body content of the request.

{random_str(int)}

Returns a random string of the specified length. The length must be between 0 and 9,999,999. Entering 0 returns an empty string.

regex_replace (String source, String regex, String replacement)

Takes the source string and replaces any content matching the specified regex pattern with the replacement string.

{to_lower(string)}

Converts the specified string to lowercase.

{to_upper(string)}

Converts the specified string to uppercase.

{base64_encode(string)}

Encodes the specified string with base64.

{base64_decode(string)}

Decodes the specified string from base64.

{generate_collaborator_address}

Generates a new Burp Collaborator address for use within a request. You can generate multiple addresses within the same BCheck by calling {generate_collaborator_address} multiple times.

sha1(String)

Hashes the provided input using the SHA1 hash function.

sha256(String)

Hashes the provided input using the SHA256 hash function.

md5(String)

Hashes the provided input using the MD5 hash function.