You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Beast is a service that runs on your host(maybe a bare metal server or a cloud instance) and helps manage deployment, lifecycle, and health check of CTF challenges. It can also be used to host Jeopardy-style CTF competition.
12
+
13
+
## Features
14
+
15
+
- Git based source of truth.
16
+
- Container based isolation
17
+
- Easy configuration
18
+
- SSH support for challenge instances
19
+
- Command line interface to perform actions and host competitions
20
+
- REST API interface for the entire ecosystem
21
+
- An optional automated health check service to periodically check the status of challenges and report if there is some sort of problem with one.
22
+
- Single source of truth for all the static content related to all the challenges making it easy to debug, monitor and manage
23
+
static content through a single interface.
24
+
- Use of sidecar mechanism for stateful workloads which can be shared by multiple challenges at once, MySQL for example.
25
+
- Support for various notification channels like slack, discord.
26
+
- Everything embedded to a single go binary which can be easily used anywhere.
27
+
28
+
For more details on the features, refer to [Features](./docs/Features.md)
29
+
30
+
## Supported Challenge's Types
31
+
32
+
As of now beast support the following type of challenges:
33
+
34
+
- Service - A service hosted on beast container instance
35
+
- Web - Web based challenges for various languages including PHP, Python, Node.js etc.
36
+
- Static - Challenges with static files, this may include forensics challenges.
37
+
- Bare - Highly customisable challenges.
38
+
- Docker - Challenges which are provided with their own docker file.
6
39
7
40
## Development
8
41
9
-
Beast go version is under development, follow the below instructions to get started.
42
+
Beast go version is under development; follow the below instructions to get started.
10
43
11
-
* Install go 1.11.x
12
-
* Make sure that `GO111MODULES` environment variable should be set to `on`, or do `export GO111MODULES=on`
13
-
* Clone the repository.
14
-
* Jump to `$GOPATH/src/github.com/sdslabs/beastv4/` and start hacking.
44
+
- Install go 1.13 or above
45
+
- Make sure that `GO111MODULES` environment variable should be set to `on`, or do `export GO111MODULES=on`
46
+
- Clone the repository.
47
+
- Jump to `$GOPATH/src/github.com/sdslabs/beastv4/` and start hacking.
BEAST: An automated challenge deployment tool for backdoor
26
59
27
-
* build: Build beast and copy binary to PATH setfor go build binaries.
60
+
* build: Build Beast and copy binary to PATH setfor go build binaries.
28
61
* check_format: Check for formatting errors using gofmt
29
62
* format: format the go files using go_fmt in the project directory.
30
63
* test: Run tests for beast
31
-
* tools: Set up required tools forbeast which includes - docker-enter, importenv
64
+
* tools: Set up required tools forBeast which includes - docker-enter, importenv
32
65
```
33
66
34
-
**All the dependencies are already vendored with the project so no need to install any dependencies**. The projcet uses go modules from
35
-
go 1.11.X fo dependency management. Make sure you vendor any library used using `go mod vendor`
67
+
**All the dependencies are already vendored with the project, so no need to install any dependencies**. The project uses go modules from go 1.13.X of dependency management. Make sure you vendor any library used using `go mod vendor`
36
68
37
69
### Building
38
70
39
-
To build beast from Source use the Makefile provided.
40
-
41
-
*`make build`
42
-
43
-
This will build beast and will place the binary in `$GOPATH/bin/` will also copy the necessery tools to desired place. To build this in production make sure you also have built the static-content docker image in `/extras/static-content`
44
-
45
-
To run the API server for beast use command `beast run -v`
46
-
47
-
### Directory Structure
71
+
To build Beast from Source use the Makefile provided.
48
72
49
-
***api**
50
-
* API exposed by beast
51
-
* This uses `gin` as rest API framework and routes are grouped under `/api`
52
-
* API Docs are served using swagger API specs.
73
+
-`make build`
53
74
54
-
***scripts**
55
-
* Build scripts for beast.
56
-
* Other relevent scripts for beast including docker-enter.
75
+
This will build Beast and place the binary in `$GOPATH/bin/` and copy the necessery tools to the desired place. To build this in production make sure you also have built the static-content docker image in `/extras/static-content`
57
76
58
-
***cmd**
59
-
* Package containing command line functionality of beast.
60
-
* `commands.go` is the main entrypoint for the package
61
-
* This makes use of spf13/cobra for command line flag parsing.
62
-
63
-
***core**
64
-
* Core functionalities of beast
65
-
* It includes package managing challenges.
66
-
* Inside package `manager` lives the code relating to all the core functionality that beast provides.
67
-
* It also contains database wrapper using gorm for beast.
68
-
69
-
***pkg**
70
-
* Contains library code which can be used by external applications also.
71
-
* **cr**
72
-
* **notify**
73
-
* **git**
74
-
* **scheduler**
75
-
* **probes**
76
-
* **workerpool**
77
-
78
-
***templates**
79
-
* Tempaltes used by beast.
80
-
* For example - Beast dockerfile template, beast challenge config template etc.
81
-
82
-
***utils**
83
-
* Beast utility functions package.
84
-
85
-
***version**
86
-
* Version package for beast.
87
-
* Use `beast version`
88
-
89
-
***_examples**
90
-
* This directory contains example challenges for beast.
91
-
* An example beast global root config to be placed in `$HOME/.beast/config.toml`
77
+
To run the API server for Beast, use the command `beast run -v`
92
78
93
79
### Testing
94
80
95
81
To test use the sample challenges in the `_examples` directory. Use the challenge simple and try to deploy it using
96
-
beast. Follow the below instructions.
82
+
Beast. Follow the below instructions.
97
83
98
84
You can find swagger API documentation here: http://localhost:5005/api/docs/index.html
# Or you can directly deploy the challenge using name in the remote
112
98
$ curl -X POST --data "action=deploy&name=<challenge_name>" localhost:5005/api/manage/challenge/
113
99
114
-
# Wait for beast to finish the image build and deployment of the challenge
100
+
# Wait for Beast to finish the image build and deployment of the challenge
115
101
# This might take some time. Have some snacks ready!
116
102
# Try connecting to the deployed service
117
103
$ nc localhost 10001
@@ -126,7 +112,7 @@ choice > 4
126
112
127
113
### Documentation
128
114
129
-
The documentation for the project lies in [/docs](/docs). We use `mkdocs` to automatically generate documentation from markdown. The configuration file for the same can be found at [mkdocs.yml](/mkdocs.yml). To view the documentation locally create a virtual environment locally and install [requirements](/requirements-dev.txt).
115
+
The documentation for the project lies in [/docs](/docs). We use `mkdocs` to automatically generate documentation from markdown. The configuration file for the same can be found at [mkdocs.yml](/mkdocs.yml). To view the documentation locally, create a virtual environment locally and install [requirements](/requirements-dev.txt).
130
116
131
117
```bash
132
118
$ virtualenv venv &&source venv/bin/activate
@@ -140,10 +126,25 @@ Serving on http://127.0.0.1:8000
140
126
141
127
### Development notes
142
128
143
-
Beast uses `logrus` for logging purposes and follow standard effective go guidelines, so anytime you are writing a code keep in mind to
144
-
add necessery logs and documentation. Also format the code before commiting using `gofmt`. Or simply run the make command `make test`
129
+
Beast uses `logrus` for logging purposes and follows standard effective go guidelines, so anytime you are writing a code, keep in mind to add necessary logs and documentation. Also, format the code before committing using `gofmt`. Or simply run the make command `make test`
145
130
146
-
For any API routes you add to the beast API do write Swagger API documentation.
131
+
For any API routes, you add to the beast API, do write Swagger API documentation.
147
132
148
133
The design documentation for the new Beast can be found [here](https://docs.google.com/document/d/1BlRes900aFS2s8jicrSx2W7b1t1FnYZhx70jGQu__HE/edit)
149
134
135
+
## Contributing
136
+
137
+
We are always open for contributions. If you find any feature missing, or just want to report a bug, feel free to open an issue and/or submit a pull request regarding the same.
138
+
139
+
For more information on contribution, check out our
140
+
[docs](./docs/contribution.md).
141
+
142
+
## Contact
143
+
144
+
If you have a query regarding the product or just want to say hello then feel
145
+
free to visit [chat.sdslabs.co](https://chat.sdslabs.co) or drop a mail at
0 commit comments