asm-mcp 1.0.0__py3-none-any.whl

asm_mcp/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 F6 JSC
+# SPDX-License-Identifier: Apache-2.0
+
+"""MCP server for the F6 ASM (Attack Surface Management) client API."""
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

asm_mcp/__main__.py

@@ -0,0 +1,9 @@
+# Copyright 2026 F6 JSC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Entry point for `python -m asm_mcp`."""
+
+from asm_mcp.server import cli
+
+if __name__ == "__main__":
+    cli()

asm_mcp/arguments.py

@@ -0,0 +1,243 @@
+# Copyright 2026 F6 JSC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tool arguments as typed models: one model per tool both checks what the
+caller sent and produces the tool's inputSchema, so the two cannot drift.
+
+The checks themselves are the ones in params.py; the models only say which
+check applies to which argument. Their messages name the argument and the
+value, because the model reads them and has to fix the call.
+"""
+
+from collections.abc import Callable
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, PlainValidator, ValidationError, WithJsonSchema
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+
+from asm_mcp.catalog import (
+    ASSET_STATUSES,
+    ASSET_TYPES,
+    ISSUE_STATUSES,
+    OPEN_ISSUE_STATUSES,
+    PERIMETER_STATUSES,
+    SEVERITIES,
+    TEST_NAME_EXAMPLES,
+)
+from asm_mcp.params import (
+    MAX_LIST_ITEMS,
+    as_int,
+    check_fields,
+    check_id,
+    check_issue_id,
+    check_ports,
+    check_seq_update,
+    choice_list,
+    text_list,
+)
+from asm_mcp.settings import MAX_PAGE_SIZE
+
+
+def checked(kind: Any, check: Callable[[Any], Any], schema: JsonSchemaValue) -> Any:
+    """An argument of type `kind` validated by one of the params.py checks and
+    shown to the client as `schema`. The check alone decides what passes."""
+    return Annotated[kind, PlainValidator(check), WithJsonSchema(schema)]
+
+
+def _int(name: str, minimum: int, maximum: int) -> Any:
+    return checked(int | None, lambda v: as_int(name, v, minimum=minimum, maximum=maximum), NUMBER)
+
+
+def _choices(name: str, allowed: dict[str, Any]) -> Any:
+    schema = {"type": "array", "items": {"type": "string", "enum": list(allowed)}}
+    return checked(list[str], choice_list(name, tuple(allowed)), schema)
+
+
+def _texts(name: str) -> Any:
+    return checked(list[str], text_list(name), STRINGS)
+
+
+def _issue_ids(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list) or len(value) > MAX_LIST_ITEMS:
+        raise ValueError(f"issue_hash must be a list of at most {MAX_LIST_ITEMS} issue ids")
+    return list(dict.fromkeys(check_issue_id(v) for v in value))
+
+
+STRING = {"type": "string"}
+NUMBER = {"type": "number"}
+STRINGS = {"type": "array", "items": STRING}
+
+CompanyId = checked(str, lambda v: check_id(v, "company_id"), STRING)
+SeqUpdate = checked(str | None, check_seq_update, STRING)
+Fields = checked(list[str], check_fields, STRINGS)
+
+COMPANY_DESCRIPTION = "Company id from asm_list_companies (field id), e.g. 3f2b6c1e-0000-4a5b-8c9d-0123456789ab."
+SEQ_DESCRIPTION = (
+    "Resume cursor: the seqUpdate of a previous answer of this tool with the same filters. "
+    "Omit to start from the oldest record. Saved after a full walk, it returns only what "
+    "changed since."
+)
+PAGE_DESCRIPTION = (
+    f"Records per API request, at most {MAX_PAGE_SIZE}. A page that times out is retried at "
+    "half the size automatically."
+)
+COMPACT_DESCRIPTION = (
+    "Default true: drop heavy and repeated fields (whois/DNS of domains, discovery graph, "
+    "descriptions, company fields). false returns records as the API sent them."
+)
+SEVERITY_DESCRIPTION = (
+    "crit / high / medium / low. In records they read as alertSeverity Crit / Error / Warning / "
+    "Low and alertBody.status 'Critical severity' / 'High severity' / ..."
+)
+
+
+class Arguments(BaseModel):
+    """Base of every tool's arguments. Unknown keys are ignored."""
+
+
+class ListCompaniesArguments(Arguments):
+    pass
+
+
+class GetAssetsArguments(Arguments):
+    company_id: CompanyId = Field(description=COMPANY_DESCRIPTION)
+    seq_update: SeqUpdate = Field(None, description=SEQ_DESCRIPTION)
+    max_items: _int("max_items", 1, 5000) = Field(
+        None, description="Integer, 1-5000, default 500: stop after this many assets."
+    )
+    page_size: _int("page_size", 1, MAX_PAGE_SIZE) = Field(None, description=PAGE_DESCRIPTION)
+    type: _choices("type", ASSET_TYPES) = Field(
+        default_factory=list,
+        description="Asset types; empty = all. Infrastructure = domain, ip, ip_range, ssl.",
+    )
+    status: _choices("status", ASSET_STATUSES) = Field(
+        default_factory=list,
+        description=(
+            "Empty = all, including excluded assets ('false'). The company perimeter is "
+            "['confirmed', 'new']."
+        ),
+    )
+    asset: _texts("asset") = Field(default_factory=list, description="Exact asset values (domain, IP).")
+    software: _texts("software") = Field(default_factory=list, description="Software names, e.g. nginx.")
+    version: _texts("version") = Field(default_factory=list, description="Software versions.")
+    compact: bool = Field(True, description=COMPACT_DESCRIPTION)
+    fields: Fields = Field(
+        default_factory=list,
+        description="Return only these fields, e.g. ['asset', 'type', 'status', 'hasIssues', 'ports'].",
+    )
+
+
+class GetIssuesArguments(Arguments):
+    company_id: CompanyId = Field(description=COMPANY_DESCRIPTION)
+    seq_update: SeqUpdate = Field(None, description=SEQ_DESCRIPTION)
+    max_items: _int("max_items", 1, 5000) = Field(
+        None, description="Integer, 1-5000, default 200: stop after this many issues."
+    )
+    page_size: _int("page_size", 1, MAX_PAGE_SIZE) = Field(None, description=PAGE_DESCRIPTION)
+    severity: _choices("severity", SEVERITIES) = Field(default_factory=list, description=SEVERITY_DESCRIPTION)
+    status: _choices("status", ISSUE_STATUSES) = Field(
+        default_factory=list,
+        description=f"Empty = every status. Open issues = {list(OPEN_ISSUE_STATUSES)}.",
+    )
+    category: _texts("category") = Field(
+        default_factory=list, description="e.g. Vulnerabilities, Network Security, DNS & Domains."
+    )
+    test_name: _texts("test_name") = Field(
+        default_factory=list,
+        description="Exact test names, e.g. " + ", ".join(repr(t) for t in TEST_NAME_EXAMPLES[:3]) + ".",
+    )
+    asset: _texts("asset") = Field(default_factory=list, description="Issues of these assets (domain, IP).")
+    port: checked(list[int], check_ports, {"type": "array", "items": NUMBER}) = Field(
+        default_factory=list, description="Ports, e.g. [22, 3389]."
+    )
+    issue_hash: checked(list[str], _issue_ids, STRINGS) = Field(
+        default_factory=list, description="Specific issues by id (alertHash)."
+    )
+    cve: _texts("cve") = Field(default_factory=list, description="CVE ids, e.g. CVE-2024-6387.")
+    sort_by_first_seen: bool | None = Field(None, description="Order by first detection instead of last update.")
+    compact: bool = Field(True, description=COMPACT_DESCRIPTION)
+    fields: Fields = Field(
+        default_factory=list,
+        description=(
+            "Return only these fields, dotted paths allowed, e.g. ['alertHash', 'alertSeverity', "
+            "'alertStatus', 'testName', 'alertBody.asset', 'alertBody.reason']."
+        ),
+    )
+
+
+class IssueEvidenceArguments(Arguments):
+    issue_id: checked(str, check_issue_id, STRING) = Field(description="Issue id (alertHash, 32 hex digits).")
+
+
+class AssetsSummaryArguments(Arguments):
+    company_id: CompanyId = Field(description=COMPANY_DESCRIPTION)
+    type: _choices("type", ASSET_TYPES) = Field(default_factory=list, description="Empty = all types.")
+    status: checked(list[str] | None, lambda v: None if v is None else choice_list("status", tuple(ASSET_STATUSES))(v),
+                    {"type": "array", "items": {"type": "string", "enum": list(ASSET_STATUSES)}}) = Field(
+        None,
+        description=f"Default: the perimeter {list(PERIMETER_STATUSES)}. Pass all three to include excluded.",
+    )
+
+
+class IssuesSummaryArguments(Arguments):
+    company_id: CompanyId = Field(description=COMPANY_DESCRIPTION)
+    status: checked(list[str] | None, lambda v: None if v is None else choice_list("status", tuple(ISSUE_STATUSES))(v),
+                    {"type": "array", "items": {"type": "string", "enum": list(ISSUE_STATUSES)}}) = Field(
+        None, description=f"Default: open issues {list(OPEN_ISSUE_STATUSES)}. Pass every status for history."
+    )
+    severity: _choices("severity", SEVERITIES) = Field(default_factory=list, description=SEVERITY_DESCRIPTION)
+    asset: _texts("asset") = Field(default_factory=list, description="Only issues of these assets.")
+
+
+class DescribeArguments(Arguments):
+    section: Literal["assets", "issues", "requests", "limits"] | None = Field(
+        None, description="Optional: only this part of the reference."
+    )
+
+
+class RequestArguments(Arguments):
+    method: Literal["GET", "POST"] = Field(
+        "GET", description="GET for most routes; POST for dashboard/scores and issues/leaks."
+    )
+    path: str = Field(description="Path under /api/v2 without a leading slash, e.g. \"reports/<company_id>/last\".")
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Query parameters (GET) or JSON body (POST), only the keys the route accepts.",
+    )
+
+
+class _ToolSchema(GenerateJsonSchema):
+    """inputSchema without anyOf-with-null, defaults or titles."""
+
+    def nullable_schema(self, schema: Any) -> JsonSchemaValue:
+        return self.generate_inner(schema["schema"])
+
+    def default_schema(self, schema: Any) -> JsonSchemaValue:
+        return self.generate_inner(schema["schema"])
+
+    def field_title_should_be_set(self, schema: Any) -> bool:
+        return False
+
+
+def input_schema(model: type[Arguments]) -> dict[str, Any]:
+    schema = model.model_json_schema(schema_generator=_ToolSchema)
+    schema.pop("title", None)
+    return schema
+
+
+def describe_errors(error: ValidationError) -> str:
+    """One line per bad argument, worded for the model that has to fix the call."""
+    messages = []
+    for item in error.errors(include_url=False):
+        name = ".".join(str(part) for part in item["loc"])
+        if item["type"] == "missing":
+            messages.append(f"{name} is required")
+        elif item["type"] == "value_error":
+            messages.append(str(item["ctx"]["error"]))
+        else:
+            messages.append(f"{name}: {item['msg']}")
+    return "; ".join(messages)

