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:
-
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.
-
In the Configure filter window, click the Bambda mode tab.
-
Write your Bambda using Java.
-
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.
Note
Converting your filter settings overwrites any existing Bambda in your WebSockets history.
To convert your filter settings to a Bambda:
-
In the Proxy > WebSockets history tab, click the filter bar to open the Configure filter window.
-
Make changes to the filter settings (if necessary).
-
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:
-
In the Bambda mode tab of the Configure filter window, click settings .
-
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:
-
In the Bambda mode tab of the Configure filter window, click settings .
-
Click Load settings, then select your Bambda JSON file via the system dialogue.
-
Click Apply.
Your Bambda is now loaded in Burp.
Note
Bambdas are only compatible with the tool that they were exported from. For example, a Bambda created for filtering the WebSockets history cannot be loaded in a different Burp tool.
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.