PsyBot

A Discord bot that provides tools for collaboration in CTFs. Inspired by fiskebot

Features

PsyBot adds a number of slash commands for easy and effective CTF management and collaboration:

CTFs

• /ctf create <name> [ctftime_link] [private]: Create a new CTF
  • Creates a new CTF channel and provides access for team members
    • /invite <user>: Add a new player to the CTF channels
    • /inviterole <role>: Add all members with a specific role to the CTF channels
    • /remove <user>: Remove a current player - players can leave manually with /leave
  • When a CTFtime link is supplied, most CTF information is automatically retrieved
    • Manually update info such as team credentials and Discord link with /ctf update <field> <value>
  • When private is set, only the admin running this command will be added to the CTF channels
  • /ctf rename <name>: Rename CTF if needed - very short names recommended to fit in channel list
• /add <category> <name>: Create new challenge
  • Creates a new channel under INCOMPLETE CHALLENGES
  • category is a selection list, create new with /category create <category>, delete with /category delete <category>
• /note [note_type]: Create challenge note
  • Lets all team members edit the same embedded note
  • Notes can be pinned/unpinned and moved to the bottom of the chat
  • Default note_type is modal, allows edits within Discord through a modal
    • Simultaneous changes are merged with diff-match-patch
  • Use note_type:doc for an external HedgeDoc markdown note
    • NOTE: HedgeDoc has disabled anonymous demo notes, this now requires a custom instance
    • Custom HedgeDoc URL can be set with /psybot set key:hedgedoc_url value:<URL>
• /working set <status>: Set working status (/w short for /working set Working)
  • Or simply click the Set Working button in the challenge channel
  • Get an overview with /working table
• /done [contributors]: Mark a challenge as done
  • Moves the challenge to COMPLETE CHALLENGES and sends a notification mentioning all contributors
  • Use /undone to move the challenge back if wrongly marked
• /ctf invite: Create a CTF invitation message in invite_channel.
  • Requests will be sent to admin_channel for an admin to accept.
• /ctf archive: Archive a CTF
  • Unarchive if needed with /ctf unarchive
• /ctf export: Export a CTF
  • Exports all CTF channels to JSON format, files are not currently exported
  • Both running and archived CTFs can be exported
• /ctf delete [security]: Delete a CTF
  • Asks for CTF name as a sanity check if not input as security

CTFtime

• /ctftime team [team] [year]: See a team's top 10 CTFs
  • Defaults to current year and your team
  • Set team with /psybot set key:ctftime_team value:kalmarunionen
• /ctftime top [country] [year]: See the top CTFtime teams
  • Defaults to this year, globally
• /ctftime calc <weight> <best_points> <team_points> <team_place> [team]
  • Use CTFtime's rating formula to compute points for a CTF
  • Shows how this would affect your team's total points

Installation

First, you need to create a bot on https://discord.com/developers/applications.

Then invite it with the following link, replacing CLIENT_ID with your actual id: https://discord.com/api/oauth2/authorize?client_id=CLIENT_ID&permissions=8&scope=bot%20applications.commands

With docker-compose

Create a .env file like this:

BOT_TOKEN=token
GUILD_ID=optional_guild_id

Create the backups directory

mkdir ./backups
chown +1000:+1000 ./backups

Then run docker-compose up -d

Manually

Install dependencies with pip

python3 -m pip install -r requirements.txt

Install MongoDB and set it up.
Set up BOT_TOKEN and optionally GUILD_ID environment variables.

Run the script

./bot.py

Configuration

The bot has a number of settings that can be modified to match your server's needs. Use /psybot info to see all the current value for all settings and /psybot set <key> <value> to modify these.

Only bot admins can view and change settings, this role is created when the bot is run (Team Admin by default) and set as admin_role. To change settings, you must first give yourself this bot admin role. Afterward, the admin and team roles can optionally be set to some of your existing server roles and the auto-generated roles can be deleted.

Settings:

• team_role: ID of CTF team role, auto-generated by default as @Team Member
  • By default, all users with this role get access to new CTFs, unless marked with private:True
• admin_role: ID of CTF admin role
  • Only admins can create, archive, export, and delete CTFs, create and delete categories, and view and modify settings
• inactive_role: ID of inactive role
  • When use_team_role_as_acl is set to True, team members can temporarily get this role by typing /leave
  • Users with this role do not have access to CTF channels, but can get the team role at any time by running /rejoin
• ctfs_category: Discord category for created CTFs, default CTFS
• incomplete_category: Discord category for incomplete challenges, default INCOMPLETE CHALLENGES
• complete_category: Discord category for complete challenges, default COMPLETE CHALLENGES
• archive_category: Discord category for archived challenges, default ARCHIVE
• ctf_archive_category: Discord category for archived CTF main channels, default ARCHIVED CTFS
• voice_category: Discord category for per-ctf voice channels, default Voice Channels
• export_channel: Channel ID for JSON export uploads
• invite_channel: Channel ID for per-ctf invitations. Access requests will be sent to admin_channel. Optional
• admin_channel: Channel ID for admin-only logs. Required together with invite_channel. Otherwise, optional
• per_ctf_voice_channels: Number of voice channels to create in voice_category when creating a CTF, default 0
• enforce_categories (default True): Players must choose a category from the existing list
  • New categories can be created by team admins
  • If false, players get the selection options but can type any category they want
  • Custom categories are then automatically added to the option list
• send_work_message (default True): Send a message in each new challenge channel with a "Set Working" button
• use_team_role_as_acl (default False): Use team_role directly as access control for public CTFs
  • If true, team members running /leave will be moved to the inactive role
  • If false, a new role is created per CTF for fine-grained access control
    • This role is automatically given to every player with team_role for immediate access
    • New players can be invited with /invite and can manually leave with /leave or be removed by an admin with /remove
  • The setting has no effect on private CTFs, a new role is always created for these
    • But all players must be manually invited, team members do not get the new role automatically
• invite_admin_only (default False): Only team admins are allowed to invite players to a CTF
• hedgedoc_url: URL for HedgeDoc notes, defaults to https://demo.hedgedoc.org/
  • NOTE: The default demo URL no longer works, HedgeDoc has disabled anonymous demo notes
• ctftime_team: CTFtime team name, used by default by /ctftime commands if set