CTFx 0.2.2__py3-none-any.whl

ctfx/__init__.py

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

ctfx/cli.py

@@ -0,0 +1,81 @@
+"""Click entry point — registers all command groups and top-level aliases."""
+
+import sys
+import click
+
+from ctfx import __version__
+from ctfx.exceptions import CTFxError
+from ctfx.commands.competition import comp_group, cmd_use, cmd_init
+from ctfx.commands.challenge import chal_group, cmd_add
+from ctfx.commands.terminal import cmd_cli, cmd_wsl, cmd_explorer, cmd_code, cmd_py
+from ctfx.commands.platform import cmd_fetch, cmd_submit, cmd_import
+from ctfx.commands.serve import cmd_serve
+from ctfx.commands.ai import cmd_ai, cmd_mcp
+from ctfx.commands.awd import awd_group
+from ctfx.commands.setup import cmd_setup
+from ctfx.commands.token import token_group
+from ctfx.commands.webui import cmd_webui
+from ctfx.commands.interactive import cmd_interactive
+from ctfx.commands.config import config_group
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(__version__, prog_name="ctfx")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """ctfx — CTF workspace manager and assistant.
+
+    Local-first CTF workspace manager. Run 'ctfx setup' on first use.
+    Docs: https://github.com/liyanqwq/CTFx
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+def _main() -> None:
+    """Wrapper that catches CTFxError for clean user-facing output."""
+    try:
+        main(standalone_mode=True)
+    except CTFxError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+# Command groups
+main.add_command(comp_group, name="comp")
+main.add_command(chal_group, name="chal")
+main.add_command(awd_group, name="awd")
+main.add_command(token_group, name="token")
+main.add_command(config_group, name="config")
+
+# Direct commands
+main.add_command(cmd_cli, name="cli")
+main.add_command(cmd_wsl, name="wsl")
+main.add_command(cmd_explorer, name="explorer")
+main.add_command(cmd_explorer, name="e")
+main.add_command(cmd_code, name="code")
+main.add_command(cmd_py, name="py")
+main.add_command(cmd_fetch, name="fetch")
+main.add_command(cmd_submit, name="submit")
+main.add_command(cmd_import, name="import")
+main.add_command(cmd_serve, name="serve")
+main.add_command(cmd_ai, name="ai")
+main.add_command(cmd_mcp, name="mcp")
+main.add_command(cmd_setup, name="setup")
+main.add_command(cmd_webui, name="webui")
+main.add_command(cmd_webui, name="web")
+main.add_command(cmd_webui, name="ui")
+main.add_command(cmd_interactive, name="interactive")
+main.add_command(cmd_interactive, name="i")
+
+# Top-level aliases
+main.add_command(cmd_use, name="use")
+main.add_command(cmd_init, name="init")
+main.add_command(cmd_add, name="add")
+
+
+@main.command("help")
+@click.pass_context
+def cmd_help(ctx: click.Context) -> None:
+    """Show this help message."""
+    click.echo(ctx.find_root().get_help())

ctfx/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

ctfx/commands/ai.py

@@ -0,0 +1,228 @@
+"""AICommand — ctfx ai / ctfx mcp"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ctfx.managers.config import ConfigManager
+from ctfx.managers.workspace import WorkspaceManager
+
+console = Console()
+
+# Marker for the user-editable section preserved across regenerations
+_EXTRA_INFO_HEADER = "## Extra Info"
+_EXTRA_INFO_DEFAULT = (
+    "<!-- preserved across regenerations; "
+    "add manual notes, known context, team strategy here -->"
+)
+
+
+def _load_active() -> tuple[ConfigManager, WorkspaceManager, dict]:
+    cfg = ConfigManager.load()
+    if not cfg.active_competition:
+        console.print("[red]No active competition.[/red] Run [cyan]ctfx use[/cyan] first.")
+        raise SystemExit(1)
+    wm = WorkspaceManager(cfg.basedir, cfg.active_competition)
+    try:
+        data = wm.load_ctf_json()
+    except FileNotFoundError:
+        console.print(f"[red]ctf.json not found for {cfg.active_competition}[/red]")
+        raise SystemExit(1)
+    return cfg, wm, data
+
+
+def _extract_extra_info(existing_text: str) -> str:
+    """Extract the ## Extra Info section from an existing prompt.md, preserving user notes."""
+    match = re.search(
+        rf"^{re.escape(_EXTRA_INFO_HEADER)}\s*\n(.*)",
+        existing_text,
+        re.MULTILINE | re.DOTALL,
+    )
+    if match:
+        return match.group(1).rstrip()
+    return _EXTRA_INFO_DEFAULT
+
+
+_MCP_SECTION = """\
+## MCP Tools
+
+When connected via MCP (Cursor, Claude Desktop, or any MCP-capable client), use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_competitions` | List all competitions in the workspace |
+| `get_competition` | Get active (or specified) competition metadata |
+| `list_challenges` | List challenges — filter by `category` or `status` |
+| `get_challenge` | Get full detail for a specific challenge by name |
+| `add_challenge` | Create a new challenge directory with scaffold |
+| `set_challenge_status` | Update status: `fetched` → `seen` → `working` → `solved` |
+| `get_prompt` | Read this prompt.md file |
+| `submit_flag` | Submit a flag to the platform (or record locally) |
+| `run_exploit` | Run `solve/exploit.py` via the configured Python command |
+| `list_awd_exploits` | List AWD exploit files for a service *(AWD mode only)* |
+| `list_awd_patches` | List AWD patch files for a service *(AWD mode only)* |
+| `get_config` | Read CTFx global configuration |
+| `set_config` | Write a CTFx config value by dot-notation key |"""
+
+_CLI_SECTION = """\
+## CLI Reference
+
+Run these from your shell (prefix with `ctfx`):
+
+```
+# Competition management
+ctfx use <dir>                   Switch active competition
+ctfx comp list                   List all competitions
+ctfx comp init                   Create a new competition
+ctfx comp info                   Show active competition metadata
+
+# Challenge management
+ctfx chal list [--cat CAT] [--status STATUS]
+ctfx chal add <name> [cat]       Add challenge (interactive category picker if cat omitted)
+ctfx chal status <name> <status> [flag]
+ctfx chal info <name>
+ctfx chal rm <name>
+
+# Platform integration
+ctfx fetch [--cat CAT]           Fetch challenges from CTFd
+ctfx submit <flag> [--chal NAME] Submit flag to platform
+ctfx import <url>                LLM-assisted challenge import from URL
+
+# Terminal helpers (path relative to competition root)
+ctfx cli [path]                  Open terminal at path
+ctfx wsl [path]                  Open WSL shell at path
+ctfx code [path]                 Open VS Code at path
+ctfx e [path]                    Open file explorer at path
+ctfx py [file]                   Run Python (or open REPL)
+
+# Server
+ctfx serve [--port PORT]         Start WebUI + API + MCP server
+ctfx webui                       Open WebUI in browser (one-time login)
+ctfx mcp [--out PATH]            Generate MCP client config
+
+# Other
+ctfx ai [--print]                Regenerate this prompt.md
+ctfx token update                Rotate root token
+ctfx config show                 Show full config
+ctfx config set <key> <value>    Edit config by dot-notation key
+ctfx i                           Interactive REPL (no ctfx prefix needed)
+```"""
+
+
+def _build_prompt(data: dict, challenges: list[dict], extra_info: str) -> str:
+    name = data.get("name", "Unknown CTF")
+    year = data.get("year", "")
+    team_name = data.get("team_name", "")
+    flag_format = data.get("flag_format", "flag{...}")
+    mode = data.get("mode", "jeopardy")
+    platform = data.get("platform", "manual")
+    url = data.get("url", "")
+
+    lines = [
+        "You are a professional CTF (Capture The Flag) competition assistant with deep expertise",
+        "in all CTF categories including pwn, crypto, web, forensics, rev, and misc.",
+        "",
+        f"You are assisting team {team_name or '(unnamed)'} in the {name} {year} competition.",
+        "",
+        "## Competition Info",
+    ]
+    if url:
+        lines.append(f"- Platform: {url}")
+    lines += [
+        f"- Flag format: `{flag_format}`",
+        f"- Mode: {mode}",
+        f"- Platform adapter: {platform}",
+        "",
+        "Do not assume any challenge is a known or previously seen challenge. Treat every",
+        "challenge as original and reason from first principles.",
+        "",
+        "## Challenge Status",
+    ]
+
+    # Group challenges by category
+    by_cat: dict[str, list[dict]] = {}
+    for chal in challenges:
+        by_cat.setdefault(chal["category"] or "misc", []).append(chal)
+
+    for cat in sorted(by_cat):
+        lines.append(f"\n### {cat}")
+        for chal in by_cat[cat]:
+            pts = f" ({chal['points']} pts)" if chal.get("points") is not None else ""
+            status_marker = "✓" if chal["status"] == "solved" else "·"
+            lines.append(f"- {status_marker} `{chal['name']}` [{chal['status']}]{pts}")
+
+    lines += [
+        "",
+        _MCP_SECTION,
+        "",
+        _CLI_SECTION,
+        "",
+        _EXTRA_INFO_HEADER,
+        extra_info,
+        "",
+    ]
+    return "\n".join(lines)
+
+
+@click.command("ai")
+@click.option("--print", "do_print", is_flag=True, help="Also print prompt to stdout")
+def cmd_ai(do_print: bool) -> None:
+    """Generate prompt.md with competition context for LLM use.
+
+    Preserves the '## Extra Info' section across regenerations.
+    """
+    cfg, wm, data = _load_active()
+    challenges = wm.list_challenges()
+
+    prompt_path = wm.competition_root() / "prompt.md"
+
+    # Preserve the ## Extra Info section if the file already exists
+    if prompt_path.exists():
+        existing = prompt_path.read_text(encoding="utf-8")
+        extra_info = _extract_extra_info(existing)
+    else:
+        extra_info = _EXTRA_INFO_DEFAULT
+
+    prompt = _build_prompt(data, challenges, extra_info)
+
+    if do_print:
+        console.print(prompt)
+        return
+
+    prompt_path.write_text(prompt, encoding="utf-8")
+    console.print(f"[green]Wrote[/green] {prompt_path}")
+    console.print(
+        f"  [dim]{len(challenges)} challenges listed | "
+        f"edit '## Extra Info' to add manual context[/dim]"
+    )
+
+
+@click.command("mcp")
+@click.option("--out", default=None, help="Write MCP client config JSON to a file")
+def cmd_mcp(out: str | None) -> None:
+    """Generate MCP client config for Claude Desktop / Cursor."""
+    cfg = ConfigManager.load()
+    payload = {
+        "mcpServers": {
+            "ctfx": {
+                "url": f"http://{cfg.serve_host}:{cfg.serve_port}/mcp/",
+                "headers": {
+                    "Authorization": f"Bearer {cfg.root_token}",
+                },
+            }
+        }
+    }
+    text = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+    if out:
+        Path(out).write_text(text, encoding="utf-8")
+        console.print(f"[green]Wrote[/green] {out}")
+        console.print(
+            f"[dim]MCP endpoint: http://{cfg.serve_host}:{cfg.serve_port}/mcp[/dim]"
+        )
+    else:
+        console.print(text)

