Burp Suite, the leading toolkit for web application security testing

PortSwigger Web Security Blog

Friday, April 8, 2016

Introducing Burp projects

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
  • Changes to Burp's configuration options
  • Configuration files
  • The new startup wizard
  • New APIs
  • New command line arguments
  • Transitioning existing data and configuration
  • Feature roadmap

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:
  • Data is saved automatically in real time. There is no need to specifically save your work when you are finished. If Burp exits abnormally, all its data is preserved.
  • Burp reopens project files considerably faster than state files. In our testing, project files that are several gigabytes in size can be reopened in a few seconds.
  • A problem with Burp's non-incremental automatic backup feature, where each periodic backup consumed more and more disk space, has gone away.
  • All data is held in the project file, including some items that were not previously included in state files, such as the Scanner's issue activity log.
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:
  • Everything in the new "User options" tab, such as font settings.
  • Options in the Extender tool, including the list of configured extensions.
  • UI-related options in other tools, such as the selected view of the Target site map.
Project-level options are those relating to the work that is being performed on a particular target application, including:
  • Everything in the new "Project options" tab, such as session handling rules.
  • Non-UI-related options in individual Burp tools, such as Proxy and Scanner.
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:
  • From the Burp menu, you can load or save configuration files for all user-level or project-level options:

  • From individual configuration panels throughout Burp, you can use the new "Options" button to load or save the configuration for just that panel:

  • In the new startup wizard, when creating or reopening a project, you can specify a configuration file from which to load project-level options:
  • When starting Burp from the command line, you can use the new command line arguments to specify one or more configuration files from which to load project-level options.
  • Burp extensions can load or save project-level configuration file contents via the new APIs.
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:
  • Temporary project - This option is useful for quick tasks where your work doesn't need to be saved. All data is held in memory, and is lost when Burp exits.
  • New project on disk - This creates a new project that will store its data in a Burp project file. This file will hold all of the data and configuration for the project, and data is saved incrementally as you work. You can also specify a name for the project.
  • Open existing project - This reopens an existing project from a Burp project file. A list of recently opened projects is shown for quick selection. When this option is selected, the Spider and Scanner tools will be automatically paused when the project reopens, to avoid sending any unintentional requests to existing configured targets. You can deselect this option if preferred.
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:
  • Use Burp defaults - This will open the project using Burp's default options.
  • Use options saved with project - This is only available when reopening an existing project, and will open the project using the options that were saved in the project file.
  • Load from configuration file - This will open the project using the options contained in the selected Burp configuration file. Note that only project-level options in the configuration file will be reloaded, and any user-level options will be ignored. A list of recently used configuration files is shown for quick selection.

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:
  • When automating Burp from scripts or other processes, you can launch Burp with a specified project file and configuration file. For example, your CI pipeline could launch Burp specifying the filename into which the project will be saved as an artifact, and a configuration file containing details of target scope or scanning options.
  • If you create different configuration files for common purposes, you can create desktop shortcuts to launch Burp with different configurations. When Burp is launched with the config-file option, the startup wizard will skip the step to select a configuration file, thereby speeding up the startup process.

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:
  • To transition data and configuration in an existing Burp state file, simply create a new Burp project, and then restore the state file in the normal way. All of the data and configuration from the state file will be stored in the project file, and this can then be reopened directly without need for the original state file.
  • Settings that are now part of user-level options (such as font settings) will automatically carry over from earlier versions of Burp.
  • Settings that are now part of project-level options (such as session handling rules) will not automatically carry over from earlier versions of Burp. If you have customized these in your locally saved settings, and want to use them in the new version, you'll need to use an old version of Burp to save a config-only state file, use the new version of Burp to restore that state file, and then save a configuration file containing the project-level options. When creating new Burp projects, you can select that configuration file in the startup wizard.

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:
  • If you launch Burp and choose to create a temporary project, it is not currently possible to change your mind and save your work into a disk-based project at a later time. We plan to provide a means of doing this.
  • Data is incrementally appended onto project files as it is generated. If you accumulate a large amount of data and then delete some of this within Burp (for example, by clearing a large Proxy history), the data is not actually removed from the project file, and the project file will not reduce in size. We plan to provide a means of compressing a project file to remove redundant data and reduce its size.
  • With the existing state file functionality, it is possible when saving a state file to select which tools' data to include, and whether to include only in-scope items. With the new project file feature, all of Burp's data is saved into the project file. We plan to provide a means of saving a project file that contains only selected items.
  • With the existing state file functionality, it is possible to restore multiple state files into the same instance of Burp, to merge the results of earlier work. With the new project file feature, only a single project file can be opened into each instance of Burp. We plan to provide a means of importing multiple project files to create a single combined project.
  • Intruder options are not currently handled by the new configuration file feature. We plan to provide a new way of handling Intruder configuration and attack data, based closely on the new Burp configuration and project files.
