ctfy.sdk.resources.instances

  1"""``client.instances`` — launch, control, status, attachments, traffic.
  2
  3Flat ``/instances/{id}`` ops plus the per-competition scoped twins
  4(``*_scoped``) for callers who play in more than one competition and must
  5address an instance unambiguously.
  6"""
  7
  8from __future__ import annotations
  9
 10import builtins
 11from collections.abc import Iterator
 12from typing import Any
 13
 14from ctfy.sdk._helpers import (
 15    InstanceReadyResult,
 16    _extract_items,
 17    _poll_instance_ready,
 18    _raise_for_status,
 19)
 20from ctfy.sdk.base import BaseHttpClient
 21from ctfy.server.models import (
 22    AttachmentList,
 23    InstanceInfo,
 24    InstanceQuestionInfo,
 25    InstanceStatusResponse,
 26    RenewResponse,
 27    StartResponse,
 28)
 29
 30
 31class InstancesResource:
 32    """Start / inspect / tear down challenge instances."""
 33
 34    def __init__(self, http: BaseHttpClient) -> None:
 35        self._http = http
 36
 37    def start(
 38        self,
 39        challenge_id: str,
 40        ttl: int | None = None,
 41        *,
 42        competition_id: str = "",
 43        timeout: int = 300,
 44        poll_interval: float = 2.0,
 45        proxy_output_dir: str | None = None,
 46    ) -> InstanceReadyResult:
 47        """Start instance and wait until ready.
 48
 49        Returns InstanceReadyResult with attack surface + sandbox network info.
 50        The .surface attribute provides backward compatibility.
 51
 52        Args:
 53            challenge_id: Challenge ID (e.g., "XBOW-047").
 54            ttl: Per-instance TTL override in seconds. ``None`` (the
 55                default) delegates to the platform's
 56                ``default_instance_ttl_s`` setting (admin-tunable,
 57                currently 24h). Explicit values are clamped to the
 58                platform's ``max_instance_ttl_s``.
 59            competition_id: Which competition to spin the instance up
 60                under. Required when the calling user is on more than
 61                one team — agents tied to a single comp can leave it
 62                empty and the server picks the unambiguous team.
 63            timeout: Max seconds to wait for ready.
 64            poll_interval: Seconds between status polls.
 65            proxy_output_dir: Host path to store proxy traffic captures.
 66        """
 67        body: dict[str, Any] = {
 68            "challenge_id": challenge_id,
 69            "competition_id": competition_id,
 70        }
 71        if ttl is not None:
 72            body["ttl"] = ttl
 73        if proxy_output_dir:
 74            body["proxy_output_dir"] = proxy_output_dir
 75        resp = self._http.request("POST", "/instances", json=body)
 76        _raise_for_status(resp)
 77        start = StartResponse.model_validate(resp.json())
 78
 79        return _poll_instance_ready(
 80            self._http._client, start.id, timeout=timeout, poll_interval=poll_interval
 81        )
 82
 83    def get(self, instance_id: str) -> InstanceInfo:
 84        """Get the full ``InstanceInfo`` for one running instance.
 85
 86        Carries the per-instance ``questions`` list with each question's
 87        ``unlocked`` / ``answered_correctly`` / ``attempts_remaining``
 88        state — the surface multi-milestone solvers iterate on. The
 89        prompt is empty for still-locked questions so the route hint
 90        doesn't leak before the prerequisite is solved.
 91
 92        See :meth:`status` for the lighter status-only payload (no
 93        questions, no spec metadata) used by polling loops.
 94        """
 95        resp = self._http.request("GET", f"/instances/{instance_id}")
 96        _raise_for_status(resp)
 97        return InstanceInfo.model_validate(resp.json())
 98
 99    def iter_pending_questions(self, instance_id: str) -> Iterator[InstanceQuestionInfo]:
100        """Yield each currently-pending question on a running instance.
101
102        "Pending" = unlocked (the ``requires:`` chain is satisfied)
103        and not yet correctly answered by the calling team. After
104        every batch is exhausted, re-fetches ``InstanceInfo`` so
105        newly-unlocked questions (whose prerequisite was just solved
106        by the consumer) flow through on the next iteration.
107
108        Terminates on either:
109
110        * no pending questions left — the natural "challenge fully
111          solved" exit;
112        * **no progress** — the same set of pending question ids
113          comes back twice in a row, meaning the consumer's solver
114          isn't capturing anything. Stops silently rather than
115          infinite-looping; inspect the caller's last :meth:`get` to
116          see what's still stuck.
117
118        This is the ergonomic helper for the common multi-milestone
119        loop::
120
121            for q in client.instances.iter_pending_questions(instance_id):
122                ans = my_solver(q.prompt)
123                client.submissions.submit(instance_id, ans, question_id=q.id)
124
125        Args:
126            instance_id: The instance to walk.
127        """
128        previous_pending_ids: frozenset[str] | None = None
129        while True:
130            info = self.get(instance_id)
131            pending = [q for q in info.questions if q.unlocked and not q.answered_correctly]
132            if not pending:
133                return
134
135            pending_ids = frozenset(q.id for q in pending)
136            if pending_ids == previous_pending_ids:
137                # Solver made no progress against the last batch — stop
138                # rather than spin. The consumer can re-call this method
139                # later (after fixing their solver) to pick up where
140                # they left off.
141                return
142            previous_pending_ids = pending_ids
143
144            yield from pending
145
146    def status(self, instance_id: str) -> InstanceStatusResponse:
147        """Get instance status and attack surface."""
148        resp = self._http.request("GET", f"/instances/{instance_id}/status")
149        _raise_for_status(resp)
150        return InstanceStatusResponse.model_validate(resp.json())
151
152    def stop(self, instance_id: str) -> None:
153        """Tear down ``instance_id``. Idempotent: a 404 from the server
154        means the instance is already gone (auto-stopped after solve,
155        TTL expiry, admin teardown) and is treated as success."""
156        resp = self._http.request("DELETE", f"/instances/{instance_id}")
157        if resp.status_code != 404:
158            _raise_for_status(resp)
159
160    def renew(self, instance_id: str, ttl: int | None = None) -> RenewResponse:
161        """Extend the TTL of a running instance.
162
163        ``ttl=None`` (the default) delegates to the platform's
164        ``default_instance_ttl_s`` setting. Explicit values are
165        clamped to ``max_instance_ttl_s``.
166        """
167        params: dict[str, Any] = {}
168        if ttl is not None:
169            params["ttl"] = ttl
170        resp = self._http.request("POST", f"/instances/{instance_id}/renew", params=params)
171        _raise_for_status(resp)
172        return RenewResponse.model_validate(resp.json())
173
174    def list(
175        self,
176        challenge_id: str = "",
177        status: str = "",
178        q: str = "",
179        offset: int = 0,
180        limit: int = 50,
181    ) -> builtins.list[InstanceInfo]:
182        """List all running instances."""
183        params: dict[str, Any] = {"offset": offset, "limit": limit}
184        if challenge_id:
185            params["challenge_id"] = challenge_id
186        if status:
187            params["status"] = status
188        if q:
189            params["q"] = q
190        resp = self._http.request("GET", "/instances", params=params)
191        _raise_for_status(resp)
192        return _extract_items(resp.json(), InstanceInfo)
193
194    def attachments(self, instance_id: str) -> AttachmentList:
195        """List per-instance (post-launch) attachments.
196
197        For challenges with ``attachments/<name>.tpl`` Jinja templates
198        the names + sizes here are the *rendered* per-team-unique
199        siblings; for ones with only static attachments the list is
200        the same as :meth:`ChallengesResource.attachments`.
201        """
202        resp = self._http.request("GET", f"/instances/{instance_id}/attachments")
203        _raise_for_status(resp)
204        return AttachmentList.model_validate(resp.json())
205
206    def download_attachment(self, instance_id: str, filename: str) -> bytes:
207        """Download one per-instance attachment as raw bytes.
208
209        For challenges with per-team Jinja templates this returns the
210        team-specific render; for static attachments it's the same
211        bytes as :meth:`ChallengesResource.download_attachment` would yield.
212        """
213        resp = self._http.request("GET", f"/instances/{instance_id}/attachments/{filename}")
214        _raise_for_status(resp)
215        return resp.content
216
217    def openvpn_config(self, instance_id: str) -> bytes:
218        """Download the per-instance OpenVPN client config as raw bytes.
219
220        Only meaningful for challenges that declare
221        ``network_topology: engagement`` in metadata.yaml. The body is
222        the rendered ``.ovpn`` file the player or automated agent
223        passes to ``openvpn --config …`` to land on the challenge's
224        DMZ docker network. The platform serves a 404 for simple-mode
225        instances.
226
227        Raises a ``CTFyError`` (404) when the challenge isn't an
228        engagement-mode one, when the instance hasn't yet reached the
229        running state, or when the node's openvpn container hasn't
230        finished its PKI bootstrap.
231        """
232        resp = self._http.request("GET", f"/instances/{instance_id}/openvpn-config")
233        _raise_for_status(resp)
234        return resp.content
235
236    def traffic(self, instance_id: str, *, competition_id: str = "") -> dict[str, Any]:
237        """Parsed mitmproxy traffic for a running instance. The flow
238        file lives on the worker node; the platform proxies the fetch.
239
240        Returns an empty dict when no capture exists (sidecar disabled,
241        node offline, instance never reached running) so callers can
242        persist conditionally without try/except.
243        """
244        params = {"competition_id": competition_id} if competition_id else {}
245        resp = self._http.request("GET", f"/instances/{instance_id}/traffic", params=params)
246        _raise_for_status(resp)
247        data = resp.json()
248        return data if isinstance(data, dict) else {}