<p align="center">
<img src="assets/DLEAPP_logo.png" alt="DLEAPP" width="200">
</p>
# Desktop Logs Events And Protobuf Parser
**DLEAPP** parses artifacts left behind by **desktop applications** — the logs, events, and stored data of Electron/Chromium-based desktop apps: IndexedDB/LevelDB stores (including protobuf-encoded values), Local Storage, service-worker and HTTP caches, cookies, and application logs. It is a member of the LEAPP family, built on the RLEAPP framework.
DLEAPP is also meant to be a home for parsers that don't fit neatly into any of the other LEAPPs — a place for desktop-application and other odds-and-ends artifacts to live rather than being forced into iLEAPP, ALEAPP, RLEAPP, and the like.
### Supported applications
| Application | What is parsed |
| --- | --- |
| **Wire** (desktop) | Accounts, devices, conversations, messages, calls, attachments, cookies, service-worker cache, and media recovered by decrypting cached asset blobs. |
| **Discord** (desktop) | Messages, attachments and recovered media, servers, channels, users, searches, reactions, message drafts, client activity, channel navigation, gateway sessions, account and application details, and a full cache index. |
| **Signal** (desktop) | Messages, attachments decrypted from disk, conversations and groups, calls, reactions, protocol sessions and identity keys, and account details. Requires the database credential — see below. |
Discord Desktop keeps no message database of its own: the client renders from
REST API responses, and those responses stay in the Chromium HTTP cache. The
Discord artifacts read that cache directly, so messages, attachments and the
images themselves are recoverable after they were deleted server-side. The
approach follows Alex Caithness's work on treating a web app's browser
artifacts as an application in their own right
([browser-forensics-presentation-2025](https://github.com/cclgroupltd/browser-forensics-presentation-2025),
[mister-skinnylegs](https://github.com/cclgroupltd/mister-skinnylegs)).
The Chromium container formats these parsers rely on live in `scripts/chromium/`
(Simple Cache reader, Local Storage LevelDB reader) and are reusable by any
future Electron application parser. More desktop-application parsers will be
added over time.
### Signal Desktop needs a credential
Signal encrypts its message database with SQLCipher, and encrypts every file in
`attachments.noindex` with a key held inside that database. Recent versions wrap
the database key with the OS credential store, so it is **not** in the profile:
* macOS — login Keychain, service `Signal Safe Storage`
* Windows — Credential Manager
Capture it from the host and pass it in. DLEAPP accepts the credential, the
64 character database key itself, or a file holding either:
```
python3 dleapp.py -t fs -i <profile> -o <output> --signal-key
```
Given the flag with no value it prompts without echo, which keeps the secret out
of shell history and the process list. The GUI has an equivalent Signal key
field. A file named `signal_password.txt` beside the extraction is also picked
up, which suits batch runs. Older profiles that still hold a plaintext `key` in
`config.json` need nothing at all.
On a dead-box macOS image there is no host to read the credential from, but the
`login.keychain-db` is in the extraction. Supply the account's **login
password** in the same place, and if a `login.keychain-db` is present DLEAPP
recovers the `Signal Safe Storage` credential from it offline
(`scripts/macos_keychain.py`) and unwraps the key with no external tooling. The
same field therefore accepts either the safeStorage credential or the login
password — DLEAPP tries the credential interpretation first, then the keychain.
If the database was already decrypted, with DB Browser for SQLCipher or another
tool, DLEAPP detects that and parses it as it is — no credential needed.
Without a credential, and with the database still encrypted, the Signal
artifacts report why and produce no rows rather than failing silently. `scripts/sqlcipher_decrypt.py` is the same pure-python
reader ALEAPP and iLEAPP use, so it needs no native SQLCipher build.
If you want to contribute hit me up on twitter: https://twitter.com/AlexisBrignoni
## Download
Download a pre-built release, no Python installation required, from
[DLEAPP GitHub Releases](https://github.com/abrignoni/DLEAPP/releases) or
[LEAPPs Releases](https://leapps.org/releases).
| Platform | Download |
| -------- | -------- |
| Windows (Intel/AMD) | `DLEAPP-*-windows-x64-portable.zip` |
| Windows (ARM) | `DLEAPP-*-windows-arm64-portable.zip` |
| macOS (Apple Silicon) | `DLEAPP-*-macos-arm64.dmg` |
| macOS (Intel) | `DLEAPP-*-macos-x64.dmg` |
| Linux (Intel/AMD) | `DLEAPP-*-linux-x64.AppImage` |
| Linux (ARM) | `DLEAPP-*-linux-arm64.AppImage` |
Each download holds one program, `dleapp`. `SHA256SUMS.txt` in each release lets you check a download.
**GUI**: open DLEAPP the usual way: by double-clicking `dleapp.exe` from the zip on
Windows, DLEAPP in Applications on macOS, or the AppImage on Linux. Started without
arguments, it opens the window.
**CLI**: give `dleapp` arguments in a terminal and it runs as a command line instead. The
output folder must already exist. On Windows, use `dleapp.exe` from the zip.
```
dleapp.exe -t fs -i C:\path\to\extraction -o C:\path\to\output\
```
On Linux, run the AppImage with the same arguments. On macOS it is inside the app; to
type just `dleapp` in a terminal, link it onto your PATH once:
```
sudo ln -s /Applications/DLEAPP.app/Contents/MacOS/dleapp /usr/local/bin/dleapp
```
## Requirements
**Python 3.11 or above**
### Dependencies
Dependencies for your python environment are listed in `requirements.txt`. Install them using the below command. Ensure the `py` part is correct for your environment, eg `py`, `python`, or `python3`, etc.
`py -m pip install -r requirements.txt`
or
`pip3 install -r requirements.txt`
To run on **Linux**, you will also need to install `tkinter` separately like so:
`sudo apt-get install python3-tk`
To install dependencies offline Troy Schnack has a neat process here:
https://twitter.com/TroySchnack/status/1266085323651444736?s=19
To read Apple Unified Logs (the tracev3 data in a Mac extraction) when running from
source, DLEAPP needs Mandiant's `unifiedlog_iterator`.
`python admin/scripts/fetch_unifiedlog_iterator.py` downloads the pinned release for your
platform into `bin/` after checking its SHA-256; see `bin/PROVENANCE.md`.
## Usage
### CLI
```
$ python dleapp.py -t <zip | tar | fs | gz | raw> -i <path_to_extraction> -o <path_for_report_output>
```
`raw` reads a disk image (`.img`, `.dd`, `.bin`, or any numbered `.001` segment of
a split set), or an acquisition and the segments or files beside it (EnCase/EWF
`.E01`, SMART `.s01`, EWF2 `.Ex01`, AFF `.aff`, AFM `.afm`, any `.aff` in an AFD folder,
AFF4 `.aff4`, an Apple `.dmg`, with any `.dmgpart` files beside it, `.sparseimage` or
`.sparsebundle` folder, or a virtual machine disk, `.vhd`, `.vhdx`, `.vmdk` or `.qcow2`), in
place: no mounting and no administrator rights. Its NTFS, FAT32, FAT16, FAT12, exFAT, ext2/3/4,
F2FS, HFS+, APFS, QNX6, QNX4, ETFS, EFS, SquashFS, JFFS2, UBI/UBIFS, YAFFS and QNX IFS
volumes are searched directly (and a U-Boot environment or Belkin NVRM store is read as one
file), and
only the files an artifact asks for are read out of the image. Logical evidence, an
EnCase `.L01` or an FTK Imager `.ad1`, is read as the files it holds. The GUI picks
`raw` on its own for those extensions, and for a sparse bundle or AFD folder chosen with
its folder button. See `admin/docs/raw_image_input.md`.
An encrypted image opens with its password (`--image_password_file` or
`--image_password_env`), or, when it is sealed to a certificate, with that certificate's
RSA private key (`--image_private_key`). A BitLocker volume in an image opens with its
password or recovery password, given the same way, or its startup key
(`--bitlocker_key`, repeatable), an APFS volume macOS encrypted in software with its
password or personal recovery key, and a LUKS container with its passphrase, each given
the same way. At a terminal whatever is missing is asked for, and the GUI asks in dialogs;
a BitLocker, APFS or LUKS volume nothing opens is reported and not searched.
The disk images of a Linux software RAID set (md, or LVM2 across disks) are read
together: give them all to `-i` with `-t raw`, or pick them together in the GUI's file
dialog. Given one image that holds a member, the other members are looked for in its
folder by what each file records about itself, not by its name; the command line lists
what it found and what it left out and why before reading the set (`--no-find-members`
reads only the image given), and the GUI asks before reading files it found. The report
names every image read and marks the ones found automatically. One image that holds an
md member is read with its arrays too: a lone RAID1 member with metadata 1.1 or 1.2
now reads its filesystem through the array, and its volume names gain the image's or
the array's name in front. One disk given twice is read once. An image in which no
RAID metadata is found is read as before; see `admin/docs/raw_image_input.md` for what
qnxprobe 1.71 does with DDF, IMSM and md member images read alone.
`tar` also reads an xz-compressed tar (`.tar.xz`), and the GUI picks `tar` for that
extension. A compressed tar, `.tar.gz` included, is decompressed once into the report folder
before any file is read, so the run needs free space there for the uncompressed tar. The
copy is deleted when the run ends, and the run log says how long the step took.
`-m <profile>` runs only the artifacts listed in a DLEAPP profile file, and `-c <folder>`
creates one. Profiles are saved as `.dlprofile`. Profiles saved as `.rlprofile` by
v2026.4.1 and earlier still load, in the CLI and in the GUI.
### GUI
```
$ python dleappGUI.py
```
### Help
```
$ python dleapp.py --help
```
### Building the binaries
`packaging/build.py` builds `dleapp` with PyInstaller for the machine it runs on, from the
same virtual environment. Fetch the Unified Log parser first, or the build ships without
native Unified Log support:
```
python admin/scripts/fetch_unifiedlog_iterator.py # bin/unifiedlog_iterator, digest-verified
python packaging/build.py exe # dist/DLEAPP/, and dist/DLEAPP.app on macOS
python packaging/build.py smoke # run what it built, without opening a window
python packaging/build.py installer # Windows: Inno Setup installer; macOS: .dmg; Linux: AppImage
```
`exe --onefile` makes `dist/dleapp` (`dist\dleapp.exe` on Windows) as a single file
instead. The Windows installer needs [Inno Setup](https://jrsoftware.org/isdl.php); on
Linux, `smoke` needs a display, which `xvfb-run` provides. `python packaging/build.py --help`
has the rest.
## Contributing artifact plugins
Artifact modules live in `scripts/artifacts/` and are loaded each time DLEAPP runs.
**New modules:** start with [How to Write an iLEAPP Module](https://leapps.org/blog-post?post=2026-06-14-how-to-write-an-ileapp-module). It uses iLEAPP as its reference, and DLEAPP modules use the same `__artifacts_v2__` block and `@artifact_processor` decorator. The helpers are not identical across the tools, so check that one exists in DLEAPP's `scripts/ilapfuncs.py` before you import it.
The helper functions a module calls to find files, read SQLite, check in media and convert timestamps are described in [Helper Functions for Artifact Modules](admin/docs/helper_functions.md).
A module has two parts: an `__artifacts_v2__` dictionary at the top of the file, and one function per artifact decorated with `@artifact_processor`. For example:
```python
__artifacts_v2__ = {
"get_cool_messages": {
"name": "Cool App Messages",
"description": "Messages from the Cool App database",
"author": "@username",
"creation_date": "2026-10-14",
"last_update_date": "2026-10-14",
"requirements": "none",
"category": "Cool App",
"notes": "",
"paths": ('*/CoolApp/cool.db*',),
"output_types": "standard",
"artifact_icon": "message",
}
}
from scripts.ilapfuncs import (
artifact_processor, convert_unix_ts_to_utc, get_file_path, get_sqlite_db_records)
@artifact_processor
def get_cool_messages(context):
source_path = get_file_path(context.get_files_found(), 'cool.db')
if not source_path:
return (), [], ''
query = 'SELECT sent_at, sender, body FROM messages'
data_list = []
for row in get_sqlite_db_records(source_path, query):
data_list.append((convert_unix_ts_to_utc(row[0]), row[1], row[2]))
data_headers = (('Sent', 'datetime'), 'Sender', 'Message')
return data_headers, data_list, source_path
```
The key of each entry (`get_cool_messages` above) must match the name of its decorated function. That is how the loader and the decorator find each other. The entry holds:
- `name`: the artifact name shown in the report. It must be unique within DLEAPP; the loader stops on a duplicate.
- `description`, `author`, `notes`: text about the artifact. `notes` can be empty.
- `creation_date`, `last_update_date`: dates in `YYYY-MM-DD` form. Both are written to the LAVA output. Bump `last_update_date` when you change the module.
- `requirements`: a note on anything the artifact needs, or `"none"`.
- `category`: groups artifacts in the report.
- `paths`: a tuple of patterns for the files the artifact reads. They are matched with Python's `fnmatch`, so `*` can cross `/`.
- `output_types`: `"standard"` (every output except KML), `"all"`, or a list taken from `html`, `tsv`, `timeline`, `lava` and `kml`.
- `artifact_icon`: a Tabler icon name that appears in `scripts/_elements/tabler-icons.css`.
Optional keys:
- `html_columns`: columns written to the HTML report without escaping. Pass any value that comes from the evidence through the helpers in `scripts/html_safe.py`.
- `data_views`: alternate LAVA views, such as a conversation view for message artifacts. Column order for those is in [Conversation Column Order](admin/docs/conversation_column_order.md).
- `sample_data`: a mapping of test corpus name to a short note about what that corpus produced, for example `{"discord_macos": "Discord 0.0.402 macOS | 12940 rows"}`. The artifact processor ignores it; it records where the artifact has been run. See [Test corpora and `sample_data`](#test-corpora-and-sample_data).
The function takes one argument, `context`, which gives it the files its `paths` matched (`context.get_files_found()`) and the rest of the run. It returns three things: the column headers, a list of row tuples, and the path of the file the rows came from. The decorator writes the HTML, TSV, timeline, KML and LAVA output from them, as `output_types` asks. An empty list writes no table.
A header can be a tuple that names a column type: `('Sent', 'datetime')`, `('Day', 'date')`, `('Number', 'phonenumber')` or `('Photo', 'media')`. A plain string is a text column.
### Test corpora and `sample_data`
Corpora live outside this repository, because sample images are usually private. A corpus directory carries a `samples.json` registry:
```json
{
"version": 1,
"samples": {
"corpus_name": {
"match": { "zip": "relative/path.zip", "sha256": "..." },
"platform": "macos",
"os_version": "macOS 26.5.2 (build 25F84)",
"app_versions": { "discord": "0.0.402" },
"notes": "how the capture was made and what it is good for"
}
}
}
```
The keys in that registry are what artifacts cite in `sample_data`. `admin/scripts/validate_sample_data.py` keeps the two in step:
```
python3 admin/scripts/validate_sample_data.py # structure only
python3 admin/scripts/validate_sample_data.py --registry <path>/samples.json # + keys resolve, corpora present
python3 admin/scripts/validate_sample_data.py --registry <path> --verify-hashes
python3 admin/scripts/validate_sample_data.py --registry <path> --run <corpus> # + re-parse and diff row counts
```
The structural check needs no test data and runs in CI on every pull request. The registry and row-count checks need the images, so run those locally before changing a parser's output.
### Output regression tests
`sample_data` records how many rows an artifact produced. To catch a change that
keeps the count and alters the values, record a fingerprint of a corpus and
compare against it later:
```
python3 admin/test/scripts/make_test_data.py --registry <path> --corpus <key>
python3 admin/test/scripts/test_module_output.py --registry <path> --corpus <key>
python3 admin/test/scripts/test_module_output.py --registry <path> --all
```
Encrypted corpora take their secret the same way a normal run does, and
`--secret signal` with no value prompts without echo:
```
python3 admin/test/scripts/test_module_output.py --registry <path> \
--corpus signal_macos_needed --secret signal
```
Baselines live in `admin/test/results/<corpus>.json` and are committed. They
hold row counts, the column list, per-column digests and how many values were
populated — **never rows**, because the corpora are private application
profiles. A digest still changes when any value does, so the regression is
caught without the baseline carrying anyone's messages.
These need the corpora, so they run locally rather than in CI.
For example:
```python
__artifacts_v2__ = {
"cool_artifact_1": {
"name": "Cool Artifact 1",
"description": "Extracts cool data from database files",
"author": "@username",
"version": "0.1",
"date": "2022-10-25",
"requirements": "none",
"category": "Really cool artifacts",
"notes": "",
"paths": ('*/com.android.cooldata/databases/database*.db',),
"function": "get_cool_data1"
},
"cool_artifact_2": {
"name": "Cool Artifact 2",
"description": "Extracts cool data from XML files",
"author": "@username",
"version": "0.1",
"date": "2022-10-25",
"requirements": "none",
"category": "Really cool artifacts",
"notes": "",
"paths": ('*/com.android.cooldata/files/cool.xml',),
"function": "get_cool_data2"
}
}
```
The functions referenced as entry points in the `__artifacts__` dictionary must take the following arguments:
* An iterable of the files found which are to be processed (as strings)
* The path of DLEAPP's output folder(as a string)
* The seeker (of type FileSeekerBase) which found the files
* A Boolean value indicating whether or not the plugin is expected to wrap text
For example:
```python
def get_cool_data1(files_found, report_folder, seeker, wrap_text):
pass # do processing here
```
Plugins are generally expected to provide output in DLEAPP's HTML output format, TSV, and optionally submit records to
the timeline. Functions for generating this output can be found in the `artifact_report` and `ilapfuncs` modules.
At a high level, an example might resemble:
```python
__artifacts_v2__ = {
"cool_artifact_1": {
"name": "Cool Artifact 1",
"description": "Extracts cool data from database files",
"author": "@username", # Replace with the actual author's username or name
"version": "0.1", # Version number
"date": "2022-10-25", # Date of the latest version
"requirements": "none",
"category": "Really cool artifacts",
"notes": "",
"paths": ('*/com.android.cooldata/databases/database*.db',),
"function": "get_cool_data1"
}
}
import datetime
from scripts.artifact_report import ArtifactHtmlReport
import scripts.ilapfuncs
def get_cool_data1(files_found, report_folder, seeker, wrap_text):
# let's pretend we actually got this data from somewhere:
rows = [
(datetime.datetime.now(), "Cool data col 1, value 1", "Cool data col 1, value 2", "Cool data col 1, value 3"),
(datetime.datetime.now(), "Cool data col 2, value 1", "Cool data col 2, value 2", "Cool data col 2, value 3"),
]
headers = ["Timestamp", "Data 1", "Data 2", "Data 3"]
# HTML output:
report = ArtifactHtmlReport("Cool stuff")
report_name = "Cool DFIR Data"
report.start_artifact_report(report_folder, report_name)
report.add_script()
report.write_artifact_data_table(headers, rows, files_found[0]) # assuming only the first file was processed
report.end_artifact_report()
# TSV output:
scripts.ilapfuncs.tsv(report_folder, headers, rows, report_name, files_found[0]) # assuming first file only
# Timeline:
scripts.ilapfuncs.timeline(report_folder, report_name, rows, headers)
```
## Test data and sample_data for your PR
A PR that adds or changes an artifact is easiest to review and merge when it arrives with
two things: a small test fixture cut from a real extraction, and `sample_data` values that
record what the module produced. Scripts generate both. Here is the whole flow.
One rule before anything else: whatever you commit here becomes public. Only use data you
are allowed to share, like a test device you populated yourself, a public research image,
or a file you sanitized by hand. Never casework.
**1. Cut a fixture from your extraction**
```
python admin/test/scripts/make_test_data.py <module> --case 1 --input <extraction.zip>
```
This pulls the files your module's `paths` patterns match out of the extraction and writes
the case file `admin/test/cases/testdata.<module>.json` plus one small zip per artifact
under `admin/test/cases/data/<module>/`.
Size rules: under 10 MB per zip, commit it with the PR. Between 10 and 25 MB, commit the
case file and attach the zip to a PR comment. Bigger than that, say so in the PR and a
maintainer will arrange a handoff.
**2. Record the expected output**
```
TZ=UTC python admin/test/scripts/test_module.py <module> -a all -c all
```
This runs the module against the fixture and writes a snapshot of the output under
`admin/test/results/<module>/`. Commit the snapshot too. It becomes the baseline that
guards the module after merge. Keep the `TZ=UTC` part: the committed snapshots are UTC
and CI runs UTC.
**3. Run the same comparison CI will run**
```
python admin/test/scripts/run_test_cases.py --module <module>
```
**4. Generate the sample_data values**
```
python admin/scripts/validate_sample_data.py --emit <extraction.zip> --key <image_name>
```
This runs DLEAPP end to end on your extraction and prints ready-to-paste `sample_data`
blocks for the modules changed on your branch. Paste them into your module's
`__artifacts_v2__` and add the app name and version you saw on the image. If a count is
zero, check the source file really is empty before recording it.
**5. Commit it all and open the PR**
Commit the module, the case file, the fixture zips, and the recorded snapshot together.
More detail lives in
[admin/docs/testing/create_module_test_cases.md](admin/docs/testing/create_module_test_cases.md).
If your extraction cannot be shared, open the PR anyway and say so. A fixture can often be
cut from a public research image instead, or the real file can be sanitized by hand. The
review does not stop while we work that out.
## Code signing policy
Free code signing provided by [SignPath.io](https://about.signpath.io/), certificate by
[SignPath Foundation](https://signpath.org/).
The Windows builds are not signed yet. DLEAPP is applying to SignPath Foundation's free code
signing program for open source projects, and this policy applies to every Windows release
signed under it.
The Windows executables attached to
[GitHub Releases](https://github.com/abrignoni/DLEAPP/releases) are built from this
repository by GitHub Actions, on GitHub-hosted runners
([`release.yml`](.github/workflows/release.yml)). Under this policy, SignPath signs only
what that workflow built. The macOS disk images are signed separately, with an Apple
Developer ID, and notarised by Apple.
SignPath signs `dleapp.exe`, the single-file program in the portable zip. Third-party files
packed inside it, such as Mandiant's Unified Log parser (`unifiedlog_iterator.exe`), are not
signed on their own.
### Team roles
- Committers and reviewers: [@abrignoni](https://github.com/abrignoni),
[@JamesHabben](https://github.com/JamesHabben),
[@Johann-PLW](https://github.com/Johann-PLW), [@stark4n6](https://github.com/stark4n6)
- Approvers: [@abrignoni](https://github.com/abrignoni),
[@Johann-PLW](https://github.com/Johann-PLW)
Changes proposed by people who are not committers are reviewed by a committer before they
are merged. Every release signing request is approved by an approver.
### Privacy policy
DLEAPP processes extractions locally, on the machine it runs on. This program will not
transfer any information to other networked systems unless specifically requested by the
user or the person installing or operating it.
The same policy covers the other LEAPPs:
[leapps.org/releases#code-signing-policy](https://leapps.org/releases#code-signing-policy).
## Licence
DLEAPP's code is under the MIT licence (`LICENSE`). To show HEIC images the packaged programs on
the releases page include heicreader, which is MIT and built from MIT and BSD-3-Clause code. Its
licence texts are in [`LICENSES/`](LICENSES/THIRD-PARTY-NOTICES.md). Every packaged program also
carries, in `LICENSES/bundled/`, the licence of each Python package it holds and of each library it takes from the build machine, and names the ones
under copyleft terms, such as simplekml (LGPL), with a link to their source.
## Acknowledgements
This tool is the result of a collaborative effort of many people in the DFIR community.
DLEAPP logo courtesy of Kevin Pagano.
The earlier DLEAPP logo artwork was by Johann Polewczyk, with the per-OS window
controls (Linux, Windows, macOS) suggested by James Habben.
DLEAPP is built on the RLEAPP framework by Alexis Brignoni and contributors.
Apple Unified Log `.tracev3` data is read with the `unifiedlog_iterator` binary from
Mandiant's [macos-UnifiedLogs](https://github.com/mandiant/macos-UnifiedLogs), licensed under
Apache-2.0. Builds that include it carry its license and the notices for the Rust crates
it links; see `bin/PROVENANCE.md`.