apifuzz 0.2.0__py3-none-any.whl

apifuzz/docker_verify.py

@@ -0,0 +1,168 @@
+"""Confirm that a scan target is a running local Docker container (the --require-docker mode).
+
+Why: a lab target in Docker is the safest thing to point a scanner at. With --require-docker, a
+typo in --base-url (or a .env left over from a real environment) can't send scan traffic anywhere
+except a container running on this machine.
+
+How: ask the Docker CLI for the running containers (`docker ps` + `docker inspect`) and check that
+the target's host:port is one they publish. Two kinds of address count:
+
+* a loopback address written literally (localhost, 127.0.0.1, ::1) on a port a container
+  publishes on all interfaces or on loopback; or
+* a container's own network IP on a port that container exposes (works on Linux bridge networks).
+
+Hostnames are never resolved through DNS. Only those literal names count, so a name that happens
+to resolve to 127.0.0.1 can't slip past the check.
+"""
+
+import json
+import subprocess
+from collections.abc import Callable
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel
+
+from apifuzz.errors import DockerVerifyError
+from apifuzz.http_client import DEFAULT_PORTS
+
+# Hosts that mean "this machine", accepted only as written (lower case, brackets removed).
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+# A port published on one of these host IPs is reachable through loopback.
+_REACHABLE_VIA_LOOPBACK = {"", "0.0.0.0", "::", "127.0.0.1", "::1"}
+
+# Runs a docker command and returns its stdout. Tests pass a fake one instead.
+Runner = Callable[[list[str]], str]
+
+
+class Container(BaseModel):
+    """The parts of a running container that matter for matching a target."""
+
+    id: str
+    name: str  # without docker's leading "/"
+    image: str
+    # Published ports: (host_ip, host_port, container_port) e.g. ("0.0.0.0", 8000, "8000/tcp").
+    published: list[tuple[str, int, str]] = []
+    ips: list[str] = []  # the container's own addresses on its networks
+    exposed: list[int] = []  # TCP ports the container exposes (reachable on its own IPs)
+
+
+class DockerMatch(BaseModel):
+    """A target address and the container that serves it."""
+
+    host: str
+    port: int
+    container: Container
+    how: str  # a human-readable explanation, e.g. "publishes 8000/tcp on 0.0.0.0:8000"
+
+    @property
+    def entry(self) -> str:
+        """The exact allowlist entry for this match, e.g. "localhost:8000" or "[::1]:8000"."""
+        host = f"[{self.host}]" if ":" in self.host else self.host
+        return f"{host}:{self.port}"
+
+
+def _run_docker(args: list[str]) -> str:
+    try:
+        done = subprocess.run(["docker", *args], capture_output=True, text=True, timeout=20)
+    except FileNotFoundError:
+        raise DockerVerifyError(
+            "can't verify the target: the docker command was not found. Install Docker "
+            "(or, for a scan, drop --require-docker)."
+        ) from None
+    except subprocess.TimeoutExpired:
+        raise DockerVerifyError("docker did not answer within 20 seconds; is the Docker daemon running?") from None
+    if done.returncode != 0:
+        detail = (done.stderr or done.stdout).strip().splitlines()
+        raise DockerVerifyError(f"docker {args[0]} failed: {detail[0] if detail else 'no output'}")
+    return done.stdout
+
+
+def running_containers(run: Runner = _run_docker) -> list[Container]:
+    """Every running container, read from `docker ps` and `docker inspect`."""
+    ids = run(["ps", "-q", "--no-trunc"]).split()
+    if not ids:
+        return []
+    try:
+        details = json.loads(run(["inspect", *ids]))
+    except json.JSONDecodeError as exc:
+        raise DockerVerifyError(f"could not read docker inspect output: {exc}") from exc
+    return [_to_container(d) for d in details if (d.get("State") or {}).get("Running")]
+
+
+def _to_container(d: dict) -> Container:
+    net = d.get("NetworkSettings") or {}
+    published = []
+    for container_port, bindings in (net.get("Ports") or {}).items():
+        if not container_port.endswith("/tcp"):
+            continue  # HTTP runs over TCP; UDP ports can't be a scan target
+        for b in bindings or []:  # None when the port is exposed but not published
+            try:
+                published.append((b.get("HostIp") or "", int(b["HostPort"]), container_port))
+            except (KeyError, TypeError, ValueError):
+                continue  # a binding without a usable port number
+    exposed = []
+    for port in ((d.get("Config") or {}).get("ExposedPorts") or {}):
+        number, _, proto = port.partition("/")
+        if proto in ("", "tcp") and number.isdigit():
+            exposed.append(int(number))
+    ips = [n["IPAddress"] for n in (net.get("Networks") or {}).values() if n and n.get("IPAddress")]
+    return Container(
+        id=str(d.get("Id", ""))[:12],
+        name=str(d.get("Name", "")).lstrip("/"),
+        image=str((d.get("Config") or {}).get("Image", "")),
+        published=published,
+        ips=ips,
+        exposed=exposed,
+    )
+
+
+def _host_port(target: str) -> tuple[str, int]:
+    """Split a URL or "host:port" entry into (host, port), using 80/443 for a URL with no port."""
+    parsed = urlsplit(target if "://" in target else f"//{target}")
+    try:
+        host, port = parsed.hostname, parsed.port
+    except ValueError:
+        host, port = None, None
+    if not host:
+        raise DockerVerifyError(f"{target!r} has no usable host")
+    if port is None:
+        if parsed.scheme not in DEFAULT_PORTS:
+            raise DockerVerifyError(
+                f"allowlist entry {target!r} has no port; with --require-docker every entry must be host:port"
+            )
+        port = DEFAULT_PORTS[parsed.scheme]
+    return host, port
+
+
+def match_target(target: str, containers: list[Container]) -> DockerMatch:
+    """Return the container serving `target` (a URL or host:port), or raise DockerVerifyError."""
+    host, port = _host_port(target)
+    for c in containers:
+        for host_ip, host_port, container_port in c.published:
+            if host_port != port:
+                continue
+            if (host in _LOOPBACK and host_ip in _REACHABLE_VIA_LOOPBACK) or host == host_ip:
+                return DockerMatch(
+                    host=host, port=port, container=c,
+                    how=f"publishes {container_port} on {host_ip or '0.0.0.0'}:{host_port}",
+                )
+        if host in c.ips and port in c.exposed:
+            return DockerMatch(host=host, port=port, container=c, how=f"has IP {host} and exposes {port}/tcp")
+
+    if not containers:
+        raise DockerVerifyError(f"{target}: no Docker containers are running")
+    if host not in _LOOPBACK and not any(host in c.ips for c in containers):
+        raise DockerVerifyError(
+            f"{target}: host {host!r} is not localhost, 127.0.0.1, ::1 or a running container's IP"
+        )
+    raise DockerVerifyError(f"{target}: no running container publishes port {port}")
+
+
+def verify_targets(base_url: str, extra_entries: list[str], run: Runner = _run_docker) -> list[DockerMatch]:
+    """Check the base URL and every extra allowlist entry. All must match a running container.
+
+    Returns one match per target (base URL first), so the caller can build an allowlist of
+    exact host:port entries and show which container each one belongs to.
+    """
+    containers = running_containers(run)
+    return [match_target(t, containers) for t in [base_url, *extra_entries]]

