🌌 VOID-BOT

The Central Nervous System for the VoidWalkers CTF Team

An advanced Discord bot designed to automate CTF operations, track team engagement, and gamify the hacking experience.

---

⚙️ Core Architecture

Void-Bot is built from the ground up to be lightweight, secure, and modular. Running on a hardened homelab, it utilizes an asynchronous Discord.py Cog architecture to ensure commands, background tasks, and database queries run concurrently without blocking.

🚩 Features & Roadmap

Our development is tracked via the internal GitHub Project board. Here is the current state of the Bot's arsenal:

🟢 Phase 1: Operations

• Modular Architecture: Cog-based system with CoreCog, EventsCog, DashboardCog, and GamificationCog.
• CTF Event Creation: Admin commands to generate CTF event embeds with start/end times, team size, and CTFTime links.
• Role Assignment UI: Persistent interactive buttons for players to mark ⭐ Interested, 🧭 Apply for Captain, or ❌ Withdraw.
• Automated Deployment: Bot automatically DMs team credentials or invite links to selected rosters.
• Zero-Hour Alerts: Background task that DMs selected players exactly when a CTF goes live.
• Live Dashboard: Auto-updating embed that displays all upcoming and active CTFs with live registration counts.
• Clock-in / Clock-out: Session tracking to monitor active hours during a CTF event.
• Idle Flagger: Players are auto-clocked out if no proof is submitted within 70 minutes.

🟡 Phase 2: Gamification (Current Focus)

• Proof Submission: Players upload screenshots of their progress via /proof, re-hosted to a permanent staff channel.
• Leaderboards: Rankings by active time and proof count per event.
• Internal Flagging: Share challenge names and submit flags to the bot to prove solves and earn points.
• Leveling System: Gain EXP and level up as you participate and solve challenges.

🔴 Phase 3: Analytics (Future)

• Engagement Tracker: Admin analytics per event showing participation rates and challenge category breakdowns.
• Hacker Profile Cards: A dynamic text card showing a player's EXP, solves, CTFs participated in, and captain history.

---

💻 Deployment Guide

Void-Bot is designed to be hosted on a secure Linux environment (but it can still be run on Windows and macOS). Follow these steps to deploy the bot to your system.

1. Prerequisites

Ensure your system has Python 3.10+ and Git installed. Select your operating system or distribution below:

Debian / Ubuntu

sudo apt update && sudo apt install python3 python3-venv python3-pip git

Arch Linux

sudo pacman -Syu python python-pip git

(Note: Arch includes the venv module in the base python package.)

Fedora / RHEL

sudo dnf install python3 python3-pip git

macOS (via Homebrew)

brew install python git

---

2. Clone the Repository

git clone https://github.com/Void-Walkers-Community/Void-Bot
cd Void-Bot

---

3. Setup the Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

4. Configuration & Secrets (.env)

CRITICAL: Never commit your bot token to GitHub. Void-Bot uses a .env file to securely load all credentials and channel IDs.

Copy the example file and fill in your values:

cp .env.example .env
nano .env

# Bot token from the Discord Developer Portal
TOKEN=your_bot_token_here

# Channel where Interested / Captain applications are posted
APPLICATION_CHANNEL_ID=000000000000000000

# Hidden staff channel where proof screenshots are permanently stored
PROOF_LOG_CHANNEL_ID=000000000000000000

# Staff-only channel that receives all admin audit logs
AUDIT_LOG_CHANNEL_ID=000000000000000000

The bot will refuse to start if any of these values are missing.

---

5. Booting the System

python3 main.py

If successful, the terminal will confirm all Cogs loaded and slash commands synced.

Loaded cogs.core
Loaded cogs.events
Loaded cogs.dashboard
Loaded cogs.gamification
Slash commands synced.
VoidBot#1234 is online and fully operational!