CTFx 0.2.2__tar.gz

ctfx-0.2.2/.github/workflows/python-publish.yml

@@ -0,0 +1,62 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm install
+          npm install @rollup/rollup-linux-x64-gnu lightningcss-linux-x64-gnu --no-save
+          npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ctfx/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

ctfx-0.2.2/.gitignore

@@ -0,0 +1,54 @@
+prompt.md
+progress.md
+
+# Python
+__pycache__/
+**/_pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.env
+
+**/package-lock.json
+
+# uv
+.python-version
+uv.lock
+
+# Node / React frontend
+frontend/node_modules/
+frontend/dist/
+frontend/.vite/
+ctfx/server/static/
+
+# Distribution
+*.whl
+*.tar.gz
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+.claude/
+.pytest*

ctfx-0.2.2/Makefile

@@ -0,0 +1,65 @@
+.PHONY: install dev test build clean lint frontend
+
+PYTHON ?= python
+PYTEST_FLAGS ?= -v
+PROTOBUF_ENV = PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python
+
+# ── Install ──────────────────────────────────────────────────────────────────
+
+install:
+	$(PYTHON) -m pip install -e .
+
+install-llm:
+	$(PYTHON) -m pip install -e ".[llm]"
+
+dev:
+	$(PYTHON) -m pip install -e ".[llm]"
+	$(PYTHON) -m pip install pytest pytest-asyncio httpx ruff
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+test:
+	$(PROTOBUF_ENV) $(PYTHON) -m pytest $(PYTEST_FLAGS) tests/
+
+test-quick:
+	$(PROTOBUF_ENV) $(PYTHON) -m pytest -x -q tests/
+
+test-cov:
+	$(PROTOBUF_ENV) $(PYTHON) -m pytest $(PYTEST_FLAGS) --tb=short tests/
+
+# ── Lint ──────────────────────────────────────────────────────────────────────
+
+lint:
+	$(PYTHON) -m ruff check ctfx/ tests/
+
+lint-fix:
+	$(PYTHON) -m ruff check --fix ctfx/ tests/
+
+# ── Frontend ──────────────────────────────────────────────────────────────────
+
+frontend:
+	cd frontend && npm install && npm run build
+
+frontend-dev:
+	cd frontend && npm run dev
+
+# ── Clean ─────────────────────────────────────────────────────────────────────
+
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache __pycache__
+	find ctfx -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
+	find tests -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
+
+# ── Build wheel ───────────────────────────────────────────────────────────────
+
+build: frontend
+	$(PYTHON) -m pip install --upgrade build
+	$(PYTHON) -m build
+
+# ── Quick dev loop ────────────────────────────────────────────────────────────
+
+run-server:
+	ctfx serve
+
+webui:
+	ctfx webui

