Skip to main content

New Burp Suite Extension Blows Your SOCKS Off

Improving Quality-Of-Life With Simple Burp Suite Extensions (Part One)

If you have been using Burp Suite for a while, you probably have some ideas for small features or tweaks to improve your everyday Quality-of-Life experience. As a web application pentester frequently conducting tests over SOCKS proxies, I create new Burp projects and reconfigure Burp’s SOCKS Proxy Settings almost each day, and often multiple times per day. Burp’s Settings page is intuitive and easy to use, but accessing the SOCKS-specific settings requires three-clicks-and-a-scroll that becomes a bit of a nuisance. It can bring out your inner Veruca Salt.

I want SOCKS now! Says Veruna Salt from Willy Wonka meme made by White Oak Security pentester who created the SOCKS burp suite extension

SOCKS Burp Suite Extension

To make SOCKS settings available in a single click, I have developed the SOCKS Settings extension seen below. In this article, we’ll take a tour of the features of the extension and discuss some tips for folks new to the Montoya API and NetBeans GUI development. I think that the Burp Extension ecosystem has a lot of room for these Quality-of-Life-type improvements, and I hope by the end of the tour you’ll have the confidence to develop a new extension and make your life a little easier too.

White Oak Security’s new SOCKS burp suite extension that improves your quality of life for penetration testing made quick and simple.

SOCKS Settings

Burp’s SOCKS Proxy settings page is already quite good and offers all the configuration options that we want, so for this extension, we’re primarily focused on re-implementing the existing functionality into a new “SOCKS Settings” tab. The stock settings page can be seen below. In my use case, Username and Password options are never used, so they have been omitted in the SOCKS Settings extension to reduce on-screen clutter:

Screenshot of the SOCKS proxy settings in burp suite with use socks proxy checked and do DNS lookups over SOCKS proxy checked

Let’s start taking a look at our code and the basic ingredients we’ll need for a functional extension. Numbers in the following paragraphs correspond to those in the screenshot below. 

Like all new Burp extensions, we need to define a new interface that implements the BurpExtension class (1) and has an initialize method that accepts a MontoyaApi object (2). When Burp loads your extension, it passes a MontoyaApi object to the initialize method in your code, which then becomes your extension’s handle for interacting with Burp Suite. 

This is the general design pattern for the new Montoya API. If you’re working with other articles that use the older BurpExtender API, the pattern is pretty similar, but the call to registerExtenderCallbacks is no longer necessary and we can just work directly with the Montoya API object. 

White Oak Security screenshot has 3 highlighted sections that are numbered. 1) implements burpextension 2 initializes and accepts montoyaAPI object  3) socksGUI interface

During initialization of the SOCKS Settings extension, we first log the current SOCKS settings to the extension’s output for some basic debugging.  Then we pass the MontoyaApi object to our socksGUI interface, which hosts most of our extension’s functionality and also contains the definitions to render our input form. Once our socksGUI interface object is instantiated, we can register it as a new Tab to load it in the Burp UI (3), reducing the three-clicks-and-a-scroll problem to a single click.

String Substitution For Setting Settings

The Montoya API provides two methods for interacting with Burp Suite’s settings, exportUserOptionsAsJson and importUserOptionsFromJson. When exporting and importing settings using these API methods, we can provide the JSON path of the exact Setting we’re interested in. We’ll need to first retrieve the current User Settings file through Burp Settings > Manage Global Settings to determine what the ideal JSON path arguments are:

White Oak Security screenshot shows manage global settings > user settings > save user settings

All the settings we need are within the user_options.connections.socks_proxy node:

Code screengrab by white oak security shows highlighted box with SOCKS proxy settings

To get and set these options, we’ll need to parse Burp’s JSON during export, and also provide it a properly formatted JSON object during import. You could import a library for manipulating JSON, but that requires a lot of additional messing about when String substitution works just as well and uses native Java functions. 

To get Burp’s current settings (exporting), we provide the JSON path of the Setting we’re interested in, and then use two regular expressions to strip away the JSON:

