Skip to main content

Tool for creating and running Capture The Flag competitions

Project description


ctfcli is a tool to manage Capture The Flag events and challenges.

ctfcli provides challenge specifications and templates to make it easier to generate challenges of different categories. It also provides an integration with the CTFd REST API to allow for command line uploading of challenges and integration with CI/CD build systems.

ctfcli features tab completion, a REPL interface (thanks to Python-Fire) and plugin support for custom commands.

WIP: ctfcli is an alpha project and changes will happen. Be sure to pin versions and read the CHANGELOG when updating.

Installation and Usage

ctfcli can be installed with pip install ctfcli

1. Create an Event

ctfcli turns the current folder into a CTF event git repo. It asks for the base url of the CTFd instance you're working with and an access token.

❯ ctf init
Please enter CTFd instance URL:
Please enter CTFd Admin Access Token: d41d8cd98f00b204e9800998ecf8427e
Do you want to continue with and d41d8cd98f00b204e9800998ecf8427e [y/N]: y
Initialized empty Git repository in /Users/user/Downloads/event/.git/

This will create the .ctf folder with the config file that will specify the URL, access token, and keep a record of all the challenges dedicated for this event.

2. Add challenges

Events are made up of challenges. Challenges can be made from a subdirectory or pulled from another repository. Remote challenges are pulled into the event repo and a reference is kept in the .ctf/config file.

❯ ctf challenge add [REPO | FOLDER]
❯ ctf challenge add crypto/stuff
❯ ctf challenge add
Cloning into 'challenge'...
remote: Enumerating objects: 624, done.
remote: Counting objects: 100% (624/624), done.
remote: Compressing objects: 100% (540/540), done.
remote: Total 624 (delta 109), reused 335 (delta 45), pack-reused 0
Receiving objects: 100% (624/624), 6.49 MiB | 21.31 MiB/s, done.
Resolving deltas: 100% (109/109), done.

3. Install challenges

Installing a challenge will automatically create the challenge in your CTFd instance using the API.

❯ ctf challenge install [challenge.yml | DIRECTORY]
❯ ctf challenge install buffer_overflow
Found buffer_overflow/challenge.yml
Loaded buffer_overflow
Installing buffer_overflow

4. Update challenges

Syncing a challenge will automatically update the challenge in your CTFd instance using the API. Any changes made in the challenge.yml file will be reflected in your instance.

❯ ctf challenge sync [challenge.yml | DIRECTORY]
❯ ctf challenge sync buffer_overflow
Found buffer_overflow/challenge.yml
Loaded buffer_overflow
Syncing buffer_overflow

Challenge Templates

ctfcli contains pre-made challenge templates to make it faster to create CTF challenges with safe defaults.

ctf challenge new
                ├── binary
                ├── crypto
                ├── programming
                └── web
❯ ctf challenge new binary
name [Hello]: buffer_overflow

❯ ls -1 buffer_overflow

Contributions welcome on improving the challenge templates to make CTF challenges better for everyone!

Challenge Specification

ctfcli provides a challenge specification (challenge.yml) that outlines the major details of a challenge.

Every challenge generated by or processed by ctfcli should have a challenge.yml file.

The specification format has already been tested and used with CTFd in production events but comments, suggestions, and PRs are welcome on the format of challenge.yml.


ctfcli plugins are essentially additions to to the command line interface via dynamic class modifications. See the plugin documentation page for a simple example.

ctfcli is an alpha project! The plugin interface is likely to change!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ctfcli-0.0.11.tar.gz (29.3 kB view hashes)

Uploaded source

Built Distribution

ctfcli-0.0.11-py3-none-any.whl (50.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page