trueseeing

# README

![Last release](https://img.shields.io/github/v/release/alterakey/trueseeing)
![Last release date](https://img.shields.io/github/release-date-pre/alterakey/trueseeing)
![Main branch deploy status](https://github.com/alterakey/trueseeing/workflows/deploy/badge.svg)
![Main branch last commit](https://img.shields.io/github/last-commit/alterakey/trueseeing/main)

trueseeing هو ماسح ثغرات أمنية سريع ودقيق ومرن لتطبيقات iOS/Android. نعمل على مستوى جهاز Dalvik الافتراضي لنظام Android – أي لا نهتم إذا كان التطبيق المستهدف مشفرًا أم لا.

## القدرات

حاليًا يمكننا:

* فحص التطبيق تلقائيًا بحثًا عن الثغرات، وإعداد تقارير بصيغة HTML/JSON/نص (انظر أدناه)
* تعديل التطبيق لتسهيل التحليل: مثل تمكين بت التصحيح، تمكين النسخ الاحتياطي الكامل، تعطيل تثبيت TLS، تعديل مستوى API المستهدف، حقن frida-gadget، إلخ.
* فحص التطبيق للحصول على معلومات عامة
* نسخ بيانات التطبيق من وإلى عبر واجهة التصحيح
* البحث عن استدعاءات/ثوابت/sput/iput معينة
* استنتاج الثوابت/مجموعات الأنواع لوسائط العملية
* فحص استدعاءات API/الخاصة للكودات الأصلية (ملاحظة: تحتاج إلى [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* فحص تطبيقات iOS بحثًا عن الثغرات الأساسية (ملاحظة: تحتاج إلى [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* إرفاق نصوص frida
* توفير جلسة تفاعلية لـ frida
* تتبع الاستدعاءات
* إلخ.

## التثبيت

### الحاويات

ملاحظة:
 * اعتبارًا من الإصدار 2.1.9، نحن على ghcr.io. (Docker Hub مهمل نوعًا ما)
 * يتطلب وجود adbd في المضيف للتحكم في الأجهزة.

نقدم حاويات لتتمكن من الاستخدام مباشرة كما يلي؛ هذا هو الآن الطريقة الموصى بها، والطريقة الوحيدة إذا كنت على Windows للتشغيل:

    $ docker run --rm -v $(pwd):/out -v ts2:/cache ghcr.io/alterakey/trueseeing

إذا كنت تريد التشغيل بدون حالة، يمكنك حذف تثبيت المجلد على /cache (غير موصى به للاستخدام اليومي رغم ذلك؛ راجع أيضًا [#254](https://github.com/alterakey/trueseeing/issues/254)):

    $ docker run --rm -v $(pwd):/out ghcr.io/alterakey/trueseeing


### التثبيت باستخدام [uv](https://github.com/astral-sh/uv)

بدلاً من ذلك، يمكنك تثبيت حزمةنا باستخدام [uv](https://github.com/astral-sh/uv) كما يلي. قد يكون شكل التثبيت `uv tool install` مفيدًا بشكل خاص للإضافات (انظر أدناه)، لأنه يمنحها أكبر قدر من الحرية. فقط تذكر أنك بحاجة إلى JRE وAndroid SDK (اختياريًا؛ للتعامل مع الأجهزة):

    $ uvx trueseeing

    $ uv tool install trueseeing
    $ trueseeing

### التثبيت باستخدام pip (مهمل)

بالطبع يمكنك دائمًا استخدام pip القديم الجيد إذا اضطررت:

    $ pip install trueseeing

## الاستخدام

### الوضع التفاعلي

يمكنك فحص/تحليل/تطبيق التصحيحات/إلخ. على التطبيقات بشكل تفاعلي - مما يجعله الخيار المثالي للتحليل اليدوي:

    $ trueseeing target.apk
    [+] trueseeing x.y.z
    ts[target.apk]> ?
    ...
    ts[target.apk]> i                      # عرض المعلومات العامة
    ...
    ts[target.apk]> pf AndroidManifest.xml # عرض ملف البيان
    ...
    ts[target.apk]> a                      # تحليل الموارد أيضًا
    ...
    ts[target.apk]> /s something           # بحث عن نص
    ...
    ts[target.apk]> as                     # فحص
    ...
    [+] done, found 6403 issues (174.94 sec.)
    ts[target.apk]> gh report.html

### الوضع الدفعي

نقبل أمرًا مضمنًا (`-c`) أو ملف سكريبت (`-i`) للتشغيل قبل إعطائك الموجه، بالإضافة إلى الخروج فورًا بدلاً من العرض (`-q`; لا نحتاج إلى tty في هذا الوضع!).

يمكنك استخدام الميزات لإجراء فحص دفعي، كما يلي مثلاً لإلقاء النتائج مباشرة على stderr:

    $ trueseeing -eqc 'as' target.apk

لإنشاء ملف تقرير بصيغة HTML:

    $ trueseeing -eqc 'as;gh report.html' target.apk

لإنشاء ملف تقرير بصيغة JSON:

    $ trueseeing -eqc 'as;gj report.json' target.apk

للحصول على التقرير في stdout، احذف اسم الملف من أمر `g*` النهائي:

    $ trueseeing -eqc 'as;gh' target.apk > report.html
    $ trueseeing -eqc 'as;gj' target.apk > report.json

### وضع الفحص غير التفاعلي (مهمل)

تقليديًا، يمكنك فحص التطبيقات باستخدام سطر الأوامر التالي للحصول على النتائج المدرجة في stderr:

    $ trueseeing --scan target.apk

لإنشاء تقرير بصيغة HTML:

    $ trueseeing --scan --scan-output report.html target.apk
    $ trueseeing --scan --scan-report=html --scan-output report.html target.apk

لإنشاء تقرير بصيغة JSON:

    $ trueseeing --scan --scan-report=json --scan-output report.json target.apk

للحصول على التقرير في stdout، حدد '-' كاسم الملف:

    $ trueseeing --scan --scan-output - target.apk > report.html
    $ trueseeing --scan --scan-report=html --scan-output - target.apk > report.html
    $ trueseeing --scan --scan-report=json --scan-output - target.apk > report.json

## الاستخدامات المتقدمة

### الإضافات

يمكنك كتابة أوامرك وتوقيعاتك الخاصة كإضافات. توضع الإضافات تحت `/ext` (حاويات) أو `~/.trueseeing2/extensions/` (uv/pip). بدلاً من ذلك يمكنك توزيع إضافاتك كحزم wheels. نقدم معلومات الأنواع حتى تتمكن ليس فقط من التحقق من أنواع إضافاتك باستخدام [zuban](https://github.com/zubanls/zuban) ولكن أيضًا الحصول على مساعدة جيدة من بيئات التطوير المتكاملة. راجع قسم التفاصيل للحصول على التفاصيل.

## البناء

يمكنك بناؤه كما يلي:

    $ docker build -t trueseeing https://github.com/alterakey/trueseeing.git#main

لبناء حزم wheels يمكنك استخدام [flit](https://flit.pypa.io/en/stable/)، كما يلي:

    $ flit build

لتطويره، تحتاج إلى إنشاء بيئة بناء مناسبة. باستخدام [uv](https://github.com/astral-sh/uv) يمكنك فقط القيام بما يلي:

    $ git clone https://github.com/alterakey/trueseeing.git wc
    $ uv sync --locked --dev
    $ (... hack ...)
    $ uv run trueseeing ...                                    # للتشغيل
    $ uv run zuban check trueseeing && uv run ruff trueseeing  # للتحقق
    Success: no issues found in XX source files
    $ uv run flit build                                        # للبناء (wheel)
    $ docker build -t trueseeing .                             # للبناء (حاوية)

باستخدام pip، لإنشاء واحدة، قم أولاً بإعداد venv، وقم بتثبيت [flit](https://flit.pypa.io/en/stable/) وأدوات التحقق ([zuban](https://github.com/zubanls/zuban) و [ruff](https://github.com/astral-sh/ruff)) فيه، واجعل flit يسحب التبعيات. باختصار، افعل شيئًا كهذا:

    $ git clone https://github.com/alterakey/trueseeing.git wc
    $ python3 -m venv wc/.venv
    $ source wc/.venv/bin/activate
    (.venv) $ pip install flit zuban ruff
    (.venv) $ flit install --deps=develop -s
    (.venv) $ (... hack ...)
    (.venv) $ trueseeing ...                                   # للتشغيل
    (.venv) $ zuban check trueseeing && ruff check trueseeing  # للتحقق
    Success: no issues found in XX source files
    (.venv) $ flit build                                       # للبناء (wheel)
    (.venv) $ docker build -t trueseeing .                     # للبناء (حاوية)


## التفاصيل

### فئات الثغرات

يمكننا حاليًا اكتشاف الفئات التالية من الثغرات، ومعظمها مغطى في قائمة OWASP Mobile Top 10 - 2016:

  * سوء استخدام المنصة (M1)

    * قابل للتصحيح
    * نشر غير مقصود للأنشطة والخدمات وموفري المحتوى ومستقبلات البث

  * بيانات غير آمنة (M2)

    * قابل للنسخ الاحتياطي (أي عرضة لهجوم النسخ الاحتياطي)
    * أذونات ملفات غير آمنة
    * التسجيل

  * اتصالات غير آمنة (M3)

    * عدم وجود تثبيت (أي عرضة لهجوم اعتراض TLS)
    * استخدام HTTP بنص واضح
    * WebViews قابلة للتلاعب

  * تشفير غير كافٍ (M5)

    * عبارات مرور/مفاتيح سرية مشفرة في الكود
    * شفرات فيرنام بمفاتيح ثابتة
    * استخدام وضع ECB

  * مشكلات جودة كود العميل (M7)

    * WebViews قابلة للانعكاس (أي يجب أن تكون XSSs في هذه العروض قابلة للتصعيد إلى تنفيذ كود عن بعد عبر انعكاس JS)
    * استخدام سياسة غير آمنة على المحتويات المختلطة

  * العبث بالكود (M8)

    * شهادات مشفرة في الكود

  * الهندسة العكسية (M9)

    * عدم وجود تشويش

### واجهة برمجة تطبيقات الإضافات

توجد واجهة برمجة تطبيقات الإضافات الخاصة بنا تحت حزمة `trueseeing.api`. نظرًا لأننا نقدم معلومات الأنواع معها، سيساعدك بيئة التطوير المتكاملة عند كتابة إضافاتك. فقط تأكد من أن PYTHONPATH الخاص بها (أو خاص بخادم لغتها) يغطي venv حيث توجد حزمةنا؛ راجع `uv tool list --show-paths` إذا قمت بتثبيتها باستخدام `uv tool install`. إذا قمت بالتثبيت باستخدام `uvx`، فكر في إعادة تثبيتها باستخدام `uvx install`. إذا قمت بالتثبيت باستخدام pip، فأنت تعرف بالفعل مكانها.

#### الأوامر

لتعريف أوامر جديدة، قم بتنفيذ `trueseeing.api.Command` وأعلن عنها.

ستوفر الفئة التالية أمرًا نموذجيًا كـ `t`، على سبيل المثال:

```python
from typing import TYPE_CHECKING
from trueseeing.api import Command
from trueseeing.core.ui import ui
if TYPE_CHECKING:
  from trueseeing.api import CommandMap, CommandPatternMap, ModifierMap, OptionMap, ConfigMap

class MyCommand(Command):
  @staticmethod
  def create() -> Command:
    return MyCommand()

  def get_commands(self) -> CommandMap:
    return {'t':dict(e=self._test, n='t', d='sample command')}

  def get_command_patterns(self) -> CommandPatternMap:
    return dict()

  def get_modifiers(self) -> ModifierMap:
     return dict()

  def get_options(self) -> OptionMap:
    return dict()

  def get_configs(self) -> ConfigMap:
    return dict()

  async def _test(self) -> None:
    ui.info('hello world')
```

#### التوقيعات

لتعريف توقيعات جديدة، قم بتنفيذ `trueseeing.api.Signature` وأعلن عنها.

ستوفر الفئة التالية كاشفًا نموذجيًا كـ `my-sig`، على سبيل المثال:

```python
from typing import TYPE_CHECKING
from trueseeing.api import Signature
if TYPE_CHECKING:
  from trueseeing.api import SignatureMap, ConfigMap

class MySignature(Signature):
  @staticmethod
  def create() -> Signature:
    return MySignature()

  def get_sigs(self) -> SignatureMap:
    return {'my-sig':dict(e=self._detect, d='sample signature')}

  def get_configs(self) -> ConfigMap:
    return dict()

  async def _detect(self) -> None:
    self._helper.raise_issue(
      self._helper.build_issue(
        sigid='my-sig',
        title='hello world',
        cvss='CVSS:3.0/AV:P/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:N/',
      )
    )
```


#### صيغ الملفات

لتعريف صيغ ملفات جديدة، قم أولاً بتنفيذ `Context`s (فئة مجردة أساسية) لصيغك، ثم قم بتنفيذ `trueseeing.api.FileFormatHandler` لإنشاء وإرجاع مثيلاتها، وأعلن عنها.

ستوفر الفئة التالية دعم ملف APK تحت النوع المسمى `apk2`، على سبيل المثال:

```python
from typing import TYPE_CHECKING
from trueseeing.api import FileFormatHandler
from trueseeing.core.android.context import APKContext

if TYPE_CHECKING:
  from typing import Optional, Set
  from trueseeing.api import FormatMap, ConfigMap
  from trueseeing.core.context import Context, ContextType

class MyAPKContext(APKContext):
  # Use a different context type
  def _get_type(self) -> Set[ContextType]:
    return {'apk2'}

class APKFileFormatHandler(FileFormatHandler):
  @staticmethod
  def create() -> FileFormatHandler:
    return APKFileFormatHandler()

  def get_formats(self) -> FormatMap:
    return {'apk2':dict(e=self._handle, r=r'\.apk$', d='sample file format', t=None)}  # if this handler can suggest device context type, advertise at t

  def get_configs(self) -> ConfigMap:
    return dict()

  def _handle(self, path: str) -> Optional[Context]:
    return MyAPKContext(path)
```

ثم تأكد من التحقق من نوع السياق في توقيعاتك، مما يجعلها تتجاهل السياقات غير المدعومة:

```python
context = self._helper.get_context().require_type('apk2')
```

عند نجاح التحقق، `require_type(...)` ستحاول تحويلها إلى الأنواع المناسبة لراحتك.

ولكن حسب التصميم، يعمل فقط مع الأنواع المعروفة (حاليًا، `apk`). لذا إذا كنت تعرّف واجهة مفصلة في فئات السياق الجديدة كما نفعل لنوع `apk`، فستحتاج إلى إجراء تحويل هنا على سبيل المثال:

```python
context: MyAPKContext = self._helper.get_context().require_type('apk2')  # type:ignore[assignment]
```

من الممكن تعريف صيغ متعددة تطابق نفس النمط. نقوم بتقييم الأنماط بالترتيب من الأكثر تقييدًا (أي الأطول) إلى الأقل. يمكنك استخدام المفتاح `-F` لفرض استخدام صيغة معينة مع الملف الهدف، على سبيل المثال:

```
$ trueseeing -F apk2 target.apk
```

#### متطلبات الحزمة

يمكن أن تكون الإضافات إما: أ) أي حزمة موضوعة تحت `/ext` (حاوية) أو `~/.trueseeing2/extensions` (pip)، أو ب) أي وحدة مثبتة باسم يبدأ بالبادئة `trueseeing_ext0_`.

### أصل اسم المشروع؟

تعويذة D&D، [True Seeing](https://www.dandwiki.com/wiki/SRD:True_Seeing).