ENTERPRISE

Deploying Burp Suite Enterprise Edition on Azure

  • Last updated: October 6, 2021

  • Read time: 13 Minutes

You deploy Burp Suite Enterprise Edition on Azure using the provided Azure Resource Manager template. You can download the template from the release notes for the version of Burp Suite Enterprise Edition that you want to deploy.

Azure Resource Manager template

The provided Azure Resource Manager (ARM) template creates almost all of the required infrastructure for running Burp Suite Enterprise Edition on Azure. This includes:

  • An Azure Virtual Network (VNet)
  • An application gateway
  • A private subnet within the VNet for the application gateway
  • An Azure Kubernetes Service (AKS) cluster
  • A private subnet within the VNet for the AKS cluster nodes
  • An Azure Files instance

Note

In addition to the infrastructure outlined above, you will need to set up and connect to a database manually as part of the deployment process.

The following diagram shows an example of a Burp Suite Enterprise Edition deployment on Azure:

Example Burp Suite Enterprise Edition deployment on Azure

Nested templates for Azure Resource Manager

The Azure Resource Manager (ARM) template actually comprises two nested templates:

  • infrastructure-<release-number>.json
  • application-<release-number>.json

You can access either of these templates separately by replacing the file name at the end of the main template URL accordingly. This gives you the option to use only part of the template if you prefer.

For example, you may already have the required infrastructure or would prefer to set it up manually and, as a result, just want to use the template for the final deployment steps. In this case, instead of entering the top-level URL for the template, you would just enter the URL for the nested application-<release-number>.json template instead. This should look something like:
https://bsee-cloud-trial.s3-eu-west-1.amazonaws.com/2021.3-1234/application-2021.3-1234.json

How to deploy Burp Suite Enterprise Edition on Azure

The process for deploying Burp Suite Enterprise Edition on Azure involves the following steps:

  1. Set up a database
  2. Create the main stack
  3. Set up the appropriate routing

Prerequisite permissions

Please note that in order to perform the entire process, you will need an Azure user with the appropriate permissions to perform the following high-level actions:

  • Create new resource groups
  • Create a database server within the new resource group
  • Change IP address access controls for the database server so that you can connect to it from your workstation or another endpoint
  • Execute command line utilities to configure the database server, create a new database, and create new users
  • Execute the az deployment command in order to deploy to the new environment. This requires a user with the Cloud Application Administrator role.

Set up a database

Unlike for on-premise installations, there is no bundled database option when running Burp Suite Enterprise Edition on the cloud. Therefore, you need to set up and connect to your own database as described below.

This involves the following steps:

  1. Creating a resource group for your database

  2. Creating the database server

  3. Configuring the database connection settings

  4. Creating the database and users

You can use any of our supported database types. We recommend using one of Azure's dedicated services for your preferred database.

Note

Throughout these instructions, we'll use a PostgreSQL database for all examples.

Create a resource group for your database

The first step of the process is to create a new resource group for the database to logically separate it from the rest of your infrastructure.

  1. Log in to Azure Portal and select "Resource Groups".
  2. From the list of resource groups, click "New".
  3. On the "Basics" tab, select your Azure subscription and enter a name for the resource group, for example, burp-enterprise-db-group.
  4. From the "Region" drop-down menu, select an appropriate Azure location. This determines where metadata about your resource group is stored.
  5. On the "Tags" tab, you can optionally add tags according to your organization's policy.
  6. On the "Review + create" tab, review the details that you've entered and click "Create".
  7. After a few minutes, your new group will be created and should appear in the list of resource groups.

