ALEAPP

Android Logs Events And Protobuf Parser

If you want to contribute hit me up here: https://abrignoni.github.io

Blog posts here: https://leapps.org/blog

Download

Pre-built releases need no Python installation: ALEAPP GitHub Releases, or LEAPPs Releases for the whole LEAPP family.

Platform	Download
Windows (Intel/AMD)	`ALEAPP--windows-x64-setup.exe` (installer) or `ALEAPP--windows-x64-portable.zip`
Windows (ARM)	`ALEAPP--windows-arm64-setup.exe` or `ALEAPP--windows-arm64-portable.zip`
macOS (Apple Silicon)	`ALEAPP-*-macos-arm64.dmg`
macOS (Intel)	`ALEAPP-*-macos-x64.dmg`
Linux (Intel/AMD)	`ALEAPP-*-linux-x64.AppImage`
Linux (ARM)	`ALEAPP-*-linux-arm64.AppImage`

Each download holds one program, aleapp. SHA256SUMS.txt in each release lets you check a download.

GUI: open ALEAPP the usual way: from the Start menu after installing on Windows, by double-clicking aleapp.exe in the portable folder, ALEAPP in Applications on macOS, or the AppImage on Linux. Started without arguments, it opens the window.

CLI: give aleapp arguments in a terminal and it runs as a command line instead. The output folder must already exist. On Windows, keep aleapp.exe in its folder with the files beside it.

aleapp.exe -t zip -i C:\path\to\extraction.zip -o C:\path\to\output\

On Linux, run the AppImage with the same arguments. On macOS it is inside the app; to type just aleapp in a terminal, link it onto your PATH once:

sudo ln -s /Applications/ALEAPP.app/Contents/MacOS/aleapp /usr/local/bin/aleapp

Requirements

Python 3.10 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

For the exact mister_skinnylegs dependency chain the releases are built with, install requirements-msl-lock.txt over that, without dependencies:

pip3 install --no-deps -r requirements-msl-lock.txt

To run on Linux, you will also need to install tkinter separately like so:

sudo apt-get install python3-tk

Building the binaries

packaging/build.py builds aleapp with PyInstaller for the machine it runs on, from the same virtual environment. It installs requirements.txt, the pinned build tools and requirements-msl-lock.txt first.

python packaging/build.py exe          # dist/ALEAPP/, and dist/ALEAPP.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/aleapp (dist\aleapp.exe on Windows) as a single file instead. The Windows installer needs Inno Setup; on Linux, smoke needs a display, which xvfb-run provides. python packaging/build.py --help has the rest.

Usage

CLI

$ python aleapp.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, 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), and an APFS volume macOS encrypted in software with its password or personal recovery key, given the same way. At a terminal whatever is missing is asked for, and the GUI asks in dialogs; a BitLocker or APFS volume nothing opens is reported and not searched.

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.

GUI

$ python aleappGUI.py

Help

$ python aleapp.py --help

Contributing artifact plugins

Each plugin is a Python source file which should be added to the scripts/artifacts folder which will be loaded dynamically each time ALEAPP is run.

The plugin source file must contain a dictionary named __artifacts_v2__ at the very beginning of the module, which defines the artifacts that the plugin processes. The keys in the __artifacts_v2__ dictionary should be IDs for the artifact(s) which must be unique within ALEAPP. The values should be dictionaries containing the following keys:

name: The name of the artifact as a string.
description: A description of the artifact as a string.
author: The author of the plugin as a string.
version: The version of the artifact as a string.
date: The date of the last update to the artifact as a string.
requirements: Any requirements for processing the artifact as a string.
category: The category of the artifact as a string.
notes: Any additional notes as a string.
paths: A tuple of strings containing glob search patterns to match the path of the data that the plugin expects for the artifact.
function: The name of the function which is the entry point for the artifact's processing as a string.

For example:

__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:

ALEAPP v2026.3.3