| Name | ctfcli JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | ctfcli is a tool to manage Capture The Flag events and challenges |
| upload_time | 2024-08-20 22:39:40 |
| maintainer | None |
| docs_url | None |
| author | Kevin Chung |
| requires_python | <4.0,>=3.8 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ctfcli
*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](https://github.com/CTFd/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](https://github.com/google/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 [`pipx`](https://github.com/pypa/pipx) as an executable command:
`pipx install ctfcli`
Alternatively, you can always install it with `pip` as a python module:
`pip install ctfcli`
To install the development version of ctfcli directly from the repository you can use:
`pip install git+https://github.com/CTFd/ctfcli.git`
## 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: https://demo.ctfd.io
Please enter CTFd Admin Access Token: d41d8cd98f00b204e9800998ecf8427e
Do you want to continue with https://demo.ctfd.io 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.
GIT-enabled challenges are pulled into the event repo, and a reference is kept in the `.ctf/config` file.
```
❯ ctf challenge add [REPO | FOLDER]
```
##### Local folder:
```
❯ ctf challenge add crypto/stuff
```
##### GIT repository:
```
❯ ctf challenge add https://github.com/challenge.git
Cloning into 'challenge'...
[...]
```
##### GIT repository to a specific subfolder:
```
❯ ctf challenge add https://github.com/challenge.git crypto
Cloning into 'crypto/challenge'...
[...]
```
## 3. Install challenges
Installing a challenge will create the challenge in your CTFd instance using the API.
```
❯ ctf challenge install [challenge]
```
```
❯ ctf challenge install buffer_overflow
Found buffer_overflow/challenge.yml
Loaded buffer_overflow
Installing buffer_overflow
Success!
```
## 4. Sync challenges
Syncing a challenge will 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]
```
```
❯ ctf challenge sync buffer_overflow
Found buffer_overflow/challenge.yml
Loaded buffer_overflow
Syncing buffer_overflow
Success!
```
## 5. Deploy services
Deploying a challenge will automatically create the challenge service (by default in your CTFd instance).
You can also use a different deployment handler to deploy the service via SSH to your own server,
or a separate docker registry.
The challenge will also be automatically installed or synced.
Obtained connection info will be added to your `challenge.yml` file.
```
❯ ctf challenge deploy [challenge]
```
```
❯ ctf challenge deploy web-1
Deploying challenge service 'web-1' (web-1/challenge.yml) with CloudDeploymentHandler ...
Challenge service deployed at: https://web-1-example-instance.chals.io
Updating challenge 'web-1'
Success!
```
## 6. Verify challenges
Verifying a challenge will check if the local version of the challenge is the same as one installed in your CTFd instance.
```
❯ ctf challenge verify [challenge]
```
```
❯ ctf challenge verify buffer_overflow
Verifying challenges [------------------------------------] 0%
Verifying challenges [####################################] 100%
Success! All challenges verified!
Challenges in sync:
- buffer_overflow
```
## 7. Mirror changes
Mirroring a challenge is the reverse operation to syncing.
It will update the local version of the challenge with details of the one installed in your CTFd instance.
It will also issue a warning if you have any remote challenges that are not tracked locally.
```
❯ ctf challenge mirror [challenge]
```
```
❯ ctf challenge verify buffer_overflow
Mirorring challenges [------------------------------------] 0%
Mirorring challenges [####################################] 100%
Success! All challenges mirrored!
```
## Operations on all challenges
You can perform operations on all challenges defined in your config by simply skipping the challenge parameter.
- `ctf challenge install`
- `ctf challenge sync`
- `ctf challenge deploy`
- `ctf challenge verify`
- `ctf challenge mirror`
# 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
/Users/user/.virtualenvs/ctfcli/lib/python3.7/site-packages/ctfcli-0.0.1-py3.7.egg/ctfcli/templates/binary/default
name [Hello]: buffer_overflow
❯ ls -1 buffer_overflow
Makefile
README.md
WRITEUP.md
challenge.yml
dist/
src/
```
**Contributions welcome on improving the challenge templates to make CTF challenges better for everyone!**
# Challenge Specification
`ctfcli` provides a [challenge specification](ctfcli/spec/challenge-example.yml) (`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`.
# Plugins
`ctfcli` plugins are essentially additions to the command line interface via dynamic class modifications. See the [plugin documentation page](docs/plugins.md) for a simple example.
*`ctfcli` is an alpha project! The plugin interface is likely to change!*
# Sub-Repos as alternative to Sub-Trees
`ctfcli` manages git-based challenges by using the built-in git `subtree` mechanism. While it works most of the time, it's been proven to have disadvantages and tends to create problems and merge conflicts.
As an alternative, we're currently experimenting with the git [`git subrepo`](https://github.com/ingydotnet/git-subrepo) extension.
This functionality can be enabled by adding a `use_subrepo = True` property to the `[config]` section inside a ctfcli project config.
Subrepo has to be installed separately, and is not backwards compatible with the default `subtree`.
Once challenges have been added by using either method, they will not work properly if you change it, and you will have to add the challenges again.
Raw data
{
"_id": null,
"home_page": null,
"name": "ctfcli",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Kevin Chung",
"author_email": "kchung@ctfd.io",
"download_url": "https://files.pythonhosted.org/packages/79/df/a421d3e0e0260501f94328433d76af8efff58a3813c40a13d963e07670a1/ctfcli-0.1.3.tar.gz",
"platform": null,
"description": "# ctfcli\n\n*ctfcli is a tool to manage Capture The Flag events and challenges.*\n\n`ctfcli` provides challenge specifications and templates to make it easier to generate challenges of different categories. It also provides an integration with the [CTFd](https://github.com/CTFd/CTFd/) REST API to allow for command line uploading of challenges and integration with CI/CD build systems.\n\n`ctfcli` features tab completion, a REPL interface (thanks to [Python-Fire](https://github.com/google/python-fire)) and plugin support for custom commands.\n\n*WIP: ctfcli is an alpha project and changes will happen. Be sure to pin versions and read the CHANGELOG when updating.*\n\n# Installation and Usage\n\nctfcli can be installed with [`pipx`](https://github.com/pypa/pipx) as an executable command:\n\n`pipx install ctfcli`\n\nAlternatively, you can always install it with `pip` as a python module:\n\n`pip install ctfcli`\n\nTo install the development version of ctfcli directly from the repository you can use:\n\n`pip install git+https://github.com/CTFd/ctfcli.git`\n\n## 1. Create an Event\n\nCtfcli turns the current folder into a CTF event git repo. \nIt asks for the base url of the CTFd instance you're working with and an access token.\n\n```\n\u276f ctf init\nPlease enter CTFd instance URL: https://demo.ctfd.io\nPlease enter CTFd Admin Access Token: d41d8cd98f00b204e9800998ecf8427e\nDo you want to continue with https://demo.ctfd.io and d41d8cd98f00b204e9800998ecf8427e [Y/n]: y\nInitialized empty Git repository in /Users/user/Downloads/event/.git/\n```\n\nThis will create the `.ctf` folder with the `config` file that will specify the URL, access token, and keep a record of\nall the challenges dedicated for this event.\n\n## 2. Add challenges\n\nEvents are made up of challenges.\nChallenges can be made from a subdirectory or pulled from another repository.\nGIT-enabled challenges are pulled into the event repo, and a reference is kept in the `.ctf/config` file.\n\n```\n\u276f ctf challenge add [REPO | FOLDER]\n```\n\n##### Local folder:\n```\n\u276f ctf challenge add crypto/stuff\n```\n\n##### GIT repository:\n```\n\u276f ctf challenge add https://github.com/challenge.git\nCloning into 'challenge'...\n[...]\n```\n\n##### GIT repository to a specific subfolder:\n```\n\u276f ctf challenge add https://github.com/challenge.git crypto\nCloning into 'crypto/challenge'...\n[...]\n```\n\n## 3. Install challenges\n\nInstalling a challenge will create the challenge in your CTFd instance using the API.\n\n```\n\u276f ctf challenge install [challenge]\n```\n\n```\n\u276f ctf challenge install buffer_overflow\nFound buffer_overflow/challenge.yml\nLoaded buffer_overflow\nInstalling buffer_overflow\nSuccess!\n```\n\n## 4. Sync challenges\n\nSyncing a challenge will update the challenge in your CTFd instance using the API. \nAny changes made in the `challenge.yml` file will be reflected in your instance.\n\n```\n\u276f ctf challenge sync [challenge]\n```\n\n```\n\u276f ctf challenge sync buffer_overflow\nFound buffer_overflow/challenge.yml\nLoaded buffer_overflow\nSyncing buffer_overflow\nSuccess!\n```\n\n## 5. Deploy services\n\nDeploying a challenge will automatically create the challenge service (by default in your CTFd instance).\nYou can also use a different deployment handler to deploy the service via SSH to your own server, \nor a separate docker registry.\n\nThe challenge will also be automatically installed or synced.\nObtained connection info will be added to your `challenge.yml` file.\n```\n\u276f ctf challenge deploy [challenge]\n```\n\n```\n\u276f ctf challenge deploy web-1\nDeploying challenge service 'web-1' (web-1/challenge.yml) with CloudDeploymentHandler ...\nChallenge service deployed at: https://web-1-example-instance.chals.io\nUpdating challenge 'web-1'\nSuccess!\n```\n\n## 6. Verify challenges\n\nVerifying a challenge will check if the local version of the challenge is the same as one installed in your CTFd instance.\n\n```\n\u276f ctf challenge verify [challenge]\n```\n\n```\n\u276f ctf challenge verify buffer_overflow\nVerifying challenges [------------------------------------] 0%\nVerifying challenges [####################################] 100%\nSuccess! All challenges verified!\nChallenges in sync:\n - buffer_overflow\n```\n\n## 7. Mirror changes\n\nMirroring a challenge is the reverse operation to syncing.\nIt will update the local version of the challenge with details of the one installed in your CTFd instance.\nIt will also issue a warning if you have any remote challenges that are not tracked locally.\n\n```\n\u276f ctf challenge mirror [challenge]\n```\n\n```\n\u276f ctf challenge verify buffer_overflow\nMirorring challenges [------------------------------------] 0%\nMirorring challenges [####################################] 100%\nSuccess! All challenges mirrored!\n```\n\n## Operations on all challenges\n\nYou can perform operations on all challenges defined in your config by simply skipping the challenge parameter.\n\n- `ctf challenge install`\n- `ctf challenge sync`\n- `ctf challenge deploy`\n- `ctf challenge verify`\n- `ctf challenge mirror`\n\n# Challenge Templates\n\n`ctfcli` contains pre-made challenge templates to make it faster to create CTF challenges with safe defaults.\n\n```\nctf challenge new\n \u251c\u2500\u2500 binary\n \u251c\u2500\u2500 crypto\n \u251c\u2500\u2500 programming\n \u2514\u2500\u2500 web\n```\n\n```\n\u276f ctf challenge new binary\n/Users/user/.virtualenvs/ctfcli/lib/python3.7/site-packages/ctfcli-0.0.1-py3.7.egg/ctfcli/templates/binary/default\nname [Hello]: buffer_overflow\n\n\u276f ls -1 buffer_overflow\nMakefile\nREADME.md\nWRITEUP.md\nchallenge.yml\ndist/\nsrc/\n```\n\n**Contributions welcome on improving the challenge templates to make CTF challenges better for everyone!**\n\n# Challenge Specification\n\n`ctfcli` provides a [challenge specification](ctfcli/spec/challenge-example.yml) (`challenge.yml`) that outlines the major details of a challenge.\n\nEvery challenge generated by or processed by `ctfcli` should have a `challenge.yml` file.\n\nThe 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`.\n\n# Plugins\n\n`ctfcli` plugins are essentially additions to the command line interface via dynamic class modifications. See the [plugin documentation page](docs/plugins.md) for a simple example.\n\n*`ctfcli` is an alpha project! The plugin interface is likely to change!*\n\n# Sub-Repos as alternative to Sub-Trees\n\n`ctfcli` manages git-based challenges by using the built-in git `subtree` mechanism. While it works most of the time, it's been proven to have disadvantages and tends to create problems and merge conflicts. \n\nAs an alternative, we're currently experimenting with the git [`git subrepo`](https://github.com/ingydotnet/git-subrepo) extension. \nThis functionality can be enabled by adding a `use_subrepo = True` property to the `[config]` section inside a ctfcli project config.\n\nSubrepo has to be installed separately, and is not backwards compatible with the default `subtree`. \nOnce challenges have been added by using either method, they will not work properly if you change it, and you will have to add the challenges again.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "ctfcli is a tool to manage Capture The Flag events and challenges",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7566e7753aeb970606b1434c63353e805b010cf335d68f5105cef940d8397e3",
"md5": "08e4e231361da09d33edab046e9a49f9",
"sha256": "4b338bdf471ae9c43d14266c2a88be20280775ff673b7268db1573a373b7347b"
},
"downloads": -1,
"filename": "ctfcli-0.1.3-cp311-cp311-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "08e4e231361da09d33edab046e9a49f9",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": "<4.0,>=3.8",
"size": 72460,
"upload_time": "2024-08-20T22:39:38",
"upload_time_iso_8601": "2024-08-20T22:39:38.975681Z",
"url": "https://files.pythonhosted.org/packages/a7/56/6e7753aeb970606b1434c63353e805b010cf335d68f5105cef940d8397e3/ctfcli-0.1.3-cp311-cp311-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79dfa421d3e0e0260501f94328433d76af8efff58a3813c40a13d963e07670a1",
"md5": "ed8063e0069063970d7888900808675a",
"sha256": "f1d775ffcc170a6159c065280dd0499e371d74d7bde5b169b9ff3ef69c2997f4"
},
"downloads": -1,
"filename": "ctfcli-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ed8063e0069063970d7888900808675a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 45839,
"upload_time": "2024-08-20T22:39:40",
"upload_time_iso_8601": "2024-08-20T22:39:40.604212Z",
"url": "https://files.pythonhosted.org/packages/79/df/a421d3e0e0260501f94328433d76af8efff58a3813c40a13d963e07670a1/ctfcli-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 22:39:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ctfcli"
}