apifuzz/endpoint_model.py

@@ -0,0 +1,180 @@
+"""Flatten a resolved OpenAPI/Swagger document into a list of Endpoint objects.
+
+Input: the spec as a Python dict, with every $ref already filled in (spec_loader does that).
+Output: one Endpoint per path + method pair, e.g. GET /orders/{id}.
+The security checks in later phases read these Endpoints to decide which requests to send.
+"""
+
+from typing import Any  # type hint meaning "any value" (a spec can contain anything)
+
+from pydantic import BaseModel  # gives classes typed fields, validation, and free JSON output
+
+# The only keys in a path item that are operations. Other keys live next to them
+# ("parameters", "summary", "x-something") and must not be mistaken for HTTP methods.
+HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+
+
+class Parameter(BaseModel):
+    """A value sent outside the request body: in the URL path, query string, a header or a cookie."""
+
+    name: str  # e.g. "id" or "q"
+    location: str  # "path", "query", "header" or "cookie" (copied from the spec's "in" field)
+    required: bool = False  # class default only; _to_parameter always passes the real value
+    type: str | None = None  # e.g. "integer"; None when the spec doesn't say
+
+
+class RequestField(BaseModel):
+    """One top-level field of a request body (a JSON property or a form field)."""
+
+    name: str  # e.g. "username"
+    required: bool = False  # True if the body schema lists this name under "required"
+    type: str | None = None  # e.g. "string", "array[integer]", "object"
+
+
+class Endpoint(BaseModel):
+    """Everything the scanner needs to know about one operation, e.g. PATCH /users/{id}."""
+
+    path: str  # the URL template, placeholders included: "/orders/{id}"
+    method: str  # upper case: GET, POST...
+    operation_id: str | None = None  # the spec's optional unique name for the operation
+    summary: str | None = None  # the spec's optional one-line description
+    parameters: list[Parameter] = []  # path/query/header/cookie values (pydantic copies this default safely)
+    request_fields: list[RequestField] = []  # fields of the request body, if it has one
+    requires_auth: bool = False  # True if a login token must be sent
+    tags: list[str] = []  # the spec's grouping labels, e.g. ["orders"]; used by --tag
+    deprecated: bool = False  # the spec marks this operation as deprecated
+
+
+def build_endpoints(spec: dict[str, Any]) -> list[Endpoint]:
+    """List every operation in `spec`, in the order the spec declares them.
+
+    `spec` must already have its $refs resolved (see spec_loader.load_spec).
+    """
+    endpoints: list[Endpoint] = []
+    # spec["paths"] maps each URL template to a "path item": {"/orders/{id}": {"get": {...}}}.
+    # `or {}` covers a spec where "paths" is present but empty (None).
+    for path, path_item in (spec.get("paths") or {}).items():
+        if not isinstance(path_item, dict):  # skip anything malformed instead of crashing
+            continue
+        # Parameters declared on the path itself apply to every method under that path.
+        shared_params = path_item.get("parameters") or []
+        for method in HTTP_METHODS:
+            operation = path_item.get(method)  # None if this path doesn't support this method
+            if not isinstance(operation, dict):
+                continue
+            # Combine the path's shared parameters with the operation's own ones.
+            parameters = _merge_parameters(shared_params, operation.get("parameters") or [])
+            endpoints.append(
+                Endpoint(
+                    path=path,
+                    method=method.upper(),
+                    operation_id=operation.get("operationId"),
+                    summary=operation.get("summary"),
+                    # "body" and "formData" are Swagger 2's way of describing the request body.
+                    # They are body content, not URL parameters, so _request_fields handles them.
+                    parameters=[_to_parameter(p) for p in parameters if p.get("in") not in ("body", "formData")],
+                    request_fields=_request_fields(operation, parameters),
+                    requires_auth=_requires_auth(operation, spec),
+                    tags=[str(t) for t in operation.get("tags") or []],
+                    deprecated=bool(operation.get("deprecated", False)),
+                )
+            )
+    return endpoints
+
+
+def _merge_parameters(path_level: list[dict], operation_level: list[dict]) -> list[dict]:
+    # A parameter is identified by (name, location); the operation's version wins over the path's.
+    merged: dict[tuple[str, str], dict] = {}
+    # Path-level ones go in first, operation-level ones second. Writing to a dict key that
+    # already exists replaces the old value, so the operation's version wins.
+    for param in [*path_level, *operation_level]:
+        if isinstance(param, dict) and "name" in param:  # ignore malformed entries
+            merged[(param["name"], param.get("in", ""))] = param
+    return list(merged.values())
+
+
+def _to_parameter(param: dict) -> Parameter:
+    # OpenAPI 3 nests the type under "schema"; Swagger 2 puts it on the parameter itself.
+    # `param.get("schema") or param` handles both: use "schema" if there is one, else the parameter.
+    schema = param.get("schema") or param
+    location = param["in"]
+    return Parameter(
+        name=param["name"],
+        location=location,
+        # Use the spec's "required" value (False if it doesn't say). A path parameter is always
+        # required, because the URL can't be built without it.
+        required=bool(param.get("required", False)) or location == "path",
+        type=_type_label(schema),
+    )
+
+
+def _request_fields(operation: dict, parameters: list[dict]) -> list[RequestField]:
+    # OpenAPI 3: requestBody.content.<media type>.schema
+    content = (operation.get("requestBody") or {}).get("content") or {}
+    if content:
+        # Prefer the JSON version of the body; otherwise take the first media type listed.
+        media = content.get("application/json") or next(iter(content.values()))
+        return _schema_fields((media or {}).get("schema") or {})
+
+    # Swagger 2: an "in: body" parameter carries a schema; "in: formData" parameters are the fields.
+    for param in parameters:
+        if param.get("in") == "body":
+            return _schema_fields(param.get("schema") or {})
+    return [
+        RequestField(name=p["name"], required=bool(p.get("required", False)), type=_type_label(p))
+        for p in parameters
+        if p.get("in") == "formData"
+    ]  # empty list when the operation has no body at all (a GET, usually)
+
+
+def _schema_fields(schema: dict) -> list[RequestField]:
+    # Turn an object schema into one RequestField per top-level property.
+    properties, required = _collect_properties(schema)
+    return [
+        RequestField(name=name, required=name in required, type=_type_label(sub))
+        for name, sub in properties.items()
+    ]
+
+
+def _collect_properties(schema: dict) -> tuple[dict[str, dict], set[str]]:
+    """Gather the properties of an object schema, merging allOf branches."""
+    properties: dict[str, dict] = {}
+    required: set[str] = set(schema.get("required") or [])  # a set, so duplicates collapse
+    # "allOf" builds a schema out of several pieces that all apply at once (e.g. base fields +
+    # extras). This function calls itself on each piece and merges the results.
+    for branch in schema.get("allOf") or []:
+        sub_properties, sub_required = _collect_properties(branch or {})
+        properties.update(sub_properties)
+        required |= sub_required  # `|=` adds the piece's required names to ours (set union)
+    # The schema's own properties go last, so they win over same-named ones from allOf.
+    properties.update(schema.get("properties") or {})
+    return properties, required
+
+
+def _type_label(schema: dict) -> str | None:
+    # Produce a short, human-readable type like "integer", "array[string]" or "object".
+    schema_type = schema.get("type")
+    if schema_type == "array":
+        # Look inside "items" to say what the array holds.
+        item_type = _type_label(schema.get("items") or {})
+        return f"array[{item_type}]" if item_type else "array"
+    # Specs often leave out "type": "object" when the schema clearly has fields.
+    if schema_type is None and ("properties" in schema or "allOf" in schema):
+        return "object"
+    # OpenAPI 3.1 allows a list like ["string", "null"]. "null" only means "may be empty", so
+    # drop it; several real types left are joined, e.g. "string|integer".
+    if isinstance(schema_type, list):
+        real = [str(t) for t in schema_type if t != "null"]
+        return "|".join(real) or None
+    return schema_type if isinstance(schema_type, str) else None
+
+
+def _requires_auth(operation: dict, spec: dict) -> bool:
+    # An operation's own "security" replaces the global one, and "security: []" switches auth off.
+    # .get(key, default) only uses the default when the key is ABSENT, so an explicit [] is kept.
+    security = operation.get("security", spec.get("security"))
+    if not security:  # None (never mentioned) or [] (explicitly no auth)
+        return False
+    # "security" is a list of alternatives; meeting any one of them is enough.
+    # An empty requirement object ({}) is an alternative that means "no credentials needed".
+    return all(bool(requirement) for requirement in security)

