Instructions
The burp-workflows is an opensource tool that can be useful for those struggling with workflow testing. This tool is implemented as a plugin for the burp-suite. It's compatible with both community and Pro version of burp suite.
Here is some main features:
- Defining parametric workflows by recording browser traffics and adding custom parameters by marking place holders to HTTP requests
- Executing defined workflows with custom parameters
- Extracting parameters from HTTP response and automatically add it to subsequent requests
- Scripting to empower your tests
- Reusing defined test-cases in different versions of an application.
By using this tool, you don't need anymore to login and logout with differnt users several times.
To install this tool download the compiled version from the Releases page. Open burp suite and goto Extender Tab and add the jar file.
Also, you can download the sourcecode, import it to an IDE and make a Burp-suite compatible JAR file.
Here is a small web application with some simple workflows. You can download and use it to evaluate the functionality of burp-workflows.
What we mean when we say Workflow:
A workflow is a sequence of operations that is done by multiple users with different roles in a system, to accomplish a specific goal.
from technical perspective:
A workflow is a sequence of HTTP requests, that is done by different users of a system.
We use the name Sequence to the parts of a workflow that is done by a single user. Technically a Sequence is the continuous requests that is sent by a single user (single session-id) in a workflow.
Consider a web portal with users in different roles. Based on the user's role he/she can access to some activities of the portal. Ordinary users can submit their download requests to portal and download will be started if the admin accepted the request. In this example the workflow consist of two sequences: one sequence for submitting the download request by ordinary user and other sequence for accepting download request by admin.
Working with the burp-workflows consist of the following steps:
- In the Sequences tab, define the sequences.
- In the Flows tab, create a flow by composing one or more sequences and adding custom parameters to each sequence. It's just like a function definition in a programming language, You define a function that takes some parameters, do something and maybe returns a value.
- In the Scenarios tab, define your test-cases. Select a flow, initiate the parameters and save it. This tab makes your test-cases reusable.
- In the Scripts tab, make some scripts and inject them to a flow. Scripts enable you to do more advance and complicated works during the test.
Configure your browsers proxy settings to work with Burp-suite. Go to Sequences tab. and click New. A dialog will be appeared.
Enter a name and description for the sequence. Then click on the Record button. In the browser, start surfing (either with a logged-in or not-logged-in user). you will see that your requests are listed in the left-side List component. Select requests that are required to accomplish the sequence and add them to the right-side list. You can use filter checkbox to avoid displaying the static files like javascript and css files. Obviously, the order of requests is important.
In case of need for request customization, use resend option.
Re-usability for workflows is simply provided by changing the Base URL. Consider an application which is installed on two application servers with different IP/domain and different context roots. One of these installed application is used in alpha testing with address:
and other application is installed for beta test with address:
Defined workflows for alpha test can be simply reused for beta test just by replacing base URL http://alphaserver.inc/alpha to base URL http://betaserver.inc/beta when running workflow.
Flow definition is just like function definition in programming languages. A flow has some inputs and can return some outputs. First step to create a flow is to select some sequences. Sequences can be customized by inserting place holders in HTTP requests.
You can insert placeholders like §id@params§ in HTTP request body. In run-time this place holders will be filled with the value of the variables.
There are 3 types of variables:
- Parameter
- Local
- Global
Variables name must be consist of alphabetic and numeric characters with dash and underscore.( Regex: [A-Za-z0-9\-\_]+)
The parameters will be used as workflow's input and will be initialized when workflow is started. Parameters are defined in the New-flow dialog in a comma separated format.
A local variable is a temporary variable which is used to make relation among requests and will be created during a workflow running. These variables will be destroyed after the workflow execution has been finished. Received responses will be used to initialize local variables.
To create a local variable click on Edit Requests button on New Flow dialog. A new dialog will be appeared. In the new window the requests of the current sequence will be displayed. Select a request and click on Response tab in right-side.
Click on + button. Currently, local variable can be extracted from response body in these ways:
- Extracting from a Hidden field. It's useful for CSRF-tokens.
- Extracting from a set-cookie header. It's useful for session-IDs.
- Extracting data using CSS-Selector
- Extracting data using REGEX
- Image Captcha: If the response is a CAPTCHA image, you can use this type of variable. In run-time a pop-up dialog will be appeared and the image will be displayed to user. User should write the text within image. The text that user has entered is considered as the variable value.
Global variables are variables that are persistent and you can use them in every workflow runs. We store these variables in database.
Defining a global variable is like defining a local variable, just check the Global checkbox in the pop-up window.
By defining a global variable with the name return (in-case-sensitive), a global variable will be created with the name of current scenario.
This feature enable you to manage cookie fields in each sequence of a flow. Values of cookie fields can be set using a static value or a defined variable(parameter, global or local) to change cookie text box.
If you leave this box empty, cookie will be sent without any changes.
A Scenario will be defined by selecting a flow and initializing input parameters.
If you need a complicated or advanced process on request/responses, you can use scripting feature. You can write scripts and inject them at a particular moment in the workflow lifecycle:
- Before starting a test
- Before initializing a request
- After initializing a request
- After a response received
- After finishing a test
Scripts can be written in javascript, python or ruby. If you are intended to use python or ruby, you must (define Jython or JRuby in Burp-suite first)[https://portswigger.net/burp/help/extender]. No module is needed if you are Using javascript.
The following code is an example for creating a new global variable. It also uses values from local variables and parameters:
instance.updateGlobalVariable("session-"+ instance.getParams().get("username"), instance.queryLocalVariable("cookie-login"))
The API is not documented yet. But you can read the source code of Flow_Running Class and other classes and make use of their public members.