TinyInst```

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

## ما هو TinyInst؟

TinyInst هي مكتبة أدوات ديناميكية خفيفة الوزن يمكن استخدامها لتجهيز وحدات مختارة فقط في العملية، مع ترك بقية العملية لتعمل بشكل أصلي. وهي مصممة لتكون سهلة الفهم، وسهلة التطوير عليها، وسهلة الاستخدام في التجارب الأمنية. إنها غير مصممة لتكون متوافقة مع جميع الأهداف (المزيد عن ذلك لاحقًا).

### كيف يمكن مقارنتها بـ [DynamoRIO](https://dynamorio.org/) و[PIN](https://software.intel.com/en-us/articles/pintool)؟

TinyInst ليس بديلاً لأُطر الأدوات المعقدة مثل DynamoRIO وPIN، بل هو خيار بديل للسيناريوهات التي يكفي فيها حل أكثر خفة. يفترض TinyInst أن الهدف حسن السلوك (بالمعنى الموضح أدناه)، وهذا ليس هو الحال بالنسبة للأُطر الأكثر تعقيدًا. وبالتالي، من المحتمل ألا تتمكن من تشغيل TinyInst بنجاح ضد البرمجيات الخبيثة كما [حدث مع DynamoRIO سابقًا](https://www.slideshare.net/MaximShudrak/fuzzing-malware-for-fun-profit-applying-coverageguided-fuzzing-to-find-bugs-in-modern-malware). من ناحية أخرى، إذا كان هدف ما لا يعمل مع الأُطر الأخرى بسبب وحدة لا تحتاج إلى تجهيز، وكانت الوحدة المجهزة حسن السلوك، فقد يعمل مع TinyInst. ولأنه مع TinyInst سيعمل معظم العملية بشكل أصلي، سيكون وقت بدء العملية أقصر، وقد يتفوق على الحلول الأخرى في الحالات التي يقضي فيها الهدف الكثير من الوقت في الوحدات التي لا تحتاج إلى أدوات قياس.

### كيف يمكن مقارنتها بـ [Mesos](https://github.com/gamozolabs/mesos) و[TrapFuzz](https://github.com/googleprojectzero/p0tools/tree/master/TrapFuzz)؟

TinyInst هو حل كامل لإعادة كتابة الثنائيات (binary rewriting)، لذا يمكن تغيير أي سلوك في الوحدة المستهدفة. وهذا يتيح له، على سبيل المثال، استخراج تغطية الحواف (edge coverage) بدلاً من الكتل الأساسية فقط. بالإضافة إلى ذلك، لا يعتمد TinyInst على برامج أخرى، مثل IDA Pro، لتحديد الكتل الأساسية.

### ما هي أنظمة التشغيل التي يدعمها TinyInst؟

يعمل TinyInst على Windows (x86 وx64)، وmacOS (x64 وARM64)، وLinux (x64 وARM64)، وAndroid (ARM64). يرجى الاطلاع على ملف README في المجلد المقابل لكل نظام تشغيل للحصول على ملاحظات وقيود إضافية.

### ما هي الأهداف المتوافقة مع TinyInst؟

يفترض TinyInst أن جميع الوحدات المجهزة حسن السلوك بمعنى أن

- لا يوجد كود يعدّل نفسه
- لا يتم الوصول إلى عنوان العودة على المكدس مباشرة بواسطة البرنامج
أو/و (حسب الإعدادات)
- لا يتم تخزين أي بيانات أبدًا قبل قمة المكدس (في عناوين أقل من تلك التي يشير إليها ESP/RSP). يمكن تخفيف هذا الشرط إلى "لا بيانات قبل (ESP/RSP - arbitrary_offset)" باستخدام العلم `-stack_offset`.

يتطلب TinyInst أيضًا تمكين DEP/NX للعملية المستهدفة. إذا لم يكن الأمر كذلك بالفعل، يمكنك استخدام العلم `-force_dep` لفرض تمكينه. ومع ذلك، في الحالة غير المحتملة التي يحتاج فيها الهدف فعليًا إلى إيقاف DEP ليعمل بشكل صحيح، فإن فرض تمكينه قد يسبب سلوكًا غير سليم.

### ما هو الحمل على الأداء؟

وفقًا للقياسات المبكرة على فك تشفير الصور، على هدف 64-بت حسن السلوك مع إعدادات TinyInst الافتراضية، كان الحمل على الأداء حوالي 15% بدون عميل (client) وحوالي 20% مع العميل النموذجي لجمع التغطية. لاحظ أن هذا لا يتضمن المهلة الزمنية الناتجة عن التجهيز الأولي للوحدات. راجع نصائح الأداء أدناه لمزيد من التفاصيل.

## بناء TinyInst

1. افتح طرفية (Terminal) وأعدّ بيئة البناء الخاصة بك (على سبيل المثال، على Windows، قم بتشغيل vcvars64.bat / vcvars32.bat)

2. انتقل إلى المجلد الذي يحتوي على الكود المصدري

3. شغّل الأوامر التالية (غيّر المولّد وفقًا لإصدار بيئة التطوير المتكاملة (IDE) والمنصة التي تريد البناء من أجلها):

#### Windows```
mkdir build
cd build
cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release

macOS```

mkdir build cd build cmake -G Xcode .. cmake --build . --config Release

#### Linux```
mkdir build
cd build
cmake ..
cmake --build . --config Release

