apifuzz 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
apifuzz/report.py ADDED
@@ -0,0 +1,261 @@
1
+ """Turn a ScanResult into something to show or save, with secrets removed.
2
+
3
+ The HTTP client records requests exactly as sent, tokens included, and a finding's evidence can
4
+ hold another user's data (that is what a BOLA finding is). Every output path goes through
5
+ `redacted()` first (unless the user explicitly passes --no-redact), so a report can be shared:
6
+ credentials are replaced, personal fields in bodies are masked, and bodies are cut to an excerpt.
7
+ """
8
+
9
+ import html # escape text before putting it in the HTML report
10
+ import json # read a body to mask its sensitive fields
11
+ import re # find e-mail addresses in body text
12
+ from collections.abc import Iterable
13
+ from datetime import datetime, timezone
14
+
15
+ from rich.table import Table
16
+ from rich.text import Text
17
+
18
+ from apifuzz.finding import Severity
19
+ from apifuzz.http_client import Exchange
20
+ from apifuzz.scanner import ScanResult
21
+
22
+ # Header names (lower case) whose values are replaced. Covers both directions of a session.
23
+ _SECRET_HEADERS = {"authorization", "proxy-authorization", "cookie", "set-cookie", "x-api-key"}
24
+ REDACTED = "[redacted]"
25
+ # A JSON field whose name contains one of these has its value replaced in a redacted report.
26
+ _SENSITIVE_KEY_PARTS = (
27
+ "password", "passwd", "secret", "token", "apikey", "api_key", "authorization",
28
+ "email", "phone", "ssn", "iban", "card",
29
+ )
30
+ _EMAIL = re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+")
31
+ _BODY_EXCERPT = 600 # characters of a body kept in a redacted report: enough to see its shape
32
+ _MIN_SECRET = 6 # shorter "secrets" are not searched for: replacing "1" or "bob" everywhere garbles the report
33
+
34
+ # Colour for each severity in the table.
35
+ _STYLE = {
36
+ Severity.CRITICAL: "bold red",
37
+ Severity.HIGH: "red",
38
+ Severity.MEDIUM: "yellow",
39
+ Severity.LOW: "cyan",
40
+ Severity.INFO: "dim",
41
+ }
42
+
43
+
44
+ def _mask(value: object) -> object:
45
+ # Walk a parsed JSON value and replace the value of every sensitive-looking key.
46
+ if isinstance(value, dict):
47
+ return {
48
+ k: REDACTED if any(part in k.lower() for part in _SENSITIVE_KEY_PARTS) else _mask(v)
49
+ for k, v in value.items()
50
+ }
51
+ if isinstance(value, list):
52
+ return [_mask(item) for item in value]
53
+ return value
54
+
55
+
56
+ def _scrub(text: str, secrets: list[str]) -> str:
57
+ for secret in secrets:
58
+ text = text.replace(secret, REDACTED)
59
+ return text
60
+
61
+
62
+ def _clean_body(body: str | None, secrets: list[str]) -> str | None:
63
+ """A body made safe to share: sensitive fields and e-mail addresses masked, then cut short."""
64
+ if not body:
65
+ return body
66
+ try:
67
+ parsed = json.loads(body)
68
+ except ValueError:
69
+ text = body # not JSON (or cut off mid-way): fall back to the text rules below
70
+ else:
71
+ text = json.dumps(_mask(parsed)) if isinstance(parsed, (dict, list)) else body
72
+ text = _EMAIL.sub(REDACTED, _scrub(text, secrets))
73
+ if len(text) > _BODY_EXCERPT:
74
+ text = text[:_BODY_EXCERPT] + " ... [shortened]"
75
+ return text
76
+
77
+
78
+ def redacted(result: ScanResult, secrets: Iterable[str | None] = ()) -> ScanResult:
79
+ """A deep copy of `result` that is safe to share.
80
+
81
+ Secret header values become "[redacted]". The values in `secrets` (the test accounts' tokens)
82
+ are replaced wherever they appear: any header, URL, body or warning. Bodies also have their
83
+ sensitive fields masked and are shortened to an excerpt.
84
+ """
85
+ known = [s for s in secrets if s and len(s) >= _MIN_SECRET]
86
+ copy = result.model_copy(deep=True) # never modify the caller's data
87
+ copy.errors = [_scrub(line, known) for line in copy.errors]
88
+ for finding in copy.findings:
89
+ for exchange in finding.evidence:
90
+ exchange.request.url = _scrub(exchange.request.url, known)
91
+ exchange.request.body = _clean_body(exchange.request.body, known)
92
+ exchange.response.body = _clean_body(exchange.response.body, known) or ""
93
+ for headers in (exchange.request.headers, exchange.response.headers):
94
+ for name in headers:
95
+ if name.lower() in _SECRET_HEADERS:
96
+ headers[name] = REDACTED
97
+ else:
98
+ headers[name] = _scrub(headers[name], known)
99
+ return copy
100
+
101
+
102
+ def to_json(result: ScanResult, redact: bool = True, secrets: Iterable[str | None] = ()) -> str:
103
+ # mode="json" turns enums and other special types into plain JSON values.
104
+ return (redacted(result, secrets) if redact else result).model_dump_json(indent=2)
105
+
106
+
107
+ def headline(result: ScanResult) -> str:
108
+ """One line summing up a scan, e.g. "6 endpoints scanned · 3 findings (1 critical, 2 medium)"."""
109
+ e, n = result.endpoints_scanned, len(result.findings)
110
+ text = f"{e} endpoint{'' if e == 1 else 's'} scanned · {n} finding{'' if n == 1 else 's'}"
111
+ counts = [(sev, sum(f.severity is sev for f in result.findings)) for sev in sorted(Severity, reverse=True)]
112
+ parts = [f"{c} {sev.name.lower()}" for sev, c in counts if c]
113
+ return f"{text} ({', '.join(parts)})" if parts else text
114
+
115
+
116
+ def findings_table(result: ScanResult) -> Table:
117
+ checks = len(result.checks_run)
118
+ table = Table(
119
+ title="Scan findings",
120
+ caption=f"{headline(result)} · {checks} check{'' if checks == 1 else 's'} run",
121
+ )
122
+ table.add_column("Severity", no_wrap=True)
123
+ table.add_column("Check", no_wrap=True)
124
+ table.add_column("Endpoint")
125
+ table.add_column("Finding")
126
+ for f in result.findings:
127
+ table.add_row(
128
+ Text(str(f.severity), style=_STYLE[f.severity]),
129
+ Text(f"{f.check}\n{f.owasp.split(' ', 1)[0]}" if f.owasp else f.check), # e.g. "bola" + "API1:2023"
130
+ Text(f.endpoint), # Text(): show "[...]" in a path literally
131
+ Text(f"{f.title}\n{f.detail}" + (f"\nFix: {f.remediation}" if f.remediation else "")),
132
+ )
133
+ return table
134
+
135
+
136
+ def coverage_table(result: ScanResult) -> Table:
137
+ """What each check actually tested. "0 findings" means little if "Tested" is 0 too."""
138
+ table = Table(
139
+ title="What was tested",
140
+ caption=f"{result.requests_sent} request{'' if result.requests_sent == 1 else 's'} sent to {result.target}",
141
+ )
142
+ table.add_column("Check", no_wrap=True)
143
+ table.add_column("Tested", justify="right")
144
+ table.add_column("Not tested", justify="right")
145
+ table.add_column("Not applicable", justify="right")
146
+ for c in result.coverage:
147
+ table.add_row(c.check, str(c.tested), Text(str(c.not_tested), style="yellow" if c.not_tested else ""),
148
+ str(c.not_applicable))
149
+ return table
150
+
151
+
152
+ def coverage_notes(result: ScanResult) -> list[str]:
153
+ """One line per endpoint a check applies to but could not judge: "bola: GET /x: reason"."""
154
+ return [f"{c.check}: {note}" for c in result.coverage for note in c.notes]
155
+
156
+
157
+ # ---------------------------------------------------------------------------------------------
158
+ # HTML: one self-contained file (inline CSS, no scripts, no external links), safe to attach.
159
+
160
+ _CSS = """
161
+ :root { color-scheme: light dark; --bg:#fff; --fg:#1b1b1f; --muted:#5d5d66; --line:#d9d9e0; --card:#f6f6f9;
162
+ --critical:#a4161a; --high:#c0392b; --medium:#9a6700; --low:#2b6cb0; --info:#6b7280; }
163
+ @media (prefers-color-scheme: dark) { :root { --bg:#141418; --fg:#ececf1; --muted:#a0a0ab; --line:#33333b;
164
+ --card:#1d1d23; --critical:#ff6b6b; --high:#ff8fa3; --medium:#f6c35b; --low:#7fb3ff; --info:#9ca3af; } }
165
+ * { box-sizing: border-box; }
166
+ body { margin: 0; padding: 24px 16px; background: var(--bg); color: var(--fg);
167
+ font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
168
+ main { max-width: 960px; margin: 0 auto; }
169
+ h1 { font-size: 1.5rem; margin: 0 0 4px; }
170
+ h2 { font-size: 1.1rem; margin: 28px 0 8px; }
171
+ .muted { color: var(--muted); }
172
+ .headline { font-size: 1.05rem; margin: 12px 0 4px; }
173
+ details { background: var(--card); border: 1px solid var(--line); border-radius: 8px; margin: 8px 0; }
174
+ summary { cursor: pointer; padding: 10px 14px; }
175
+ summary > * { margin-right: 10px; }
176
+ .body { padding: 0 14px 14px; }
177
+ .sev { font-weight: 700; font-size: .78rem; letter-spacing: .04em; }
178
+ .CRITICAL { color: var(--critical); } .HIGH { color: var(--high); } .MEDIUM { color: var(--medium); }
179
+ .LOW { color: var(--low); } .INFO { color: var(--info); }
180
+ code, pre { font: 13px/1.45 ui-monospace, "Cascadia Code", Consolas, monospace; }
181
+ pre { background: var(--bg); border: 1px solid var(--line); border-radius: 6px; padding: 10px;
182
+ overflow-x: auto; white-space: pre-wrap; word-break: break-word; margin: 6px 0 12px; }
183
+ ul { padding-left: 20px; }
184
+ table { border-collapse: collapse; margin: 8px 0; }
185
+ th, td { border: 1px solid var(--line); padding: 4px 12px; text-align: right; }
186
+ th:first-child, td:first-child { text-align: left; }
187
+ """
188
+
189
+
190
+ def _exchange_text(ex: Exchange) -> tuple[str, str]:
191
+ req = ex.request
192
+ req_lines = [f"{req.method} {req.url}"] + [f"{k}: {v}" for k, v in req.headers.items()]
193
+ if req.body:
194
+ req_lines += ["", req.body]
195
+ res = ex.response
196
+ res_lines = [f"HTTP {res.status_code} ({ex.elapsed_ms:.0f} ms)"] + [f"{k}: {v}" for k, v in res.headers.items()]
197
+ if res.body:
198
+ res_lines += ["", res.body + (" [truncated]" if res.truncated else "")]
199
+ return "\n".join(req_lines), "\n".join(res_lines)
200
+
201
+
202
+ def to_html(
203
+ result: ScanResult, title: str = "apifuzz report", redact: bool = True, secrets: Iterable[str | None] = ()
204
+ ) -> str:
205
+ """A standalone HTML report: findings grouped by severity, each expandable to its evidence."""
206
+ shown = redacted(result, secrets) if redact else result
207
+ e = html.escape
208
+ out = [
209
+ "<!doctype html><html lang='en'><head><meta charset='utf-8'>",
210
+ "<meta name='viewport' content='width=device-width, initial-scale=1'>",
211
+ f"<title>{e(title)}</title><style>{_CSS}</style></head><body><main>",
212
+ f"<h1>{e(title)}</h1>",
213
+ f"<p class='muted'>Generated {datetime.now(timezone.utc):%Y-%m-%d %H:%M} UTC · checks: "
214
+ f"{e(', '.join(shown.checks_run) or 'none')}"
215
+ f"{'' if redact else ' · <strong>secrets NOT redacted</strong>'}</p>",
216
+ f"<p class='headline'><strong>{e(headline(shown))}</strong></p>",
217
+ f"<p class='muted'>Target {e(shown.target or 'unknown')} · {shown.requests_sent} requests sent · "
218
+ f"{shown.duration_s:g} s · apifuzz {e(shown.tool_version)}</p>",
219
+ ]
220
+ if shown.incomplete:
221
+ out.append("<p><strong>This scan stopped early, so the results are partial.</strong> See the warnings.</p>")
222
+ if not shown.findings:
223
+ out.append("<p>No findings.</p>")
224
+ for sev in sorted(Severity, reverse=True):
225
+ group = [f for f in shown.findings if f.severity is sev]
226
+ if not group:
227
+ continue
228
+ out.append(f"<h2 class='{sev.name}'>{sev.name.title()} ({len(group)})</h2>")
229
+ for f in group:
230
+ out.append(
231
+ f"<details><summary><span class='sev {sev.name}'>{sev.name}</span>"
232
+ f"<code>{e(f.endpoint)}</code><span>{e(f.title)}</span>"
233
+ f"<span class='muted'>{e(f.check)}</span></summary><div class='body'>"
234
+ + (f"<p class='muted'>OWASP {e(f.owasp)}</p>" if f.owasp else "")
235
+ + f"<p>{e(f.detail)}</p>"
236
+ )
237
+ if f.remediation:
238
+ out.append(f"<p><strong>Fix:</strong> {e(f.remediation)}</p>")
239
+ for i, ex in enumerate(f.evidence, 1):
240
+ req, res = _exchange_text(ex)
241
+ out.append(f"<p class='muted'>Evidence {i}: request</p><pre>{e(req)}</pre>")
242
+ out.append(f"<p class='muted'>Evidence {i}: response</p><pre>{e(res)}</pre>")
243
+ out.append("</div></details>")
244
+ if shown.coverage:
245
+ out.append(
246
+ "<h2>What was tested</h2><p class='muted'>No findings is only good news for endpoints "
247
+ "that were tested.</p><table><tr><th>Check</th><th>Tested</th><th>Not tested</th>"
248
+ "<th>Not applicable</th></tr>"
249
+ + "".join(
250
+ f"<tr><td>{e(c.check)}</td><td>{c.tested}</td><td>{c.not_tested}</td><td>{c.not_applicable}</td></tr>"
251
+ for c in shown.coverage
252
+ )
253
+ + "</table>"
254
+ )
255
+ notes = coverage_notes(shown)
256
+ if notes:
257
+ out.append("<p>Not tested:</p><ul>" + "".join(f"<li>{e(n)}</li>" for n in notes) + "</ul>")
258
+ if shown.errors:
259
+ out.append("<h2>Warnings</h2><ul>" + "".join(f"<li>{e(x)}</li>" for x in shown.errors) + "</ul>")
260
+ out.append("</main></body></html>")
261
+ return "\n".join(out)
apifuzz/scanner.py ADDED
@@ -0,0 +1,97 @@
1
+ """Run a set of checks against a set of endpoints and collect what they report.
2
+
3
+ A failure talking to one endpoint (connection refused, timeout) is recorded and the scan moves
4
+ on, so one broken route doesn't hide results from the rest. A refused host (AllowlistError) is
5
+ different: it means the scan is misconfigured, so it stops everything.
6
+
7
+ Besides findings, the result says what was actually tested. For every check it counts the
8
+ endpoints that were tested, the ones that could not be (with the reason), and the ones the check
9
+ does not apply to. A report with no findings is only good news if something was tested.
10
+ """
11
+
12
+ import time
13
+ from datetime import datetime, timezone
14
+
15
+ from pydantic import BaseModel
16
+
17
+ from apifuzz import __version__
18
+ from apifuzz.checks.base import NOT_TESTED, TESTED, Check, ScanContext
19
+ from apifuzz.endpoint_model import Endpoint
20
+ from apifuzz.errors import RequestError, RequestLimitError
21
+ from apifuzz.finding import Finding
22
+
23
+ SCHEMA_VERSION = 2 # bump when the JSON report's shape changes in a way that breaks readers
24
+
25
+
26
+ class Coverage(BaseModel):
27
+ """What one check did across the scan."""
28
+
29
+ check: str
30
+ tested: int = 0 # endpoints where the check reached a verdict
31
+ not_tested: int = 0 # endpoints the check applies to but could not judge
32
+ not_applicable: int = 0 # endpoints the check has nothing to look for on
33
+ notes: list[str] = [] # one line per not-tested endpoint: "GET /orders/{id}: <reason>"
34
+
35
+
36
+ class ScanResult(BaseModel):
37
+ schema_version: int = SCHEMA_VERSION
38
+ tool_version: str = __version__
39
+ target: str = "" # the base URL that was scanned
40
+ started_at: str = "" # UTC, ISO 8601
41
+ duration_s: float = 0.0
42
+ requests_sent: int = 0
43
+ findings: list[Finding] = [] # worst first
44
+ errors: list[str] = [] # one line per (check, endpoint) that couldn't be completed
45
+ checks_run: list[str] = [] # the ids of the checks that ran
46
+ endpoints_scanned: int = 0
47
+ coverage: list[Coverage] = [] # one entry per check, in the order they ran
48
+ incomplete: bool = False # True when the scan stopped early (request limit reached)
49
+
50
+
51
+ def run_scan(endpoints: list[Endpoint], checks: list[type[Check]], ctx: ScanContext) -> ScanResult:
52
+ started = time.perf_counter()
53
+ result = ScanResult(
54
+ checks_run=[c.id for c in checks],
55
+ endpoints_scanned=len(endpoints),
56
+ target=ctx.settings.base_url,
57
+ started_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
58
+ )
59
+ if not ctx.endpoints:
60
+ ctx.endpoints = endpoints # let checks see the whole scan (e.g. bola's id recon)
61
+ try:
62
+ for check_cls in checks:
63
+ check = check_cls()
64
+ coverage = Coverage(check=check.id)
65
+ result.coverage.append(coverage)
66
+ for endpoint in endpoints:
67
+ label = f"{endpoint.method} {endpoint.path}"
68
+ try:
69
+ result.findings.extend(check.run(endpoint, ctx))
70
+ except RequestError as exc:
71
+ # A network-level failure on this one request: note it and carry on.
72
+ result.errors.append(f"{check.id} on {label}: {exc}")
73
+ ctx.outcomes[(check.id, label)] = (NOT_TESTED, "a request failed (see warnings)")
74
+ # AllowlistError is deliberately NOT caught: it propagates and aborts the scan.
75
+ _count(coverage, label, ctx.outcomes.get((check.id, label)))
76
+ except RequestLimitError as exc:
77
+ # The request budget ran out. Keep what was found so far, but say the scan is partial.
78
+ result.errors.append(f"scan stopped early: {exc}")
79
+ result.incomplete = True
80
+ # Anything a check created on the target and could not remove again is said out loud.
81
+ result.errors.extend(f"left behind on the target: {line}" for line in ctx.cache.get("leftovers", [])) # type: ignore[union-attr]
82
+ # Stable sort: worst severity first, ties keep the order the checks produced them in.
83
+ result.findings.sort(key=lambda f: f.severity, reverse=True)
84
+ result.requests_sent = ctx.client.requests_sent
85
+ result.duration_s = round(time.perf_counter() - started, 2)
86
+ return result
87
+
88
+
89
+ def _count(coverage: Coverage, label: str, outcome: tuple[str, str] | None) -> None:
90
+ status, reason = outcome or ("", "")
91
+ if status == TESTED:
92
+ coverage.tested += 1
93
+ elif status == NOT_TESTED:
94
+ coverage.not_tested += 1
95
+ coverage.notes.append(f"{label}: {reason}" if reason else label)
96
+ else:
97
+ coverage.not_applicable += 1
@@ -0,0 +1,146 @@
1
+ """Log the two test accounts in, and make sure their tokens work before the scan relies on them.
2
+
3
+ If APIFUZZ_TOKEN_A / _B are set, they are used as they are. Otherwise, if a username and password
4
+ are set for an account (APIFUZZ_USER_A / APIFUZZ_PASSWORD_A, and the same for B), the session
5
+ manager POSTs them to the login endpoint and reads the token from the answer. The credentials are
6
+ sent as JSON by default, or as form fields with APIFUZZ_LOGIN_FORMAT=form.
7
+
8
+ `preflight` then checks the tokens. A scan with a dead token gets 401 everywhere and would report
9
+ "no findings" for an API it never tested, and a scan where A and B are the same user would
10
+ "prove" that two accounts can read each other's data. Both stop the scan here instead.
11
+
12
+ Every request goes through the same HttpClient as the checks, so it obeys the allowlist.
13
+ """
14
+
15
+ import json
16
+
17
+ from apifuzz.endpoint_model import Endpoint
18
+ from apifuzz.errors import SessionError
19
+ from apifuzz.http_client import HttpClient
20
+ from apifuzz.settings import Settings
21
+
22
+ # Where the token usually sits in a login response: {"token": "..."}, {"access_token": "..."}...
23
+ _TOKEN_KEYS = ("token", "access_token", "accessToken", "jwt", "id_token")
24
+ # Last path segments of endpoints that describe the caller, e.g. GET /me or GET /users/me.
25
+ IDENTITY_NAMES = {"me", "whoami", "self", "profile", "account", "userinfo", "current"}
26
+ _MAX_PREFLIGHT_TRIES = 3 # protected endpoints to try per account before giving up
27
+
28
+
29
+ def login(client: HttpClient, settings: Settings, username: str, password: str, account: str) -> str:
30
+ """POST the username and password to the login path and return the token from the answer."""
31
+ url = f"{settings.base_url}/{settings.login_path.lstrip('/')}"
32
+ credentials = {settings.login_user_field: username, settings.login_password_field: password}
33
+ if settings.login_format == "form":
34
+ exchange = client.request("POST", url, data=credentials)
35
+ else:
36
+ exchange = client.request("POST", url, json=credentials)
37
+ status = exchange.response.status_code
38
+ if status == 429:
39
+ raise SessionError(
40
+ f"logging in account {account} at {url} failed: HTTP 429. The login endpoint is "
41
+ "rate-limiting this client (perhaps after an earlier scan); wait a little and try again."
42
+ )
43
+ if not exchange.response.ok:
44
+ raise SessionError(f"logging in account {account} at {url} failed: HTTP {status}")
45
+ try:
46
+ body = json.loads(exchange.response.body)
47
+ except ValueError:
48
+ body = None
49
+ if isinstance(body, dict):
50
+ for key in _TOKEN_KEYS:
51
+ if isinstance(body.get(key), str) and body[key]:
52
+ return body[key]
53
+ raise SessionError(
54
+ f"logging in account {account} at {url} worked (HTTP {status}), but the answer has no token "
55
+ f"field ({', '.join(_TOKEN_KEYS)})"
56
+ )
57
+
58
+
59
+ def authenticate(client: HttpClient, settings: Settings) -> Settings:
60
+ """Return settings with token_a / token_b filled in by logging in where credentials are given."""
61
+ updates: dict[str, str] = {}
62
+ for account in ("a", "b"):
63
+ if getattr(settings, f"token_{account}"):
64
+ continue # an explicit token wins
65
+ username, password = getattr(settings, f"user_{account}"), getattr(settings, f"password_{account}")
66
+ if username and password:
67
+ updates[f"token_{account}"] = login(client, settings, username, password, account.upper())
68
+ return settings.model_copy(update=updates) if updates else settings
69
+
70
+
71
+ def _is_identity(endpoint: Endpoint) -> bool:
72
+ return endpoint.path.rstrip("/").rsplit("/", 1)[-1].lower() in IDENTITY_NAMES
73
+
74
+
75
+ def _probe_endpoints(endpoints: list[Endpoint]) -> list[Endpoint]:
76
+ """Protected GET endpoints that can be called as they are, "who am I" style ones first."""
77
+ usable = [
78
+ e
79
+ for e in endpoints
80
+ if e.method == "GET"
81
+ and e.requires_auth
82
+ and "{" not in e.path
83
+ and not any(p.required and p.location in ("path", "query") for p in e.parameters)
84
+ ]
85
+ return sorted(usable, key=lambda e: not _is_identity(e))[:_MAX_PREFLIGHT_TRIES] # stable sort
86
+
87
+
88
+ def preflight(client: HttpClient, settings: Settings, endpoints: list[Endpoint]) -> list[str]:
89
+ """Check the test accounts before scanning. Raises SessionError when they can't be used.
90
+
91
+ - A and B must not have the same token.
92
+ - Each token must be accepted by a protected endpoint. If every one tried answers 401 or 403,
93
+ the token is expired or wrong.
94
+ - On a "who am I" endpoint such as /me, A and B must not get the same answer: that would mean
95
+ both tokens belong to one user.
96
+
97
+ Returns warnings for what it could not confirm (for example, the spec has no protected
98
+ endpoint that can be called without inventing a value).
99
+ """
100
+ tokens = {"A": settings.token_a, "B": settings.token_b}
101
+ if tokens["A"] and tokens["A"] == tokens["B"]:
102
+ raise SessionError(
103
+ "accounts A and B have the same token. The bola check compares two different users, "
104
+ "so give B the token of a second test account."
105
+ )
106
+
107
+ warnings: list[str] = []
108
+ probes = _probe_endpoints(endpoints)
109
+ identity: dict[str, tuple[str, str]] = {} # account -> (path, body) from a "who am I" endpoint
110
+ for account, token in tokens.items():
111
+ if not token:
112
+ continue
113
+ if not probes:
114
+ warnings.append(
115
+ f"could not confirm account {account}'s token works: the spec has no protected GET "
116
+ "endpoint that can be called without parameters"
117
+ )
118
+ continue
119
+ refused: list[str] = []
120
+ accepted = False
121
+ for endpoint in probes:
122
+ url = f"{settings.base_url}/{endpoint.path.lstrip('/')}"
123
+ exchange = client.request("GET", url, headers=settings.auth_headers(token))
124
+ status = exchange.response.status_code
125
+ if exchange.response.ok:
126
+ accepted = True
127
+ if _is_identity(endpoint):
128
+ identity[account] = (endpoint.path, exchange.response.body)
129
+ break
130
+ if status in (401, 403):
131
+ refused.append(f"GET {endpoint.path} answered HTTP {status}")
132
+ if accepted:
133
+ continue
134
+ if refused and len(refused) == len(probes):
135
+ raise SessionError(
136
+ f"account {account}'s token was refused ({'; '.join(refused)}). It may be expired or "
137
+ "wrong. Scanning with it would test nothing and report a clean API."
138
+ )
139
+ warnings.append(f"could not confirm account {account}'s token works: no protected endpoint answered 2xx")
140
+
141
+ if len(identity) == 2 and identity["A"] == identity["B"] and identity["A"][1].strip():
142
+ raise SessionError(
143
+ f"accounts A and B look like the same user: GET {identity['A'][0]} gave both the same "
144
+ "answer. The bola check needs two different users."
145
+ )
146
+ return warnings