Playing With the New Burp Suite REST API

One of the coolest new features released in the recent beta version of Burp Suite is the introduction of a REST API. I blogged about the UI and some other feature enhancements earlier this week. Today I want to talk a little bit about a command-line Ruby script that I’ve written to interface with this REST API called Burpcommander.

Introducing Burpcommander

Burpcommander is a proof-of-concept Ruby script which demonstrates the ease in which you can interact with the new Burp Suite REST API over http. The code is hosted here on our Github page. Check it out and install the necessary Ruby gems to begin testing it out. The OOB code can do the following:

• Query the Issue knowledge base by :issue_type_id
• Query the Issue knowledge base by :name
• Return the entire JSON object or just the issue description
• Start a default scan of a given target with or without credentials
• Query the status of the :ScanProgress
• Grab all the issues from a given scan :task_id
• Grab a single/specific issue from a given scan :task_id

Enabling the REST API

In addition to downloading the Burpcommander code, you’ll need to configure the REST API inside the Burp Suite User/Misc. options page. Simply turn on the REST API by checking the “Service running” box and create a New API key. Make sure to copy the key to your clipboard and securely store it somewhere.

Querying The Knowledge Base

You can use Burpcommander to query the issue knowledge base either by searching a specific :issue_type_id or simply doing a text-based search on the :name filed. Here is an example of what that looks like. API Keys are generated at random and useless after the service has stopped running so don’t freak out about the clear-text keys in the following screeshots.

Starting A New Scan

We can launch a new scan from the command line as well. Currently the PoC script only supports the default scan profile however you can find the documentation to the API just by navigating to it in a browser. If you are familiar with Ruby it wouldn’t be difficult at all to modify the code to take in an additional argument which points to a specific the scan profile you wish to use. Here is what it looks like when you launch a new scan.

Burpcommander will return the :task_id for the scan which was just launched. We can leverage this to make additional requests to the REST API. In this case Burp Suite has created a scan with task_id #3. If we check back in the Dashboard we can see that the scan has been successfully initiated.

Check the Status of an Existing Scan

Now that we know the :task_id of our new scan we can query the REST API for its :ScanProgress which can tell us useful information about the current status of the scan and any results/issues that have been discovered. Here are a couple of example requests using Burpcommander.

We can request to see the :scan_metrics like this.

Here it shows this scan has still has items in the queue and that their are 47 issues so far. We can query all of the issues or specific a specific one just by using the “-I” option.

Conclusion For Now

That’s as far as I’ve gone up to this point but many of you have already begun to play around with this code. There is even a Python Fork! I think this proof-of-concept does a good job on demonstrating some of the things you can do with this REST API but certainly their are many more use cases which would be thought of and implemented hopefully using this code as a framework. If you want to contribute check out the Github repo and fork your own copy. You can also post a comment below if you have a feature request you would like to see implemented. That’s all for now, thanks for reading!

Hack responsibly

Share this article