التجميع المتقاطع لنظام أندرويد```

mkdir build cd build cmake -DCMAKE_TOOLCHAIN_FILE=</path/to/android/ndk>build/cmake/android.toolchain.cmake -DANDROID_NDK=</path/to/android/ndk> -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM= .. cmake --build . --config Release

ملاحظة رقم 1: سيعمل إصدار 64-bit أيضًا على أهداف 32-bit في أنظمة تشغيل Windows و Linux

ملاحظة رقم 2: تواجه مشاكل في إنشاء إصدار 32-bit على نظام Windows 64-bit بسبب عدم إعداد البيئة بشكل صحيح ونقص المكتبات؟ افتح ملف .sln الذي تم إنشاؤه في Visual Studio وقم بالبناء من هناك بدلاً من تشغيل cmake --build. لاحظ أيضًا أن إصدار 64-bit سيعمل على أهداف 32-bit، لذا قد لا يكون إنشاء إصدار 32-bit ضروريًا.

## استخدام TinyInst

TinyInst مخصص في المقام الأول للاستخدام كمكتبة داخل برامج أخرى.

يُكتب عميل TinyInst كفئة فرعية من فئة TinyInst. يمكن للعميل بعد ذلك تجاوز طرق API التي يحتاجها. يتم تعريف طرق API أدناه.

بعد إنشاء العميل، يجب تهيئته بخيارات سطر الأوامر عن طريق استدعاء

`void init(int argc, char **argv);`

يتم تعريف خيارات سطر الأوامر أدناه، ويمكن للعميل أيضًا تعريف خيارات خاصة به. بعد ذلك، لتشغيل برنامج مُجهز (instrumented) والتحكم فيه، يمكن استخدام الدوال التالية.

`DebuggerStatus Run(int argc, char **argv, uint32_t timeout);`
`DebuggerStatus Attach(unsigned int pid, uint32_t timeout);`

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

عندما تعود `Run` و `Attach` بينما لا تزال عملية الهدف قيد الحياة، يمكن استخدام الدوال التالية إما لإنهاء العملية أو مواصلة التنفيذ.

`DebuggerStatus Kill();`

`DebuggerStatus Continue(uint32_t timeout);`

يأتي TinyInst مع ملف ثنائي مثال للتغطية (coverage)، يمكن استدعاؤه باستخدام

`<options> -- <target command line>`

مثال على Windows:

`litecov.exe -instrument_module notepad.exe -coverage_file coverage.txt -- notepad.exe`

## واجهة برمجة التطبيقات للتجهيز (Instrumentation API)

### استدعاءات أحداث المصحح

هذه الاستدعاءات مخصصة للمعلومات فقط، ويجب على العميل ألا يصدر أي كود مُجهز أثناءها. يجب على العملاء استدعاء نفس المعالج المعرف في الفئة الفائقة قبل معالجة هذه الأحداث بأنفسهم.

`OnProcessCreated`
يستدعى عند إنشاء عملية الهدف أو الارتباط بها.

`OnProcessExit`
يستدعى عند خروج عملية الهدف.

`OnProcessEntrypoint`
يستدعى عند الوصول إلى نقطة دخول العملية (الملف الثنائي الرئيسي).

`OnTargetMethodReached`
إذا تم تعريف طريقة الهدف، يستدعى عند الوصول إلى طريقة الهدف لأول مرة.

`OnModuleLoaded`
يستدعى عند تحميل وحدة. يستدعى لكل وحدة، وليس فقط للوحدات المُجهزة.

`OnModuleUnloaded`
يستدعى عند إلغاء تحميل وحدة. يستدعى لكل وحدة، وليس فقط للوحدات المُجهزة.

`OnException`
يستدعى عند مواجهة استثناء. يجب على العميل إما إرجاع true (إذا تم التعامل مع الاستثناء) أو نتيجة نفس الطريقة في الفئة الأصلية.

### استدعاءات التجهيز

خلال هذه الاستدعاءات، يمكن للعميل إضافة كود إلى الهدف عن طريق استدعاء `WriteCode()`. لاحظ أن العميل مسؤول عن حفظ واستعادة أي سياق (مثل السجلات والأعلام التي يتم إتلافها في الكود المُدرج).

`InstrumentBasicBlock`
يمكن استخدامه لإدراج كود سيتم تشغيله على كتلة أساسية معينة.

`InstrumentEdge`
يمكن استخدامه لإدراج كود سيتم تشغيله على حافة معينة. ملاحظة: لأسباب تتعلق بالأداء، يتم إصدار هذا الاستدعاء فقط على الحواف غير الحتمية (أي القفزات الشرطية) والقفزات/الاستدعاءات غير المباشرة (مثل `call rax`). بالنسبة للحواف التي تكون فيها الكتلة الأساسية التالية معروفة دائمًا بالنظر إلى الكتلة الأساسية السابقة (مثل `jmp offset` و `call offset`)، لن يتم إصدار أي استدعاء.

`InstrumentInstruction`
يمكن استخدامه لتعديل التعليمات أو إدراج كود قبلها. اعتمادًا على رمز الإرجاع، سيتم إصدار التعليمات الأصلية أو لن يتم إصدارها بعد الاستدعاء.

### استدعاءات أخرى

TinyInst

الأكثر شعبية

TinyInst```

macOS```

التجميع المتقاطع لنظام أندرويد```