This is a Terraform configuration to build a Burp Private Collaborator Server on an Amazon Web Services EC2 Instance. It uses Terraform to create the instance and then uses our Ansible Burp Collaborator Server role from Ansible Galaxy to provision the Burp service.
Some basic awareness of the AWS API and perhaps a little Terraform is assumed but if you're playing with Burp Collaborator you are hopefully technical enough to muddle through if not. Ping us questions if you get stuck @4ARMED.
This configuration assumes you have registered your domain on the AWS Route53 Registrar. There's a very good reason why this is simpler, we don't have to mess about with working out NS servers for the hosted zone and waiting for NS updates to propagate. If we keep it all within the AWS family it's quicker and easier. It's almost like they've thought of this. ;-)
If you want to use an existing domain registered with another provider it is perfectly possible and there are instructions at the end on how to tweak this accordingly.
Just in case you've been living in a cave, everything in this README will cost you money on AWS. Even the free tier won't save you as it costs $0.50 per month for a hosted zone.
4ARMED are not in any way liable for your infrastructure costs. You should know by now not to just run things without understanding what you're doing. :-)
To use this you need to perform a couple of additional steps to be ready to run Terraform. The first is you need an AWS account and a valid access ID and secret (create a programmatic-only IAM user). I'm not going to talk through how to do this as it'll double the length of this document. Sorry! Try here http://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html.
Once you have these values they can be plugged in to this to configure the AWS Provider.
This config assumes you will use the AWS CLI credentials store. First install it if you have not already:
pip install aws-cli
Then configure it:
aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: ENTER
If you don't have Ansible installed, you will need to do so. I recommend the devel version, it's very stable. If you choose to go main make sure you have at least version 2.2.
pip install git+git://github.com/ansible/ansible.git@devel
git clone https://github.com/4ARMED/terraform-burp-collaborator.git
cd terraform-burp-collaborator
It is assumed that everything else in this doc will be performed with the current working directory in this folder.
We're going to assume you don't have a keypair already in AWS so we'll generate one now and upload it to AWS. You can skip this step if you already have one, just update terraform.tfvars to use the right key_pair_name and place the public key file in this directory.
Feel free to use a different comment or algorithm and it's best to set a passphrase on the key (obvs).
ssh-keygen -b 2048 -t rsa -C private_burp@aws -f mykeypair
Which will produce output like:
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in mykeypair.
Your public key has been saved in mykeypair.pub.
Make sure your keypair file has the same name as your key_pair_name variable as we will look there to upload it to AWS.
You will need to supply your own copy of the latest Burp Suite Professional jar file. Go buy one at the Portswigger website. When you have it copy the jar into this folder. The Ansible playbook will glob in this directory, if you put more than one in you are at the mercy of glob as to which ends up on your server.
In this example I've used the latest version at the time of writing. Given the rate of release these instructions will be out of date in a couple of weeks.
cp /some/path/to/burpsuite_pro_v1.7.21.jar .
Edit the file terraform.tfvars.
# Use whatever region you prefer
region = "eu-west-2"
# Here we are using a different AWS profile from default, you don't have to but this is how if you need to.
profile = "research"
# Adjust according to your region and AZ preference
availability_zone = "eu-west-2a"
# This is the smallest (read cheapest) instance type available. Works ok with this.
instance_type = "t2.nano"
# Make sure the name of your keypair matches the filename minus the .pub suffix.
key_name = "mykeypair"
# You can call this what you like, it's only used to set the hostname
# on the Linux box
server_name = "burp-collaborator"
# Don't use this one. It's ours.
zone = "4armed.net"
# This is a pretty sensible default but again, change it if you like. The only downside is it's long which may
# cause problems if you only have limited injection space.
burp_zone = "collaborator" # This will result in collaborator.4armed.net
# Restrict this to places you will SSH from. The whole Internet is not all so friendly.
permitted_ssh_cidr_block = "0.0.0.0/0"
Now we're ready to run Terraform. First verify everything is ok by running plan:
terraform plan
Assuming you don't get any horrible errors you're ready to go.
terraform apply
Now sit back and behold the awesomeness of infrastructure as code.
The following operations will be performed:
- Create AWS security group permitting all Burp Collaborator traffic plus SSH to your permitted_ssh_cidr_block CIDR.
- Create EC2 instance using Ubuntu Xenial (16.04) image for your chosen region in your default VPC.
- Create an A record for your chosen hostname in your AWS hosted zone pointing to the IP address of new EC2 instance
- Create an NS record for your chosen hostname pointing to the A record just created.
- Run the 4ARMED.burp-collaborator Ansible playbook on the EC2 instance to install and configure Burp Collaborator.
If you want to use this Terraform config but are using a domain registered somewhere other than AWS (and not transferred in) you can use a slightly different version of this Terraform plan. You will also need to manually update the DNS at your register to point an A record to your new EC2 instance and an NS record for the zone too.
There is a different version of main.tf that does not include the route53 section at main.tf.nonawsdomain. To use this simply take a backup of the main.tf file and then copy this nonawsdomain version over it.
cp main.tf{,.aws}
cp main.tf{.nonawsdomain,}
Now run the plan and apply steps as above. It will output the public IP address that you will need for your dns updates but just in case you miss it somehow you can run anytime:
terraform output public_ip
If everything went ok you should be able to plug the hostname of your new private server into Burp and test it out.
Fire up Burp Suite Professional and go to Project options > Misc > Burp Collaborator Server and check the box for Use a private Collaborator server.
In Server location enter the hostname of your server. Hint, this will be the value of burp_zone prepended to zone from terraform.tfvars. In our example collaborator.4armed.net. You will also need to tick the box for Poll over unencrypted HTTP at the moment as we have used a self-signed certificate.
If you would like to purchase a proper wildcard TLS certificate for use with this server you need to generate a more appropriate CSR (the default values are fairly generic). There is an Ansible playbook included in this folder to help you.
Once you have the CSR you can go and purchase a Wildcard TLS certificate with it and then upload it to your Burp server.
Here are the steps.
- Edit owntls.yml and set the different variables according to what you want in your certificate
- Delete the generated CSR:
rm burp.csr ansible-playbook -i inventory owntls.yml --tags tls- Use the contents of the newly generated burp.csr file to purchase your certificate.
- Copy your new certificate to burp.crt
- Copy any intermediate CA cert bundle to intermediate.crt
ansible-playbook -i inventory playbook.yml --tags setup,restart
When you've had your fun, if you want to kill the whole thing just run:
terraform destroy