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 ist ein schneller, genauer und robuster Schwachstellenscanner für iOS-/Android-Apps. Wir arbeiten auf der Dalvik-VM-Ebene für Android – d.h. es ist uns egal, ob die Ziel-App obfuskiert ist oder nicht.

## Fähigkeiten

Derzeit können wir:

* Automatisches Scannen der App auf Schwachstellen, Berichterstellung im HTML/JSON/Text-Format (siehe unten)
* Manipulieren der App für eine einfachere Analyse: z.B. Aktivieren des Debug-Bits, Aktivieren der vollständigen Sicherung, Deaktivieren von TLS-Pinning, Manipulieren der Ziel-API-Ebene, Injizieren von frida-gadget usw.
* Untersuchen der App auf allgemeine Informationen
* Kopieren von App-Daten über die Debug-Schnittstelle
* Suche nach bestimmten Aufrufen/Konstanten/sput/iput
* Ableitung von Konstanten/Typensätzen für Argumente von Operationen
* Scannen von API-/privaten Aufrufen auf nativen Code (Hinweis: Sie benötigen [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* Scannen von iOS-Apps auf grundlegende Schwachstellen (Hinweis: Sie benötigen [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* Anhängen von Frida-Skripten
* Bereitstellen einer interaktiven Frida-Sitzung
* Ablaufverfolgung von Aufrufen
* usw.

## Installation

### Container

HINWEIS:
 * Ab Version 2.1.9 sind wir auf ghcr.io. (Docker Hub ist etwas veraltet)
 * Erfordert adbd auf dem Host, um Geräte zu steuern.

Wir stellen Container zur Verfügung, damit Sie sie wie folgt sofort nutzen können; dies ist jetzt auch die empfohlene Methode und die einzige Möglichkeit, wenn Sie Windows verwenden, um auszuführen:

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

Wenn Sie zustandslos ausführen möchten, lassen Sie das Einhängen des Volumes auf /cache weg (für den täglichen Gebrauch jedoch nicht empfohlen; siehe auch [#254](https://github.com/alterakey/trueseeing/issues/254)):

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

### Installation mit [uv](https://github.com/astral-sh/uv)

Alternativ können Sie unser Paket wie folgt mit [uv](https://github.com/astral-sh/uv) installieren. Insbesondere die Installationsform `uv tool install` könnte für Erweiterungen nützlich sein (siehe unten), da sie ihnen die größte Freiheit gewährt. Denken Sie daran, dass Sie eine JRE und ein Android SDK benötigen (optional; um mit Geräten zu arbeiten):

    $ uvx trueseeing

    $ uv tool install trueseeing
    $ trueseeing

### Installation mit pip (veraltet)

Natürlich können Sie bei Bedarf immer die gute alte pip verwenden:

    $ pip install trueseeing

## Verwendung

### Interaktiver Modus

Sie können Apps interaktiv scannen/analysieren/patchen usw. – dies ist die ideale Wahl für die manuelle Analyse:

    $ trueseeing target.apk
    [+] trueseeing x.y.z
    ts[target.apk]> ?
    ...
    ts[target.apk]> i                      # allgemeine Informationen anzeigen
    ...
    ts[target.apk]> pf AndroidManifest.xml # Manifestdatei anzeigen
    ...
    ts[target.apk]> a                      # Ressourcen ebenfalls analysieren
    ...
    ts[target.apk]> /s something           # Text suchen
    ...
    ts[target.apk]> as                     # scannen
    ...
    [+] done, found 6403 issues (174.94 sec.)
    ts[target.apk]> gh report.html

### Batch-Modus

Wir akzeptieren einen Inline-Befehl (`-c`) oder eine Skriptdatei (`-i`), die ausgeführt wird, bevor wir Ihnen eine Eingabeaufforderung geben, sowie das sofortige Beenden anstelle einer Eingabeaufforderung (`-q`; in diesem Modus benötigen wir kein tty!).

Sie können die Funktionen verwenden, um einen Batch-Scan durchzuführen, um z.B. Ergebnisse direkt auf stderr auszugeben:

    $ trueseeing -eqc 'as' target.apk

Um einen Bericht im HTML-Format zu erstellen:

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

Um einen Bericht im JSON-Format zu erstellen:

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

Um den Bericht in stdout zu erhalten, lassen Sie den Dateinamen im abschließenden `g*`-Befehl weg:

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

### Nicht-interaktiver Scan-Modus (veraltet)

Traditionell können Sie Apps mit der folgenden Befehlszeile scannen, um Ergebnisse in stderr aufzulisten:

    $ trueseeing --scan target.apk

Um einen Bericht im HTML-Format zu erstellen:

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

Um einen Bericht im JSON-Format zu erstellen:

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

Um den Bericht in stdout zu erhalten, geben Sie '-' als Dateinamen an:

    $ 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

## Erweiterte Nutzung

### Erweiterungen

Sie können Ihre eigenen Befehle und Signaturen als Erweiterungen schreiben. Erweiterungen werden unter `/ext` (Container) oder `~/.trueseeing2/extensions/` (uv/pip) abgelegt. Alternativ können Sie Ihre Erweiterungen als Wheels verteilen. Wir stellen Typinformationen bereit, sodass Sie Ihre Erweiterungen nicht nur mit [zuban](https://github.com/zubanls/zuban) typüberprüfen, sondern auch eine ordentliche Unterstützung von IDEs erhalten. Einzelheiten finden Sie im Abschnitt Details.

## Erstellung

Sie können es wie folgt erstellen:

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

Um Wheels zu erstellen, können Sie es mit [flit](https://flit.pypa.io/en/stable/) wie folgt tun:

    $ flit build

Um daran zu hacken, müssen Sie eine geeignete Build-Umgebung erstellen. Mit [uv](https://github.com/astral-sh/uv) können Sie einfach Folgendes tun:

    $ git clone https://github.com/alterakey/trueseeing.git wc
    $ uv sync --locked --dev
    $ (... hack ...)
    $ uv run trueseeing ...                                    # zum Ausführen
    $ uv run zuban check trueseeing && uv run ruff trueseeing  # zur Validierung
    Success: no issues found in XX source files
    $ uv run flit build                                        # zum Erstellen (wheel)
    $ docker build -t trueseeing .                             # zum Erstellen (container)

Mit pip müssen Sie zunächst eine venv einrichten, dort [flit](https://flit.pypa.io/en/stable/) und die Validierungstoolchains ([zuban](https://github.com/zubanls/zuban) und [ruff](https://github.com/astral-sh/ruff)) installieren und flit die Abhängigkeiten ziehen lassen. Kurz gesagt, tun Sie so etwas:

    $ 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 ...                                   # zum Ausführen
    (.venv) $ zuban check trueseeing && ruff check trueseeing  # zur Validierung
    Success: no issues found in XX source files
    (.venv) $ flit build                                       # zum Erstellen (wheel)
    (.venv) $ docker build -t trueseeing .                     # zum Erstellen (container)

## Details

### Schwachstellenklassen

Derzeit können wir die folgenden Schwachstellenklassen erkennen, die größtenteils in OWASP Mobile Top 10 - 2016 abgedeckt sind:

  * Unsachgemäße Plattformnutzung (M1)

    * Debuggable
    * Unbeabsichtigte Veröffentlichung von Activities, Services, ContentProviders, BroadcastReceivers

  * Unsicherer Datenschutz (M2)

    * Backupable (d.h. anfällig für den Backup-Angriff)
    * Unsichere Dateiberechtigungen
    * Protokollierung

  * Unsichere Kommunikation (M3)

    * Fehlendes Pinning (d.h. anfällig für TLS-Abfangangriffe)
    * Verwendung von Klartext-HTTP
    * Manipulierbare WebViews

  * Unzureichende Kryptografie (M5)

    * Hartcodierte Passphrasen/geheime Schlüssel
    * Vernum-Chiffren mit statischen Schlüsseln
    * Verwendung des ECB-Modus

  * Probleme mit der Client-Code-Qualität (M7)

    * Reflektierbare WebViews (d.h. XSS in solchen Ansichten sollten über JS-Reflection zu Remote-Code-Ausführungen eskalierbar sein)
    * Verwendung unsicherer Richtlinien für gemischte Inhalte

  * Code-Manipulation (M8)

    * Hartcodierte Zertifikate

  * Reverse Engineering (M9)

    * Fehlende Obfuskation

### Erweiterungs-API

Unsere Erweiterungs-API befindet sich im Paket `trueseeing.api`. Da wir Typinformationen bereitstellen, unterstützt Sie Ihre IDE beim Schreiben Ihrer Erweiterungen. Stellen Sie sicher, dass der PYTHONPATH (oder der seines Language Servers) die venv abdeckt, in der sich unser Paket befindet; siehe `uv tool list --show-paths`, wenn Sie es mit `uv tool install` installiert haben. Wenn Sie es mit `uvx` installiert haben, installieren Sie es gegebenenfalls mit `uvx install` neu. Wenn Sie es mit pip installiert haben, wissen Sie bereits, wo es ist.

#### Befehle

Um neue Befehle zu definieren, implementieren Sie `trueseeing.api.Command` und machen Sie diese bekannt.

Die folgende Klasse stellt beispielsweise einen Beispielbefehl als `t` bereit:

```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')
```

#### Signaturen

Um neue Signaturen zu definieren, implementieren Sie `trueseeing.api.Signature` und machen Sie diese bekannt.

Die folgende Klasse stellt beispielsweise einen Beispiel-Detektor als `my-sig` bereit:

```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/',
      )
    )
```

#### Dateiformate

Um neue Dateiformate zu definieren, implementieren Sie zunächst `Context`s (ABC) für Ihre Formate, dann implementieren Sie `trueseeing.api.FileFormatHandler`, um deren Instanzen zu erstellen und zurückzugeben, und machen Sie diese bekannt.

Die folgende Klasse stellt beispielsweise APK-Dateiunterstützung unter dem Typnamen `apk2` bereit:

```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):
  # Verwenden Sie einen anderen Kontexttyp
  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)}  # wenn dieser Handler einen Gerätekontexttyp vorschlagen kann, geben Sie ihn bei t an

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

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

Stellen Sie dann sicher, dass Sie den Typ des Kontexts in Ihren Signaturen überprüfen, sodass sie bei nicht unterstützten Kontexten ignoriert werden:

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

Nach erfolgreicher Prüfung wird `require_type(...)` versuchen, sie zu Ihrem Vorteil in die entsprechenden Typen umzuwandeln.

Aber konstruktionsbedingt funktioniert es nur für bekannte Typen (derzeit der `apk`-Typ). Wenn Sie also wie wir für den `apk`-Typ eine detaillierte Schnittstelle in Ihren neuen Kontextklassen definieren, müssen Sie hier eine Downcast durchführen, d.h.:

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

Es ist möglich, mehrere Formate zu definieren, die demselben Muster entsprechen. Wir werten Muster in der Reihenfolge vom strengsten (d.h. lang) zum geringsten aus. Verwenden Sie den Schalter `-F`, um ein bestimmtes Format für die Zieldatei zu erzwingen, z.B.:

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

#### Paketanforderungen

Erweiterungen können entweder a) ein beliebiges Paket sein, das unter `/ext` (Container) oder `~/.trueseeing2/extensions` (pip) abgelegt ist, oder b) ein installiertes Modul, das mit dem Präfix `trueseeing_ext0_` benannt ist.

### Ursprung des Projektnamens?

Der D&D-Zauber [True Seeing](https://www.dandwiki.com/wiki/SRD:True_Seeing).