Update: XML_External_Entity_Prevention_Cheat_Sheet

Improve Java XXE guidance: make the cheat sheet more actionable

Problem

The recent rewrite of the Java section significantly improves the technical depth and consistency of the guidance, but it also makes the cheat sheet harder to use for developers looking for a practical answer to a specific configuration problem.

The previous version was more straightforward: for a given API, the reader could quickly find the relevant configuration and a code example showing how to apply it.

In the current version, the reader often needs to understand several concepts and navigate between different sections before they can determine how to securely configure a specific API.

For example, when using TransformerFactory, it is not immediately obvious how to obtain and configure the required secure XMLReader. The reader may need to combine information from multiple sections to construct the final solution.

This creates a gap between the technical explanation and the practical goal of a cheat sheet.

What the guidance should provide

For each relevant Java XML API, the reader should ideally be able to answer three questions directly:

1. What is the security risk?
2. How do I mitigate it?
3. What does the secure configuration look like in code?

The main recommendation should be easy to find first, while advanced details and edge cases can follow afterwards.

Suggested structure

Consider restructuring the Java section into two layers:

1. Quick / actionable guidance

For each commonly used API, provide:

• when the guidance applies;
• the recommended secure configuration;
• a minimal copy/paste-ready code example.

For example:

• DocumentBuilderFactory
• SAXParserFactory
• XMLInputFactory
• TransformerFactory
• SchemaFactory
• Validator
• XMLReader
• JAXB and other relevant APIs

2. Detailed explanation and edge cases

Keep the deeper discussion about:

• JAXP implementation differences;
• resolver behavior;
• ACCESS_EXTERNAL_*;
• FEATURE_SECURE_PROCESSING;
• XSLT/XSD imports and includes;
• catalogs and allowlisting;
• fail-closed behavior;
• implementation-specific caveats.

This would preserve the technical depth of the new version while making the cheat sheet significantly easier to consume.

Example of the current usability issue

Some explanations are technically accurate but difficult to interpret without already understanding the underlying XML/JAXP model.

For example:

“References carried by your own style sheet or schema — xsl:import, xsl:include, xs:import, xs:include and the XSLT document() function — are yours, and splitting one across files is ordinary practice. These are the ones to restrict rather than close.”

As a reader, it is not immediately clear:

• what specific threat this is addressing;
• when this situation applies;
• what the recommended configuration is;
• what the corresponding secure code should look like.

The same information could be presented more directly by first explaining the risk and recommended mitigation, followed by an example.

Goal

The goal is not to reduce the technical depth of the Java section, but to make the primary path through the documentation more obvious:

identify the API → understand the risk → apply the recommended fix → see the secure code

Advanced explanations can then provide the necessary context for readers who need it.