ALEAPP

محلل سجلات وأحداث وبروتوكولات أندرويد (ALEAPP)

إذا كنت ترغب في المساهمة، تواصل معي هنا: https://abrignoni.github.io

المشاركات في المدونة هنا: https://leapps.org/blog

المتطلبات

بايثون 3.10 أو أحدث

التبعيات

التبعيات الخاصة ببيئة بايثون لديك مذكورة في requirements.txt. قم بتثبيتها باستخدام الأمر أدناه. تأكد من أن جزء py صحيح لبيئتك، مثل py أو python أو python3 وغيرها.

py -m pip install -r requirements.txt أو pip3 install -r requirements.txt

للتشغيل على لينكس، ستحتاج أيضًا إلى تثبيت tkinter بشكل منفصل كما يلي:

sudo apt-get install python3-tk

الترجمة إلى ملف تنفيذي

للترجمة إلى ملف تنفيذي حتى تتمكن من تشغيل هذا على نظام بدون تثبيت بايثون.

نظام ويندوز

لإنشاء 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

نظام لينكس

لإنشاء 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

المساهمة بإضافات القطع الأثرية

كل إضافة هي ملف مصدر بلغة بايثون يجب إضافته إلى مجلد 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 (كنص)
الباحث (من نوع 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) الخاص بك

يكون طلب السحب الذي يضيف أو يغير قطعة أثرية أسهل في المراجعة والدمج عندما يصل مع شيئين: أداة اختبار صغيرة مقتطعة من استخراج حقيقي، وقيم 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، قم بالتزامه مع طلب السحب. بين 10 و25 ميجابايت، قم بالتزام ملف الحالة وأرفق ملف zip بتعليق على طلب السحب. أكبر من ذلك، اذكر ذلك في طلب السحب وسيقوم أحد المشرفين بترتيب التسليم.

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. قم بالتزام كل شيء وافتح طلب السحب

قم بالتزام الوحدة وملف الحالة وملفات zip الخاصة بأدوات الاختبار واللقطة المسجلة معًا. مزيد من التفاصيل موجودة في admin/docs/testing/create_module_test_cases.md.

إذا تعذر مشاركة استخراجك، افتح طلب السحب على أي حال واذكر ذلك. يمكن غالبًا اقتطاع أداة اختبار من صورة بحث عامة بدلاً من ذلك، أو يمكن تنظيف الملف الحقيقي يدويًا. لا تتوقف المراجعة بينما نعمل على حل ذلك.

شكر وتقدير

هذه الأداة هي نتيجة جهد تعاوني للعديد من الأشخاص في مجتمع التحقيق الرقمي والاستجابة للحوادث (DFIR).

شعار ALEAPP بإذن من Derek Eiri.

اقرأ المزيد

ALEAPP v2026.3.3

الفئات