Collaborative tool for CTF (capture the flag) teams to keep track of and collaborate on challenges during competitions.
The goal of this project is to provide an open source, developer friendly, pickup and go solution to collaberative development while solving cybersecurity puzzles in CTF competitions.
- Pick up and go: Our website is meant to be as simple as possible. Users don’t need accounts, they just enter a PIN and get access to an instance similar to Kahoot.
- Open source: We value transparency and community. By choosing to make our software open source we are enabling others to contribute to and audit the code.
- Industry-Standard Tech Stack: Built with Go (backend), SvelteKit (frontend), and MySQL (database), our stack prioritizes performance, scalability, and developer familiarity.
- Developer-Friendly Codebase: We prioritize code organization and helpful comments to make the project accessible to new contributors.
- Kevin Rossel: Resident CTF’er. Backend and database schema. Guided UI/UX
- Teo Liam Ippolito: UX Designer and Frontend Development Lead
- Brayden Aldrich: Frontend, backend, and API development
- Danny T Nguyen: Implemented frontend features
- Maximiliano Maldonado: Backend Development Lead, Database Design, API Development, and Implementing Frontend
- Sory Diagouraga: Backend development and API documentation.
Development of CTFNote is ongoing. We can't provide guarantees of its stability in a production environmnet. Use at your own risk.
- CTFCollab
- Project Values
- Team Members and Roles
- Table of contents
- End User Documentation
- Technical Documentation
- Self-hostable
- Live document editing
- Challenge tracking
- CTF tracking
- CTF member tracking
- Free and open source
Create a .env file in the root directory of CTFCollab. Here is a template:
MYSQL_ROOT_PASSWORD=CHANGE_ME
MYSQL_DATABASE=ctfcollab
MYSQL_USER=ctfuser
MYSQL_PASSWORD=CHANGE_ME
MYSQL_URL=${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(db:3306)/${MYSQL_DATABASE}?multiStatements=true&parseTime=true
CMD_DB_URL=mysql://hedgedoc:hedgedoc_pass@db:3306/hedgedoc
CMD_DOMAIN=localhost:3001
HEDGEDOC_URL=http://hedgedoc:3000
CMD_PROTOCOL_USESSL=false
CMD_URL_ADDPORT=false
ADMIN_USERNAME=Admin
ADMIN_PASSWORD=CHANGE_ME
JWT_SECRET=CHANGE_ME
Starting
docker compose up --build
Stopping
docker compose down
Removing database
docker volume rm ctfcollab_db-data
# or, to remove the database while spinning the containers down
docker compose down -v
For frontend development, it helps to not run the frontend in docker so it auto updated with each change to the source code.
# Run just the backend in docker
docker compose -f compose.backend_only.yaml up --build
# Run the frontend outside of docker (make sure to do npm install)
npm run devIf for whatever reason you want to run the frontend outside of docker, first run npm install (or pnpm install or yarn) in the repository directory. Then to run the frontend, use one of these commands:
npm run dev
# or start the server and open the app in a new browser tab
npm run dev -- --openIt is also recommended to get the svelte extension for vscode. If you use another editor there is likely a svelte extension/plugin for it.
To create a production version of the frontend:
npm run buildYou can preview the production build with npm run preview.
Golang is required to compile and run the backend code on your computer
For working on the database schema, sqlc is required https://docs.sqlc.dev/en/stable/overview/install.html
Running code: go run . while in the backend directory
You can modify the queries and schema in backend/db/. Once you modify them, use sqlc generate to generate the corresponding go code. You will need to install sqlc to do so.
Also, we recommend using the mysql docker container to run the database locally
To run the tests, make sure the backend is running, and then run the commands:
cd backend
go test ./tests
Sometimes the database can get messed up, in that case you can one of run the following commands:
# Spin down the backend and remove the database volume at the same time
docker compose down -v
# Remove the database volume
docker volume rm ctfcollab_db-data
- Go to the website domain
- Choose Log In
- Provide:
- Username
- Password
- Navigate to the Landing Page
- Enter a valid Join Phrase provided by an Admin
- If joining as a guest, select a nickname
- Get to taking notes!
- Join new events through the landing page by inputing a phrase provided by the Admin
- View CTF info: name, description, flag
- Open a challenge to write or edit shared notes
- Supports Markdown formatting
- Collaboration is real-time and team-wide
- Go to Admin Panel → Create CTF
- Fill in:
- Name, Description
- Start/End Time
- Description
- Navigate to your CTF
- Click Add Challenge
- Input:
- Name
- Description
- Share the Join Phrase
- Recommend users pick unique nicknames
- Provide a quick tour:
- Landing Page → CTF Page → Notes
- Use admin token to create first account
- Set up your CTFs in the Admin Panel
- Share join phrases with users or teams
| Issue | Solution |
|---|---|
| Invalid Join Phrase | Double-check spelling or confirm with event organizer |
| Nickname already taken | Choose a different nickname unique to the current CTF |
| Page won't load | Check your internet connection, refresh, or clear your browser cache |
| Can't add notes or challenges | Ensure you’re logged in and have appropriate permissions |
| 500 Internal Server Error | Check console logs (if self-hosted) or contact Admin |
Yes, guests can join using a nickname and the join phrase.
Admins are set manually or by using a special token during registration.
Yes, as long as the CTF is still active and your nickname hasn't been taken.
The quickest way to access Swagger API documentation is running the backend only.
docker compose -f compose.backend_only.yaml up --buildThen, navigate to http://localhost:1337/swagger/index.html#/ in your browser
The database schema can be viewed in the file backend/db/migrations/1_init_schema.up.sql
- Initial project creation
- Schema, UI plans, backend plans
- Create basic codebase
- Dockerized deployment
- Public GitHub repository
- User authentication improvements
- Enhanced permissions and role management
- Improved UI/UX and responsiveness
- Admin panel
- Real time document editing
- Real-time updates to UI
- Additional UI improvement & mist features
- Guest accounts for joining CTFs quickly
- Website UI to view CTFs and challenges
- Join CTFs with code
- Real time document editing
- Real time CTF listing updates
- Admin panel for managing CTFs
- Guest account access
- Admin accounts, regular accounts
- Swagger API documentation
- Database migrations
- Backend test suite
- Further UI improvements (new features & visual enhancements)
- Scalability improvements for large events
- Ongoing maintenance and support
- More test cases for backend
- End to end tests for frontend
Title:
A clear and concise title describing the issue or feature request.
Description:
Describe the bug, enhancement, or question. Include relevant details and context.
Steps to Reproduce (for bugs):
1.
2.
3.
Expected Behavior:
What did you expect to happen?
Actual Behavior:
What actually happened?
Screenshots/Logs:
If applicable, add screenshots or logs to help explain your problem.
Environment:
- OS:
- Browser (if frontend):
- Go version (if backend):
- MySQL version:
Additional Context:
Any other information or context.
- Fork the repository and create a new branch for your changes.
- For backend changes, use Go and follow existing code style. Run
go fmtbefore submitting. - For frontend changes, use Svelte and keep components modular.
- For database changes, update migration files in
backend/db/migrations/. - Test your changes locally before opening a pull request.
- If applicable, write tests for your feature
- Write clear commit messages and describe your changes in the PR.
- Be respectful and constructive in code reviews and discussions.
- If unsure, open an issue to discuss your idea before starting work.
We opted for a simple architecture for our project.
