Creating a private Burp collaborator in Amazon AWS with a LetsEncrypt wildcard certificate

Burp’s collaborator is a useful tool to assist with web application (i.e., webapp) penetration and security testing, particularly when malicious payloads are injected and then executed by a vulnerable system. When the collaborator is in use, Burp crafts messages that are sent to the application containing links that will be caught by the collaborator server and reported back to your instance of Burp.

By default, Burp is configured to use the default collaborator server, which is hosted by PortSwigger. Because there may be some controversy with where vulnerable data is being stored, Burp provides the ability to have a custom, private collaborator server. A private collaborator server creates isolation between PortSwigger and the system under test, therefore allowing a more secure web application security testing environment.

The document below walks you through how to build and configure your own server using Amazon AWS and LetsEncrypt.

Variables and Explanation

Throughout this article, the following variables will be used. These have been selected to all work together. If you’re following along, you just need to change the entries in the “Example Value” field and the remainder of the guide should work for you.

Variable	Example Value	Notes
[EXTERNAL_IP]	99.88.77.66	This is the external IP that Amazon AWS has provided you for your server.
[INTERNAL_IP]	192.168.1.1	This is the internal IP that Amazon AWS has provided you for your server.
[SUBDOMAIN]	xyz.example.com	This is the URL that your collaborator will be listening on. Burp will create random subdomain values and append this. So, if you use xyz.example.com as your domain, Burp will create a request using the following subdomain randomsubdomain.xyz.example.com
[WILDCARD_SUBDOMAIN]	*.xyz.example.com	This is going to be needed for the wildcard certificate process
[COLLAB_PATH]	/opt/collaborator/	The location of Burp’s JAR file on your server
[BURP_JAR]	burpsuite_pro_v2020.8.1.jar	The JAR file of Burp Suite Pro
[COLLAB_CONFIG_FILE]	collaborator.config	The configuration file for Burp, which should be located with the JAR file contained in the [COLLAB_PATH] folder.
[METRICS_PATH]	SomeRandomPath	A random path added onto the URL for metrics purposes on the collector.
[METRICS_WHITELIST]	192.168.5.0/24	A whitelist of IP’s that can access the metrics path. This could be internal or external IP’s.
[DNS_SERVER]	ns1.xyz.example.com	The value of the authoritative DNS server for the collaborator. This is something that you will build below in the DNS Setup section.

DNS Setup

The collaborator server should be authoritative as its own DNS server. At your DNS provider, you’ll need to create the following entries:

Name	Record Type	Value	Notes
ns1.[SUBDOMAIN]	A	[EXTERNAL_IP]	This maps the external IP of the AWS server to what will be the name server for the private collaborator server.
[SUBDOMAIN]	NS	ns1.[SUBDOMAIN]	This allows the collaborator server to be authoritative for DNS requests.

Create a small (t3.micro) Ubuntu server in Amazon AWS.
Bind an Elastic IP to this server. This will be the value of [EXTERNAL_IP].
Create and associate a security group that allows the following inbound communication:

TCP/22 – This only for administration, so it should not be exposed to the entire internet.
TCP/80 – This needs to be allowed from ANY network.
TCP/443 – This needs to be allowed from ANY network.
TCP/25 – This needs to be allowed from ANY network.
TCP/587 – This needs to be allowed from ANY network.
TCP/465 – This needs to be allowed from ANY network.
TCP/9090 – This needs to be allowed from ANY network.
TCP/9443 – This needs to be allowed from ANY network.
TCP/53 – This needs to be allowed from ANY network.
UDP/53 – This needs to be allowed from ANY network.

Once the server is up, make sure all the packages are up-to-date.
sudo apt-get update
sudo apt-get -y upgrade

Create the directory where the collaborator will run from.
sudo mkdir -p [COLLAB_PATH]

Install the LetsEncypt Certbot.
cd [COLLAB_PATH]
wget https://dl.eff.org/certbot-auto
chmod a+x ./certbot-auto

Generate a wildcard certificate for your subdomain using the command below:
cd [COLLAB_PATH]
sudo ./certbot-auto certonly

-d [SUBDOMAIN] -d [WILDCARD_SUBDOMAIN]

--server https://acme-v02.api.letsencrypt.org/directory

--manual --agree-tos --no-eff-email

--manual-public-ip-logging-ok --preferred-challenges dns-01

Important:

You’ll also need to have access to your DNS provider during this step. As part of the certificate creation process, LetsEncrypt will have you create multiple TXT record for verification purposes.
Wait around five minutes after each TXT record is created before performing the verification by Certbot to allow for DNS propagation.

At this point, you should now have an Ubuntu server up and running that is accessible on the ports listed. It should be secured by a LetsEncrypt wildcard certificate, so any value beneath the wildcard subdomain should be both routable and secured by the certificate.

Installing & Configuring the Burp Collaborator

Installing Burp’s Collaborator

The first step is to download the latest version from PortSwigger. Please note this functionality only resides in the professional version (i.e., not in the community version), so a valid license is required. From PortSwigger, obtain the latest JAR file, and upload it to [COLLAB_PATH] on your server. Next, create the config file [COLLAB_CONFIG_FILE] alongside the JAR file.

Burp Collaborator Configuration File

Your configuration file should look as follows:

{

"serverDomain" : "[SUBDOMAIN]",

"workerThreads" : 10,

"eventCapture": {

"localAddress" : "[INTERNAL_IP]",

"publicAddress" : "[EXTERNAL_IP]",

"http": {

"ports" : 80

},

"https": {

"ports" : 443

},

"smtp": {

"ports" : [25, 587]

},

"smtps": {

"ports" : 465

},

"ssl": {

"certificateFiles" : [

"/etc/letsencrypt/live/[SUBDOMAIN]/privkey.pem",

"/etc/letsencrypt/live/[SUBDOMAIN]/cert.pem",

"/etc/letsencrypt/live/[SUBDOMAIN]/fullchain.pem"

]

}

},

"polling" : {

"localAddress" : "[INTERNAL_IP]",

"publicAddress" : "[EXTERNAL_IP]",

"http": {

"port" : 9090

},

"https": {

"port" : 9443

},

"ssl": {

"certificateFiles" : [

"/etc/letsencrypt/live/[SUBDOMAIN]/privkey.pem",

"/etc/letsencrypt/live/[SUBDOMAIN]/cert.pem",

"/etc/letsencrypt/live/[SUBDOMAIN]/fullchain.pem"

]

}

},

"metrics": {

"path" : "[METRICS_PATH]",

"addressWhitelist" : ["[METRICS_WHITELIST]"]

},

"dns": {

"interfaces" : [{

"name":"[DNS_SERVER]",

"localAddress":"[INTERNAL_IP]",

"publicAddress":"[EXTERNAL_IP]"

}],

"ports" : 53

},

"logLevel" : "INFO"

}

Starting the Collaborator

Now that you have the server configured, the collaborator components ready and certificates generated, you can start the server using one of the following methods. Below are the steps to start the server manually via a script or running the collaborator as a service. The benefit to running the collaborator as a service is that it will automatically restart if the server is rebooted.

Starting via Script

Change to the home directory of the default user.
cd ~

Create a script that will be manually run when the collaborator is needed.
vi start-burp-collaborator.sh

Enter the following content for the script:
#!/bin/bash
set -e

cd [COLLAB_PATH]
sudo java -jar [BURP_JAR]

--collaborator-server

--collaborator-config=[COLLAB_CONFIG_FILE]

Assign the correct permissions to the script, once saved.
chmod +x start-burp-collaborator.sh

Starting via Service

This is the more useful way to start the collaborator server. If the server reboots, or the process hangs, it will automatically restart.

Create the service definition file.
sudo vi /etc/systemd/system/collaborator.service

Enter the following content into the service declaration and save the file

[Unit]

Description=Burp Collaborator Server

After=network.target

[Service]

Type=simple

Restart=always

RestartSec=1

TimeoutStopSec=180

User=root

ExecStart=/usr/bin/java -Xms10m -Xmx200m -XX:GCTimeRatio=19

-jar [COLLAB_PATH]/[BURP_JAR] --collaborator-server

--collaborator-config=[COLLAB_PATH]/[COLLAB_CONFIG_FILE]

[Install]

WantedBy=multi-user.target

Enable the service.
sudo systemctl enable collaborator

Start the service.
sudo start collaborator

At this point in time, you now have a server that is properly provisioned, and Burp’s collaborator is running. The next step is to configure your Burp to use this instance, rather than the default one.

Configuring Burp to Use a Private Collaborator

To use your private Burp collaborator server and not the default one from PortSwigger, follow the steps below:

Start Burp, load a project, and navigate to the Project Options tab across the top.
Select the Misc. sub tab and look for the Burp Collaborator Server configuration section.
By default, Burp will be set to “Use the default Collaborator server”.
Select “Use a private Collaborator server” and enter the following information:

Server location: [SUBDOMAIN]
Polling location (optional): [SUBDOMAIN]:9443

Once that information has been populated and your private collaborator server has been started, you should be able to click the “Run health check…” button. In the window that pops up, you should get green text indicating success.

Renewing Your LetsEncrypt Certificates

When LetsEncrypt generates a certificate, it’s valid for 90 days. LetsEncrypt recommends that certificates be renewed every 60 days. Because a DNS challenge is required to renew certificates, the following steps need to be performed in order to successfully renew your certificates:

At your DNS provider, temporarily remove the NS record that was created above in the DNS Setup section. This will allow LetsEncrypt to interact with Certbot and not the collaborator.
Re-run the following command to renew the certificates:

cd [COLLAB_PATH]

sudo ./certbot-auto certonly