In parallel with the addition of the above features, some existing Burp features will be removed:
  • The automatic backup feature, which saves Burp's state periodically into state files, has been removed in the new release.
  • Existing APIs relating to configuration options and state files have been deprecated.
  • The ability to save new state files will be removed in the near term.
  • The ability to restore old state files will be removed in the longer term.


Lee Baird said...

What about the follow:
Mapping each findings to OWASP and WASC Threat Classification v2.0
Provide more external links for each finding
Provide "How to" links on finding to existing blog posts
The BApp Store needs a new column name "Updated" so that you can easily track when the extensions have been updated

Daniel Miessler said...

Phenomenal work, team.

vizzdoom said...

Just awesome. Great work!

Watnegutten said...

Why do you still have the save/restore state option if the project files are replacing the state functionality?

I just opened my project, saved the state within the project and restored it again within the project.

the result was a project file with double size...

Dafydd Stuttard said...


1. We are retaining the state file functionality for a while so that people can still work with their existing state files.

2. State files are compressed with ZIP while project files are not compressed as their contents are accessed directly at runtime, rather than being saved/loaded via stream I/O. So project files are larger but deliver huge performance and functional improvements over state files.

Anonymous said...

Automatic Backup Feature which was available in 1.69 is no longer Available in 1.7beta?

Dafydd Stuttard said...

@Anonymous. Correct. As stated in the blog post the automatic backup state feature has already been removed. Data is saved automatically in real time into disk-based project files so there is no need to use automatic backup of state.

Max said...

tnx for great update. What about GUI changes? Options>Display>User Interface and new themes such as DARK UI and others?

Max said...

hmm, on start burp now we need each time choose option+conf options((
this is very bad update.
This update was killed my good conf.
Not recommend this version, I'll back to 1.6.39.
Not good very not good portswigger((

Watnegutten said...

I'm not sure I understand what your problem is Max, but you can save your configs if you want and import them back whenever you start a new project.
Additionally, your user options will stay persistent from project to project if you choose to.

Dafydd Stuttard said...

@Max You can open Burp in two mouse clicks on the startup wizard, so it won't slow you down much. Read the blog post for details of how to migrate existing settings and data - nothing is lost. If you create a preferred default config file, you can even create a desktop shortcut that loads Burp with this config, and bypasses the second step of the startup wizard.

Max said...

now I tested with some startups.
Created new project. Then when proxy&target is clear I was changed options for me, then saved this options in json. Then close burp.

--Open again burp then choosed that project and conf file. Normally opened. Close burp
--Open again burp choosed temp project and in second step choosed my conf file. See all burp options in clear. All options really clear 100%. Example default burp options can start with 60-70% choosed params, but this 100% clear.

--Open burp again choosed that project+my conf file. Opened with my project+clear options 100%.

I think burp will save incrementally all options+data in file+conf file on each exit. On 1.6.39 we can choose save on exit or not save.

Pls if you can revert back startup from 1.6.39. This is really problem if user have tuned burp options and project options will kill all of them.
Sorry for bad english.

Max said...

may be you can delete this startup option and place it as new tab? Then user can choose work with projects or not. Im really not need this option and if need I can save state and close burp.
New tab with projects will be good choise, who need will use, who not need wil not activate.

Dafydd Stuttard said...

@Max I don't understand what you're talking about saying that options are "100% clear".

The new Burp features give you everything you could do previously and a lot more besides. It sounds like you haven't fully understood how the new features work. I suggest you have a careful read of the blog post and the Burp documentation on using configuration files. If you use them correctly, you can create configuration files for different purposes, and load them on project creation or at any time later. You have complete flexibility.

Max said...

with 100% options clear I mean that all options not checked. If user not want to store all time save to project file it need during startup choose temp file and in second step choose its tuned conf. Then user will see absolutely clear option(not checked any options).
I think you need revert back old burp function with startup. After expiring my license ill not update burp lic.

Max said...

I think this startup function specially for security from cracks loaders, but this will create discomfort for real users.

Dafydd Stuttard said...

@Max. If you have created a config file with your preferred default project options, then you just need to select it at step two of the startup wizard. It will show in the recent list, so it is a single mouse click to select it. There is no need to select a temp file in the first step - just leave the default option to create a temporary project if that is what you want.

FYI the new behavior is here to stay and we will eventually remove state file support as per the blog post.

Max said...

I can select previously created project from recent list, but after each work with burp, it save previously webapps/domains in the project file. I'm not need it and want only after startup open clear burp with my tuned conf. I think u understand me.
You can check on startup. Select temp project and not recent project. On second step select you conf(from that project). You will see. Burp will start with not configured and default params too not checked.

Dafydd Stuttard said...

@Max I think you're doing something wrong.

1. If you use a disk-based project, then options are saved with that project file, and will reappear if you reopen the project. This is intended behavior.

2. If you use a temporary project and select your own config file in the second step of the startup wizard, then the project will open with the configs from that file (assuming it is a valid Burp config file, not a project file). No options will be saved when the temporary project is closed.

Anonymous said...

Create option for "Configurating Temporary Project".
Now is terrible...

Anonymous said...

I want to create my default configuration for "Temporary project".

Dafydd Stuttard said...

@Anonymous You can specify the configuration for a temporary project the same as a disk-based one. Use the Burp UI to create your desired configuration, and then save a configuration file for project options, via the Burp menu. Then you can either:

(a) Select the configuration file in the second step of the startup wizard. After selecting it once, it will show in the recent list for faster selection.

(b) Create a desktop shortcut that uses the --config-file argument to specify your configuration file, thereby skipping the second step of the startup wizard.

Boris said...

Dear mr.
I think you started to destroy burp suite, it was such a wonderful product.
After version 1.6.39 was impossible to use a burp with the normal configuration settings. Please delete the autosave feature of the project file, and add the ability to save your configuration on a temporary project. It turns out too large file.

Dafydd Stuttard said...

@Boris. You can do this. You can save and load your configuration for any project at any time, including temporary projects. Go to Burp menu / Project options. When you've saved a config file with your settings, you can load it manually whenever you need to, or select it during project startup, or specify it via a command-line argument (so you can create a desktop shortcut to use it).

Peter said...

Thank you for all the awesome features in 1.7. State files sometimes used to take hours to save and load, but projects take only seconsd. We also like the flexible way of working with preferences. Keep up the great work!

Anonymous said...

Hi Guys,
Is there an option to get the 'snip' of data sent/received in the xml file output (similar to what we see in the html report output) yet? I saw that request a while back, but if you responded, I missed it.


Dafydd Stuttard said...

@Shane. There is still a pending feature request to provide HTML exerts in the XML output.

Max said...

Thank you Dafydd Stuttard.
The problem of configuration files for a temporary project solved.
1. Prompt how to remove/clear deleted projects/jsons from recent file list?
2. And what about desktop link for quick start? java -jar -Xmx4g /path/to/burp.jar --config-file=my-conf.json?
3. What about other UI look and feel(themes)?

Dafydd Stuttard said...

@Max Glad you got the configuration handling working.

We're planning to improve the recent lists to remove deleted items.

Yes, you can use a shortcut like you've described. Use the --help argument to see a list of available command line arguments.

We aren't actively working on support for different UI themes, sorry.

Max said...

I think just adding on various themes UI can increase product sales

Thanks again for such a powerful tool

Kelley Bryant said...

Hi - I there away for only inscope targets to be saved incrementally in the background? My .burp files are huge due every target being saved. I only want the targets I select as inscope to be saved automatically.

Dafydd Stuttard said...

@Kelley. At present, everything gets saved. We plan to offer two relevant features in future:

1. The ability to save a copy of a project file containing only selected items, based on scope and Burp tool, similar to the options that you have when saving state.

2. An option to not capture out-of-scope items anywhere in Burp, including Proxy history and Target site map, so that out-of-scope items never go into the project data.

Kelley Bryant said...

@Dafydd Either would be great! Thank you.

Max said...

Dear Dafydd
tnx to new version.
Now im tested new feature about project file start and not working.

I have my-conf.json file.
In first time in first step selectted temp project. In 2nd step selected Load from configuration file and chhosed my-conf.json+selected to DEFAULT IN THIS OPTION IN FUTURE.
ok burp started.
Then I close burp and open brup again.
1st step temp project, then in 2nd step I see again when I need choose again my konf file and then start.
Of course i can use my start.bat which have:
java -jar -Xmx4g burpsuite_pro_v1.7.03.jar --config-file=burp1.7conf.json

but I think it is not convenient for users

Dafydd Stuttard said...


When you use the "Default to this option in future" checkbox, Burp will remember your config file selection when you start a new project in future. The second step of the startup wizard is still show, in case you want to change from this default, but your remembered config will be pre-selected on that step.

Max said...

ok Dafydd now understand.
Good job and big tnx again

Anonymous said...

If you start burp with the command --project-file=blah, a file called blah.burp is automatically created. However, once blah.burp is created, further calls using --project-file=blah causes the app to crash with no error. Using --project-file=blah.burp fixes the problem.

My guess is that the app checks for a file called "blah" and, seeing that none exist, tries to create a file called blah.burp. But since blah.burp does exist, it crashes.

Dafydd Stuttard said...

@Anonymous. Thanks for this report. We'll get the problem fixed.

Anonymous said...

How can I change my default "project settings" ?
Can I change my default setting to "Temporary project" ?

Dafydd Stuttard said...


1. Create your desired config file, select it during project startup, and tick the "Default to this option in future" box.

2. The default selection is always "Temporary project", so this is already the default.

richie said...

Is there a way to reduce the size of the project file.
The old system allowed you to only save items in scope, but there doesn't seem to be this option with the project files, which can make them massive and full of useless stuff.

Dafydd Stuttard said...

@richie We're aware of this limitation and we plan to provide ways of both:

- Saving a copy of a project file that includes only in-scope items
- Configuring Burp to not capture any data regarding out-of-scope items

We don't yet have a firm ETA for these features but they are in our near-term roadmap.

Anonymous said...

It's time consuming... Can you create option to "override" the Temporary Project Default Options ???

Dafydd Stuttard said...

@Anonymous You can do this in current versions of Burp. Create a project options file containing the options you want. Then on the second step of the startup wizard, select that file and check the "Default to this option in future" box.

Support Center

Get help and join the community discussions at the Burp Suite Support Center.

Visit the Support Center ›

Copyright 2016 PortSwigger Ltd. All rights reserved.