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 è uno scanner di vulnerabilità veloce, accurato e resiliente per app iOS/Android. Operiamo a livello di Dalvik VM per Android – cioè non ci interessa se l'app target è offuscata o meno.

## Capacità

Attualmente possiamo:

* Scansionare automaticamente l'app per vulnerabilità, producendo report in formato HTML/JSON/testo (vedi sotto)
* Manipolare l'app per un'analisi più semplice: ad es. abilitazione del debug bit, abilitazione del backup completo, disabilitazione del TLS pinning, manipolazione del livello API target, iniezione di frida-gadget, ecc.
* Esaminare l'app per informazioni generali
* Copiare dati dentro/fuori dall'app tramite interfaccia di debug
* Cercare determinate chiamate/const/sput/iput
* Dedurre costanti/typesets per gli argomenti di op
* Scansionare chiamate API/private per codici nativi (NB: è necessario [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* Scansionare app iOS per vulnerabilità di base (NB: è necessario [ts2-disasm-ghidra](https://github.com/alterakey/ts2-disasm-ghidra))
* Allega script frida
* Fornisce sessione interattiva frida
* Tracciamento chiamate
* ecc.

## Installazione

### Container

NOTA:
 * A partire dalla 2.1.9, siamo su ghcr.io. (Docker Hub è un po' deprecato)
 * Richiede adbd nell'host per controllare i dispositivi.

Forniamo container così puoi usarli subito come segue; ora questa è anche la via raccomandata, e l'unico modo se sei su Windows, per eseguire:

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

Se vuoi eseguire senza stato, ometti il montaggio del volume su /cache (non consigliato per l'uso quotidiano; vedi anche [#254](https://github.com/alterakey/trueseeing/issues/254)):

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

### Installazione con [uv](https://github.com/astral-sh/uv)

In alternativa, puoi installare il nostro pacchetto con [uv](https://github.com/astral-sh/uv) come segue. In particolare la forma di installazione `uv tool install` potrebbe essere utile per le estensioni (vedi sotto), poiché concede loro la massima libertà. Ricorda solo che hai bisogno di un JRE e Android SDK (opzionalmente; per armeggiare con i dispositivi):

    $ uvx trueseeing

    $ uv tool install trueseeing
    $ trueseeing

### Installazione con pip (deprecato)

Ovviamente puoi sempre usare il buon vecchio pip se necessario:

    $ pip install trueseeing

## Utilizzo

### Modalità interattiva

Puoi scansionare/analizzare/patchare/ecc. le app in modo interattivo – rendendola la scelta ideale per l'analisi manuale:

    $ trueseeing target.apk
    [+] trueseeing x.y.z
    ts[target.apk]> ?
    ...
    ts[target.apk]> i                      # show generic information
    ...
    ts[target.apk]> pf AndroidManifest.xml # show manifest file
    ...
    ts[target.apk]> a                      # analyze resources too
    ...
    ts[target.apk]> /s something           # search text
    ...
    ts[target.apk]> as                     # scan
    ...
    [+] done, found 6403 issues (174.94 sec.)
    ts[target.apk]> gh report.html

### Modalità batch

Accettiamo un comando inline (`-c`) o file script (`-i`) da eseguire prima di darti il prompt, così come uscire subito invece di chiedere prompt (`-q`; non richiediamo un tty in questa modalità!).

Puoi usare le funzionalità per eseguire una scansione batch, come segue ad es. per scaricare i risultati direttamente su stderr:

    $ trueseeing -eqc 'as' target.apk

Per generare un file di report in formato HTML:

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

Per generare un file di report in formato JSON:

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

Per ottenere il report generato su stdout, ometti il nome del file dal comando `g*` finale:

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

### Modalità di scansione non interattiva (deprecata)

Tradizionalmente, puoi scansionare app con la seguente riga di comando per ottenere i risultati elencati su stderr:

    $ trueseeing --scan target.apk

Per generare un report in formato HTML:

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

Per generare un report in formato JSON:

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

Per ottenere il report generato su stdout, specifica '-' come nome file:

    $ 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

## Utilizzi Avanzati

### Estensioni

Puoi scrivere i tuoi comandi e firme come estensioni. Le estensioni sono posizionate sotto `/ext` (container) o `~/.trueseeing2/extensions/` (uv/pip). In alternativa puoi distribuire le tue estensioni come wheel. Forniamo informazioni sui tipi in modo da poter non solo eseguire il type-check delle tue estensioni con [zuban](https://github.com/zubanls/zuban) ma anche ottenere un buon supporto dagli IDE. Vedi la sezione dettagli per i dettagli.

## Compilazione

Puoi compilarlo come segue:

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

Per compilare wheel puoi farlo con [flit](https://flit.pypa.io/en/stable/), come segue:

    $ flit build

Per hackerarlo, devi creare un ambiente di build appropriato. Con [uv](https://github.com/astral-sh/uv) puoi semplicemente fare:

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

Con pip, per crearne uno, prima imposta un venv, installa [flit](https://flit.pypa.io/en/stable/) e le toolchain di validazione ([zuban](https://github.com/zubanls/zuban) e [ruff](https://github.com/astral-sh/ruff)) lì dentro, e fai sì che flit tiri le dipendenze. In breve, fai qualcosa del genere:

    $ 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 ...                                   # to run
    (.venv) $ zuban check trueseeing && ruff check trueseeing  # to validate
    Success: no issues found in XX source files
    (.venv) $ flit build                                       # to build (wheel)
    (.venv) $ docker build -t trueseeing .                     # to build (container)

## Dettagli

### Classi di vulnerabilità

Attualmente possiamo rilevare le seguenti classi di vulnerabilità, in gran parte quelle coperte da OWASP Mobile Top 10 - 2016:

  * Improper Platform Usage (M1)

    * Debuggabile
    * Pubblicazione involontaria di Activity, Service, ContentProvider, BroadcastReceiver

  * Insecure Data (M2)

    * Backupabile (cioè suscettibile all'attacco di backup)
    * Permessi file insicuri
    * Registrazione

  * Insecure Communications (M3)

    * Mancanza di pinning (cioè suscettibile all'attacco di intercettazione TLS)
    * Uso di HTTP in chiaro
    * WebView manipolabili

  * Insufficient Cryptography (M5)

    * Passphrase/chiavi segrete hardcoded
    * Cifrari Vernam con chiavi statiche
    * Uso della modalità ECB

  * Client Code Quality Issues (M7)

    * WebView riflettenti (cioè gli XSS in tali viste dovrebbero essere escalabili a esecuzioni di codice remoto tramite riflessione JS)
    * Uso di policy insicura su contenuti misti

  * Code Tampering (M8)

    * Certificati hardcoded

  * Reverse Engineering (M9)

    * Mancanza di offuscamento

### API delle estensioni

La nostra API delle estensioni si trova sotto il pacchetto `trueseeing.api`. Poiché forniamo informazioni sui tipi, il tuo IDE ti assisterà nello scrivere le tue estensioni. Assicurati solo che il suo (o del suo language server) PYTHONPATH copra il venv in cui si trova il nostro pacchetto; vedi `uv tool list --show-paths` se lo hai installato con `uv tool install`. Se lo hai installato con `uvx`, considera reinstallarlo con `uvx install`. Se lo hai installato con pip, sai già dov'è.

#### Comandi

Per definire nuovi comandi, implementa `trueseeing.api.Command` e pubblicizzali.

La seguente classe fornirà un comando di esempio come `t`, per esempio:

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

#### Firme

Per definire nuove firme, implementa `trueseeing.api.Signature` e pubblicizzale.

La seguente classe fornirà un rilevatore di esempio come `my-sig`, per esempio:

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

#### Formati di file

Per definire nuovi formati di file, prima implementa i `Context` (ABC) per i tuoi formati, poi implementa `trueseeing.api.FileFormatHandler` per creare e restituire le loro istanze, e pubblicizzali.

La seguente classe fornirà il supporto per file APK sotto il tipo chiamato `apk2`, per esempio:

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

Poi assicurati di controllare il tipo del contesto nelle tue firme, facendole ignorare su contesti non supportati:

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

In caso di controllo riuscito, `require_type(...)` tenterà di downcastarli ai tipi appropriati per tua comodità.

Ma per progettazione funziona solo per tipi conosciuti (attualmente, `apk`). Quindi se stai definendo un'interfaccia dettagliata nelle tue nuove classi di contesto come facciamo per il tipo `apk`, devi fare un downcast qui, cioè:

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

È possibile definire più formati che corrispondono allo stesso pattern. Valutiamo i pattern in ordine dal più stringente (cioè lungo) al meno. Usa l'opzione `-F` per forzare un formato da utilizzare con il file target, ad es.:

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

#### Requisiti del pacchetto

Le estensioni possono essere: a) qualsiasi pacchetto posizionato sotto `/ext` (container) o `~/.trueseeing2/extensions` (pip), oppure b) qualsiasi modulo installato con il prefisso `trueseeing_ext0_`.

### Origine del nome del progetto?

L'incantesimo di D&D, [True Seeing](https://www.dandwiki.com/wiki/SRD:True_Seeing).