ctfx-0.2.2/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: CTFx
+Version: 0.2.2
+Summary: Local-first CTF workspace manager and assistant CLI
+Author: Li Yan
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: itsdangerous>=2.1
+Requires-Dist: mcp>=1.0
+Requires-Dist: paramiko>=3.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# CTFx
+
+A local-first CTF workspace manager and assistant CLI for Jeopardy and AWD competitions.
+
+## Background
+
+CTFx started from a bunch of PowerShell scripts I wrote for CTF competitions back in HKCERT 2024.
+
+Later, in the HKCERT 2025 Final, I made a Python-based CTF Assistant for AWD matches. It worked pretty well, got some positive feedback, and helped our team achieve a solid result.
+
+After that, I decided to turn those ideas and experiences into CTFx, hoping it can give CTF players a bit of extra help in the AI era.
+
+## Features
+
+- **Competition management** — create, list, and switch between CTF workspaces
+- **Challenge scaffolding** — auto-generate category-specific solve templates (`pwn`, `crypto`, `forensics`, `rev`, `misc`)
+- **Platform integration** — fetch challenges and submit flags via CTFd API using either team token or platform cookies
+- **Terminal integration** — open shells, WSL, editors, and file explorers at challenge paths
+- **AI context** — generate `prompt.md` with competition context plus CLI/MCP usage notes for LLM-assisted solving
+- **WebUI** — React dashboard with challenge add/delete, editable challenge detail, flags table, and writeup editor
+- **REST API + MCP** — machine-readable interface for Claude Desktop / Cursor integration
+- **AWD mode** — SSH/SCP helpers, exploit runner, patch tracker, host map
+
+## Installation
+
+Requires Python 3.11+.
+
+```sh
+pip install ctfx
+# or with uv (recommended)
+uv tool install CTFx
+```
+
+### Install Guide
+
+Install from PyPI:
+
+```sh
+pip install ctfx
+ctfx --help
+```
+
+Upgrade to the latest release:
+
+```sh
+pip install -U ctfx
+```
+
+Install from a local checkout during development:
+
+```sh
+git clone https://github.com/liyanqwq/CTFx
+cd CTFx
+pip install -e .
+ctfx --help
+```
+
+## Quick Start
+
+```sh
+# First run — initializes ~/.config/ctfx/config.json
+ctfx setup
+
+# Create a competition workspace
+ctfx comp init --name HKCERT_CTF --year 2025 --mode jeopardy --platform ctfd
+
+# Switch to it
+ctfx use HKCERT_CTF_2025
+
+# Add a challenge
+ctfx add baby_pwn pwn
+
+# Open in editor
+ctfx code pwn/baby_pwn
+
+# Open a terminal at the solve directory
+ctfx cli pwn/baby_pwn/solve
+
+# Start the WebUI + API + MCP server
+ctfx serve
+
+# Open WebUI in browser (auto-login)
+ctfx webui
+```
+
+### Typical Flag Workflow
+
+`CTFx` now separates local flag recording from remote submission:
+
+1. Save a discovered flag locally in the WebUI or via API. This moves the challenge to `hoard`.
+2. Review hoarded flags in the `Flags` page.
+3. Submit the flag to the remote platform when ready.
+4. A successful remote submission promotes the challenge to `solved`.
+
+## Notes
+
+- Paths passed to `ctfx cli`, `ctfx code`, `ctfx explorer`, API routes, and MCP tools are restricted to the active competition workspace. Escaping with `..` is rejected.
+- Challenge categories, challenge names, and AWD service names are treated as path components and must not contain `/` or `\\`.
+- If `terminal.python_cmd` contains spaces, quote the executable path normally. Example on Windows: `"C:\Program Files\Python313\python.exe" -u`
+- `ctfx webui` generates a one-time login URL for the local WebUI. API and MCP still use the root token unless you are already authenticated in the browser.
+- For platform-backed competitions, set either `team_token` or `team_cookies` in the competition profile before attempting remote submission.
+- Challenge status flow is `fetched -> seen -> working -> hoard -> solved`.
+
+## CLI Reference
+
+```
+ctfx comp list [query]                  List competitions
+ctfx comp use <name>                    Set active competition
+ctfx comp init                          Create new competition workspace
+ctfx comp info                          Show active competition metadata
+
+ctfx chal list [query] [--cat] [--status]   List challenges
+ctfx chal add <name> [cat]             Add and scaffold a challenge
+ctfx chal rm <name>                    Remove a challenge
+ctfx chal info <name>                  Show challenge detail
+ctfx chal status <name> <status>       Update challenge status
+
+ctfx cli [path]                         Open terminal at path
+ctfx wsl [path] [-- cmd]               Open WSL shell or run command
+ctfx e [path]                          Open file explorer
+ctfx code [path]                       Open editor
+ctfx py [file]                         Run Python in configured environment
+
+ctfx fetch [--cat] [--chal]            Fetch challenges from platform
+ctfx submit <flag> [--chal]            Submit flag to platform
+ctfx import <url>                      LLM-assisted challenge import
+
+ctfx ai [--print]                      Generate AI context prompt.md with CLI/MCP notes
+ctfx mcp [--out PATH]                  Generate MCP client config
+
+ctfx webui / ctfx web / ctfx ui        Open WebUI in browser
+ctfx token update                      Rotate root token
+
+ctfx config show                       Display current configuration
+ctfx config list                       Alias for config show
+ctfx config set <key> <value>          Set a config value (dot-notation)
+
+ctfx serve [--port] [--host]           Start WebUI + API + MCP server
+ctfx setup                             Interactive configuration wizard
+ctfx i                                 Interactive REPL
+```
+
+### Aliases
+| Short | Full |
+|---|---|
+| `ctfx use <comp>` | `ctfx comp use <comp>` |
+| `ctfx init` | `ctfx comp init` |
+| `ctfx add <chal> [cat]` | `ctfx chal add <chal> [cat]` |
+| `ctfx e [path]` | `ctfx explorer [path]` |
+| `ctfx i` | `ctfx interactive` |
+
+## Configuration
+
+Global config lives at `~/.config/ctfx/config.json`. Run `ctfx setup` to configure interactively, or use `ctfx config set` for individual keys.
+
+```sh
+ctfx config show                        # view all settings
+ctfx config set serve.port 9000
+ctfx config set terminal.editor_cmd cursor
+ctfx config set terminal.wsl_distro ubuntu
+ctfx config set basedir ~/ctf
+```
+
+Settable keys: `basedir`, `active_competition`, `serve.host`, `serve.port`, `terminal.cli_cmd`, `terminal.editor_cmd`, `terminal.wsl_distro`, `terminal.python_cmd`, `terminal.explorer_cmd`, `terminal.file_manager_cmd`, `auth.one_time_login_ttl_sec`, `auth.session_ttl_sec`, `auth.webui_cookie_name`
+
+Key fields:
+- `basedir` — root directory for all competition workspaces (default: `~/ctf`)
+- `root_token` — auth secret for REST API, MCP, and WebUI; rotate with `ctfx token update` (not settable via `config set`)
+- `serve.port` — default server port (default: `8694`)
+- `terminal.*` — shell, editor, WSL distro, Python command
+
+Example Windows Python configuration with spaces in the executable path:
+
+```sh
+ctfx config set terminal.python_cmd "\"C:\Program Files\Python313\python.exe\" -u"
+```
+
+## Server & Authentication
+
+```sh
+ctfx serve              # starts on 127.0.0.1:8694 by default
+ctfx webui              # opens browser with auto one-time login
+```
+
+API and MCP endpoints require `Authorization: Bearer <root_token>`.
+
+The WebUI authenticates through a one-time login URL and then uses a secure session cookie for subsequent browser requests.
+
+Changing the active competition through the CLI or API also updates the in-process MCP server state, so MCP tools follow the currently selected competition.
+
+MCP client config for Claude Desktop / Cursor:
+```sh
+ctfx mcp --out mcp.json
+```
+
+The generated MCP URL uses `/mcp/` with a trailing slash.
+
+## Workspace Structure
+
+```
+~/ctf/
+└── HKCERT_CTF_2025/
+    ├── ctf.json
+    ├── prompt.md
+    └── pwn/
+        └── baby_pwn/
+            ├── src/
+            ├── solve/
+            │   └── exploit.py
+            ├── wp.md
+            └── chal.md
+```
+
+## AWD Mode
+
+Set `"mode": "awd"` in `ctf.json` to enable AWD commands:
+
+```sh
+ctfx awd ssh <service> [--team NAME]    SSH into service host
+ctfx awd scp <service> <src> <dst>      SCP file transfer
+ctfx awd cmd <service> -- <command>     Run remote command
+```
+
+Security note:
+- AWD SSH now relies on known host keys. Add the target host to your SSH known hosts first, otherwise the connection will be rejected instead of being auto-trusted.
+
+## Platform Support
+
+| Platform | Fetch | Submit |
+|---|---|---|
+| CTFd | yes | yes |
+| rCTF | planned | planned |
+| Manual | via `ctfx add` | no |
+
+## Development
+
+```sh
+git clone https://github.com/liyanqwq/CTFx
+cd CTFx
+pip install -e .
+ctfx --help
+```
+
+Frontend (React + Vite):
+```sh
+cd frontend
+npm install
+npm run dev       # dev server
+npm run build     # outputs to ctfx/server/static/
+```

