Setting up the external database
Last updated: September 30, 2022
Read time: 5 Minutes
In this section, we'll show you how to set up a database that you want to connect to Burp Suite Enterprise Edition. This is relevant in the following cases:
You have been using Burp Suite Enterprise Edition's embedded database and want to transfer your data to an external one.
You want to create a standard deployment of Burp Suite Enterprise Edition and use an external database from the start.
You want to deploy Burp Suite Enterprise Edition to Kubernetes.
Preparing the database for Burp Suite Enterprise Edition involves the following high-level steps:
Connect to your database server.
Run the setup script for your database type. This creates a database and two users for Burp Suite Enterprise Edition.
Note the connection URL for your database. You will need this later to connect Burp Suite Enterprise Edition.
For more information on database system requirements, see Burp Suite Enterprise Edition system requirements .
Database setup scripts
The setup scripts below create a new database and two users:
burp_agent. These are used by the Enterprise server and your scanning machines to connect to your database. If you're setting up this database in order to migrate from the embedded one, you must use these exact usernames.
You should substitute the placeholder
******** strings used in the example script with your own strong passwords.
CREATE DATABASE burp_enterprise; CREATE USER burp_enterprise PASSWORD '********'; CREATE USER burp_agent PASSWORD '********'; GRANT ALL ON DATABASE burp_enterprise TO burp_enterprise;
If you're migrating data from Burp Suite Enterprise Edition's bundled database to a new PostgreSQL database, you must also temporarily assign the
SUPERUSER role to the
burp_enterprise user. This is a prerequisite for running the database transfer tool that we provide. We recommend demoting the user again once you have completed the migration.
CREATE TABLESPACE burp_enterprise_tabspace; CREATE USER burp_enterprise DEFAULT TABLESPACE burp_enterprise_tabspace QUOTA UNLIMITED ON burp_enterprise_tabspace IDENTIFIED BY ********; GRANT CREATE PROCEDURE, CREATE SEQUENCE, CREATE SESSION, CREATE TABLE, CREATE TRIGGER, CREATE SYNONYM, CREATE PUBLIC SYNONYM, DROP PUBLIC SYNONYM TO burp_enterprise; CREATE USER burp_agent IDENTIFIED BY ********; GRANT CREATE SESSION to burp_agent;
MariaDB / MySQL
CREATE DATABASE burp_enterprise CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci'; CREATE USER 'burp_enterprise'@'%' IDENTIFIED BY '********'; CREATE USER 'burp_agent'@'%' IDENTIFIED BY '********'; GRANT ALL PRIVILEGES ON burp_enterprise.* TO 'burp_enterprise'@'%' WITH GRANT OPTION;
If you run into errors during installation with a MySQL database, please refer to the troubleshooting section below for details on how to resolve a couple of known issues.
Microsoft SQL Server
sp_configure 'contained database authentication', 1; RECONFIGURE; CREATE DATABASE burp_enterprise CONTAINMENT = PARTIAL; USE burp_enterprise; CREATE USER burp_enterprise WITH PASSWORD = '********'; CREATE USER burp_agent WITH PASSWORD = '********'; ALTER ROLE db_owner ADD MEMBER burp_enterprise;
To support password-based logins, you also need to make sure that the Windows Authentication and SQL Server Authentication option is enabled for the installation. This option is sometimes referred to as Mixed Mode Authentication.
Additional configuration for Microsoft SQL Server
Burp Suite Enterprise Edition uses Microsoft's JDBC driver to connect to SQL Server databases. By default, the driver only lets you connect to databases that have a valid TLS certificate signed by a public certificate authority. Therefore, you need to install a suitable certificate on your SQL Server instance before attempting to connect to it from Burp Suite Enterprise Edition. For details on how to do this, please refer to the Microsoft SQL Server documentation.
As a temporary workaround, you can bypass this certificate validation by appending
;trustServerCertificate=true to the JDBC connection URL that you provide when deploying Burp Suite Enterprise Edition. However, we do not recommend this as a long-term solution as this potentially enables malicious third parties to intercept traffic on the connection to your database.
Database connection URL format
To connect Burp Suite Enterprise Edition to your new database, you will need to provide the JDBC URL in various places. The format for this URL differs slightly depending on the database type.
MariaDB / MySQL (except AWS Aurora databases):
MySQL (AWS Aurora databases only):
Microsoft SQL Server:
Note for Microsoft SQL Server users
If you have not installed a suitable TLS certificate on your SQL Server instance, you need to append
;trustServerCertificate=true to the URL to bypass the JDBC driver's certificate validation. We do not recommend this as a long-term solution as it potentially enables malicious third parties to intercept traffic on the connection to your database.
Troubleshooting for MySQL databases
There is a known issue with using self-signed public keys to authenticate with MySQL 8. This section explains how to resolve the issue.
RSA public key is not available client side
When using the default authentication mechanism for MySQL 8, the Burp Suite Enterprise Edition driver validates the public key of the database. If the key is self-signed, you the following exception is displayed:
liquibase.exception.DatabaseException: liquibase.exception.DatabaseException: java.sql.SQLTransientConnectionException: Could not connect to address=(host=127.0.0.1)(port=3306)(type=master) : RSA public key is not available client side (option serverRsaPublicKeyFile not set)
There are several options for resolving this issue:
Use a certificate signed by a well-known certification authority instead.
Distribute the public key of the self-signed certificate manually. Please see the instructions below for details on how to do this.
Disable the security feature that is raising this issue by appending the
allowPublicKeyRetrieval=trueparameter to the database connection URL. You should not do this unless you fully understand the security implications as this could potentially enable man-in-the-middle attacks on the connection.
Distributing the public key manually
Obtain an RSA key pair on your database server by following the steps detailed in the MySQL documentation.
.pemfile containing the public key to the machine on which the Burp Suite Enterprise Edition server is hosted, as well as any external scanning machines that you've deployed. The path to this file must be identical across all of your machines.
serverRsaPublicKeyFileparameter to your database connection URL, pointing it to the location of the key on your machines. For example:
Was this article helpful?
An error occurred, please try again.