XML Entity Recursion Limits and Safe Configuration

The XML entity recursion limit is a security threshold designed to prevent Denial of Service (DoS) attacks caused by exponential entity expansion, commonly known as the “Billion Laughs” attack. This article explores how recursive XML entities operate, the risks they pose to server infrastructure, and the specific configurations modern application servers and XML parsers employ to safely mitigate these vulnerabilities.

Understanding XML Entity Recursion and the Billion Laughs Attack

XML allows authors to define custom entities using Document Type Definitions (DTDs). These entities act as variables or macros that can be referenced within the XML document. While useful for reducing redundancy, this feature introduces severe vulnerabilities when entities are defined recursively or nested within one another.

In an entity expansion attack, an attacker defines an initial entity and nests subsequent entities that repeatedly reference the previous ones:

<?xml version="1.0"?>
<!DOCTYPE lolz [
 <!ENTITY lol "lol">
 <!ENTITY lol2 "&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;">
 <!ENTITY lol3 "&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;">
 ...
 <!ENTITY lol9 "&lol8;&lol8;&lol8;&lol8;&lol8;&lol8;&lol8;&lol8;&lol8;&lol8;">
]>
<lolz>&lol9;</lolz>

When an unhardened parser processes &lol9;, it recursively expands the references. A payload of less than one kilobyte can expand into gigabytes of data in memory, exhausting CPU and RAM, and crashing the host process.

The Role of the Recursion and Expansion Limit

The entity recursion limit is a boundary enforced by the XML parser that caps the number of times an entity can reference other entities or the total number of entity expansions allowed during parsing. When this threshold is exceeded, the parser immediately terminates processing and throws a parsing exception, preserving system resources.

Safe Configuration Strategies for Modern Application Servers

Modern application servers protect against recursive entity attacks by utilizing a combination of complete DTD disabling, secure processing features, and explicit entity limits.

1. Completely Disabling DTDs (Best Practice)

The most effective mitigation is to disable DTD processing entirely if the application does not require it.

2. Enabling Feature Secure Processing (FSP)

If DTDs are required, parsers should be configured with secure processing flags. In Java, XMLConstants.FEATURE_SECURE_PROCESSING instructs the parser to enforce reasonable defaults for entity limits and restricts external resource loading.

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);

3. Setting Explicit Expansion Limits via System Properties

Application runtimes allow administrators to enforce global limits via JVM arguments or system properties to safeguard legacy applications without modifying source code.

These properties can be passed directly at server startup:

-Djdk.xml.entityExpansionLimit=1000 -Djdk.xml.totalEntitySizeLimit=100000

4. Web Application Firewall (WAF) and Gateway Inspection

Enterprise deployments often enforce entity restrictions at the API gateway or WAF layer. Gateways inspect incoming Content-Type: application/xml payloads to reject requests containing <!DOCTYPE declarations before the payload reaches backend application servers.