ctfy.sdk.resources.submissions

  1"""``client.submissions`` — graded submit, oracle verify, QA challenges."""
  2
  3from __future__ import annotations
  4
  5import base64
  6import builtins
  7from typing import Any
  8
  9from ctfy.core.state.models import SubmissionState
 10from ctfy.sdk._helpers import PagedList, _extract_items, _raise_for_status
 11from ctfy.sdk.base import BaseHttpClient
 12from ctfy.server.models import (
 13    CheckAnswerResponse,
 14    DefenceSource,
 15    PatchSubmissionInfo,
 16    QaChallengeView,
 17    SubmissionResponse,
 18    VerifyAnswerResponse,
 19)
 20
 21
 22class SubmissionsResource:
 23    """Answer submission (graded), oracle verification (no record), and QA."""
 24
 25    def __init__(self, http: BaseHttpClient) -> None:
 26        self._http = http
 27
 28    def submit(
 29        self,
 30        instance_id: str,
 31        answer: str | builtins.list[str],
 32        *,
 33        question_id: str = "flag",
 34    ) -> SubmissionResponse:
 35        """Submit ``answer`` against ``question_id`` on ``instance_id``.
 36
 37        The server reads challenge_id, team_id and competition_id off
 38        the instance row; the calling user must be on the same team
 39        that started this instance (in the same competition).
 40
 41        ``question_id`` defaults to ``"flag"`` for single-question
 42        challenges (the most common case). Multi-question challenges
 43        (see :class:`ChallengeInfo.questions`) require an explicit id.
 44        ``answer`` is a single string for dynamic / static /
 45        single_select questions and a list of strings for multi_select.
 46        """
 47        resp = self._http.request(
 48            "POST",
 49            "/submissions",
 50            json={
 51                "instance_id": instance_id,
 52                "question_id": question_id,
 53                "answer": answer,
 54            },
 55        )
 56        _raise_for_status(resp)
 57        return SubmissionResponse.model_validate(resp.json())
 58
 59    def verify(
 60        self,
 61        instance_id: str,
 62        answer: str | builtins.list[str],
 63        *,
 64        question_id: str = "flag",
 65    ) -> VerifyAnswerResponse:
 66        """Server-side answer verification — no submission record.
 67
 68        Same grader as :meth:`submit` (mode-aware,
 69        ``$ANSWER_<UPPER_ID>`` tolerance for dynamic, set-equal for
 70        ``multi_select``, etc.) but writes nothing to the audit log.
 71        Use for oracle-style probes; for graded competitions use
 72        :meth:`submit`.
 73
 74        Returns :class:`VerifyAnswerResponse` with ``.correct`` and
 75        ``.question_id`` (the latter echoed on a correct match).
 76        """
 77        resp = self._http.request(
 78            "POST",
 79            f"/instances/{instance_id}/verify-answer",
 80            json={"question_id": question_id, "answer": answer},
 81        )
 82        _raise_for_status(resp)
 83        return VerifyAnswerResponse.model_validate(resp.json())
 84
 85    def check(
 86        self,
 87        instance_id: str,
 88        *,
 89        question_id: str = "flag",
 90    ) -> CheckAnswerResponse:
 91        """Run the checker for a *checker-mode* question (proof-of-exploitation).
 92
 93        The platform execs the question's author-supplied checker inside
 94        the trusted judge sidecar and records a solve iff the sidecar emits
 95        this instance's minted token — the player submits no answer string.
 96        Fails closed: a failed / timed-out / missing checker returns
 97        ``passed=False`` and records nothing.
 98
 99        Returns :class:`CheckAnswerResponse` with ``.passed`` and, on a
100        fresh solve, ``.solve_rank`` / ``.challenge_fully_solved``.
101        """
102        resp = self._http.request(
103            "POST",
104            f"/instances/{instance_id}/check",
105            json={"question_id": question_id},
106        )
107        _raise_for_status(resp)
108        return CheckAnswerResponse.model_validate(resp.json())
109
110    def list(
111        self, challenge_id: str = "", offset: int = 0, limit: int = 50
112    ) -> PagedList[SubmissionState]:
113        """List current team's submissions."""
114        params: dict[str, Any] = {"offset": offset, "limit": limit}
115        if challenge_id:
116            params["challenge_id"] = challenge_id
117        resp = self._http.request("GET", "/submissions", params=params)
118        _raise_for_status(resp)
119        return _extract_items(resp.json(), SubmissionState)
120
121    def submit_qa(
122        self,
123        challenge_id: str,
124        competition_id: str,
125        answer: str | builtins.list[str],
126        *,
127        question_id: str = "answer",
128    ) -> SubmissionResponse:
129        """Submit ``answer`` against a pure question-answer challenge.
130
131        Unlike :meth:`submit`, QA challenges have no instance — the
132        caller passes ``challenge_id`` + ``competition_id`` explicitly,
133        and the server resolves the team for the competition via the
134        standard auth helper. ``question_id`` defaults to ``"answer"``
135        (the canonical id for MCQ items produced by ``ctfy-admin
136        challenge import``).
137        """
138        resp = self._http.request(
139            "POST",
140            "/qa/submissions",
141            json={
142                "challenge_id": challenge_id,
143                "competition_id": competition_id,
144                "question_id": question_id,
145                "answer": answer,
146            },
147        )
148        _raise_for_status(resp)
149        return SubmissionResponse.model_validate(resp.json())
150
151    def list_qa_challenges(self, competition_id: str) -> builtins.list[QaChallengeView]:
152        """All QA challenges in scope of one competition + team status.
153
154        Returns one :class:`QaChallengeView` per challenge with the
155        calling team's per-question solve / wrong-attempt state
156        pre-joined. The quiz UI renders the full surface from this
157        single response.
158        """
159        resp = self._http.request(
160            "GET", "/qa/challenges", params={"competition_id": competition_id}
161        )
162        _raise_for_status(resp)
163        data = resp.json()
164        return [QaChallengeView.model_validate(item) for item in data]
165
166
167class PatchesResource:
168    """``client.patches`` — AWD+ defence submissions.
169
170    Submitting is not judging: the platform records the patch and a
171    worker builds and rules on it later, so :meth:`submit` returns a
172    ``pending`` row and :meth:`list` is how a client watches for the
173    verdict.
174    """
175
176    def __init__(self, http: BaseHttpClient) -> None:
177        self._http = http
178
179    def source(self, challenge_id: str) -> dict[str, bytes]:
180        """The patchable source, decoded — what a defender starts from.
181
182        AWD+ gives every team the same vulnerable service *and its
183        source*; this is that. Returns exactly the challenge's
184        ``patch.targets``, keyed by challenge-relative path, and
185        deliberately **not** the benchmark tree — the reference exploit
186        and the checker live there too.
187
188        Decoded here so it pairs with :meth:`submit`, which takes bytes:
189        ``patches.submit(inst, patches.source(chal) | {p: fixed})`` is
190        the whole round trip.
191
192        Challenge-scoped, so it works before an instance exists and
193        after the event ends — which is what makes upsolve possible.
194        """
195        resp = self._http.request("GET", f"/challenges/{challenge_id}/defence/source")
196        _raise_for_status(resp)
197        payload = DefenceSource.model_validate(resp.json())
198        return {path: base64.b64decode(blob) for path, blob in payload.files.items()}
199
200    def submit(self, instance_id: str, files: dict[str, bytes]) -> PatchSubmissionInfo:
201        """Submit replacement files for ``instance_id``'s challenge.
202
203        ``files`` maps a **challenge-relative** path to its new bytes.
204        Only paths the challenge's ``patch.targets`` whitelist covers are
205        accepted; anything else is refused on this call rather than at
206        judge time, so the caller learns which file was rejected without
207        waiting for a build.
208
209        Encoding is handled here: the wire carries base64 because a
210        patch target may legitimately be binary.
211        """
212        resp = self._http.request(
213            "POST",
214            "/patches",
215            json={
216                "instance_id": instance_id,
217                "files": {
218                    path: base64.b64encode(content).decode() for path, content in files.items()
219                },
220            },
221        )
222        _raise_for_status(resp)
223        return PatchSubmissionInfo.model_validate(resp.json())
224
225    def submit_for_challenge(
226        self,
227        challenge_id: str,
228        files: dict[str, bytes],
229        *,
230        competition_id: str = "",
231    ) -> PatchSubmissionInfo:
232        """Submit a patch with **no box running**.
233
234        :meth:`source` has always worked before an instance exists and
235        after the event ends — that is what its own docstring calls the
236        thing that makes upsolve possible — while :meth:`submit`
237        required an instance, so the round trip it advertises had a
238        broken second half. This is that half: upsolve, virtual
239        participation, and a defender fixing a challenge after their box
240        expired.
241
242        A separate method rather than an optional ``instance_id``: the
243        two are different addressings, not a default, and the split
244        keeps them as obvious as :meth:`submit` versus
245        :meth:`submit_live`.
246
247        The credited team comes from the caller's own membership for
248        ``competition_id`` — there is no team on the wire — so this is
249        no weaker than naming a box you own.
250        """
251        resp = self._http.request(
252            "POST",
253            "/patches",
254            json={
255                "challenge_id": challenge_id,
256                "competition_id": competition_id,
257                "files": {
258                    path: base64.b64encode(content).decode() for path, content in files.items()
259                },
260            },
261        )
262        _raise_for_status(resp)
263        return PatchSubmissionInfo.model_validate(resp.json())
264
265    def submit_live(self, instance_id: str) -> PatchSubmissionInfo:
266        """Submit whatever is *currently in the box* — no payload.
267
268        The channel an AWD player actually uses: SSH in, edit in place,
269        then ask the platform to read the result back and judge it. The
270        platform decides which paths to read, from the challenge's
271        pristine source tree — the box never gets to nominate what is
272        graded.
273
274        Requires the challenge to declare a ``patch.live`` block;
275        without one the platform answers ``patch_live_unsupported`` and
276        the upload form is the only channel.
277        """
278        resp = self._http.request(
279            "POST",
280            "/patches",
281            json={"instance_id": instance_id, "source": "live"},
282        )
283        _raise_for_status(resp)
284        return PatchSubmissionInfo.model_validate(resp.json())
285
286    def list(self, *, challenge_id: str = "") -> builtins.list[PatchSubmissionInfo]:
287        """This team's defence history, newest first.
288
289        Carries each submission's status and verdict but not its code —
290        the stored row keeps the bytes so a verdict can be re-derived,
291        while this is a status view that gets polled.
292        """
293        params = {"challenge_id": challenge_id} if challenge_id else {}
294        resp = self._http.request("GET", "/patches", params=params)
295        _raise_for_status(resp)
296        return [PatchSubmissionInfo.model_validate(row) for row in resp.json()]