ProfessionalCommunity Edition

Filtering the WebSockets history with Bambdas

• Last updated: December 14, 2023

• Read time: 3 Minutes

You can write Java-based Bambdas to create custom filters for your WebSockets history.

Two interfaces of the Montoya API are available to help you write your Bambdas:

• ProxyWebSocketMessage

• Utilities

To create a Bambda to filter your WebSockets history:

1. In the Proxy > WebSockets history tab, click the filter bar to open the Configure filter window.

   The filter bar only appears when there is one or more messages in your WebSockets history.

2. In the Configure filter window, click the Bambda mode tab.

3. Write your Bambda using Java.

4. Click Apply.

Burp compiles your Bambda and applies it to every item already logged in your WebSockets history, and to any future WebSockets traffic generated in this project.

Example Bambda

In the example below, we'll create a Bambda that filters the WebSockets history to show only items that meet the following criteria:

• The message must be sent from the server.

• The message payload length must be greater than 300 characters.

return message.payload().length() > 300 && message.direction() == Direction.SERVER_TO_CLIENT;

Converting filter settings to Bambdas

If you have already used Settings mode to configure a WebSockets history filter, you can convert these settings to a Bambda.

To convert your filter settings to a Bambda:

1. In the Proxy > WebSockets history tab, click the filter bar to open the Configure filter window.

2. Make changes to the filter settings (if necessary).

3. At the bottom of the Configure filter window, click Convert to Bambda.

Your filter is now converted into a Bambda, enabling you to customize it further using Java.

Saving Bambdas

You can save your Bambda as a JSON file. This makes it easy for you to migrate your filter configuration to other projects.

To save a Bambda:

1. In the Bambda mode tab of the Configure filter window, click settings .

2. Click Save settings.

Your Bambda is now downloaded as a JSON file.

Loading Bambdas

You can load a saved Bambda into other projects.

To load a Bambda:

1. In the Bambda mode tab of the Configure filter window, click settings .

2. Click Load settings, then select your Bambda JSON file via the system dialogue.

3. Click Apply.

Your Bambda is now loaded in Burp.

Troubleshooting Bambdas

There are two types of error you may encounter when working with Bambdas: compilation and runtime.

Compilation errors

Burp highlights compilation errors in real time by underlining them in red in the Bambda mode editor. You must resolve any compilation errors before Burp can apply your Bambda.

To display details of the error, hover over the red underline. If you click Apply while your Bambda contains compilation errors, the error details are shown in the Compilation errors tab.

Runtime errors

Runtime errors can occur after a Bambda has been applied. If Burp detects any runtime errors, a banner appears above the filter bar on the Proxy > WebSockets history. Click Edit Bambda to view the error details, and make changes to the code.