Skip to content

v1.36 - report delivery a person can use

Choose a tag to compare

@hermanekt hermanekt released this 06 Aug 22:19
· 44 commits to main since this release
1ed9cf1

Report delivery, finished: v1.35 could not actually write to disk, and the link it handed back was one an MCP client could open but a person could not.

Behaviour change. report_generate now answers with a link by default instead of an inline base64 PDF, so the return shape changed: callers that read summary["report"] (data:application/pdf;base64,...) get a resource link and a download_url instead. Pass as_link: false for the old inline payload, which still applies the [server].response_max_chars ceiling. This is why the release is v1.36 and not a patch on v1.35.

Fixed

  • save_to_file could never succeed on a default install. The service runs with ProtectSystem=strict, which makes the entire filesystem read-only apart from an explicit allowlist - so [reporting].output_dir failed with Read-only file system no matter who owned the directory, and the directory did not exist in the first place. The unit now declares StateDirectory=zabbix-mcp/reports (mode 0750), which creates it, chowns it to the service user and makes it writable; config.example.toml documents that pointing output_dir elsewhere needs a matching ReadWritePaths.

Added

  • A report link a human can click. zabbix://reports/<id> can only be opened by an MCP client, so the person reading the chat was left with nothing to click. When the server runs over HTTP the same report is now also published at GET /reports/<id>.pdf and the tool returns it as download_url alongside the resource link. The 122-bit random report id (uuid4) is the credential - a capability URL: unguessable, valid for one report, and dead the moment the link expires. The route deliberately needs no bearer token (that is the point of handing it to a person) and answers with Content-Disposition: attachment, Cache-Control: no-store, private, Referrer-Policy: no-referrer and X-Content-Type-Options: nosniff. Turn it off with [reporting].download_urls = false.

    Behind a reverse proxy that forwards a list of paths rather than all of /, add /reports/ to it - otherwise the link looks perfectly correct and answers 404. README, docs/OAUTH.md and config.example.toml all call this out.

    Upgrade note: this is on by default, so a 1.35 install that already serves HTTP starts publishing report downloads at /reports/<id>.pdf after the update, with no config change. The route is unauthenticated by design (the id is the credential). Set [reporting].download_urls = false, or untick Settings -> Report Delivery -> Clickable download link, to keep MCP resource links only.

  • Links are now the default answer for report_generate rather than something the client has to ask for with as_link: true (see the note above), and the tool description tells the model to pass the download URL on instead of trying to render the document.

Fixed (edge cases in the above)

  • Nothing about the link is inferred. The URL is built only from [server].public_url, or from X-Forwarded-Host + X-Forwarded-Proto sent by a peer in [server].trusted_proxies. Neither the local bind nor a bare Host header is used: the shipped default binds 127.0.0.1 behind a reverse proxy, and with no host allowlist configured the MCP SDK rejects any non-loopback Host anyway, so both read 127.0.0.1 in exactly the deployment where a link matters - handing a remote user http://127.0.0.1:8080/reports/<id>.pdf, a dead link that also sends a live report id to whatever answers on their port 8080. A forwarded value is accepted only as a bare authority, so no header can smuggle a path or a second origin into the link, and the last element of a chain is taken because a proxy that appends leaves the client's own value in front.
  • No URL is emitted when none can be built honestly: stdio has no HTTP listener at all, and an unproxied server without public_url has nothing vouching for its address. Both return a download_url_unavailable line naming what to configure; the resource link keeps working on every transport.
  • The effective transport is used rather than the configured one, because --transport overrides config.toml.
  • [server].trusted_proxies entries are now matched as addresses or networks rather than by string equality, so 10.0.0.0/24 and any spelling of an IPv6 address actually match the peer. Previously both were silently ignored, which weakened the token IP allowlist and would now also have suppressed download links; an entry that is neither address nor network logs a warning and keeps its old literal behaviour.
  • Serving download URLs over plaintext HTTP logs a startup warning, and enabling them without public_url logs one too: the report id travels as a bearer credential and the PDF is unencrypted in transit.

Fixed (internal)

  • report_generate base64-encoded the whole PDF on every call - including the link path that discards the string - allocating ~1.37x the file and blocking the event loop for the duration. The inline-size check now computes the encoded length arithmetically and the encode happens only when the PDF is actually returned inline.
  • The report id was documented as 128-bit in SECURITY.md, README.md and the config comments. uuid4().hex is 122 random bits (6 are fixed for version and variant) - ample, but a security document should not overstate it.

Verified

  • 416 unit + e2e tests (two pre-existing macOS-only symlink failures aside), including 21 new cases across two files: the URL builder (stdio, nothing vouched for, forwarded chains, IPv6 literals, values carrying a path/query/CRLF) and the request-context middleware driven as itself - trusted-proxy CIDR and IPv6 matching, an untrusted peer's X-Forwarded-* being ignored, the context not surviving the request, and two interleaved requests never seeing each other's value
  • End to end on a live server: the exact download_url returned by report_generate fetched over HTTPS as a valid PDF with every security header present, and the same tool over stdio returning no URL plus the explanation
  • Reproduced the ProtectSystem=strict failure with systemd-run before the fix and confirmed the write succeeds after it