NuHarbor Security Penetration Testing | Burp SuiteBy: Eric Kobelski, Security Engineer
Updated on: 06/28/2018

Burp’s Collaborator is a useful tool to assist with web application (webapp) penetration and security testing; particularly when malicious payloads are injected and then exercised 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. 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 configure your own server using Amazon AWS and LetsEncrypt.

Variables & Explanation

Throughout this article, the following variables will be used. These have been selected to all work together. If you are following along, you should 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
[HOSTNAME] xyz This is the name of your server
[EXTERNAL_IP] This is the external IP that Amazon AWS has provided you for your server.
[INTERNAL_IP] This is the internal IP that Amazon AWS has provided you for your server.
[SUBDOMAIN] This is the URL that your collaborator will be listening on. Burp will create random subdomain values and append this.


So, if you use as your domain, Burp will create a request using the following subdomain

[WILDCARD_SUBDOMAIN] * This is going to be needed for the wildcard certificate process
[BURP_JAR_PATH] ~/burp/ The location of Burp’s JAR file on your server
[BURP_JAR_FILE] burpsuite_pro_v1.7.35.jar The JAR file of Burp Suite Pro
[BURP_CONFIG_FILE] burp.config The configuration file for Burp, which should be located with the JAR file in the [BURP_PATH] folder.
[METRICS_PATH] SomeRandomPath A random path added onto the URL for metrics purposes on the collector.
[METRICS_WHITELIST] A whitelist of IP’s that can access the metrics path. This could be internal or external IP’s.
[BURP_LAUNCHER] /opt/BurpSuitePro/BurpSuitePro This is the shell script that launches Burp Suite Pro

DNS Setup

At your DNS provider, you will need to create the following entries:

  • An A-Record mapping the subdomain [SUBDOMAIN] to the external IP [EXTERNAL_IP]
  • A wildcard A-record mapping anything under the subdomain to the external IP

Server Setup

  • Create a small (t2.micro) Ubuntu 16.04 server in Amazon AWS.
    • Bind a static Elastic IP to this server
    • Create a security group and associate it with the server that allows the following inbound communication
      • TCP/22 – This is only needed for administration, so you will want to have this associated with the network you are testing from
      • 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
    • Once the server is up and running make sure all the packages are up to date via the following commands:
        sudo apt-get update
        sudo apt-get -y upgrade
        sudo apt-get -y dist-upgrade
    • Set the host name of the server to [HOSTNAME].
    • Reboot the server to apply the hostname change.
    • Install the LetsEncypt Certbot
        sudo apt-get -y install letsencrypt
    • Generate a wildcard certificate for your subdomain
        sudo letsencrypt certonly –manual -d [WILDCARD_SUBDOMAIN] –server
      • Important – to generate a wildcard certificate, you must specify the server to use. As of this article, the default API server LetsEncrypt uses does not support wildcard certificates.
      • 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 a TXT record for verification purposes.

At this point in time 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 (and not in the community version), so a valid license is required. From PortSwigger, download the latest JAR file.  Once downloaded, copy that file to [BURP_JAR_PATH] on your server. Next, create the config file [BURP_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" : [
  "polling" : {
    "localAddress" : "[INTERNAL_IP]",
    "publicAddress" : "[EXTERNAL_IP]",
    "http": {
      "port" : 9090
    "https": {
      "port" : 9443
    "ssl": {
      "certificateFiles" : [
  "metrics": {
    "path" : "[METRICS_PATH]",
    "addressWhitelist" : ["[METRICS_WHITELIST]"]
  "dns": {
    "interfaces" : [{
    "ports" : 53
  "logLevel" : "INFO"

LetsEncrypt and JVM

As of the publishing date of this article, the current versions of Java JVM do not trust the wildcard certificates generated by LetsEncrypt. The following steps need to be taken to import the latest root certificates from LetsEncrypt:
set -e
# This path works for Ubuntu 16.04 - start with "whereis java" and follow the simlinks to find the CAcerts folder
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias isrgrootx1 -file letsencryptauthorityx1.der
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias isrgrootx2 -file letsencryptauthorityx2.der
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias letsencryptauthorityx1 -file lets-encrypt-x1-cross-signed.der
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias letsencryptauthorityx2 -file lets-encrypt-x2-cross-signed.der
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias letsencryptauthorityx3 -file lets-encrypt-x3-cross-signed.der
keytool -trustcacerts -keystore $KEYSTORE -storepass changeit -noprompt -importcert -alias letsencryptauthorityx4 -file lets-encrypt-x4-cross-signed.der
rm -f letsencryptauthorityx1.der letsencryptauthorityx2.der lets-encrypt-x1-cross-signed.der lets-encrypt-x2-cross-signed.der lets-encrypt-x3-cross-signed.der lets-encrypt-x4-cross-signed.der

Starting the Collaborator

Now that you have the certificates generated and trusted, you can start the server using the following commands or wrap them together as scripted below:
set -e
sudo java -jar [BURP_JAR_FILE] --collaborator-server --collaborator-config=[BURP_CONFIG_FILE]

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

Configuring Web Application Penetration Testing Machine

To use your private Burp Collaborator server and not the default one from PortSwigger. There are a few more modifications that you need to make on your testing box.

Burp is Java-based, so you will need to follow the steps under “LetsEncrypt and JVM” above.

Override Burp’s default launcher

You should be able to locate this file in [BURP_LAUNCHER]. As root, edit this file. Near the top of the file, you are going to want to change:

# Uncomment the following line to add additional VM parameters


# Uncomment the following line to add additional VM parameters

This will tell the virtual machine to use the Java KeyStore which contains the LetsEncrypt certificates we inserted at an earlier date.

Configuring Burp to use the custom Collaborator

Start Burp and navigate to the Project Options tab across the top. Once there, 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” which is hosted by PortSwigger. You are going to want to select “Use a private Collaborator server” and enter the following information:

  • Server location: [SUBDOMAIN]
  • Polling location (optional): polling.[SUBDOMAIN]:9443

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

Pin It on Pinterest

Share This