ctfy.sdk.admin_resources.challenges

  1"""``client.admin.challenges`` — catalog rescan, pre-build, stats, feedback audit."""
  2
  3from __future__ import annotations
  4
  5from datetime import datetime
  6from typing import Any
  7
  8from ctfy.sdk._helpers import PagedList, _extract_items, _raise_for_status
  9from ctfy.sdk.base import BaseHttpClient
 10from ctfy.server.models import (
 11    AdminChallengeLatencyBucket,
 12    AdminChallengeQuestions,
 13    AdminChallengeSolveStatsRow,
 14    AdminChallengeStatsRow,
 15    AdminChallengeTimeseries,
 16    AdminFeedbackRow,
 17    AdminTaskInfo,
 18    ChallengeBlueprint,
 19    ChallengeBuildStateResponse,
 20    ChallengePullStateResponse,
 21    DeceptionStats,
 22    LlmBudgetPage,
 23    LlmBudgetResetInfo,
 24    QuestionAttemptResetInfo,
 25    RangeProgress,
 26    RangeReplay,
 27)
 28
 29
 30class AdminChallengesResource:
 31    """Operator challenge tooling: reload the catalog, pre-build on nodes,
 32    inspect attempt/solve stats, audit feedback, reset attempt caps."""
 33
 34    def __init__(self, http: BaseHttpClient) -> None:
 35        self._http = http
 36
 37    def export_harbor(self, challenge_id: str) -> bytes:
 38        """Download a Harbor task tar.gz from the platform's local source.
 39
 40        Platform administrator session required. Contains reference sources
 41        and grading data; unsupported task features return 409.
 42        """
 43        resp = self._http.request("GET", f"/admin/challenges/{challenge_id}/export/harbor")
 44        _raise_for_status(resp)
 45        return resp.content
 46
 47    def rescan(self) -> AdminTaskInfo:
 48        """Submit a catalog-rescan background task (reload the platform's
 49        spec cache + fan the rescan out to every online node). Returns the
 50        task record; poll ``admin.tasks.get(id)`` (or watch the Tasks page)
 51        for the per-node outcome in ``result``. Wraps
 52        ``POST /admin/challenges/rescan``."""
 53        resp = self._http.request("POST", "/admin/challenges/rescan")
 54        _raise_for_status(resp)
 55        return AdminTaskInfo.model_validate(resp.json())
 56
 57    def build(self, challenge_id: str) -> AdminTaskInfo:
 58        """Submit a single-challenge pre-build background task.
 59
 60        Fans the build out to every online node and polls it to
 61        completion; poll :meth:`build_state` (or the Tasks surface) to
 62        watch ``building`` → ``built`` / ``failed``. Returns the task
 63        record. Wraps ``POST /admin/challenges/{id}/build``."""
 64        resp = self._http.request("POST", f"/admin/challenges/{challenge_id}/build")
 65        _raise_for_status(resp)
 66        return AdminTaskInfo.model_validate(resp.json())
 67
 68    def build_all(self, *, competition_id: str = "") -> AdminTaskInfo:
 69        """Submit a bulk pre-build background task. With ``competition_id``
 70        the build is scoped to that competition's effective challenge set;
 71        otherwise the whole catalog. The task kicks each online node off
 72        and polls them to completion; the per-node outcome + final
 73        per-challenge status land in ``result``. Returns the task record.
 74        Wraps ``POST /admin/challenges/build-all``."""
 75        params: dict[str, Any] = {}
 76        if competition_id:
 77            params["competition_id"] = competition_id
 78        resp = self._http.request("POST", "/admin/challenges/build-all", params=params)
 79        _raise_for_status(resp)
 80        return AdminTaskInfo.model_validate(resp.json())
 81
 82    def build_push(
 83        self,
 84        *,
 85        bucket: str = "",
 86        challenge_ids: list[str] | None = None,
 87        node_id: str = "",
 88    ) -> AdminTaskInfo:
 89        """Submit a build-and-push task: freeze the scoped challenges'
 90        ``build:`` services into the registry (Layer 2 P0, producer side).
 91
 92        An explicit scope is **required** — a ``bucket`` (family such as
 93        ``XBOW``) or ``challenge_ids`` — or the server refuses it (400); it
 94        never freezes the whole catalog. ``node_id`` pins the build host
 95        (default: the first online node running each challenge).
 96        Super-admin. Returns the task record. Wraps
 97        ``POST /admin/challenges/build-push``."""
 98        body: dict[str, Any] = {
 99            "bucket": bucket,
100            "challenge_ids": challenge_ids or [],
101            "node_id": node_id,
102        }
103        resp = self._http.request("POST", "/admin/challenges/build-push", json=body)
104        _raise_for_status(resp)
105        return AdminTaskInfo.model_validate(resp.json())
106
107    def questions(self, challenge_id: str) -> AdminChallengeQuestions:
108        """Every milestone a challenge declares, gated ones included.
109
110        The catalog projection omits questions behind ``requires`` so a
111        player cannot read a challenge's attack chain off its public page;
112        this is the organiser's way back in — "which milestones exist, and
113        why did this team not get credit for one". Wraps
114        ``GET /admin/challenges/{id}/questions``."""
115        resp = self._http.request("GET", f"/admin/challenges/{challenge_id}/questions")
116        _raise_for_status(resp)
117        return AdminChallengeQuestions.model_validate(resp.json())
118
119    def blueprint(self, challenge_id: str) -> ChallengeBlueprint:
120        """A range's estate and kill chain, for the people running it.
121
122        The sibling :meth:`questions` answers *which milestones exist*;
123        at four services that is the whole picture and at forty it is a
124        flat list with no shape. This adds the two axes a large range is
125        actually debugged along: which network segment each service sits
126        on (and so what can only be reached through a foothold), and
127        what has to fall before each milestone.
128
129        Derived server-side from the challenge's own ``metadata.yaml``
130        and ``docker-compose.yml``, so it works for a hand-built range
131        and a generated one alike. Carries no groundtruth: see
132        :meth:`ctfy.sdk.admin_resources.records.RecordsResource.instance_answers`
133        for the value of a minted answer. Wraps
134        ``GET /admin/challenges/{id}/blueprint``."""
135        resp = self._http.request("GET", f"/admin/challenges/{challenge_id}/blueprint")
136        _raise_for_status(resp)
137        return ChallengeBlueprint.model_validate(resp.json())
138
139    def range_progress(self, competition_id: str, challenge_id: str) -> RangeProgress:
140        """Where every team of one competition is on one range.
141
142        :meth:`blueprint` says what the range *is*; this says where each
143        team got to on it — which milestones they hold, where they are
144        stopped, what they could take next, and which estate hosts they
145        have reached.
146
147        The blueprint is deliberately **not** in the answer: it is a
148        property of the challenge and cacheable, while this changes on
149        every save, and a caller drawing the overlay already holds it.
150        Carries no groundtruth and no network depth — the layer axis is
151        derived from the blueprint, which has the segments. Wraps
152        ``GET /admin/competitions/{cid}/ranges/{chid}/progress``."""
153        resp = self._http.request(
154            "GET", f"/admin/competitions/{competition_id}/ranges/{challenge_id}/progress"
155        )
156        _raise_for_status(resp)
157        return RangeProgress.model_validate(resp.json())
158
159    def range_replay(
160        self, competition_id: str, challenge_id: str, *, frames: int | None = None
161    ) -> RangeReplay:
162        """The same field, wound back — where every team stood at time T.
163
164        :meth:`range_progress` answers *now*; this cuts the whole event
165        into instants, so a caller can ask *who moved when*. The last
166        frame equals that method's answer element for element, which is
167        the property the feature rests on: the clock is ``solved_at``,
168        the immutable first capture that every solve row carries.
169
170        ⚠️ **``frames: []`` means there is no time axis** — nothing was
171        captured and no window was declared, or nobody entered — and is
172        *not* what asking for no frames gets: ``frames=0`` is a 422,
173        because two facts behind one shape is the ``0``-versus-unset
174        trap. Omit ``frames`` for the server's default.
175
176        ⚠️ **A position carries ``reached`` as a count and no milestone
177        ids**, deliberately: carrying them would multiply the payload by
178        the milestone count. Its ``team_id`` is the id
179        :meth:`range_progress` published — an alias where the entrant
180        withheld their identity — so the two reads join without this
181        caller deciding who anybody is. Wraps
182        ``GET /admin/competitions/{cid}/ranges/{chid}/progress/replay``."""
183        params = {} if frames is None else {"frames": frames}
184        resp = self._http.request(
185            "GET",
186            f"/admin/competitions/{competition_id}/ranges/{challenge_id}/progress/replay",
187            params=params,
188        )
189        _raise_for_status(resp)
190        return RangeReplay.model_validate(resp.json())
191
192    def build_state(self) -> ChallengeBuildStateResponse:
193        """Aggregate per-challenge build state across every online node.
194
195        Returns one row per known challenge with an ``aggregated``
196        worst-case status plus the per-node breakdown for the modal
197        drill-down. Wraps ``GET /admin/challenges/build-state``."""
198        resp = self._http.request("GET", "/admin/challenges/build-state")
199        _raise_for_status(resp)
200        return ChallengeBuildStateResponse.model_validate(resp.json())
201
202    def pull(self, challenge_id: str) -> AdminTaskInfo:
203        """Submit a single-challenge pre-pull background task (pull-side
204        twin of :meth:`build`: warms registry-only ``image:`` services).
205        Returns the task record. Wraps ``POST /admin/challenges/{id}/pull``."""
206        resp = self._http.request("POST", f"/admin/challenges/{challenge_id}/pull")
207        _raise_for_status(resp)
208        return AdminTaskInfo.model_validate(resp.json())
209
210    def pull_all(self, *, competition_id: str = "") -> AdminTaskInfo:
211        """Submit a bulk pre-pull background task (pull-side twin of
212        :meth:`build_all`). Returns the task record. Wraps
213        ``POST /admin/challenges/pull-all``."""
214        params: dict[str, Any] = {}
215        if competition_id:
216            params["competition_id"] = competition_id
217        resp = self._http.request("POST", "/admin/challenges/pull-all", params=params)
218        _raise_for_status(resp)
219        return AdminTaskInfo.model_validate(resp.json())
220
221    def pull_state(self) -> ChallengePullStateResponse:
222        """Aggregate per-challenge pull state across every online node.
223
224        Pull-side twin of :meth:`build_state`. Wraps
225        ``GET /admin/challenges/pull-state``."""
226        resp = self._http.request("GET", "/admin/challenges/pull-state")
227        _raise_for_status(resp)
228        return ChallengePullStateResponse.model_validate(resp.json())
229
230    def stats(self, offset: int = 0, limit: int = 50) -> list[AdminChallengeStatsRow]:
231        """Per-challenge attempt / solve / first-blood counts."""
232        resp = self._http.request(
233            "GET",
234            "/admin/challenges/stats",
235            params={"offset": offset, "limit": limit},
236        )
237        _raise_for_status(resp)
238        return [AdminChallengeStatsRow.model_validate(r) for r in resp.json()["items"]]
239
240    def solve_stats(
241        self, *, competition_id: str = "", q: str = "", offset: int = 0, limit: int = 50
242    ) -> list[AdminChallengeSolveStatsRow]:
243        """Solves and attempts per challenge, one row per ``(competition,
244        challenge)`` pair (#2341): a team counts only inside its own
245        competition. ``competition_id`` narrows to one scope. Wraps
246        ``GET /admin/challenges/solve-stats``."""
247        resp = self._http.request(
248            "GET",
249            "/admin/challenges/solve-stats",
250            params={"competition_id": competition_id, "q": q, "offset": offset, "limit": limit},
251        )
252        _raise_for_status(resp)
253        return [AdminChallengeSolveStatsRow.model_validate(r) for r in resp.json()["items"]]
254
255    def timeseries(
256        self,
257        challenge_id: str,
258        *,
259        window: int = 86400,
260        bucket: int = 3600,
261    ) -> AdminChallengeTimeseries:
262        """Per-challenge timeseries for the row-level drawer on
263        ``/admin/challenges``."""
264        resp = self._http.request(
265            "GET",
266            f"/admin/challenges/{challenge_id}/timeseries",
267            params={"window": window, "bucket": bucket},
268        )
269        _raise_for_status(resp)
270        return AdminChallengeTimeseries.model_validate(resp.json())
271
272    def latency_histogram(self) -> list[AdminChallengeLatencyBucket]:
273        """Instance-start latency distribution across challenges (the
274        admin challenges latency chart)."""
275        resp = self._http.request("GET", "/admin/challenges/latency-histogram")
276        _raise_for_status(resp)
277        return [AdminChallengeLatencyBucket.model_validate(b) for b in resp.json()]
278
279    def feedback(
280        self, challenge_id: str, *, competition_id: str = ""
281    ) -> PagedList[AdminFeedbackRow]:
282        """Admin audit list: every reaction row on a challenge with
283        denormalised user identity. Requires admin role."""
284        params: dict[str, Any] = {}
285        if competition_id:
286            params["competition_id"] = competition_id
287        resp = self._http.request(
288            "GET", f"/admin/challenges/{challenge_id}/feedback", params=params
289        )
290        _raise_for_status(resp)
291        return _extract_items(resp.json(), AdminFeedbackRow)
292
293    def reset_question_attempts(
294        self,
295        team_id: str,
296        challenge_id: str,
297        question_id: str,
298        *,
299        reason: str = "",
300    ) -> QuestionAttemptResetInfo:
301        """Reset the per-question wrong-attempt counter for one team.
302
303        Writes a fresh baseline timestamp; the cap counter ignores all
304        wrong submissions before the new baseline, so the team gets a
305        fresh batch of attempts on this question without any audit
306        rows being deleted. Returns the new baseline row.
307        Wraps ``POST /admin/teams/{team_id}/questions/{challenge_id}/{question_id}/reset-attempts``."""
308        resp = self._http.request(
309            "POST",
310            f"/admin/teams/{team_id}/questions/{challenge_id}/{question_id}/reset-attempts",
311            json={"reason": reason},
312        )
313        _raise_for_status(resp)
314        return QuestionAttemptResetInfo.model_validate(resp.json())
315
316    def list_llm_budgets(self, *, competition_id: str = "") -> LlmBudgetPage:
317        """Who has spent what against the challenge-LLM gateway.
318
319        The reader for :meth:`reset_llm_budget` — without it an organiser
320        can only hand back an allowance to a team somebody already named.
321        ⚠️ ``gateway_configured`` is on the envelope because an empty
322        list otherwise reads as "nobody spent anything" when it means
323        "this deployment enforces no budgets", and those call for
324        opposite actions.
325        Wraps ``GET /admin/llm-budgets``."""
326        params = {"competition_id": competition_id} if competition_id else None
327        resp = self._http.request("GET", "/admin/llm-budgets", params=params)
328        _raise_for_status(resp)
329        return LlmBudgetPage.model_validate(resp.json())
330
331    def deception_stats(
332        self,
333        *,
334        competition_id: str = "",
335        challenge_id: str = "",
336        since: datetime | None = None,
337    ) -> DeceptionStats:
338        """How often an assessing agent obeyed a directive planted in a
339        challenge's own output.
340
341        ⚠️ ``resisted`` is an **upper bound**, and the response carries
342        that caveat on the wire rather than leaving it to documentation:
343        the probe runs inside a container the player is invited to
344        compromise, so a missing compliance record is not evidence of
345        restraint. ``comply_rate`` is ``None`` rather than ``0.0`` when
346        nothing has been contacted — 0/0 rendered as 0% would assert
347        that no agent was fooled.
348
349        Nothing here is scored; it reports, it does not rule.
350        Wraps ``GET /admin/deception/stats``."""
351        # ⚠️ ``since`` is the route's third filter and this wrapper used
352        # to drop it, so "what happened during *this* event" was
353        # unaskable from anything but a hand-rolled request — the shape
354        # ``admin competition update``'s missing flags already record.
355        params = {
356            k: v
357            for k, v in (
358                ("competition_id", competition_id),
359                ("challenge_id", challenge_id),
360                ("since", since.isoformat() if since else ""),
361            )
362            if v
363        }
364        resp = self._http.request("GET", "/admin/deception/stats", params=params or None)
365        _raise_for_status(resp)
366        return DeceptionStats.model_validate(resp.json())
367
368    def reset_llm_budget(
369        self,
370        team_id: str,
371        competition_id: str,
372        challenge_id: str,
373        *,
374        reason: str = "",
375    ) -> LlmBudgetResetInfo:
376        """Give one team its LLM allowance back on one challenge.
377
378        Clears the gateway's live tally **and** the platform's durable
379        total — either alone un-does itself, so the route does both or
380        refuses. ⚠️ Always answers 200; read ``.outcome`` rather than the
381        status, because ``unreachable`` means nothing changed and is
382        worth retrying.
383        Wraps ``POST /admin/teams/{team_id}/llm-budget/{competition_id}/{challenge_id}/reset``."""
384        resp = self._http.request(
385            "POST",
386            f"/admin/teams/{team_id}/llm-budget/{competition_id}/{challenge_id}/reset",
387            json={"reason": reason},
388        )
389        _raise_for_status(resp)
390        return LlmBudgetResetInfo.model_validate(resp.json())