Resolving XML External Entity (XXE) Vulnerabilities in Java DocumentBuilderFactory

The Problem: Uncontrolled Entity Expansion

When a Java application parses XML from an untrusted source using default settings, it may attempt to resolve external entities defined within the Document Type Definition (DTD). This behavior allows an attacker to use the SYSTEM identifier to force the server to read local files (Local File Inclusion) or make requests to internal network resources (Server-Side Request Forgery), potentially leaking sensitive data like /etc/passwd or cloud metadata services.

Diagnostic Matrix

If your application processes XML, use this table to identify if your current configuration is vulnerable.

Symptom	Likely Cause	Risk Level
Application returns contents of local files when a SYSTEM entity is provided.	External General Entities are enabled.	Critical
Application hangs or crashes when parsing a deeply nested entity.	DTD processing is enabled (Billion Laughs attack).	High
Internal network services are triggered by XML uploads.	External Parameter Entities are enabled.	High

Step-by-Step Security Audit

Follow these checks to determine where your DocumentBuilderFactory configuration is failing. These checks assume the use of JAXP (Java API for XML Processing) version 1.5 or higher.

1. Check for DTD Disablement: Verify if the feature http://apache.org/xml/features/disallow-doctype-decl is set to true. If this is enabled, the parser will throw an exception if a ` declaration is present, providing the strongest protection.
2. Check General Entity Resolution: If DTDs must be allowed for internal reasons, check if http://xml.org/sax/features/external-general-entities is set to false. This prevents the resolution of entities used within the XML body.
3. Check Parameter Entity Resolution: Check if http://xml.org/sax/features/external-parameter-entities is set to false. This prevents entities used only within the DTD itself from being resolved.

Implementation Fixes

The fix must be applied to the DocumentBuilderFactory instance before the newDocumentBuilder() method is called. Applying these settings to the builder itself is often too late.

Example: Secure Factory Configuration

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;

public class XmlParserService {
    public void parseSecurely(byte[] xmlData) throws ParserConfigurationException {
        DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();

        // 1. Completely disable DTDs to prevent XXE and Denial of Service
        // This is the recommended setting for most modern applications
        dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);

        // 2. If DTDs cannot be disabled, disable external entities specifically
        dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
        dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
        
        // 3. Disable external DTDs
        dbf.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);

        // Now create the builder from the secured factory
        dbf.newDocumentBuilder().parse(new java.io.ByteArrayInputStream(xmlData));
    }
}

Verification and Limitations

To verify the fix, attempt to parse a payload containing a SYSTEM entity pointing to a non-existent local file. A secure parser should either throw a SAXParseException (if DTDs are disallowed) or ignore the entity and return an empty string/null for that element.

Limitations:

• Compatibility: Disabling disallow-doctype-decl will break XML files that rely on internal DTDs for entity shortcuts (e.g., &companyName;). In these cases, use the general/parameter entity flags instead.
• Provider Variance: Some legacy JAXP providers may ignore these feature strings. Always verify the result with a test payload.

Rollback and Escalation

If the security features cause legitimate XML files to fail parsing, roll back the setFeature calls one by one, starting with disallow-doctype-decl, to find the minimum required restriction.

Escalate to a dependency update or security wrapper if:

• The XML parsing is handled by a third-party library that does not expose the DocumentBuilderFactory.
• The library uses a proprietary parser that does not support standard JAXP feature flags.