# CTF Terminal 🚩
**ctf-term** - A production-ready, cross-platform terminal CTF engine with both CLI and TUI interfaces. Features local SQLite storage, importable challenge packs (YAML), salted-hash flag verification, hint penalties, and live leaderboards.
**Created by:** [Sherin Joseph Roy](https://sherinjosephroy.link) • Co-Founder & Head of Products at [DeepMost AI](https://deepmost.ai)
## Features
- 🎯 **Clean CLI** with all essential CTF commands
- 🖥️ **Beautiful TUI** built with Textual for keyboard-first navigation
- 🔒 **Secure** flag verification using SHA256 salted hashes
- 📦 **Pack System** - import challenges from YAML files
- 🏆 **Advanced Leaderboard** with hint penalties and first blood bonuses
- 🩸 **First Blood** - 10% bonus points for being the first solver
- 💾 **Local Storage** - SQLite database with proper indexes
- 🎨 **Rich Output** - beautiful terminal tables and formatting
- 🌗 **Themes** - dark and light modes (TUI)
- ⚡ **Fast** - optimized for low-end machines
- 🧪 **Tested** - comprehensive test suite
- 📊 **Challenge Stats** - tracking solves, hints, and performance
## Quick Start
### Installation
```bash
pipx install ctf-term
```
Or from source:
```bash
git clone <repo>
cd ctf-term
pipx install .
```
### CLI Usage
```bash
# Initialize the app
ctf init
# Import a challenge pack
ctf import-pack ~/.ctf/packs/sample.yml
# List challenges
ctf list
ctf list --category crypto
# Show challenge details
ctf show rot13-hello
# Get a hint (view-only, no penalty yet)
ctf hint alice rot13-hello
# Submit a flag
ctf submit alice rot13-hello flag{flap}
# View leaderboard
ctf scoreboard
# Generate flag hash for pack authors
ctf make-flag-hash "flag{example}" "salt"
```
### TUI Usage
```bash
# Launch the interactive TUI
ctf tui
```
**Keyboard Shortcuts:**
- `?` / `F1` - Help
- `/` - Search challenges
- `c` - Filter by category
- `u` - Switch/create user
- `Enter` - Open challenge
- `s` - Submit flag
- `h` - Show hint
- `g` - Go to scoreboard
- `t` - Toggle theme
- `Esc` - Go back / Close dialogs
- `q` - Quit
## Pack Authoring
### YAML Schema
```yaml
pack: My CTF Pack
version: 1
challenges:
- id: unique-challenge-id
title: Challenge Title
category: crypto # crypto, pwn, web, forensics, misc
description: |
This is the challenge description.
Can be multi-line markdown.
points: 100
salt: "unique-salt-per-challenge"
flag_hash: "sha256(salt:flag)"
hint: "Optional hint text"
hint_penalty: 20
```
### Creating Flag Hashes
```bash
# Method 1: Use the CLI tool
ctf make-flag-hash "flag{my_flag}" "my_salt"
# Method 2: Manual calculation
python3 -c "import hashlib; print(hashlib.sha256(b'my_salt:flag{my_flag}').hexdigest())"
```
### Development Mode
For local testing, you can use `flag_plain` which will be automatically hashed:
```yaml
challenges:
- id: test-challenge
title: Test Challenge
category: misc
description: "Test description"
points: 50
salt: "s1"
flag_plain: "flag{test}" # Dev only - never commit this!
hint: "This is a hint"
hint_penalty: 10
```
**⚠️ Warning:** Never commit packs with `flag_plain` to version control!
## Project Structure
```
ctf-term/
├── src/ctfterm/
│ ├── __init__.py
│ ├── cli.py # CLI commands
│ ├── db.py # Database operations
│ ├── model.py # Data models
│ ├── packs.py # Pack import/export
│ ├── security.py # Flag verification
│ ├── paths.py # Path resolution
│ ├── settings.py # Settings management
│ ├── __main__.py # Python module entrypoint
│ ├── tui/ # TUI implementation
│ │ ├── app.py
│ │ ├── router.py
│ │ ├── styles.tcss
│ │ ├── views/
│ │ └── widgets/
│ └── services/ # Business logic
│ ├── challenges.py
│ ├── users.py
│ ├── scoreboard.py
│ └── flags.py
├── tests/ # Test suite
├── examples/ # Sample packs
└── pyproject.toml
```
## Security
- Flags are never stored in plaintext
- Verification uses `SHA256(salt:flag)` only
- Database stores `salt` and `flag_hash`
- No network calls - completely offline
- No dynamic code execution
## Development
### Setup
```bash
git clone <repo>
cd ctf-term
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
pytest --cov=src/ctfterm --cov-report=html
```
### Code Formatting
```bash
ruff check src/ tests/
black src/ tests/
```
## Author & Credits
### Sherin Joseph Roy
**Co-Founder & Head of Products** at [DeepMost AI](https://deepmost.ai)
Sherin is an AI entrepreneur and product leader specializing in enterprise AI systems that connect data, automation, and intelligence. With expertise in scalable, human-centered AI solutions, he focuses on bridging research and application to solve real-world challenges.
#### Connect & Learn More
- 🌐 **Portfolio**: [sherinjosephroy.link](https://sherinjosephroy.link)
- 💼 **LinkedIn**: [linkedin.com/in/sherin-roy-deepmost](https://www.linkedin.com/in/sherin-roy-deepmost)
- 🐦 **X (Twitter)**: [@SherinSEF](https://x.com/SherinSEF)
- 🐘 **Mastodon**: [@sherinjoesphroy](https://mastodon.social/@sherinjoesphroy)
- 💻 **GitHub**: [github.com/Sherin-SEF-AI](https://github.com/Sherin-SEF-AI)
- 📧 **Contact**: [sherinjosephroy.link/contact](https://sherinjosephroy.link/contact)
#### About DeepMost AI
DeepMost AI builds enterprise AI systems that help organizations think, decide, and grow through intelligent automation and data-driven solutions.
## License
MIT License - see LICENSE file
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request
## Acknowledgments
Built with:
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Terminal formatting
- [Textual](https://textual.textualize.io/) - TUI framework
- [PyYAML](https://pyyaml.org/) - YAML parsing
Raw data
{
"_id": null,
"home_page": null,
"name": "ctf-term",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Sherin Joseph Roy <contact@sherinjosephroy.link>",
"keywords": "capture-the-flag, challenges, cli, ctf, cybersecurity, flags, hacking, leaderboard, pentesting, python, scoreboard, security-training, terminal, textual, tui, typer",
"author": null,
"author_email": "Sherin Joseph Roy <contact@sherinjosephroy.link>",
"download_url": "https://files.pythonhosted.org/packages/f9/6f/1e58029e14756d49fde3009e83cacff5a9eb024582619af8709b0369e216/ctf_term-0.1.0.tar.gz",
"platform": null,
"description": "# CTF Terminal \ud83d\udea9\n\n**ctf-term** - A production-ready, cross-platform terminal CTF engine with both CLI and TUI interfaces. Features local SQLite storage, importable challenge packs (YAML), salted-hash flag verification, hint penalties, and live leaderboards.\n\n**Created by:** [Sherin Joseph Roy](https://sherinjosephroy.link) \u2022 Co-Founder & Head of Products at [DeepMost AI](https://deepmost.ai)\n\n## Features\n\n- \ud83c\udfaf **Clean CLI** with all essential CTF commands\n- \ud83d\udda5\ufe0f **Beautiful TUI** built with Textual for keyboard-first navigation\n- \ud83d\udd12 **Secure** flag verification using SHA256 salted hashes\n- \ud83d\udce6 **Pack System** - import challenges from YAML files\n- \ud83c\udfc6 **Advanced Leaderboard** with hint penalties and first blood bonuses\n- \ud83e\ude78 **First Blood** - 10% bonus points for being the first solver\n- \ud83d\udcbe **Local Storage** - SQLite database with proper indexes\n- \ud83c\udfa8 **Rich Output** - beautiful terminal tables and formatting\n- \ud83c\udf17 **Themes** - dark and light modes (TUI)\n- \u26a1 **Fast** - optimized for low-end machines\n- \ud83e\uddea **Tested** - comprehensive test suite\n- \ud83d\udcca **Challenge Stats** - tracking solves, hints, and performance\n\n## Quick Start\n\n### Installation\n\n```bash\npipx install ctf-term\n```\n\nOr from source:\n\n```bash\ngit clone <repo>\ncd ctf-term\npipx install .\n```\n\n### CLI Usage\n\n```bash\n# Initialize the app\nctf init\n\n# Import a challenge pack\nctf import-pack ~/.ctf/packs/sample.yml\n\n# List challenges\nctf list\nctf list --category crypto\n\n# Show challenge details\nctf show rot13-hello\n\n# Get a hint (view-only, no penalty yet)\nctf hint alice rot13-hello\n\n# Submit a flag\nctf submit alice rot13-hello flag{flap}\n\n# View leaderboard\nctf scoreboard\n\n# Generate flag hash for pack authors\nctf make-flag-hash \"flag{example}\" \"salt\"\n```\n\n### TUI Usage\n\n```bash\n# Launch the interactive TUI\nctf tui\n```\n\n**Keyboard Shortcuts:**\n- `?` / `F1` - Help\n- `/` - Search challenges\n- `c` - Filter by category\n- `u` - Switch/create user\n- `Enter` - Open challenge\n- `s` - Submit flag\n- `h` - Show hint\n- `g` - Go to scoreboard\n- `t` - Toggle theme\n- `Esc` - Go back / Close dialogs\n- `q` - Quit\n\n## Pack Authoring\n\n### YAML Schema\n\n```yaml\npack: My CTF Pack\nversion: 1\nchallenges:\n - id: unique-challenge-id\n title: Challenge Title\n category: crypto # crypto, pwn, web, forensics, misc\n description: |\n This is the challenge description.\n Can be multi-line markdown.\n points: 100\n salt: \"unique-salt-per-challenge\"\n flag_hash: \"sha256(salt:flag)\"\n hint: \"Optional hint text\"\n hint_penalty: 20\n```\n\n### Creating Flag Hashes\n\n```bash\n# Method 1: Use the CLI tool\nctf make-flag-hash \"flag{my_flag}\" \"my_salt\"\n\n# Method 2: Manual calculation\npython3 -c \"import hashlib; print(hashlib.sha256(b'my_salt:flag{my_flag}').hexdigest())\"\n```\n\n### Development Mode\n\nFor local testing, you can use `flag_plain` which will be automatically hashed:\n\n```yaml\nchallenges:\n - id: test-challenge\n title: Test Challenge\n category: misc\n description: \"Test description\"\n points: 50\n salt: \"s1\"\n flag_plain: \"flag{test}\" # Dev only - never commit this!\n hint: \"This is a hint\"\n hint_penalty: 10\n```\n\n**\u26a0\ufe0f Warning:** Never commit packs with `flag_plain` to version control!\n\n## Project Structure\n\n```\nctf-term/\n\u251c\u2500\u2500 src/ctfterm/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # CLI commands\n\u2502 \u251c\u2500\u2500 db.py # Database operations\n\u2502 \u251c\u2500\u2500 model.py # Data models\n\u2502 \u251c\u2500\u2500 packs.py # Pack import/export\n\u2502 \u251c\u2500\u2500 security.py # Flag verification\n\u2502 \u251c\u2500\u2500 paths.py # Path resolution\n\u2502 \u251c\u2500\u2500 settings.py # Settings management\n\u2502 \u251c\u2500\u2500 __main__.py # Python module entrypoint\n\u2502 \u251c\u2500\u2500 tui/ # TUI implementation\n\u2502 \u2502 \u251c\u2500\u2500 app.py\n\u2502 \u2502 \u251c\u2500\u2500 router.py\n\u2502 \u2502 \u251c\u2500\u2500 styles.tcss\n\u2502 \u2502 \u251c\u2500\u2500 views/\n\u2502 \u2502 \u2514\u2500\u2500 widgets/\n\u2502 \u2514\u2500\u2500 services/ # Business logic\n\u2502 \u251c\u2500\u2500 challenges.py\n\u2502 \u251c\u2500\u2500 users.py\n\u2502 \u251c\u2500\u2500 scoreboard.py\n\u2502 \u2514\u2500\u2500 flags.py\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Sample packs\n\u2514\u2500\u2500 pyproject.toml\n```\n\n## Security\n\n- Flags are never stored in plaintext\n- Verification uses `SHA256(salt:flag)` only\n- Database stores `salt` and `flag_hash`\n- No network calls - completely offline\n- No dynamic code execution\n\n## Development\n\n### Setup\n\n```bash\ngit clone <repo>\ncd ctf-term\npython -m venv venv\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=src/ctfterm --cov-report=html\n```\n\n### Code Formatting\n\n```bash\nruff check src/ tests/\nblack src/ tests/\n```\n\n## Author & Credits\n\n### Sherin Joseph Roy\n**Co-Founder & Head of Products** at [DeepMost AI](https://deepmost.ai)\n\nSherin is an AI entrepreneur and product leader specializing in enterprise AI systems that connect data, automation, and intelligence. With expertise in scalable, human-centered AI solutions, he focuses on bridging research and application to solve real-world challenges.\n\n#### Connect & Learn More\n- \ud83c\udf10 **Portfolio**: [sherinjosephroy.link](https://sherinjosephroy.link)\n- \ud83d\udcbc **LinkedIn**: [linkedin.com/in/sherin-roy-deepmost](https://www.linkedin.com/in/sherin-roy-deepmost)\n- \ud83d\udc26 **X (Twitter)**: [@SherinSEF](https://x.com/SherinSEF)\n- \ud83d\udc18 **Mastodon**: [@sherinjoesphroy](https://mastodon.social/@sherinjoesphroy)\n- \ud83d\udcbb **GitHub**: [github.com/Sherin-SEF-AI](https://github.com/Sherin-SEF-AI)\n- \ud83d\udce7 **Contact**: [sherinjosephroy.link/contact](https://sherinjosephroy.link/contact)\n\n#### About DeepMost AI\nDeepMost AI builds enterprise AI systems that help organizations think, decide, and grow through intelligent automation and data-driven solutions.\n\n## License\n\nMIT License - see LICENSE file\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new features\n4. Ensure all tests pass\n5. Submit a pull request\n\n## Acknowledgments\n\nBuilt with:\n- [Typer](https://typer.tiangolo.com/) - CLI framework\n- [Rich](https://rich.readthedocs.io/) - Terminal formatting\n- [Textual](https://textual.textualize.io/) - TUI framework\n- [PyYAML](https://pyyaml.org/) - YAML parsing\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A terminal-based CTF (Capture The Flag) engine with CLI and TUI interfaces for cybersecurity training",
"version": "0.1.0",
"project_urls": {
"Author": "https://sherinjosephroy.link",
"Company": "https://deepmost.ai",
"Documentation": "https://github.com/Sherin-SEF-AI/ctf-term/blob/main/README.md",
"Homepage": "https://github.com/Sherin-SEF-AI/ctf-term",
"Issues": "https://github.com/Sherin-SEF-AI/ctf-term/issues",
"Repository": "https://github.com/Sherin-SEF-AI/ctf-term"
},
"split_keywords": [
"capture-the-flag",
" challenges",
" cli",
" ctf",
" cybersecurity",
" flags",
" hacking",
" leaderboard",
" pentesting",
" python",
" scoreboard",
" security-training",
" terminal",
" textual",
" tui",
" typer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "609fb84cdaaf1bdcb7639d8daad74178095e7ddc22ea867f9e658927329dc6a1",
"md5": "8faccdd77f285e897f23d508d87df81a",
"sha256": "74bd219cda0259055b06c475b699bde8f4c7a97e133ef56b6510b7d08a7eb405"
},
"downloads": -1,
"filename": "ctf_term-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8faccdd77f285e897f23d508d87df81a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25953,
"upload_time": "2025-10-26T09:56:39",
"upload_time_iso_8601": "2025-10-26T09:56:39.926739Z",
"url": "https://files.pythonhosted.org/packages/60/9f/b84cdaaf1bdcb7639d8daad74178095e7ddc22ea867f9e658927329dc6a1/ctf_term-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f96f1e58029e14756d49fde3009e83cacff5a9eb024582619af8709b0369e216",
"md5": "20702eb1e8b9893c3b45bd67d528b718",
"sha256": "6c5ec40c80fbf620cae53b849c4ba20aa007643e53cb9985d489cb501fe6b7d3"
},
"downloads": -1,
"filename": "ctf_term-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "20702eb1e8b9893c3b45bd67d528b718",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27328,
"upload_time": "2025-10-26T09:56:42",
"upload_time_iso_8601": "2025-10-26T09:56:42.310511Z",
"url": "https://files.pythonhosted.org/packages/f9/6f/1e58029e14756d49fde3009e83cacff5a9eb024582619af8709b0369e216/ctf_term-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 09:56:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sherin-SEF-AI",
"github_project": "ctf-term",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ctf-term"
}
JSON
