BCheck definition reference

metadata: language: v2-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 [v2-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

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

The run for each keyword is optional. If used, you must place it before the given...then statement in your definition.

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

Declares variables with inner scope. The define keyword is optional. If used, you must place it before the given...then statement in your definition.

define: variable_name = "variable_content"

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

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

Each BCheck must have a single 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.
• given path then - The check runs once for each unique path 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 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 body content audited.
• given header or cookie insertion point then - The check runs once for each header or cookie audited.

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 header names)	Removes the specified header(s) from the request. You can list multiple header names	"Origin"
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 parameters	"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 parameters	"title=example_query"
removing queries: (1-n query names)	Removes the value of the specified query parameter(s) from the request. You can list multiple parameters	"title"
appending query_string: (string)	Appends the specified query string to the existing query. Alternatively, if there is no existing query, adds the query string to the request	"title=value&example_title=example_value"
replacing query_string: (string)	Replaces the entire query string with a specified value	"example_title=example_query"
removing query_string:	Removes the query string from the request
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 appended or replaced. Can be used with given insertion point only.

send payload [called payload_name]: appending: "payload" replacing: "payload"

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

Causes Burp Scanner to report an issue. This terminates the BCheck, even if there are parts of the check that have not yet run.

For example, consider the following BCheck:

given host: send request: method: `GET` headers: `Host`: `{collaborator_address}` if dns interactions then report issue: severity: info confidence: certain end if if http interactions then report issue: severity: high confidence: certain end if

This check looks for first DNS and then HTTP interactions resulting from its Burp Collaborator payload. However, if the check finds a DNS interaction then it performs its first report issue action and does not subsequently report any HTTP interactions, even if there are HTTP interactions present.

Causes Burp Scanner to report an issue, then continue to run the BCheck. For example, consider the following BCheck:

given host: send request: method: `GET` headers: `Host`: `{collaborator_address}` if dns interactions then report issue and continue: severity: info confidence: certain end if if http interactions then report issue: severity: high confidence: certain end if

This check looks for first DNS and then HTTP interactions resulting from its Burp Collaborator payload. If the check finds a DNS interaction then it performs its first report issue action. It then continues to run the check, and reports any subsequent HTTP interactions.

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. Example: GET
request.url	Returns the URL that the request was sent to. Example: https://ginandjuice.shop:443/catalog/product?productId=1
request.url.protocol	Returns the request URL's protocol. Example: https
request.url.host	Returns the host that the request was sent to. Example: ginandjuice.shop
request.url.port	Returns the port that the request was sent over. Example: 443
request.url.path	Returns the request URL path. Example: /catalog/product
request.url.file	Returns the URL file (the portion of the URL after the initial slash). Example: /catalog/product?productId=1
request.url.query	Returns the query string used in the request URL. Example: productId=1
request.http_version	Returns the HTTP version used in the request. Example: HTTP/2
request.headers	Returns a list of request headers.
request.body	Returns the body content of the request.

Returns Burp's user agent.

Returns the base value of the specified insertion point.

{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.