Bound decoder work to prevent a pointer fan-out denial of service

A crafted data section could nest pointers to shared targets so that
decoding one record cost exponential time and memory from a small file
(GHSA-hj94-g986-h9r7).

The decoder now limits the number of values it decodes for a single record
and rejects a database that exceeds the limit with an InvalidDatabaseError.
The limit is 65,536, far above the few hundred values the largest real
records decode. Pointer cycles and over-deep data are rejected the same way
rather than exhausting the stack. The limit state is call-local, so the
decoder stays safe for concurrent reads. This matches the reader resource
limits now recommended by the MaxMind DB specification.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: oschwald

HISTORY.rst

@@ -3,6 +3,16 @@
 History
 -------
 
+3.2.0
++++++
+
+* Fixed a denial-of-service issue in the pure Python decoder. A crafted database
+  could nest data-section pointers to shared targets so that decoding one record
+  cost exponential time and memory from a small file. The decoder now limits the
+  number of values it decodes for a single record and rejects a database that
+  exceeds it, along with pointer cycles and over-deep data, with an
+  ``InvalidDatabaseError``. See GHSA-hj94-g986-h9r7.
+
 3.1.1 (2026-03-05)
 ++++++++++++++++++
 

maxminddb/decoder.py

@@ -18,7 +18,19 @@
     from maxminddb.file import FileBuffer
     from maxminddb.types import Record
 
-    DecoderFunc = Callable[["Decoder", int, int], tuple[Record, int]]
+    DecoderFunc = Callable[["Decoder", int, int, list[int]], tuple[Record, int]]
+
+
+# Per-lookup limit on the number of values decoded, recommended by the MaxMind
+# DB specification. It stops a pointer fan-out, where nested pointers to shared
+# targets would otherwise cost 2**depth decode operations. The largest real
+# records decode a few hundred values, so the limit leaves a wide margin.
+# Pointer cycles and over-deep data are caught separately by Python's own
+# recursion limit (see ``decode``).
+_MAX_VALUES = 1 << 16
+_TOO_MANY_VALUES = (
+    "The MaxMind DB file's data section exceeds the maximum number of values"
+)
 
 
 class Decoder:
