XXE via XML parameter entities
XXE parameter entities are a special entity type usable only inside the DTD, written with a percent sign (`%name;`). They are the engine behind blind and error-based XXE, and the fallback when an application strips or blocks ordinary general entities but still processes the DTD's internal subset.
- Target formats
- Plain XMLSOAP
- Affected parsers
- Java XercesPHP libxmlPython lxml
- Impact
- Filter bypassBlind file disclosureExfiltration primitive
How it works
General entities (&name;) appear in the document body; parameter entities (%name;) appear only within the DTD. Many naive XXE filters block the string <!ENTITY followed by a name and SYSTEM, or strip & references, but miss parameter-entity syntax.
Parameter entities can also be nested and can declare further entities dynamically, which is exactly what blind and error-based exfiltration rely on. Understanding them is what lets you build those chains.
Which parser configuration makes it work
Works when the parser processes the internal or external DTD subset and external parameter entities are enabled, even if general entities are filtered by a WAF or input sanitiser.
Representative payloads
Replace callback hosts and target paths with your own authorized test values.
<?xml version="1.0"?>
<!DOCTYPE foo [
<!ENTITY % xxe SYSTEM "file:///etc/passwd">
%xxe;
]>
<foo>trigger</foo>On its own this often only triggers errors; chain it (see blind/error-based XXE) to exfiltrate.
<!ENTITY % outer "<!ENTITY % inner SYSTEM 'file:///etc/hostname'>">
%outer;
%inner;Detection
As a tester, reach for parameter entities when general-entity payloads are blocked. As a defender, ensure your input filtering is not a string-match that only looks for &entity; or general <!ENTITY name SYSTEM> — parameter-entity syntax (<!ENTITY % name) slips past such filters, so detection must look for any DOCTYPE/entity declaration, not a specific form.
- <!ENTITY % declarations in request bodies
- DOCTYPE present despite a general-entity filter being in place
- Percent-reference (%name;) usage in the internal subset
Remediation
Do not rely on string-matching filters to stop XXE — they are routinely bypassed with parameter entities and encoding. Instead disable DOCTYPE processing at the parser, which eliminates both general and parameter entities in one step. If a DTD is required, explicitly disable external-parameter-entities in addition to external-general-entities, and disable external DTD loading, because parameter-entity attacks ignore the general-entity switch.
Fix checklist
- Reject DOCTYPE declarations at the parser (do not filter by regex)
- Disable external PARAMETER entities explicitly where DTDs are allowed
- Disable external DTD loading
- Treat any entity declaration in untrusted XML as hostile