ctfy.sdk.admin_resources.reports

 1"""``client.admin.reports`` — the organiser's view of the deliverable."""
 2
 3from __future__ import annotations
 4
 5from ctfy.sdk._helpers import _raise_for_status
 6from ctfy.sdk.base import BaseHttpClient
 7from ctfy.server.models import (
 8    ReportAttachmentsResponse,
 9    ReportRosterResponse,
10    ReportVersionsResponse,
11)
12
13
14class AdminReportsResource:
15    """Who has written a report, and what one team actually wrote.
16
17    Split for the same reason ``client.admin.patches`` is: the roster is
18    competition-wide and carries **no bodies** — an event accumulates
19    report versions all week, so a listing that shipped them would read
20    every one out of SQLite to render a table of lengths. :meth:`get`
21    carries them, one team at a time, which is what retaining every
22    version was for.
23    """
24
25    def __init__(self, http: BaseHttpClient) -> None:
26        self._http = http
27
28    def list(self, competition_id: str) -> ReportRosterResponse:
29        """Every current report's status in one competition.
30
31        One row per ``(team, range)``: a team that wrote up three of the
32        event's four ranges is three rows.
33
34        ``missing_team_count`` is served rather than derived: subtracting
35        the roster from the team list client-side is arithmetic two
36        clients can do differently, and then two organisers disagree
37        about who has not written anything.
38        """
39        resp = self._http.request("GET", f"/admin/competitions/{competition_id}/reports")
40        _raise_for_status(resp)
41        return ReportRosterResponse.model_validate(resp.json())
42
43    def get(self, competition_id: str, team_id: str, challenge_id: str) -> ReportVersionsResponse:
44        """One team's whole report history on one range, bodies included.
45
46        ⚠️ The bodies are **attacker-authored text**. Render them as
47        text, never as HTML, and never feed one back into a prompt
48        outside the bounded matching task the grader defines.
49        """
50        resp = self._http.request(
51            "GET",
52            f"/admin/competitions/{competition_id}/reports/{team_id}/{challenge_id}",
53        )
54        _raise_for_status(resp)
55        return ReportVersionsResponse.model_validate(resp.json())
56
57    def attachments(
58        self, competition_id: str, team_id: str, challenge_id: str
59    ) -> ReportAttachmentsResponse:
60        """One team's evidence appendix for one range.
61
62        ⚠️ **Empty rather than 404** for a team that uploaded nothing,
63        unlike :meth:`get`. That one distinguishes "wrote nothing" from
64        "you typed the wrong team id"; by the time an organiser is here
65        the team has already been resolved by reading the report, and an
66        appendix with no files is the ordinary case.
67        """
68        resp = self._http.request(
69            "GET",
70            f"/admin/competitions/{competition_id}/reports/{team_id}/{challenge_id}/attachments",
71        )
72        _raise_for_status(resp)
73        return ReportAttachmentsResponse.model_validate(resp.json())
74
75    def attachment_bytes(
76        self, competition_id: str, team_id: str, challenge_id: str, attachment_id: str
77    ) -> bytes:
78        """Fetch one team's attachment, as an organiser.
79
80        ⚠️ The bytes were chosen by an untrusted uploader. The platform
81        serves them ``nosniff`` + sandboxed and, for anything that is not
82        a real image, as a download — so treat a saved file the way you
83        would treat any artifact recovered from an engagement.
84        """
85        resp = self._http.request(
86            "GET",
87            f"/admin/competitions/{competition_id}/reports/{team_id}/{challenge_id}"
88            f"/attachments/{attachment_id}",
89        )
90        _raise_for_status(resp)
91        return resp.content