Android Logs Events And Protobuf Parser

Wenn du einen Beitrag leisten möchtest, melde dich hier: https://abrignoni.github.io

Blogbeiträge hier: https://leapps.org/blog

Anforderungen

Python 3.10 oder höher

Abhängigkeiten

Die Abhängigkeiten für deine Python-Umgebung sind in requirements.txt aufgelistet. Installiere sie mit dem folgenden Befehl. Stelle sicher, dass der py-Teil für deine Umgebung korrekt ist, z. B. py, python oder python3 usw.

py -m pip install -r requirements.txt oder pip3 install -r requirements.txt

Zum Ausführen unter Linux musst du zusätzlich tkinter separat installieren:

sudo apt-get install python3-tk

In eine ausführbare Datei kompilieren

Zum Kompilieren in eine ausführbare Datei, damit du dieses Tool auf einem System ohne installiertes Python ausführen kannst.

Windows-Betriebssystem

Um aleapp.exe zu erstellen, führe Folgendes aus:

pyinstaller scripts\pyinstaller\aleapp.spec

Um aleappGUI.exe zu erstellen, führe Folgendes aus:

pyinstaller scripts\pyinstaller\aleappGUI.spec

macOS

Um aleapp zu erstellen, führe Folgendes aus:

pyinstaller scripts/pyinstaller/aleapp_macOS.spec

Um aleappGUI.app zu erstellen, führe Folgendes aus:

pyinstaller scripts/pyinstaller/aleappGUI_macOS.spec

Linux

Um aleapp zu erstellen, führe Folgendes aus:

pyinstaller scripts/pyinstaller/aleapp_Linux.spec

Um aleappGUI zu erstellen, führe Folgendes aus:

pyinstaller scripts/pyinstaller/aleappGUI_Linux.spec

Verwendung

CLI

$ python aleapp.py -t <zip | tar | fs | gz> -i <Pfad_zur_Extraktion> -o <Pfad_für_den_Berichtsausgabeordner>

GUI

$ python aleappGUI.py

Hilfe

$ python aleapp.py --help

Beitrag durch Artefakt-Plugins

Jedes Plugin ist eine Python-Quelldatei, die dem Ordner scripts/artifacts hinzugefügt werden sollte und bei jedem ALEAPP-Lauf dynamisch geladen wird.

Die Plugin-Quelldatei muss ganz am Anfang des Moduls ein Wörterbuch namens __artifacts_v2__ enthalten, das die Artefakte definiert, die das Plugin verarbeitet. Die Schlüssel im __artifacts_v2__-Wörterbuch sollten IDs für das/die Artefakt(e) sein, die innerhalb von ALEAPP eindeutig sein müssen. Die Werte sollten Wörterbücher sein, die die folgenden Schlüssel enthalten:

• name: Der Name des Artefakts als Zeichenkette.
• description: Eine Beschreibung des Artefakts als Zeichenkette.
• author: Der Autor des Plugins als Zeichenkette.
• version: Die Version des Artefakts als Zeichenkette.
• date: Das Datum der letzten Aktualisierung des Artefakts als Zeichenkette.
• requirements: Alle Anforderungen zur Verarbeitung des Artefakts als Zeichenkette.
• category: Die Kategorie des Artefakts als Zeichenkette.
• notes: Zusätzliche Hinweise als Zeichenkette.
• paths: Ein Tupel von Zeichenketten mit Glob-Suchmustern, um den Pfad der Daten abzugleichen, die das Plugin für das Artefakt erwartet.
• function: Der Name der Funktion, die den Einstiegspunkt für die Verarbeitung des Artefakts darstellt, als Zeichenkette.

Zum Beispiel:

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

Die Funktionen, die im __artifacts__-Wörterbuch als Einstiegspunkte referenziert werden, müssen die folgenden Argumente annehmen:

