Назад к обновлениям
New releaseSep 11, 2026

ALEAPP v2026.3.3

Парсер журналов Android, событий и Protobuf

Поделиться

ALEAPP

Android Logs Events And Protobuf Parser

Если вы хотите внести свой вклад, свяжитесь со мной здесь: https://abrignoni.github.io

Записи в блоге здесь: https://leapps.org/blog

Требования

Python 3.10 или выше

Зависимости

Зависимости для вашего окружения Python перечислены в requirements.txt. Установите их с помощью приведённой ниже команды. Убедитесь, что часть py корректна для вашего окружения, например py, python или python3 и т. д.

py -m pip install -r requirements.txt или pip3 install -r requirements.txt

Для запуска на Linux вам также потребуется отдельно установить tkinter следующим образом:

sudo apt-get install python3-tk

Компиляция в исполняемый файл

Чтобы скомпилировать в исполняемый файл и запускать эту программу на системе без установленного Python.

ОС Windows

Чтобы создать aleapp.exe, выполните:

pyinstaller scripts\pyinstaller\aleapp.spec

Чтобы создать aleappGUI.exe, выполните:

pyinstaller scripts\pyinstaller\aleappGUI.spec

macOS

Чтобы создать aleapp, выполните:

pyinstaller scripts/pyinstaller/aleapp_macOS.spec

Чтобы создать aleappGUI.app, выполните:

pyinstaller scripts/pyinstaller/aleappGUI_macOS.spec

Linux

Чтобы создать aleapp, выполните:

pyinstaller scripts/pyinstaller/aleapp_Linux.spec

Чтобы создать aleappGUI, выполните:

pyinstaller scripts/pyinstaller/aleappGUI_Linux.spec

Использование

CLI

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

GUI

$ python aleappGUI.py

Справка

$ python aleapp.py --help

Создание плагинов артефактов

Каждый плагин — это исходный файл Python, который следует добавить в папку scripts/artifacts; он будет загружаться динамически при каждом запуске ALEAPP.

Исходный файл плагина должен содержать словарь с именем __artifacts_v2__ в самом начале модуля, который определяет артефакты, обрабатываемые плагином. Ключи в словаре __artifacts_v2__ должны быть идентификаторами артефакта(ов), уникальными в рамках ALEAPP. Значения должны быть словарями, содержащими следующие ключи:

  • name: название артефакта в виде строки.
  • description: описание артефакта в виде строки.
  • author: автор плагина в виде строки.
  • version: версия артефакта в виде строки.
  • date: дата последнего обновления артефакта в виде строки.
  • requirements: любые требования для обработки артефакта в виде строки.
  • category: категория артефакта в виде строки.
  • notes: любые дополнительные примечания в виде строки.
  • paths: кортеж строк, содержащих шаблоны поиска glob для сопоставления с путём данных, которые ожидает плагин для данного артефакта.
  • function: имя функции, которая является точкой входа для обработки артефакта, в виде строки.

Например:

__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"
    }
}

Функции, указанные как точки входа в словаре __artifacts__, должны принимать следующие аргументы:

  • Итерируемый объект найденных файлов, подлежащих обработке (в виде строк)
  • Путь к выходной папке ALEAPP (в виде строки)
  • Объект seeker (типа FileSeekerBase), который нашёл файлы
  • Логическое значение, указывающее, ожидается ли от плагина перенос текста

Например:

def get_cool_data1(files_found, report_folder, seeker, wrap_text):
    pass  # do processing here

Ожидается, что плагины предоставляют вывод в формате HTML-отчёта ALEAPP, TSV и, при необходимости, отправляют записи в таймлайн. Функции для генерации такого вывода можно найти в модулях artifact_report и ilapfuncs. На высоком уровне пример может выглядеть так:

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

Тестовые данные и sample_data для вашего PR

PR, который добавляет или изменяет артефакт, проще всего рецензировать и объединять, если он сопровождается двумя вещами: небольшим тестовым фикстуром, вырезанным из реальной выгрузки, и значениями sample_data, фиксирующими результат работы модуля. Скрипты генерируют и то, и другое. Вот весь процесс.

Одно правило прежде всего: всё, что вы коммитите сюда, становится публичным. Используйте только те данные, которыми вам разрешено делиться, например тестовое устройство, заполненное вами самостоятельно, публичный исследовательский образ или файл, вручную очищенный вами. Никогда не используйте материалы реальных расследований.

1. Вырежьте фикстур из вашей выгрузки

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

Эта команда извлекает файлы, соответствующие шаблонам paths вашего модуля, из выгрузки и записывает файл кейса admin/test/cases/testdata.<module>.json, а также по одному небольшому zip-архиву на артефакт в admin/test/cases/data/<module>/.

Правила по размеру: менее 10 МБ на zip — коммитьте вместе с PR. От 10 до 25 МБ — коммитьте файл кейса и прикрепите zip к комментарию в PR. Больше этого — сообщите об этом в PR, и мейнтейнер организует передачу.

2. Зафиксируйте ожидаемый вывод

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

Эта команда запускает модуль на фикстуре и записывает снимок вывода в admin/test/results/<module>/. Коммитьте и снимок тоже. Он станет базовым эталоном, защищающим модуль после объединения. Сохраняйте часть TZ=UTC: закоммиченные снимки имеют формат UTC, и CI также работает в UTC.

3. Запустите то же сравнение, которое запустит CI

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

4. Сгенерируйте значения sample_data

python admin/scripts/validate_sample_data.py --emit <extraction.zip> --key <image_name>

Эта команда запускает ALEAPP целиком на вашей выгрузке и выводит готовые к вставке блоки sample_data для модулей, изменённых в вашей ветке. Вставьте их в __artifacts_v2__ вашего модуля и добавьте название приложения и версию, которые вы видели на образе. Если счётчик равен нулю, проверьте, что исходный файл действительно пуст, прежде чем фиксировать это.

5. Закоммитьте всё и откройте PR

Коммитьте модуль, файл кейса, zip-архивы фикстуров и записанный снимок вместе. Более подробная информация приведена в admin/docs/testing/create_module_test_cases.md.

Если вашу выгрузку нельзя публиковать, всё равно откройте PR и сообщите об этом. Фикстур часто можно вырезать из публичного исследовательского образа, либо реальный файл можно очистить вручную. Рецензирование не останавливается, пока мы это решаем.

Благодарности

Этот инструмент — результат совместных усилий многих людей из сообщества DFIR.

Логотип ALEAPP предоставлен Derek Eiri.

Читать далее

Категории

Мобильная криминалистикаЦифровая криминалистикаРеагирование на ИнцидентыАнализ Журналов