Creating a private Burp collaborator in Amazon AWS with a LetsEncrypt wildcard certificate
Eric KobelskiBurp’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
-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 will 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.
- Once your certificates have been renewed, re-create the NS record to allow the collaborator to be authoritative when it comes to DNS.