distrinet / bughog

Powerful framework for pinpointing bug lifecycles in web browsers.

BugHog

BugHog is a powerful framework designed specifically to address the challenging task of pinpointing the exact revisions in which a particular browser bug was introduced or fixed.

This framework has been developed as part of the "A Bug's Life: Analyzing the Lifecycle and Mitigation Process of Content Security Policy Bugs" paper to identify Content Security Policy bug lifecycles, published at USENIX Security '23.

Installation

BugHog is compatible with UNIX systems running Docker, including WSL on Windows. Follow these steps to get started:

1. Clone this repository:

   git clone https://github.com/DistriNet/BugHog
   cd BugHog

2. Obtain images:

   You will need at least 5 GB of disk space. There are two options available to obtain the BugHog images, and you can switch between them by executing the appropriate command.

   Option A: Pulling (fastest)

   Use the following command to pull the necessary Docker images:

   docker compose pull core worker web

   💡 If you prefer to use a version other than the latest, simply modify the BUGHOG_VERSION and / or BUGHOG_WEB_VERSION variables accordingly.

   Option B: Building

   Use the following commands to build the Docker images yourself, for instance after you made changes to the source code:

   docker compose build core worker web

   💡 For reference, building takes about 4 minutes on a machine with 8 CPU cores and 8 GB of RAM.

Usage

Launch BugHog using the following command:

docker compose up -d

⚠️ If you use sudo with this command, the PWD environment variable won't be passed to the BugHog containers, which is necessary for dynamically starting worker containers. To avoid this, explicitly pass on this variable: sudo PWD=$PWD docker compose up.

Open your web browser and navigate to http://localhost:5000 to access the graphical interface. If BugHog is started on a remote server, substitute 'localhost' with the appropriate IP address.

BugHog can be stopped through:

docker compose down

⚠️ BugHog's own MongoDB instance will persist data within the database folder. Be sure to back-up accordingly, or use your own MongoDB instance as explained below.

Optional: Use your own MongoDB instance

By default, BugHog uses a MongoDB container to store data. If you prefer storing data in your own MongoDB instance, follow these steps:

1. Create a .env file from .env.example (both in the config folder) and fill in the missing database values.

2. (Re)start BugHog.

Adding your new experiments

Instructions to add your own custom experiments to the server can be found here. Be sure to restart the BugHog framework when you add a new experiment:

docker compose down
docker compose up -d

Development

For extending or debugging the Vue UI, the most convenient approach is to launch an interactive Node environment. The UI can be visited at http://localhost:5173.

docker compose up node_dev

For debugging the core application, consider using the VS Code dev container. You can utilize the configuration in .devcontainer for this.

Contact

Don't hesitate to open a GitHub issue if you encounter a bug or want to suggest a feature!

For questions or collaboration, you can reach out to Gertjan Franken.

Troubleshooting

If something isn't working as expected, check out the troubleshooting tips below. If you don't find a solution, don't hesitate to open a GitHub issue. Feel free to include any relevant logs.

Consult the logs

• Try launching BugHog without the -d flag to see logging output in the terminal, which might provide more information about the issue.
• For more detailed logs at the DEBUG level, check out the logs folder for all logging files.

WSL on Windows

• Ensure you clone the BugHog project to the WSL file system instead of the Windows file system, and launch it from there. Virtualization between these file systems can cause complications with file management.

bughog's Issues

Improve dark mode

When dark mode is enabled in the web browser, some parts of the GUI are not very readable. This should be improved.

Evaluation queue

Convenient links to revision pages

Improve efficiency related to previously evaluated binaries

Improve evaluation efficiency

BugHog is partly agnostic to experiments for which the result is already available in its database. For example, it will only check for a database entry of the experiment that is about to be conducted. If present, the experiment will be skipped.

However, when performing a targeted evaluation for example, BugHog does not take into account results of experiments that are not in its evaluation queue. By considering those, the evaluation efficiency could be improved.

Even more efficient: overhauling the current "general sweep" strategy of a predetermined experiment queue, in favor of checking for the largest unevaluated ranges and queueing experiments within those first.

Infer reproducibility through browser logs

Ideally, we would be able to infer the reproducibility of a bug, not only through sent requests, but also through browser logs.
This way, console.log() calls would be logged to a file that is readable by the worker container in which the browser runs.

However, this doesn't seem to be straightforward to implement, nor robust for all experiment scenarios.
For example, Chrome (and Firefox?) will not log console output when in incognito mode.

Current status (not implemented):

• Chrome: logging works quite well if in --headless mode, up until +/- version 110. Using the new --headless=new for versions after 110 also doesn't seem to be robust (e.g., browser crashes or doesn't start properly).
• Firefox: I still haven't figured out how to include console output in browser logs.

For now, this idea will be put into the freezer. However, it would be convenient to have another way of inferring reproducibility, other than requests / traffic.

PoC editor

Add evaluation queue functionality

Now, we can only run one evaluation configuration at a time. It would be cool if we could queue several evaluations; if one ends, the next one will start.

The application already allows us to indicate after how many experiments an evaluation should finish. Extending current UI to allow users to submit multiple evaluation configurations and managing queue in the back-end will be the main effort to achieve this.