CTF Progress Tracker and Task Management Tool
npm install flagtrack> A comprehensive CTF challenge tracking and management tool for teams


flagtrack is a command-line tool that helps CTF teams manage challenges, track progress, and collaborate effectively. It provides a structured approach to organizing writeups, automating Git workflows, and maintaining team progress dashboards.
- Structured Challenge Management: Create and organize challenges by category
- Automatic README Generation: Keep track of team progress with auto-updating dashboards
- Git Integration: Streamlined Git workflows for team collaboration
- Task Completion Tracking: Record flags, points, and solvers for each challenge
- Team Leaderboard: Track individual contributions and generate statistics
- GitHub Actions Support: Automatic README updates when challenges are solved
``bashGlobal installation (recommended)
npm install -g flagtrack
š§© Getting Started
$3
`bash
Initialize a new CTF project
flagtrack setup
`This interactive command will:
- Create configuration for a new CTF competition
- Set up categories for challenges
- Configure GitHub Actions for automatic README updates
- Create the necessary directory structure
$3
`bash
Create a new challenge task
flagtrack create
`This will:
- Create appropriate folders and files for the challenge
- Generate a writeup template
- Create and checkout a Git branch for the task
- Automatically commit and push the branch
$3
`bash
Mark a challenge as complete
flagtrack solve
`Use this command when you've solved a challenge to:
- Record the flag, points, and solver information
- Update the writeup with solution details
- Merge the completed task back to main branch
- Clean up the task branch
$3
`bash
Generate/update the README progress tracker
flagtrack update
`This will:
- Scan all challenge directories
- Compile statistics and completion status
- Generate a comprehensive README with progress information
- Show challenge details, flags, and solvers
$3
`bash
Show team leaderboard and contributor statistics
flagtrack leaderboard
`This will:
- Generate a ranking of all challenge solvers
- Show points and challenges completed by each person
- Identify top categories for each solver
- Offer export options (Markdown or JSON)
š Directory Structure
flagtrack follows a structured approach to organizing CTF challenges:
`
CTF_Name/
āāā 01_Crypto/
ā āāā 01_challenge_name/
ā ā āāā writeup.md # Challenge writeup
ā ā āāā challenge_files/ # Original challenge files
ā ā āāā workspace/ # Playground for experiments and tests
ā ā āāā exploit/ # Final solution files
ā ā āāā screenshots/ # Visual evidence
ā ā āāā notes.txt # Working notes
ā āāā ...
āāā 02_Web/
āāā 03_Pwn/
āāā ...
`š Writeup Format
Each challenge has a
writeup.md file with the following structure:`markdown
š§© Challenge Name
Category: Web
Points: 250
Flag:
flag{example_flag_here}
Solver: Team Member Name---
š Challenge Description
> Original challenge description here...
---
š ļø Steps to solution
Detailed walkthrough of the solution...
---
š§ Notes & Takeaways
Things learned, techniques to remember...
`š¤ Git Workflow
flagtrack implements a streamlined Git workflow:
1. Start a challenge:
flagtrack create creates a branch like web-01-challenge-name
2. Work on solution: Make changes in the task branch
3. Complete challenge: flagtrack solve updates solution, merges to main, and cleans up
4. Track progress: GitHub Actions automatically updates the READMEš GitHub Actions Integration
When properly set up, flagtrack creates a GitHub Actions workflow to automatically update your README whenever writeups are modified. This keeps your progress dashboard current without manual intervention.
š ļø Advanced Usage
$3
The configuration is stored in
.flagtrack/config.yml in your repository:`yaml
ctfName: HackThePlanet 2025
categories:
1: Crypto
2: Web
3: Pwn
4: Forensics
5: Misc
6: Rev
parentDir: null
createdAt: "2025-04-03T12:34:56.789Z"
`$3
You can use flagtrack in your scripts:
`javascript
const flagtrack = require('flagtrack');// Run commands programmatically
flagtrack.commands.updateReadme()
.then(() => console.log('README updated'))
.catch(err => console.error(err));
`š Command Reference
| Command | Description |
|---------|-------------|
|
flagtrack setup | Initialize a new CTF project |
| flagtrack create | Create a new challenge task |
| flagtrack solve | Mark a challenge as completed |
| flagtrack update | Update the README progress tracker |
| flagtrack leaderboard | Generate team contribution statistics |
| flagtrack --help | Show help information |
| flagtrack Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.