Setting up Beast

Beast compiles to a single Golang binary which can be used anywhere.


To build beast from source follow the instruction below

  • Make sure you have docker and golang installed in your system and have it in $PATH
$ mkdir -p $GOPATH/src/

$ git clone $GOPATH/src/

$ cd $GOPATH/src/

# Build beast
$ make build

# Build additional tooling required with beast.
$ make tools

Building beast with above method will copy the beast binary to $GOBIN so make sure that it is in your $PATH

Run beast version to check if beast is build with the commit that you pulled the source code with.

[fristonio] $ ~/golang/src/ documentation
❮❮ beast version

        ****************** Beast ******************

            Version    : 0.1
            Revision   : 2b9cd25
            Branch     : master
            Build-User : [email protected]
            Build-Date : 20190713-22:50:27
            Go-Version : 1.11



All the beast related files lies in $HOME/.beast directory. Create this directory which will be used by beast.

Create a configuration file for beast in the root of beast configuration directory($HOME/.beast) named config.toml, an example configuration for the same is present in /_examples/example.config.toml.

Configuration file

The structure of the configuration file used by beast is as follows

# Authorized key file used by ssh daemon running on the host
# This is used for forwarding ssh connection to docker containers, the
# access to a container is only given to the author of the challenge.
authorized_keys_file = "/home/fristonio/.beast/beast_authorized_keys"

# Directory which will contain all the autogenerated scripts by beast
# These scripts are the heart to above authorized keys file. Each entry in authorized
# keys file as a corresponding script which is executed during an SSH attempt.
scripts_dir = "/home/fristonio/.beast/scripts"

# Base OS image that beast allows the challenges to use.
allowed_base_images = ["ubuntu:18.04", "ubuntu:16.04", "debian:jessie"]

# For authentication purposes beast uses JWT based authentication, this is the
# key used for encrypting the claims of a user. Keep this strong.
jwt_secret = "beast_jwt_secret_SUPER_STRONG_0x100010000100"

# To allow beast to send notification to a notification channel povide this webhook URL
# We are also working on implmeneting notification using IRC.

# The webhook URL of notification channel where notification should be sent
url = ""

# The service name to be used. It can be `discord` and `slack`
service_name = "discord"

# Status of webhook URL to be used.
# If it is false then notification will not be sent on this URL
active = true

# The sidecar that we support with beast, currently we only support two MySQL and
# MongoDB.
available_sidecars = ["mysql", "mongodb"]

# The frequency for any periodic event in beast, the value is provided in seconds.
# This is currently only used for health check periodic duration.s
ticker_frequency = 3000

# Container default resource limits for each challenge, this can be
# Overridden by challenge configuration beast.toml file.
default_cpu_shares = 1024
default_memory_limit = 1024
default_pids_limit = 100

# Configuration corresponding to the remote repository used by beast
# We use ssh authentication mechanism for interacting with git repository.

# URL of the remote git repository, this should be [email protected]:<git_repository> format
url = "[email protected]:sdslabs/hack-test.git"

# Name of the remote
name = "hack-test"

# Branch we are tracking the remote in beast.
branch = "master"

# Path to private SSH key for interacting with the git repository.
ssh_key = "/home/fristonio/.beast/secrets/key.priv"

# Status of remote git repository URL to be used
# If it is set to false then that remote git repository will not be used
active = true

# The following fields are required only while hosting a competition on beast
# This section contains information about the competition to be hosted
# Structure of the sections with the acceptable fields are:

# Required Fields

# Name of the competition
name = ""

# About the competition
about = ""

# Starting time of competition wrt time zone in `16:31:23 UTC: +05:30, 17th February 2021, Wednesday` format
starting_time = ""

# Ending time of competition wrt time zone in `16:31:23 UTC: +05:30, 17th February 2021, Wednesday` format
ending_time = ""

# Time zone for reference in `Asia/Calcutta: UTC +05:30` format
timezone = ""

# Optional fields

# Prizes for the competition winners
prizes = ""

# Absolute path of logo file. Default logo dir is in the "BEAST_GLOBAL_DIR/assets/"
logo_url = ""

Along with this configuration file we also need one more configuration file which is used by beast static content provider and protects some routes for the same.

The file is located at $HOME/.beast/.static.beast.htpasswd and is generated using htpasswd utility. To generate this file use the below command.

$ htpasswd -C 10 -c -B .static.beast.htpasswd <username>
New Password: <Type the password>

Configuration Directory Structure

The configuration directory structure of beast($HOME/.beast) look something as below:

├── assets
│   └── logo.png
├── authorized_keys_file
├── beast.db
├── config.toml
├── hack-secrets
│   ├── id_rsa
│   └──
├── remote
│   └── hack-test
│       └── challenges
│           └── MIGHTY-PHP
│               ├── beast.toml
│               └── challenge
│                   └── flag.php
├── scripts
│   └── 043a6aa3658c08c85d64321d986afbf69cb7ad345f16fe8aa0368ee6478f6e24
├── staging
│   └── MIGHTY-PHP
│       ├── beast.toml
│       ├── Dockerfile
│       ├── logs
│       │   └── MIGHTY-PHP.20190609173618.log
│       ├── MIGHTY-PHP.tar.gz
│       └── static
├── uploads
│   └── MIGHTY-GO
│       ├── beast.toml
│       └── challenge
│           └── flag.go

Configuring frontend for competition hosting

Clone the frontend repository and follow the setup instructions mentioned in its file.


Once the setup and configuration is done run the beast web server using the below command

beast run -v -p <PORT>

Follow the API Authentication flow to obtain a Token, use that token further to make any REST API call to the beast server. The whole swagger API documentation for the REST API can be found at the http://localhost:5005/api/docs/index.html


  • Make sure all the secrets/passwords you are using are strong enough. Also, make sure that the static content provider endpoint is HTTPS protected.