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
+  could 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,24 @@
     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 count follows
+# the specification's flat rule: the root is one value, each array and map
+# charges its declared children, and a pointer costs nothing beyond the value
+# it resolves to, which its container already charged. 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 an explicit,
+# call-local depth limit (see ``decode``).
+_MAX_VALUES = 1 << 16
+_MAX_DEPTH = 512
+_TOO_MANY_VALUES = (
+    "The MaxMind DB file's data section exceeds the maximum number of values"
+)
+_TOO_DEEP = "The MaxMind DB file's data section exceeds the maximum depth"
 
 
 class Decoder:
@@ -42,35 +59,72 @@ 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)
+        budget[1] += 1
+        if budget[1] > _MAX_DEPTH:
+            raise InvalidDatabaseError(_TOO_DEEP)
         array = []
         for _ in range(size):
-            (value, offset) = self.decode(offset)
+            (value, offset) = self._decode(offset, budget)
             array.append(value)
+        budget[1] -= 1
         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 +135,33 @@ 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)
+        budget[1] += 1
+        if budget[1] > _MAX_DEPTH:
+            raise InvalidDatabaseError(_TOO_DEEP)
         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
+        budget[1] -= 1
         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 +181,32 @@ def _decode_pointer(self, size: int, offset: int) -> tuple[Record, int]:
 
         if self._pointer_test:
             return pointer, new_offset
-        (value, _) = self.decode(pointer)
+
+        # The value at the pointer's position was charged by its containing
+        # array or map, so the target costs nothing more. Only the depth changes.
+        budget[1] += 1
+        if budget[1] > _MAX_DEPTH:
+            raise InvalidDatabaseError(_TOO_DEEP)
+        (value, _) = self._decode(pointer, budget)
+        budget[1] -= 1
         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 +233,20 @@ 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`` carries the remaining value count and current
+        # nested decode depth so both are shared across the recursion. It is
+        # call-local, which keeps the decoder safe for concurrent reads. The
+        # root value is charged here; containers charge their children. The
+        # explicit depth limit is independent of Python's process-wide recursion
+        # limit; RecursionError remains a fallback on interpreters whose stack
+        # limit is reached first.
+        try:
+            return self._decode(offset, [_MAX_VALUES - 1, 0])
+        except RecursionError as ex:
+            raise InvalidDatabaseError(_TOO_DEEP) 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 +263,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/data

@@ -1,14 +1,20 @@
 from __future__ import annotations
 
 import mmap
+import sys
 import unittest
 from typing import TYPE_CHECKING, Any, ClassVar
 
 from maxminddb.decoder import Decoder
+from maxminddb.errors import InvalidDatabaseError
 
 if TYPE_CHECKING:
     from _typeshed import SizedBuffer
 
+# Each structural level uses about two Python frames. This lets the 513-level
+# cases reach the decoder's explicit limit with ample test-harness headroom.
+_DEPTH_TEST_RECURSION_LIMIT = 2_000
+
 
 class TestDecoder(unittest.TestCase):
     def test_arrays(self) -> None:
@@ -232,3 +238,89 @@ 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)
+
+    @classmethod
+    def _scalar_pointer_array(cls, pointer_count: int) -> bytes:
+        # A uint16 leaf at offset 0 and, at offset 1, an array of pointers to
+        # it. 0x1e: extended type with size code 30; 0x04: array.
+        header = bytes([0xA0, 0x1E, 0x04]) + (pointer_count - 285).to_bytes(2, "big")
+        return header + cls._pointer(0) * pointer_count
+
+    def test_value_limit_follows_the_flat_rule(self) -> None:
+        # The specification charges the root as one value and each pointer as
+        # the value it resolves to, not as a separate value. An array of 65,535
+        # pointers to a scalar is therefore 65,536 values, exactly the limit,
+        # and decodes. One more pointer exceeds it.
+        (decoded, _) = Decoder(
+            self._scalar_pointer_array(65_535), pointer_base=0
+        ).decode(1)
+        self.assertEqual(decoded, [0] * 65_535)
+
+        with self.assertRaisesRegex(
+            InvalidDatabaseError,
+            "^The MaxMind DB file's data section exceeds the maximum number of values$",
+        ):
+            Decoder(self._scalar_pointer_array(65_536), pointer_base=0).decode(1)
+
+    def test_cyclic_pointer_raises(self) -> None:
+        # A pointer to itself must hit the decoder's own depth limit even when
+        # Python's process-wide recursion limit is much higher.
+        cyclic = bytes([0x20, 0x00])  # pointer (base 0) to offset 0, itself
+        old_recursion_limit = sys.getrecursionlimit()
+        try:
+            sys.setrecursionlimit(_DEPTH_TEST_RECURSION_LIMIT)
+            with self.assertRaisesRegex(
+                InvalidDatabaseError,
+                "^The MaxMind DB file's data section exceeds the maximum depth$",
+            ):
+                Decoder(cyclic, pointer_base=0).decode(0)
+        finally:
+            sys.setrecursionlimit(old_recursion_limit)
+
+    def test_container_depth_is_bounded_independently_of_recursion_limit(self) -> None:
+        # Each prefix is an array with one element. Raising Python's global
+        # recursion limit proves that the decoder's call-local limit is what
+        # accepts 512 containers and rejects the 513th.
+        at_limit = bytes([0x01, 0x04]) * 512 + bytes([0xA0])
+        over_limit = bytes([0x01, 0x04]) * 513 + bytes([0xA0])
+        old_recursion_limit = sys.getrecursionlimit()
+        try:
+            sys.setrecursionlimit(_DEPTH_TEST_RECURSION_LIMIT)
+            Decoder(at_limit, pointer_base=0).decode(0)
+            with self.assertRaisesRegex(
+                InvalidDatabaseError,
+                "^The MaxMind DB file's data section exceeds the maximum depth$",
+            ):
+                Decoder(over_limit, pointer_base=0).decode(0)
+        finally:
+            sys.setrecursionlimit(old_recursion_limit)
+
+    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)