@@ -42,35 +54,68 @@ def __init__(
         self._buffer = database_buffer
         self._pointer_base = pointer_base
 
-    def _decode_array(self, size: int, offset: int) -> tuple[list[Record], int]:
+    def _decode_array(
+        self,
+        size: int,
+        offset: int,
+        budget: list[int],
+    ) -> tuple[list[Record], int]:
+        budget[0] -= size
+        if budget[0] < 0:
+            raise InvalidDatabaseError(_TOO_MANY_VALUES)
         array = []
         for _ in range(size):
-            (value, offset) = self.decode(offset)
+            (value, offset) = self._decode(offset, budget)
             array.append(value)
         return array, offset
 
-    def _decode_boolean(self, size: int, offset: int) -> tuple[bool, int]:
+    def _decode_boolean(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[bool, int]:
         return size != 0, offset
 
-    def _decode_bytes(self, size: int, offset: int) -> tuple[bytes, int]:
+    def _decode_bytes(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[bytes, int]:
         new_offset = offset + size
         return self._buffer[offset:new_offset], new_offset
 
-    def _decode_double(self, size: int, offset: int) -> tuple[float, int]:
+    def _decode_double(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[float, int]:
         self._verify_size(size, 8)
         new_offset = offset + size
         packed_bytes = self._buffer[offset:new_offset]
         (value,) = struct.unpack(b"!d", packed_bytes)
         return value, new_offset
 
-    def _decode_float(self, size: int, offset: int) -> tuple[float, int]:
+    def _decode_float(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[float, int]:
         self._verify_size(size, 4)
         new_offset = offset + size
         packed_bytes = self._buffer[offset:new_offset]
         (value,) = struct.unpack(b"!f", packed_bytes)
         return value, new_offset
 
-    def _decode_int32(self, size: int, offset: int) -> tuple[int, int]:
+    def _decode_int32(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[int, int]:
         if size == 0:
             return 0, offset
         new_offset = offset + size
@@ -81,15 +126,29 @@ def _decode_int32(self, size: int, offset: int) -> tuple[int, int]:
         (value,) = struct.unpack(b"!i", packed_bytes)
         return value, new_offset
 
-    def _decode_map(self, size: int, offset: int) -> tuple[dict[str, Record], int]:
+    def _decode_map(
+        self,
+        size: int,
+        offset: int,
+        budget: list[int],
+    ) -> tuple[dict[str, Record], int]:
+        # A map entry decodes a key and a value, so it costs two values.
+        budget[0] -= size * 2
+        if budget[0] < 0:
+            raise InvalidDatabaseError(_TOO_MANY_VALUES)
         container: dict[str, Record] = {}
         for _ in range(size):
-            (key, offset) = self.decode(offset)
-            (value, offset) = self.decode(offset)
+            (key, offset) = self._decode(offset, budget)
+            (value, offset) = self._decode(offset, budget)
             container[cast("str", key)] = value
         return container, offset
 
-    def _decode_pointer(self, size: int, offset: int) -> tuple[Record, int]:
+    def _decode_pointer(
+        self,
+        size: int,
+        offset: int,
+        budget: list[int],
+    ) -> tuple[Record, int]:
         pointer_size = (size >> 3) + 1
 
         buf = self._buffer[offset : offset + pointer_size]
@@ -109,15 +168,26 @@ def _decode_pointer(self, size: int, offset: int) -> tuple[Record, int]:
 
         if self._pointer_test:
             return pointer, new_offset
-        (value, _) = self.decode(pointer)
+
+        (value, _) = self._decode(pointer, budget)
         return value, new_offset
 
-    def _decode_uint(self, size: int, offset: int) -> tuple[int, int]:
+    def _decode_uint(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[int, int]:
         new_offset = offset + size
         uint_bytes = self._buffer[offset:new_offset]
         return int.from_bytes(uint_bytes, "big"), new_offset
 
-    def _decode_utf8_string(self, size: int, offset: int) -> tuple[str, int]:
+    def _decode_utf8_string(
+        self,
+        size: int,
+        offset: int,
+        _budget: list[int],
+    ) -> tuple[str, int]:
         new_offset = offset + size
         return self._buffer[offset:new_offset].decode("utf-8"), new_offset
 
@@ -144,6 +214,19 @@ def decode(self, offset: int) -> tuple[Record, int]:
             offset: the location of the data structure to decode
 
         """
+        # Bound the work per lookup so a crafted database cannot exhaust CPU or
+        # memory. ``budget`` is a single-element list so the running count is
+        # shared across the recursion. It is call-local, which keeps the
+        # decoder safe for concurrent reads. There is no separate depth limit: a
+        # pointer cycle or over-deep data exhausts Python's own recursion limit,
+        # which is converted into an InvalidDatabaseError.
+        try:
+            return self._decode(offset, [_MAX_VALUES])
+        except RecursionError as ex:
+            msg = "The MaxMind DB file's data section exceeds the maximum depth"
+            raise InvalidDatabaseError(msg) from ex
+
+    def _decode(self, offset: int, budget: list[int]) -> tuple[Record, int]:
         new_offset = offset + 1
         ctrl_byte = self._buffer[offset]
         type_num = ctrl_byte >> 5
@@ -160,7 +243,7 @@ def decode(self, offset: int) -> tuple[Record, int]:
             ) from ex
 
         (size, new_offset) = self._size_from_ctrl_byte(ctrl_byte, new_offset, type_num)
-        return decoder(self, size, new_offset)
+        return decoder(self, size, new_offset, budget)
 
     def _read_extended(self, offset: int) -> tuple[int, int]:
         next_byte = self._buffer[offset]

tests/decoder_test.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING, Any, ClassVar
 
 from maxminddb.decoder import Decoder
+from maxminddb.errors import InvalidDatabaseError
 
 if TYPE_CHECKING:
     from _typeshed import SizedBuffer
@@ -232,3 +233,40 @@ def test_real_pointers(self) -> None:
             self.assertEqual(({"long_key2": "long_value2"}, 59), decoder.decode(57))
 
             mm.close()
+
+    @staticmethod
+    def _pointer(target: int) -> bytes:
+        # One-byte-payload pointer (type 1, pointer_size 1) with base 0.
+        return bytes([(1 << 5) | ((target >> 8) & 0x7), target & 0xFF])
+
+    def test_pointer_fan_out_is_bounded(self) -> None:
+        # A data section of nested arrays, each holding two pointers to the
+        # node below, would cost 2**depth decode operations. The decoder bounds
+        # the number of values it decodes per lookup and rejects the database.
+        depth = 100
+        buf = bytearray([0xA0])  # leaf: uint16 with value 0
+        prev = 0
+        for _ in range(depth):
+            offset = len(buf)
+            buf += bytes([0x02, 0x04]) + self._pointer(prev) + self._pointer(prev)
+            prev = offset
+
+        with self.assertRaises(InvalidDatabaseError):
+            Decoder(bytes(buf), pointer_base=0).decode(prev)
+
+    def test_cyclic_pointer_raises(self) -> None:
+        # A pointer to itself must raise a catchable InvalidDatabaseError
+        # rather than recursing until the interpreter's stack limit.
+        cyclic = bytes([0x20, 0x00])  # pointer (base 0) to offset 0, itself
+        with self.assertRaises(InvalidDatabaseError):
+            Decoder(cyclic, pointer_base=0).decode(0)
+
+    def test_oversized_map_is_bounded(self) -> None:
+        # A map entry decodes a key and a value, so a map of N entries costs
+        # 2N values. A map that declares 32,769 entries reaches 65,538 values,
+        # just past the 65,536 limit, and is rejected before any entry is read.
+        # 0xfe: map with size code 30, then the two size bytes for
+        # 32,769 - 285 = 32,484 (0x7ee4).
+        oversized_map = bytes([0xFE, 0x7E, 0xE4])
+        with self.assertRaises(InvalidDatabaseError):
+            Decoder(oversized_map, pointer_base=0).decode(0)