apifuzz/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions raised by apifuzz. The CLI turns any ApifuzzError into a one-line message."""
+
+# Why custom exception classes? They let the CLI tell "expected problems" (bad spec, blocked
+# host) apart from real bugs. The CLI catches ApifuzzError and prints a friendly message;
+# any other exception is a bug and is allowed to show a full traceback.
+
+
+class ApifuzzError(Exception):
+    """Base class for errors that are safe to show to the user as-is."""
+
+
+# Each subclass below inherits from ApifuzzError, so `except ApifuzzError` catches all of them,
+# while code that cares about one specific problem can catch just that subclass.
+
+
+class SpecError(ApifuzzError):
+    """The OpenAPI spec could not be read, parsed, resolved or validated."""
+
+
+class AllowlistError(ApifuzzError):
+    """A request was refused because its target is not on the allowlist."""
+
+
+class DockerVerifyError(ApifuzzError):
+    """--require-docker is on, and the target couldn't be confirmed as a running Docker container."""
+
+
+class RequestError(ApifuzzError):
+    """A request to an allowed target failed at the network level (refused, timed out...)."""
+
+
+class SessionError(ApifuzzError):
+    """Logging in a test account failed (bad credentials, no login endpoint, no token in the answer)."""
+
+
+class RequestLimitError(ApifuzzError):
+    """The scan reached --max-requests. It stops there instead of sending more."""

