Troubleshooting Burp extensions

To access extensions from the BApp Store in Burp, your device must be able to access portswigger.net. You might not be able to access extensions because:

• You're offline.
• Your network requires an upstream proxy.
• An intercepting proxy is intercepting and resigning traffic with its own certificate. Burp doesn't trust self-signed certificates by default, so it blocks the connection.

If you're working offline in Burp, you can use a separate browser to download extensions from our website, then install them manually. For more information, see Installing extensions manually.

Step 1: Check your internet connection

Make sure your computer is connected to the internet. To verify this, open an external browser and try visiting https://portswigger.net. If you can't access the site, check your network settings or contact your administrator.

Step 2: Configure an upstream proxy

Some networks require an upstream proxy for internet access. If your network requires one, configure Burp to use it:

1. In Burp, click Settings. The Settings dialog opens.

2. Go to Network > Connections.

3. Under Upstream proxy servers, click Add. The Add upstream proxy rule dialog opens.

4. Enter the details of the upstream proxy. For more information, see Connections settings - Upstream proxy servers.

5. Click OK.

6. The upstream proxy rule is added to the table.

Step 3: Identify and resolve an intercepting proxy

Some networks use intercepting proxies, such as ZScaler, to inspect and decrypt encrypted traffic. These proxies intercept HTTPS connections and re-sign certificates, which means Burp won't trust the connection.

To check if an intercepting proxy is impacting your connection:

1. In Burp's browser, go to https://portswigger.net/bappstore.

2. In Burp, go to Settings > Network > TLS.

3. Under Server TLS certificates, find the entry for portswigger.net.

4. Check the issuer of the certificate:

   • If the issuer is a well-known CA provider such as Amazon, it's unlikely that an intercepting proxy is interfering with the connection.

   • If the certificate is issued by an intercepting proxy (such as ZScaler), or your company's security system, then your traffic is being intercepted.

If you identify that your traffic is intercepted by an intercepting proxy, you'll need to set the proxy as a trusted entity. You have the following options:

• Allowlist Burp in the intercepting proxy.

• Configure Burp to use your system's trusted certificate store (Windows only).

• Manually import the intercepting proxy's certificate into Java's trust store.

Option 1: Allowlist Burp in the intercepting proxy

If your security software allows exceptions, add portswigger.net to the allowlist. You may need to ask a network administrator to do this.

Option 2: Configure Burp to use your system's trusted certificate store

If your system already trusts the intercepting proxy's certificate, you can configure Burp to use your system's certificate store instead of its default Java trust store.

This option is quick and easy to set up, but is only available for Windows systems.

To use your system's certificate store:

1. Create a user.vmoptions file. This enables you to specify custom Java options for Burp. For instructions, see Creating a user.vmoptions file.

2. Add the following to the user.vmoptions file:

   -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT

3. Restart Burp, then check if you can access the BApp store.

Option 3: Import the intercepting proxy's certificate into Java's trust store

If you're using MacOS or Linux, or can't configure Burp to use the system's certificate store, you can manually add the intercepting proxy's certificate to Java's trust store.

1. Find the file path of the intercepting proxy's certificate. If you're unsure, check your system settings or ask a network administrator.

2. In Burp, go to Help > Diagnostics. The Burp Suite diagnostics dialog opens.

3. Locate the java.home property and make a note of the path to Burp's Java installation.

4. Open a terminal and use the following command to navigate to the Java bin folder. Make sure to replace JAVA_FOLDER with the Java installation path you noted earlier.

   • MacOS and Linux: cd "JAVA_FOLDER/bin"
   • Windows: cd "JAVA_FOLDER\bin"

5. Import the certificate using the following command. Make sure to replace JAVA_FOLDER with the Java installation path you noted earlier, and CERTIFICATE_FILE_PATH with the path to the intercepting proxy's certificate.

   • MacOS and Linux: keytool -import -trustcacerts -keystore "JAVA_FOLDER/lib/security/cacerts" -storepass changeit -alias MyCert -file CERTIFICATE_FILE_PATH
   • Windows: keytool -import -trustcacerts -keystore "JAVA_FOLDER\lib\security\cacerts" -storepass changeit -alias MyCert -file CERTIFICATE_FILE_PATH