ctfx/commands/awd.py

@@ -0,0 +1,214 @@
+"""AWDCommand — ctfx awd ssh / scp / cmd (AWD mode only)"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ctfx.managers.config import ConfigManager
+from ctfx.managers.workspace import WorkspaceManager
+
+console = Console()
+
+
+def _load_awd() -> tuple[ConfigManager, WorkspaceManager, dict]:
+    cfg = ConfigManager.load()
+    if not cfg.active_competition:
+        console.print("[red]No active competition.[/red] Run [cyan]ctfx use[/cyan] first.")
+        raise SystemExit(1)
+    wm = WorkspaceManager(cfg.basedir, cfg.active_competition)
+    try:
+        data = wm.load_ctf_json()
+    except FileNotFoundError:
+        console.print("[red]ctf.json not found.[/red]")
+        raise SystemExit(1)
+    if data.get("mode") != "awd":
+        console.print(
+            "[red]AWD commands are only available in AWD mode.[/red] "
+            "Set [cyan]\"mode\": \"awd\"[/cyan] in ctf.json."
+        )
+        raise SystemExit(1)
+    return cfg, wm, data
+
+
+def _resolve_host(wm: WorkspaceManager, service: str, team: str | None) -> tuple[str, str]:
+    """Return (username, ip) for the target team/host."""
+    try:
+        hosts = wm.load_hostlist(service)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+    if not hosts:
+        console.print(
+            f"[red]No hosts found for service '{service}'.[/red] "
+            f"Create [cyan]{service}/hostlist.txt[/cyan] in the competition directory."
+        )
+        raise SystemExit(1)
+
+    if team:
+        match = next((h for h in hosts if h[0].lower() == team.lower()), None)
+        if not match:
+            available = ", ".join(h[0] for h in hosts)
+            console.print(
+                f"[red]Team '{team}' not found.[/red] Available: {available}"
+            )
+            raise SystemExit(1)
+        return "root", match[1]
+
+    if len(hosts) == 1:
+        return "root", hosts[0][1]
+
+    from rich.table import Table
+    table = Table(show_header=True, header_style="bold cyan", box=None)
+    table.add_column("#", width=3, style="dim")
+    table.add_column("Team")
+    table.add_column("IP")
+    for i, (t, ip) in enumerate(hosts, 1):
+        table.add_row(str(i), t, ip)
+    console.print(table)
+
+    while True:
+        raw = click.prompt("Select host number (or q to cancel)", default="q")
+        if raw.strip().lower() in ("q", "quit", ""):
+            raise SystemExit(0)
+        try:
+            idx = int(raw.strip()) - 1
+            if 0 <= idx < len(hosts):
+                return "root", hosts[idx][1]
+        except ValueError:
+            pass
+        console.print(f"[red]Invalid.[/red] Enter 1–{len(hosts)} or q.")
+
+
+@click.group("awd")
+def awd_group() -> None:
+    """AWD mode commands (SSH, SCP, remote exec)."""
+
+
+@awd_group.command("ssh")
+@click.argument("service")
+@click.option("--team", default=None, help="Team name to SSH into")
+@click.option("--port", default=22, type=int, show_default=True)
+@click.option("--user", default="root", show_default=True)
+def awd_ssh(service: str, team: str | None, port: int, user: str) -> None:
+    """Open an interactive SSH shell into a service host."""
+    _, wm, _ = _load_awd()
+    _, ip = _resolve_host(wm, service, team)
+    try:
+        key_path = wm.get_service_key_path(service)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    console.print(
+        f"Connecting to [bold]{ip}:{port}[/bold] "
+        + (f"(key: {key_path.name})" if key_path else "(password auth)")
+    )
+
+    try:
+        from ctfx.managers.awd import AWDSession
+        with AWDSession(ip, port=port, username=user, key_path=key_path) as sess:
+            sess.interactive_shell()
+    except Exception as e:
+        console.print(f"[red]SSH failed:[/red] {e}")
+        raise SystemExit(1)
+
+
+@awd_group.command("scp")
+@click.argument("service")
+@click.argument("src")
+@click.argument("dst")
+@click.option("--team", default=None, help="Target team name")
+@click.option("--port", default=22, type=int, show_default=True)
+@click.option("--user", default="root", show_default=True)
+def awd_scp(service: str, src: str, dst: str, team: str | None, port: int, user: str) -> None:
+    """SCP file transfer. Prefix remote paths with ':' (e.g. :/tmp/file)."""
+    _, wm, _ = _load_awd()
+    _, ip = _resolve_host(wm, service, team)
+    try:
+        key_path = wm.get_service_key_path(service)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    try:
+        from ctfx.managers.awd import AWDSession
+        with AWDSession(ip, port=port, username=user, key_path=key_path) as sess:
+            if src.startswith(":"):
+                remote = src[1:]
+                local = Path(dst)
+                console.print(f"[dim]Downloading[/dim] {ip}:{remote} → {local}")
+                sess.get(remote, local)
+                console.print(f"[green]Done.[/green] Saved to {local}")
+            elif dst.startswith(":"):
+                local = Path(src)
+                remote = dst[1:]
+                if not local.exists():
+                    console.print(f"[red]Local file not found:[/red] {local}")
+                    raise SystemExit(1)
+                console.print(f"[dim]Uploading[/dim] {local} → {ip}:{remote}")
+                sess.put(local, remote)
+                console.print(f"[green]Done.[/green]")
+            else:
+                console.print("[red]Prefix the remote path with ':' (e.g. :/tmp/file).[/red]")
+                raise SystemExit(1)
+    except SystemExit:
+        raise
+    except Exception as e:
+        console.print(f"[red]SCP failed:[/red] {e}")
+        raise SystemExit(1)
+
+
+@awd_group.command("cmd")
+@click.argument("service")
+@click.argument("command", nargs=-1, required=True)
+@click.option("--team", default=None, help="Run on a specific team's host")
+@click.option("--all-teams", "all_teams", is_flag=True, help="Run on all hosts in hostlist")
+@click.option("--port", default=22, type=int, show_default=True)
+@click.option("--user", default="root", show_default=True)
+@click.option("--timeout", "cmd_timeout", default=30.0, type=float, show_default=True)
+def awd_cmd(
+    service: str,
+    command: tuple[str, ...],
+    team: str | None,
+    all_teams: bool,
+    port: int,
+    user: str,
+    cmd_timeout: float,
+) -> None:
+    """Run a remote command on service host(s) via SSH."""
+    _, wm, _ = _load_awd()
+    cmd_str = " ".join(command)
+    try:
+        key_path = wm.get_service_key_path(service)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    if all_teams:
+        hosts = wm.load_hostlist(service)
+        if not hosts:
+            console.print(f"[red]No hosts found for service '{service}'.[/red]")
+            raise SystemExit(1)
+        targets = [(t, ip) for t, ip in hosts]
+    else:
+        _, ip = _resolve_host(wm, service, team)
+        targets = [(team or ip, ip)]
+
+    from ctfx.managers.awd import AWDSession
+
+    for team_name, ip in targets:
+        console.print(f"\n[bold cyan]{team_name}[/bold cyan] ({ip})")
+        try:
+            with AWDSession(ip, port=port, username=user, key_path=key_path) as sess:
+                stdout, stderr, code = sess.run(cmd_str, timeout=cmd_timeout)
+            if stdout.strip():
+                console.print(stdout.rstrip())
+            if stderr.strip():
+                console.print(f"[dim]{stderr.rstrip()}[/dim]")
+            if code != 0:
+                console.print(f"[yellow]exit {code}[/yellow]")
+        except Exception as e:
+            console.print(f"  [red]Failed:[/red] {e}")