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/settings.py
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
"""Where the scanner gets its configuration: a .env file, the environment, and CLI flags.
|
|
2
|
+
|
|
3
|
+
Precedence, highest first: an explicit CLI flag, then an environment variable (or a line in a
|
|
4
|
+
local .env file), then a fallback worked out from the spec. Nothing here sends any requests; it
|
|
5
|
+
only gathers settings and turns obvious mistakes into clear errors.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import os # read environment variables
|
|
9
|
+
from pathlib import Path # read the .env file
|
|
10
|
+
from urllib.parse import urljoin, urlsplit # pull the host[:port] out of a base URL
|
|
11
|
+
|
|
12
|
+
from pydantic import BaseModel # a typed settings record
|
|
13
|
+
|
|
14
|
+
from apifuzz.errors import ApifuzzError
|
|
15
|
+
from apifuzz.http_client import DEFAULT_PORTS, Allowlist
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class ConfigError(ApifuzzError):
|
|
19
|
+
"""A setting is missing or malformed (e.g. no base URL, or a token that isn't set)."""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class Settings(BaseModel):
|
|
23
|
+
"""The settings a scan needs, after flags, environment and spec have been combined."""
|
|
24
|
+
|
|
25
|
+
base_url: str # the root the API is served from, e.g. "https://staging.example.com"
|
|
26
|
+
allowlist: list[str] # hosts the scanner may contact; always includes the base URL's host
|
|
27
|
+
token_a: str | None = None # bearer token for test account A (the main caller)
|
|
28
|
+
token_b: str | None = None # bearer token for test account B (used by the BOLA/IDOR check)
|
|
29
|
+
require_docker: bool = False # only scan targets confirmed as running Docker containers
|
|
30
|
+
# Credentials the session manager uses to log in when a token isn't given directly.
|
|
31
|
+
user_a: str | None = None
|
|
32
|
+
password_a: str | None = None
|
|
33
|
+
user_b: str | None = None
|
|
34
|
+
password_b: str | None = None
|
|
35
|
+
login_path: str = "/login" # where the session manager POSTs the credentials
|
|
36
|
+
login_format: str = "json" # "json" or "form": how the credentials are encoded
|
|
37
|
+
login_user_field: str = "username" # the name of the username field in the login request
|
|
38
|
+
login_password_field: str = "password"
|
|
39
|
+
# How a token is sent. Worked out from the spec's security scheme; "Authorization: Bearer <token>"
|
|
40
|
+
# when the spec doesn't say. A cookie scheme uses header "Cookie" and prefix "<name>=".
|
|
41
|
+
auth_header: str = "Authorization"
|
|
42
|
+
auth_prefix: str = "Bearer "
|
|
43
|
+
# Path patterns (shell style, e.g. "/posts/*") whose objects are shared between users on
|
|
44
|
+
# purpose. The bola check leaves them alone.
|
|
45
|
+
shared_paths: list[str] = []
|
|
46
|
+
burst: int = 15 # how many identical requests the rate-limit check sends to one endpoint
|
|
47
|
+
|
|
48
|
+
def auth_headers(self, token: str) -> dict[str, str]:
|
|
49
|
+
"""The header that logs a request in with `token`, e.g. {"Authorization": "Bearer abc"}."""
|
|
50
|
+
return {self.auth_header: f"{self.auth_prefix}{token}"}
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def load_dotenv(path: str | Path = ".env") -> dict[str, str]:
|
|
54
|
+
"""Read a simple KEY=VALUE .env file into a dict. Missing file -> empty dict.
|
|
55
|
+
|
|
56
|
+
Deliberately small: no quoting rules, no interpolation, no export keyword. Blank lines and
|
|
57
|
+
lines starting with '#' are ignored; surrounding whitespace and one pair of matching quotes
|
|
58
|
+
around the value are stripped.
|
|
59
|
+
"""
|
|
60
|
+
values: dict[str, str] = {}
|
|
61
|
+
file = Path(path)
|
|
62
|
+
if not file.is_file():
|
|
63
|
+
return values
|
|
64
|
+
for raw in file.read_text(encoding="utf-8").splitlines():
|
|
65
|
+
line = raw.strip()
|
|
66
|
+
if not line or line.startswith("#") or "=" not in line:
|
|
67
|
+
continue
|
|
68
|
+
key, _, value = line.partition("=")
|
|
69
|
+
key = key.strip()
|
|
70
|
+
value = value.strip()
|
|
71
|
+
# Strip one surrounding pair of single or double quotes, if present.
|
|
72
|
+
if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
|
|
73
|
+
value = value[1:-1]
|
|
74
|
+
if key:
|
|
75
|
+
values[key] = value
|
|
76
|
+
return values
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def host_entry(url: str) -> str:
|
|
80
|
+
"""Return "host" or "host:port" from a URL, or raise ConfigError if it isn't a usable http(s) URL."""
|
|
81
|
+
parts = urlsplit(url)
|
|
82
|
+
if parts.scheme not in ("http", "https") or not parts.hostname:
|
|
83
|
+
raise ConfigError(f"base URL must be an http(s) URL with a host, got: {url!r}")
|
|
84
|
+
# netloc keeps any port but also any "user@"; rebuild from the clean host and optional port.
|
|
85
|
+
return f"{parts.hostname}:{parts.port}" if parts.port else parts.hostname
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def resolve_settings(
|
|
89
|
+
*,
|
|
90
|
+
spec: dict | None = None,
|
|
91
|
+
base_url: str | None = None,
|
|
92
|
+
allowlist: list[str] | None = None,
|
|
93
|
+
token_a: str | None = None,
|
|
94
|
+
token_b: str | None = None,
|
|
95
|
+
require_docker: bool | None = None,
|
|
96
|
+
shared_paths: list[str] | None = None,
|
|
97
|
+
burst: int | None = None,
|
|
98
|
+
spec_source: str | None = None,
|
|
99
|
+
env: dict[str, str] | None = None,
|
|
100
|
+
) -> Settings:
|
|
101
|
+
"""Combine CLI arguments, environment/.env, and the spec into one Settings object.
|
|
102
|
+
|
|
103
|
+
`env` defaults to the real environment merged over a local .env file (the environment wins).
|
|
104
|
+
Pass `env` explicitly in tests to avoid depending on the machine's real environment.
|
|
105
|
+
"""
|
|
106
|
+
if env is None:
|
|
107
|
+
# .env provides defaults; a real environment variable of the same name overrides it.
|
|
108
|
+
env = {**load_dotenv(), **os.environ}
|
|
109
|
+
|
|
110
|
+
# Extra allowlist entries come from the flag or the env.
|
|
111
|
+
entries = list(allowlist) if allowlist else _split_list(env.get("APIFUZZ_ALLOWLIST"))
|
|
112
|
+
|
|
113
|
+
base_url = base_url or env.get("APIFUZZ_BASE_URL")
|
|
114
|
+
if not base_url:
|
|
115
|
+
# Nobody named the target, so the spec's own "servers" entry is the only candidate. A spec
|
|
116
|
+
# is just a document (often downloaded), so it may not pick the target by itself.
|
|
117
|
+
base_url = _confirmed_spec_server(_base_url_from_spec(spec), spec_source, entries)
|
|
118
|
+
if not base_url:
|
|
119
|
+
raise ConfigError(
|
|
120
|
+
"no base URL: pass --base-url, set APIFUZZ_BASE_URL, or use a spec that lists a server"
|
|
121
|
+
)
|
|
122
|
+
base_url = base_url.rstrip("/") # so base_url + "/orders" doesn't double the slash
|
|
123
|
+
|
|
124
|
+
# A base URL that got this far was confirmed by the user, so its host is allowed.
|
|
125
|
+
host = host_entry(base_url)
|
|
126
|
+
if host not in entries:
|
|
127
|
+
entries.insert(0, host)
|
|
128
|
+
|
|
129
|
+
auth_header, auth_prefix = _auth_scheme(spec, env)
|
|
130
|
+
if burst is None:
|
|
131
|
+
try:
|
|
132
|
+
burst = int(env.get("APIFUZZ_BURST") or 15)
|
|
133
|
+
except ValueError:
|
|
134
|
+
raise ConfigError(f"APIFUZZ_BURST must be a whole number, got: {env.get('APIFUZZ_BURST')!r}") from None
|
|
135
|
+
if not 2 <= burst <= 50:
|
|
136
|
+
raise ConfigError(f"the burst size must be between 2 and 50, got: {burst}")
|
|
137
|
+
login_format = (env.get("APIFUZZ_LOGIN_FORMAT") or "json").strip().lower()
|
|
138
|
+
if login_format not in ("json", "form"):
|
|
139
|
+
raise ConfigError(f"APIFUZZ_LOGIN_FORMAT must be json or form, got: {login_format!r}")
|
|
140
|
+
|
|
141
|
+
return Settings(
|
|
142
|
+
base_url=base_url,
|
|
143
|
+
allowlist=entries,
|
|
144
|
+
token_a=token_a or env.get("APIFUZZ_TOKEN_A") or None,
|
|
145
|
+
token_b=token_b or env.get("APIFUZZ_TOKEN_B") or None,
|
|
146
|
+
user_a=env.get("APIFUZZ_USER_A") or None,
|
|
147
|
+
password_a=env.get("APIFUZZ_PASSWORD_A") or None,
|
|
148
|
+
user_b=env.get("APIFUZZ_USER_B") or None,
|
|
149
|
+
password_b=env.get("APIFUZZ_PASSWORD_B") or None,
|
|
150
|
+
login_path=env.get("APIFUZZ_LOGIN_PATH") or "/login",
|
|
151
|
+
login_format=login_format,
|
|
152
|
+
login_user_field=env.get("APIFUZZ_LOGIN_USER_FIELD") or "username",
|
|
153
|
+
login_password_field=env.get("APIFUZZ_LOGIN_PASSWORD_FIELD") or "password",
|
|
154
|
+
auth_header=auth_header,
|
|
155
|
+
auth_prefix=auth_prefix,
|
|
156
|
+
shared_paths=list(shared_paths) if shared_paths else _split_list(env.get("APIFUZZ_SHARED")),
|
|
157
|
+
burst=burst,
|
|
158
|
+
# None means "not given on the command line": fall back to the env ("1", "true", "yes").
|
|
159
|
+
require_docker=require_docker_setting(require_docker, env),
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def require_docker_setting(flag: bool | None, env: dict[str, str] | None = None) -> bool:
|
|
164
|
+
"""--require-docker if given, else APIFUZZ_REQUIRE_DOCKER ("1", "true", "yes") from the env or .env."""
|
|
165
|
+
if flag is not None:
|
|
166
|
+
return flag
|
|
167
|
+
if env is None:
|
|
168
|
+
env = {**load_dotenv(), **os.environ}
|
|
169
|
+
return env.get("APIFUZZ_REQUIRE_DOCKER", "").strip().lower() in ("1", "true", "yes")
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _origin(url: str) -> tuple[str, str | None, int | None]:
|
|
173
|
+
# ("http", "localhost", 8000): scheme, host and port, with the default port filled in.
|
|
174
|
+
parts = urlsplit(url)
|
|
175
|
+
try:
|
|
176
|
+
port = parts.port
|
|
177
|
+
except ValueError:
|
|
178
|
+
port = None
|
|
179
|
+
return parts.scheme, parts.hostname, port or DEFAULT_PORTS.get(parts.scheme)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _is_http_url(text: str | None) -> bool:
|
|
183
|
+
return bool(text) and text.lower().startswith(("http://", "https://"))
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def _confirmed_spec_server(server: str | None, spec_source: str | None, entries: list[str]) -> str | None:
|
|
187
|
+
"""The spec's server URL, but only if something other than the spec confirms it as the target.
|
|
188
|
+
|
|
189
|
+
It is confirmed when the spec was downloaded from that same host and port (the API is
|
|
190
|
+
describing itself), or when the user listed the host in --allow / APIFUZZ_ALLOWLIST.
|
|
191
|
+
Otherwise the scan, and the test accounts' tokens, would go wherever a document says.
|
|
192
|
+
"""
|
|
193
|
+
if not server:
|
|
194
|
+
return None
|
|
195
|
+
if server.startswith("/"): # a relative server such as "/api/v1": relative to where the spec lives
|
|
196
|
+
if not _is_http_url(spec_source):
|
|
197
|
+
raise ConfigError(
|
|
198
|
+
f"the spec's server is the relative path {server!r}, so the host is unknown: pass --base-url"
|
|
199
|
+
)
|
|
200
|
+
server = urljoin(spec_source, server)
|
|
201
|
+
host_entry(server) # raises ConfigError unless it is an http(s) URL with a host
|
|
202
|
+
if _is_http_url(spec_source) and _origin(spec_source) == _origin(server):
|
|
203
|
+
return server
|
|
204
|
+
if Allowlist(entries).permits(server):
|
|
205
|
+
return server
|
|
206
|
+
raise ConfigError(
|
|
207
|
+
f"the spec names {server} as its server, but a spec may not choose the target on its own. "
|
|
208
|
+
f"If that is the API you mean to test, pass --base-url {server}"
|
|
209
|
+
)
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _auth_scheme(spec: dict | None, env: dict[str, str]) -> tuple[str, str]:
|
|
213
|
+
"""How to send a token: (header name, text put before the token).
|
|
214
|
+
|
|
215
|
+
APIFUZZ_AUTH_HEADER / APIFUZZ_AUTH_PREFIX win. Otherwise the spec's security scheme decides,
|
|
216
|
+
and "Authorization: Bearer <token>" is the fallback.
|
|
217
|
+
"""
|
|
218
|
+
header, prefix = env.get("APIFUZZ_AUTH_HEADER"), env.get("APIFUZZ_AUTH_PREFIX")
|
|
219
|
+
if header or prefix:
|
|
220
|
+
prefix = (prefix or "").strip()
|
|
221
|
+
if prefix.isalpha(): # a word such as "Bearer" or "Token" is followed by a space
|
|
222
|
+
prefix += " "
|
|
223
|
+
return (header or "Authorization").strip(), prefix
|
|
224
|
+
return _auth_scheme_from_spec(spec) or ("Authorization", "Bearer ")
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _auth_scheme_from_spec(spec: dict | None) -> tuple[str, str] | None:
|
|
228
|
+
if not spec:
|
|
229
|
+
return None
|
|
230
|
+
# OpenAPI 3 keeps schemes under components.securitySchemes; Swagger 2 under securityDefinitions.
|
|
231
|
+
schemes = (spec.get("components") or {}).get("securitySchemes") or spec.get("securityDefinitions") or {}
|
|
232
|
+
if not isinstance(schemes, dict) or not schemes:
|
|
233
|
+
return None
|
|
234
|
+
# Prefer the scheme the spec applies to every operation; otherwise the first one declared.
|
|
235
|
+
names = [n for req in spec.get("security") or [] if isinstance(req, dict) for n in req]
|
|
236
|
+
scheme = next((schemes[n] for n in names if n in schemes), next(iter(schemes.values())))
|
|
237
|
+
if not isinstance(scheme, dict):
|
|
238
|
+
return None
|
|
239
|
+
kind, name = scheme.get("type"), scheme.get("name")
|
|
240
|
+
if kind == "apiKey" and isinstance(name, str) and name:
|
|
241
|
+
if scheme.get("in") == "header":
|
|
242
|
+
return name, ""
|
|
243
|
+
if scheme.get("in") == "cookie":
|
|
244
|
+
return "Cookie", f"{name}="
|
|
245
|
+
return None # bearer, OAuth2 and anything unknown: the Authorization: Bearer fallback
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
def _split_list(value: str | None) -> list[str]:
|
|
249
|
+
# Turn "a, b ,c" into ["a", "b", "c"], dropping empties and whitespace.
|
|
250
|
+
if not value:
|
|
251
|
+
return []
|
|
252
|
+
return [part.strip() for part in value.split(",") if part.strip()]
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _base_url_from_spec(spec: dict | None) -> str | None:
|
|
256
|
+
# OpenAPI 3: the first "servers" entry. Swagger 2: host + basePath + the first scheme.
|
|
257
|
+
if not spec:
|
|
258
|
+
return None
|
|
259
|
+
servers = spec.get("servers")
|
|
260
|
+
if isinstance(servers, list) and servers and isinstance(servers[0], dict):
|
|
261
|
+
url = servers[0].get("url")
|
|
262
|
+
if isinstance(url, str) and url:
|
|
263
|
+
return url
|
|
264
|
+
host = spec.get("host") # Swagger 2
|
|
265
|
+
if isinstance(host, str) and host:
|
|
266
|
+
schemes = spec.get("schemes") or ["https"]
|
|
267
|
+
scheme = schemes[0] if isinstance(schemes, list) and schemes else "https"
|
|
268
|
+
base_path = spec.get("basePath") or ""
|
|
269
|
+
return f"{scheme}://{host}{base_path}"
|
|
270
|
+
return None
|
apifuzz/spec_loader.py
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Load an OpenAPI/Swagger spec from a file or URL, resolve its $refs and validate it.
|
|
2
|
+
|
|
3
|
+
The one public function is load_spec(); everything else in this file is a helper for it.
|
|
4
|
+
Its output (a plain Python dict) is the input to endpoint_model.build_endpoints().
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re # regular expressions: used to cut prance's fake filename out of error messages
|
|
8
|
+
from pathlib import Path # file paths as objects; Path(...).read_text() reads a whole file
|
|
9
|
+
from typing import Any # type hint meaning "any value" (a spec can contain anything)
|
|
10
|
+
|
|
11
|
+
import httpx # HTTP library; used here only to download a spec when given a URL
|
|
12
|
+
from prance import ResolvingParser, ValidationError # prance parses, fills in $refs, validates
|
|
13
|
+
from prance.util.url import ResolutionError # what prance raises when a $ref points nowhere
|
|
14
|
+
|
|
15
|
+
from apifuzz.errors import SpecError # our error type for "something is wrong with the spec"
|
|
16
|
+
|
|
17
|
+
# How many seconds to wait for a spec download before giving up.
|
|
18
|
+
_FETCH_TIMEOUT = 15.0
|
|
19
|
+
|
|
20
|
+
# prance parses from a string using a made-up file name; keep that out of error messages.
|
|
21
|
+
# Matches e.g. "file:///c:/__placeholder_url__.yaml" and stops before "#", so the useful part
|
|
22
|
+
# that follows (like "#/components/schemas/Nope") stays in the message.
|
|
23
|
+
_PLACEHOLDER_URL = re.compile(r"file:///[^#\s\"']*__placeholder_url__\.yaml")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def load_spec(
|
|
27
|
+
source: str, *, client: httpx.Client | None = None, follow_redirects: bool = True
|
|
28
|
+
) -> dict[str, Any]:
|
|
29
|
+
"""Return the validated spec at `source` (a file path or http(s) URL) with internal $refs inlined.
|
|
30
|
+
|
|
31
|
+
Raises SpecError with a readable message for anything wrong with the spec.
|
|
32
|
+
`client` is only used for URL sources and exists so tests can inject a mock transport.
|
|
33
|
+
`follow_redirects=False` makes a redirected spec URL an error. `scan --require-docker` uses
|
|
34
|
+
it, so a spec on a verified container can't send the download to some other host.
|
|
35
|
+
"""
|
|
36
|
+
# Step 1: get the raw text, from disk or from the network.
|
|
37
|
+
text = _read_source(source, client, follow_redirects)
|
|
38
|
+
# Step 2: an empty file would make prance crash with a confusing internal error, so catch it here.
|
|
39
|
+
if not text.strip():
|
|
40
|
+
raise SpecError(f"{source}: the spec is empty")
|
|
41
|
+
|
|
42
|
+
# Step 3: let prance parse the text, replace every $ref with its real content, and validate.
|
|
43
|
+
try:
|
|
44
|
+
parser = ResolvingParser(
|
|
45
|
+
spec_string=text, # we pass the text itself, so files and URLs share one code path
|
|
46
|
+
backend="openapi-spec-validator", # which library checks the spec against OpenAPI rules
|
|
47
|
+
strict=True, # an invalid spec raises an error instead of only printing a warning
|
|
48
|
+
recursion_limit_handler=_cut_recursive_ref, # what to do with self-referencing schemas
|
|
49
|
+
)
|
|
50
|
+
except ValidationError as exc:
|
|
51
|
+
# The spec breaks the OpenAPI rules (or isn't JSON/YAML at all).
|
|
52
|
+
# `from exc` keeps the original error attached for debugging; the user sees our message.
|
|
53
|
+
raise SpecError(f"{source}: {_describe_validation_error(exc)}") from exc
|
|
54
|
+
except ResolutionError as exc:
|
|
55
|
+
# A $ref points at something that doesn't exist, e.g. "#/components/schemas/Nope".
|
|
56
|
+
raise SpecError(f"{source}: could not resolve a reference: {_clean(str(exc))}") from exc
|
|
57
|
+
|
|
58
|
+
# The finished result: a plain dict with no $refs left in it.
|
|
59
|
+
return parser.specification
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _read_source(source: str, client: httpx.Client | None, follow_redirects: bool = True) -> str:
|
|
63
|
+
# Anything starting with http:// or https:// is downloaded; everything else is a file path.
|
|
64
|
+
if source.lower().startswith(("http://", "https://")):
|
|
65
|
+
return _fetch(source, client, follow_redirects)
|
|
66
|
+
# "ftp://...", "file://..." etc. would otherwise be treated as an odd file name.
|
|
67
|
+
# (A Windows path like C:\spec.json has no "://", so it isn't caught here.)
|
|
68
|
+
if "://" in source:
|
|
69
|
+
scheme = source.split("://", 1)[0]
|
|
70
|
+
raise SpecError(f"{source}: unsupported URL scheme '{scheme}'; use a file path or an http(s) URL")
|
|
71
|
+
path = Path(source)
|
|
72
|
+
if path.is_dir():
|
|
73
|
+
# Windows reports reading a folder as "Permission denied", which sends people the wrong way.
|
|
74
|
+
raise SpecError(f"{source}: is a folder, not a spec file")
|
|
75
|
+
try:
|
|
76
|
+
return path.read_text(encoding="utf-8") # specs are UTF-8 text
|
|
77
|
+
except FileNotFoundError:
|
|
78
|
+
# `from None` hides Python's own FileNotFoundError: our message already says everything.
|
|
79
|
+
raise SpecError(f"{source}: file not found") from None
|
|
80
|
+
except (OSError, UnicodeDecodeError) as exc:
|
|
81
|
+
# Any other read problem: no permission, it's a folder, it isn't text...
|
|
82
|
+
raise SpecError(f"{source}: could not read file: {exc}") from exc
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _fetch(url: str, client: httpx.Client | None, follow_redirects: bool = True) -> str:
|
|
86
|
+
# Fetching the spec is a plain GET of a document; scan traffic goes through HttpClient instead.
|
|
87
|
+
# Remember whether WE create the client: we must only close a client we created ourselves,
|
|
88
|
+
# never one a test passed in.
|
|
89
|
+
owns_client = client is None
|
|
90
|
+
# Following redirects is fine by default because we're only downloading a document.
|
|
91
|
+
# (The scanner's HttpClient never does, for safety.)
|
|
92
|
+
client = client or httpx.Client(timeout=_FETCH_TIMEOUT, follow_redirects=follow_redirects)
|
|
93
|
+
try:
|
|
94
|
+
response = client.get(url)
|
|
95
|
+
response.raise_for_status() # turns a 4xx/5xx answer into an HTTPStatusError exception
|
|
96
|
+
return response.text
|
|
97
|
+
except httpx.HTTPStatusError as exc:
|
|
98
|
+
# The server answered, but with an error code like 404 or 500.
|
|
99
|
+
raise SpecError(f"{url}: server answered HTTP {exc.response.status_code}") from exc
|
|
100
|
+
except httpx.HTTPError as exc:
|
|
101
|
+
# The server didn't answer at all: connection refused, DNS failure, timeout...
|
|
102
|
+
raise SpecError(f"{url}: could not fetch spec: {exc}") from exc
|
|
103
|
+
finally:
|
|
104
|
+
# `finally` runs whether we returned or raised, so the connection is always cleaned up.
|
|
105
|
+
if owns_client:
|
|
106
|
+
client.close()
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _cut_recursive_ref(limit: int, parsed_url: Any, recursions: Any = ()) -> dict[str, Any]:
|
|
110
|
+
# Self-referencing schemas (a tree of categories, say) are legal and common. prance's default
|
|
111
|
+
# is to give up; instead we stop expanding at the point of recursion.
|
|
112
|
+
# prance calls this function when it hits the loop, and puts whatever we return in place of
|
|
113
|
+
# the $ref. An empty dict means "stop here". The arguments are required by prance but unused.
|
|
114
|
+
return {}
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _describe_validation_error(exc: ValidationError) -> str:
|
|
118
|
+
# prance stores the readable message as the first argument of the exception.
|
|
119
|
+
message = str(exc.args[0]) if exc.args else "the document is not a valid OpenAPI spec"
|
|
120
|
+
# The validator's message can run to dozens of lines; the first line is the useful summary.
|
|
121
|
+
message = message.splitlines()[0] if message else message
|
|
122
|
+
# __cause__ is the lower-level error prance wrapped (from openapi-spec-validator, when
|
|
123
|
+
# validation failed). It knows WHERE in the spec the problem is.
|
|
124
|
+
cause = exc.__cause__
|
|
125
|
+
# No underlying cause + "Could not parse" means the text wasn't JSON/YAML in the first place.
|
|
126
|
+
if cause is None and message.startswith("Could not parse"):
|
|
127
|
+
return "not valid JSON or YAML, or not an OpenAPI document"
|
|
128
|
+
# `path` is the list of keys leading to the problem, e.g. ["info"] or ["paths", "/a", "get"].
|
|
129
|
+
# getattr(..., ()) returns an empty tuple if the cause has no `path` (or there is no cause).
|
|
130
|
+
location = "/".join(str(part) for part in getattr(cause, "path", ()))
|
|
131
|
+
if location:
|
|
132
|
+
return f"invalid spec at '{location}': {message}"
|
|
133
|
+
return f"invalid spec: {message}"
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def _clean(message: str) -> str:
|
|
137
|
+
# Replace prance's fake filename with nothing (see _PLACEHOLDER_URL at the top of the file).
|
|
138
|
+
return _PLACEHOLDER_URL.sub("", message).strip()
|