Create the database server

  1. In Azure Portal, search for your preferred database service, for example, "Azure Database for PostgreSQL servers" and select it from the list.
  2. Click "New".
  3. When prompted, select the "Single Server" deployment option.
  4. On the "Basics" tab, select your Azure subscription and the resource group that you created earlier.
  5. Under "Server details", enter a name that you want to assign to the database server, for example, burp-enterprise-db.
  6. Select the data source "None".
  7. Select a suitable Azure location for the database server.
  8. Select a version of your database that is compatible with Burp Suite Enterprise Edition. For details on supported versions, please refer to the system requirements.
  9. If you want to adjust the technical specs of the server, under "Compute + storage" select "Configure server". However, note that you must still use the "General Purpose" pricing tier - do not switch to "Basic". Please refer to the system requirements for details on sizing.
  10. Under "Administrator account", enter the credentials that you want to set for the database admin user. These can be any credentials you like. For our examples, we've used the username postgres. Make a note of these credentials; you will need them shortly to finish setting up the database.
  11. Adjust any further configuration settings according to your own preferences and requirements. For example, on the "Tags" tab, you can optionally add tags according to your organization's policy.
  12. Review the details you have entered and click "Create".

After a few minutes, your database server will be available from the list of resources in your resource group.

Configure the database connection settings

By default, your newly created database server will not be accessible from other Azure services. You need to adjust the connection settings to finish the database setup and deploy Burp Suite Enterprise Edition.

You can do this from the Azure Portal as follows:

  1. From the list of resources, go to the database server that you created earlier.
  2. From the left-hand navigation panel, select "Connection security".
  3. Temporarily enable the "Allow access to Azure services" option. Please be aware that this will allow any resources in Azure to potentially connect to your database. You should disable this setting once you have finished the deployment.
  4. Click "Save".

Create the database and users

Once you've created a suitable database server in Azure and configured the connection settings, you can connect to the database server and create the actual database.

  1. In the Azure Portal, go to the "Overview" page for your database server.
  2. Under "Essentials", copy the "Server name" and "Admin username" values.
  3. Open Azure Cloud Shell.
  4. Enter the connection string in the format required for your database type, substituting the server name and admin username that you just copied into the corresponding parameters. You can find an overview of connection string formats in Azure Portal from the "Connection strings" settings page. For our PostgreSQL example, the result should look something like this:
    psql --host=burp-enterprise-db.postgres.database.azure.com --username=postgres@burp-enterprise-db --dbname=postgres
  5. When prompted, enter the admin password that you set when creating the database server earlier. You should now be connected to the database server.
  6. Enter the corresponding commands for your database type as described in our database setup documentation.

This will create a database called burp_enterprise as well as two users, called burp_enterprise and burp_agent respectively. These are used by the Enterprise server and agents to connect to the database. Make a note of the passwords you set because you will need to provide these in the ARM template later.

Deploy the main stack to Azure

You deploy the main Burp Suite Enterprise Edition stack to Azure using an Azure Resource Manager (ARM) template. This contains a list of parameters, some of which have a default value. During the deployment, you will be prompted to enter values for each parameter that does not have a default assigned.

Get the Azure Resource Manager template URL

  1. Go to the release notes for the version of Burp Suite Enterprise Edition that you want to deploy.
  2. Copy the URL for the Azure Resource Manager template. Alternatively, if you only want to use part of the template, copy the URL and replace the file name with the name of the corresponding nested templates.

Note

These instructions generally assume that you're using the full template. If you're only using one of the nested templates, some of these steps will not apply.

Overriding the default values (optional)

You can override the default values for any of the parameters by creating a separate parameters.json file to use during the deployment. You can also enter values for any remaining parameters here to avoid having to enter them via the command line later.

For example, you may want to set a different applicationGatewayPrivateIPAddress, which is the IP address you will use to access the application once it is deployed. Please note that any address you choose must still belong to the address space defined in the addressSpaces parameter, so you may also need to update this as well.

You can refer to the list of parameters in the template to see the default values and their description.

Create the service principal

After getting the template URL, the next step in the deployment process is to create a service principal, which will be used to manage some of the AKS-related resources. You will then write this service principal object to a credentials.json file that you can pass into the ARM template during the deployment.

  1. In Azure Portal, open Azure Cloud Shell.
  2. Enter the following command. This will create a service principal and write the output to a file called auth.json, which you will use in the next step.
    az ad sp create-for-rbac --skip-assignment -o json > auth.json
  3. Enter the following commands to assign the newly generated values from the auth.json file to the corresponding variables.
    appId=$(jq -r ".appId" auth.json)
    password=$(jq -r ".password" auth.json)
    name=$(jq -r ".name" auth.json)
    objectId=$(az ad sp show --id $appId --query "objectId" -o tsv)
    tenant=$(jq -r ".tenant" auth.json)
  4. Enter the following command to create a credentials.json file using the variables you just assigned. You will use this later when running the Azure Resource Manager template.
    cat <<EOF > credentials.json
    {
      "servicePrincipalAppId": {"value": "$appId"},
      "servicePrincipalClientSecret": {"value": "$password"},
      "servicePrincipalName": {"value": "$name"},
      "servicePrincipalObjectId": {"value": "$objectId"},
      "servicePrincipalTenant": {"value": "$tenant"}
    }
    EOF

You are now ready to run the Azure Resource Manager (ARM) template to create and deploy the application and related infrastructure.

Create a new resource group

In Azure Cloud Shell, enter the following command to create a new resource group for the deployment.

az group create -n your-new-group-name -l your-region

The name (-n) of the group can be anything you like. The location (-l) must be the name of a region to which you have access, for example, eastus. You can use the following command to output a list of available regions:

az account list-locations

Start the deployment

Enter the following command to start the final deployment.

az deployment group create -g your-resource-group-name -n any-new-deployment-name --template-uri your-copied-template-url --parameters @credentials.json

  • -g is the name of the group that you just created in the previous step.

  • -n is the name that you want to assign to the deployment you're creating. This can be anything you like.

  • --template-uri is the URL of the Azure Resource Manager template that you copied from the release notes. Alternatively, you can enter the URL of one of the nested templates.

  • The credentials.json file is the one that you generated earlier when creating the service principal. If you encounter an InvalidPrincipalId error, you need to repeat those steps again to generate a new file.

Note

If you've created a separate parameters.json file to override the default values, you should also pass this in here by appending the command with --parameters @parameters.json.

Enter the remaining details for your deployment

Unless you set values for every parameter in a separate JSON file, you now have to provide the remaining details needed for the deployment. When prompted, enter values for each of the following parameters:

  • adminEmail

    The email address that you want to set for the initial admin user.

  • adminUsername

    The username you want to set for the initial admin user.

  • adminPassword

    The password you want to set for the initial admin user.

  • adminRepositoryURL

    The JDBC URL for your database. For example, jdbc:postgresql://burp-enterprise-db.postgres.database.azure.com:5432/burp_enterprise. The format of this URL differs depending on your database type. Please refer to our database setup instructions for some examples.

  • adminRepositoryUsername

    The database username that you created for the Enterprise server when setting up the database. If you copied our setup scripts, this should be burp_enterprise.

  • adminRepositoryConnectionUsername

    The connection username in the correct format for Azure. This is the same username that you just entered, followed by the hostname for your database. For example: burp_enterprise@burp-enterprise-db

  • adminRepositoryPassword

    The password that you assigned to the burp_enterprise user when setting up your database.

  • agentRepositoryURL

    The same JDBC URL that you entered as the adminRepositoryURL earlier. For example, jdbc:postgresql://burp-enterprise-db.postgres.database.azure.com:5432/burp_enterprise

  • agentRepositoryUsername

    The database username that you created for agents when setting up the database. If you copied our setup scripts, this should be burp_enterprise.

  • agentRepositoryConnectionUsername

    The connection username of the burp_agent user in the correct format for Azure. This is the same username that you just entered, followed by the hostname for your database. For example: burp_agent@burp-enterprise-db

  • agentRepositoryPassword

    The password that you assigned to the burp_agent user when setting up your database.

Once you've set all the parameters, Azure will begin the deployment.

Wait for the deployment to finish

While the deployment is running, you can monitor its progress in Azure Portal. Select your resource group and go to the "Overview" page. In the "Essentials" section, click the link under "Deployments" to see a list of resources that are being deployed and monitor their status.

Once all of these resources have been successfully deployed, Azure will begin deploying the bsee-application. You can see this on the resource group "Overview" page. When this also has the status Succeeded, Burp Suite Enterprise Edition is up and running.

If the deployment of bsee-application fails, please refer to the troubleshooting section below.

Configure connection security settings

Now that the deployment is complete, you need to set a VNet rule to allow the nodes subnet to access the Burp Suite Enterprise Edition VNet.

  1. In Azure Portal, select "Connection security" from the left-hand navigation menu.

  2. Under "VNet rules", select "Adding an existing virtual network".

  3. Create a new VNet rule using the virtual network bseeVNet and the subnet nodesSubnet.

  4. Back on the main "Connection security" page, deselect the option "Allow access to Azure services".

Set up routing and access the application

Now that the application is deployed, you can access the Burp Suite Enterprise Edition login page in your browser by visiting the applicationGatewayPrivateIPAddress that you set during the deployment. Unless you explicitly changed this using a parameters.json file, this will be 10.0.0.10 by default.

Note that the application is not available from the public internet and can only be accessed via your Azure Virtual Network (VNet). Therefore, you need to set up the appropriate routing from your client browser into the VNet, for example, using a VPN.

Alternatively, you can add a virtual machine and an Azure Bastion service to your VNet. You can then use the Bastion service to connect to your virtual machine, which can subsequently access Burp Suite Enterprise Edition. This is a good approach for making sure that the application is up and running before trying to configure more complex routing.

You can then log in using the admin username and password that you set during the deployment process. You will be prompted to activate your license and complete a short onboarding wizard. The remainder of this process is the same as for an on-premise installation.

Troubleshooting

If you encounter issues during the deployment process, you may be able to diagnose the problem yourself by following the instructions below. Otherwise, please contact our support team.

The deployment is complete but bsee-application is in a "failed" state

If the deployment appears to have been completed successfully, but the bsee-application is in a "failed" state, this may be because there were issues connecting to your database during the deployment.

Check the database connection

You can check whether the connection was successful by examining the burp_enterprise database to see if the expected tables have been created. The options you have for doing this depend on your database type. For a PostgreSQL database, you can use the psql command-line tool as follows:

  1. In Azure Portal, go to your database and open the "Connection security" page.
  2. Temporarily enable the "Allow access to Azure services" option.
  3. Open Azure Cloud Shell and connect to your database server using the same connection string you used when setting up the database. This should look something like this:
    psql --host=burp-enterprise-db.postgres.database.azure.com --username=postgres@burp-enterprise-db --dbname=postgres
  4. Enter the following command to connect to your burp_enterprise database:
    postgres=> \c burp_enterprise
  5. Enter the following command to output a list of tables in the database:
    postgres=> \dt
  6. If this command returns an empty list, the relevant tables were not created as expected. This is a strong indication that there were issues with the connection string or database credentials that you entered during the deployment.

If the command returns a list of Burp Suite Enterprise Edition tables, the issue is unlikely to be related to your database connection and you should investigate other potential causes.

Note

When you're finished checking the database, we strongly recommend that you go back to the "Connection security" page and disable the "Allow Access to Azure services" option.

Checking the logs from your Kubernetes cluster

You can also check the logs of your Kubernetes cluster for clues as to why you are facing issues.

  1. In Azure Portal, open your resource group and select the Kubernetes cluster. The name should begin with bseeCluster followed by a unique identifier.
  2. From the cluster overview page, click "Connect". You will then be given instructions on how to configure command-line tools to interact with your cluster using the kubectl tool.
  3. Enter the two commands as instructed in Azure Cloud Shell. This will update your kubeconfig file with the required details and connect you to your cluster.
  4. Enter the following command to examine the logs from the bsee-application resource, remembering to enter your own resource group name:
    az container logs --resource-group your-resource-group-name --name bsee-application
  5. You can also enter the following command to check whether any Kubernetes "pods" are in an error state and investigate them further:
    kubectl get pods --all-namespaces | grep Error

How do I remove Burp Suite Enterprise Edition from Azure?

To remove Burp Suite Enterprise Edition from Azure completely, you can usually just delete the entire resource group. If you encounter errors, you can try deleting individual items first and then deleting the resource group itself.