== Why is this an issue?

include::../description.adoc[]

=== Noncompliant code example

For https://docs.oracle.com/javase/9/docs/api/javax/xml/parsers/DocumentBuilderFactory.html[DocumentBuilder], https://docs.oracle.com/javase/9/docs/api/javax/xml/parsers/SAXParserFactory.html[SAXParser], https://docs.oracle.com/javase/9/docs/api/javax/xml/stream/XMLInputFactory.html[XMLInput], https://docs.oracle.com/javase/9/docs/api/javax/xml/transform/TransformerFactory.html[Transformer] and https://docs.oracle.com/javase/9/docs/api/javax/xml/validation/SchemaFactory.html[Schema] JAPX factories:

[source,java]
----
factory.setXIncludeAware(true); // Noncompliant
// or
factory.setFeature("http://apache.org/xml/features/xinclude", true); // Noncompliant
----

For https://dom4j.github.io/[Dom4j] library:

[source,java]
----
SAXReader xmlReader = new SAXReader();
xmlReader.setFeature("http://apache.org/xml/features/xinclude", true); // Noncompliant
----

For http://www.jdom.org/[Jdom2] library:

[source,java]
----
SAXBuilder builder = new SAXBuilder();
builder.setFeature("http://apache.org/xml/features/xinclude", true); // Noncompliant
----

=== Compliant solution

Xinclude is disabled by default and can be explicitely disabled like below.  

For https://docs.oracle.com/javase/9/docs/api/javax/xml/parsers/DocumentBuilderFactory.html[DocumentBuilder], https://docs.oracle.com/javase/9/docs/api/javax/xml/parsers/SAXParserFactory.html[SAXParser], https://docs.oracle.com/javase/9/docs/api/javax/xml/stream/XMLInputFactory.html[XMLInput], https://docs.oracle.com/javase/9/docs/api/javax/xml/transform/TransformerFactory.html[Transformer] and https://docs.oracle.com/javase/9/docs/api/javax/xml/validation/SchemaFactory.html[Schema] JAPX factories:

[source,java]
----
factory.setXIncludeAware(false);
// or
factory.setFeature("http://apache.org/xml/features/xinclude", false);
----

For https://dom4j.github.io/[Dom4j] library:

[source,java]
----
SAXReader xmlReader = new SAXReader(); 
xmlReader.setFeature("http://apache.org/xml/features/xinclude", false);
----

For http://www.jdom.org/[Jdom2] library:

[source,java]
----
SAXBuilder builder = new SAXBuilder();
builder.setFeature("http://apache.org/xml/features/xinclude", false);
----

=== Exceptions

This rule does not raise issues when Xinclude is enabled with a custom ``++EntityResolver++``:

For DocumentBuilderFactory:

[source,java]
----
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setXIncludeAware(true);
// ...
DocumentBuilder builder = factory.newDocumentBuilder();
builder.setEntityResolver((publicId, systemId) -> new MySafeEntityResolver(publicId, systemId));
----

For SAXBuilder:

[source,java]
----
SAXBuilder builder = new SAXBuilder();
builder.setFeature("http://apache.org/xml/features/xinclude", true);
builder.setEntityResolver((publicId, systemId) -> new MySafeEntityResolver(publicId, systemId));
----

For SAXReader:

[source,java]
----
SAXReader xmlReader = new SAXReader();
xmlReader.setFeature("http://apache.org/xml/features/xinclude", true);
xmlReader.setEntityResolver((publicId, systemId) -> new MySafeEntityResolver(publicId, systemId));
----

For XMLInputFactory:

[source,java]
----
XMLInputFactory factory = XMLInputFactory.newInstance();
factory.setProperty("http://apache.org/xml/features/xinclude", true);
factory.setXMLResolver(new MySafeEntityResolver());
----

== Resources

* https://docs.oracle.com/en/java/javase/13/security/java-api-xml-processing-jaxp-security-guide.html#GUID-8CD65EF5-D113-4D5C-A564-B875C8625FAC[Oracle Java Documentation] - XML External Entity Injection Attack
* https://owasp.org/www-project-top-ten/2017/A4_2017-XML_External_Entities_(XXE)[OWASP Top 10 2017 Category A4] - XML External Entities (XXE)
* https://cheatsheetseries.owasp.org/cheatsheets/XML_External_Entity_Prevention_Cheat_Sheet.html#java[OWASP XXE Prevention Cheat Sheet]
* https://cwe.mitre.org/data/definitions/611[MITRE, CWE-611] - Information Exposure Through XML External Entity Reference
* https://cwe.mitre.org/data/definitions/827[MITRE, CWE-827] - Improper Control of Document Type Definition

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Disable the inclusion of files in XML processing.



'''
== Comments And Links
(visible only on this page)

=== on 25 Jan 2022, 10:34:00 Quentin Jaquier wrote:
Quick fixes (for Java): even if it is technically possible to provide a fix that would result in compliant code, it does not sound wise to set properties blindly, as it can have side effects. Fixing the issue requires a careful and good understanding of the overall context of the code.

endif::env-github,rspecator-view[]