ctfy 0.1.23__tar.gz

ctfy-0.1.23/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.Python
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+
+# Testing & coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Type checkers & linters
+.mypy_cache/
+.ruff_cache/
+.pytype/
+
+# IDEs
+.idea/
+.vscode/
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+# openapi.json is a transient build artifact — TS types are generated from it
+# and committed, but the raw schema isn't worth tracking.
+frontend/openapi.json
+# tsc incremental build cache; churns on every build and adds noise to diffs.
+frontend/tsconfig.tsbuildinfo
+
+# Frontend build output (all historical paths)
+ctfy/dashboard/static/
+ctfy/server/static/
+llm_pentest_bench/server/static/
+pentest/server/static/
+
+# Environment & secrets
+.env
+.envrc
+.pypirc
+
+# uv
+# uv.lock is committed for reproducibility
+
+# Data & runtime artifacts
+data/results/
+*.sqlite3
+*.sqlite3-*
+*.log
+
+# Docker
+docker-compose.override.yml
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Data files
+data/

ctfy-0.1.23/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: ctfy
+Version: 0.1.23
+Requires-Python: >=3.11
+Requires-Dist: docker>=7.0
+Requires-Dist: fastapi-pagination>=0.12
+Requires-Dist: fastapi>=0.135.3
+Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: portpicker>=1.6.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: structlog>=23.0
+Requires-Dist: typer>=0.9
+Requires-Dist: uvicorn>=0.43.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Provides-Extra: screenshots
+Requires-Dist: playwright>=1.49; extra == 'screenshots'

ctfy-0.1.23/README.md

@@ -0,0 +1,32 @@
+# ctfy
+
+Open-source CTF platform — run challenges, register teams, score submissions.
+Ships with a REST API and MCP server for AI-agent evaluation harnesses.
+
+![ctfy dashboard](docs/screenshots/dashboard.png)
+
+## Quick start
+
+```bash
+echo "CTFY_ADMIN_TOKEN=$(openssl rand -hex 32)" > .env && docker compose up -d
+```
+
+Then open <http://localhost:8100>.
+
+## Screens
+
+### Challenges
+
+![](docs/screenshots/challenges.png) 
+
+### Scoreboard
+
+![](docs/screenshots/scoreboard.png)
+
+### Activity
+
+![](docs/screenshots/activity.png)
+
+### Achievements
+
+![](docs/screenshots/achievements.png)

ctfy-0.1.23/ctfy/cli/__init__.py

