Working With Burp Projects

Burp projects are used to manage your work on different tasks or target applications. You can create two types of Burp projects:

  • Temporary projects are 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.
  • Disk-based projects allow you to save your work and resume it later. All data is held on disk in a project file.

Project Files

Burp project files hold all of the data and configuration for a particular piece of work. Data is saved incrementally into the file as you work. There is no need to specifically "save" your work when you are finished.

You can reopen an existing project when Burp starts, using the startup wizard or command line arguments. Burp will reload the project's data and configuration, and you can resume working where you left off.

Note: Testing of some applications can generate significant amounts of data, and so Burp project files can potentially grow to be very large (e.g. several gigabytes in size). You should ensure that you have sufficient free disk space available when using Burp project files.

Saving a Copy of a Project

You can save a copy of the current project into a new project file by selecting "Save copy of project" from the Burp menu.

You can choose the tools whose data you want to be included in the new project file, and whether you only want to save in-scope items.

This feature can be useful to create a smaller project file after you have refined your project scope, or deleted some unwanted data.

You can continue using Burp while the new project is being saved, although you may experience some brief delays if you try to perform an operation on data that Burp is in the process of saving, to prevent any data corruption.

Saving the Burp Collaborator Identifier

When saving a copy of a project, you will be prompted whether to include within the project file the unique identifier that Burp uses to retrieve any ongoing Burp Collaborator interactions that are associated with the project. If two instances of Burp share the same identifier in ongoing work, then some Collaborator-based issues may be missed or incorrectly reported. You should not include the Collaborator identifier if you plan to pass the project file on to someone else and you do not want them to be able to receive details of any ongoing Collaborator interactions that are associated with your testing.

Configuration Files

You can use configuration files to manage different Burp 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.

User and Project Configuration Files

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

User configuration files contain options relating to the individual user's environment and UI, including:

  • Everything in the User options tab.
  • 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 configuration files contain options relating to the work that is being performed on a particular target application, including:

Loading and Saving Configuration Files

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 "Options" button to load or save the configuration for just that panel.
  • In the 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 command line arguments to specify one or more configuration files from which to load user-level or project-level options.
  • Burp extensions can load or save configuration file contents via the API.

Configuration File Format

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 "Options" button on each configuration panel, or by removing the unneeded sections from a full configuration file. When configuration is loaded from a partial configuration file, 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.