When working on a project I want to keep all project data in one directory. I keep notes and logs to make reporting easier, and to be able to answer customer questions. Although it’s rare, sometimes it is necessary to go back through the logs to see what happened during the test. In that case the logs need to be complete, and contain only information from that project. To make this easier, I have partly automated a workflow I will explain below.

Project separation

The goal of my workflow is to easily store project data in the project folder, and to prevent contamination with other projects or non-project related work. When I am hacking Acme’s API I want all requests to go through Burp, keep screenshots, notes, and browser history. When I switch to Wayne’s web app, I don’t want to have requests to Wayne end up in Acme’s Burp project, and vice versa. Projects need to be strictly separated, while making it easy to store information.

Using a virtual machine

I used to have a virtual machine running Kali Linux for hacking. By using a VM it is possible to make snapshots and revert to a clean state, making sure projects don’t contaminate each other. However, virtual machines have some drawbacks:

  • Copy-pasting between the VM and the host often breaks.
  • The snapshots take up considerable disk space.
  • The VM is not integrated in the windowing system of the host. Getting the VM to work right on multiple screens is a challenge.

Using a VM is particularly useful since it segments all your files. If you add a static mapping to /etc/hosts, it is gone as soon as you revert to a clean snapshot.

In practice, it sometimes still happens that project files end up in the “clean” VM snapshot. As with all systems like this, you have to remember to switch contexts.

Especially the problems with multiple screens led me to try another solution. At first I had one VM with a browser connected to another VM with Burp. However, this made little sense, especially when Burp started supporting projects in 2016.

Running native

I switched to running the browser, Burp, and some other tools directly on MacOS and discarded the virtual machines.

Burp projects work great at separating data from different projects. For the browser I used to clear all data (⌘⇧⌦) every time I switched projects, but later I created a new Firefox profile for each project.

Initializing a project

I created a shell script that initializes a new project. It creates a new directory with the given name, a new Firefox profile and a new Burp project. It creates these subdirectories in the project directory:

  • burp stores the Burp project and log.
  • code has any available source code.
  • screenshots has all screenshots for this project.
  • project has the project information such as the proposal.
  • bin has some project specific scripts, particularly to start the browser and Burp with the correct arguments.

And finally, it creates a file notes.txt to contain all notes made during the project.

Each project has its own directory. There is a symlink named current that points to the directory of the current project. This is automatically set by the project initialization script described above, and I can set it to any project when I change projects. This makes it easy to find the files for the current project, and I can configure tools to save files to this directory.

Saving screenshots

One use of the current symlink is to save screenshots. Screenshots are saved to the screenshots directory in the current project. So now I can take screenshots with ⌘⇧4 and they automatically end up in the correct directory of the current project. The following command changes the directory screenshots are saved to:

defaults write com.apple.screencapture location /Users/me/Projects/current/screenshots

Firefox profile

The project initialization script creates a new Firefox profile specifically for the project. This facilitates project specific browser history, saved passwords, and saved form inputs.

After creating the project, the script copies a custom user.js into the profile folder. This configuration file makes Firefox use Burp as proxy and sets some other preferences.

Burp configuration

Each project has its own script to start Burp, which specifies the project and configuration files to use. The configuration file in turn enables logging to /burp/$project.log. The file bin/burp that starts Burp for the current project looks like this:

~/bin/burp --project-file='$PWD/burp/$project.burp' --config-file='$PWD/burp/$project.conf.json' --unpause-spider-and-scanner

Possible improvements

Currently, it is possible to start the browser of one project while running the Burp instance of another project. Requests then end up in the wrong Burp project. To avoid this, each project could use its own port number for the proxy. Firefox connects to Burp on this project specific port, making it impossible to connect Firefox to the wrong Burp project.

Another possible improvement would be to make it clearly visible to which project a Firefox instance belongs. It would be nice if the project name was visible in the title bar, but I have not yet found a way to do so.


Using several bash scripts I create a new Firefox profile and Burp project for each project. This keeps project information separate and complete.