dfindexeddb 20241105__tar.gz → 20260205__tar.gz

dfindexeddb-20260205/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: dfindexeddb
+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>
+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
+```
+
+### Optional plugins
+
+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 .
+```
+
+### Optional plugins
+
+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] {blink,gecko,db,ldb,log} ...
+
+A cli tool for parsing IndexedDB files
+
+positional arguments:
+  {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
+```
+
+#### Examples:
+
+| 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"` |
+
+
+### 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
+
+| 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
+following artifacts:
+
+| Plugin Name | Artifact Name |
+| -------- | ------- |
+| `ChromeNotificationRecord` | Chrome/Chromium Notifications |

{dfindexeddb-20241105 → 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