circus-companion
The companion ~cube~ container spawned specifically for one user.
Purpose
- Validator for flags
- Temporary secret vault for the user
- control endpoint of challenge containers for the user
Usage
This executable needs some parameters to work properly:
| Key | Required? | Description |
|---|---|---|
-port |
No | The port for HTTP. Default: 8080 |
-username |
No | Name of our user, as used e.g. in salutation. No length or charset limitation. Default: Player 1 |
-accessCode |
Yes | Access code for the user. Default: AllYourCodesAreBelongToUs |
-sessionSalt |
Yes | Variable to salt the session token generator with. |
-seedFile |
Yes | JSON file to read challenge information from. |
-vpnRemoteAddress |
Yes | Address the VPN will run on, as rendered into the client VPN configuration file. |
-vpnRemotePort |
No | Port the VPN will run on |
-endTimestamp |
No | Date/Time after which flags are not accepted anymore |
-endAfter |
No | Seconds (!) after the first login, after which flags are not accepted anymore |
If -endTimestamp and -endAfter is given, flags are not accepted if one of the given flags kicks in.
Seed file
The seed file should be of the following format:
{
"challenges": [
{
"name": "Evil Service",
"description": "A meaningful and funny description",
"flag": "CIRCUS[IS_REALLY_COOL]",
"container": "challenge-evilservice",
"category": "Miscellaneous",
"points": 100
},
{
"name": "Insecure Stuff",
[...]
]
}
API endpoints
| Path | Method | Parameter | Description |
|---|---|---|---|
/ |
GET | - | static hosting /files/index.html |
/files/{file} |
GET | - | static hosting {file}, from hosted/ directory. Path traversal-safe |
/login |
GET | - | static hosting /files/login.html |
/login |
POST | username, accesscode |
processing username and accesscode, giving the user a session if they are valid |
/logout |
GET | - | Invalidates the session |
/challenges |
GET | - | static hosting /files/challenges.html |
/access |
GET | - | static hosting /files/access.html |
/api/getChallenges |
GET | - | Returns all challenges, as JSON. For an example, see below. |
/api/submitFlag |
POST | challengeName, flag |
Validates flag for challengeName |
/api/startContainer |
POST | challengeName |
Starts the challenge container for challengeName, if it's not already started |
/api/stopContainer |
POST | challengeName |
Stops the challenge container for challengeName, if it's running |
/api/getAccess |
GET | - | Returns the VPN configuration required for accessing the containers |
Response: /api/getChallenges
{
"categories": {
"Miscellaneous":1 // contains the amount of challenges in that category
},
"challenges": [
{
"name": "ChallengeName",
"description": "Some meaningful, interesting and funny description",
"category": "Miscellaneous",
"points": 100,
"foundFlag": false, // whether the user found the flag
"ContainsLaunchable": true, // if set to true: there's a container which can be started/stopped
"IPAddress": "1.2.3.4" // contains the IP address if the container is running
}
]
}