6. Verify that the certificate was added successfully using the following command. Make sure to replace JAVA_FOLDER with the Java installation path.

   • MacOS and Linux: keytool -list -keystore "JAVA_FOLDER/lib/security/cacerts" -storepass changeit | grep MyCert
   • Windows: keytool -list -keystore "JAVA_FOLDER\lib\security\cacerts" -storepass changeit | findstr MyCert

7. Restart Burp, then check if you can access the BApp store.

If you can't install an extension from the BApp Store, the Install button is grayed out. This may be because:

• You need to update Burp.

• You need to install Jython or JRuby.

• You need to upgrade to Burp Suite Professional.

You need to update Burp

Some extensions require features or API methods that were introduced in newer versions of Burp. To update Burp:

1. Click the Help top-level menu.

2. Select Check for updates. A dialog opens with details of the latest Burp version.

3. Click Update now.

4. Wait for Burp to prepare the update. When it's ready, you'll be prompted to restart. Click Update and restart to complete the process.

5. When Burp restarts, return to Extensions > BApp store to download your extension.

You need to configure Jython or JRuby

To use an extension that is written in Python or Ruby, you'll need to configure Jython or JRuby. Burp is a Java application and requires Java-compatible implementations of these languages to run the extension code.

To configure Jython or JRuby:

1. Download the Jython standalone JAR file or the Ruby JAR file.

2. In Burp Suite, click Settings to open the Settings dialog.

3. Go to Extensions.

4. Under Python Environment or Ruby Environment, click Select file.

5. Select the downloaded JAR file and click Open.

Once configured, return to Extensions > BApp Store, click , select Refresh list, then download your extension.

You need to upgrade to Burp Suite Professional

Some extensions require Burp Suite Professional features. If you're using Burp Suite Community edition, you must upgrade to install these extensions.

For more information, see Upgrade to Burp Suite Professional.

If an extension is installed but not working properly, try the following steps to investigate the issue.

Step 1: Update Burp

It's best practice to run extensions on the latest version of Burp. If an extension requires features that were introduced in a newer version than the one you're using, it may not function correctly.

To update Burp:

1. Click the Help top-level menu.

2. Select Check for updates. A dialog opens with details of the latest Burp version.

3. Click Update now.

4. Wait for Burp to prepare the update. When prompted, click Update and restart to finish.

5. When Burp restarts, check that your extension is working as expected.

Step 2: Visit the extension's repository

All extensions in the BApp Store include a link to PortSwigger's fork of the author's GitHub repository. This may include additional documentation and troubleshooting information.

To access the author's GitHub repository:

1. In Burp, go to Extensions > BApp Store.

2. Select the extension you want to investigate.

3. In the description panel, scroll to Source and click the repository link.

4. Review the README file and any other resources in the repository.

Step 3: Use AI to review the extension's code

You can use an LLM to help you understand how the extension works and identify any bugs. To support this, we provide a CLAUDE.md file that includes essential context on how Burp extensions are structured for the model.

Before you start, you'll need to install or access your preferred LLM. These instructions use Claude Code, but you can adapt them for use with other LLMs. For more information on Claude Code, see the Anthropic documentation.

Step 1: Access the extension code file

To access the extension's code:

1. In Burp, go to Extensions > BApp Store.

2. Select the extension you want to review.

3. In the description panel, scroll to Source and click the repository link.

4. In GitHub, if the repository was forked, click the Forked from link to access the original repository.

5. Fork the original repository to your own GitHub account.

6. Clone your forked repository to your local machine.

7. Open or import the local clone into your IDE.

Step 2: Run your LLM to analyze the extension

To use Claude Code to review the extension:

1. Download our CLAUDE.md file and supporting documentation from GitHub.

2. Add the CLAUDE.md file to the root of the extension's folder.

3. Create a docs folder in the extension's folder and add the supporting documentation inside it.

4. Open a terminal and navigate to the extension's folder.

5. Run Claude Code using the following command: claude.