asm_mcp/catalog.py

@@ -0,0 +1,166 @@
+# Copyright 2026 F6 JSC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Reference data about the ASM client API, taken from its swagger (Client API
+3.0.0) and the server code, and the read-only routes asm_request may reach.
+
+Everything here is answered locally by asm_describe, with no API call."""
+
+from dataclasses import dataclass
+
+# --------------------------------------------------------------------------- values
+
+ASSET_TYPES: dict[str, str] = {
+    "domain": "domain or subdomain found for the company",
+    "ip": "single IP address with ports, ASN, netname, location",
+    "ip_range": "IP range (netblock) with ASN and netname",
+    "ssl": "TLS certificate: common name, issuer, validity",
+    "software": "software/version detected on a host and port (the source of most CVE issues)",
+    "login_form": "login form found on a company site",
+    "typosq": "typosquatting domain imitating the company (a third party's asset, not the company's)",
+}
+INFRA_ASSET_TYPES = ("domain", "ip", "ip_range", "ssl")
+
+# 'false' is a string here: the swagger lists it as a JSON boolean by mistake,
+# the server (ASSET_STATUS) compares strings.
+ASSET_STATUSES: dict[str, str] = {
+    "confirmed": "in the perimeter, confirmed by the client or by rules",
+    "new": "found and attributed to the company, not yet reviewed",
+    "false": "excluded from the perimeter (false positive or not the company's)",
+}
+PERIMETER_STATUSES = ("confirmed", "new")
+
+ISSUE_STATUSES: dict[str, str] = {
+    "detected": "open, found by the last scan",
+    "under review": "open, being handled",
+    "solved": "no longer observed",
+    "manually solved": "closed by a user",
+    "ignored": "accepted risk",
+    "false positive": "marked as not a real problem",
+}
+OPEN_ISSUE_STATUSES = ("detected", "under review")
+
+# filter value -> alertSeverity in a record -> alertBody.status in a record
+SEVERITIES: dict[str, tuple[str, str]] = {
+    "crit": ("Crit", "Critical severity"),
+    "high": ("Error", "High severity"),
+    "medium": ("Warning", "Medium severity"),
+    "low": ("Low", "Low severity"),
+}
+
+ISSUE_CATEGORIES = (
+    "Vulnerabilities", "Network Security", "DNS & Domains", "SSL/TLS Security", "Email Security",
+)
+TEST_NAME_EXAMPLES = (
+    "CVE vulnurability",  # sic: the server spells it this way, filters must too
+    "Insecure Network Headers",
+    "Remote management open port: 22",
+    "Certificate expires soon",
+    "Invalid certificate",
+    "Domain Expired",
+    "Open login form",
+    "DNS DNSSEC",
+    "SPF Record Published",
+    "DMARC Policy Enabled",
+)
+
+ASSET_FIELDS: dict[str, tuple[str, ...]] = {
+    "common": ("id", "asset", "type", "status", "hasIssues", "score", "discoverBy", "detectionDate",
+               "lastSeen", "lastScan", "tags", "seqUpdate"),
+    "domain": ("registrar", "regDate", "expDate", "owner", "email", "redirecting", "ssl_cert", "domainInfo"),
+    "ip": ("asn", "netname", "location", "ports", "range_number"),
+    "ip_range": ("ip_range_asn", "ip_range_netname", "ip_range_location", "ip_range_ports"),
+    "ssl": ("common", "issuer", "valid_from", "valid_till", "hash"),
+    "software": ("software", "version", "software_type", "software_port", "vulnerabilities"),
+    "login_form": ("login_form_domain", "login_form_software", "login_form_report_id"),
+    "typosq": ("typosq_root_domain", "typosq_owner", "typosq_redirect", "typosq_domain_status",
+               "typosq_dotmagnet_id"),
+}
+ISSUE_FIELDS = (
+    "alertHash", "alertSeverity", "alertStatus", "testName", "alertFirstSeen", "alertLastSeen",
+    "alertLifetime", "commandToCheck", "alertMitreInfo", "alertAdditionInfo", "seqUpdate",
+    "alertBody.asset", "alertBody.valuetype", "alertBody.category", "alertBody.status",
+    "alertBody.reason", "alertBody.description", "alertBody.cve", "alertBody.software_info",
+    "alertBody.port", "alertBody.protocol", "alertBody.url", "alertBody.score", "alertBody.path",
+)
+
+QUIRKS = (
+    "The status filter of /issues/updated lets through records with other statuses; tools "
+    "re-check status and severity locally and report how many they dropped (droppedByFilter).",
+    "With a status filter and a small count the API answers an empty page with seqUpdate null; "
+    "tools never ask for fewer than 100 records when a filter is set and trim locally.",
+    "Large /assets/updated pages of domains time out (whois/DNS in every record), and large "
+    "/issues/updated pages are sometimes refused with 400 \"Failed to get paged issues\"; such a "
+    "page is retried at half the size, down to 50.",
+    "The resume cursor is the seqUpdate of the last record returned, so continuing with it never "
+    "skips records; records are ordered oldest-first and an updated record is renumbered.",
+    "Without a status filter /assets/updated returns excluded assets (status 'false') too; the "
+    "company perimeter is status confirmed + new.",
+    "testName of CVE findings is spelled 'CVE vulnurability'.",
+    "POST issues/leaks fails without an explicit status list; asm_request sends every valid status "
+    "when status is left out.",
+    "GET reports/{company_id}/last can exceed the 1 MB result limit for a large company; "
+    "GET reports/{company_id} lists report ids, reports/{report_id}/report returns one report.",
+)
+
+RATE_LIMIT = (
+    "one request per second per token across all endpoints (0.1 s for paid clients), 429 otherwise; "
+    "accounts may also have a request quota (403 \"Your API request limit has been reached\")"
+)
+
+
+# --------------------------------------------------------------------------- asm_request routes
+
+
+@dataclass(frozen=True)
+class Route:
+    """A read-only endpoint asm_request may call.
+
+    template: path under /api/v2, placeholders in braces; params: the only
+    keys accepted, sent as the query string (GET) or the JSON body (POST).
+    """
+
+    method: str
+    template: str
+    description: str
+    params: tuple[str, ...] = ()
+    required: tuple[str, ...] = ()
+    # Values sent when the caller leaves a param out, for params the server
+    # needs although the swagger marks them optional.
+    defaults: tuple[tuple[str, object], ...] = ()
+
+    @property
+    def segments(self) -> tuple[str, ...]:
+        return tuple(self.template.split("/"))
+
+
+ROUTES: tuple[Route, ...] = (
+    Route("GET", "companies", "companies available to the token (also asm_list_companies)"),
+    Route("GET", "companies/logs", "change log of companies", ("companyId", "dateFrom", "dateTo")),
+    Route("GET", "companies/{company_id}", "company card: client, license type, scan country, branches"),
+    Route("GET", "assets/{company_id}",
+          "perimeter settings: confirmed and excluded domains and IPs set by hand"),
+    Route("GET", "reports/{company_id}", "list of the company's reports"),
+    Route("GET", "reports/{company_id}/last", "the latest report of the company"),
+    Route("GET", "reports/{report_id}/report", "one full report by its id"),
+    Route("GET", "issues/evidence/{issue_id}", "evidence of one issue (also asm_get_issue_evidence)"),
+    Route("GET", "users/logs", "actions of this account's users", ("dateFrom", "dateTo")),
+    Route("GET", "clients", "clients visible to the token"),
+    Route("GET", "clients/{client_id}", "one client"),
+    Route("GET", "partners", "partners visible to the token"),
+    Route("POST", "dashboard/scores", "security score history and counters of a company",
+          ("companyId", "dateFrom", "dateTo"), ("companyId",)),
+    Route("POST", "issues/leaks", "leaked credentials of the company's domains; companyId is a list",
+          ("companyId", "dateFrom", "dateTo", "status"), ("companyId", "dateFrom", "dateTo"),
+          # Without status the server fails its own validation ("Status[1] must be one of ...").
+          (("status", ["detected", "under review", "solved", "ignored", "false positive"]),)),
+)
+
+# Literal segments of every route in the API, including the ones that change data:
+# a placeholder may never take one of them, so a template cannot be bent into
+# another endpoint ("companies/{company_id}" must not reach "companies/create").
+LITERAL_SEGMENTS = frozenset({
+    "companies", "assets", "reports", "issues", "users", "clients", "partners", "dashboard",
+    "logs", "last", "report", "evidence", "scores", "leaks", "updated", "create", "update",
+    "add", "remove", "status", "change", "comments", "domain", "ip", "get_token", "web", "hi",
+})

asm_mcp/client.py

@@ -0,0 +1,241 @@
+# Copyright 2026 F6 JSC
+# SPDX-License-Identifier: Apache-2.0
+
+"""The HTTP client: requests to the ASM API with a Bearer token, throttling,
+retries and the checks that keep an unexpected body out of the model's context."""
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from asm_mcp.settings import (
+    API_ROOT,
+    MAX_ERROR_CHARS,
+    MAX_RESULT_BYTES,
+    RETRY_STATUSES,
+    USER_AGENT,
+    Settings,
+)
+
+
+class BudgetExceeded(Exception):
+    """The caller's deadline would pass before the next request or retry could finish.
+    Pages already received stay valid; the caller returns them with a resume cursor."""
+
+
+class APIError(RuntimeError):
+    """A non-2xx answer from ASM, with the status kept for callers that branch on it."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class RequestTimeout(RuntimeError):
+    """One request outlived ASM_TIMEOUT. Paging reacts by halving the page:
+    heavy /assets/updated pages of domains are the usual cause."""
+
+
+# Closes the hints of the statuses where the request never got a real answer,
+# so that the model does not report "nothing found".
+NOT_FETCHED = " — nothing was read, so report this data as unchecked, not as empty"
+
+# Built from the server code (middlewares.try_handle_client_api, RateLimitDecorator,
+# checker_api_limit, the request validators), so a failing call says what to fix
+# instead of echoing a code.
+STATUS_HINTS: dict[int, str] = {
+    400: (
+        "bad request — the body below names what the server rejected; fix that argument "
+        "(asm_describe lists the accepted values and params)"
+    ),
+    401: "ASM_API_TOKEN is missing, wrong or revoked — issue a new API token in ASM",
+    403: (
+        "either this token has no access to the company (check company_id against "
+        "asm_list_companies), a partner account called a client-only endpoint, or the API "
+        "request quota of the account is used up (\"Your API request limit has been reached\")"
+    ),
+    404: "no such record or endpoint on this ASM installation",
+    422: "ASM failed to build the answer (\"An error has occurred\"), retry later" + NOT_FETCHED,
+    429: (
+        "rate limited — one request per second per token (0.1 s for paid clients); lower the "
+        "pace with ASM_MIN_INTERVAL"
+    ),
+    500: "server-side error on the ASM side, retry in a few minutes" + NOT_FETCHED,
+    502: "ASM is unavailable behind its proxy, retry in a few minutes" + NOT_FETCHED,
+    503: "ASM is temporarily unavailable, retry in a few minutes" + NOT_FETCHED,
+    504: "ASM did not answer in time — lower page_size so it has less to process" + NOT_FETCHED,
+}
+
+
+class Throttle:
+    """Keeps requests at most one per min_interval seconds.
+
+    The ASM limit is per token across all endpoints, so there is one interval
+    for the whole process. The lock is held across the wait to serialise callers;
+    a deadline that the wait would overrun raises BudgetExceeded instead.
+    """
+
+    def __init__(self, min_interval: float) -> None:
+        self._min_interval = min_interval
+        self._lock = asyncio.Lock()
+        self._last_start: float | None = None
+
+    async def acquire(self, deadline: float | None = None) -> None:
+        if self._min_interval <= 0:
+            return
+        async with self._lock:
+            loop = asyncio.get_running_loop()
+            wait = 0.0
+            if self._last_start is not None:
+                wait = max(0.0, self._min_interval - (loop.time() - self._last_start))
+            if deadline is not None and loop.time() + wait >= deadline:
+                raise BudgetExceeded()
+            if wait:
+                await asyncio.sleep(wait)
+            self._last_start = loop.time()
+
+
+class ASMClient:
+    """The ASM API as this process sees it: one connection pool and one throttle
+    for the server's whole lifetime, so calls reuse open connections and share
+    the rate limit.
+
+    trust_env=False keeps HTTP_PROXY and SSL_CERT_FILE out of the picture: the
+    proxy is ASM_PROXY, the CA is ASM_CA_BUNDLE, both stated. follow_redirects
+    stays off on purpose: a redirect would carry the token to wherever it points.
+    A transport, when given, replaces the network entirely (tests), so the
+    proxy and TLS settings do not apply to it.
+    """
+
+    def __init__(self, settings: Settings, *, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        self._settings = settings
+        self._throttle = Throttle(settings.min_interval)
+        network: dict[str, Any] = (
+            {"verify": settings.verify, "proxy": settings.proxy}
+            if transport is None
+            else {"transport": transport}
+        )
+        self._http = httpx.AsyncClient(
+            timeout=settings.timeout, follow_redirects=False, trust_env=False, **network
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        deadline: float | None = None,
+        max_bytes: int = MAX_RESULT_BYTES,
+    ) -> Any:
+        """One API call. `path` is relative to /api/v2 and built by the caller
+        from constants and checked segments only (params.py)."""
+        settings = self._settings
+        if not settings.base_url or not settings.api_token:
+            raise RuntimeError(
+                "ASM_BASE_URL and ASM_API_TOKEN environment variables must be set "
+                "(the address of your ASM installation and an API token)"
+            )
+        url = f"{settings.base_url}{API_ROOT}/{path.lstrip('/')}"
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            "Authorization": f"Bearer {settings.api_token}",
+        }
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        loop = asyncio.get_running_loop()
+        timeout = settings.timeout
+
+        try:
+            for attempt in range(settings.retries + 1):
+                await self._throttle.acquire(deadline)
+                timeout = settings.timeout
+                if deadline is not None:
+                    remaining = deadline - loop.time()
+                    if remaining <= 0.1:
+                        raise BudgetExceeded()
+                    # A request cut short by the budget is a budget stop, not a slow page.
+                    timeout = min(timeout, remaining)
+                response = await self._http.request(
+                    method, url, params=query, json=body, headers=headers, timeout=timeout
+                )
+                if response.status_code not in RETRY_STATUSES or attempt == settings.retries:
+                    break
+                retry_after = (response.headers.get("Retry-After") or "").strip()
+                delay = (
+                    float(retry_after)
+                    if retry_after.replace(".", "", 1).isdigit()
+                    else max(settings.min_interval, 0.5) * (2**attempt)
+                )
+                if deadline is not None and loop.time() + delay >= deadline:
+                    raise BudgetExceeded()
+                await asyncio.sleep(delay)
+        except httpx.TimeoutException as error:
+            # Cut short by the caller's budget, with no time left: a budget stop, not a slow page.
+            if timeout < settings.timeout and deadline is not None and deadline - loop.time() <= 0.5:
+                raise BudgetExceeded() from error
+            raise RequestTimeout(
+                f"ASM did not answer {method} {path} within {settings.timeout:.0f} s "
+                "(ASM_TIMEOUT) — lower page_size or narrow the filters" + NOT_FETCHED
+            ) from error
+        except httpx.HTTPError as error:
+            # Transport failures can carry an empty message, so name the class and
+            # the URL, and say how the proxy comes into play. Values of the ambient
+            # variables are never echoed: they can carry a password.
+            detail = str(error) or type(error).__name__
+            if settings.proxy:
+                hint = f" Requests go through ASM_PROXY ({settings.proxy_display})."
+            elif settings.ambient_proxy:
+                hint = " HTTP(S)_PROXY is ignored; set ASM_PROXY to route through a proxy."
+            else:
+                hint = ""
+            raise RuntimeError(f"Network error contacting {url}: {detail}.{hint}") from error
+
+        return _parse(response, path, max_bytes)
+
+
+def _parse(response: httpx.Response, path: str, max_bytes: int) -> Any:
+    """The JSON body of a successful answer, or an error that says what went wrong."""
+    if response.is_redirect:
+        location = response.headers.get("Location", "")
+        raise RuntimeError(
+            f"API error {response.status_code} (redirect to {location or 'unknown'}): not followed, "
+            "because it would carry the token elsewhere — check ASM_BASE_URL (scheme, host, a "
+            "trailing path) and whether a login proxy sits in front of the API"
+        )
+
+    if not response.is_success:
+        parts = [f"API error {response.status_code} {response.reason_phrase}".rstrip()]
+        if hint := STATUS_HINTS.get(response.status_code, ""):
+            parts.append(hint)
+        # Only echo a JSON error body, and only a bounded slice of it: an HTML
+        # error page can carry tracebacks, settings and upstream names.
+        if _is_json(response) and (text := response.text.strip()):
+            parts.append(text[:MAX_ERROR_CHARS])
+        raise APIError(response.status_code, " — ".join(parts))
+
+    if len(response.content) > max_bytes:
+        raise RuntimeError(
+            f"response is {len(response.content)} bytes, over the {max_bytes} byte limit "
+            "— narrow the request"
+        )
+    if not response.content:
+        return {"status": response.status_code, "body": None}
+    # Decided by the body, not the header. An HTML page or a binary file does
+    # not parse, so neither reaches the model.
+    try:
+        return response.json()
+    except ValueError as error:
+        content_type = response.headers.get("content-type", "unknown")
+        raise RuntimeError(
+            f"expected JSON from {path}, got an unparsable body (content-type '{content_type}')"
+        ) from error
+
+
+def _is_json(response: httpx.Response) -> bool:
+    return response.headers.get("content-type", "").split(";")[0].strip() == "application/json"