A powerful and customizable bot to manage and organize CTF competitions on Discord.
DiscordCTFHelper is a Go bot built with disgo designed to streamline CTF (Capture The Flag) management on Discord servers. The bot integrates with CTFTime and provides essential features for tracking events, managing participants, and sharing updates.
- One command to publish a CTF:
/createreads the event from CTFtime and sets up a role, a private channel, a post in the feed channel and a Discord scheduled event. If a step fails, everything already created is removed, so it can simply be retried. - Opt-in participation: members react to the feed post to get the CTF role and access to its channel, and remove the reaction to leave.
- Start and end announcements: the CTF role is pinged when the event starts. When it ends, the channel moves to the archive category and the role is retired.
- Team votes:
/voteopens a poll on the CTFs of the week, or of the next week near the weekend. The winner is created automatically, and a tie is reported to the team. - Challenge threads:
/challopens a discussion thread for a challenge while the CTF is running. - Flag tracking:
/flagannounces a solve to the team, credits a teammate, counts it, and locks the thread if used in one. - Shared credentials:
/credsstores the team's login for a CTF and shows it only to its participants. - Results:
/reportshows place and score from CTFtime, along with the solve count. - Upcoming events:
/next-ctfslists the next CTFs on CTFtime. - Welcome reaction: new members are greeted with a reaction, using a custom emoji if configured.
- Automatic command sync: slash commands are published at each start, for every server the bot is in or joins later.
| Command | Description | Who can use it | Where |
|---|---|---|---|
/init |
Configure the bot for the server | Administrators | Any channel |
/create |
Publish a CTF from its CTFtime ID | Managers | Any channel |
/remove |
Remove a CTF and everything it owns | Managers | Any channel |
/vote |
Open a poll on the next CTF | Managers | Any channel |
/delete-flag |
Take back a solve from the count | Managers | CTF channel |
/next-ctfs |
List the next CTFs on CTFtime | Everyone | Any channel |
/flag |
Register a flag | Anyone in the CTF channel | CTF channel or its threads |
/chall |
Open a challenge thread | Participants, while the CTF is active | CTF channel |
/report |
Show the results of the CTF | Participants | CTF channel |
/creds |
Show or set the CTF credentials | Participants | CTF channel |
/delete-creds |
Delete the CTF credentials | Participants | CTF channel |
/help, /guide, /rules |
Commands, how to play and rules | Everyone | Anywhere |
/ping, /version |
Latency and build information | Everyone | Anywhere |
Managers hold the role chosen with /init, and participants hold the role of the CTF. Being a manager doesn't make someone a participant.
- Go 1.27.3 or later
- A C compiler such as
gcc, needed by the SQLite driver - A Discord bot token (obtainable via the Discord Developer Portal)
-
Clone this repository:
git clone https://github.com/ByteTheCookies/DiscordCTFHelper.git cd DiscordCTFHelper -
Install dependencies:
go mod download
-
Set up your
.envfile: Create a.envfile in the root directory and include the following variables:TOKEN=<discord_token> LOG_LEVEL=info LOG_FORMAT=text LOG_SOURCE=false
-
Create the directory for the database:
mkdir -p data
-
Run the bot:
go run ./cmd/ctfhelper
Slash commands are published automatically at each start, globally. Use a separate bot token for development, as running with the production one publishes your local commands to every server.
mkdir -p data
sudo chown -R 1000:1000 data
docker compose up --buildThe container runs as UID 1000, which needs write access to the directory holding the database.
| Variable | Required | Description |
|---|---|---|
TOKEN |
Yes | Discord bot token |
LOG_LEVEL |
Yes | debug, info, warn or error |
LOG_FORMAT |
No | text or json, text by default |
LOG_SOURCE |
No | true to log the source location |
DB_PATH |
No | Database path, data/ctfs.db by default |
GREET_EMOJI_ID |
No | Custom emoji to greet new members with, 🍪 by default |
- Invite the bot to your server using an OAuth2 link from the Discord Developer Portal. It needs permission to manage channels, roles, events, threads and messages, view message history, send messages and polls, create public threads and add reactions. No privileged intents are required.
- As an administrator, run
/initto choose the categories for active and archived CTFs, the manager role, the feed channel, your CTFtime team ID and the team role. - As a manager, publish a CTF with
/create, or let the team choose with/vote. - Members react to the post in the feed channel to join.
This project is licensed under the Apache License. See the LICENSE file for details.
- Add final scraping for team stats
- Add overall report generation
- New handling of channel one channel only read width the banner show
- Flag command
- Reaction cookie and fire too each flag
- Remove command
- Creds command (command for store and show the creds of a ctf)
- Send link to ctf message when channel is created
-
/challcommand to add challenges - Migration to discordgo or disgo (not urgent)
-
/voteto vote next ctf
For support or questions, feel free to open an issue or contact us directly
