XXE: how XML external entities work and the parser settings that stop them
XML external entity (XXE) injection happens when an XML parser follows an instruction inside a document to fetch content from somewhere else, such as a file on your server or an address on your network.
Entities declared inside the same document can also expand until memory runs out, with nothing fetched at all. This guide explains what an entity is, where XML still turns up in applications built on JSON, and why the fix is a parser setting rather than an input filter. It gives you a parser configuration worksheet and a local DTD canary lab that shows what your parser does with its defaults and with hardened settings.
In this guide
XML parser worksheet, parser reference table and DTD canary lab
An illustration written for this page, not client code. A configuration worksheet with one block for every place your application parses XML and four yes or no questions; a reference table of what the Python, libxml2, PHP, Java and .NET documentation says for each question and for which version; and a Python lab that runs three harmless canaries (a marker file in its own temporary folder, a bounded entity expansion and a 127.0.0.1 listener) through each parser with its defaults, opened up and hardened, with a regression test.
How to use itHide the instructions
Recorded on macOS 27.2.1 with Python 3.14.7 and libxml2 2.9.13 and 2.15.3. Use it on your own computer to learn, and to test parsers you own.
xxe.txt
ILLUSTRATION ONLY. The worksheet, the canary documents, the lab code and the results below were written and recorded for this page. They are not a client's code or a client's result. Use the canaries on your own computer to learn, and to test a parser you own or are authorised in writing to test. Every canary stays on your machine: the file canary points at a marker file the lab writes into its own temporary folder, the expansion canary stops at 30,000 characters, and the network canary calls a listener the lab starts on 127.0.0.1. Do not point any part of it at a system file, at another machine or at someone else's server.
This asset has three parts:
PART 1. An XML parser configuration worksheet, one block for every place your application parses XML.
PART 2. A parser reference table: what each parser's own documentation says about the four worksheet questions, and for which version.
PART 3. A local DTD canary lab in Python, with the output it printed and a regression test.
==== PART 1. XML PARSER CONFIGURATION WORKSHEET ====
Copy the block below once for every place your application parses XML, including places where a library parses it for you. Answer each question yes or no, and write down the setting that decides the answer, named as the parser's documentation names it. When the documentation does not settle a question for your version, the canaries in Part 3 answer it.
PLACES TO LOOK
API bodies: routes that accept application/xml or text/xml, SOAP endpoints, XML-RPC, and routes written for JSON. On a staging copy, send each JSON route the file canary with Content-Type: application/xml and record whether it is parsed or refused.
File imports: spreadsheets, catalogue and stock files, bank and accounting exports, data feeds from partners.
Office and SVG uploads: .docx, .xlsx and .pptx files, SVG images, and anything your server converts, previews or resizes.
SAML and other federation messages: single sign-on responses, assertions and metadata.
Feeds: RSS, Atom and sitemap files your server fetches or accepts.
Configuration: XML settings files, manifests and anything read at start-up from a location someone else can write to.
Libraries: document converters, PDF and image tools, and SDKs that accept XML and parse it on your behalf.
---- BLOCK: copy once per place ----
Place, and the route or job that parses it:
Who can send this XML (the public, signed-in users, a partner, your own staff):
Parser, library and version, and the Expat or libxml2 version underneath where there is one:
Q1. Are external entities resolved? yes / no Setting that decides it:
Q2. Are DTDs processed at all? yes / no Setting that decides it:
Q3. Is entity expansion limited? yes / no Limit, and the setting that sets it:
Q4. Can the parser reach the network? yes / no Setting that decides it:
Where the documented parser policy is written down (file, wiki page or code comment):
Canary results (file, expansion, network) and the date they were last run:
Regression test that keeps it this way:
WHAT TO AIM FOR WITH UNTRUSTED XML
OWASP's XML External Entity Prevention Cheat Sheet says to disable DTDs whenever possible and to reject DOCTYPE declarations if the parser supports it. That makes Q2 no, and Q1 and Q3 follow from it. If your application needs DTDs, the same cheat sheet says to disable external entity resolution and external DTD loading, and to limit entity expansion: Q1 no, Q3 yes. It also says to restrict external access during schema validation and style sheet processing as well as XML parsing, and to treat an unsupported security setting as a configuration failure rather than carry on with partial hardening. Q4 no.
---- WORKED EXAMPLE: the lab's hardened xml.sax profile ----
Place, and the route or job that parses it: the lab only, xml.sax in the hardened profile
Who can send this XML: anyone, so it is treated as untrusted
Parser, library and version: Python 3.14.7 xml.sax, Expat 2.7.4 (pyexpat.EXPAT_VERSION)
Q1. Are external entities resolved? no feature_external_ges set to False (the default since Python 3.7.1, set anyway so the code says it)
Q2. Are DTDs processed at all? no a pyexpat StartDoctypeDeclHandler that raises, run before the real parse
Q3. Is entity expansion limited? yes no DTD means no entity declarations; Expat's own protection sits underneath
Q4. Can the parser reach the network? no nothing is loaded, because the document is refused at its DOCTYPE
Where the documented parser policy is written down: the comments at the top of parsers.py
Canary results and the date: file REFUSED, expansion REFUSED, network REFUSED, no request to the listener; 14 November 2026
Regression test that keeps it this way: test_canaries.py, run with LAB_PROFILE unset
==== PART 2. PARSER REFERENCE TABLE ====
Each entry gives what the parser's own documentation says for each worksheet question, and the version that documentation covers. Defaults have changed between versions, so read the documentation for the version you run and confirm it with the canaries. Every page below was opened on 14 November 2026.
PYTHON STANDARD LIBRARY: xml.etree.ElementTree, xml.dom.minidom, xml.dom.pulldom, xml.sax
Documentation: Python 3.14 (XML Processing Modules, xml.sax, xml.sax.handler, xml.dom.minidom, xml.dom.pulldom, xml.parsers.expat), and the Python 3.12 XML Processing Modules page for its vulnerability table.
Underneath: the built-in XML parsers rely on Expat. Whether Python uses its bundled copy or a system-wide Expat depends on how the interpreter was configured, so check pyexpat.EXPAT_VERSION. The 3.14 page says Expat versions lower than 2.7.2 may be vulnerable to the billion laughs, quadratic blowup and large tokens vulnerabilities, or to disproportional use of dynamic memory.
Q1 External entities: since Python 3.7.1 the SAX parser no longer processes general external entities by default; setFeature() with feature_external_ges switches it back on, and the documentation warns that enabling it opens a vulnerability to external entity attacks with user-provided XML. xml.dom.pulldom carries the same 3.7.1 note. The 3.12 table adds that ElementTree does not expand external entities and raises ParseError when an entity occurs, and that minidom does not expand external entities and returns the unexpanded entity verbatim.
Q2 DTDs: to refuse a DTD, the lab's hardened profile raises from pyexpat's StartDoctypeDeclHandler, which the documentation says is called when Expat begins parsing the document type declaration. OWASP's cheat sheet, for its part, recommends the defusedxml package's parsing interfaces for untrusted XML, with forbid_dtd=True on the interfaces that offer it when DTDs are unnecessary; the lab sticks to the standard library and does not use it.
Q3 Expansion: pyexpat's SetBillionLaughsAttackProtectionActivationThreshold() and SetBillionLaughsAttackProtectionMaximumAmplification(), added in Python 3.14.6. Parser objects usually have an activation threshold of 8 MiB and a maximum amplification factor of 100, but the actual defaults depend on the Expat library underneath. The documentation notes that thresholds below 4 MiB are known to break DITA 1.3 payloads and are not recommended.
Q4 Network: by default, Expat itself does not access local files or create network connections. Before Python 3.7.1, the SAX parser created network connections to fetch remote files.
LIBXML2 AND XMLLINT (the same library sits under PHP's XML extensions)
Documentation: the current xmllint documentation (it notes --nonet has no effect with libxml2 2.15 or later), the xmllint documentation at version 2.9.13, the libxml2 NEWS file and OWASP's XML External Entity Prevention Cheat Sheet.
Q1 External entities: the PHP documentation says entity substitution is disabled by default as of libxml 2.9.0; XML_PARSE_NOENT, in the cheat sheet's words, expands entities and substitutes them with replacement text; xmllint's --noent, in its documentation's words, substitutes entity values for entity references. Both versions of the xmllint documentation say that by default xmllint leaves entity references in place, and the current one adds that --noent enables loading of external DTDs and entities. NEWS lists "Do not fetch external parsed entities" under 2.9.0, and a parser option XML_PARSE_NO_XXE under 2.13.0 that disables loading of external entities or DTDs.
Q2 DTDs: XML_PARSE_DTDLOAD, in the cheat sheet's words, loads the external DTD; xmllint's --loaddtd fetches an external DTD and external parameter entities. The cheat sheet says neither XML_PARSE_NOENT nor XML_PARSE_DTDLOAD should be set.
Q3 Expansion: the current xmllint documentation gives --max-ampl, the maximum amplification factor that protects against exponential entity expansion, a default of 5. NEWS lists xmlCtxtSetMaxAmplification under 2.12.0, added to let applications parse files that would otherwise trigger the billion laughs protection. --huge ignores some hardcoded parser limits; leave it off for untrusted input.
Q4 Network: NEWS says that from 2.13.0 HTTP support is disabled by default and has to be enabled with --with-http when libxml2 is built; 2.13 still turned it on by default in legacy mode, 2.14.0 stopped the legacy option enabling it, and 2.15.0 removed the built-in HTTP client. On older builds --nonet stops xmllint fetching DTDs or entities from the Internet.
PHP: DOM, XMLReader and XMLWriter, on top of libxml2
Documentation: the PHP documentation for libxml_disable_entity_loader() and for the libxml constants, and OWASP's cheat sheet.
Q1 External entities: as of libxml 2.9.0 entity substitution is disabled by default, and libxml_disable_entity_loader() is deprecated as of PHP 8.0.0. The PHP documentation says it is generally preferable to use libxml_set_external_entity_loader() to suppress loading of external entities, and that LIBXML_NO_XXE needs libxml 2.13.0 or later and PHP 8.4.0. It warns that enabling LIBXML_NOENT may facilitate XXE attacks. The cheat sheet says to install a callback that returns null, and that passing null directly to libxml_set_external_entity_loader() is not equivalent.
Q2 DTDs: the PHP documentation warns that LIBXML_DTDLOAD and LIBXML_DTDATTR enable fetching of external entities, and that LIBXML_DTDVALID may facilitate XXE attacks.
Q3 Expansion: LIBXML_PARSEHUGE increases some hardcoded parser limits, such as the maximum depth of a document or the entity recursion, and the documentation says it should only be used with trusted data.
Q4 Network: LIBXML_NONET disables network access when loading documents.
JAVA: JAXP (DocumentBuilderFactory, SAXParserFactory, XMLInputFactory, TransformerFactory, SchemaFactory)
Documentation: the Java API for XML Processing (JAXP) Security Guide for JDK 27, with the JDK 21 guide for comparison, and OWASP's cheat sheet.
Q1 External entities: the JDK 27 guide says the JDK turns FEATURE_SECURE_PROCESSING on by default for SAX, DOM, validation and transformation factories, but external connections such as external entity resolution are not disabled by default; setting the feature explicitly on the factory disables them.
Q2 DTDs: jdk.xml.dtd.support takes allow (the default), ignore or deny. For SAX and DOM, the feature http://apache.org/xml/features/disallow-doctype-decl set to true throws a fatal error on a DOCTYPE; for StAX, XMLInputFactory.SUPPORT_DTD set to false.
Q3 Expansion: the processing-limits table in the JAXP Security Guide for JDK 27 gives jdk.xml.entityExpansionLimit a default of 2500 and jdk.xml.totalEntitySizeLimit a default of 100000, where the JDK 21 guide's table gives 64000 for entityExpansionLimit; the JDK 27 guide's Limiting Entity Expansion section still says 64,000. Check the value your own runtime uses.
Q4 Network: javax.xml.accessExternalDTD (external DTDs and external entity references), accessExternalSchema and accessExternalStylesheet each default to all; an empty string grants no protocol.
.NET: XmlReader with XmlReaderSettings
Documentation: Microsoft's .NET 10 API reference for XmlReaderSettings, and OWASP's cheat sheet for the other .NET readers.
Q1 and Q4: XmlReaderSettings.XmlResolver. If it is null, the reader throws an XmlException when it tries to access an external resource. Starting with .NET Framework 4.5.2 its default is null; before that, a new XmlUrlResolver with no credentials.
Q2 DTDs: DtdProcessing defaults to Prohibit, which throws an XmlException when a DTD is encountered; Ignore skips the DTD and Parse processes it.
Q3 Expansion: MaxCharactersFromEntities defaults to 0, which means no limit on the characters that expanding entities can produce.
Other readers: the cheat sheet says XmlDocument, XmlTextReader and XPathNavigator are vulnerable to external entity attacks below .NET Framework 4.5.2, and that an ASP.NET application on .NET Framework 4.5.2 or later must also set httpRuntime targetFramework to 4.5.2 or later in Web.config, or risk being vulnerable regardless of the actual .NET version.
==== PART 3. LOCAL DTD CANARY LAB ====
WHAT IT NEEDS
Python 3 and its standard library, with nothing to install, and xmllint if your system has it. The results below were recorded on macOS 27.2.1 with Python 3.14.7 (Expat 2.7.4), the xmllint that ships with macOS (libxml2 2.9.13), and a second xmllint from a libxml2 2.15.3 package, named in LAB_XMLLINT. Your results depend on your own Python, Expat and libxml2 versions, so run it and read your own table. The expansion limit probe needs Python 3.14.6 or later, where pyexpat added the method it calls; on an older Python it says so and skips. The commands under RUN IT set environment variables the way macOS and Linux shells do; on Windows, set them the way your shell does.
WHAT IT DOES NOT DO
The lab writes everything into one new temporary folder and deletes it when it finishes. The only file any canary points at is marker.txt in that folder, which holds the word LAB-FILE-CANARY. The listener runs on 127.0.0.1, on a port the operating system picks, records the path of every request and answers with a fixed word; it is stopped when the lab finishes. Nothing contacts another machine and no canary names a real system file. In the output, LAB stands for the temporary folder and PORT for the listener's port, because both change on every run.
THE THREE CANARIES (written by lab_setup.py, and printed at the start of the output)
file a DOCTYPE with an internal subset that declares one external entity, marker, whose system identifier is the file: URI of marker.txt, and a canary element that refers to it. A parser that resolves it hands the application LAB-FILE-CANARY.
expansion four levels of internal entities, each repeating the one before ten times, under a DOCTYPE. Full expansion is 10,000 copies of LAB: 30,000 characters from a document of a few hundred bytes. It shows whether DTDs are processed at all, and whether a limit applies at that size.
network a DOCTYPE whose external DTD is http://127.0.0.1:PORT/canary.dtd and whose internal subset declares an external entity at http://127.0.0.1:PORT/entity. The listener records which of the two the parser asked for.
The lab also writes a UTF-16 copy of the file canary for the text filter check.
THE THREE PROFILES (in parsers.py)
DEFAULT each parser as it comes, with no settings changed.
OPENED UP a documented option that turns entity loading on: feature_external_ges for xml.sax and minidom, --noent with --loaddtd for xmllint. The lab gives ElementTree no opened-up profile; the Python 3.12 documentation's table says it does not expand external entities. This column exists to prove the canaries detect a parser that resolves them. Never ship it.
HARDENED the profile to copy. Python: refuse any document with a DOCTYPE, using the pyexpat hook above, then parse with external general entities off. xmllint: no --noent, no --loaddtd, and --nonet.
SET-UP
Make an empty folder, save the five files below into it under the names shown, and run the commands under RUN IT from that folder.
==== File 1 of 5: lab_setup.py ====
# lab_setup.py: builds the lab on this computer. It makes a temporary folder,
# writes a marker file and the canary documents into it, and starts a
# listener on 127.0.0.1 that records every request and answers with a fixed
# word. Nothing here reads a file outside that folder or contacts another
# machine. close_lab() stops the listener and deletes the folder.
import http.server
import os
import pathlib
import shutil
import tempfile
import threading
FILE_MARKER = 'LAB-FILE-CANARY'
NETWORK_MARKER = 'LAB-NETWORK-CANARY'
EXPANSION_LEVELS = 4
EXPANSION_COPIES = 10
EXPANDED_LENGTH = len('LAB') * EXPANSION_COPIES ** EXPANSION_LEVELS
class RecordingHandler(http.server.BaseHTTPRequestHandler):
# Records the path of every request. /canary.dtd gets a DTD that holds
# only a comment; any other path gets the network marker word.
def do_GET(self):
self.server.requests.append(self.path)
body = NETWORK_MARKER
if self.path.endswith('.dtd'):
body = '<!-- ' + NETWORK_MARKER + ' -->'
self.send_response(200)
self.send_header('Content-Type', 'text/plain')
self.end_headers()
self.wfile.write(body.encode('utf-8'))
def log_message(self, format, *args):
pass
def start_listener():
server = http.server.ThreadingHTTPServer(('127.0.0.1', 0), RecordingHandler)
server.requests = []
threading.Thread(target=server.serve_forever, daemon=True).start()
return server
def write_text(path, lines, encoding):
with open(path, 'w', encoding=encoding) as handle:
for line in lines:
print(line, file=handle)
def file_canary(marker_uri, encoding):
return [
'<?xml version="1.0" encoding="' + encoding + '"?>',
'<!DOCTYPE canary [',
' <!ENTITY marker SYSTEM "' + marker_uri + '">',
']>',
'<canary>▮</canary>',
]
def expansion_canary():
lines = ['<?xml version="1.0"?>', '<!DOCTYPE canary [', ' <!ENTITY e0 "LAB">']
for level in range(1, EXPANSION_LEVELS + 1):
reference = '&e' + str(level - 1) + ';'
lines.append(' <!ENTITY e' + str(level) + ' "' + reference * EXPANSION_COPIES + '">')
lines.append(']>')
lines.append('<canary>&e' + str(EXPANSION_LEVELS) + ';</canary>')
return lines
def network_canary(base_url):
return [
'<?xml version="1.0"?>',
'<!DOCTYPE canary SYSTEM "' + base_url + '/canary.dtd" [',
' <!ENTITY netmark SYSTEM "' + base_url + '/entity">',
']>',
'<canary>&netmark;</canary>',
]
def write_canaries(folder, base_url):
marker_path = os.path.join(folder, 'marker.txt')
write_text(marker_path, [FILE_MARKER], 'utf-8')
marker_uri = pathlib.Path(marker_path).as_uri()
documents = {
'file': (file_canary(marker_uri, 'UTF-8'), 'utf-8'),
'expansion': (expansion_canary(), 'utf-8'),
'network': (network_canary(base_url), 'utf-8'),
'file-utf16': (file_canary(marker_uri, 'UTF-16'), 'utf-16'),
}
paths = {}
for name in documents:
lines, encoding = documents[name]
paths[name] = os.path.join(folder, name + '-canary.xml')
write_text(paths[name], lines, encoding)
return paths
def build_lab():
folder = tempfile.mkdtemp(prefix='xxe-canary-')
listener = start_listener()
base_url = 'http://127.0.0.1:' + str(listener.server_address[1])
canaries = write_canaries(folder, base_url)
return {'folder': folder, 'listener': listener, 'base_url': base_url, 'canaries': canaries}
def close_lab(lab):
lab['listener'].shutdown()
lab['listener'].server_close()
shutil.rmtree(lab['folder'])
def redact(lab, text):
# Swaps the temporary folder for LAB and the listener's port for PORT,
# so the output reads the same on every run and shows no local path.
folder = lab['folder']
for form in (os.path.realpath(folder), folder):
text = text.replace(form, 'LAB')
return text.replace(lab['base_url'], 'http://127.0.0.1:PORT')
==== File 2 of 5: parsers.py ====
# parsers.py: every parser the lab runs, in three profiles.
# default: the parser as it comes, with no settings changed.
# opened: a documented option that turns entity loading on, so you can
# see that the canaries detect it. Never ship this profile.
# hardened: the settings to copy.
# Each parse function takes a file path and returns the text the
# application would receive, or raises an error.
import os
import platform
import pyexpat
import shutil
import subprocess
import xml.dom.minidom
import xml.etree.ElementTree
import xml.parsers.expat
import xml.sax
import xml.sax.handler
PROFILES = ['default', 'opened', 'hardened']
def python_label(module):
return 'Python ' + platform.python_version() + ' ' + module + ' (' + pyexpat.EXPAT_VERSION + ')'
# HARDENED PYTHON: refuse any document that declares a DTD at all. pyexpat
# calls StartDoctypeDeclHandler when it meets <!DOCTYPE, before any entity
# is declared, so raising there stops the parse.
def refuse_doctype(name, system_id, public_id, has_internal_subset):
raise ValueError('DOCTYPE refused: this endpoint accepts no DTD')
def check_no_doctype(path):
gate = xml.parsers.expat.ParserCreate()
gate.StartDoctypeDeclHandler = refuse_doctype
with open(path, 'rb') as handle:
gate.ParseFile(handle)
# xml.etree.ElementTree
def etree_default(path):
root = xml.etree.ElementTree.parse(path).getroot()
return xml.etree.ElementTree.tostring(root, encoding='unicode')
def etree_hardened(path):
check_no_doctype(path)
return etree_default(path)
# xml.sax: the handler keeps the text and any entity the parser skipped.
class TextCollector(xml.sax.handler.ContentHandler):
def __init__(self):
super().__init__()
self.parts = []
def characters(self, content):
self.parts.append(content)
def skippedEntity(self, name):
self.parts.append('(skipped &' + name + ';)')
def sax_parser(external_entities):
parser = xml.sax.make_parser()
parser.setFeature(xml.sax.handler.feature_external_ges, external_entities)
return parser
def sax_run(path, parser):
collector = TextCollector()
parser.setContentHandler(collector)
parser.parse(path)
return ''.join(collector.parts)
def sax_default(path):
return sax_run(path, xml.sax.make_parser())
def sax_opened(path):
return sax_run(path, sax_parser(True))
def sax_hardened(path):
check_no_doctype(path)
return sax_run(path, sax_parser(False))
# xml.dom.minidom takes an optional SAX parser, so it opens up the same way.
def minidom_default(path):
return xml.dom.minidom.parse(path).documentElement.toxml()
def minidom_opened(path):
return xml.dom.minidom.parse(path, parser=sax_parser(True)).documentElement.toxml()
def minidom_hardened(path):
check_no_doctype(path)
return xml.dom.minidom.parse(path, parser=sax_parser(False)).documentElement.toxml()
# xmllint, from libxml2. Options per profile come from the xmllint
# documentation: --noent substitutes entities, --loaddtd fetches an external
# DTD and --nonet refuses to fetch DTDs or entities over the network.
XMLLINT_OPTIONS = {
'default': [],
'opened': ['--noent', '--loaddtd'],
'hardened': ['--nonet'],
}
def find_xmllints():
candidates = [shutil.which('xmllint')]
candidates += os.environ.get('LAB_XMLLINT', '').split(os.pathsep)
found = []
for candidate in candidates:
if candidate and os.path.exists(candidate) and candidate not in found:
found.append(candidate)
return found
def libxml2_version(binary):
report = subprocess.run([binary, '--version'], capture_output=True, text=True, timeout=30)
number = int(report.stderr.split('using libxml version ')[1].split()[0])
return str(number // 10000) + '.' + str(number // 100 % 100) + '.' + str(number % 100)
class XmllintError(Exception):
pass
def first_message(stderr):
# The first line of xmllint's report that names an error or a warning.
for line in stderr.splitlines():
if 'error' in line or 'warning' in line:
return line.strip()
return stderr.strip()
def xmllint_runner(binary, options):
# Returns the printed document and xmllint's first message, if any.
# A non-zero exit code is a refusal.
def run(path):
result = subprocess.run([binary] + options + [path], capture_output=True, text=True, timeout=30)
if result.returncode != 0:
raise XmllintError(first_message(result.stderr), result.stdout)
return result.stdout, first_message(result.stderr)
return run
def python_parsers():
return [
(python_label('xml.etree.ElementTree'), {'default': etree_default, 'opened': None, 'hardened': etree_hardened}),
(python_label('xml.dom.minidom'), {'default': minidom_default, 'opened': minidom_opened, 'hardened': minidom_hardened}),
(python_label('xml.sax'), {'default': sax_default, 'opened': sax_opened, 'hardened': sax_hardened}),
]
def xmllint_parsers():
parsers = []
for binary in find_xmllints():
runners = {}
for profile in PROFILES:
runners[profile] = xmllint_runner(binary, XMLLINT_OPTIONS[profile])
parsers.append(('xmllint, libxml2 ' + libxml2_version(binary), runners))
return parsers
def all_parsers():
return python_parsers() + xmllint_parsers()
def environment_lines():
lines = ['Python ' + platform.python_version() + ', ' + pyexpat.EXPAT_VERSION]
if platform.mac_ver()[0]:
lines.append('macOS ' + platform.mac_ver()[0])
else:
lines.append(platform.platform())
for binary in find_xmllints():
lines.append('xmllint at ' + binary + ' uses libxml2 ' + libxml2_version(binary))
return lines
==== File 3 of 5: canary_checks.py ====
# canary_checks.py: runs one parse function on one canary and says what
# happened, in the short words the table uses.
from lab_setup import EXPANDED_LENGTH, FILE_MARKER, NETWORK_MARKER, redact
from parsers import XmllintError
REFERENCES = {'file': '▮', 'file-utf16': '▮', 'expansion': '&e4;', 'network': '&netmark;'}
def run_canary(parse, lab, canary):
# Returns what the parser handed back, any error, and every request the
# listener received while this one parse ran.
lab['listener'].requests.clear()
output = ''
error = ''
note = ''
try:
output = parse(lab['canaries'][canary])
except XmllintError as problem:
error = problem.args[0]
output = problem.args[1]
except Exception as problem:
error = type(problem).__name__ + ': ' + str(problem)
if isinstance(output, tuple):
output, note = output
requests = list(lab['listener'].requests)
return {'output': redact(lab, output), 'error': redact(lab, error), 'note': redact(lab, note), 'requests': requests}
def canary_text(output):
# The content of the canary element. xmllint prints the whole document,
# DOCTYPE included, so the DTD's own text is left out of the count.
if '<canary>' in output and '</canary>' in output:
return output.rsplit('<canary>', 1)[1].split('</canary>', 1)[0]
return output
def describe_content(result, canary):
text = canary_text(result['output'])
if FILE_MARKER in text:
return 'READ THE FILE'
if NETWORK_MARKER in text:
return 'USED THE REPLY'
if canary == 'expansion' and len(text) >= EXPANDED_LENGTH:
return 'EXPANDED TO ' + str(len(text)) + ' CHARACTERS'
if result['error']:
return 'REFUSED'
if REFERENCES[canary] in text:
return 'KEPT ' + REFERENCES[canary]
if '(skipped' in text:
return 'SKIPPED ' + REFERENCES[canary]
return 'LEFT IT OUT'
def describe(result, canary):
words = describe_content(result, canary)
if result['requests']:
return 'REQUESTED ' + ' '.join(result['requests']) + ', ' + words
return words
==== File 4 of 5: run_lab.py ====
# run_lab.py: runs every parser on every canary in every profile and prints
# the table, then two smaller checks: whether Expat's expansion limit can be
# made to fire, and what a text filter misses.
import os
import xml.parsers.expat
from canary_checks import canary_text, describe, run_canary
from lab_setup import build_lab, close_lab, redact
from parsers import PROFILES, all_parsers, check_no_doctype, environment_lines, sax_opened
CANARIES = ['file', 'expansion', 'network']
COLUMN_NAMES = {'default': 'DEFAULT', 'opened': 'OPENED UP', 'hardened': 'HARDENED'}
def print_grid(title, columns, rows):
widths = [len(column) for column in columns]
for row in rows:
widths = [max(width, len(cell)) for width, cell in zip(widths, row)]
print(title)
for line in [columns] + rows:
cells = [cell.ljust(width) for cell, width in zip(line, widths)]
print(' '.join(cells).rstrip())
print('')
def print_canaries(lab):
for canary in CANARIES:
print('CANARY: ' + canary)
with open(lab['canaries'][canary], encoding='utf-8') as handle:
print(redact(lab, handle.read()))
def run_table(lab):
rows = []
errors = []
for label, runners in all_parsers():
for canary in CANARIES:
row = [label, canary]
for profile in PROFILES:
if runners[profile] is None:
row.append('NO SUCH OPTION')
continue
result = run_canary(runners[profile], lab, canary)
row.append(describe(result, canary))
message = result['error'] or result['note']
if message:
errors.append(label + ', ' + canary + ', ' + profile + ': ' + message)
rows.append(row)
return rows, errors
def expat_limit_probe(lab, threshold):
parser = xml.parsers.expat.ParserCreate()
text = []
parser.CharacterDataHandler = text.append
if threshold:
parser.SetBillionLaughsAttackProtectionActivationThreshold(threshold)
try:
with open(lab['canaries']['expansion'], 'rb') as handle:
parser.ParseFile(handle)
except xml.parsers.expat.ExpatError as problem:
return 'REFUSED: ' + str(problem)
return 'EXPANDED TO ' + str(len(''.join(text))) + ' CHARACTERS'
def print_limit_probe(lab):
print('EXPANSION LIMIT PROBE (pyexpat, expansion canary)')
print('activation threshold left as it comes: ' + expat_limit_probe(lab, None))
if hasattr(xml.parsers.expat.ParserCreate(), 'SetBillionLaughsAttackProtectionActivationThreshold'):
print('activation threshold set to 16384 bytes: ' + expat_limit_probe(lab, 16384))
else:
print('SetBillionLaughsAttackProtectionActivationThreshold is not available in this Python')
print('')
def filter_allows(path):
# A text filter of the kind the page warns against: refuse any upload
# whose bytes contain <!ENTITY.
with open(path, 'rb') as handle:
return b'<!ENTITY' not in handle.read()
def print_filter_check(lab):
print('TEXT FILTER CHECK (refuse any upload whose bytes contain <!ENTITY)')
for canary in ['file', 'file-utf16']:
path = lab['canaries'][canary]
verdict = 'let it through' if filter_allows(path) else 'refused it'
opened = run_canary(sax_opened, lab, canary)
print(canary + ' canary: the filter ' + verdict + '; xml.sax opened up then saw: ' + canary_text(opened['output']).strip())
try:
check_no_doctype(lab['canaries']['file-utf16'])
print('file-utf16 canary: the DOCTYPE check let it through')
except ValueError as problem:
print('file-utf16 canary: the DOCTYPE check refused it: ' + str(problem))
print('')
def main():
lab = build_lab()
try:
for line in environment_lines():
print(line)
print('')
print_canaries(lab)
rows, errors = run_table(lab)
print_grid('WHAT EACH PARSER DID', ['Parser and version', 'Canary'] + [COLUMN_NAMES[profile] for profile in PROFILES], rows)
print('MESSAGES BEHIND THE TABLE (errors raised, and the first warning xmllint printed)')
for line in errors:
print(line)
print('')
print_limit_probe(lab)
print_filter_check(lab)
finally:
close_lab(lab)
print('Listener stopped. Temporary folder removed: ' + str(not os.path.exists(lab['folder'])))
main()
==== File 5 of 5: test_canaries.py ====
# test_canaries.py: a regression test for the profile LAB_PROFILE names
# (hardened unless set). It fails if any parser in that profile reads the
# marker file or sends a request to the listener.
import os
import unittest
import warnings
from canary_checks import canary_text, run_canary
from lab_setup import FILE_MARKER, build_lab, close_lab
from parsers import all_parsers
PROFILE = os.environ.get('LAB_PROFILE', 'hardened')
def parsers_in_profile():
chosen = []
for label, runners in all_parsers():
if runners[PROFILE] is not None:
chosen.append((label, runners[PROFILE]))
return chosen
class CanaryRegressionTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
# In the opened-up profile, Python's SAX reader leaves the files and
# replies it fetched open and reports each as a ResourceWarning. The
# warnings are left out so the output shows only the results.
warnings.simplefilter('ignore', ResourceWarning)
cls.lab = build_lab()
@classmethod
def tearDownClass(cls):
close_lab(cls.lab)
def test_file_canary_is_not_read(self):
for label, parse in parsers_in_profile():
with self.subTest(parser=label):
result = run_canary(parse, self.lab, 'file')
text = canary_text(result['output']).strip()
self.assertNotIn(FILE_MARKER, text, label + ' read the marker file')
def test_network_canary_sends_no_request(self):
for label, parse in parsers_in_profile():
with self.subTest(parser=label):
result = run_canary(parse, self.lab, 'network')
requested = ', '.join(result['requests'])
self.assertFalse(result['requests'], label + ' requested ' + requested)
if __name__ == '__main__':
unittest.main()
==== RUN IT ====
export LAB_XMLLINT=/opt/homebrew/opt/libxml2/bin/xmllint
python3 run_lab.py
python3 -m unittest -v test_canaries
LAB_PROFILE=default python3 -m unittest -v test_canaries
LAB_PROFILE=opened python3 -m unittest -v test_canaries
The export line is optional. It names a second xmllint to compare with the first one on your PATH; the path shown is where the libxml2 2.15.3 package was on this Mac. Leave it out if you have only one.
==== OUTPUT OF python3 run_lab.py (Python 3.14.7, macOS 27.2.1) ====
Python 3.14.7, expat_2.7.4
macOS 27.2.1
xmllint at /usr/bin/xmllint uses libxml2 2.9.13
xmllint at /opt/homebrew/opt/libxml2/bin/xmllint uses libxml2 2.15.3
CANARY: file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE canary [
<!ENTITY marker SYSTEM "file://LAB/marker.txt">
]>
<canary>▮</canary>
CANARY: expansion
<?xml version="1.0"?>
<!DOCTYPE canary [
<!ENTITY e0 "LAB">
<!ENTITY e1 "&e0;&e0;&e0;&e0;&e0;&e0;&e0;&e0;&e0;&e0;">
<!ENTITY e2 "&e1;&e1;&e1;&e1;&e1;&e1;&e1;&e1;&e1;&e1;">
<!ENTITY e3 "&e2;&e2;&e2;&e2;&e2;&e2;&e2;&e2;&e2;&e2;">
<!ENTITY e4 "&e3;&e3;&e3;&e3;&e3;&e3;&e3;&e3;&e3;&e3;">
]>
<canary>&e4;</canary>
CANARY: network
<?xml version="1.0"?>
<!DOCTYPE canary SYSTEM "http://127.0.0.1:PORT/canary.dtd" [
<!ENTITY netmark SYSTEM "http://127.0.0.1:PORT/entity">
]>
<canary>&netmark;</canary>
WHAT EACH PARSER DID
Parser and version Canary DEFAULT OPENED UP HARDENED
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4) file REFUSED NO SUCH OPTION REFUSED
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4) expansion EXPANDED TO 30000 CHARACTERS NO SUCH OPTION REFUSED
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4) network REFUSED NO SUCH OPTION REFUSED
Python 3.14.7 xml.dom.minidom (expat_2.7.4) file LEFT IT OUT READ THE FILE REFUSED
Python 3.14.7 xml.dom.minidom (expat_2.7.4) expansion EXPANDED TO 30000 CHARACTERS EXPANDED TO 30000 CHARACTERS REFUSED
Python 3.14.7 xml.dom.minidom (expat_2.7.4) network LEFT IT OUT REQUESTED /canary.dtd /entity, USED THE REPLY REFUSED
Python 3.14.7 xml.sax (expat_2.7.4) file LEFT IT OUT READ THE FILE REFUSED
Python 3.14.7 xml.sax (expat_2.7.4) expansion EXPANDED TO 30000 CHARACTERS EXPANDED TO 30000 CHARACTERS REFUSED
Python 3.14.7 xml.sax (expat_2.7.4) network LEFT IT OUT REQUESTED /canary.dtd /entity, USED THE REPLY REFUSED
xmllint, libxml2 2.9.13 file KEPT ▮ READ THE FILE KEPT ▮
xmllint, libxml2 2.9.13 expansion REFUSED REFUSED REFUSED
xmllint, libxml2 2.9.13 network KEPT &netmark; REQUESTED /canary.dtd /entity, USED THE REPLY KEPT &netmark;
xmllint, libxml2 2.15.3 file KEPT ▮ READ THE FILE KEPT ▮
xmllint, libxml2 2.15.3 expansion KEPT &e4; EXPANDED TO 30000 CHARACTERS KEPT &e4;
xmllint, libxml2 2.15.3 network KEPT &netmark; LEFT IT OUT KEPT &netmark;
MESSAGES BEHIND THE TABLE (errors raised, and the first warning xmllint printed)
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4), file, default: ParseError: undefined entity ▮: line 5, column 8
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4), file, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4), expansion, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4), network, default: ParseError: undefined entity &netmark;: line 5, column 8
Python 3.14.7 xml.etree.ElementTree (expat_2.7.4), network, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.dom.minidom (expat_2.7.4), file, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.dom.minidom (expat_2.7.4), expansion, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.dom.minidom (expat_2.7.4), network, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.sax (expat_2.7.4), file, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.sax (expat_2.7.4), expansion, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
Python 3.14.7 xml.sax (expat_2.7.4), network, hardened: ValueError: DOCTYPE refused: this endpoint accepts no DTD
xmllint, libxml2 2.9.13, expansion, default: Entity: line 1: parser error : Detected an entity reference loop
xmllint, libxml2 2.9.13, expansion, opened: Entity: line 1: parser error : Detected an entity reference loop
xmllint, libxml2 2.9.13, expansion, hardened: Entity: line 1: parser error : Detected an entity reference loop
xmllint, libxml2 2.15.3, network, opened: LAB/network-canary.xml:4: I/O warning : failed to load "http://127.0.0.1:PORT/canary.dtd": No such file or directory
EXPANSION LIMIT PROBE (pyexpat, expansion canary)
activation threshold left as it comes: EXPANDED TO 30000 CHARACTERS
activation threshold set to 16384 bytes: REFUSED: limit on input amplification factor (from DTD and entities) breached: line 9, column 8
TEXT FILTER CHECK (refuse any upload whose bytes contain <!ENTITY)
file canary: the filter refused it; xml.sax opened up then saw: LAB-FILE-CANARY
file-utf16 canary: the filter let it through; xml.sax opened up then saw: LAB-FILE-CANARY
file-utf16 canary: the DOCTYPE check refused it: DOCTYPE refused: this endpoint accepts no DTD
Listener stopped. Temporary folder removed: True
==== REGRESSION TEST RESULTS (Python 3.14.7, macOS 27.2.1) ====
The lines below are copied from the test runner's output. Durations change from run to run. Each traceback under a failure is cut, because it names the folder the lab ran in; the AssertionError line after it is kept.
Run: python3 -m unittest -v test_canaries
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) ... ok
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) ... ok
----------------------------------------------------------------------
Ran 2 tests in 0.507s
OK
Exit code: 0
Run: LAB_PROFILE=default python3 -m unittest -v test_canaries
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) ... ok
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) ... ok
----------------------------------------------------------------------
Ran 2 tests in 0.508s
OK
Exit code: 0
Run: LAB_PROFILE=opened python3 -m unittest -v test_canaries
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) ...
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='Python 3.14.7 xml.dom.minidom (expat_2.7.4)') ... FAIL
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='Python 3.14.7 xml.sax (expat_2.7.4)') ... FAIL
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='xmllint, libxml2 2.9.13') ... FAIL
test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='xmllint, libxml2 2.15.3') ... FAIL
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) ...
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='Python 3.14.7 xml.dom.minidom (expat_2.7.4)') ... FAIL
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='Python 3.14.7 xml.sax (expat_2.7.4)') ... FAIL
test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='xmllint, libxml2 2.9.13') ... FAIL
======================================================================
FAIL: test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='Python 3.14.7 xml.dom.minidom (expat_2.7.4)')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: 'LAB-FILE-CANARY' unexpectedly found in 'LAB-FILE-CANARY' : Python 3.14.7 xml.dom.minidom (expat_2.7.4) read the marker file
======================================================================
FAIL: test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='Python 3.14.7 xml.sax (expat_2.7.4)')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: 'LAB-FILE-CANARY' unexpectedly found in 'LAB-FILE-CANARY' : Python 3.14.7 xml.sax (expat_2.7.4) read the marker file
======================================================================
FAIL: test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='xmllint, libxml2 2.9.13')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: 'LAB-FILE-CANARY' unexpectedly found in 'LAB-FILE-CANARY' : xmllint, libxml2 2.9.13 read the marker file
======================================================================
FAIL: test_file_canary_is_not_read (test_canaries.CanaryRegressionTest.test_file_canary_is_not_read) (parser='xmllint, libxml2 2.15.3')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: 'LAB-FILE-CANARY' unexpectedly found in 'LAB-FILE-CANARY' : xmllint, libxml2 2.15.3 read the marker file
======================================================================
FAIL: test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='Python 3.14.7 xml.dom.minidom (expat_2.7.4)')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: ['/canary.dtd', '/entity'] is not false : Python 3.14.7 xml.dom.minidom (expat_2.7.4) requested /canary.dtd, /entity
======================================================================
FAIL: test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='Python 3.14.7 xml.sax (expat_2.7.4)')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: ['/canary.dtd', '/entity'] is not false : Python 3.14.7 xml.sax (expat_2.7.4) requested /canary.dtd, /entity
======================================================================
FAIL: test_network_canary_sends_no_request (test_canaries.CanaryRegressionTest.test_network_canary_sends_no_request) (parser='xmllint, libxml2 2.9.13')
----------------------------------------------------------------------
(traceback cut here: it names the folder the lab ran in)
AssertionError: ['/canary.dtd', '/entity'] is not false : xmllint, libxml2 2.9.13 requested /canary.dtd, /entity
----------------------------------------------------------------------
Ran 2 tests in 0.547s
FAILED (failures=7)
Exit code: 1
==== READING THE TABLE ====
READ THE FILE: the application received LAB-FILE-CANARY, so the parser resolved the external entity and read marker.txt. On a server, the same entity could name a different file.
REQUESTED followed by paths: the listener received those requests while that one parse ran, so the parser reached the network. /canary.dtd is the external DTD and /entity is the external entity. USED THE REPLY means the listener's word reached the application too.
EXPANDED TO 30000 CHARACTERS: every internal entity was expanded, so DTDs are processed and no limit applied at this size. Read the probe below the table before deciding whether a limit exists at all.
KEPT followed by a reference: xmllint printed the entity reference as it was, without substituting it.
LEFT IT OUT and SKIPPED: the parser did not load the entity and the application received nothing in its place.
REFUSED: the parse raised an error. The section headed MESSAGES BEHIND THE TABLE gives each one.
NO SUCH OPTION: the lab has no opened-up profile for this parser.
A cell can be safe for the wrong reason. On libxml2 2.15.3, the opened-up profile made no network request because that build has no HTTP client, which is why its first warning reads "No such file or directory". The same options on 2.9.13 fetched both URLs. Record the setting, not the luck of the build.
==== USING THE CANARIES ON YOUR OWN PARSER ====
1. Fill in a Part 1 block for each place your application parses XML, from the documentation for the exact version you run.
2. For a Python parser, write a function that takes a file path and returns what your code hands the rest of the application, add it to python_parsers() in parsers.py under the profile it belongs to, and run run_lab.py and the test.
3. For a parser in another language, start the lab from a Python prompt in the lab folder: from lab_setup import build_lab, close_lab, then lab = build_lab(). The canary files are listed in lab['canaries'] and the listener keeps running. Point your parser, with its production settings, at each file, read lab['listener'].requests after each one, and call close_lab(lab) when you finish.
4. Copy the test's two assertions into your own test suite, against your real parse function: the file canary's marker never reaches the application, and the listener records no request. A later change that switches entity loading back on then fails a build instead of reaching production.
5. Write the date and the results into the worksheet, and run the canaries again whenever the parser, the library that wraps it or the runtime underneath is upgraded, because the defaults in Part 2 have changed between versions before.What XXE is
XML external entity injection, shortened to XXE, is a flaw in how an application reads XML rather than in what it does with the data afterwards.
OWASP's XML External Entity Prevention Cheat Sheet says it occurs when an XML processor resolves an external entity from untrusted input, and that this can expose local files, cause server-side request forgery (SSRF), or exhaust resources. MITRE catalogues the weakness as CWE-611, Improper Restriction of XML External Entity Reference: the product processes an XML document that can contain XML entities with URIs that resolve to documents outside of the intended sphere of control, causing the product to embed incorrect documents into its output.
In the OWASP Top 10:2025, CWE-611 is one of the weaknesses mapped to A02:2025 Security Misconfiguration. MITRE's entry for CWE-611 lists its memberships, among them A02:2025 Security Misconfiguration, A05:2021 Security Misconfiguration and OWASP Top Ten 2017 Category A4, XML External Entities (XXE), a 2017 category named for the flaw itself.
ASVS 5.0 requirement 1.5.1, a Level 1 requirement in section V1.5 Safe Deserialization, asks that the application configures XML parsers to use a restrictive configuration and that unsafe features such as resolving external entities are disabled to prevent XXE attacks.
An XXE vulnerability needs two things: a parser that will follow an external reference, and a document someone else wrote reaching it. This guide covers the first, the XML parser: what an external entity is, why a parser's defaults matter, and how to prove what yours does. What a server can reach once it fetches an address someone else chose is the subject of the SSRF guide in this library.
What an XML entity is, and why it can fetch content from elsewhere
An entity is a named piece of content that a document can refer to instead of spelling it out.
The W3C's XML 1.0 recommendation (Fifth Edition) says in section 4 that an XML document may consist of one or many storage units called entities, that the contents of a parsed entity are its replacement text, considered an integral part of the document, and that parsed entities are invoked by name using entity references.
Section 4.1 says an entity reference refers to the content of a named entity, and that references to parsed general entities use an ampersand and a semicolon as delimiters around the name. Where the reference sits, the parser puts the replacement text.
Entities are declared in the document type definition, or DTD. Section 2.8 says the document type declaration contains or points to markup declarations that provide a grammar for a class of documents, and that it can point to an external subset, contain the declarations directly in an internal subset, or do both.
An internal entity carries its content in the declaration itself (section 4.2.1). An external entity does not: section 4.2.2 gives it a system identifier that is meant to be converted to a URI reference and dereferenced to obtain the entity's replacement text.
That is the whole mechanism. A document an outsider wrote can declare an entity whose system identifier is a file: URI or an http: URL, refer to it once, and leave the fetching to your parser. The recommendation leaves room for parsers to differ.
Section 4.4.3 says a processor that is not validating the document may, but need not, include an external entity's replacement text, and must tell the application when it recognised an entity but did not read it. Section 5.1 says validating processors must read and process the entire DTD and all external parsed entities referenced in the document.
Whether a given parser fetches is a property of that parser and its settings, which is why the rest of this guide is about settings.
Internal entities matter as well. Section 5.1 also says non-validating processors must process the declarations they read in the internal DTD subset, up to the first reference to a parameter entity they do not read, and use them to include the replacement text of internal entities. An internal entity whose content refers to other internal entities is how the expansion attacks below are built.
What an attacker gains from an external entity
CWE-611 lists three groups of consequences, and the OWASP XML Security Cheat Sheet covers the same ground.
Each one is the parser acting on the attacker's behalf, with the server's own permissions and from the server's place on the network.
- Reading a file the server can read. CWE-611 says that if the attacker is able to include a crafted DTD and a default entity resolver is enabled, the attacker may be able to access arbitrary files on the system, and gives file:///etc/passwd, the password file on Unix-based systems, as one of its examples. The content is fed back into the application, which may echo it, for example in an error message. What that exposure costs depends on the data, which the sensitive data exposure guide in this library covers.
- Making the server call an address. CWE-611 says a crafted DTD using URIs with schemes such as http:// can force the application to make outgoing requests to servers the attacker cannot reach directly, which can be used to bypass firewall restrictions, hide the source of attacks such as port scanning, or otherwise leverage the server's trust relationship with other systems. It notes that SSRF (CWE-918) and XXE are closely related, though XXE can also be performed client-side or where the software is not acting directly as a server.
- Exhausting memory or CPU. CWE-611 adds that a URI can point to a large file or a device that always returns data. Internal entities alone are enough for the classic attack: MITRE catalogues CWE-776, Improper Restriction of Recursive Entity References in DTDs, whose alternate terms include XML entity expansion, the billion laughs attack and XML bomb. Its example nests entities until the last one expands to 2^32 characters, or 4 GB. The XML Security Cheat Sheet says these expansion attacks need no external entity or network access, so blocking external entities does not stop them.
When the attacker cannot see the result
A parser can resolve an entity without the result ever appearing in a response. The XML Security Cheat Sheet says that when the resolved entity is not reflected in the response or in an error message, the attacker can still confirm the attack or retrieve content out of band, through parameter entities and a remote DTD.
This guide names that technique and goes no further. The canary lab proves the same thing with a listener on your own machine: a request arriving at the listener is the evidence, whether or not anything comes back in the response.
Where XML turns up in an application that speaks JSON
An application can be JSON from end to end in its own code and still parse XML in several places, including inside the libraries it calls.
OWASP's Top 10:2025 entry for injection, writing about injection flaws in general rather than XXE, says their detection is best achieved by a combination of source code review and automated testing, including fuzzing, of all parameters, headers, URL, cookies, JSON, SOAP and XML data inputs. XML is on that list, which is reason enough to look for it in an API built on JSON. Look for these:
- SVG images. MDN describes SVG as an XML-based markup language for two-dimensional vector graphics, and CWE-611's observed examples include XXE during SVG image conversion. The file upload security guide in this library covers what an upload feature accepts and keeps; the question here is what happens when a server-side library parses the file.
- Office documents. Microsoft's Open XML SDK documentation describes Open XML as an open standard for word-processing documents, presentations and spreadsheets, says an Open XML file is stored in a ZIP archive, and says the document parts in the package are created as XML markup. A server that opens one of these files to read its contents is parsing XML. CWE-611's observed examples include XXE in an office document product.
- Single sign-on. OWASP's SAML Security Cheat Sheet describes SAML as an open standard for exchanging authorisation and authentication information. Among its recommendations for validating signatures, it lists always performing schema validation on the XML document before using it for any security-related purpose, and never allowing automatic download of schemas from third-party locations.
- SOAP and XML-RPC. CWE-827, Improper Control of Document Type Definition, notes that the SOAP specification prohibits SOAP messages from containing DTDs. A SOAP endpoint can therefore refuse every DOCTYPE without turning away a message the specification allows. CWE-611's observed examples include XXE via an XML-RPC request.
- Imports, feeds and configuration. List every import, feed and configuration file your server reads in an XML format, such as spreadsheet and accounting exports, sitemaps, RSS or Atom feeds and settings files, even when the format feels internal.
- Routes written for JSON. Whether a framework hands an XML body to an XML parser depends on how it picks a parser for a content type, so check it: send the file canary with an XML content type to each route on a staging copy and record what happens. The API security guide in this library covers keeping an inventory of every route.
Why "we do not use XML" needs checking
The answer to whether an application parses XML lives in its dependency tree, not in the team's memory.
The WSTG test for XML injection, WSTG-INPV-07, has two objectives: identify XML injection points, and assess the types of exploits that can be attained and their severities. Its source code review section lists Java APIs that may be vulnerable to XXE if they are not configured properly, among them DocumentBuilder, SAXParserFactory, XMLInputFactory, TransformerFactory and SchemaFactory, and libxml2 keywords that may apply to C code, such as xmlReadFile and xmlCtxtUseOptions.
It asks reviewers to check whether the DOCTYPE, external DTDs and external parameter entities are set as forbidden.
XML is easy to miss for three reasons. A library can parse it on your behalf: a document converter, an image tool, a single sign-on library or an SDK. One library can sit on top of another, so the setting that matters may belong to the parser underneath: Python's documentation says its built-in XML parsers rely on Expat, and PHP's documentation gives DOM, XMLWriter and XMLReader as examples of libxml extensions.
And the parser underneath can come from outside your lock file: Python's documentation says whether it uses its bundled Expat or a system-wide one depends on how the interpreter was configured, and tells you to check pyexpat.EXPAT_VERSION.
The worksheet in the asset on this page starts from that inventory: one block for every place XML is parsed, including the ones a library handles, with the parser and the version underneath it. Where a Node.js application parses XML through a package, that package's own documentation is the place to look for its defaults, and the canaries test it the same way.
XXE prevention is a parser setting, not an input filter
OWASP's XXE cheat sheet starts its general guidance with the parser: disable DTDs whenever possible, and reject DOCTYPE declarations if the parser supports it.
If the application needs DTDs, disable external entity resolution and external DTD loading, and limit entity expansion. Keep XInclude disabled unless it is explicitly required, because it can load resources independently of DTDs, and restrict external access during schema validation and style sheet processing as well as parsing. It also says to treat an unsupported security setting as a configuration failure, rather than continue processing untrusted XML with partial hardening.
The other sources give the same advice about the parser. The XML Security Cheat Sheet says disabling DTD processing for untrusted XML blocks the expansion, file, network and out-of-band attacks it describes, and that where a DTD is genuinely required, external entities and external DTD loading should be off and entity expansion and entity size limits enforced.
CWE-611's mitigation is that many XML parsers and validators can be configured to disable external entity expansion. The first of CWE-776's two mitigations is, if possible, to prohibit DTDs or use a parser that limits the expansion of recursive DTD entities; its second is to scan for recursive entity declarations before parsing and not continue parsing potentially explosive content.
Filtering the input instead looks simpler, and is weaker:
- A DOCTYPE does not need an entity declaration to make a parser fetch. The XML Security Cheat Sheet says an external DTD reference in the DOCTYPE makes the parser fetch a URL even without any entity declaration. A filter that looks only for entity declarations would let that document through.
- The bytes need not look like the text you are filtering for. Section 4.3.3 of the XML recommendation says all XML processors must be able to read entities in both UTF-8 and UTF-16. In the lab, a filter that refused any upload whose bytes contained an entity declaration refused the UTF-8 file canary and let a UTF-16 copy through, and xml.sax with external entities switched on then read the marker file from that copy.
- A filter has to recognise every form a construct can take, in every encoding. A parser setting is applied by the component that reads the document as it will actually be processed.
What the hardened profile does
The lab's hardened Python profile refuses any document that declares a DTD, before the real parse, using the pyexpat hook that the Python documentation says is called when Expat begins parsing the document type declaration. It refused the UTF-16 copy that the text filter let through. Where an application needs DTDs, the reference table in the asset gives each parser's documented settings for the other half of the advice: external entities off, external DTD loading off, expansion limited.
A parser left more permissive than the application needs is the kind of finding the security misconfiguration guide in this library covers.
XML parser security: what the defaults are, and for which version
Defaults decide whether code that never mentions entities is exposed, and they have changed from one version to the next.
The reference table in the asset gives each parser's documented behaviour for the four worksheet questions. These changes show why the version belongs in the worksheet:
- Python. The xml.sax documentation says that since Python 3.7.1 the SAX parser no longer processes general external entities by default; before, it created network connections to fetch remote files or loaded local files for DTDs and entities. The Python 3.14 documentation says Expat itself does not access local files or create network connections by default, and that Expat versions lower than 2.7.2 may be vulnerable to the billion laughs, quadratic blowup and large tokens vulnerabilities, or to disproportional use of dynamic memory. Python 3.14.6 added pyexpat methods to tune the billion laughs protection.
- libxml2. Its NEWS file lists "Do not fetch external parsed entities" under 2.9.0, a parser option XML_PARSE_NO_XXE under 2.13.0, HTTP support disabled by default at build time from 2.13.0 (in 2.13 the legacy mode still enabled it; from 2.14.0 it no longer does), and removal of the built-in HTTP client in 2.15.0. The current xmllint documentation says --nonet has no effect with libxml2 2.15 or later.
- Java. The processing-limits table in the JAXP Security Guide for JDK 27 gives jdk.xml.entityExpansionLimit a default of 2500, where the JDK 21 guide's table gives 64000; the JDK 27 guide's Limiting Entity Expansion section still says 64,000, so check the value your own runtime uses. The JDK 27 guide also says that although the JDK turns FEATURE_SECURE_PROCESSING on by default for SAX, DOM, validation and transformation factories, external connections such as external entity resolution are not disabled by default, and the feature has to be set explicitly to restrict them.
- .NET. Microsoft's .NET 10 API reference says XmlReaderSettings.DtdProcessing defaults to Prohibit, and that the XmlResolver setting has defaulted to null starting with .NET Framework 4.5.2, where before it was a new XmlUrlResolver with no credentials. OWASP's cheat sheet says XmlDocument, XmlTextReader and XPathNavigator are vulnerable to external entity attacks and billion laughs below .NET Framework 4.5.2, and protected from that version on.
- PHP. The PHP documentation says that as of libxml 2.9.0 entity substitution is disabled by default, that libxml_disable_entity_loader() is deprecated as of PHP 8.0.0, and that the LIBXML_NO_XXE constant needs libxml 2.13.0 or later and PHP 8.4.0. It warns that enabling LIBXML_NOENT or LIBXML_DTDVALID may facilitate XXE attacks, and that enabling LIBXML_DTDLOAD will enable fetching of external entities.
A good default is not a finished configuration
Every default above can be overridden by one line of your code, or by an option a library passes for you, and a runtime pinned in an old container image keeps its old default. That is why the worksheet asks for the setting that decides each answer and for the canary results with a date, not only the version number.
Walking through the DTD canary lab
The lab in the asset is an illustration written for this page, not a client's code.
It is Python using only the standard library, plus xmllint where the system has it. It creates one temporary folder, writes a marker file into it, starts a listener on 127.0.0.1 that records every request, and writes three canary documents: one with an external entity pointing at the marker file, one with four levels of internal entities that expand to 30,000 characters, and one whose external DTD and external entity both point at the listener.
It never names a real system file and never contacts another machine.
When it finishes it stops the listener and deletes the folder, and its output says LAB for the folder and PORT for the listener's port.
It ran on macOS 27.2.1 against five parsers: Python 3.14.7's xml.etree.ElementTree, xml.dom.minidom and xml.sax, all on Expat 2.7.4, the xmllint at /usr/bin on that Mac, which reported libxml2 2.9.13, and a second xmllint from a libxml2 2.15.3 package. Each parser ran every canary three times: as it comes, opened up with a documented option that turns entity loading on, and hardened.
Your results depend on your own versions, so run it and read your own table. A parser in another language uses the same three canary files and the worksheet.
What the table showed
With no settings changed, none of the five parsers read the marker file or sent a request to the listener. ElementTree refused both external-entity canaries with ParseError: undefined entity. minidom and xml.sax returned the canary element empty. Both xmllint builds printed the entity references as they were.
The Python 3.12 documentation's table says minidom returns the unexpanded entity verbatim; on Python 3.14.7 the lab got an empty element, which is the reason to run the canary rather than rely on a table.
Defaults differed on the expansion canary. All three Python parsers expanded it to 30,000 characters. The xmllint built on libxml2 2.9.13 refused it with "Detected an entity reference loop" even with no options, while the 2.15.3 build left the reference in place by default and expanded all 30,000 characters in the opened-up profile, with --noent set. One document, two versions of one library, two different results.
The opened-up column proves the canaries work. With feature_external_ges switched on, minidom and xml.sax read the marker file and requested both /canary.dtd and /entity from the listener. xmllint with --noent and --loaddtd read the marker file on both builds.
The 2.9.13 build also requested both URLs, while 2.15.3 made no request and warned that it failed to load the DTD's URL; libxml2's NEWS file records the built-in HTTP client as removed in 2.15.0.
In the hardened column, every Python parser refused all three canaries at the DOCTYPE, and xmllint with --nonet and without --noent or --loaddtd read no file and sent no request.
Is entity expansion limited?
Expansion to 30,000 characters does not show that there is no limit, only that none applied at that size. The Python documentation says parser objects usually activate Expat's billion laughs protection at 8 MiB of output, with a maximum amplification factor of 100, though the actual defaults depend on the Expat library.
The lab's probe lowers the activation threshold to 16,384 bytes with SetBillionLaughsAttackProtectionActivationThreshold(), and the same canary was then refused with "limit on input amplification factor (from DTD and entities) breached".
That threshold makes the limit visible at the canary's size and is not a value to copy: the documentation says thresholds below 4 MiB are known to break DITA 1.3 payloads and are not recommended.
The regression test
test_canaries.py runs two tests over every parser in the profile that LAB_PROFILE names: the file canary's marker never reaches the application, and the listener records no request. The hardened profile passed both and the run exited with code 0.
The default profile also passed on these versions. The opened-up profile failed seven subtests, four for the file canary and three for the network canary, and exited with code 1. Each failure names the parser, such as "xmllint, libxml2 2.9.13 requested /canary.dtd, /entity".
Keep the hardened test in your own suite, pointed at your real parse function, so a change that switches entity loading back on fails a build.
XXE testing in code and on a running build
In code, start from the parsers rather than the inputs.
Find every place an XML parser is created, including inside libraries, using the WSTG's list of Java APIs and libxml2 functions as a starting point for those languages, and for each one note the settings it is created with. CWE-611 says automated static analysis can find some instances of the weakness, and that typically this is done by building a model of data flow and control flow, then searching for potentially vulnerable patterns that connect sources (origins of input) with sinks; it rates the method's effectiveness as High.
A parser created inside a library you call is still a sink to trace, and the secure code review guide in this library covers that work across a whole code base.
Against a running build, use the lab's method: harmless canaries, your own listener, and only an application you own or are authorised in writing to test, on a test or staging copy where you can. Send the file canary pointing at a marker file you placed on that server, or the network canary pointing at a listener you control, and look for the marker in the response or a request at the listener.
The WSTG's examples include requests for well-known system files and for /dev/random, and it notes the /dev/random test could crash the web server on a UNIX system if the parser attempts to substitute the entity with that file's contents.
Proving the flaw needs neither. For expansion, a few levels show whether the parser expands entities at all and whether a limit applies at that size.
Whether a limit exists further up is a question for the parser's documentation and settings, as the lab's probe shows, not for a bigger payload.
Then turn each result into a regression test like test_canaries.py, and record the result and the date in the worksheet.
Where an outside test fits
The lab checks the parsers you know about.
A review looks for the ones you do not. Clever Ops reviews code for applications such as Next.js, React and Node with read-only access to the repository, and a secure code review follows the paths in scope, looking at untrusted input along the way. Code findings are confirmed against a running build where the scope allows, and the report marks any that rest on the code alone.
In a Clever Ops web application and API penetration test, file uploads are in scope, and read-only code access to named areas can be added to confirm how a control is enforced. Each finding is confirmed with the least intrusive proof available, and destructive actions are off by default for real people's accounts and for records that existed before the test.
If Clever Ops built or hosts your application, the work is a security review rather than an independent test, and the report says who built it and who hosts it.
Frequently asked questions
XML external entity. MITRE lists XXE as an alternate term for CWE-611, an acronym for XML eXternal Entities. It is the flaw where an XML parser follows a document's DTD to content stored somewhere else, such as a local file or a URL, and hands it to the application.
It sits inside a broader category. In the OWASP Top 10:2025, CWE-611 is one of the weaknesses mapped to A02:2025 Security Misconfiguration. MITRE's entry for CWE-611 also lists OWASP Top Ten 2017 Category A4, XML External Entities (XXE), among its memberships, a 2017 category named for the flaw itself.
No. The billion laughs attack uses internal entities only. The OWASP XML Security Cheat Sheet says expansion attacks need no external entity or network access, so blocking external entities does not stop them. Disable DTD processing for untrusted XML, which it says blocks both kinds, or enforce entity expansion and entity size limits where a DTD is genuinely required.
It can if anything behind it parses XML: an SVG or office document upload, a SAML login, an import, or a route whose framework accepts an XML body as well as JSON. List every parser in the dependency tree with the worksheet, and send the canaries to each route on a staging copy rather than assume.
Not on its own. A filter has to recognise every form a declaration can take. The XML Security Cheat Sheet says an external DTD reference makes a parser fetch a URL even without an entity declaration, and the XML recommendation requires processors to read UTF-16 as well as UTF-8. In the lab, a byte filter for entity declarations let a UTF-16 copy of the file canary through. Set the parser to refuse DTDs, or at least external entities and external DTDs, and test the setting with the canaries.
It depends on the parser and its version, and defaults have changed. Python's SAX parser has not processed general external entities by default since Python 3.7.1. PHP's documentation says entity substitution is disabled by default as of libxml 2.9.0. Microsoft's .NET 10 API reference gives XmlReaderSettings.DtdProcessing a default of Prohibit. Java's JAXP guide for JDK 27 says external connections are not disabled by default even though secure processing is on for SAX, DOM, validation and transformation factories. A default holds only until code or a library changes it, so record the setting and run the canaries.
Use canaries that stay on systems you control: an entity pointing at a marker file you placed yourself, a listener of your own for the network check, and a few levels of expansion rather than a real bomb. Test only applications you own or are authorised in writing to test, and turn each result into a regression test. The lab on this page does all of that on one computer.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.