Setting up the external database

This process is only relevant if you plan to use an external database rather than the embedded one provided with Burp Suite Enterprise Edition. If this is your first time setting up Burp Suite Enterprise Edition, remember you can always start with the bundled database and migrate to an external database later.

If using an external database, you will need to create a database schema for Burp Suite Enterprise Edition to use. To do this, you can simply connect to your database server and run the setup script below that corresponds to your database type.

The script will create two users, called burp_enterprise and burp_agent respectively. You may occasionally see these referred to as the "admin repository username" and "agent repository username". These will be used by the Enterprise server and your agents in order to connect to your database. You should obviously substitute the placeholder ******** passwords used in the example script with your own strong passwords.


If you're setting up this database as part of the initial Burp Suite Enterprise Edition installation process, you can call these users whatever you want. However, if you're setting up the database in order to migrate from Burp Suite Enterprise Edition's bundled database, you need to use these exact names.

After creating the users, make sure you keep a record of the connection details for your database. You will need to provide these later during the installation or migration process.

Please be aware that if you're setting up an on-premise version of Burp Suite Enterprise Edition, when prompted to provide your JDBC URL in the installation wizard, you do not need to include the jdbc:<subprotocol>:// prefix; this will be derived automatically based on the database type that you selected. During a cloud deployment, however, you will still need to provide the full JDBC URL as specified below.


Setup script: CREATE DATABASE burp_enterprise;
CREATE USER burp_enterprise PASSWORD '********';
CREATE USER burp_agent PASSWORD '********';
GRANT ALL ON DATABASE burp_enterprise TO burp_enterprise;
JDBC URL format: jdbc:postgresql://{Server address}:5432/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.

Note that this requirement applies only to our database transfer tool. If you're just setting up a PostgreSQL database as part of the initial installation of Burp Suite Enterprise Edition, you do not need to do this.

Microsoft SQL Server

Setup script: sp_configure 'contained database authentication', 1;
USE burp_enterprise;
CREATE USER burp_enterprise WITH PASSWORD = '********';
CREATE USER burp_agent WITH PASSWORD = '********';
ALTER ROLE db_owner ADD MEMBER burp_enterprise;
JDBC URL format: jdbc:sqlserver://[serverName]:1433;databaseName=burp_enterprise

To support password-based logins, you need to ensure that the "Windows Authentication and SQL Server Authentication" option is enabled for the installation. This option is sometimes referred to as "Mixed Mode Authentication".


Setup script: CREATE TABLESPACE burp_enterprise_tabspace DATAFILE 'burp_enterprise_tabspace.dat' SIZE 100M
CREATE USER burp_enterprise DEFAULT TABLESPACE burp_enterprise_tabspace QUOTA UNLIMITED ON
  burp_enterprise_tabspace IDENTIFIED BY ********;
CREATE USER burp_agent IDENTIFIED BY ********;
JDBC URL format: jdbc:oracle:thin:@//[serverName]:1521/[instanceId]

MariaDB / MySQL

Setup script: CREATE DATABASE burp_enterprise;
CREATE USER 'burp_enterprise'@'%' IDENTIFIED BY '********';
CREATE USER 'burp_agent'@'%' IDENTIFIED BY '********';
GRANT ALL PRIVILEGES ON burp_enterprise.* TO 'burp_enterprise'@'%' WITH GRANT OPTION;
JDBC URL format: jdbc:mysql://{server address}:3306/burp_enterprise

Note for MySQL users

If binary logging is enabled for your MySQL database, users cannot create stored functions unless they have SUPER privileges. As a result, Burp Suite Enterprise Edition may be unable to create the functions it needs to set up your database. Although you might not have explicitly enabled binary logging, if you're using a cloud service, such as an RDS instance on AWS, it is often enabled by default. In this case, you may encounter the following error when trying to install Burp Suite Enterprise Edition:

liquibase.exception.MigrationFailedException: Migration failed for change set true::in_progress_scan_by_agent_mysql::PortSwigger:
Reason: liquibase.exception.DatabaseException: (conn=21) You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable) [Failed SQL: (1419) CREATE FUNCTION in_progress_scans_for_agent(machine_id VARCHAR(64))

To prevent this error, you just need to set the global system variable log_bin_trust_function_creators = 1. If you're using a cloud service, you may need to consult your service provider's documentation for details on how to do this.

Resolving MySQL8 public key exception

When using the default authentication mechanism for MySQL 8, the Burp Suite Enterprise Edition driver will validate the public key of the database that it is connecting to. You will see this error if the key is self-signed:

liquibase.exception.DatabaseException: liquibase.exception.DatabaseException: java.sql.SQLTransientConnectionException: Could not connect to address=(host= : RSA public key is not available client side (option serverRsaPublicKeyFile not set)

You can resolve the issue behind this error in three ways:

  1. Use a certificate signed by a well-known certification authority.
  2. Disable this security feature by appending &allowPublicKeyRetrieval=true to the JDBC URL. This would allow a man-in-the-middle attack on the connection and should only be done if you understand the consequences of this.
  3. Distribute the public key of the self signed certificate manually.

For option 3, You can obtain an RSA key pair on the MySQL server by following the steps detailed in the MySQL documentation. Once you have the public key, copy it into a file on the machine hosting the Burp Suite Enterprise Edition server, and also any machines hosting external agents. The path of the file on these machines needs to be identical. The JDBC connection string should refer to that file with the serverRsaPublicKeyFile option. For example: