Bound decoder string and bytes payload to stop amplification

A crafted database could aim many data-section pointers at one large
string or bytes value. The value count stayed low, but the pure Python
decoder copied each target, so a small file could materialize gigabytes.

Add a call-local 2 MiB budget for the total string and bytes payload a
single decode produces. Each value is charged its length wherever it is
decoded, so re-decoding a shared target through another pointer recharges
the budget, which stops the amplification. Also reject a variable-length
integer whose declared size exceeds its type before the bytes are copied.
The metadata read when a database is opened uses the same decoder, so the
limit covers it too.

Bump the test-data submodule to the fixtures for these cases.

See GHSA-hj94-g986-h9r7.

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

Author: oschwald

HISTORY.rst

@@ -6,12 +6,19 @@ 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.
+* Fixed two denial-of-service issues 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, or point many
+  times at one large string or bytes value so that a record with few values
+  materialized far more data than the file holds. The decoder now applies the
+  limits recommended by the MaxMind DB specification to each record it decodes
+  and to the metadata read when a database is opened. A database that exceeds
+  a limit raises ``InvalidDatabaseError``. The limits are:
+
+  * 65,536 decoded values.
+  * 2 MiB of string and bytes payload. An oversized variable-length integer is
+    also rejected.
+  * 512 levels of nesting, which also stops pointer cycles.
 
 3.1.1 (2026-03-05)
 ++++++++++++++++++

maxminddb/decoder.py

@@ -32,10 +32,25 @@
 # call-local depth limit (see ``decode``).
 _MAX_VALUES = 1 << 16
 _MAX_DEPTH = 512
+# Per-lookup limit on the total string and bytes payload materialized, matching
+# libmaxminddb and the Go reader. It stops a payload amplification, where many
+# pointers to one large value would otherwise materialize N * size bytes from a
+# small file. Each string or bytes value is charged its length wherever it is
+# decoded, so re-decoding a shared target through another pointer recharges.
+_MAX_PAYLOAD_BYTES = 1 << 21
+# The widest fixed-width integer the format defines is the 16-byte uint128; a
+# declared size past that is malformed and could copy attacker-controlled bytes.
+_MAX_UINT_BYTES = 16
+_MAX_INT32_BYTES = 4
 _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"
+_TOO_LARGE = "The MaxMind DB file's data section exceeds the maximum payload size"
+_BAD_DATA = (
+    "The MaxMind DB file's data section contains bad data "
+    "(unknown data type or corrupt data)"
+)
 
 
 class Decoder:
@@ -90,8 +105,13 @@ def _decode_bytes(
         self,
         size: int,
         offset: int,
-        _budget: list[int],
+        budget: list[int],
     ) -> tuple[bytes, int]:
+        # Charge the payload before copying so a crafted size cannot force a
+        # large allocation, and so pointers reusing one target recharge.
+        budget[2] -= size
+        if budget[2] < 0:
+            raise InvalidDatabaseError(_TOO_LARGE)
         new_offset = offset + size
         return self._buffer[offset:new_offset], new_offset
 
@@ -125,6 +145,8 @@ def _decode_int32(
         offset: int,
         _budget: list[int],
     ) -> tuple[int, int]:
+        if size > _MAX_INT32_BYTES:
+            raise InvalidDatabaseError(_BAD_DATA)
         if size == 0:
             return 0, offset
         new_offset = offset + size
@@ -197,6 +219,10 @@ def _decode_uint(
         offset: int,
         _budget: list[int],
     ) -> tuple[int, int]:
+        # Reject a declared size past the widest defined unsigned integer before
+        # copying, so a crafted size cannot force a large allocation.
+        if size > _MAX_UINT_BYTES:
+            raise InvalidDatabaseError(_BAD_DATA)
         new_offset = offset + size
         uint_bytes = self._buffer[offset:new_offset]
         return int.from_bytes(uint_bytes, "big"), new_offset
@@ -205,8 +231,13 @@ def _decode_utf8_string(
         self,
         size: int,
         offset: int,
-        _budget: list[int],
+        budget: list[int],
     ) -> tuple[str, int]:
+        # Charge the payload before copying so a crafted size cannot force a
+        # large allocation, and so pointers reusing one target recharge.
+        budget[2] -= size
+        if budget[2] < 0:
+            raise InvalidDatabaseError(_TOO_LARGE)
         new_offset = offset + size
         return self._buffer[offset:new_offset].decode("utf-8"), new_offset
 
@@ -234,15 +265,15 @@ def decode(self, offset: int) -> tuple[Record, int]:
 
         """
         # 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.
+        # memory. ``budget`` carries the remaining value count, the current
+        # nested decode depth, and the remaining string and bytes payload, so
+        # all three 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])
+            return self._decode(offset, [_MAX_VALUES - 1, 0, _MAX_PAYLOAD_BYTES])
         except RecursionError as ex:
             raise InvalidDatabaseError(_TOO_DEEP) from ex
 
@@ -281,13 +312,7 @@ def _read_extended(self, offset: int) -> tuple[int, int]:
     @staticmethod
     def _verify_size(expected: int, actual: int) -> None:
         if expected != actual:
-            msg = (
-                "The MaxMind DB file's data section contains bad data "
-                "(unknown data type or corrupt data)"
-            )
-            raise InvalidDatabaseError(
-                msg,
-            )
+            raise InvalidDatabaseError(_BAD_DATA)
 
     def _size_from_ctrl_byte(
         self,

tests/decoder_test.py

@@ -3,8 +3,9 @@
 import mmap
 import sys
 import unittest
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
+from maxminddb import MODE_MEMORY, open_database
 from maxminddb.decoder import Decoder
 from maxminddb.errors import InvalidDatabaseError
 
@@ -15,6 +16,12 @@
 # cases reach the decoder's explicit limit with ample test-harness headroom.
 _DEPTH_TEST_RECURSION_LIMIT = 2_000
 
+# Directory holding the shared MaxMind DB test fixtures.
+_TEST_DATA_DIR = "tests/data/test-data"
+_PAYLOAD_TOO_LARGE = (
+    "^The MaxMind DB file's data section exceeds the maximum payload size$"
+)
+
 
 class TestDecoder(unittest.TestCase):
     def test_arrays(self) -> None:
@@ -324,3 +331,121 @@ def test_oversized_map_is_bounded(self) -> None:
         oversized_map = bytes([0xFE, 0x7E, 0xE4])
         with self.assertRaises(InvalidDatabaseError):
             Decoder(oversized_map, pointer_base=0).decode(0)
+
+    def test_oversized_string_payload_is_bounded(self) -> None:
+        # A single string that declares one byte more than the 2 MiB payload
+        # limit is rejected before its bytes are copied. This also covers the
+        # wrapped-scalar variant: the charge is applied wherever a string is
+        # decoded, not only for a direct pointer target. 0x5f: string with size
+        # code 31; 0x1efee4: 2,097,153 - 65,821, one byte over 2 MiB.
+        oversized_string = bytes([0x5F, 0x1E, 0xFE, 0xE4])
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            Decoder(oversized_string, pointer_base=0).decode(0)
+
+    def test_oversized_bytes_payload_is_bounded(self) -> None:
+        # As above for the bytes type. 0x9f: bytes with size code 31.
+        oversized_bytes = bytes([0x9F, 0x1E, 0xFE, 0xE4])
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            Decoder(oversized_bytes, pointer_base=0).decode(0)
+
+    def test_oversized_uint_is_bounded(self) -> None:
+        # A uint128 that declares 17 bytes exceeds the 16-byte format maximum
+        # and is rejected before the declared bytes are copied. 0x11: extended
+        # type, size 17; 0x03: extended type number 10 (uint128).
+        oversized_uint = bytes([0x11, 0x03])
+        with self.assertRaises(InvalidDatabaseError):
+            Decoder(oversized_uint, pointer_base=0).decode(0)
+
+    def test_oversized_int32_is_bounded(self) -> None:
+        # An int32 that declares 5 bytes exceeds its 4-byte maximum and is
+        # rejected before the declared bytes are copied. 0x05: extended type,
+        # size 5; 0x01: extended type number 8 (int32).
+        oversized_int32 = bytes([0x05, 0x01])
+        with self.assertRaises(InvalidDatabaseError):
+            Decoder(oversized_int32, pointer_base=0).decode(0)
+
+
+class TestDecoderResourceLimits(unittest.TestCase):
+    """Fixture-backed checks for the pure-Python decoder resource limits."""
+
+    @staticmethod
+    def _lookup(filename: str, ip: str = "0.0.0.1") -> object:
+        # MODE_MEMORY forces the pure-Python decoder. Each DoS fixture resolves
+        # any IPv4 address to its single crafted record.
+        with open_database(f"{_TEST_DATA_DIR}/{filename}", mode=MODE_MEMORY) as reader:
+            return reader.get(ip)
+
+    def test_payload_amplification_is_rejected(self) -> None:
+        # An array of 8,192 pointers to one 65,535-byte value. The value count
+        # stays low, but copying each target would materialize about 512 MiB.
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            self._lookup("MaxMind-DB-test-payload-amplification-dos.mmdb")
+
+    def test_payload_amplification_string_is_rejected(self) -> None:
+        # The UTF-8 string variant, so the decode path for strings is exercised.
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            self._lookup("MaxMind-DB-test-payload-amplification-dos-string.mmdb")
+
+    def test_payload_amplification_worst_case_is_rejected(self) -> None:
+        # 65,535 pointers to one 65,535-byte value. The record is exactly
+        # 65,536 values under the flat rule, so only the payload budget can
+        # reject it.
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            self._lookup("MaxMind-DB-test-payload-amplification-dos-worst-case.mmdb")
+
+    def test_value_count_boundary(self) -> None:
+        # The at-limit fixture decodes to exactly 65,536 values and must decode.
+        # The pointer-heavy fixture reaches 65,535 values through pointers,
+        # which cost nothing beyond the values they resolve to. One value more
+        # than the limit is rejected.
+        self.assertIsInstance(
+            self._lookup("MaxMind-DB-test-decoder-value-limit.mmdb"),
+            list,
+        )
+        self.assertIsInstance(
+            self._lookup("MaxMind-DB-test-decoder-value-limit-pointer-heavy.mmdb"),
+            list,
+        )
+        with self.assertRaisesRegex(
+            InvalidDatabaseError,
+            "^The MaxMind DB file's data section exceeds the maximum number of values$",
+        ):
+            self._lookup("MaxMind-DB-test-decoder-value-limit-over.mmdb")
+
+    def test_pointer_fan_out_fixture_is_rejected(self) -> None:
+        # A full database whose record nests arrays of pointers to the level
+        # below, the classic 2**depth fan-out.
+        with self.assertRaises(InvalidDatabaseError):
+            self._lookup("MaxMind-DB-test-pointer-decoder-dos.mmdb")
+
+    def test_payload_at_limit_is_accepted(self) -> None:
+        # References totaling exactly 2 MiB of payload decode successfully, so
+        # the limit does not reject a record at the boundary.
+        self.assertIsInstance(
+            self._lookup("MaxMind-DB-test-decoder-payload-limit.mmdb"),
+            list,
+        )
+
+    def test_payload_one_over_limit_is_rejected(self) -> None:
+        # One byte more than 2 MiB is rejected, catching an off-by-one.
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            self._lookup("MaxMind-DB-test-decoder-payload-limit-over.mmdb")
+
+    def test_metadata_payload_limit_is_enforced_on_open(self) -> None:
+        # The same decoder reads metadata on open, so an over-limit metadata
+        # structure is rejected there too.
+        with self.assertRaisesRegex(InvalidDatabaseError, _PAYLOAD_TOO_LARGE):
+            open_database(
+                f"{_TEST_DATA_DIR}/MaxMind-DB-test-metadata-payload-limit.mmdb",
+                mode=MODE_MEMORY,
+            )
+
+    def test_normal_record_still_decodes(self) -> None:
+        # A record with ordinary string and bytes values, which the payload
+        # budget also charges, decodes unchanged.
+        record = cast(
+            "dict",
+            self._lookup("MaxMind-DB-test-decoder.mmdb", "::1.1.1.0"),
+        )
+        self.assertEqual(record["utf8_string"], "unicode! ☯ - ♫")
+        self.assertEqual(record["bytes"], b"\x00\x00\x00*")