fkie-cad/friTap

GitHub: fkie-cad/friTap

基于 Frida 的 SSL/TLS 流量解密工具，通过动态 Hook 从进程内存中提取密钥材料，实现对加密网络流量的实时解密和分析。

Stars: 471 | Forks: 42

Real-time key extraction and traffic decryption for security research

# friTap ![version](https://img.shields.io/badge/version-1.4.6.0-blue) [![PyPI version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=py&r=r&ts=1683906897&type=6e&v=1.4.6.0&x2=0)](https://badge.fury.io/py/friTap) [![CI](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/e698274a86024103.svg)](https://github.com/fkie-cad/friTap/actions/workflows/ci.yml) [![Ruff](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/2ae2d12d02024104.svg)](https://github.com/fkie-cad/friTap/actions/workflows/lint.yml) [![Publish status](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/40580f15c6024105.svg)](https://github.com/fkie-cad/friTap/actions/workflows/publish.yml) friTap 是一款强大的工具，旨在协助研究人员分析封装在 SSL/TLS 中的网络流量。凭借其自动提取密钥的能力，friTap 在处理恶意软件分析或调查应用程序隐私问题时显得尤为宝贵。通过简化解密和检查加密流量的过程，friTab 让研究人员能够轻松发现关键洞察。主要功能包括对自动 SSL/TLS 密钥提取的无缝支持，使其成为需要快速准确进行流量分析场景的理想选择。无论您是正在剖析恶意网络行为还是评估数据隐私合规性，friTap 都能为您的工作流程提速。欲了解更多详情，请浏览 [OSDFCon 网络研讨会幻灯片](assets/friTapOSDFConwebinar.pdf) 或查看我们的 [博客文章](https://lolcads.github.io/posts/2022/08/fritap/)。该项目受 [SSL_Logger](https://github.com/google/ssl_logger ) 启发，目前支持所有主要操作系统。未来版本中将添加更多平台和库支持。 ## 主要功能 friTap 的主要功能包括： - 实时 TLS 密钥提取 (`-k key.log`) - 实时将 TLS 载荷解密为 PCAP (`-p plaintext.pcap`) - 库分析与调试 (`--list-libraries`) - Python 集成。[了解更多](https://github.com/fkie-cad/friTap/blob/main/INTEGRATION.md) - 支持自定义 Frida 脚本。[详情](https://github.com/fkie-cad/friTap/blob/main/USAGE.md#custom-script-example) - 支持大多数常见的 SSL 库（OpenSSL, BoringSSL, NSS, GnuTLS 等） ## 安装安装非常简单，只需执行 `pip3 install fritap`。这将为您安装 `fritap` 命令。您可以使用 `pip3 install --upgrade fritap` 来更新现有的 `fritap` 安装。 ## 使用在 Linux/Windows/MacOS 上，我们可以通过输入进程名或其 PID 轻松附加到进程： ``` $ sudo fritap --pcap mycapture.pcap thunderbird ``` 对于移动应用程序，我们只需添加 `-m` 参数来表明我们要附加（或启动）一个 Android 或 iOS 应用： ``` $ fritap -m -k keys.log com.example.app ``` 此外，请确保 frida-server 正在 Android/iOS 设备上运行。请记住，在使用 pip 安装版时，您调用 `fritap` 命令时需要使用 sudo，且写法略有不同。可以作为模块调用： ``` $ sudo -E python3 -m friTap.friTap --pcap mycapture.pcap thunderbird ``` 或者直接调用脚本： ``` $ which friTap /home/daniel/.local/bin/friTap $ sudo -E /home/daniel/.local/bin/friTap ``` friTap 也可以作为 Python 库在您的项目中使用： ``` from friTap import SSL_Logger ``` 有关将 friTap 集成到您的 Python 项目的更多详情，请查看 [INTEGRATION.md](./INTEGRATION.md) 指南。 friTap 允许您在会话期间通过提供自定义 Frida 脚本来增强其功能。该自定义脚本将在 friTap 应用其自身的 hooks 之前被调用。为此，请使用 `-c` 参数（[更多](./USAGE.md#custom-script-example)）。关于使用 friTap 的更多示例可以在 [USAGE.md](./USAGE.md) 中找到。在 Android 上使用 friTap 的详细介绍也可参见 [EXAMPLE.md](./EXAMPLE.md)。 ## Hook 无符号库在某些场景下，我们想要 hook 的库不提供符号，或者是与其他库静态链接的，这使得直接 hook 函数具有挑战性。例如，Cronet (`libcronet.so`) 和 Flutter (`libflutter.so`) 通常静态链接了 **BoringSSL**。尽管没有符号，我们仍然可以使用 friTap 进行解析和 hook。 ### 通过字节模式 Hook 为了解决这个问题，我们可以使用带有字节模式的 friTap 来 hook 目标函数。您可以为 friTap 提供一个 JSON 文件，其中包含基于架构和平台的用于 hook 特定函数的字节模式，使用 `--patterns ` 选项。为了对各种字节模式应用适当的 hooks，我们区分了不同的 hook 类别。这些类别包括： - Dump-Keys - Install-Key-Log-Callback - KeyLogCallback-Function - SSL_Read - SSL_Write 每个类别都有主要和备用字节模式，以便在主要模式失败时提供灵活性。对于像 BoringSSL 这样的库，其 TLS 功能通常静态链接到其他二进制文件中，我们开发了一个名为 [BoringSecretHunter](https://github.com/monkeywave/BoringSecretHunter) 的工具。该工具通过字节模式匹配自动识别 hook BoringSSL 所需的字节模式。BoringSecretHunter 作为 Docker 容器提供，并预配置了 Ghidra 环境： ``` # 创建目录并复制目标库 mkdir -p binary results cp /path/to/libflutter.so binary/ # 运行 BoringSecretHunter docker run --rm -v "$(pwd)/binary":/usr/local/src/binaries -v "$(pwd)/results":/host_output boringsecrethunter # 将生成的 patterns 用于 friTap fritap --patterns results/libflutter.so_patterns.json -k keys.log target_app ``` 关于不同 hook 类别的更多信息可以在 [friTap 中字节模式的使用](./USAGE.md#hooking-by-byte-patterns) 中找到。 ### 通过偏移量 Hook 或者，您可以使用 `--offsets ` 选项，利用已知的偏移量来 hook 函数。friTap 允许您指定用户定义的偏移量（相对于目标 SSL/socket 库的基地址）或绝对虚拟地址来进行函数解析。这是通过一个 JSON 文件完成的，并使用 `--offsets` 参数传递。如果使用了 `--offsets` 参数，friTap 将只覆盖 JSON 文件中指定的函数地址。对于未指定的函数，friTap 将尝试（使用符号）自动检测地址。 ## 问题生成的 pcap 文件 (-p ) 中出现流量缺失或不完整可能源于多种原因。在提交新 issue 之前，请尝试以下解决方案： ### 默认 Socket 信息在某些情况下，friTap 可能无法检索 socket 信息。在这些场景中，使用默认 socket 信息 (`--enable_default_fd`) 运行 friTap 可能会解决问题。当无法使用文件描述符 (FD) 获取 socket 详细信息时，此方法会为所有流量使用默认 socket 信息 (127.0.0.1:1234 到 127.0.0.1:2345)： ``` fritap -m --enable_default_fd -p plaintext.pcap com.example.app ``` ### 处理子进程流量来自子进程的流量可能是另一个影响因素。为了捕获此流量，friTap 可以利用 Frida 的 spawn gating 功能，该功能使用 `--enable_spawn_gating` 参数拦截新生成的进程： ``` fritap -m -p log.pcap --enable_spawn_gating com.example.app ``` ### 库支持仅限于密钥提取如果目标库仅支持密钥提取（参见下表），您可以结合完整数据包捕获使用 `-k ` 参数： ``` fritap -m -p log.pcap --full_capture -k keys.log com.example.app ``` ### 寻求进一步帮助如果这些方法未能解决您的问题，请创建一个详细的 issue 报告以帮助排查。为了促进更有效的诊断，请在报告中包含以下信息： - 操作系统及其版本 - 遇到问题的特定应用程序，或表现出类似问题的可比应用程序 - 使用指定参数执行 friTap 的输出，并附加上 friTap 的调试输出： ``` fritap -do -v com.example.app ``` ## 支持的 SSL/TLS 实现及相应的日志记录能力 ``` | Library | Linux | Windows | MacOSX | Android | iOS | |---------------------------|---------------|---------------|----------|----------|--------------| | OpenSSL | Full | R/W-Hook only | TBI | Full | TBI | | BoringSSL | Full | R/W-Hook only | KeyEo | Full | KeyEo | | NSS | Full | R/W-Hook only | TBI | TBA | TBI | | GnuTLS | R/W-Hook only | R/W-Hook only | TBI | Full | TBI | | WolfSSL | R/W-Hook only | R/W-Hook only | TBI | Full | TBI | | MbedTLS | R/W-Hook only | R/W-Hook only | TBI | Full | TBI | | Bouncycastle/Spongycastle | TBA | TBA | TBA | Full | TBA | | Conscrypt | TBA | TBA | TBA | Full | TBA | | S2n-tls | Full | LibNO | TBA | Full | LibNO | | RusTLS | KeyEo | TBI | TBI | KeyEo | TBI | ``` **R/W-Hook only** = 仅记录进程发送和接收的数据
**KeyEo** = 仅可提取密钥材料
**Full** = 记录进程发送和接收的数据 + 记录用于安全连接的密钥
**TBA** = 待确定
**TBI** = 待实现
**LibNO** = 此平台不支持该库
**我们仅在 Windows 10 上验证了 Windows 实现** ## 依赖 - [frida](https://frida.re) (`>= 17`) - `>= python3.10` - click (`python3 -m pip install click`) - hexdump (`python3 -m pip install hexdump`) - scapy (`python3 -m pip install scapy`) - watchdog (`python3 -m pip install watchdog`) - AndroidFridaManager (`python3 -m pip install AndroidFridaManager`) - textual (`python3 -m pip install textual`) - rich (`python3 -m pip install rich`) - 若要在 Android 上进行 hook，请确保 `adb` 命令位于您的 PATH 中 ## 计划功能 - [ ] 添加更改解密载荷的能力 - 与 https://github.com/mitmproxy/mitmproxy 集成 - 与 http://portswigger.net/burp/ 集成 - [ ] 添加 wine 支持 - [x] ~~添加 Flutter 支持~~ - [ ] 添加更多库（请参阅此 [维基百科条目](https://en.wikipedia.org/wiki/Comparison_of_TLS_implementations)）： - Botan (BSD license, Jack Lloyd) - LibreSSL (OpenBSD) - Cryptlib (Peter Gutmann) - JSSE (Java Secure Socket Extension, Oracle) - [MatrixSSL](https://github.com/matrixssl/matrixssl) - ... - [x] ~~处理静态链接库~~ - [x] ~~添加 TLS-Read/Write/SSLKEY 函数原型设计功能~~ - [ ] 改进 iOS/MacOS 支持（目前正在开发中） ## 开发 ### 快速开发设置对于想要为 friTap 做贡献的开发者，我们提供了自动化设置： ``` # 克隆并配置开发环境 git clone https://github.com/fkie-cad/friTap.git cd friTap # 自动设置（推荐） python setup_dev.py # 手动设置 pip install -r requirements-dev.txt pip install -e . npm install # For TypeScript agent compilation ``` ### 测试 friTap 包含一个全面的测试框架： ``` # 运行所有快速测试 python run_tests.py --fast # 运行特定测试类别 python run_tests.py unit # Unit tests python run_tests.py agent # Agent compilation tests python run_tests.py integration # Mock integration tests # 生成覆盖率报告 python run_tests.py coverage ``` ### 开发依赖 - **Python 3.7+** 及开发依赖 (`requirements-dev.txt`) - **Node.js 16+** 用于 TypeScript agent 编译 - **测试框架**：pytest 及全面的 mocking - **代码质量**：black, flake8, mypy, pre-commit hooks 详细的开发设置和测试指南请参见 [DEVELOPMENT.md](./DEVELOPMENT.md)。 ## 贡献我们随时欢迎贡献。只需 Fork 本项目并提交 Pull Request！更多详情可在 [CONTRIBUTION.md](./CONTRIBUTION.md) 中找到。 ## 更新日志请参阅 Wiki 中的 [发布说明](https://github.com/fkie-cad/friTap/releases)。 ## 如何引用 friTap 如果您在研究中使用了 **friTap**，请引用以下论文： ### 📄 BibTeX ``` @article{baier2024tls, title={TLS key material identification and extraction in memory: current state and future challenges}, author={Baier, Daniel and Basse, Alexander and Hilgert, Jan-Niclas and Lambertz, Martin}, journal={Forensic Science International: Digital Investigation}, volume={49}, pages={301766}, year={2024}, publisher={Elsevier}, doi={10.1016/j.fsidi.2024.301766} } ``` 或者，您可以在 `CITATION.cff` 中找到引用文件，或使用 GitHub 上的 “Cite this repository” 按钮。 ## 支持如果您有任何建议或错误报告，请在 Issue Tracker 中创建 issue。如果您有任何问题或其他疑问，请随时发送邮件至： [daniel.baier@fkie.fraunhofer.de](mailto:daniel.baier@fkie.fraunhofer.de)。