ctfx-0.2.2/README.md

@@ -0,0 +1,250 @@
+# CTFx
+
+A local-first CTF workspace manager and assistant CLI for Jeopardy and AWD competitions.
+
+## Background
+
+CTFx started from a bunch of PowerShell scripts I wrote for CTF competitions back in HKCERT 2024.
+
+Later, in the HKCERT 2025 Final, I made a Python-based CTF Assistant for AWD matches. It worked pretty well, got some positive feedback, and helped our team achieve a solid result.
+
+After that, I decided to turn those ideas and experiences into CTFx, hoping it can give CTF players a bit of extra help in the AI era.
+
+## Features
+
+- **Competition management** — create, list, and switch between CTF workspaces
+- **Challenge scaffolding** — auto-generate category-specific solve templates (`pwn`, `crypto`, `forensics`, `rev`, `misc`)
+- **Platform integration** — fetch challenges and submit flags via CTFd API using either team token or platform cookies
+- **Terminal integration** — open shells, WSL, editors, and file explorers at challenge paths
+- **AI context** — generate `prompt.md` with competition context plus CLI/MCP usage notes for LLM-assisted solving
+- **WebUI** — React dashboard with challenge add/delete, editable challenge detail, flags table, and writeup editor
+- **REST API + MCP** — machine-readable interface for Claude Desktop / Cursor integration
+- **AWD mode** — SSH/SCP helpers, exploit runner, patch tracker, host map
+
+## Installation
+
+Requires Python 3.11+.
+
+```sh
+pip install ctfx
+# or with uv (recommended)
+uv tool install CTFx
+```
+
+### Install Guide
+
+Install from PyPI:
+
+```sh
+pip install ctfx
+ctfx --help
+```
+
+Upgrade to the latest release:
+
+```sh
+pip install -U ctfx
+```
+
+Install from a local checkout during development:
+
+```sh
+git clone https://github.com/liyanqwq/CTFx
+cd CTFx
+pip install -e .
+ctfx --help
+```
+
+## Quick Start
+
+```sh
+# First run — initializes ~/.config/ctfx/config.json
+ctfx setup
+
+# Create a competition workspace
+ctfx comp init --name HKCERT_CTF --year 2025 --mode jeopardy --platform ctfd
+
+# Switch to it
+ctfx use HKCERT_CTF_2025
+
+# Add a challenge
+ctfx add baby_pwn pwn
+
+# Open in editor
+ctfx code pwn/baby_pwn
+
+# Open a terminal at the solve directory
+ctfx cli pwn/baby_pwn/solve
+
+# Start the WebUI + API + MCP server
+ctfx serve
+
+# Open WebUI in browser (auto-login)
+ctfx webui
+```
+
+### Typical Flag Workflow
+
+`CTFx` now separates local flag recording from remote submission:
+
+1. Save a discovered flag locally in the WebUI or via API. This moves the challenge to `hoard`.
+2. Review hoarded flags in the `Flags` page.
+3. Submit the flag to the remote platform when ready.
+4. A successful remote submission promotes the challenge to `solved`.
+
+## Notes
+
+- Paths passed to `ctfx cli`, `ctfx code`, `ctfx explorer`, API routes, and MCP tools are restricted to the active competition workspace. Escaping with `..` is rejected.
+- Challenge categories, challenge names, and AWD service names are treated as path components and must not contain `/` or `\\`.
+- If `terminal.python_cmd` contains spaces, quote the executable path normally. Example on Windows: `"C:\Program Files\Python313\python.exe" -u`
+- `ctfx webui` generates a one-time login URL for the local WebUI. API and MCP still use the root token unless you are already authenticated in the browser.
+- For platform-backed competitions, set either `team_token` or `team_cookies` in the competition profile before attempting remote submission.
+- Challenge status flow is `fetched -> seen -> working -> hoard -> solved`.
+
+## CLI Reference
+
+```
+ctfx comp list [query]                  List competitions
+ctfx comp use <name>                    Set active competition
+ctfx comp init                          Create new competition workspace
+ctfx comp info                          Show active competition metadata
+
+ctfx chal list [query] [--cat] [--status]   List challenges
+ctfx chal add <name> [cat]             Add and scaffold a challenge
+ctfx chal rm <name>                    Remove a challenge
+ctfx chal info <name>                  Show challenge detail
+ctfx chal status <name> <status>       Update challenge status
+
+ctfx cli [path]                         Open terminal at path
+ctfx wsl [path] [-- cmd]               Open WSL shell or run command
+ctfx e [path]                          Open file explorer
+ctfx code [path]                       Open editor
+ctfx py [file]                         Run Python in configured environment
+
+ctfx fetch [--cat] [--chal]            Fetch challenges from platform
+ctfx submit <flag> [--chal]            Submit flag to platform
+ctfx import <url>                      LLM-assisted challenge import
+
+ctfx ai [--print]                      Generate AI context prompt.md with CLI/MCP notes
+ctfx mcp [--out PATH]                  Generate MCP client config
+
+ctfx webui / ctfx web / ctfx ui        Open WebUI in browser
+ctfx token update                      Rotate root token
+
+ctfx config show                       Display current configuration
+ctfx config list                       Alias for config show
+ctfx config set <key> <value>          Set a config value (dot-notation)
+
+ctfx serve [--port] [--host]           Start WebUI + API + MCP server
+ctfx setup                             Interactive configuration wizard
+ctfx i                                 Interactive REPL
+```
+
+### Aliases
+| Short | Full |
+|---|---|
+| `ctfx use <comp>` | `ctfx comp use <comp>` |
+| `ctfx init` | `ctfx comp init` |
+| `ctfx add <chal> [cat]` | `ctfx chal add <chal> [cat]` |
+| `ctfx e [path]` | `ctfx explorer [path]` |
+| `ctfx i` | `ctfx interactive` |
+
+## Configuration
+
+Global config lives at `~/.config/ctfx/config.json`. Run `ctfx setup` to configure interactively, or use `ctfx config set` for individual keys.
+
+```sh
+ctfx config show                        # view all settings
+ctfx config set serve.port 9000
+ctfx config set terminal.editor_cmd cursor
+ctfx config set terminal.wsl_distro ubuntu
+ctfx config set basedir ~/ctf
+```
+
+Settable keys: `basedir`, `active_competition`, `serve.host`, `serve.port`, `terminal.cli_cmd`, `terminal.editor_cmd`, `terminal.wsl_distro`, `terminal.python_cmd`, `terminal.explorer_cmd`, `terminal.file_manager_cmd`, `auth.one_time_login_ttl_sec`, `auth.session_ttl_sec`, `auth.webui_cookie_name`
+
+Key fields:
+- `basedir` — root directory for all competition workspaces (default: `~/ctf`)
+- `root_token` — auth secret for REST API, MCP, and WebUI; rotate with `ctfx token update` (not settable via `config set`)
+- `serve.port` — default server port (default: `8694`)
+- `terminal.*` — shell, editor, WSL distro, Python command
+
+Example Windows Python configuration with spaces in the executable path:
+
+```sh
+ctfx config set terminal.python_cmd "\"C:\Program Files\Python313\python.exe\" -u"
+```
+
+## Server & Authentication
+
+```sh
+ctfx serve              # starts on 127.0.0.1:8694 by default
+ctfx webui              # opens browser with auto one-time login
+```
+
+API and MCP endpoints require `Authorization: Bearer <root_token>`.
+
+The WebUI authenticates through a one-time login URL and then uses a secure session cookie for subsequent browser requests.
+
+Changing the active competition through the CLI or API also updates the in-process MCP server state, so MCP tools follow the currently selected competition.
+
+MCP client config for Claude Desktop / Cursor:
+```sh
+ctfx mcp --out mcp.json
+```
+
+The generated MCP URL uses `/mcp/` with a trailing slash.
+
+## Workspace Structure
+
+```
+~/ctf/
+└── HKCERT_CTF_2025/
+    ├── ctf.json
+    ├── prompt.md
+    └── pwn/
+        └── baby_pwn/
+            ├── src/
+            ├── solve/
+            │   └── exploit.py
+            ├── wp.md
+            └── chal.md
+```
+
+## AWD Mode
+
+Set `"mode": "awd"` in `ctf.json` to enable AWD commands:
+
+```sh
+ctfx awd ssh <service> [--team NAME]    SSH into service host
+ctfx awd scp <service> <src> <dst>      SCP file transfer
+ctfx awd cmd <service> -- <command>     Run remote command
+```
+
+Security note:
+- AWD SSH now relies on known host keys. Add the target host to your SSH known hosts first, otherwise the connection will be rejected instead of being auto-trusted.
+
+## Platform Support
+
+| Platform | Fetch | Submit |
+|---|---|---|
+| CTFd | yes | yes |
+| rCTF | planned | planned |
+| Manual | via `ctfx add` | no |
+
+## Development
+
+```sh
+git clone https://github.com/liyanqwq/CTFx
+cd CTFx
+pip install -e .
+ctfx --help
+```
+
+Frontend (React + Vite):
+```sh
+cd frontend
+npm install
+npm run dev       # dev server
+npm run build     # outputs to ctfx/server/static/
+```

ctfx-0.2.2/ctfx/__init__.py

@@ -0,0 +1,3 @@
+"""CTFx package."""
+
+__version__ = "0.2.2"