apifuzz/finding.py

@@ -0,0 +1,55 @@
+"""What a check reports when it finds something: a Finding, plus the severity scale.
+
+A Finding is deliberately plain data. A check creates it; the reporter displays it. It carries the
+Exchange(s) that back it up, so a reader can see the exact request and response behind the claim.
+"""
+
+import hashlib  # the finding's fingerprint
+from enum import IntEnum  # an ordered set of severities, so findings can be sorted worst-first
+
+from pydantic import BaseModel, computed_field, field_serializer
+
+from apifuzz.http_client import Exchange
+
+
+class Severity(IntEnum):
+    """How serious a finding is. IntEnum so `sorted(..., reverse=True)` puts the worst first."""
+
+    INFO = 0  # not a flaw: something worth noting, or a check that confirmed good behaviour
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    def __str__(self) -> str:  # so it prints as "HIGH", not "Severity.HIGH"
+        return self.name
+
+
+class Finding(BaseModel):
+    """One result from one check about one endpoint."""
+
+    check: str  # the id of the check that produced this, e.g. "auth-required"
+    owasp: str = ""  # the OWASP API Security Top 10 category, e.g. "API1:2023 Broken Object Level Authorization"
+    severity: Severity
+    title: str  # a short headline, e.g. "Endpoint reachable without authentication"
+    endpoint: str  # which operation, as "METHOD /path", e.g. "GET /orders/{id}"
+    detail: str  # a sentence or two explaining what was observed and why it matters
+    remediation: str = ""  # how a developer fixes it, in a sentence or two
+    # The request/response pairs that justify the finding. Kept so a report can show evidence and
+    # a reader can reproduce it. May be empty for an INFO note that isn't about a specific request.
+    evidence: list[Exchange] = []
+    # What tells this finding apart from another by the same check on the same endpoint, e.g. the
+    # field or parameter name. Empty when a check reports at most one finding per endpoint.
+    key: str = ""
+
+    # A short stable id built from the check, the endpoint and the key. It stays the same from one
+    # run to the next, so two reports can be compared and a finding can be marked as accepted.
+    @computed_field  # included in the JSON output
+    @property
+    def fingerprint(self) -> str:
+        return hashlib.sha256(f"{self.check}|{self.endpoint}|{self.key}".encode()).hexdigest()[:16]
+
+    # In JSON, write the severity as "HIGH" rather than the number 3, so reports read clearly.
+    @field_serializer("severity")
+    def _severity_name(self, severity: Severity) -> str:
+        return severity.name