@@ -0,0 +1,98 @@
+"""ctfy — unified CLI entrypoint.
+
+Command groups:
+  ctfy server …       platform server lifecycle + invitations
+  ctfy node …         worker-node cluster membership
+  ctfy instance …     running challenge instances
+  ctfy challenge …    static challenge assets (sync, ls, show, validate)
+  ctfy mcp            start the MCP server
+  ctfy config …       inspect active configuration
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+import typer
+from dotenv import load_dotenv
+
+from ctfy.cli.challenge import challenge_app
+from ctfy.cli.config import config_app
+from ctfy.cli.instance import instance_app
+from ctfy.cli.node import node_app
+from ctfy.cli.server import server_app
+
+app = typer.Typer(help="ctfy — open-source CTF platform", no_args_is_help=True)
+app.add_typer(server_app, name="server")
+app.add_typer(node_app, name="node")
+app.add_typer(instance_app, name="instance")
+app.add_typer(challenge_app, name="challenge")
+app.add_typer(config_app, name="config")
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    try:
+        version = metadata.version("ctfy")
+    except metadata.PackageNotFoundError:
+        version = "0.0.0+unknown"
+    typer.echo(f"ctfy {version}")
+    raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the ctfy version and exit.",
+    ),
+    platform_url: str = typer.Option(
+        "http://localhost:8100",
+        "--platform-url",
+        envvar="CTFY_PLATFORM_URL",
+        help="Platform URL used by client subcommands (instance/challenge/mcp).",
+    ),
+    team_token: str = typer.Option(
+        "",
+        "--team-token",
+        envvar="CTFY_TEAM_TOKEN",
+        help="Team bearer token for subcommands that authenticate as a team.",
+    ),
+    admin_token: str = typer.Option(
+        "",
+        "--admin-token",
+        envvar="CTFY_ADMIN_TOKEN",
+        help="Admin bearer token for admin-only subcommands.",
+    ),
+):
+    """Populate ctx.obj with shared client settings for every subcommand."""
+    ctx.ensure_object(dict)
+    ctx.obj["platform_url"] = platform_url.rstrip("/")
+    ctx.obj["team_token"] = team_token
+    ctx.obj["admin_token"] = admin_token
+
+
+@app.command()
+def mcp(
+    ctx: typer.Context,
+):
+    """Start the MCP server."""
+    from ctfy.mcp.server import main as mcp_main
+
+    mcp_main(platform_url=ctx.obj["platform_url"], team_key=ctx.obj["team_token"])
+
+
+def main() -> None:
+    # Load .env before typer parses args so envvar= options pick up .env values.
+    load_dotenv(override=False)
+    app()
+
+
+if __name__ == "__main__":
+    main()

ctfy-0.1.23/ctfy/cli/challenge.py

@@ -0,0 +1,197 @@
+"""`ctfy challenge …` — static challenge assets in challenges_dir."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+import typer
+import yaml
+from pydantic import ValidationError
+from rich.table import Table
+
+from ctfy.cli.runtime import console, err_console
+from ctfy.core.challenge import ChallengeSpec
+from ctfy.core.challenge_validate import validate_dir
+from ctfy.core.config import CtfyConfig
+from ctfy.core.enums import Difficulty
+from ctfy.core.log import log, setup_logging
+
+challenge_app = typer.Typer(help="Static challenge assets in challenges_dir", no_args_is_help=True)
+
+
+def _default_challenges_dir() -> Path:
+    return CtfyConfig.model_fields["challenges_dir"].default
+
+
+CHALLENGES_DIR_OPTION = typer.Option(
+    _default_challenges_dir(),
+    "--challenges-dir",
+    envvar="CTFY_CHALLENGES_DIR",
+    help="Directory containing challenge metadata.yaml files.",
+)
+
+
+def _iter_specs(
+    challenges_dir: Path,
+    *,
+    challenge_id: str | None = None,
+    difficulty: Difficulty | None = None,
+    tag: str | None = None,
+) -> Iterable[ChallengeSpec]:
+    if not challenges_dir.exists():
+        return
+    for d in sorted(challenges_dir.iterdir()):
+        yml = d / "metadata.yaml"
+        if not d.is_dir() or not yml.exists():
+            continue
+        try:
+            spec = ChallengeSpec.from_yaml(yml)
+        except (ValidationError, yaml.YAMLError) as e:
+            log.warning("Skipping invalid challenge spec", path=str(yml), error=str(e))
+            continue
+        if challenge_id:
+            patterns = [p.strip() for p in challenge_id.split(",")]
+            if not any(spec.id == p or spec.id.startswith(p + "-") for p in patterns):
+                continue
+        if difficulty is not None and spec.difficulty != difficulty:
+            continue
+        if tag and tag not in spec.tags:
+            continue
+        yield spec
+
+
+@challenge_app.command("sync")
+def challenge_sync(
+    repo: str = typer.Option(
+        "",
+        "--repo",
+        envvar="CTFY_CHALLENGES_REPO",
+        help="Git repo URL (default: from config).",
+    ),
+    challenges_dir: Path = CHALLENGES_DIR_OPTION,
+):
+    """Clone or fast-forward-pull the challenges repo locally.
+
+    Run once after install, then whenever you want to pick up upstream
+    changes. Server / node startup no longer pulls automatically.
+    """
+    setup_logging()
+    config = CtfyConfig.from_env(
+        overrides={
+            "challenges_repo": repo,
+            "challenges_dir": challenges_dir,
+        }
+    )
+    from ctfy.core.challenges_sync import ensure_challenges
+
+    ensure_challenges(config.challenges_dir, config.challenges_repo)
+    console.print(f"[green]✓ Synced {config.challenges_repo} → {config.challenges_dir}[/green]")
+
+
+@challenge_app.command("ls")
+def challenge_ls(
+    challenge: str | None = typer.Option(
+        None, "--challenge", help="Filter by challenge ID (comma-separated, prefix-match)"
+    ),
+    difficulty: Difficulty | None = typer.Option(
+        None, "--difficulty", help="Filter by difficulty (easy | medium | hard)"
+    ),
+    tag: str | None = typer.Option(None, "--tag", help="Filter by a single tag"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a table"),
+    challenges_dir: Path = CHALLENGES_DIR_OPTION,
+):
+    """List challenge definitions in challenges_dir."""
+    setup_logging()
+    specs = list(
+        _iter_specs(challenges_dir, challenge_id=challenge, difficulty=difficulty, tag=tag)
+    )
+
+    if json_output:
+        console.print_json(data=[s.model_dump(mode="json") for s in specs])
+        return
+
+    table = Table(title="Challenge Definitions")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Difficulty", style="magenta")
+    table.add_column("Tags", style="dim")
+    for spec in specs:
+        table.add_row(spec.id, spec.name, spec.difficulty.value, ", ".join(spec.tags))
+    console.print(table)
+    console.print(f"\n[bold]{len(specs)}[/bold] challenge(s)")
+
+
+@challenge_app.command("show")
+def challenge_show(
+    challenge_id: str = typer.Argument(help="Challenge ID"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a summary"),
+    challenges_dir: Path = CHALLENGES_DIR_OPTION,
+):
+    """Show full metadata for a single challenge."""
+    setup_logging()
+    for spec in _iter_specs(challenges_dir, challenge_id=challenge_id):
+        if spec.id == challenge_id:
+            if json_output:
+                console.print_json(data=spec.model_dump(mode="json"))
+            else:
+                console.print(spec.model_dump(mode="json"))
+            return
+    err_console.print(f"[red]Challenge not found: {challenge_id}[/red]")
+    raise typer.Exit(1)
+
+
+@challenge_app.command("validate")
+def challenge_validate(
+    challenge_id: str | None = typer.Argument(
+        None, help="Challenge ID to validate (omit with --all to scan every challenge)"
+    ),
+    all_: bool = typer.Option(
+        False, "--all", help="Validate every metadata.yaml in challenges_dir"
+    ),
+    strict: bool = typer.Option(
+        False, "--strict", help="Passed through to the upstream audit (warnings become errors)."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit one JSON object per finding"),
+    challenges_dir: Path = CHALLENGES_DIR_OPTION,
+):
+    """Validate metadata + compose + source-code hygiene via the upstream audit."""
+    setup_logging()
+    if not all_ and not challenge_id:
+        err_console.print("[red]Pass a challenge ID or --all.[/red]")
+        raise typer.Exit(2)
+
+    findings = validate_dir(
+        challenges_dir,
+        challenge_id=None if all_ else challenge_id,
+        strict=strict,
+    )
+
+    if not findings:
+        err_console.print("[red]No challenges matched.[/red]")
+        raise typer.Exit(2)
+
+    failed = [f for f in findings if not f.ok]
+
+    if json_output:
+        import json
+
+        for f in findings:
+            console.print(
+                json.dumps(
+                    {"challenge": f.challenge, "status": f.status, "reason": f.reason},
+                    ensure_ascii=False,
+                )
+            )
+    else:
+        for f in findings:
+            if f.ok:
+                console.print(f"[green]OK[/green]    {f.challenge}")
+            else:
+                console.print(f"[red]FAIL[/red]  {f.challenge}: {f.reason}")
+        console.print(
+            f"\n[bold]{len(findings) - len(failed)}[/bold] ok, [bold]{len(failed)}[/bold] failed"
+        )
+
+    if failed:
+        raise typer.Exit(1)

ctfy-0.1.23/ctfy/cli/config.py

@@ -0,0 +1,44 @@
+"""`ctfy config …` — inspect active configuration.
+
+Re-uses :meth:`CtfyConfig.from_env` so what you see here is exactly what
+``ctfy server start`` / ``ctfy node join`` would resolve from the same
+environment at this moment.
+"""
+
+from __future__ import annotations
+
+import typer
+from pydantic import SecretStr
+
+from ctfy.cli.runtime import console
+from ctfy.core.config import CtfyConfig
+
+config_app = typer.Typer(help="Inspect active configuration", no_args_is_help=True)
+
+
+def _redact(value) -> str:
+    if isinstance(value, SecretStr):
+        return "<set>" if value.get_secret_value() else "<unset>"
+    return str(value)
+
+
+@config_app.command("show")
+def config_show(
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a table"),
+):
+    """Print the effective settings (secrets redacted)."""
+    cfg = CtfyConfig.from_env()
+    data = {k: _redact(getattr(cfg, k)) for k in cfg.model_fields}
+
+    if json_output:
+        console.print_json(data=data)
+        return
+
+    from rich.table import Table
+
+    table = Table(title="ctfy configuration")
+    table.add_column("Setting", style="cyan")
+    table.add_column("Value")
+    for k in sorted(data):
+        table.add_row(k, data[k])
+    console.print(table)

ctfy-0.1.23/ctfy/cli/instance.py

@@ -0,0 +1,91 @@
+"""`ctfy instance …` — running challenge instances."""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+
+from ctfy.cli.runtime import console, err_console, get_client
+from ctfy.core.enums import InstanceStatus
+from ctfy.core.log import setup_logging
+
+instance_app = typer.Typer(help="Running challenge instances", no_args_is_help=True)
+
+
+@instance_app.command("ls")
+def instance_ls(
+    ctx: typer.Context,
+    challenge: str | None = typer.Option(None, "--challenge", help="Filter by challenge ID"),
+    status: str | None = typer.Option(None, "--status", help="Filter by status"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a table"),
+):
+    """List instances currently running on the platform."""
+    setup_logging()
+    client = get_client(ctx)
+    instances = client.list_instances(challenge_id=challenge or "", status=status or "")
+
+    if json_output:
+        console.print_json(data=[i.model_dump() for i in instances])
+        return
+
+    table = Table(title="Running Instances")
+    table.add_column("Instance ID", style="cyan")
+    table.add_column("Challenge")
+    table.add_column("Status")
+    table.add_column("Started", style="dim")
+    table.add_column("TTL", justify="right")
+
+    for inst in instances:
+        status_style = "green" if inst.status == InstanceStatus.READY else "yellow"
+        table.add_row(
+            inst.instance_id,
+            inst.challenge_id or inst.name,
+            f"[{status_style}]{inst.status}[/]",
+            str(int(inst.started_at)) if inst.started_at else "",
+            str(inst.ttl) if inst.ttl else "",
+        )
+    console.print(table)
+    console.print(f"\n[bold]{len(instances)}[/bold] running")
+
+
+@instance_app.command("start")
+def instance_start(
+    ctx: typer.Context,
+    challenge_id: str = typer.Argument(help="Challenge ID to start"),
+    ttl: int = typer.Option(3600, "--ttl", help="Time-to-live in seconds"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a table"),
+):
+    """Start an instance of a challenge and wait until it is ready."""
+    setup_logging()
+    client = get_client(ctx)
+    console.print(f"Starting [bold]{challenge_id}[/bold]...")
+    try:
+        ready = client.start_instance(challenge_id, ttl=ttl)
+    except Exception as e:
+        err_console.print(f"[red]Failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    if json_output:
+        console.print_json(data=ready.surface.model_dump())
+        return
+
+    console.print("[green]Ready![/green]")
+    for svc in ready.surface.services:
+        suffix = f"  ({svc.label})" if svc.label else ""
+        console.print(f"  {svc.service_type.value}://{svc.host}:{svc.port}{suffix}")
+
+
+@instance_app.command("stop")
+def instance_stop(
+    ctx: typer.Context,
+    instance_id: str = typer.Argument(help="Instance ID (or challenge ID) to stop"),
+):
+    """Stop a running instance."""
+    setup_logging()
+    client = get_client(ctx)
+    try:
+        client.stop_instance(instance_id)
+    except Exception as e:
+        err_console.print(f"[red]Failed: {e}[/red]")
+        raise typer.Exit(1)
+    console.print(f"[green]Stopped {instance_id}[/green]")