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/__init__.py +13 -0
- apifuzz/__main__.py +5 -0
- apifuzz/checks/__init__.py +9 -0
- apifuzz/checks/auth_required.py +62 -0
- apifuzz/checks/base.py +152 -0
- apifuzz/checks/bola.py +337 -0
- apifuzz/checks/injection.py +289 -0
- apifuzz/checks/mass_assignment.py +283 -0
- apifuzz/checks/rate_limit.py +168 -0
- apifuzz/cli.py +425 -0
- apifuzz/docker_verify.py +168 -0
- apifuzz/endpoint_model.py +180 -0
- apifuzz/errors.py +37 -0
- apifuzz/finding.py +55 -0
- apifuzz/http_client.py +221 -0
- apifuzz/report.py +261 -0
- apifuzz/scanner.py +97 -0
- apifuzz/session_manager.py +146 -0
- apifuzz/settings.py +270 -0
- apifuzz/spec_loader.py +138 -0
- apifuzz-0.2.0.dist-info/METADATA +350 -0
- apifuzz-0.2.0.dist-info/RECORD +25 -0
- apifuzz-0.2.0.dist-info/WHEEL +4 -0
- apifuzz-0.2.0.dist-info/entry_points.txt +2 -0
- apifuzz-0.2.0.dist-info/licenses/LICENSE +21 -0
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
|