dfindexeddb 20251109__tar.gz → 20260205__tar.gz

{dfindexeddb-20251109 → dfindexeddb-20260205}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfindexeddb
-Version: 20251109
+Version: 20260205
 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>
@@ -55,6 +55,8 @@ include:
     $ pip install dfindexeddb
 ```
 
+### Optional plugins
+
 To also install the dependencies for leveldb/indexeddb plugins, run
 ```
     $ pip install 'dfindexeddb[plugins]'
@@ -79,6 +81,8 @@ To also install the dependencies for leveldb/indexeddb plugins, run
     $ pip install .
 ```
 
+### Optional plugins
+
 To also install the dependencies for leveldb/indexeddb plugins, run
 ```
     $ pip install '.[plugins]'
@@ -94,15 +98,17 @@ installation:
 
 ```
 $ dfindexeddb -h
-usage: dfindexeddb [-h] {db,ldb,log} ...
+usage: dfindexeddb [-h] {blink,gecko,db,ldb,log} ...
 
-A cli tool for parsing indexeddb files
+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.
+  {blink,gecko,db,ldb,log}
+    blink               Parse a file as a blink-encoded value.
+    gecko               Parse a file as a gecko-encoded value.
+    db                  Parse a directory/file 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
@@ -110,48 +116,17 @@ options:
 
 #### 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:
+| Platform / Source | Format | Command |
+| :--- | :--- | :--- |
+| **Firefox** (sqlite) | JSON | `dfindexeddb db -s SOURCE --format firefox -o json` |
+| **Safari** (sqlite) | JSON-L | `dfindexeddb db -s SOURCE --format safari -o jsonl` |
+| **Chrome** (LevelDB/sqlite) | JSON | `dfindexeddb db -s SOURCE --format chrome` |
+| **Chrome** (.ldb) | JSON-L | `dfindexeddb ldb -s SOURCE -o jsonl` |
+| **Chrome** (.log) | Python repr | `dfindexeddb log -s SOURCE -o repr` |
+| **Chrome** (Blink) | JSON | `dfindexeddb blink -s SOURCE` |
+| **Filter Records by key** | JSON | `dfindexeddb db -s SOURCE --format chrome --filter_key search_term` |
+| **Filter Records by value** | JSON | `dfindexeddb db -s SOURCE --format chrome --filter_value "search_term"` |
 
-```
-dfindexeddb blink -s SOURCE
-```
 
 ### LevelDB
 
@@ -174,44 +149,18 @@ options:
 
 #### 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
+| Source | Type | Command |
+| :--- | :--- | :--- |
+| **LevelDB Folder** | Records | `dfleveldb db -s SOURCE` |
+| **Log file** (.log) | Physical Records | `dfleveldb log -s SOURCE -t physical_records` |
+| **Log file** (.log) | Blocks | `dfleveldb log -s SOURCE -t blocks` |
+| **Log file** (.log) | Write Batches | `dfleveldb log -s SOURCE -t write_batches` |
+| **Log file** (.log) | Internal Key Records | `dfleveldb log -s SOURCE -t parsed_internal_key` |
+| **Table file** (.ldb) | Records | `dfleveldb ldb -s SOURCE -t record` |
+| **Table file** (.ldb) | Blocks | `dfleveldb ldb -s SOURCE -t blocks` |
+| **Descriptor** (MANIFEST) | Version Edits | `dfleveldb descriptor -s SOURCE -t versionedit` |
+
+#### Optional Plugins
 
 To apply a plugin parser for a leveldb file/folder, add the
 `--plugin [Plugin Name]` argument.  Currently, there is support for the

{dfindexeddb-20251109 → dfindexeddb-20260205}/README.md

@@ -32,6 +32,8 @@ include:
     $ pip install dfindexeddb
 ```
 
+### Optional plugins
+
 To also install the dependencies for leveldb/indexeddb plugins, run
 ```
     $ pip install 'dfindexeddb[plugins]'
@@ -56,6 +58,8 @@ To also install the dependencies for leveldb/indexeddb plugins, run
     $ pip install .
 ```
 
+### Optional plugins
+
 To also install the dependencies for leveldb/indexeddb plugins, run
 ```
     $ pip install '.[plugins]'
@@ -71,15 +75,17 @@ installation:
 
 ```
 $ dfindexeddb -h
-usage: dfindexeddb [-h] {db,ldb,log} ...
+usage: dfindexeddb [-h] {blink,gecko,db,ldb,log} ...
 
-A cli tool for parsing indexeddb files
+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.
+  {blink,gecko,db,ldb,log}
+    blink               Parse a file as a blink-encoded value.
+    gecko               Parse a file as a gecko-encoded value.
+    db                  Parse a directory/file 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
@@ -87,48 +93,17 @@ options:
 
 #### 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:
+| Platform / Source | Format | Command |
+| :--- | :--- | :--- |
+| **Firefox** (sqlite) | JSON | `dfindexeddb db -s SOURCE --format firefox -o json` |
+| **Safari** (sqlite) | JSON-L | `dfindexeddb db -s SOURCE --format safari -o jsonl` |
+| **Chrome** (LevelDB/sqlite) | JSON | `dfindexeddb db -s SOURCE --format chrome` |
+| **Chrome** (.ldb) | JSON-L | `dfindexeddb ldb -s SOURCE -o jsonl` |
+| **Chrome** (.log) | Python repr | `dfindexeddb log -s SOURCE -o repr` |
+| **Chrome** (Blink) | JSON | `dfindexeddb blink -s SOURCE` |
+| **Filter Records by key** | JSON | `dfindexeddb db -s SOURCE --format chrome --filter_key search_term` |
+| **Filter Records by value** | JSON | `dfindexeddb db -s SOURCE --format chrome --filter_value "search_term"` |
 
-```
-dfindexeddb blink -s SOURCE
-```
 
 ### LevelDB
 
@@ -151,44 +126,18 @@ options:
 
 #### 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
+| Source | Type | Command |
+| :--- | :--- | :--- |
+| **LevelDB Folder** | Records | `dfleveldb db -s SOURCE` |
+| **Log file** (.log) | Physical Records | `dfleveldb log -s SOURCE -t physical_records` |
+| **Log file** (.log) | Blocks | `dfleveldb log -s SOURCE -t blocks` |
+| **Log file** (.log) | Write Batches | `dfleveldb log -s SOURCE -t write_batches` |
+| **Log file** (.log) | Internal Key Records | `dfleveldb log -s SOURCE -t parsed_internal_key` |
+| **Table file** (.ldb) | Records | `dfleveldb ldb -s SOURCE -t record` |
+| **Table file** (.ldb) | Blocks | `dfleveldb ldb -s SOURCE -t blocks` |
+| **Descriptor** (MANIFEST) | Version Edits | `dfleveldb descriptor -s SOURCE -t versionedit` |
+
+#### Optional Plugins
 
 To apply a plugin parser for a leveldb file/folder, add the
 `--plugin [Plugin Name]` argument.  Currently, there is support for the

{dfindexeddb-20251109 → dfindexeddb-20260205}/dfindexeddb/indexeddb/chromium/definitions.py

@@ -14,11 +14,14 @@
 # limitations under the License.
 """Definitions for IndexedDB."""
 from enum import Enum, IntEnum, IntFlag
+import textwrap
 
 REQUIRES_PROCESSING_SSV_PSEUDO_VERSION = 0x11
 REPLACE_WITH_BLOB = 0x01
 COMPRESSED_WITH_SNAPPY = 0x02
 
+SENTINEL = 0x00
+
 
 class DatabaseMetaDataKeyType(IntEnum):
   """Database Metadata key types."""
@@ -72,6 +75,16 @@ class IDBKeyType(IntEnum):
   BINARY = 6
 
 
+class OrderedIDBKeyType(IntEnum):
+  """Ordered IndexedDB key types."""
+
+  NUMBER = 0x10
+  DATE = 0x20
+  STRING = 0x30
+  BINARY = 0x40
+  ARRAY = 0x50
+
+
 class IndexMetaDataKeyType(IntEnum):
   """IndexedDB metadata key types."""
 
@@ -398,3 +411,82 @@ class SerializedImageOrientation(IntEnum):
   RIGHT_BOTTOM = 6
   LEFT_BOTTOM = 7
   LAST = LEFT_BOTTOM
+
+
+class DatabaseCompressionType(IntEnum):
+  """Database Compression Types."""
+
+  UNCOMPRESSED = 0
+  ZSTD = 1
+  SNAPPY = 2
+
+
+SQL_RECORDS_QUERY_BASE = textwrap.dedent(
+    """
+    SELECT
+        row_id,
+        object_store_id,
+        compression_type,
+        key,
+        value,
+        EXISTS (
+            SELECT 1
+            FROM blob_references
+            WHERE record_row_id = records.row_id
+        ) AS has_blobs
+    FROM records"""
+).strip()
+
+SQL_RECORDS_QUERY = SQL_RECORDS_QUERY_BASE
+
+SQL_RECORDS_BY_ID_QUERY = f"{SQL_RECORDS_QUERY_BASE} WHERE object_store_id = ?"
+
+SQL_RECORDS_BY_NAME_QUERY = textwrap.dedent(
+    f"""
+    {SQL_RECORDS_QUERY_BASE}
+    JOIN object_stores ON records.object_store_id = object_stores.id
+    WHERE object_stores.name = ?"""
+).strip()
+
+SQL_OBJECT_STORES_QUERY = textwrap.dedent(
+    """
+    SELECT
+        id,
+        name,
+        key_path,
+        auto_increment,
+        key_generator_current_number
+    FROM object_stores"""
+).strip()
+
+SQL_BLOB_DATA_QUERY = textwrap.dedent(
+    """
+    SELECT
+        b.row_id,
+        b.object_type,
+        b.mime_type,
+        b.size_bytes,
+        b.file_name,
+        0 AS chunk_index,
+        b.bytes
+    FROM blobs b
+    JOIN blob_references r ON b.row_id = r.blob_row_id
+    WHERE r.record_row_id = ?
+
+    UNION ALL
+
+    SELECT
+        c.blob_row_id AS row_id,
+        b.object_type,
+        b.mime_type,
+        b.size_bytes,
+        b.file_name,
+        c.chunk_index,
+        c.bytes
+    FROM overflow_blob_chunks c
+    JOIN blobs b ON c.blob_row_id = b.row_id
+    JOIN blob_references r ON b.row_id = r.blob_row_id
+    WHERE r.record_row_id = ?
+
+    ORDER BY row_id, chunk_index"""
+).strip()