• Ein iterierbares Objekt der gefundenen Dateien, die verarbeitet werden sollen (als Zeichenketten)
• Der Pfad des ALEAPP-Ausgabeordners (als Zeichenkette)
• Der Seeker (vom Typ FileSeekerBase), der die Dateien gefunden hat
• Ein boolescher Wert, der angibt, ob das Plugin Text umbrechen soll

Zum Beispiel:

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

Von Plugins wird allgemein erwartet, dass sie Ausgaben im ALEAPP-HTML-Ausgabeformat, TSV und optional Datensätze für die Zeitleiste bereitstellen. Funktionen zur Erzeugung dieser Ausgaben finden sich in den Modulen artifact_report und ilapfuncs. Auf hoher Ebene könnte ein Beispiel wie folgt aussehen:

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

Testdaten und sample_data für deinen PR

Ein PR, der ein Artefakt hinzufügt oder ändert, ist am einfachsten zu überprüfen und zusammenzuführen, wenn er mit zwei Dingen geliefert wird: einer kleinen Test-Fixture, die aus einer echten Extraktion geschnitten wurde, und sample_data-Werten, die festhalten, was das Modul erzeugt hat. Skripte generieren beides. Hier ist der gesamte Ablauf.

Eine Regel vor allem anderen: Was auch immer du hier committest, wird öffentlich. Verwende nur Daten, die du teilen darfst, wie ein Testgerät, das du selbst befüllt hast, ein öffentliches Forschungsimage oder eine Datei, die du von Hand bereinigt hast. Niemals Fallarbeit.

1. Schneide eine Fixture aus deiner Extraktion

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

Dies zieht die Dateien, auf die die paths-Muster deines Moduls zutreffen, aus der Extraktion und schreibt die Falldatei admin/test/cases/testdata.<module>.json sowie ein kleines Zip pro Artefakt unter admin/test/cases/data/<module>/.

Größenregeln: Unter 10 MB pro Zip, committe es mit dem PR. Zwischen 10 und 25 MB, committe die Falldatei und hänge das Zip an einen PR-Kommentar an. Größer als das, sage es im PR und ein Maintainer wird eine Übergabe arrangieren.

2. Zeichne die erwartete Ausgabe auf

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

Dies führt das Modul gegen die Fixture aus und schreibt einen Snapshot der Ausgabe unter admin/test/results/<module>/. Committe auch den Snapshot. Er wird zur Baseline, die das Modul nach dem Zusammenführen schützt. Behalte den TZ=UTC-Teil bei: Die committeten Snapshots sind UTC und CI läuft in UTC.

3. Führe denselben Vergleich aus, den CI ausführen wird

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

4. Generiere die sample_data-Werte

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

Dies führt ALEAPP Ende-zu-Ende auf deiner Extraktion aus und gibt fertig einzufügende sample_data-Blöcke für die Module aus, die auf deinem Branch geändert wurden. Füge sie in das __artifacts_v2__ deines Moduls ein und füge den App-Namen und die Version hinzu, die du auf dem Image gesehen hast. Wenn eine Anzahl null ist, prüfe, ob die Quelldatei wirklich leer ist, bevor du sie aufzeichnest.

5. Committe alles und öffne den PR

Committe das Modul, die Falldatei, die Fixture-Zips und den aufgezeichneten Snapshot zusammen. Weitere Details findest du in admin/docs/testing/create_module_test_cases.md.

Wenn deine Extraktion nicht geteilt werden kann, öffne den PR trotzdem und sage es. Eine Fixture kann oft stattdessen aus einem öffentlichen Forschungsimage geschnitten werden, oder die echte Datei kann von Hand bereinigt werden. Die Überprüfung stoppt nicht, während wir das klären.

Danksagungen

Dieses Tool ist das Ergebnis einer gemeinsamen Anstrengung vieler Menschen in der DFIR-Community.

ALEAPP-Logo mit freundlicher Genehmigung von Derek Eiri.