ALEAPP

Android 日志、事件与 Protobuf 解析器

如果你想贡献代码，请在此联系我：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 <提取路径> -o <报告输出路径>

图形界面（GUI）

$ python aleappGUI.py

帮助

$ python aleapp.py --help

贡献工件插件

每个插件都是一个 Python 源文件，应添加到 scripts/artifacts 文件夹中，该文件夹将在每次运行 ALEAPP 时动态加载。

插件源文件必须在模块的最开头包含一个名为 __artifacts_v2__ 的字典，该字典定义了插件处理的工件。__artifacts_v2__ 字典中的键应为工件的 ID，且必须在 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

插件通常预期以 ALEAPP 的 HTML 输出格式、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)

为你的 PR 提供测试数据和 sample_data

添加或更改工件的 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，同时在 admin/test/cases/data/<module>/ 下为每个工件生成一个小型 zip 文件。

大小规则：每个 zip 小于 10 MB，随 PR 一起提交。介于 10 到 25 MB 之间，提交案件文件并将 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 提供。