feat: Add Parser insecurely_allow_entities param

Author: Rogdham

CHANGELOG.md

@@ -17,6 +17,7 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 - Add documentation to explain how to import the library
 - Warnings due to wrong usage are now using `UserWarning` instead of `RuntimeWarning`
+- Undocumented parameter `insecurely_allow_entities` to `Parser`
 
 ### :house: Internal
 

src/bigxml/parser.py

@@ -1,4 +1,5 @@
 from typing import TYPE_CHECKING, Callable, Iterator, Optional, Tuple, Union
+import warnings
 
 from defusedxml.ElementTree import iterparse
 
@@ -73,12 +74,24 @@ def create_node(elem: "Element", iteration: int) -> Union[XMLElement, XMLText]:
 
 
 class Parser(HandleMgr):
-    def __init__(self, *streams: Streamable) -> None:
+    def __init__(
+        self,
+        *streams: Streamable,
+        insecurely_allow_entities: bool = False,
+    ) -> None:
+        if insecurely_allow_entities:
+            warnings.warn(
+                "Using 'insecurely_allow_entities' makes your code vulnerable to some XML attacks."
+                " Are you sure you trust where the input streams are coming from?",
+                UserWarning,
+                stacklevel=1,
+            )
         iterator = IterWithRollback(
             rewrite_exceptions(
                 iterparse(
                     StreamChain(*streams),
                     ("start", "end"),
+                    forbid_entities=not insecurely_allow_entities,
                 )
             )
         )

stubs/defusedxml/ElementTree.pyi

@@ -1,6 +1,27 @@
-# note: only used items are defined here
+# ruff: noqa: FBT001
+# note: only used items are defined here, with used typing
 
-from xml.etree.ElementTree import Element, ParseError, iterparse
+import sys
+from typing import Iterator, Optional, Sequence, TypeVar
+from xml.etree.ElementTree import Element, ParseError
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    from typing_extensions import Protocol
+else:  # pragma: no cover
+    from typing import Protocol
+
+_T_co = TypeVar("_T_co", covariant=True)
+
+class _SupportsRead(Protocol[_T_co]):
+    def read(self, size: Optional[int] = None) -> _T_co: ...
+
+def iterparse(
+    source: _SupportsRead[bytes],
+    events: Sequence[str] | None = None,
+    forbid_dtd: bool = False,
+    forbid_entities: bool = True,
+    forbid_external: bool = False,
+) -> Iterator[tuple[str, Element]]: ...
 
 class DefusedXmlException(ValueError): ...  # noqa: N818
 

tests/integration/test_security.py

@@ -101,3 +101,16 @@ def test_external_entities(xml: bytes, msg: str) -> None:
         Parser(xml).return_from(handler_get_text)
     assert str(exc_info.value) == msg
     assert exc_info.value.security
+
+
+def test_insecurely_allow_entities() -> None:
+    xml = (
+        b"<!DOCTYPE foobar [\n"
+        b'    <!ENTITY Omega "&#937;">\n'
+        b"]>\n"
+        b"<root>&Omega;</root>\n"
+    )
+    with pytest.warns(UserWarning):
+        parser = Parser(xml, insecurely_allow_entities=True)
+    value = parser.return_from(handler_get_text)
+    assert value == "Ω"

tests/unit/test_parser.py

@@ -80,6 +80,7 @@ def test_root_level(
 elem_b_node = elem("bar", parents=(root_node,), attributes={"abc": "def"})
 text_h_node = XMLText("Hello", (root_node,))
 text_w_node = XMLText("World", (root_node,))
+text_pi_node = XMLText("π", (root_node,))
 
 # to make sure that text are not in buffer, we generate huge texts
 BIG_TEXT_LEN = 1_000_000
@@ -186,3 +187,21 @@ def root_handler(
     assert list(parser.iter_from(root_handler)) == [
         (f"handler-yield-{i}", node) for i, node in enumerate(nodes)
     ]
+
+
+def test_insecurely_allow_entities(
+    # pylint: disable=redefined-outer-name
+    handler: HANDLER_TYPE,
+) -> None:
+    xml = b'<!DOCTYPE money [<!ENTITY pi "&#960;">]><root>&pi;</root>'
+
+    @xml_handle_element("root")
+    def root_handler(
+        node: XMLElement,
+    ) -> Iterator[Tuple[str, Union[XMLElement, XMLText]]]:
+        yield from node.iter_from(handler)
+
+    with pytest.warns(UserWarning):
+        parser = Parser(xml, insecurely_allow_entities=True)
+
+    assert list(parser.iter_from(root_handler)) == [("handler-yield-0", text_pi_node)]