Skip to main content

Module entity_resolver

sup_xml_core

Module entity_resolver 

Source
Expand description

Pluggable resolver for external XML resources (DTDs, parsed entities) referenced by SYSTEM / PUBLIC identifier.

§Why this exists

XML 1.0 lets DOCTYPE declarations and <!ENTITY> declarations reference external resources by URL. Loading those resources is the primary XXE attack vector — a malicious document can cause a parser to fetch arbitrary URLs, leak local files, or trigger SSRF against internal services.

SupXML’s default behaviour is to refuse all external loading. Callers who genuinely need it (DocBook publishing, XHTML 1.0 processing, JATS, etc.) opt in by setting ParseOptions::external_resolver to either:

  • The recommended FilesystemResolver — loads from a configured allowlist of local directories, optionally consulting an OASIS catalog first.
  • A NetworkResolver (behind the network-resolver feature) — fetches over HTTPS from a configured host allowlist with SSRF defenses.
  • A ChainedResolver composing the two — try local first, fall back to network for anything not pre-cached.
  • A custom EntityResolver impl for bespoke setups (in-memory bundles, S3, audit-logging, etc.).

The presence of a resolver IS the opt-in. Without one, every external reference is rejected.

Structs§

ChainedResolver
Composes multiple resolvers, trying each in order. The first resolver to return either Ok or a non-Refused error wins; Refused falls through to the next resolver.
FilesystemResolver
Recommended default resolver: loads from filesystem only, refuses anything outside the configured allowed-root directories, optionally consults an OASIS catalog first.
InMemoryResolver
Resolver backed by an in-memory map from system_id to bytes. Refuses anything not in the map. Useful in tests where you want deterministic resolution without filesystem dependencies.
NetworkResolver
HTTPS-fetching resolver. Hardened by default with multiple SSRF and amplification defenses; the constructor requires a host allowlist so there’s no convenient “any host” mode.

Enums§

ResolveError
Why a resolver couldn’t deliver the requested bytes.

Traits§

EntityResolver
Resolves external XML resources by their public/system identifier. Implementors decide what URLs are loadable, where the bytes come from, and what security checks apply.