apifuzz/http_client.py

@@ -0,0 +1,221 @@
+"""The only place apifuzz sends requests to a target.
+
+Every request is checked against an allowlist before it leaves the process, and the raw request
+and response are recorded so a finding can later show its evidence.
+"""
+
+import time  # used to measure how long each request took
+from collections.abc import Iterable  # type hint for "anything you can loop over"
+from types import TracebackType  # type hint used by __exit__ (the `with` statement support)
+from typing import Any
+from urllib.parse import urlparse  # splits a URL into scheme, host, port, path...
+
+import httpx  # the HTTP library that actually sends requests
+from pydantic import BaseModel  # typed record classes with free JSON output
+
+from apifuzz import __version__
+from apifuzz.errors import AllowlistError, RequestError, RequestLimitError
+
+# The only schemes we allow, and the port each one uses when the URL doesn't name a port.
+DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+class Allowlist:
+    """Hosts the tool may talk to. Entries are `host` (any port) or `host:port`.
+
+    Matching is exact on the host name: allowing `example.com` does not allow `api.example.com`.
+    An empty allowlist permits nothing.
+    """
+
+    def __init__(self, entries: Iterable[str] = ()) -> None:
+        # Stored as (host, port) pairs; port None means "any port on this host".
+        # A set makes duplicates disappear and lookups fast.
+        self._entries: set[tuple[str, int | None]] = set()
+        for entry in entries:
+            self._entries.add(self._parse_entry(entry))
+
+    @staticmethod  # doesn't need `self`; it's a helper that belongs with this class
+    def _parse_entry(entry: str) -> tuple[str, int | None]:
+        text = entry.strip()
+        # urlparse only recognises a host when it follows "//". A bare entry like "localhost:8000"
+        # would be misread as a path, so we put "//" in front. Full URLs already have "://".
+        parsed = urlparse(text if "://" in text else f"//{text}")
+        try:
+            # .hostname is lower-cased and has [ ] removed from IPv6 addresses.
+            # .port raises ValueError for a non-number like "localhost:abc".
+            host, port = parsed.hostname, parsed.port
+        except ValueError:
+            host, port = None, None
+        if not host:
+            # A bad entry is a configuration mistake: fail loudly rather than allow nothing silently.
+            raise ValueError(f"invalid allowlist entry: {entry!r}")
+        return host, port
+
+    def permits(self, url: str) -> bool:
+        try:
+            parsed = urlparse(url)
+            # Using .hostname (not the raw text) defeats tricks like "http://allowed.com@evil.test/":
+            # the part before "@" is a username, and the real host is evil.test.
+            host, port = parsed.hostname, parsed.port
+        except ValueError:
+            return False  # unparseable URL: refuse
+        if parsed.scheme not in DEFAULT_PORTS or not host:
+            return False  # only http(s) with a real host; no file://, ftp://, etc.
+        port = port or DEFAULT_PORTS[parsed.scheme]  # no port in the URL -> 80 or 443
+        # Allowed if ANY entry has the same host and either no port restriction or the same port.
+        return any(host == allowed_host and allowed_port in (None, port) for allowed_host, allowed_port in self._entries)
+
+    def check(self, url: str) -> None:
+        # Same test as permits(), but raises instead of returning False, so callers can't
+        # forget to look at the answer.
+        if not self.permits(url):
+            raise AllowlistError(f"refusing to contact {url}: its host is not on the allowlist")
+
+
+# The three record classes below are the "evidence" a finding will show in a report.
+
+
+class RecordedRequest(BaseModel):
+    method: str  # "GET", "POST"...
+    url: str  # the full URL as sent, query string included
+    headers: dict[str, str]  # every header sent, including Authorization
+    body: str | None = None  # None for requests without a body (a GET, usually)
+
+
+class RecordedResponse(BaseModel):
+    status_code: int  # 200, 403, 404...
+    headers: dict[str, str]
+    body: str  # the body as text, cut off at the capture limit
+    truncated: bool = False  # True when the body was longer than the capture limit
+
+    @property
+    def ok(self) -> bool:
+        """True for a 2xx status: the request succeeded."""
+        return 200 <= self.status_code < 300
+
+
+class Exchange(BaseModel):
+    """One request and the response it got, as sent and received."""
+
+    request: RecordedRequest
+    response: RecordedResponse
+    elapsed_ms: float  # how long the round trip took (useful later for the rate-limit check)
+
+
+class HttpClient:
+    """Sends requests to allowlisted hosts and returns them as Exchange records.
+
+    Redirects are never followed: a redirect could point at a host outside the allowlist, so the
+    3xx response is returned as it is. Request headers (including Authorization) are recorded
+    unredacted; redaction belongs to the reporter.
+    """
+
+    def __init__(
+        self,
+        allowlist: Allowlist,
+        *,  # everything after this must be passed by name, e.g. timeout=5
+        timeout: float = 10.0,  # seconds before a request is abandoned
+        max_body_bytes: int = 64 * 1024,  # keep at most 64 KB of each response body
+        transport: httpx.BaseTransport | None = None,  # tests pass a fake network here
+        max_requests: int | None = None,  # stop the scan after this many requests (None = no cap)
+        delay: float = 0.0,  # seconds to wait between requests, to go easy on the target
+    ) -> None:
+        self._allowlist = allowlist
+        self._max_body_bytes = max_body_bytes
+        self._max_requests = max_requests
+        self._delay = delay
+        self.requests_sent = 0  # requests that left the process (whether or not they were answered)
+        self.responses_received = 0  # requests that got an HTTP answer back
+        # One reusable httpx client: it keeps connections open between requests (faster).
+        # The User-Agent names the tool, so the target's logs show where the traffic came from.
+        self._client = httpx.Client(
+            timeout=timeout,
+            follow_redirects=False,
+            transport=transport,
+            headers={"User-Agent": f"apifuzz/{__version__}"},
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,  # e.g. {"Authorization": "Bearer <token>"}
+        params: dict[str, Any] | None = None,  # query string values, e.g. {"q": "book"}
+        json: Any = None,  # a body to send as JSON
+        data: dict[str, str] | None = None,  # a body to send as form fields (some logins need this)
+    ) -> Exchange:
+        # httpx's `params=` REPLACES a query string already in the URL ("/search?q=a" would lose
+        # q=a). Merge instead, so a URL from the spec or the user keeps its own query values.
+        full_url = httpx.URL(url).copy_merge_params(params) if params else url
+        # Build the request without sending it, so we can inspect the final URL first.
+        request = self._client.build_request(method, full_url, headers=headers, json=json, data=data)
+        self._allowlist.check(str(request.url))  # before anything is sent
+        if self._max_requests is not None and self.requests_sent >= self._max_requests:
+            raise RequestLimitError(f"request limit reached ({self._max_requests}); raise it with --max-requests")
+        if self._delay and self.requests_sent:
+            time.sleep(self._delay)
+        self.requests_sent += 1
+
+        started = time.perf_counter()  # a high-precision clock, good for measuring durations
+        try:
+            # stream=True means "don't download the whole body yet"; we read it ourselves below
+            # so we can stop at the size limit instead of loading a huge response into memory.
+            response = self._client.send(request, stream=True)
+            try:
+                body, truncated = self._read_body(response)
+            finally:
+                response.close()  # always release the connection, even if reading failed
+        except httpx.HTTPError as exc:
+            # Network-level failure (refused, timed out...). Convert it to our own error type.
+            # `exc or type(exc).__name__`: some httpx errors have an empty message; fall back to the class name.
+            raise RequestError(f"{method.upper()} {request.url}: {exc or type(exc).__name__}") from exc
+        elapsed_ms = (time.perf_counter() - started) * 1000  # seconds -> milliseconds
+        self.responses_received += 1
+
+        # Package everything into plain records that a report can show later.
+        return Exchange(
+            request=RecordedRequest(
+                method=request.method,
+                url=str(request.url),
+                headers=dict(request.headers),
+                # request.content is raw bytes; decode to text. errors="replace" swaps any bytes
+                # that aren't valid UTF-8 for a placeholder character instead of crashing.
+                body=request.content.decode("utf-8", errors="replace") if request.content else None,
+            ),
+            response=RecordedResponse(
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                body=body,
+                truncated=truncated,
+            ),
+            elapsed_ms=elapsed_ms,
+        )
+
+    def _read_body(self, response: httpx.Response) -> tuple[str, bool]:
+        # Read the body in chunks and stop once we have more than the limit.
+        received = bytearray()  # a growable byte buffer
+        for chunk in response.iter_bytes():
+            received += chunk
+            if len(received) > self._max_body_bytes:
+                break
+        # "More than the limit" (not "equal to") means something was actually cut off.
+        truncated = len(received) > self._max_body_bytes
+        return bytes(received[: self._max_body_bytes]).decode("utf-8", errors="replace"), truncated
+
+    def close(self) -> None:
+        self._client.close()  # close the open connections
+
+    # __enter__ and __exit__ let you write `with HttpClient(...) as client:`.
+    # The client is then closed automatically when the `with` block ends, even after an error.
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()