ENTERPRISE

Setting up the external database

  • Last updated: May 17, 2022

  • Read time: 4 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 deploy Burp Suite Enterprise Edition and use an external database from the start. If you're a first-time user, remember that you can always start out with the embedded database and migrate to a different one later.

Preparing the database for Burp Suite Enterprise Edition involves the following high-level steps:

  1. Connect to your database server.

  2. Run the setup script for your database type. This creates a database and two users for Burp Suite Enterprise Edition.

  3. Note the connection URL for your database. You will need this later to connect Burp Suite Enterprise Edition.

Database setup scripts

The setup scripts below create a new database and two users: burp_enterprise and 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.

PostgreSQL

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.

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 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.

Oracle

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.

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.

  • PostgreSQL: jdbc:postgresql://<host>:5432/burp_enterprise

  • Microsoft SQL Server: jdbc:sqlserver://<host>:1433;databaseName=burp_enterprise

  • Oracle: jdbc:oracle:thin:@//<host>:1521/<instance-id>

  • MariaDB / MySQL: jdbc:mysql://<host>:3306/burp_enterprise

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=true parameter 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

  1. Obtain an RSA key pair on your database server by following the steps detailed in the MySQL documentation.

  2. Copy the .pem file 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.

  3. Append the serverRsaPublicKeyFile parameter to your database connection URL, pointing it to the location of the key on your machines. For example:

    jdbc:mysql://mysql.dev.example.com:3306/burpenterprise?serverRsaPublicKeyFile=/home/user/public_key.pem