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