Looking for our research? We've moved it to a dedicated page

Introducing Burp Projects

Dafydd Stuttard | 08 April 2016 at 16:52 UTC

The latest major release of Burp introduces some great new capabilities for handling Burp's data and configuration. This blog post covers the following areas:

Burp project files

Burp's new project files are used to hold all of the data and configuration for a particular piece of work. Data is saved incrementally into the file as you work. When you reopen an existing project, Burp reloads the project's data and configuration, and you can resume working where you left off.

Burp project files are a replacement for the existing state file functionality, and are significantly superior in various ways:

Note: The new project files feature is not available on 32-bit platforms or in the free edition of Burp.

Changes to Burp's configuration options

Burp's configuration options have been split into two groups: user options and project options. This has been done to make it easier to work with Burp's configuration when dealing with multiple separate projects.

User-level options are those relating to the individual user's environment and UI, including:

Project-level options are those relating to the work that is being performed on a particular target application, including:

User-level options will typically be long-lived and are automatically preserved across different Burp sessions. Project-level options are not automatically preserved in the same way. Rather, they are stored within project files and configuration files.

Some options, such as upstream proxy settings, can be defined at both the project and user level. For these options, you can configure your normal options at the user level, and then override these if required on a per-project basis. For example, you might normally use a corporate LAN proxy to connect to the Internet, and you can configure this in your user-level settings. For particular projects, when testing an internal application or on site at a particular client, you might need to use a different upstream proxy or none at all. You can configure this in your project-level settings for the relevant projects.

Configuration files

You can use Burp's new configuration files to manage different configurations for particular tasks. For example, you might need to load a particular configuration when working on a particular client. Or you might create different configurations for different types of scans.

Separate configuration files can be used to manage user-level and project-level options.

You can load and save configuration files in various ways:

Configuration files use the JSON format. The structure and naming scheme used within the JSON correspond to the way that options are presented within the Burp UI. The easiest way to generate a configuration file for a particular purpose is to create the desired configuration within the Burp UI and save a configuration file from it. If preferred, you can also hand-edit an existing configuration file, since the contents are human-readable and self-documenting:

Partial configuration files can be used when needed. You can create a partial configuration file by saving the configuration of just one area of Burp, via the new "Options" button on each configuration panel, or by removing the unneeded sections from a full configuration file. When a partial configuration file is loaded, any options that are not defined within that file are left unchanged. This allows you to create small focused partial configuration files for common purposes, and load them when required to create a desired overall configuration.

New APIs

There are two new APIs that extensions can use to manage project-level options:

void loadConfigFromJson(String config);
String saveConfigAsJson(String... configPaths);

Both methods handle settings using the new JSON format that is used in configuration files.

The load method takes a String containing some configuration options, and updates Burp with the specified options. Partial configurations are acceptable, and any settings not specified will be left unmodified.

The save method by default saves the entire project-level configuration. To include only certain sections of the configuration, you can optionally supply the path to each section that should be included, for example: "project_options.connections".

The APIs only operate on project-level options, and user-level options cannot be loaded or saved via the API.

The old API methods for processing options via maps of name/value pairs, and for saving and loading state files, are now deprecated and will be removed at some future point.

The new startup wizard

When Burp launches, a new startup wizard is displayed.

The first screen lets you choose what Burp project to open:

You can choose from the following options to create or open a project:

Note: You can rename a project later via the Burp menu.

The next screen lets you choose what project configuration to use:

You can choose from the following options for the project configuration:

New command line arguments

There are two new command line arguments to facilitate working with Burp projects and configuration files:
--project-file=filename  Opens the specified project file. The file will be created as a new project if it does not already exist.
--config-file=filename  Loads the specified project configuration file(s). This option may be repeated to load multiple files.

The new command line arguments are particularly useful for the following purposes:

Transitioning existing data and configuration

The changes to Burp may require some action by users who want to continue working with existing data and configuration:

Feature roadmap

Burp's new capabilities surrounding projects and configuration are fully functional in their own terms, but give rise to a number of desirable features that will be added to Burp over the coming months:

In parallel with the addition of the above features, some existing Burp features will be removed: