Motivation

Most people doing bug bounties or penetration testing are running some VPS box where they have faster internet access or tooling installed to avoid black-listing.

With that in mind, the runner running as a process on the VPS can also have access to those tools. BountyHub allows leveraging your machine to actually do the work in the background, while storing results on the server accessible to you from any machine.

If you don't want your result uploaded (for example, screenshots), you can write your workflow to instruct the runner to output data to some directory on your box. The important thing to note is, unless your workflows specifies the uploads, nothing will be uploaded as a result to the server. However, the workdir configured for the runner is going to be cleaned up on every run, so your results will not be preserved on the machine after the run.

Another important argument for running self-hosted runner is that you control your environment. The reasoning is that:

• You control your environment. The runner is installed where you want, with permissions you want
• If you want to use proxy in corporate environments, you can.
• If you don't want to buy a VPS, you can start the runner on your own machine.
• You specify how to avoid being blocked by DNS providers etc. If you want to use Tor, you can. As far as the platform is concerned, your runner gets the job, propagates information from the job, and finishes the job. That is it.
• No need for higher pricing by the platform. In most cases, you have a VPS so why not use it and avoid unnecessary cost of the platform provisioning machines for you.
• You control the tooling. If you have proprietary tools available only on your machine, you can simply invoke it. The platform doesn't have to pull these binaries or scripts.

Runner

Runner is an agent executing workflows. You can start it on your home machine, or a VPS and leave it running.

The server will notify your runner when there is a workflow ready to be executed. The runner does not act as a server, so it is safe to leave it running. The runner also does not come with pre-defined dependencies. As long as you have tools visible to the runner on your machine, you can run any tool you want. If you have custom tools, that is also fine. As far as the runner is concerned, it executes what you specify in your workflow.

Runner source is available on GitHub. The reason for open-sourcing the runner is to show you that it is not doing anything behind your back. Having runner open-sourced will cause slower development speed. Building stuff in the open means that you need to make sure you are not exposing any secrets during the process. However, the price of you knowing exactly what is being executed on your own machine is worth sacrificing the development speed.

Registration

Runners need to be registered in order to execute tasks. During registration, runner will receive its own authentication token. That token allows runner to communicate with the back-end and receive jobs.

To register your runner, visit your profile, and under Runners tab, click New Runner. The New Runner page contains information how to download the runner and how to configure it.

There are few important variables during registration time:

1. Name: It is the name of the runner. Each runner must have a unique name at the time of registration.
2. Workdir: The working directory that the runner will use to create temporary files and execute commands from.

To see all options when configuring the runner, you can run the following command:

Deletion

You can remove your runners from your profile. Once removed from your profile page, the runner will not be able to connect to the back-end anymore.

On your own machine, the runner registration information is stored in the .runner file. If you remove this file, the runner will still exist on the server, but you will not have a way to connect to the server anymore.

Session

The runner uses two types of tokens for authentication:

1. Runner Token
   The runner token is used for routine operations such as acquiring jobs, completing jobs, and general communication. This token is designed to be long-lived and is generated as a globally unique UUID v4, making it highly secure and nearly impossible to guess.
   To enhance security, the runner token has a lifetime of 30 days. A session refresh mechanism allows the token to be renewed within this period. If the token expires without being refreshed, the runner will no longer function, requiring reconfiguration.
2. Worker Token
   The worker token is specific to job-related tasks, such as resolving jobs, updating timelines, and uploading logs and assets. This token is short-lived, with a fixed 4-hour lifetime and no refresh mechanism.
   The 4-hour limit is intentional for the following reasons:
   • Workflow Integrity: Jobs running longer than 4 hours may indicate a design issue. Breaking large tasks into smaller, interdependent jobs ensures better resource management. Expired tokens free up runner capacity for other jobs.
   • Security: The worker token is only communicated to the runner when acquiring a job and is not stored on the file system, minimizing exposure even if the machine is compromised.

Running the runner

The runner should be long-running process. When it runs, it keeps the session alive, continuously asking for jobs.

The pre-condition for runner to ask for the job is that the runner is configured.

Running the runner in the foreground

The foreground means that the runner execution will be bound to your terminal, and as long as that terminal is open, the runner will try to receive and run jobs. Once you kill the terminal, the runner will shut down as well.

This mode can be useful when you want to manually control when the runner is online. Although this is not scalable, if you hack from time to time, this may be an option for you. You don't need to waste resources if you hack every two weeks for example.

To run the runner in the foreground (provided that the runner is registered), please run the following:

Running the runner in the background

The more useful mode for professionals is to have runners running as a service. When started as a service, the runner will actually be installed using systemd, and will be managed by it. That way, you can exit your terminal session and the runner will stay online, running jobs when they arrive.

To quickly install and run the runner as a service, please run the following command:

Limitations

Currently, runner application is only supported on the Linux platform. This may change in the future based on the feedback.

Having said that, it is not impossible to compile it to run on other platforms. The runner is written in Rust, so you can build it on your own. Having all platforms supported would mean that runner needs to be tested on them. So let's not support something until there is a real need for it.