Burp Suite is an integrated platform for performing security testing of web applications. It is not a point-and-click tool, but is designed to be used by hands-on testers to support the testing process. With a little bit of effort, anyone can start using the core features of Burp to test the security of their applications. Some of Burp's more advanced features will take further learning and experience to master. All of this investment is hugely worth it - Burp's user-driven workflow is by the far the most effective way to perform web security testing, and will take you way beyond the capabilities of any conventional point-and-click scanner. Burp is intuitive and user-friendly, and the best way to start learning is by doing. These steps will get you started with running Burp and using its basic features. You can then read on deeper into the documentation to become more proficient in using this supremely powerful tool.
Note: Using Burp Suite may result in unexpected effects in some applications. Until you are fully familiar with its functionality and settings, you should only use Burp Suite against non-production systems.
Burp Suite is a Java application and is distributed as a standalone Java executable file, with the .JAR extension. You can download Burp Suite Free Edition from the PortSwigger.net website. For Burp Suite Professional users, you can log in and download the latest Professional build using your account details. The Burp JAR file can be executed using a Java Runtime Environment, and there is no need to unpack the contents of the JAR file itself.
To launch Burp, first check whether Java is installed:
With Java installed, on some platforms you may be able to run Burp directly by double-clicking the Burp JAR file. However, it is preferable to launch Burp from the command line, as this gives you more control over its execution, in particular the amount of memory that your computer assigns to Burp. To do this, in your command prompt type a command like:
java -jar -Xmx1024m /path/to/burp.jar
where 1024 is the amount of memory (in Mb) that you want to assign to Burp, and /path/to/burp.jar is the location of the Burp JAR file on your computer.
If everything is working, a splash screen should display for a few seconds, and then the main startup wizard window should appear. If nothing happens, or if an error message appears, please refer to the troubleshooting help.
Various command line arguments are available to control Burp's behavior on startup. For example, you can tell Burp to prevent reloading of extensions, open a particular Burp project file, or load a particular configuration file.
You can view a list of available options using the command line argument --help.
When Burp launches, the startup wizard is displayed. This lets you choose what Burp project to open, and what project configuration to use.
You can choose from the following options to create or open a project:
Note: You can rename a project later via the Burp menu.
You can choose from the following options for the project configuration:
If you open an existing project that was created by a different installation of Burp, then Burp will prompt you to decide whether to take full ownership of the project.
This decision is needed because Burp stores within the project file an identifier that is used 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 only take full ownership of a project from a different Burp installation if no other instance of Burp is working on that project.
The first time you run Burp, it is worth taking a moment to check your display settings. Burp lets you select different sized fonts for different parts of the UI, and you may want to change these settings, depending on your screen resolution.
First, look at the text shown in Burp's menus, tab captions, buttons and other text. If you want to change the main UI font size, go to the Options tab, then go to the Display sub-tab, and edit the font size in the User Interface section. Then restart Burp and check whether the new font is suitable.
Second, go to the Repeater tab and look at the HTTP message shown in the request panel. If you want to change the font size for HTTP messages, go to the Options tab, then go to the Display sub-tab, and edit the font size in the HTTP Message Display section. Then go back to the Repeater tab and check whether the new font is suitable (there is no need to restart).
Burp is designed to be used alongside your browser. Burp functions as an HTTP proxy server, and all HTTP/S traffic from your browser passes through Burp. To do any kind of testing with Burp, you need to configure your browser to work with it.
Firstly, you need to confirm that Burp's Proxy listener is active and working. Go to the Proxy tab, then the Options sub-tab, and look in the Proxy Listeners section. You should see an entry in the table with the checkbox ticked in the Running column, and "127.0.0.1:8080" showing in the Interface column. If this is not the case, try pressing the "Restore defaults" button to the left of the panel. If the listener is still not running, then Burp was not able to open the default Proxy listener port (8080). You will need to select the table entry, click "Edit", and change the port number of the listener to a different number. See the Proxy listeners help for more details.
Secondly, you need to configure your browser to use the Burp Proxy listener as its HTTP proxy server. To do this, you need to change your browser's proxy settings to use the proxy host address (by default, 127.0.0.1) and port (by default, 8080) for both HTTP and HTTPS protocols, with no exceptions. The details of how to do this vary by browser and version, but are roughly as follows:
When you've configured your browser, you need to test that it is working properly. With Burp running, in your browser go to any HTTP URL (don't use HTTPS for the moment). Your browser should sit waiting for the request to complete. In Burp, go to the Proxy tab, and then the Intercept sub-tab. These tabs should be highlighted, and there should be an HTTP request showing in the main panel. Click on the "Intercept is on" button so that it says "Intercept is off". Go back to your browser, and you should (shortly) see the URL you requested being loaded in the normal way. If things aren't working in the way described, please refer to the troubleshooting help.
Finally, you need to configure your browser to be able to send HTTPS requests through Burp without any problems. This step isn't strictly necessary to use Burp in a basic way or only for non-HTTPS URLs, but it only needs to be done once and is necessary to get the most out of Burp when testing applications that use HTTPS. The reason for this requirement is that Burp breaks SSL connections between your browser and destination web servers, in order to view and modify the plain contents of HTTPS messages. SSL is designed to prevent this happening, and so by default your browser will show a security warning when you visit an HTTPS URL using Burp. To ensure that applications using HTTPS function properly, you need to install Burp's Certificate Authority (CA) SSL certificate in your browser trust store. For detailed help on doing this, please refer to the help on installing Burp's CA certificate. When you have done this, you can confirm things are working properly by closing all your browser windows, opening a new browser and visiting any HTTPS URL. The browser should not display any security warnings, and the page should load in the normal way (you will need to turn off interception again in the Proxy Intercept tab if you have re-enabled this).
Once you have Burp running, and have configured your browser to work with Burp, go to the Proxy Intercept tab, and ensure that interception is turned on (if the button says "Intercept is off" then click it to toggle the interception status). Then go to your browser and visit any URL.
Each HTTP request made by your browser is displayed in the Intercept tab. You can view each message, and edit it if required. You then click the "Forward" button to send the request on to the destination web server. If at any time there are intercepted messages pending, you will need to forward all of these in order for your browser to complete loading the pages it is waiting for. You can toggle the "Intercept is on / off" button in order to browse normally without any interception, if you require. For more help, see Getting started with Burp Proxy.
As you browse an application via Burp, the Proxy history keeps a record of all requests and responses. In the Proxy, go to the History tab and review the series of requests you have made. Select an item in the table and view the full messages in the Request and Response tabs.
Also, as you browse, Burp builds up a site map of the target application. Go to the Target tab, and the Site Map sub-tab, to view this. The site map contains all of the URLs you have visited in your browser, and also all of the content that Burp has inferred from responses to your requests (e.g. by parsing links from HTML responses). Items that have been requested are shown in black, and other items are shown in gray. You can expand branches in the tree, select individual items, and view the full requests and responses (where available). For more help, see Using the Target tool.
Burp Suite is designed to be a hands-on tool, where the user controls the actions that are performed. At the core of Burp's user-driven workflow is the ability to pass HTTP requests between the Burp tools, to carry out particular tasks. You can send messages from the Proxy intercept tab, the Proxy history, the site map, and indeed anywhere else in Burp that you see HTTP messages. To do this, select one or more messages, and use the context menu to send the request to another tool.
The Burp tools you will use for particular tasks are as follows:
You can combine Burp's different tools in numerous ways, to perform testing tasks ranging from very simple to highly advanced and specialized. For more detailed help on Burp's user-driven workflow, see Using Burp Suite.
If you don't want to use Burp as a hands-on testing tool, and only want to perform a quick and easy vulnerability scan of your application, please refer to Using Burp as a Point-and-Click Scanner.
There is extensive documentation for all of Burp's tools and features, and the typical workflow you need to use when testing with Burp.
Get help and join the community discussions at the Burp Suite Support Center.
This major release introduces several new features, including: