ALEAPP: parsing Android logs, events and protobuf files for forensics

What ALEAPP parses, and who actually needs it

An Android extraction is a filesystem, not a report. App data sits in SQLite databases, XML preferences, protobuf blobs and log files scattered under package directories, and the interesting records are usually a few rows inside a file nobody wants to open by hand. ALEAPP exists to walk that extraction, match files against known patterns, and emit something an examiner can read. The README describes it as the Android Logs Events And Protobuf Parser, which names the three data shapes it targets.

The audience is narrow on purpose. ALEAPP is for someone holding an extraction and asking what an app stored, when, and in which file. It is not an acquisition tool, not a live device agent, and not a general file browser. If you do not already have the filesystem data, ALEAPP has nothing to chew on. That constraint is visible in the CLI, which takes a type flag and a path to an extraction rather than a device identifier.

How the plugin loader and artifact dictionary work

ALEAPP loads artifacts dynamically. Every Python file in scripts/artifacts is read at startup, and each one declares a dictionary named __artifacts_v2__ at the top of the module. The keys are artifact IDs, and the README states they must be unique within ALEAPP. Each value carries name, description, author, version, date, requirements, category, notes, a tuple of glob patterns in paths, and the name of the entry function.

The glob tuple is the mechanism that ties a plugin to data. ALEAPP searches the extraction for files matching those patterns and hands the matches to the function named in the same dictionary entry. The function signature is fixed: an iterable of found file paths, the output folder, the seeker object that found them, and a boolean for whether text should be wrapped.

That design is the whole architecture. There is no central registry to edit and no import list to maintain, so adding an app means dropping a file into scripts/artifacts. The trade-off is that a malformed dictionary or a duplicated ID fails at load time rather than at review time, and the README gives no schema validator beyond the description of the keys.

Installing ALEAPP and running a first extraction

ALEAPP needs Python 3.10 or above. Dependencies live in requirements.txt and install with pip. The README notes the py part of the command must match your environment, so py, python or python3 all appear as options.

py -m pip install -r requirements.txt

On Linux the README adds one extra step, because tkinter is not bundled with every Python build and the GUI needs it.

sudo apt-get install python3-tk

The command line entry point takes a type flag, an input path and an output path. The README shows the four accepted types: zip, tar, fs and gz.

python aleapp.py -t <zip | tar | fs | gz> -i <path_to_extraction> -o <path_for_report_output>

After the run, the output folder holds the report. The README does not enumerate the report contents in the section shown, but it does state that plugins generally produce HTML and TSV, with optional records submitted to the timeline. If you prefer a window over a terminal, the GUI starts with the second entry script.

python aleappGUI.py

To see every flag the CLI accepts, the README points at the help output.

python aleapp.py --help

One dependency note matters before you install anything else. The requirements file carries an explicit warning: do not pip install the PyPI blackboxprotobuf package into this environment, because it force-downgrades protobuf to 3.10.0 and reintroduces patched CVEs. ALEAPP uses a vendored copy under scripts/blackboxprotobuf instead.

Building a standalone binary, and where that path gets awkward

For machines without Python, the README documents PyInstaller specs per platform. Windows builds two executables, macOS builds a binary and an app bundle, and Linux builds a binary and a GUI binary. The spec files live under scripts/pyinstaller.

pyinstaller scripts\pyinstaller\aleapp.spec

pyinstaller scripts/pyinstaller/aleapp_macOS.spec

pyinstaller scripts/pyinstaller/aleapp_Linux.spec

This is the part of the project with the least room for improvisation. PyInstaller builds are tied to the environment that produced them, and the README gives no version pins for PyInstaller itself, only the spec paths. Nothing in the shown documentation covers signing, notarisation or how a frozen build resolves the vendored protobuf directory at runtime. If you need a reproducible binary for a lab, treat the spec files as a starting point and verify the frozen output against the same extraction you tested with the source install.

The test fixture workflow is the real contribution gate

The README spends more words on contributing artifacts than on using the tool, and the reason is sound: an artifact change is only reviewable if it ships with data that proves it works. The flow has five steps, and each one has a script.

python admin/test/scripts/make_test_data.py <module> --case 1 --input <extraction.zip>

That command cuts the files matching your module's paths patterns out of an extraction and writes a case file plus one small zip per artifact under admin/test/cases/data. Size rules are explicit: under 10 MB commits with the PR, between 10 and 25 MB commits the case file and attaches the zip to a PR comment, and anything larger needs a maintainer to arrange a handoff.

The next step records expected output, and the timezone matters.

TZ=UTC python admin/test/scripts/test_module.py <module> -a all -c all

The README states that committed snapshots are UTC and CI runs UTC, so dropping the TZ=UTC prefix produces a snapshot that will not match. The third command runs the same comparison CI runs.

python admin/test/scripts/run_test_cases.py --module <module>

Finally, sample_data values are generated by running ALEAPP end to end on the extraction and printing paste-ready blocks for the changed modules. The README adds a check worth repeating: if a count is zero, confirm the source file really is empty before recording it. And one rule sits above all of it. Whatever you commit becomes public, so use a device you populated yourself, a public research image, or a hand-sanitised file. Never casework.

Where ALEAPP stops, and what iLEAPP does differently

ALEAPP parses Android extractions. iLEAPP, from the same author and surfaced repeatedly in related searches, is the iOS counterpart. The difference is not a feature gap but a data model gap. Android artifacts live in package-scoped directories with SQLite and protobuf files, which is why ALEAPP's plugin contract centres on glob patterns and a protobuf parser. iOS artifacts come from a different filesystem layout and a different set of databases, so an iLEAPP artifact and an ALEAPP artifact are not interchangeable even when they describe the same app concept.

The practical consequence: if your case is an iPhone backup, ALEAPP is the wrong tool, and if your case is an Android extraction, iLEAPP is. The two are siblings, not alternatives to each other.

A second boundary is acquisition. Neither tool produces the extraction. ALEAPP's CLI takes a path to data that already exists, so a workflow that starts with ALEAPP has a step before it that the README does not describe. Teams that assume otherwise will install the tool, point it at a device, and find nothing to point at.

Maintenance, licensing and the cost of keeping up

The repository is not archived, and the last push was on 2026-08-27, which is recent. Three releases landed in August 2026: v2026.3.0 on 2026-08-14, v2026.3.1 on 2026-08-18, and v2026.3.2 on 2026-08-27. That cadence suggests artifacts are being added or corrected regularly, which is what you want from a parser whose value depends on matching app versions.

The licence is MIT, which permits commercial and internal forensic use with the usual requirement to preserve the copyright notice. That is a statement about the licence text, not legal advice; if you redistribute ALEAPP inside a product, read the LICENSE file in the repository rather than this paragraph.

Upgrade cost is where the real work sits. Because artifacts are loaded dynamically from scripts/artifacts, a new release can change parsing behaviour for an app you already rely on without any change to the CLI. The test infrastructure exists precisely for that: run_test_cases.py compares module output against committed snapshots, and those snapshots are the baseline that guards the module after merge. If you maintain private artifacts, pinning a version and diffing your own snapshots against a new release is cheaper than discovering a changed column in the middle of a case. The requirements file is also worth reading on every upgrade, since the protobuf pin and the vendored blackboxprotobuf copy are deliberate choices rather than incidental ones.

Editorial conclusion

ALEAPP fits examiners who already have an Android extraction in zip, tar, fs or gz form and need app-level artifacts in a readable report. It does not fit anyone looking for a one-click phone acquisition tool: ALEAPP parses an extraction, it does not create one, and the README points to no acquisition step. Before relying on it, confirm two things on your own image: that the artifact plugins you need match the apps actually present, and that the version you install parses a small test extraction end to end. Check the vendored protobuf path in scripts/blackboxprotobuf before adding any dependency that touches protobuf.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes