dfindexeddb 20241031__py3-none-any.whl → 20251109__py3-none-any.whl

dfindexeddb/utils.py

@@ -14,13 +14,13 @@
 # limitations under the License.
 """Utilities for dfindexeddb."""
 from __future__ import annotations
+
 import copy
 import dataclasses
 import io
 import os
 import struct
-from typing import BinaryIO, Tuple, Type, TypeVar
-
+from typing import Any, BinaryIO, Literal, Tuple, Type, TypeVar
 
 from dfindexeddb import errors
 
@@ -28,8 +28,8 @@ from dfindexeddb import errors
 class StreamDecoder:
   """A helper class to decode primitive data types from BinaryIO streams.
 
-   Attributes:
-    stream (BinaryIO): the binary stream.
+  Attributes:
+   stream (BinaryIO): the binary stream.
   """
 
   def __init__(self, stream: BinaryIO):
@@ -51,7 +51,7 @@ class StreamDecoder:
     self.stream.seek(current_offset, os.SEEK_SET)
     num_rem_bytes = end_offset - current_offset
     if num_rem_bytes < 0:
-      raise errors.DecoderError('Negative number of remaining bytes.')
+      raise errors.DecoderError("Negative number of remaining bytes.")
     return num_rem_bytes
 
   def ReadBytes(self, count: int = -1) -> Tuple[int, bytes]:
@@ -71,10 +71,11 @@ class StreamDecoder:
     offset = self.stream.tell()
     buffer = self.stream.read(count)
     if count == -1 and not buffer:
-      raise errors.DecoderError(f'No bytes available at offset {offset}')
+      raise errors.DecoderError(f"No bytes available at offset {offset}")
     if count != -1 and len(buffer) != count:
       raise errors.DecoderError(
-          f'Read {len(buffer)} bytes, but wanted {count} at offset {offset}')
+          f"Read {len(buffer)} bytes, but wanted {count} at offset {offset}"
+      )
     return offset, buffer
 
   def PeekBytes(self, count: int) -> Tuple[int, bytes]:
@@ -94,8 +95,8 @@ class StreamDecoder:
   def DecodeInt(
       self,
       byte_count: int = -1,
-      byte_order: str = 'little',
-      signed: bool = True
+      byte_order: Literal["big", "little"] = "little",
+      signed: bool = True,
   ) -> Tuple[int, int]:
     """Decodes an integer from the binary stream.
 
@@ -162,27 +163,27 @@ class StreamDecoder:
     """Returns a Tuple of the offset and a double-precision float."""
     offset, blob = self.ReadBytes(8)
     if little_endian:
-      value = struct.unpack('<d', blob)[0]
+      value = struct.unpack("<d", blob)[0]
     else:
-      value = struct.unpack('>d', blob)[0]
+      value = struct.unpack(">d", blob)[0]
     return offset, value
 
   def DecodeFloat(self, little_endian: bool = True) -> Tuple[int, float]:
     """Returns a Tuple of the offset and a single-precision float."""
     offset, blob = self.ReadBytes(4)
     if little_endian:
-      value = struct.unpack('<f', blob)[0]
+      value = struct.unpack("<f", blob)[0]
     else:
-      value = struct.unpack('>f', blob)[0]
+      value = struct.unpack(">f", blob)[0]
     return offset, value
 
   def DecodeVarint(self, max_bytes: int = 10) -> Tuple[int, int]:
     """Returns a Tuple of the offset and the decoded base128 varint."""
     offset = self.stream.tell()
     varint = 0
-    for i in range(0, max_bytes*7, 7):
+    for i in range(0, max_bytes * 7, 7):
       _, varint_part = self.ReadBytes(1)
-      varint |= (varint_part[0] & 0x7f) << i
+      varint |= (varint_part[0] & 0x7F) << i
       if not varint_part[0] >> 7:
         break
     return offset, varint
@@ -209,7 +210,7 @@ class StreamDecoder:
     return self.DecodeZigzagVarint(max_bytes=10)
 
 
-T = TypeVar('T')
+T = TypeVar("T")
 
 
 class FromDecoderMixin:
@@ -217,7 +218,8 @@ class FromDecoderMixin:
 
   @classmethod
   def FromDecoder(
-      cls: Type[T], decoder: StreamDecoder, base_offset: int = 0) -> T:
+      cls: Type[T], decoder: StreamDecoder, base_offset: int = 0
+  ) -> T:
     """Decodes a class type from the current position of a StreamDecoder.
 
     Args:
@@ -233,8 +235,7 @@ class FromDecoderMixin:
     raise NotImplementedError
 
   @classmethod
-  def FromStream(
-      cls: Type[T], stream: BinaryIO, base_offset: int = 0) -> T:
+  def FromStream(cls: Type[T], stream: BinaryIO, base_offset: int = 0) -> T:
     """Decodes a class type from the current position of a binary stream.
 
     Args:
@@ -245,11 +246,12 @@ class FromDecoderMixin:
       The class instance.
     """
     decoder = StreamDecoder(stream)
-    return cls.FromDecoder(decoder=decoder, base_offset=base_offset)
+    return cls.FromDecoder(  # type: ignore[attr-defined,no-any-return]
+        decoder=decoder, base_offset=base_offset
+    )
 
   @classmethod
-  def FromBytes(
-      cls: Type[T], raw_data: bytes, base_offset: int = 0) -> T:
+  def FromBytes(cls: Type[T], raw_data: bytes, base_offset: int = 0) -> T:
     """Parses a class type from raw bytes.
 
     Args:
@@ -260,10 +262,12 @@ class FromDecoderMixin:
       The class instance.
     """
     stream = io.BytesIO(raw_data)
-    return cls.FromStream(stream=stream, base_offset=base_offset)
+    return cls.FromStream(  # type: ignore[attr-defined,no-any-return]
+        stream=stream, base_offset=base_offset
+    )
 
 
-def asdict(obj, *, dict_factory=dict):  # pylint: disable=invalid-name
+def asdict(obj, *, dict_factory=dict) -> Any:  # type: ignore[no-untyped-def]  # pylint: disable=invalid-name
   """Custom implementation of the asdict dataclasses method to include the
   class name under the __type__ attribute name.
   """
@@ -272,24 +276,25 @@ def asdict(obj, *, dict_factory=dict):  # pylint: disable=invalid-name
   return _asdict_inner(obj, dict_factory)
 
 
-def _asdict_inner(obj, dict_factory):
+def _asdict_inner(obj, dict_factory):  # type: ignore[no-untyped-def]
   """Custom implementation of the _asdict_inner dataclasses method."""
   if dataclasses.is_dataclass(obj):
-    result = [('__type__', obj.__class__.__name__)]
+    result = [("__type__", obj.__class__.__name__)]
     for f in dataclasses.fields(obj):
       value = _asdict_inner(getattr(obj, f.name), dict_factory)
       result.append((f.name, value))
     return dict_factory(result)
 
-  if isinstance(obj, tuple) and hasattr(obj, '_fields'):
+  if isinstance(obj, tuple) and hasattr(obj, "_fields"):
     return type(obj)(*[_asdict_inner(v, dict_factory) for v in obj])
 
   if isinstance(obj, (list, tuple)):
     return type(obj)(_asdict_inner(v, dict_factory) for v in obj)
 
   if isinstance(obj, dict):
-    return type(obj)((_asdict_inner(k, dict_factory),
-                      _asdict_inner(v, dict_factory))
-                      for k, v in obj.items())
+    return type(obj)(
+        (_asdict_inner(k, dict_factory), _asdict_inner(v, dict_factory))
+        for k, v in obj.items()
+    )
 
   return copy.deepcopy(obj)

dfindexeddb/version.py

@@ -15,9 +15,9 @@
 """Version information for dfIndexeddb."""
 
 
-__version__ = "20241031"
+__version__ = "20251109"
 
 
-def GetVersion():
+def GetVersion() -> str:
   """Returns the version information."""
   return __version__

