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.

🚀 Features

- 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

📋 Installation

``bash


Global installation (recommended)

npm install -g flagtrack

Verify installation

flagtrack --version
`

🧩 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 --help` | Show help for a specific command |

🔐 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.