abrignoni/aleappAnalizador de registros, eventos y protobuf de Android
Si quieres contribuir, contáctame aquí: https://abrignoni.github.io
Publicaciones del blog aquí: https://leapps.org/blog
Python 3.10 o superior
Las dependencias para tu entorno de Python están listadas en requirements.txt. Instálalas usando el siguiente comando. Asegúrate de que la parte py sea correcta para tu entorno, por ejemplo, py, python o python3, etc.
py -m pip install -r requirements.txt
o
pip3 install -r requirements.txt
Para ejecutar en Linux, también necesitarás instalar tkinter por separado de la siguiente manera:
sudo apt-get install python3-tk
Para compilar a un ejecutable y poder ejecutarlo en un sistema sin Python instalado.
Sistema operativo Windows
Para crear aleapp.exe, ejecuta:
pyinstaller scripts\pyinstaller\aleapp.spec
Para crear aleappGUI.exe, ejecuta:
pyinstaller scripts\pyinstaller\aleappGUI.spec
macOS
Para crear aleapp, ejecuta:
pyinstaller scripts/pyinstaller/aleapp_macOS.spec
Para crear aleappGUI.app, ejecuta:
pyinstaller scripts/pyinstaller/aleappGUI_macOS.spec
Linux
Para crear aleapp, ejecuta:
pyinstaller scripts/pyinstaller/aleapp_Linux.spec
Para crear aleappGUI, ejecuta:
pyinstaller scripts/pyinstaller/aleappGUI_Linux.spec
$ python aleapp.py -t <zip | tar | fs | gz> -i <ruta_a_la_extraccion> -o <ruta_para_la_salida_del_informe>
$ python aleappGUI.py
$ python aleapp.py --help
Cada plugin es un archivo fuente de Python que debe agregarse a la carpeta scripts/artifacts, la cual se cargará dinámicamente cada vez que se ejecute ALEAPP.
El archivo fuente del plugin debe contener un diccionario llamado __artifacts_v2__ al comienzo del módulo, que define los artefactos que procesa el plugin. Las claves en el diccionario __artifacts_v2__ deben ser identificadores de los artefactos que deben ser únicos dentro de ALEAPP. Los valores deben ser diccionarios que contengan las siguientes claves:
name: El nombre del artefacto como cadena.description: Una descripción del artefacto como cadena.author: El autor del plugin como cadena.version: La versión del artefacto como cadena.date: La fecha de la última actualización del artefacto como cadena.requirements: Cualquier requisito para procesar el artefacto como cadena.category: La categoría del artefacto como cadena.notes: Cualquier nota adicional como cadena.paths: Una tupla de cadenas que contienen patrones de búsqueda glob para coincidir con la ruta de los datos que el plugin espera para el artefacto.function: El nombre de la función que es el punto de entrada para el procesamiento del artefacto como cadena.Por ejemplo:
__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"
}
}
Las funciones referenciadas como puntos de entrada en el diccionario __artifacts__ deben aceptar los siguientes argumentos:
Por ejemplo:
def get_cool_data1(files_found, report_folder, seeker, wrap_text):
pass # do processing here
Generalmente se espera que los plugins proporcionen salida en el formato de salida HTML de ALEAPP, TSV y, opcionalmente, envíen registros a la línea de tiempo. Las funciones para generar esta salida se pueden encontrar en los módulos artifact_report e ilapfuncs. A alto nivel, un ejemplo podría parecerse a:
__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)
Un PR que agrega o cambia un artefacto es más fácil de revisar y fusionar cuando llega con dos cosas: un pequeño fixture de prueba extraído de una extracción real y valores de sample_data que registran lo que produjo el módulo. Los scripts generan ambos. Aquí está el flujo completo.
Una regla antes que nada: cualquier cosa que confirmes aquí se vuelve pública. Solo usa datos que tengas permitido compartir, como un dispositivo de prueba que hayas poblado tú mismo, una imagen de investigación pública o un archivo que hayas saneado manualmente. Nunca casos de trabajo real.
1. Corta un fixture de tu extracción
python admin/test/scripts/make_test_data.py <module> --case 1 --input <extraction.zip>
Esto extrae los archivos que coinciden con los patrones de paths de tu módulo de la extracción y escribe el archivo de caso admin/test/cases/testdata.<module>.json más un pequeño zip por artefacto en admin/test/cases/data/<module>/.
Reglas de tamaño: menos de 10 MB por zip, confírmalo con el PR. Entre 10 y 25 MB, confirma el archivo de caso y adjunta el zip a un comentario del PR. Más grande que eso, indícalo en el PR y un mantenedor organizará una entrega.
2. Registra la salida esperada
TZ=UTC python admin/test/scripts/test_module.py <module> -a all -c all
Esto ejecuta el módulo contra el fixture y escribe una instantánea de la salida en admin/test/results/<module>/. Confirma también la instantánea. Se convierte en la línea base que protege el módulo después de la fusión. Mantén la parte TZ=UTC: las instantáneas confirmadas están en UTC y CI se ejecuta en UTC.
3. Ejecuta la misma comparación que ejecutará CI
python admin/test/scripts/run_test_cases.py --module <module>
4. Genera los valores de sample_data
python admin/scripts/validate_sample_data.py --emit <extraction.zip> --key <image_name>
Esto ejecuta ALEAPP de principio a fin en tu extracción e imprime bloques de sample_data listos para pegar para los módulos modificados en tu rama. Pégalos en el __artifacts_v2__ de tu módulo y agrega el nombre y la versión de la aplicación que viste en la imagen. Si un conteo es cero, verifica que el archivo fuente realmente esté vacío antes de registrarlo.
5. Confirma todo y abre el PR
Confirma el módulo, el archivo de caso, los zips de fixtures y la instantánea registrada juntos. Más detalles en admin/docs/testing/create_module_test_cases.md.
Si tu extracción no se puede compartir, abre el PR de todos modos e indícalo. A menudo se puede cortar un fixture de una imagen de investigación pública en su lugar, o el archivo real se puede sanear manualmente. La revisión no se detiene mientras resolvemos eso.
Esta herramienta es el resultado de un esfuerzo colaborativo de muchas personas en la comunidad DFIR.
El logotipo de ALEAPP es cortesía de Derek Eiri.