Access GUIDS stream like a sequence.

Closes #84

Author: malwarefrank

HISTORY.rst

@@ -6,6 +6,7 @@ HEAD
 ----
 
 * BREAKING CHANGE: resource type DateTime is parsed into an object that exposes Kind value
+* FEATURE: access GUIDS stream like a 0-based sequence. GuidHeap subclasses abc.Sequence
 
 0.15.1 (2024)
 -------------

src/dnfile/stream.py

@@ -13,8 +13,9 @@
 
 import struct as _struct
 import logging
-from typing import Dict, List, Tuple, Union, Optional
+from typing import Dict, List, Tuple, Union, Optional, overload
 from binascii import hexlify as _hexlify
+from collections.abc import Sequence
 
 from pefile import MAX_STRING_LENGTH, Structure
 
@@ -268,6 +269,8 @@ def get(self, index, encoding="utf-16") -> Optional[UserString]:
 
 class HeapItemGuid(base.HeapItem):
 
+    ITEM_SIZE = 128 // 8  # number of bytes in a guid
+
     def __init__(self, data: bytes, rva: Optional[int] = None):
         super().__init__(data, rva)
 
@@ -288,7 +291,7 @@ def __repr__(self):
         return f"HeapItemGuid(data={self.__data__},rva={self.rva})"
 
 
-class GuidHeap(base.ClrHeap):
+class GuidHeap(base.ClrHeap, Sequence):
     offset_size = 0
 
     def get_str(self, index, as_bytes=False):
@@ -302,21 +305,48 @@ def get_str(self, index, as_bytes=False):
 
         return str(item)
 
-    def get(self, index) -> Optional[HeapItemGuid]:
-        if index is None or index < 1:
+    def get(self, index: int) -> Optional[HeapItemGuid]:
+        if not isinstance(index, int):
+            raise IndexError(f"unexpected type: {type(index)}")
+
+        # 1-based indexing
+        if index < 1 or index > len(self):
             return None
 
-        size = 128 // 8  # number of bytes in a guid
         # offset into the GUID stream
-        offset = (index - 1) * size
+        offset = (index - 1) * HeapItemGuid.ITEM_SIZE
 
-        if offset + size > len(self.__data__):
-            raise IndexError("index out of range")
-
-        item = HeapItemGuid(self.__data__[offset:offset + size], self.rva + offset)
+        item = HeapItemGuid(self.__data__[offset:offset + HeapItemGuid.ITEM_SIZE], self.rva + offset)
 
         return item
 
+    def __len__(self) -> int:
+        return len(self.__data__) // HeapItemGuid.ITEM_SIZE
+
+    @overload
+    def __getitem__(self, i: int) -> HeapItemGuid:
+        ...
+
+    @overload
+    def __getitem__(self, i: slice) -> List[HeapItemGuid]:
+        ...
+
+    def __getitem__(self, i):
+        if isinstance(i, int):
+            if i < 0:
+                # convert negative index into positive
+                index0 = len(self) + i
+            else:
+                index0 = i
+            item = self.get(index0 + 1)
+            if item is None:
+                raise IndexError(f"unexpected index: {i}")
+            return item
+        elif isinstance(i, slice):
+            start, stop, step = i.indices(len(self))
+            return [self[index] for index in range(start, stop, step)]
+        raise IndexError(f"unexpected type '{type(i)}'")
+
 
 class MDTablesStruct(Structure):
     Reserved_1: int

tests/test_parse.py

@@ -62,9 +62,24 @@ def test_guids():
     assert hasattr(dn.net, "guids")
 
     assert dn.net.guids.get(0) is None
+    assert isinstance(dn.net.guids.get(1), dnfile.stream.HeapItemGuid)
     assert dn.net.guids.get(1).value == b"\x8c\x8b\xc5\x48\xff\x24\x91\x45\x9e\xc8\x94\xbf\xea\xbd\x9f\x3e"
 
 
+def test_guids_as_sequence():
+    path = fixtures.get_data_path_by_name("hello-world.exe")
+
+    dn = dnfile.dnPE(path)
+    assert dn.net is not None
+    assert b"#GUID" in dn.net.metadata.streams
+    assert hasattr(dn.net, "guids")
+
+    assert len(dn.net.guids) == 1
+    assert dn.net.guids[0] is not None
+    assert hasattr(dn.net.guids[0], "value")
+    assert dn.net.guids[0].value == b"\x8c\x8b\xc5\x48\xff\x24\x91\x45\x9e\xc8\x94\xbf\xea\xbd\x9f\x3e"
+
+
 def test_tables():
     path = fixtures.get_data_path_by_name("hello-world.exe")