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 앱을 위한 빠르고 정확하며 탄력적인 취약점 스캐너입니다. Android의 Dalvik VM 수준에서 작동합니다. 즉, 대상 앱이 난독화되었는지 여부는 중요하지 않습니다.

## 기능

현재 다음을 수행할 수 있습니다:

* 취약점에 대해 앱을 자동으로 스캔하고 HTML/JSON/텍스트 형식으로 보고서 생성 (아래 참조)
* 분석을 용이하게 하기 위해 앱 조작: 예: 디버그 비트 활성화, 전체 백업 활성화, TLS 핀 비활성화, 대상 API 레벨 조작, frida-gadget 삽입 등
* 일반 정보를 위해 앱 검사
* 디버그 인터페이스를 통해 앱 데이터 복사/내보내기
* 특정 호출/상수/sput/iput 검색
* op 인수에 대한 상수/타입셋 추론
* 네이티브 코드에 대한 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                      # 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

### 배치 모드

프롬프트를 제공하기 전에 실행할 인라인 명령(`-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

최종 `g*` 명령에서 파일 이름을 생략하면 stdout으로 보고서가 생성됩니다:

    $ 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)으로 확장 기능의 타입 검사를 할 수 있을 뿐만 아니라 IDE에서 적절한 지원을 받을 수 있습니다. 자세한 내용은 세부 사항 섹션을 참조하세요.

## 빌드

다음과 같이 빌드할 수 있습니다:

    $ 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 ...                                    # 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)

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 ...                                   # 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)

## 세부 사항

### 취약점 클래스

현재 다음 취약점 클래스를 감지할 수 있으며, 이는 대부분 OWASP Mobile Top 10 - 2016에 포함된 것입니다:

  * 부적절한 플랫폼 사용 (M1)

    * 디버그 가능
    * Activity, Service, ContentProvider, BroadcastReceiver의 우발적 게시

  * 안전하지 않은 데이터 (M2)

    * 백업 가능 (즉, 백업 공격에 취약)
    * 안전하지 않은 파일 권한
    * 로깅

  * 안전하지 않은 통신 (M3)

    * 핀 부족 (즉, TLS 가로채기 공격에 취약)
    * 평문 HTTP 사용
    * 조작 가능한 WebView

  * 부족한 암호화 (M5)

    * 하드코딩된 암호/비밀 키
    * 정적 키를 사용하는 Vernum 암호
    * ECB 모드 사용

  * 클라이언트 코드 품질 문제 (M7)

    * 반사 가능한 WebView (즉, 이러한 뷰의 XSS는 JS 반사를 통해 원격 코드 실행으로 확장될 수 있음)
    * 혼합 콘텐츠에 대한 안전하지 않은 정책 사용

  * 코드 변조 (M8)

    * 하드코딩된 인증서

  * 리버스 엔지니어링 (M9)

    * 난독화 부족

### 확장 API

확장 API는 `trueseeing.api` 패키지 아래에 있습니다. 타입 정보를 제공하므로 IDE가 확장 기능을 작성할 때 도움을 줍니다. IDE(또는 해당 언어 서버)의 PYTHONPATH가 패키지가 설치된 venv를 포함하는지 확인하세요. `uv tool install`로 설치한 경우 `uv tool list --show-paths`를 참조하십시오. `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`(ABC)를 구현한 다음 `trueseeing.api.FileFormatHandler`를 구현하여 인스턴스를 생성하고 반환한 후 알립니다.

다음 클래스는 `apk2`라는 유형의 APK 파일 지원을 제공합니다. 예시:

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

#### 패키지 요구 사항

확장 기능은 a) `/ext`(컨테이너) 또는 `~/.trueseeing2/extensions`(pip)에 배치된 모든 패키지, 또는 b) `trueseeing_ext0_` 접두사로 명명된 설치된 모듈일 수 있습니다.

### 프로젝트 이름의 유래?

D&D 주문, [True Seeing](https://www.dandwiki.com/wiki/SRD:True_Seeing).