# 自述文件
trueseeing 是一款快速、准确且坚韧的 iOS/Android 应用漏洞扫描器。我们在 Android 的 Dalvik 虚拟机层面运行——即，我们不关心目标应用是否被混淆。
## 功能特性
目前我们能够：
* 自动扫描应用漏洞，以 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 # 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
要将报告输出到 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）下。另外，你可以将扩展作为 wheel 包分发。我们提供类型信息，这样你不仅可以利用 [zuban](https://github.com/zubanls/zuban) 对扩展进行类型检查，还能从 IDE 获得良好的辅助。详见细节部分。
## 构建
你可以按如下方式构建：
$ docker build -t trueseeing https://github.com/alterakey/trueseeing.git#main
要构建 wheel 包，你可以使用 [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 创建一个，首先设置一个虚拟环境，在其中安装 [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)
* 硬编码的密码/密钥
* 使用静态密钥的维吉尼亚密码
* 使用 ECB 模式
* 客户端代码质量问题 (M7)
* 可反射的 WebView（即此类视图中的 XSS 应可通过 JS 反射升级为远程代码执行）
* 对混合内容使用不安全策略
* 代码篡改 (M8)
* 硬编码的证书
* 逆向工程 (M9)
* 缺少混淆
### 扩展 API
我们的扩展 API 位于 `trueseeing.api` 包下。由于我们提供了类型信息，你的 IDE 将在编写扩展时为你提供帮助。只需确保其（或其语言服务器的）PYTHONPATH 覆盖了包含我们包的虚拟环境；如果你使用 `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`（抽象基类），然后实现 `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_` 为前缀命名的已安装模块。
### 项目名称起源？
龙与地下城法术，[真知术](https://www.dandwiki.com/wiki/SRD:True_Seeing)。
