# Runner Overview

The Runner is an agent that executes tasks on your behalf. No more, no less.

The purpose of the runner is to decouple the execution of tasks from the main application, allowing for greater flexibility and scalability. By using a runner, you can offload resource-intensive operations, manage task execution more efficiently, and improve the overall performance of your system.

Let's first explore the reasons why the runner is decoupled and designed to run on your own environment.

# Full control over the environment

One of the goals of the BountyHub platform is to allow bounty hunters to control the environment from which the scans are executed.

Controlling the environment is crucial for several reasons:

  1. Customization and flexibility: You can run proprietary or sensitive tools without exposing them to third-party services. As long as the runner is able to find the executable, it can run it. The platform does not care what the scan is. It simply schedules it, assigns it to the runner, and propagates the scan information so the runner can successfully execute it.
  2. Increased security: Network policies, VPNs, and firewalls can restrict access to certain resources. By running the runner in your own environment, you can ensure that it has access to the necessary network resources to perform its tasks. Based on your target, you might need to configure specific access rules to allow the runner to reach the target systems. With self-hosted runners, you can configure the network settings to meet your specific requirements. The best part of it: none of these policies or configurations are part of the BountyHub platform. You have full control over them.
  3. Reduced costs: Since self-hosting is not part of the platform, you can designate the VPS servers or cloud instances that you already own to run the runner. Most of us use the VPS to run scans, so you can re-use your own instance and start the runner on it. By re-using your existing infrastructure, BountyHub does not have to provision and run runners for you. Therefore, the only cost of you running the runner is the cost of the load the servers must handle when executing the scans. This is a significant cost saving, especially for long-running scans.

However, running self-hosted does have downsides:

  1. Maintenance overhead: You are responsible for maintaining and updating the runner software. This includes ensuring that the runner is up-to-date with the latest features and security patches.
  2. Initial setup complexity: Setting up the runner in your own environment may require some technical knowledge and effort. You need to ensure that the runner is properly configured and has access to the necessary resources.
  3. Monitoring and troubleshooting: You are responsible for monitoring the runner's performance and troubleshooting any issues that may arise. This may require additional tools and expertise.

Despite these downsides, the benefits of having full control over the environment often outweigh the challenges, especially for security-conscious users and organizations. If you are serious about security and want to ensure that your scans are executed in a controlled and secure manner, self-hosting the runner is the way to go.

If down the line, multiple users want to use hosted services, we might consider offering hosted runners as an additional option. However, for now, the focus is on providing self-hosted runners to ensure maximum control and security for our users.

Ability to self-host will always be one of top priorities of the platform. It was one of the reason this platform was created in the first place.

If you are curious, check out the Comparison With Other Automation Platforms.

# Open-source

The runner is open-source, allowing users to inspect the code, contribute to its development, and customize it to fit their specific needs.

There are multiple reasons why open-sourcing the runner is beneficial:

  1. Transparency: you know exactly what is being executed on your machines. There are no hidden functionalities or backdoors. You can inspect the code to ensure that it aligns with your security and privacy requirements.
  2. Community contributions: Open-sourcing the runner allows for community contributions, which can lead to faster development, bug fixes, and new features. Users can contribute code, report issues, and suggest improvements, fostering a collaborative environment that benefits everyone.
  3. Customization: Users can modify the runner to suit their specific needs, adding features or integrations that are relevant to their workflows. This flexibility allows users to tailor the runner to their unique requirements, enhancing its utility and effectiveness. You can always build your own runner, since you already know what the API looks like. However, if you decide to build your own runner, you are on your own. There is no support for custom runners.

You can see the source code of the runner on GitHub. Feel free to explore the code, report issues, and contribute to its development.

# Scalability

By decoupling task execution from the main application, the runner allows for scalable task management. You can deploy multiple runners across different environments, distributing the workload and ensuring that tasks are executed efficiently. This scalability is particularly beneficial for handling large volumes of tasks or resource-intensive operations.

Having multiple runners running in parallel allows for better resource utilization and improved performance. Tasks can be distributed among the available runners, reducing bottlenecks and ensuring that tasks are completed in a timely manner.

# Isolation and fault tolerance

The runner operates independently of the main application, providing isolation for task execution. This isolation ensures that any issues or failures in the runner do not impact the overall system. If a runner encounters an error or crashes, it can be restarted or replaced without affecting the main application. This fault tolerance is crucial for maintaining system stability and reliability.

Since tasks are executed in a separate environment, no information is shared between different users. Isolation could be achieved running the runner in a containerized environment, such as Docker. This ensures that each user's tasks are executed in a separate and secure environment, preventing any potential data leaks or cross-contamination.

However, if a malicious user gets access to the container, and is able to escape it, it can potentially do a lateral move and exploit other users' data.

Even though this scenario is highly unlikely, it is still a risk to consider. Therefore, the platform can:

  1. Invest significant efforts into ensuring that the hosted environment is isolated and secure. Continuously monitor the environment for any potential vulnerabilities or breaches.
  2. Avoid this whole problem by requiring separate environments maintained by users. No machine is ever shared between machines executing the runner, so there is no way a malicious user can laterally move.

Again, if down the line, the need arises for hosted runners, we might consider offering them as an additional option. However, for now, the focus is on providing self-hosted runners to ensure maximum control and security for our users.

# How it works

The Runner is designed to be lightweight and easy to deploy. It communicates with the main application via a secure API, receiving tasks to execute and reporting back the results.

Make sure to check the Getting Started guide to learn how to set up your first runner.

In order for the runner to talk to the BountyHub platform, it needs to be registered and configured.

Registration is done by fetching the one-time token. Once the token is used, it cannot be used again.

During registration, you need to configure:

  1. The name of the runner: unique per user account.
  2. Workdir: the directory where the runner will store its data.
  3. URL: Back-end URL of the BountyHub platform.

Optionally, you can configure capacity, which is the maximum number of tasks the runner can handle in parallel. By default, the capacity is set to 1, meaning that the runner will execute one task at a time. You can increase this value to allow the runner to handle multiple tasks concurrently, depending on the resources available on the host machine.

Just keep in mind that increasing the parallelism means that two jobs associated with the same target can land on the same machine. Make sure you always follow the rules of engagement. You can always use proxies to proxy your requests, making sure that you are not violating any rules.

Once configured, the runner will continuously poll the BountyHub platform for new tasks to execute. Once the task is assigned to the runner, it cannot be unassigned. The runner is responsible for executing the task until completion.

To illustrate the flow, let's take a look at the following sequence diagram:

Loading diagram...

# Next steps