Skip to content

Prevent XXE in Java XML parsers

To disable external entities in Java and prevent XXE, configure each XML factory before you parse: the single strongest setting is the Xerces feature disallow-doctype-decl, which rejects any document containing a DOCTYPE and so eliminates both file-read and billion-laughs attacks in one line.

Java is the ecosystem most affected by XXE because its default XML factories resolve external entities. The fix is always the same shape: get the factory, set the security features, then create the parser. The preferred control is to reject DOCTYPE entirely; where a legitimate DTD is required, disable external general entities, external parameter entities and external DTD loading instead.

Secure parser configuration

DocumentBuilderFactory (DOM)

java
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
// Primary defence: refuse any document with a DOCTYPE.
dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
// If a DTD must be allowed, disable entities instead of the line above:
dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
dbf.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
dbf.setXIncludeAware(false);
dbf.setExpandEntityReferences(false);
DocumentBuilder db = dbf.newDocumentBuilder();

disallow-doctype-decl alone is sufficient and also stops entity-expansion DoS.

SAXParserFactory (SAX)

java
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
spf.setFeature("http://xml.org/sax/features/external-general-entities", false);
spf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
spf.setXIncludeAware(false);
SAXParser parser = spf.newSAXParser();

XMLInputFactory (StAX)

java
XMLInputFactory xif = XMLInputFactory.newFactory();
xif.setProperty(XMLInputFactory.SUPPORT_DTD, false);
xif.setProperty("javax.xml.stream.isSupportingExternalEntities", false);

SUPPORT_DTD=false is the StAX equivalent of disallow-doctype-decl.

TransformerFactory / XSLT

java
TransformerFactory tf = TransformerFactory.newInstance();
tf.setAttribute(XMLConstants.ACCESS_EXTERNAL_DTD, "");
tf.setAttribute(XMLConstants.ACCESS_EXTERNAL_STYLESHEET, "");

SchemaFactory / Validator

java
SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
sf.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, "");
sf.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, "");

DOM4J SAXReader

java
SAXReader reader = new SAXReader();
reader.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
reader.setFeature("http://xml.org/sax/features/external-general-entities", false);
reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);

JAXB Unmarshaller

java
// JAXB does not read XML itself — feed it a hardened XMLStreamReader/SAXSource.
XMLInputFactory xif = XMLInputFactory.newFactory();
xif.setProperty(XMLInputFactory.SUPPORT_DTD, false);
xif.setProperty("javax.xml.stream.isSupportingExternalEntities", false);
XMLStreamReader xsr = xif.createXMLStreamReader(inputStream);
Object o = unmarshaller.unmarshal(xsr);

Never unmarshal directly from an InputStream/File — that uses a default, unsafe parser.

Common pitfalls that re-introduce XXE

  • Setting features on the parser after creation instead of on the factory — too late.
  • Disabling only external-general-entities, which leaves blind/OOB (parameter-entity) XXE open.
  • Unmarshalling JAXB straight from an InputStream, bypassing your hardened factory.
  • Catching the feature-not-supported exception and silently continuing with defaults.

Verifying the fix

Send a classic file-read payload and a blind OOB payload to every XML entry point and confirm both fail. A hardened factory with disallow-doctype-decl should throw a "DOCTYPE is disallowed" parse exception; verify that exception is caught and not echoed to the client.

Techniques these settings prevent

References