6. Prompt Claude to review the code, explain how to use the extension, and identify any bugs.

Claude should automatically read the contents of the ExtensionTemplateProject folder, including the CLAUDE.md file, then explain how the extension works. If you think it hasn't read the CLAUDE.md file, directly prompt it to do so before continuing.

If you identify any issues with the extension's code, you can report this to the extension's author to fix.

Step 4: Report an issue or suggest a fix to the extension's author

PortSwigger doesn't maintain the community-created extensions in the BApp Store. If you believe you've found a bug or need support for a particular extension, please contact the extension's author through their repository.

To do this, you need to access the author's original extension repository:

1. In Burp, go to Extensions > BApp Store.

2. Select the extension you want to investigate.

3. In the description panel, scroll to Source and click the repository link.

4. If the repository was forked, click the Forked from link to access the original repository.

Option 1: Report an issue

If you don't have a proposed solution, you can still report the issue to make the extension's author aware of the problem:

1. In the extension author's original repository, click the Issues tab.

2. Review existing issues to see if the problem has already been reported.

3. If not, click New issue and describe the problem in detail, including:

   • The version of Burp Suite you're using.

   • The operating system.

   • Any relevant steps to reproduce the issue.

   • Screenshots or logs, if applicable.

Option 2: Suggest a fix

If you've identified the cause of the issue and have a proposed solution, you can suggest a fix. This may speed up the resolution process.

To suggest a fix:

1. Fork the extension author's original repository.

2. Make changes to the extension's code.

3. Create a pull request. In the description, clearly describe the problem and proposed fix, including:

   • The version of Burp Suite you're using.

   • The operating system.

   • Any relevant steps to reproduce the issue.

   • A summary of the changes introduced by your fix.

   • Screenshots or logs that support your solution, if applicable.

Extensions can cause Burp to run slowly. Extensions on the BApp Store aren't tested by PortSwigger for performance.

If you notice performance issues while using extensions, try the following troubleshooting steps:

Step 1: Disable unused extensions

Running too many extensions can slow Burp down. To minimize resource usage:

1. In Burp, go to Extensions > Installed.

2. In the Loaded column, uncheck any extensions you're not currently using.

3. Restart Burp.

4. Test Burp's performance.

Step 2: View the performance impact estimate for particular extensions

Before testing an extension manually, you can get a general idea of its impact by checking the Estimated system impact ratings in the BApp Store.

To check the expected system impact of a specific BApp Store extension:

1. Go to Extensions > BApp Store.

2. Select the extension and scroll down the right-hand panel to Estimated system impact.

3. Review the estimated impact across the following categories:

   • Memory - Potential impact on Burp Suite's memory usage.

   • CPU - Additional processing load on the CPU.

   • Time - Impact on Burp's overall speed. This includes the responsiveness of the interface and how long tools take to complete tasks.

   • Scanner - Potential increase in scan duration.

   • Overall - The highest impact rating among all categories.

Step 3: Manually test extensions

Extensions can impact performance individually, or the combination of extensions can cause a performance issue. Follow these steps to pinpoint the cause:

1. Disable all extensions:

   1. In Burp, go to Extensions > Installed.

   2. In the Burp extensions table, click anywhere in the list and press Ctrl + A or Cmd + A to select all extensions.

   3. Right-click then select Unload. This unloads all your installed extensions.

   4. Test Burp's performance without any extensions enabled.

2. In Extensions > Installed, re-enable extensions one at a time, starting with the ones you want to use immediately.

3. Test Burp's performance after enabling each extension. If Burp slows down, the recently enabled extensions may be causing the issue.

4. If Burp slows down after enabling multiple extensions, disable them selectively to identify conflicts.

You may see this error message if you load several Python or Ruby extensions, or if you unload and reload extensions multiple times.

To avoid this issue, configure Java to allocate more Metaspace storage:

1. Open a terminal or command prompt.

2. Add -XX:MaxMetaspaceSize=1G to the command you use to launch Burp, as follows:

   java -XX:MaxMetaspaceSize=1G -jar FILE_PATH.jar