nexctf-sandbox 1.0.0__tar.gz

nexctf_sandbox-1.0.0/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+
+
+Copyright (c) 2026 d3vyce
+
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+
+of this software and associated documentation files (the "Software"), to deal
+
+in the Software without restriction, including without limitation the rights
+
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+
+copies of the Software, and to permit persons to whom the Software is
+
+furnished to do so, subject to the following conditions:
+
+
+
+The above copyright notice and this permission notice shall be included in all
+
+copies or substantial portions of the Software.
+
+
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+
+SOFTWARE.

nexctf_sandbox-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: nexctf-sandbox
+Version: 1.0.0
+Summary: Sandboxed code execution for NexCTF, script checker and code runner via microsandbox microVMs.
+Keywords: nexctf,ctf,sandbox,microvm,plugin
+Author: NexCTF
+Author-email: NexCTF <contact@nexctf.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Security
+Requires-Dist: microsandbox>=0.7.8
+Requires-Dist: nexctf>=0.12,<0.13
+Requires-Python: >=3.15
+Project-URL: Homepage, https://github.com/NexCTF/Sandbox
+Project-URL: Repository, https://github.com/NexCTF/Sandbox
+Project-URL: Issues, https://github.com/NexCTF/Sandbox/issues
+Description-Content-Type: text/markdown
+
+# NexCTF Sandbox
+
+A [NexCTF](https://github.com/NexCTF/NexCTF) plugin that checks answers by running Python: a code runner that tests players' programs against test cases, and a script checker that validates answers with a function you write. Every run happens in a throwaway [microsandbox](https://github.com/microsandbox/microsandbox) microVM, booted for the submission and removed right after.
+
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.15](https://img.shields.io/badge/python-3.15-blue.svg)](https://www.python.org/downloads/)
+
+## Quick Start
+
+Add the plugin to NexCTF's `NEXCTF_PLUGINS` and restart it; NexCTF installs it from PyPI and applies its migrations:
+
+```bash
+NEXCTF_PLUGINS=nexctf-sandbox==1.0.0
+```
+
+Each plugin release supports one NexCTF minor version, so upgrade the two together:
+
+| nexctf-sandbox | NexCTF |
+|---|---|
+| 1.0.x | 0.12.x |
+
+The NexCTF process that checks submissions boots the microVMs, so it needs read and write access to `/dev/kvm`. Nothing else: the network setting is enforced by microsandbox's own network stack, with no extra capability or root.
+
+With NexCTF's `compose.yml`, that goes on the `app` service, e.g. in a `compose.override.yml`. `/dev/kvm` belongs to the host's `kvm` group, which the image's unprivileged user has to join; get its id with `stat -c %g /dev/kvm`:
+
+```yaml
+services:
+  app:
+    devices:
+      - /dev/kvm
+    group_add:
+      - "993"  # the kvm group id on the host
+    environment:
+      NEXCTF_PLUGINS: nexctf-sandbox==1.0.0
+```
+
+Then, on a question, pick the solution type **runner** or **script**.
+
+## Features
+
+### 🏃 Code runner
+- Runs the player's Python 3 code against up to 20 test cases, feeding each one's input on stdin
+- Accepted only when every case's stdout matches the expected output, whitespace stripped
+- A crash or a non-zero exit fails the case
+- All the cases of a submission share one microVM, run one after the other
+- For questions with a **code** input
+
+### ✅ Script checker
+- Validates the answer with your own Python function, `check(answer, team_id, team_fields) -> bool`
+- Hands the checker the team's custom fields, typed, private ones included: per-team flags and seeds work out of the box
+- The starter checker lists the team custom fields that exist
+- Checkers written without `team_fields` keep working as they are
+- For questions with an **input**, **text** or **code** input
+
+## Writing a checker
+
+The checker is a function named `check` that returns `True` to accept the answer. `team_id` is the team's id as a string, or `None`; `team_fields` maps each team custom field name to its value (`int`, `bool` or `str`), and a key is missing when the team left the field empty. Declare `team_fields` only if you need it:
+
+```python
+import hashlib
+
+
+def check(answer: str, team_id: str | None, team_fields: dict) -> bool:
+    seed = team_fields.get("seed", "")
+    flag = "FLAG{" + hashlib.sha256(seed.encode()).hexdigest()[:16] + "}"
+    return answer.strip() == flag
+```
+
+The checker runs in its own microVM, with the base image's Python and the network access set below.
+
+## Settings
+
+Under **Settings → Plugins → Sandbox**:
+
+| Setting | Default |
+|---|---|
+| Base image | `python:3.14-slim`; any OCI image with `python3` on `PATH` |
+| vCPUs | 1 |
+| Memory | 256 MiB, plus the root disk |
+| Root disk | 64 MiB, in RAM |
+| Network access | `disabled`; `internet` for public addresses and the host's DNS, `all` for unfiltered egress, the host's own network included |
+| Max concurrent microVMs | 8, across all challenges; takes effect after a restart |
+
+## Development
+
+The tests stub out the microVMs and need no database. NexCTF is a dev dependency installed from git (currently its `v0.12.0` tag).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run ty check .
+```
+
+The `live` tests boot real microVMs and skip without `/dev/kvm`; the one reaching the internet also skips when the host has none. Run them on the host that will check submissions before an event:
+
+```bash
+uv run pytest -m live
+```
+
+To load a local checkout in a dev NexCTF, add its path to `NEXCTF_PLUGINS` in NexCTF's `.env.dev.override`, then restart `task dev:backend`.

nexctf_sandbox-1.0.0/README.md

@@ -0,0 +1,102 @@
+# NexCTF Sandbox
+
+A [NexCTF](https://github.com/NexCTF/NexCTF) plugin that checks answers by running Python: a code runner that tests players' programs against test cases, and a script checker that validates answers with a function you write. Every run happens in a throwaway [microsandbox](https://github.com/microsandbox/microsandbox) microVM, booted for the submission and removed right after.
+
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.15](https://img.shields.io/badge/python-3.15-blue.svg)](https://www.python.org/downloads/)
+
+## Quick Start
+
+Add the plugin to NexCTF's `NEXCTF_PLUGINS` and restart it; NexCTF installs it from PyPI and applies its migrations:
+
+```bash
+NEXCTF_PLUGINS=nexctf-sandbox==1.0.0
+```
+
+Each plugin release supports one NexCTF minor version, so upgrade the two together:
+
+| nexctf-sandbox | NexCTF |
+|---|---|
+| 1.0.x | 0.12.x |
+
+The NexCTF process that checks submissions boots the microVMs, so it needs read and write access to `/dev/kvm`. Nothing else: the network setting is enforced by microsandbox's own network stack, with no extra capability or root.
+
+With NexCTF's `compose.yml`, that goes on the `app` service, e.g. in a `compose.override.yml`. `/dev/kvm` belongs to the host's `kvm` group, which the image's unprivileged user has to join; get its id with `stat -c %g /dev/kvm`:
+
+```yaml
+services:
+  app:
+    devices:
+      - /dev/kvm
+    group_add:
+      - "993"  # the kvm group id on the host
+    environment:
+      NEXCTF_PLUGINS: nexctf-sandbox==1.0.0
+```
+
+Then, on a question, pick the solution type **runner** or **script**.
+
+## Features
+
+### 🏃 Code runner
+- Runs the player's Python 3 code against up to 20 test cases, feeding each one's input on stdin
+- Accepted only when every case's stdout matches the expected output, whitespace stripped
+- A crash or a non-zero exit fails the case
+- All the cases of a submission share one microVM, run one after the other
+- For questions with a **code** input
+
+### ✅ Script checker
+- Validates the answer with your own Python function, `check(answer, team_id, team_fields) -> bool`
+- Hands the checker the team's custom fields, typed, private ones included: per-team flags and seeds work out of the box
+- The starter checker lists the team custom fields that exist
+- Checkers written without `team_fields` keep working as they are
+- For questions with an **input**, **text** or **code** input
+
+## Writing a checker
+
+The checker is a function named `check` that returns `True` to accept the answer. `team_id` is the team's id as a string, or `None`; `team_fields` maps each team custom field name to its value (`int`, `bool` or `str`), and a key is missing when the team left the field empty. Declare `team_fields` only if you need it:
+
+```python
+import hashlib
+
+
+def check(answer: str, team_id: str | None, team_fields: dict) -> bool:
+    seed = team_fields.get("seed", "")
+    flag = "FLAG{" + hashlib.sha256(seed.encode()).hexdigest()[:16] + "}"
+    return answer.strip() == flag
+```
+
+The checker runs in its own microVM, with the base image's Python and the network access set below.
+
+## Settings
+
+Under **Settings → Plugins → Sandbox**:
+
+| Setting | Default |
+|---|---|
+| Base image | `python:3.14-slim`; any OCI image with `python3` on `PATH` |
+| vCPUs | 1 |
+| Memory | 256 MiB, plus the root disk |
+| Root disk | 64 MiB, in RAM |
+| Network access | `disabled`; `internet` for public addresses and the host's DNS, `all` for unfiltered egress, the host's own network included |
+| Max concurrent microVMs | 8, across all challenges; takes effect after a restart |
+
+## Development
+
+The tests stub out the microVMs and need no database. NexCTF is a dev dependency installed from git (currently its `v0.12.0` tag).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run ty check .
+```
+
+The `live` tests boot real microVMs and skip without `/dev/kvm`; the one reaching the internet also skips when the host has none. Run them on the host that will check submissions before an event:
+
+```bash
+uv run pytest -m live
+```
+
+To load a local checkout in a dev NexCTF, add its path to `NEXCTF_PLUGINS` in NexCTF's `.env.dev.override`, then restart `task dev:backend`.

nexctf_sandbox-1.0.0/nexctf_sandbox/__init__.py

@@ -0,0 +1,102 @@
+from nexctf.plugins import (
+    ConfigCategory,
+    ConfigDef,
+    ConfigType,
+    InputType,
+    Plugin,
+    TypeDef,
+)
+
+from nexctf_sandbox._sandbox import (
+    DEFAULT_BASE_IMAGE,
+    DEFAULT_CPUS,
+    DEFAULT_MAX_CONCURRENT,
+    DEFAULT_MEMORY_MIB,
+    DEFAULT_NETWORK_ACCESS,
+    DEFAULT_ROOT_DISK_MIB,
+    NETWORK_ACCESS_CHOICES,
+)
+from nexctf_sandbox.solutions.runner import (
+    RunnerSolution,
+    RunnerSolutionCreate,
+    RunnerSolutionRead,
+    RunnerSolutionUpdate,
+)
+from nexctf_sandbox.solutions.script import (
+    ScriptSolution,
+    ScriptSolutionCreate,
+    ScriptSolutionRead,
+    ScriptSolutionUpdate,
+)
+
+plugin = Plugin(
+    solution_types=[
+        TypeDef(
+            "runner",
+            model=RunnerSolution,
+            create_schema=RunnerSolutionCreate,
+            update_schema=RunnerSolutionUpdate,
+            read_schema=RunnerSolutionRead,
+            compatible_input_types=[InputType.CODE],
+            description="Code runner — executes the submitted Python 3 code against a set of test cases.",
+        ),
+        TypeDef(
+            "script",
+            model=ScriptSolution,
+            create_schema=ScriptSolutionCreate,
+            update_schema=ScriptSolutionUpdate,
+            read_schema=ScriptSolutionRead,
+            compatible_input_types=[InputType.INPUT, InputType.TEXT, InputType.CODE],
+            description="Script checker — runs a custom Python function check(answer, team_id, team_fields) → bool to validate the answer.",
+        ),
+    ],
+    config=ConfigCategory(
+        "Sandbox",
+        (
+            ConfigDef(
+                key="base_image",
+                label="Base image",
+                default=DEFAULT_BASE_IMAGE,
+                type=ConfigType.STRING,
+                description="OCI image every microVM boots from. It must provide python3 on PATH.",
+            ),
+            ConfigDef(
+                key="cpus",
+                label="vCPUs",
+                default=DEFAULT_CPUS,
+                description="Virtual CPUs given to each microVM.",
+            ),
+            ConfigDef(
+                key="memory_mib",
+                label="Memory (MiB)",
+                default=DEFAULT_MEMORY_MIB,
+                description="Guest RAM for each microVM. The root disk is added on top of this.",
+            ),
+            ConfigDef(
+                key="root_disk_mib",
+                label="Root disk (MiB)",
+                default=DEFAULT_ROOT_DISK_MIB,
+                description="Size of the tmpfs root disk. It is RAM-backed, so it is charged to guest memory.",
+            ),
+            ConfigDef(
+                key="network_access",
+                label="Network access",
+                default=DEFAULT_NETWORK_ACCESS,
+                type=ConfigType.CHOICE,
+                choices=NETWORK_ACCESS_CHOICES,
+                description=(
+                    "'disabled': no egress at all.\n"
+                    "'internet': public addresses, plus the host's DNS resolver on port 53.\n"
+                    "'all': unfiltered, including everything on the host's own network."
+                ),
+            ),
+            ConfigDef(
+                key="max_concurrent",
+                label="Max concurrent microVMs",
+                default=DEFAULT_MAX_CONCURRENT,
+                description="Ceiling on microVMs running at once, across all challenges. Takes effect after a restart.",
+            ),
+        ),
+        icon="box",
+    ),
+)

nexctf_sandbox-1.0.0/nexctf_sandbox/_sandbox.py

@@ -0,0 +1,178 @@
+"""Shared microsandbox helper for solution plugins that execute untrusted code."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from functools import partial
+from uuid import uuid4
+
+from microsandbox import (
+    Image,
+    Network,
+    NetworkProfile,
+    RootDisk,
+    Sandbox,
+)
+from pydantic import ValidationError
+
+logger = logging.getLogger(__name__)
+
+PLUGIN_SLUG = "nexctf_sandbox"
+
+DEFAULT_BASE_IMAGE = "python:3.14-slim"
+DEFAULT_CPUS = 1
+DEFAULT_MEMORY_MIB = 256
+DEFAULT_ROOT_DISK_MIB = 64
+DEFAULT_MAX_CONCURRENT = 8
+
+NETWORK_DISABLED = "disabled"  # no egress at all
+NETWORK_INTERNET = "internet"  # public addresses and DNS, but nothing host-side
+NETWORK_ALL = "all"  # unfiltered, including the host's own network
+NETWORK_ACCESS_CHOICES = [NETWORK_DISABLED, NETWORK_INTERNET, NETWORK_ALL]
+DEFAULT_NETWORK_ACCESS = NETWORK_DISABLED
+
+type ConfigValue = str | int | float | bool
+
+_DEFAULTS: frozendict[str, ConfigValue] = frozendict(
+    base_image=DEFAULT_BASE_IMAGE,
+    cpus=DEFAULT_CPUS,
+    memory_mib=DEFAULT_MEMORY_MIB,
+    root_disk_mib=DEFAULT_ROOT_DISK_MIB,
+    max_concurrent=DEFAULT_MAX_CONCURRENT,
+    network_access=DEFAULT_NETWORK_ACCESS,
+)
+
+_MAX_OUTPUT_BYTES = 64 * 1024
+_RUN = (
+    f"python3 /code.py >/out 2>/err; rc=$?; "
+    f"head -c {_MAX_OUTPUT_BYTES} /out; head -c {_MAX_OUTPUT_BYTES} /err >&2; exit $rc"
+)
+_SLOTS: asyncio.Semaphore | None = None
+
+MAX_PAYLOAD_CHARS = _MAX_OUTPUT_BYTES
+MIN_TIMEOUT = 1
+MAX_TIMEOUT = 30
+
+
+_no_host = False
+
+
+def _slots(limit: int) -> asyncio.Semaphore:
+    """Return the process-wide VM slot semaphore, building it on first use."""
+    global _SLOTS
+    if _SLOTS is None:
+        _SLOTS = asyncio.Semaphore(limit)
+    return _SLOTS
+
+
+async def _settings() -> dict[str, ConfigValue]:
+    """Resolve the admin-set VM settings, falling back to ``_DEFAULTS``."""
+    global _no_host
+    if _no_host:
+        return dict(_DEFAULTS)
+    try:
+        from nexctf.core import appconfig
+        from nexctf.core.cache import get_client
+        from nexctf.plugins import get_plugin_config
+    except ImportError, ValidationError:
+        logger.debug("sandbox.config host unavailable; using defaults", exc_info=True)
+        _no_host = True
+        return dict(_DEFAULTS)
+    except Exception:
+        logger.warning(
+            "sandbox.config host import failed; using defaults", exc_info=True
+        )
+        return dict(_DEFAULTS)
+
+    try:
+        overrides = await appconfig.fetch_overrides(get_client())
+    except Exception:
+        logger.warning("sandbox.config fetch failed; using defaults", exc_info=True)
+        return dict(_DEFAULTS)
+
+    resolved: dict[str, ConfigValue] = {}
+    for key, fallback in _DEFAULTS.items():
+        try:
+            resolved[key] = get_plugin_config(key, overrides, plugin_key=PLUGIN_SLUG)
+        except Exception:
+            logger.warning(
+                "sandbox.config bad key=%s; using default", key, exc_info=True
+            )
+            resolved[key] = fallback
+    return resolved
+
+
+def _network(access: ConfigValue) -> Network:
+    """Build the guest's egress policy from the ``network_access`` setting."""
+    if access == NETWORK_INTERNET:
+        return Network.from_profiles(NetworkProfile.PUBLIC)
+    if access == NETWORK_ALL:
+        return Network.allow_all()
+    if access != NETWORK_DISABLED:
+        logger.warning("sandbox.network unknown access=%r; denying egress", access)
+    return Network.none()
+
+
+@asynccontextmanager
+async def _ephemeral(cfg: dict[str, ConfigValue]):
+    network = _network(cfg["network_access"])
+    root_disk_mib = int(cfg["root_disk_mib"])
+    name = f"nexctf-{uuid4().hex}"
+    sb = None
+    try:
+        sb = await Sandbox.create(
+            name,
+            image=Image.oci(
+                str(cfg["base_image"]), root_disk=RootDisk.tmpfs(root_disk_mib)
+            ),
+            cpus=int(cfg["cpus"]),
+            memory=int(cfg["memory_mib"]) + root_disk_mib,
+            network=network,
+        )
+        yield sb
+    finally:
+        try:
+            if sb is not None:
+                await sb.destroy(force=True)
+            else:
+                await Sandbox.remove(name)
+        except Exception:
+            logger.warning("sandbox.destroy failed name=%s", name, exc_info=True)
+
+
+async def _exec(sb, code: str, stdin: str = "", *, timeout: int) -> tuple[int, str]:
+    """Run *code* in an already-booted microVM. Raises ``ExecTimeoutError`` on timeout."""
+    logger.info("sandbox.start stdin=%s timeout=%ds", bool(stdin), timeout)
+    await sb.fs.write("/code.py", code.encode())
+    result = await sb.shell(
+        _RUN,
+        stdin=stdin.encode() if stdin else None,
+        timeout=float(timeout),
+    )
+    out = result.stdout_text
+    logger.info(
+        "sandbox.run exit_code=%d out=%dB err=%dB",
+        result.exit_code,
+        len(out),
+        len(result.stderr_text),
+    )
+    return result.exit_code, out
+
+
+@asynccontextmanager
+async def python_runner():
+    """Yield ``run(code, stdin, *, timeout) -> (exit_code, stdout)`` on one microVM."""
+    cfg = await _settings()
+    async with _slots(int(cfg["max_concurrent"])), _ephemeral(cfg) as sb:
+        yield partial(_exec, sb)
+
+
+async def run_python(code: str, stdin: str = "", *, timeout: int) -> tuple[int, str]:
+    """Run Python *code* in its own isolated microVM.
+
+    Returns ``(exit_code, stdout)``. Raises ``ExecTimeoutError`` on timeout.
+    """
+    async with python_runner() as run:
+        return await run(code, stdin, timeout=timeout)

nexctf_sandbox-1.0.0/nexctf_sandbox/alembic/versions/0001_init_sandbox.py

@@ -0,0 +1,58 @@
+"""Create solutions_script and solutions_runner tables.
+
+The check constraints bound the cost of one verify(): the schemas enforce the
+same ranges, but fixtures and direct model writes do not go through Pydantic.
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-04-18
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "0001"
+down_revision: str | None = None
+branch_labels = None
+depends_on = None
+
+_TIMEOUT = "timeout BETWEEN 1 AND 30"
+_TEST_CASES = "jsonb_array_length(test_cases) <= 20"
+_CHECKER_CODE = "length(checker_code) <= 65536"
+# 20 cases x (input + expected_output) x 65536: a ceiling on the blob, since a
+# CHECK cannot walk the array to bound each field the way the schema does.
+_TEST_CASES_SIZE = "length(test_cases::text) <= 2621440"
+
+
+def upgrade() -> None:
+    op.create_table(
+        "solutions_script",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("checker_code", sa.Text(), nullable=False),
+        sa.Column("timeout", sa.Integer(), nullable=False, server_default="5"),
+        sa.CheckConstraint(_TIMEOUT, name="ck_solutions_script_timeout"),
+        sa.CheckConstraint(_CHECKER_CODE, name="ck_solutions_script_checker_code"),
+        sa.ForeignKeyConstraint(["id"], ["solutions.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "solutions_runner",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("test_cases", JSONB(), nullable=False, server_default="[]"),
+        sa.Column("timeout", sa.Integer(), nullable=False, server_default="5"),
+        sa.CheckConstraint(_TIMEOUT, name="ck_solutions_runner_timeout"),
+        sa.CheckConstraint(_TEST_CASES, name="ck_solutions_runner_test_cases"),
+        sa.CheckConstraint(
+            _TEST_CASES_SIZE, name="ck_solutions_runner_test_cases_size"
+        ),
+        sa.ForeignKeyConstraint(["id"], ["solutions.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("solutions_runner")
+    op.drop_table("solutions_script")

nexctf_sandbox-1.0.0/nexctf_sandbox/solutions/runner.py

@@ -0,0 +1,134 @@
+"""Runner solution: executes player Python3 code against test cases."""
+
+from __future__ import annotations
+
+import logging
+from uuid import UUID
+
+from fastapi_toolsets.schemas import PydanticBase
+from microsandbox import ExecTimeoutError
+from nexctf.exceptions import SolutionTimeoutError
+from nexctf.model.solution import Solution
+from nexctf.schema.solution import AdminSolutionRead
+from pydantic import Field
+from sqlalchemy import CheckConstraint, ForeignKey
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from nexctf_sandbox._sandbox import (
+    MAX_PAYLOAD_CHARS,
+    MAX_TIMEOUT,
+    MIN_TIMEOUT,
+    python_runner,
+)
+
+logger = logging.getLogger(__name__)
+
+MAX_TEST_CASES = 20  # all of them share one microVM, run one after the other
+
+
+class TestCase(PydanticBase):
+    input: str = Field(
+        default="",
+        max_length=MAX_PAYLOAD_CHARS,
+        title="Input (stdin)",
+        description="Text fed to the program on stdin.",
+    )
+    expected_output: str = Field(
+        max_length=MAX_PAYLOAD_CHARS,
+        title="Expected output",
+        description="Expected stdout, compared after stripping whitespace.",
+    )
+
+
+class RunnerSolutionCreate(PydanticBase):
+    question_id: UUID
+    test_cases: list[TestCase] = Field(
+        default=[],
+        max_length=MAX_TEST_CASES,
+        title="Test cases",
+        description="All test cases must pass for the answer to be accepted.",
+    )
+    timeout: int = Field(
+        default=5,
+        ge=MIN_TIMEOUT,
+        le=MAX_TIMEOUT,
+        title="Timeout (s)",
+        description="Maximum seconds each test case may run.",
+    )
+
+
+class RunnerSolutionUpdate(PydanticBase):
+    id: UUID
+    test_cases: list[TestCase] | None = Field(
+        default=None, max_length=MAX_TEST_CASES, title="Test cases"
+    )
+    timeout: int | None = Field(
+        default=None, ge=MIN_TIMEOUT, le=MAX_TIMEOUT, title="Timeout (s)"
+    )
+
+
+class RunnerSolutionRead(AdminSolutionRead):
+    test_cases: list[TestCase]
+    timeout: int
+
+
+async def run_code(run, code: str, stdin: str, timeout: int) -> str | None:
+    """Execute player *code* on *run*'s microVM and return stdout, or None on error.
+
+    Raises ``ExecTimeoutError`` on timeout: a timeout says nothing about the answer,
+    so it must not be flattened into "wrong".
+    """
+    try:
+        exit_code, stdout = await run(code, stdin, timeout=timeout)
+        return stdout if exit_code == 0 else None
+    except ExecTimeoutError:
+        raise
+    except Exception:
+        logger.exception("runner failed")
+        return None
+
+
+class RunnerSolution(Solution):
+    """Runs submitted Python3 code against a set of test cases (all must pass)."""
+
+    __tablename__ = "solutions_runner"
+    __mapper_args__ = {"polymorphic_identity": "runner"}  # noqa: RUF012 — SQLAlchemy idiom
+    __table_args__ = (
+        CheckConstraint(
+            f"timeout BETWEEN {MIN_TIMEOUT} AND {MAX_TIMEOUT}",
+            name="ck_solutions_runner_timeout",
+        ),
+        CheckConstraint(
+            f"jsonb_array_length(test_cases) <= {MAX_TEST_CASES}",
+            name="ck_solutions_runner_test_cases",
+        ),
+        # Backstop for the per-field max_length above: one ceiling on the whole blob,
+        # because a CHECK cannot walk the array (no subqueries).
+        CheckConstraint(
+            f"length(test_cases::text) <= {MAX_TEST_CASES * 2 * MAX_PAYLOAD_CHARS}",
+            name="ck_solutions_runner_test_cases_size",
+        ),
+    )
+
+    id: Mapped[UUID] = mapped_column(ForeignKey("solutions.id"), primary_key=True)
+    test_cases: Mapped[list[dict]] = mapped_column(JSONB, default=list)
+    timeout: Mapped[int] = mapped_column(default=5)
+
+    async def verify(self, submission: str, *, team_id=None) -> bool:
+        if not self.test_cases:
+            return False
+        try:
+            # One VM for the whole submission: booting one per case cost ~1.1s each.
+            # The cases see each other's guest state; they cannot see another player.
+            async with python_runner() as run:
+                for tc in self.test_cases:
+                    stdin = tc.get("input", "")
+                    expected = tc.get("expected_output", "")
+                    actual = await run_code(run, submission, stdin, self.timeout)
+                    if actual is None or actual.strip() != expected.strip():
+                        return False
+        except ExecTimeoutError as exc:
+            logger.warning("runner timed out solution_id=%s", self.id)
+            raise SolutionTimeoutError(self.id) from exc
+        return True

nexctf_sandbox-1.0.0/nexctf_sandbox/solutions/script.py

@@ -0,0 +1,255 @@
+"""Script checker solution: runs an admin-provided Python checker in a microVM."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Annotated, Any
+from uuid import UUID
+
+from fastapi_toolsets.schemas import PydanticBase
+from microsandbox import ExecTimeoutError
+from nexctf.exceptions import SolutionTimeoutError
+from nexctf.model.custom_field import (
+    CustomFieldDefinition,
+    CustomFieldTarget,
+    CustomFieldType,
+    CustomFieldValue,
+)
+from nexctf.model.solution import Solution
+from nexctf.schema.solution import AdminSolutionRead
+from nexctf.util.pydantic import CodeStr, DynamicDefault
+from pydantic import Field
+from sqlalchemy import CheckConstraint, ForeignKey, Text, select
+from sqlalchemy.ext.asyncio import AsyncSession, async_object_session
+from sqlalchemy.orm import Mapped, mapped_column
+lazy from nexctf.core.db import get_db_context
+
+from nexctf_sandbox._sandbox import (
+    MAX_PAYLOAD_CHARS,
+    MAX_TIMEOUT,
+    MIN_TIMEOUT,
+    run_python,
+)
+
+logger = logging.getLogger(__name__)
+
+_CHECK_SIGNATURE = (
+    "def check(answer: str, team_id: str | None, team_fields: dict) -> bool:\n"
+)
+_CHECK_BODY = '    return answer.strip() == "expected_answer"\n'
+_DEFAULT_CHECKER = _CHECK_SIGNATURE + _CHECK_BODY
+
+# team_fields goes by name, and only to a checker that can take it: a checker
+# written before it existed, even check(answer, team_id, strict=False), is unchanged.
+_WRAPPER = """\
+import sys as _sys
+import json as _json
+import inspect as _inspect
+
+{checker_code}
+
+_data = _json.load(_sys.stdin)
+_args = (_data["answer"], _data.get("team_id"))
+_kwargs = {{"team_fields": _data.get("team_fields") or {{}}}}
+try:
+    _inspect.signature(check).bind(*_args, **_kwargs)
+except (TypeError, ValueError):
+    _kwargs = {{}}
+_result = check(*_args, **_kwargs)
+_sys.exit(0 if bool(_result) else 1)
+"""
+
+_CHECKER_DESCRIPTION = (
+    "Python function check(answer, team_id, team_fields) → bool. Return True to accept "
+    "the answer. team_fields maps each team custom field name to its value (int, bool "
+    "or str); declare it only if the checker needs it."
+)
+
+# Label shown in the starter checker, and the parser applied before the checker runs.
+_FIELD_TYPES: frozendict[CustomFieldType, tuple[str, Callable[[str], Any]]] = (
+    frozendict(
+        {
+            CustomFieldType.integer: ("int", int),
+            CustomFieldType.boolean: ("bool", lambda value: value.lower() == "true"),
+        }
+    )
+)
+_STR_FIELD = ("str", str)
+
+
+def checker_template(fields: list[tuple[str, CustomFieldType]]) -> str:
+    """Return the default checker, with a comment listing the team custom fields."""
+    if not fields:
+        return _DEFAULT_CHECKER
+    # repr() keeps a field name from ending the comment line or the string.
+    lines = [
+        f"    #   team_fields[{name!r}]: {_FIELD_TYPES.get(ftype, _STR_FIELD)[0]}\n"
+        for name, ftype in fields
+    ]
+    header = (
+        "    # Team custom fields (a key is missing when the team left it empty):\n"
+    )
+    return "".join([_CHECK_SIGNATURE, header, *lines, _CHECK_BODY])
+
+
+def _db_context():
+    return get_db_context()
+
+
+async def _default_checker() -> str:
+    """Build the starter checker when the admin form asks for the schema."""
+    try:
+        async with _db_context() as session:
+            rows = await session.execute(
+                select(CustomFieldDefinition.name, CustomFieldDefinition.field_type)
+                .where(CustomFieldDefinition.target == CustomFieldTarget.team)
+                .order_by(CustomFieldDefinition.name)
+            )
+            return checker_template(list(rows))
+    except Exception:
+        # A missing hint must not take the whole solution form down with it.
+        logger.warning("script.checker template without team fields", exc_info=True)
+        return _DEFAULT_CHECKER
+
+
+class ScriptSolutionCreate(PydanticBase):
+    question_id: UUID
+    checker_code: Annotated[CodeStr, DynamicDefault(_default_checker)] = Field(
+        default=_DEFAULT_CHECKER,
+        max_length=MAX_PAYLOAD_CHARS,
+        title="Checker function",
+        description=_CHECKER_DESCRIPTION,
+    )
+    timeout: int = Field(
+        default=5,
+        ge=MIN_TIMEOUT,
+        le=MAX_TIMEOUT,
+        title="Timeout (s)",
+        description="Maximum seconds the checker may run before being killed.",
+    )
+
+
+class ScriptSolutionUpdate(PydanticBase):
+    id: UUID
+    checker_code: CodeStr | None = Field(
+        default=None,
+        max_length=MAX_PAYLOAD_CHARS,
+        title="Checker function",
+        description=_CHECKER_DESCRIPTION,
+    )
+    timeout: int | None = Field(
+        default=None,
+        ge=MIN_TIMEOUT,
+        le=MAX_TIMEOUT,
+        title="Timeout (s)",
+        description="Maximum seconds the checker may run before being killed.",
+    )
+
+
+class ScriptSolutionRead(AdminSolutionRead):
+    checker_code: CodeStr
+    timeout: int
+
+
+def _field_value(field_type: CustomFieldType, value: str | None) -> Any:
+    if value is None:
+        return None
+    _, parse = _FIELD_TYPES.get(field_type, _STR_FIELD)
+    try:
+        return parse(value)
+    except ValueError:
+        return value  # written before its type changed; hand over the raw string
+
+
+async def load_team_fields(session: AsyncSession, team_id: UUID) -> dict[str, Any]:
+    """Return every custom field value of *team_id*, keyed by field name.
+
+    Private fields are included: the checker is admin code, and per-team secrets
+    or seeds are the point of passing fields at all.
+    """
+    rows = await session.execute(
+        select(
+            CustomFieldDefinition.name,
+            CustomFieldDefinition.field_type,
+            CustomFieldValue.value,
+        )
+        .join(
+            CustomFieldDefinition,
+            CustomFieldValue.definition_id == CustomFieldDefinition.id,
+        )
+        .where(CustomFieldValue.team_id == team_id)
+    )
+    return {name: _field_value(ftype, value) for name, ftype, value in rows}
+
+
+async def run_checker(
+    checker_code: str,
+    answer: str,
+    team_id: UUID | None,
+    timeout: int,
+    *,
+    session: AsyncSession | None = None,
+) -> bool:
+    code = _WRAPPER.format(checker_code=checker_code)
+    if session is None and team_id is not None:
+        # A detached solution has nothing to read from, and opening a connection
+        # of our own would starve the pool: the checker sees no fields at all.
+        logger.warning(
+            "script.checker no session, team_fields empty team_id=%s", team_id
+        )
+    try:
+        team_fields = (
+            await load_team_fields(session, team_id)
+            if session is not None and team_id is not None
+            else {}
+        )
+        stdin = json.dumps(
+            {
+                "answer": answer,
+                "team_id": str(team_id) if team_id else None,
+                "team_fields": team_fields,
+            }
+        )
+        exit_code, _ = await run_python(code, stdin, timeout=timeout)
+        return exit_code == 0
+    except ExecTimeoutError:
+        raise
+    except Exception:
+        logger.exception("script.checker failed team_id=%s", team_id)
+        return False
+
+
+class ScriptSolution(Solution):
+    """Custom checker: admin provides a Python check(answer, team_id, team_fields) -> bool function."""
+
+    __tablename__ = "solutions_script"
+    __mapper_args__ = {"polymorphic_identity": "script"}  # noqa: RUF012 — SQLAlchemy idiom
+    __table_args__ = (
+        CheckConstraint(
+            f"timeout BETWEEN {MIN_TIMEOUT} AND {MAX_TIMEOUT}",
+            name="ck_solutions_script_timeout",
+        ),
+        CheckConstraint(
+            f"length(checker_code) <= {MAX_PAYLOAD_CHARS}",
+            name="ck_solutions_script_checker_code",
+        ),
+    )
+
+    id: Mapped[UUID] = mapped_column(ForeignKey("solutions.id"), primary_key=True)
+    checker_code: Mapped[str] = mapped_column(Text)
+    timeout: Mapped[int] = mapped_column(default=5)
+
+    async def verify(self, submission: str, *, team_id: UUID | None = None) -> bool:
+        try:
+            return await run_checker(
+                self.checker_code,
+                submission,
+                team_id,
+                self.timeout,
+                session=async_object_session(self),
+            )
+        except ExecTimeoutError as exc:
+            logger.warning("script.checker timed out solution_id=%s", self.id)
+            raise SolutionTimeoutError(self.id) from exc

nexctf_sandbox-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "nexctf-sandbox"
+version = "1.0.0"
+description = "Sandboxed code execution for NexCTF, script checker and code runner via microsandbox microVMs."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "nexctf",
+    "ctf",
+    "sandbox",
+    "microvm",
+    "plugin",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Education",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Security",
+]
+requires-python = ">=3.15"
+dependencies = [
+    "microsandbox>=0.7.8",
+    "nexctf>=0.12,<0.13",
+]
+
+[[project.authors]]
+name = "NexCTF"
+email = "contact@nexctf.dev"
+
+[project.urls]
+Homepage = "https://github.com/NexCTF/Sandbox"
+Repository = "https://github.com/NexCTF/Sandbox"
+Issues = "https://github.com/NexCTF/Sandbox/issues"
+
+[project.entry-points."nexctf.plugins"]
+nexctf_sandbox = "nexctf_sandbox"
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["live: boots a real microVM, needs /dev/kvm"]
+addopts = "-m 'not live'"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.17.0",
+    "ty>=0.0.86",
+    "nexctf @ git+https://github.com/NexCTF/NexCTF.git@v0.12.0#subdirectory=backend",
+]

nexctf_sandbox-1.0.0/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "nexctf-sandbox"
+version = "1.0.0"
+description = "Sandboxed code execution for NexCTF, script checker and code runner via microsandbox microVMs."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "NexCTF", email = "contact@nexctf.dev" }
+]
+keywords = ["nexctf", "ctf", "sandbox", "microvm", "plugin"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Education",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Security",
+]
+requires-python = ">=3.15"
+dependencies = [
+    "microsandbox>=0.7.8",
+    "nexctf>=0.12,<0.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/NexCTF/Sandbox"
+Repository = "https://github.com/NexCTF/Sandbox"
+Issues = "https://github.com/NexCTF/Sandbox/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.17.0",
+    "ty>=0.0.86",
+    "nexctf @ git+https://github.com/NexCTF/NexCTF.git@v0.12.0#subdirectory=backend",
+]
+
+[project.entry-points."nexctf.plugins"]
+nexctf_sandbox = "nexctf_sandbox"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "live: boots a real microVM, needs /dev/kvm",
+]
+addopts = "-m 'not live'"  # opt in with: pytest -m live