JSON path of the SOCKS burp suite extension settings export provided by screenshot of code by white oak security

To set Settings (importing), we reconstitute the JSON object with string concatenation before calling the import method:

JSON Settings import for SOCKS burp extension by white oak security

Beautiful Big Bold Buttons

One of the few improvements I wanted to make over the stock SOCKS Settings interface was to increase the legibility of whether the SOCKS Proxy and DNS Lookups Over SOCKS settings are enabled. I wanted to know at a glance if they are turned on without hunting for little checkboxes on big external monitors. To accomplish this, I developed a new GUI with oversized toggle buttons in NetBeans:

Screenshot by white oak security shows the SOCKS proxy and SOCKS GUI

Swing GUI development in Netbeans is pretty dead-simple, with auto-alignment of form elements already taken care of and double-click access to the code for each element as well. There are four basic steps to GUI development in Netbeans:

  • Design the input form with its necessary elements
  • Double-click form elements to access their backend code
  • Develop code to perform your extension’s primary functionality (e.g., importing and exporting Settings)
  • Add additional action handlers to automate form behavior

Let’s take another look at our extension’s GUI when loaded into a Burp Tab:

Burp suite extension GUI loaded with SOCKS settings and proxy enabled

These toggle buttons dynamically set their display text to “ENABLED” or “DISABLED” depending on the state of the Settings when the refreshExtension method is called (below). Their state can be quickly understood through the blue background fill color, so reading isn’t even necessary. Mike Teavee would be proud!

Refresh extension method by screenshot in white oak security code

The ActionPerformed event listener can be used to execute code each time the toggle button is selected. We just update the state of our internal useProxy variable and then import our updated settings:

Action performed JSON code screenshot by white oak security

When you are working with your GUI, consider using other event listeners as well to improve the responsiveness of your extension. For example, rather than relying on the user to click the “REFRESH / SET” button each time they want to save their settings, the FocusLost event can be used to save the settings and refresh the form as soon as the user clicks away from an input. 

Text field focus lost JSON socks settings screenshot by white oak security

In fact, the “REFRESH / SET” button doesn’t actually need any functionality programmed in it to execute the Setting Import. When the user clicks away from the “SOCKS Host” or “SOCKS Port” text inputs to select the “REFRESH / SET” button, the above FocusLost event will trigger first and execute the Setting Import. The button itself just performs a redundant refresh after that, but it’s nice to have a target on screen to shift focus to:

Jactions button for socks settings white oak security screenshot

You can even use the formComponentShown listener to force an automatic refresh of the GUI whenever the user selects your extension’s tab::

Form compound shown code JSON screenshot by white oak security

A World Of Pure Imagination

Well, I’m sure the SOCKS Settings extension isn’t quite as exciting as a Great Glass Elevator or Everlasting Gobstopper or even a Bean Feast, but we’ve made it to the end of the tour. That means you’ve won! This is terrific! Now the fun is really going to start! Just think of the extensions that have to be made! 

I hope you’ve enjoyed reading this article and have a better understanding of extension development using the Burp Montoya API and GUI development using Netbeans. Now, all that is left is for you to stretch your Java (or Python, or Ruby…) coding fingers and make things the way you want. If you’re looking for some more inspiration, take a look at the Montoya API Examples GitHub.

If you’d like to download the SOCKS Settings plugin, you can do so from the White Oak Security Github page.

For more information on GUI development for Burp extensions, see this archived blog.

If you want to view paradise

Simply look around and view it

Anything you want to, do it

Want to change the GUI?

There’s nothing to it


Veruca Salt – I Want It Now (Willy Wonka and the Chocolate Factory)


White Oak Security provides deep-dive offensive security testing. We are a highly skilled and knowledgeable cyber security and penetration testing company that works hard to help organizations strengthen their security posture by getting into the minds of opponents to try to protect those we serve from malicious threats through expertise, integrity, and passion. 

Our unique industry experience allows us to offer a wide range of services to help analyze and test information security controls and provide guidance to prioritize and remediate vulnerabilities.

Read more from White Oak Security’s pentesting team.