dfindexeddb-20251109.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: dfindexeddb
+Version: 20251109
+Summary: dfindexeddb is an experimental Python tool for performing digital forensic analysis of IndexedDB and leveldb files.
+Author-email: Syd Pleno <sydp@google.com>
+Maintainer-email: dfIndexeddb Developers <dfindexeddb-dev@googlegroups.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/google/dfindexeddb
+Project-URL: Documentation, https://github.com/google/dfindexeddb/tree/main/docs
+Project-URL: Repository, https://github.com/google/dfindexeddb
+Project-URL: Bug Tracker, https://github.com/google/dfindexeddb/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-snappy==0.6.1
+Requires-Dist: zstd==1.5.5.1
+Provides-Extra: plugins
+Requires-Dist: protobuf; extra == "plugins"
+Requires-Dist: dfdatetime; extra == "plugins"
+Dynamic: license-file
+
+# dfIndexeddb
+
+dfindexeddb is an experimental Python tool for performing digital forensic
+analysis of IndexedDB and LevelDB files.
+
+It parses LevelDB, IndexedDB and JavaScript structures from these files without
+requiring native libraries.  (Note: only a subset of IndexedDB key types and
+JavaScript types for Firefox, Safari and Chromium-based browsers are currently supported).
+
+The content of IndexedDB files is dependent on what a web application stores
+locally/offline using the web browser's
+[IndexedDB API](https://www.w3.org/TR/IndexedDB/).  Examples of content might
+include:
+* text from a text/source-code editor application,
+* emails and contact information from an e-mail application,
+* images and metadata from a photo gallery application
+
+
+## Installation
+
+1. [Linux] Install the snappy compression development package
+
+```
+    $ sudo apt install libsnappy-dev
+```
+
+2. Create a virtual environment and install the package
+
+```
+    $ python3 -m venv .venv
+    $ source .venv/bin/activate
+    $ pip install dfindexeddb
+```
+
+To also install the dependencies for leveldb/indexeddb plugins, run
+```
+    $ pip install 'dfindexeddb[plugins]'
+```
+
+
+## Installation from source
+
+1. [Linux] Install the snappy compression development package
+
+```
+    $ sudo apt install libsnappy-dev
+```
+
+2. Clone or download/unzip the repository to your local machine.
+
+3. Create a virtual environment and install the package
+
+```
+    $ python3 -m venv .venv
+    $ source .venv/bin/activate
+    $ pip install .
+```
+
+To also install the dependencies for leveldb/indexeddb plugins, run
+```
+    $ pip install '.[plugins]'
+```
+
+## Usage
+
+Two CLI tools for parsing IndexedDB/LevelDB files are available after
+installation:
+
+
+### IndexedDB
+
+```
+$ dfindexeddb -h
+usage: dfindexeddb [-h] {db,ldb,log} ...
+
+A cli tool for parsing indexeddb files
+
+positional arguments:
+  {db,ldb,log}
+    db          Parse a directory as indexeddb.
+    ldb         Parse a ldb file as indexeddb.
+    log         Parse a log file as indexeddb.
+
+options:
+  -h, --help    show this help message and exit
+```
+
+#### Examples:
+
+To parse IndexedDB records from an sqlite file for Firefox and output the
+results as JSON, use the following command:
+
+```
+dfindexeddb db -s SOURCE --format firefox -o json
+```
+
+To parse IndexedDB records from an sqlite file for Safari and output the
+results as JSON-L, use the following command:
+
+```
+dfindexeddb db -s SOURCE --format safari -o jsonl
+```
+
+To parse IndexedDB records from a LevelDB folder for Chrome/Chromium, using the
+manifest file to determine recovered records and output as JSON, use the
+following command:
+
+```
+dfindexeddb db -s SOURCE --format chrome --use_manifest
+```
+
+To parse IndexedDB records from a LevelDB ldb (.ldb) file and output the
+results as JSON-L, use the following command:
+
+```
+dfindexeddb ldb -s SOURCE -o jsonl
+```
+
+To parse IndexedDB records from a LevelDB log (.log) file and output the
+results as the Python printable representation, use the following command:
+
+```
+dfindexeddb log -s SOURCE -o repr
+```
+
+To parse a file as a Chrome/Chromium IndexedDB blink value and output the
+results as JSON:
+
+```
+dfindexeddb blink -s SOURCE
+```
+
+### LevelDB
+
+```
+$ dfleveldb -h
+usage: dfleveldb [-h] {db,log,ldb,descriptor} ...
+
+A cli tool for parsing leveldb files
+
+positional arguments:
+  {db,log,ldb,descriptor}
+    db                  Parse a directory as leveldb.
+    log                 Parse a leveldb log file.
+    ldb                 Parse a leveldb table (.ldb) file.
+    descriptor          Parse a leveldb descriptor (MANIFEST) file.
+
+options:
+  -h, --help            show this help message and exit
+```
+
+#### Examples
+
+To parse records from a LevelDB folder, use the following command:
+
+```
+dfleveldb db -s SOURCE
+```
+
+To parse records from a LevelDB folder, and use the sequence number to
+determine recovered records and output as JSON, use the
+following command:
+
+```
+dfleveldb db -s SOURCE --use_sequence_number
+```
+
+To parse blocks / physical records/ write batches / internal key records from a
+LevelDB log (.log) file, use the following command, specifying the type (block,
+physical_records, etc) via the `-t` option.  By default, internal key records are parsed:
+
+```
+$ dfleveldb log  -s SOURCE [-t {blocks,physical_records,write_batches,parsed_internal_key}]
+```
+
+To parse blocks / records from a LevelDB table (.ldb) file, use the following
+command, specifying the type (blocks, records) via the `-t` option.  By
+default, records are parsed:
+
+```
+$ dfleveldb ldb -s SOURCE [-t {blocks,records}]
+```
+
+To parse version edit records from a Descriptor (MANIFEST) file, use the
+following command:
+
+```
+$ dfleveldb descriptor -s SOURCE [-o {json,jsonl,repr}] [-t {blocks,physical_records,versionedit} | -v]
+```
+
+#### Plugins
+
+To apply a plugin parser for a leveldb file/folder, add the
+`--plugin [Plugin Name]` argument.  Currently, there is support for the
+following artifacts:
+
+| Plugin Name | Artifact Name |
+| -------- | ------- |
+| `ChromeNotificationRecord` | Chrome/Chromium Notifications |

dfindexeddb-20251109.dist-info/RECORD

@@ -0,0 +1,40 @@
+dfindexeddb/__init__.py,sha256=KPYL9__l8od6_OyDfGRTgaJ6iy_fqIgZ-dS2S-e3Rac,599
+dfindexeddb/errors.py,sha256=PNpwyf_lrPc4TE77oAakX3mu5D_YcP3f80wq8Y1LkvY,749
+dfindexeddb/utils.py,sha256=gep43m3LpAZNnW6JFOQTDn8MRrEXzGlc1NZ5yMuBsvI,10194
+dfindexeddb/version.py,sha256=C6239PGrB1o3OzfiWQ-W1g11b6xwmAfs53zspL7Ub1w,758
+dfindexeddb/indexeddb/__init__.py,sha256=kExXSVBCTKCD5BZJkdMfUMqGksH-DMJxP2_lI0gq-BE,575
+dfindexeddb/indexeddb/cli.py,sha256=gEVlE6ZRAu360Oc5dePVQEupKLEGQUt6mUljlbptIUE,7686
+dfindexeddb/indexeddb/types.py,sha256=m9llt7PTVMSvhsQ_uDIlZJUkbM_5k3gUx5CtMc3TvC8,1893
+dfindexeddb/indexeddb/utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dfindexeddb/indexeddb/chromium/__init__.py,sha256=kExXSVBCTKCD5BZJkdMfUMqGksH-DMJxP2_lI0gq-BE,575
+dfindexeddb/indexeddb/chromium/blink.py,sha256=oQdbgzn4w1dUs3jAqtCF0078o4ccupHSjH0hB42vJSc,32978
+dfindexeddb/indexeddb/chromium/definitions.py,sha256=cNFUhE9ngd_-NSNnH-0sXNRaX1keNrN6UKvF_ADaYds,8864
+dfindexeddb/indexeddb/chromium/record.py,sha256=AwZTvgjwj3wOPSNh2S94SXD2Ynhi8l1xqTB1asWp3vg,49373
+dfindexeddb/indexeddb/chromium/v8.py,sha256=cbaFQmhZoJMWGphLdvz1ZcvTge9MSh6GLH4K1yQNiWk,21888
+dfindexeddb/indexeddb/firefox/__init__.py,sha256=kExXSVBCTKCD5BZJkdMfUMqGksH-DMJxP2_lI0gq-BE,575
+dfindexeddb/indexeddb/firefox/definitions.py,sha256=C9qziLvNMmWFwVrt6K_lw4I_1YbiWJ9nxb65x0TefvU,4306
+dfindexeddb/indexeddb/firefox/gecko.py,sha256=rcph8PrX0IL_67cCvx9EsbEK_8r8lkXvW-nU7_2IsxA,19932
+dfindexeddb/indexeddb/firefox/record.py,sha256=wm0jHuTK47Qp6NPb2dQzRcqHnFTxOaPIz9sDHqb8gSc,6878
+dfindexeddb/indexeddb/safari/__init__.py,sha256=kExXSVBCTKCD5BZJkdMfUMqGksH-DMJxP2_lI0gq-BE,575
+dfindexeddb/indexeddb/safari/definitions.py,sha256=_st96KuCjgzAeltDGylmoojlCtVvTGQPWwqzYCuX3s8,2793
+dfindexeddb/indexeddb/safari/record.py,sha256=TKD1ltTOzhjKKU-3sCy7zm4H2r4NAZjlNel57m4BDZo,8132
+dfindexeddb/indexeddb/safari/webkit.py,sha256=16Vj7f3Pbts2ebdFg1dXmqQ3ixAKKv4_3znvsP21b4U,20816
+dfindexeddb/leveldb/__init__.py,sha256=KPYL9__l8od6_OyDfGRTgaJ6iy_fqIgZ-dS2S-e3Rac,599
+dfindexeddb/leveldb/cli.py,sha256=7CkM9P0bk83uj1cJrGFai82FIPBF0sul1tI2KUTMokA,10291
+dfindexeddb/leveldb/definitions.py,sha256=cvwO3BkbEh5ISlPzlM_TL2xs-1lRyqepiyy7_ZZ8-_A,1490
+dfindexeddb/leveldb/descriptor.py,sha256=Cmy9y73cBeb586pryoagZ0-Zb2iA_8MCRGu6SN5dKbo,12479
+dfindexeddb/leveldb/ldb.py,sha256=7sjpqMXrU6iXz5d4GAx58BuEknpjPM3qlrzNv6jdLIk,8140
+dfindexeddb/leveldb/log.py,sha256=oCMpLH8STOSK0qM-u44wnf781ehy5-JPe1e_osMlgL4,9510
+dfindexeddb/leveldb/record.py,sha256=Fnz7i446IO3IjJZAlB9olM_VSiEaM2ONHzG7BqrBzak,11978
+dfindexeddb/leveldb/utils.py,sha256=-70BjnttqGHHG1Ze9r8Pxspp6LGbRqHxXb3FODyXF6I,3879
+dfindexeddb/leveldb/plugins/__init__.py,sha256=RoC6tRkq8FhqIaFs6jwu1fao_qaSvlSfIFxQVjWregI,690
+dfindexeddb/leveldb/plugins/chrome_notifications.py,sha256=H2TgriK_mre1kflTh2Zd2aIvcoHXa_qJum5f5Sbwp88,5485
+dfindexeddb/leveldb/plugins/interface.py,sha256=1kFbhzgiRLQ18gdOc-pzbizQ7dp_Li-ut4ZHjXSxKIU,1193
+dfindexeddb/leveldb/plugins/manager.py,sha256=UV8dtdeu6xPCNzvx3fSef1WrZxGPzkPBD8mD2qpoVzY,2317
+dfindexeddb/leveldb/plugins/notification_database_data_pb2.py,sha256=DCPZHbyq2szLgrBprOKrJKycKJma8Z_SnAQM6Jx9bZg,4389
+dfindexeddb-20251109.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+dfindexeddb-20251109.dist-info/METADATA,sha256=pewsavAQMLj0KqCnAxod4ZswNQ02HV9dBXEIEirLiLc,6015
+dfindexeddb-20251109.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dfindexeddb-20251109.dist-info/entry_points.txt,sha256=WG9YNLZ9lBx4Q9QF6wS4dZdZfADT3Zs4_-MV5TcA0ls,102
+dfindexeddb-20251109.dist-info/top_level.txt,sha256=X9OTaub1c8S_JJ7g-f8JdkhhdiZ4x1j4eni1hdUCwE4,12
+dfindexeddb-20251109.dist-info/RECORD,,

{dfindexeddb-20241031.dist-info → dfindexeddb-20251109.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.3.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

dfindexeddb-20241031.dist-info/AUTHORS

@@ -1,12 +0,0 @@
-# Names should be added to this file with this pattern:
-#
-# For individuals:
-#   Name (email address)
-#
-# For organizations:
-#   Organization (fnmatch pattern)
-#
-# See python fnmatch module documentation for more information.
-
-Google Inc. (*@google.com)
-Syd Pleno (syd.pleno@gmail.com)