gh-139313: Improve docs on XML security (GH-139460)

Clarify that:
- it takes parsing for an attack
- that some doors are closed by default
- only Expat version 2.7.2 has all the fixes
- use of the bundle depends on configuration

diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index f533850c0ca679be39235ab569b01a11e8793ecc..2f5db81955c235d607b931664afa02b995be4fe8 100644 (file)
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -634,6 +634,15 @@ otherwise stated.
 
 .. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)
 
+   .. warning::
+
+      Implementing a handler that accesses local files and/or the network
+      may create a vulnerability to
+      `external entity attacks <https://en.wikipedia.org/wiki/XML_external_entity_attack>`_
+      if :class:`xmlparser` is used with user-provided XML content.
+      Please reflect on your `threat model <https://en.wikipedia.org/wiki/Threat_model>`_
+      before implementing this handler.
+
    Called for references to external entities.  *base* is the current base, as set
    by a previous call to :meth:`SetBase`.  The public and system identifiers,
    *systemId* and *publicId*, are strings if given; if the public identifier is not

diff --git a/Doc/library/xml.rst b/Doc/library/xml.rst
index 3f74557347440515f387b910544f0ff21f1090b1..acd8d399fe32fcd37140cf4d75a4706e2d5b7f74 100644 (file)
--- a/Doc/library/xml.rst
+++ b/Doc/library/xml.rst
@@ -53,11 +53,22 @@ XML security
 
 An attacker can abuse XML features to carry out denial of service attacks,
 access local files, generate network connections to other machines, or
-circumvent firewalls.
-
-Expat versions lower than 2.6.0 may be vulnerable to "billion laughs",
-"quadratic blowup" and "large tokens". Python may be vulnerable if it uses such
-older versions of Expat as a system-provided library.
+circumvent firewalls when attacker-controlled XML is being parsed,
+in Python or elsewhere.
+
+The built-in XML parsers of Python rely on the library `libexpat`_, commonly
+called Expat, for parsing XML.
+
+By default, Expat itself does not access local files or create network
+connections.
+
+Expat versions lower than 2.7.2 may be vulnerable to the "billion laughs",
+"quadratic blowup" and "large tokens" vulnerabilities, or to disproportional
+use of dynamic memory.
+Python bundles a copy of Expat, and whether Python uses the bundled or a
+system-wide Expat, depends on how the Python interpreter
+:option:`has been configured <--with-system-expat>` in your environment.
+Python may be vulnerable if it uses such older versions of Expat.
 Check :const:`!pyexpat.EXPAT_VERSION`.
 
 :mod:`xmlrpc` is **vulnerable** to the "decompression bomb" attack.
@@ -90,5 +101,6 @@ large tokens
   be used to cause denial of service in the application parsing XML.
   The issue is known as :cve:`2023-52425`.
 
+.. _libexpat: https://github.com/libexpat/libexpat
 .. _Billion Laughs: https://en.wikipedia.org/wiki/Billion_laughs
 .. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb