{"id":20101011,"url":"https://github.com/fkie-cad/fritap","last_synced_at":"2025-10-09T12:37:12.425Z","repository":{"id":43398400,"uuid":"411940494","full_name":"fkie-cad/friTap","owner":"fkie-cad","description":"Simplifying SSL/TLS traffic analysis for researchers by making SSL decryption effortless.","archived":false,"fork":false,"pushed_at":"2025-09-13T18:18:12.000Z","size":34356,"stargazers_count":407,"open_issues_count":6,"forks_count":37,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-09-13T19:45:20.923Z","etag":null,"topics":["android","android-https-capture","binary-analysis","frida","hooking","https","linux","network-analysis","network-capture","network-forensics","security","security-audit","ssl","ssldump","tcpdump","tls"],"latest_commit_sha":null,"homepage":"https://fkie-cad.github.io/friTap/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fkie-cad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING_TO_DOCS.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-30T05:55:40.000Z","updated_at":"2025-09-13T18:18:15.000Z","dependencies_parsed_at":"2024-12-09T16:28:01.308Z","dependency_job_id":"767114d4-c947-425a-81ed-c8a750422e5d","html_url":"https://github.com/fkie-cad/friTap","commit_stats":{"total_commits":472,"total_committers":13,"mean_commits":36.30769230769231,"dds":0.6080508474576272,"last_synced_commit":"fbc9185f52b1fcc5e440569791a17f6dede68dca"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/fkie-cad/friTap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FfriTap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FfriTap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FfriTap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FfriTap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fkie-cad","download_url":"https://codeload.github.com/fkie-cad/friTap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FfriTap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001432,"owners_count":26083078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-https-capture","binary-analysis","frida","hooking","https","linux","network-analysis","network-capture","network-forensics","security","security-audit","ssl","ssldump","tcpdump","tls"],"created_at":"2024-11-13T17:22:56.176Z","updated_at":"2025-10-09T12:37:12.420Z","avatar_url":"https://github.com/fkie-cad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/logo.png\" alt=\"friTap Logo\" width=\"300\"/\u003e\n    \u003cp\u003e\u003c/p\u003e\u003cstrong\u003eReal-time key extraction and traffic decryption for security research\u003c/strong\u003e\u003c/div\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n# friTap\n![version](https://img.shields.io/badge/version-1.4.0.3-blue) [![PyPI version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=py\u0026r=r\u0026ts=1683906897\u0026type=6e\u0026v=1.4.0.3\u0026x2=0)](https://badge.fury.io/py/friTap) [![CI](https://github.com/fkie-cad/friTap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fkie-cad/friTap/actions/workflows/ci.yml)\n[![Ruff](https://github.com/fkie-cad/friTap/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/fkie-cad/friTap/actions/workflows/lint.yml)\n[![Publish status](https://github.com/fkie-cad/friTap/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/fkie-cad/friTap/actions/workflows/publish.yml)\n\nfriTap is a powerful tool designed to assist researchers in analyzing network traffic encapsulated in SSL/TLS. With its ability to automate key extraction, friTap is especially valuable when dealing with malware analysis or investigating privacy issues in applications. By simplifying the process of decrypting and inspecting encrypted traffic, friTap empowers researchers to uncover critical insights with ease.\n\nKey features include seamless support for automated SSL/TLS key extraction, making it an ideal choice for scenarios requiring rapid and accurate traffic analysis. Whether you’re dissecting malicious network behavior or assessing data privacy compliance, friTap streamlines your workflow.\n\nFor more details, explore the [OSDFCon webinar slides](assets/friTapOSDFConwebinar.pdf) or check out our [blog post](https://lolcads.github.io/posts/2022/08/fritap/).\n\n\nThis project was inspired by [SSL_Logger](https://github.com/google/ssl_logger ) and currently supports all major operating systems (Linux, Windows, Android). More platforms and libraries will be added in future releases.\n\n## Key Features\n\nThe main features of friTap are:\n\n- TLS key extraction in real time (`-k key.log`)\n- Decryption of TLS payload as PCAP in real time (`-p plaintext.pcap`)\n- Library analysis and debugging (`--list-libraries`)\n- Integration with Python. [Learn more](https://github.com/fkie-cad/friTap/blob/main/INTEGRATION.md)\n- Support for custom Frida scripts. [Details](https://github.com/fkie-cad/friTap/blob/main/USAGE.md#custom-script-example)\n- Support of most common SSL libraries (OpenSSL, BoringSSL, NSS, GnuTLS, etc.)\n\n## Installation\n\nInstallation is simply a matter of `pip3 install fritap`. This will give you the `fritap` command. You can update an existing `fritap` installation with `pip3 install --upgrade fritap`.\n\n## Usage\n\nOn Linux/Windows/MacOS we can easily attach to a process by entering its name or its PID:\n\n```bash\n$ sudo fritap --pcap mycapture.pcap thunderbird\n```\n\nFor mobile applications we just have to add the `-m` parameter to indicate that we are now attaching (or spawning) an Android or iOS app:\n\n```bash\n$ fritap -m -k keys.log com.example.app\n```\n\nFurther ensure that the frida-server is running on the Android/iOS device. \n\n\nRemember when working with the pip installation you have to invoke the `fritap` command with sudo a little bit different. Either as module:\n```bash\n$ sudo -E python3 -m friTap.friTap --pcap mycapture.pcap thunderbird\n```\nor directly invoking the script:\n```bash\n$ which friTap\n/home/daniel/.local/bin/friTap\n\n$ sudo -E /home/daniel/.local/bin/friTap\n```\n\nfriTap can also be used as a Python library within your project:\n```python\nfrom friTap import SSL_Logger\n```\nFor more details on integrating friTap into your Python project, check out the [INTEGRATION.md](./INTEGRATION.md) guide.\n\nfriTap allows you to enhance its functionality by providing a custom Frida script during your session. This custom script will be invoked just before friTap applies its own hooks. To do so, use the `-c` parameter ([more](./USAGE.md#custom-script-example)).\nMore examples on using friTap can be found in the [USAGE.md](./USAGE.md). A detailed introduction using friTap on Android is under [EXAMPLE.md](./EXAMPLE.md) as well.\n\n## Hooking Libraries Without Symbols\n\nIn certain scenarios, the library we want to hook offers no symbols or is statically linked with other libraries, making it challenging to directly hook functions. For example Cronet (`libcronet.so`) and Flutter (`libflutter.so`) are often statically linked with **BoringSSL**.\n\nDespite the absence of symbols, we can still use friTap for parsing and hooking.\n\n### Hooking by Byte Patterns\n\nTo solve this, we can use friTap with byte patterns to hook the desired functions. You can provide friTap with a JSON file that contains byte patterns for hooking specific functions, based on architecture and platform using the `--patterns \u003cbyte-pattern-file.json\u003e` option.\nIn order to apply the apprioate hooks for the various byte patterns we distinguish between different hooking categories.\nThese categories include:\n\n  -  Dump-Keys\n  -  Install-Key-Log-Callback\n  -  KeyLogCallback-Function\n  -  SSL_Read\n  -  SSL_Write\n\nEach category has a primary and fallback byte pattern, allowing flexibility when the primary pattern fails.\nFor libraries like BoringSSL, where TLS functionality is often statically linked into other binaries, we developed a tool called [BoringSecretHunter](https://github.com/monkeywave/BoringSecretHunter). This tool automatically identifies the necessary byte patterns to hook BoringSSL by byte-pattern matching. BoringSecretHunter is available as a Docker container with pre-configured Ghidra environment:\n\n```bash\n# Create directories and copy target libraries\nmkdir -p binary results\ncp /path/to/libflutter.so binary/\n\n# Run BoringSecretHunter\ndocker run --rm -v \"$(pwd)/binary\":/usr/local/src/binaries -v \"$(pwd)/results\":/host_output boringsecrethunter\n\n# Use generated patterns with friTap\nfritap --patterns results/libflutter.so_patterns.json -k keys.log target_app\n```\n\nMore about the different hooking categories can be found in [usage of byte-patterns in friTap](./USAGE.md#hooking-by-byte-patterns).\n\n### Hooking by Offsets\n\nAlternatively, you can use the `--offsets \u003coffset-file.json\u003e` option to hook functions using known offsets. friTap allows you to specify user-defined offsets (relative to the base address of the targeting SSL/socket library) or absolute virtual addresses for function resolution. This is done through a JSON file, which is passed using the `--offsets` parameter.\n\nIf the `--offsets` parameter is used, friTap will only overwrite the function addresses specified in the JSON file. For functions that are not specified, friTap will attempt to detect the addresses automatically (using symbols).\n\n\n## Problems\n\nThe absence of traffic or incomplete traffic capture in the resulting pcap file (-p \u003cyour.pcap\u003e) may stem from various causes. Before submitting a new issue, consider attempting the following solutions:\n\n### Default Socket Information\n\nThere might be instances where friTap fails to retrieve socket information. In such scenarios, running friTap with default socket information (`--enable_default_fd`) could resolve the issue. This approach utilizes default socket information (127.0.0.1:1234 to 127.0.0.1:2345) for all traffic when the file descriptor (FD) cannot be used to obtain socket details:\n\n```bash\nfritap -m --enable_default_fd -p plaintext.pcap com.example.app\n```\n\n### Handling Subprocess Traffic\n\nTraffic originating from a subprocess could be another contributing factor. To capture this traffic, friTap can leverage Frida's spawn gating feature, which intercepts newly spawned processes using the `--enable_spawn_gating` parameter:\n\n```bash\nfritap -m -p log.pcap --enable_spawn_gating com.example.app\n```\n\n### Library Support exist only for Key Extraction\n\nIn cases where the target library solely supports key extraction (cf. the table below), you can utilize the `-k \u003ckey.log\u003e` parameter alongside full packet capture:\n\n```bash\nfritap -m -p log.pcap --full_capture -k keys.log com.example.app\n```\n\n### Seeking Further Assistance\n\nIf these approaches do not address your issue, please create a detailed issue report to aid in troubleshooting. To facilitate a more effective diagnosis, include the following information in your report:\n\n- The operating system and its version\n- The specific application encountering the issue or a comparable application that exhibits similar problems\n- The output from executing friTap with the specified parameters, augmented with friTap's debug output:\n```bash\nfritap -do -v com.example.app\n```\n\n\n## Supported SSL/TLS implementations and corresponding logging capabilities\n\n```markdown\n| Library                   | Linux         | Windows       | MacOSX   | Android  | iOS          |\n|---------------------------|---------------|---------------|----------|----------|--------------|\n| OpenSSL                   |     Full      | R/W-Hook only |  TBI     |   Full   | TBI          |\n| BoringSSL                 |     Full      | R/W-Hook only |  KeyEo   |   Full   | KeyEo        |\n| NSS                       |     Full      | R/W-Hook only |  TBI     |   TBA    | TBI          |\n| GnuTLS                    | R/W-Hook only | R/W-Hook only |  TBI     |   Full   | TBI          |\n| WolfSSL                   | R/W-Hook only | R/W-Hook only |  TBI     |   Full   | TBI          |\n| MbedTLS                   | R/W-Hook only | R/W-Hook only |  TBI     |   Full   | TBI          |\n| Bouncycastle/Spongycastle |     TBA       |    TBA        |  TBA     |   Full   | TBA          |\n| Conscrypt                 |     TBA       |    TBA        |  TBA     |   Full   | TBA          |\n| S2n-tls                   |     Full      |    LibNO      |  TBA     |   Full   | LibNO        |\n| RusTLS                    |     KeyEo     |    TBI        |  TBI     |   KeyEo  | TBI          |\n```\n**R/W-Hook only** = Logging data sent and received by process\u003cbr\u003e\n**KeyEo** = Only the keying material can be extracted\u003cbr\u003e\n**Full** = Logging data send and received by process + Logging keys used for secure connection\u003cbr\u003e\n**TBA** = To be answered\u003cbr\u003e\n**TBI** = To be implemented\u003cbr\u003e\n**LibNO** = This library is not supported for this plattform\u003cbr\u003e\n\n**We verified the Windows implementations only for Windows 10**\n\n## Dependencies\n\n- [frida](https://frida.re) (`\u003e= 17`)\n- `\u003e= python3.7`\n- click (`python3 -m pip install click`)\n- hexdump (`python3 -m pip install hexdump`)\n- scapy (`python3 -m pip install scapy`)\n- watchdog (`python3 -m pip install watchdog`)\n- importlib.resources  (`python3 -m pip install importlib-resources`)\n- AndroidFridaManager (`python3 -m pip install AndroidFridaManager`)\n- for hooking on Android ensure that the `adb`-command is in your PATH\n\n## Planned features\n\n- [ ] add the capability to alter the decrypted payload\n  - integration with https://github.com/mitmproxy/mitmproxy\n  - integration with http://portswigger.net/burp/\n- [ ] add wine support\n- [x] \u003cstrike\u003eadd Flutter support\u003c/strike\u003e\n- [ ] add further libraries (have a look at this [Wikipedia entry](https://en.wikipedia.org/wiki/Comparison_of_TLS_implementations)):\n  - Botan (BSD license, Jack Lloyd)\n  - LibreSSL (OpenBSD)\n  - Cryptlib (Peter Gutmann)\n  - JSSE (Java Secure Socket Extension, Oracle)\n  - [MatrixSSL](https://github.com/matrixssl/matrixssl) \n  - ...\n- [x] \u003cstrike\u003eWorking with static linked libraries\u003c/strike\u003e\n- [x] \u003cstrike\u003eAdd feature to prototype TLS-Read/Write/SSLKEY functions\u003c/strike\u003e\n- [ ] improve iOS/MacOS support (currently under development)\n\n## Development\n\n### Quick Development Setup\n\nFor developers who want to contribute to friTap, we provide an automated setup:\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/fkie-cad/friTap.git\ncd friTap\n\n# Automated setup (recommended)\npython setup_dev.py\n\n# Manual setup\npip install -r requirements-dev.txt\npip install -e .\nnpm install  # For TypeScript agent compilation\n```\n\n### Testing\n\nfriTap includes a comprehensive testing framework:\n\n```bash\n# Run all fast tests\npython run_tests.py --fast\n\n# Run specific test categories\npython run_tests.py unit           # Unit tests\npython run_tests.py agent          # Agent compilation tests  \npython run_tests.py integration    # Mock integration tests\n\n# Generate coverage report\npython run_tests.py coverage\n```\n\n### Development Dependencies\n\n- **Python 3.7+** with development dependencies (`requirements-dev.txt`)\n- **Node.js 16+** for TypeScript agent compilation\n- **Testing framework**: pytest with comprehensive mocking\n- **Code quality**: black, flake8, mypy, pre-commit hooks\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development setup and testing guide.\n\n## Contribute\n\nContributions are always welcome. Just fork it and open a pull request!\nMore details can be found in the [CONTRIBUTION.md](./CONTRIBUTION.md).\n___\n\n## Changelog\n\nSee the wiki for [release notes](https://github.com/fkie-cad/friTap/releases).\n\n## How to Cite friTap\n\nIf you use **friTap** in your research, please cite the following paper:\n\n\u003e **Daniel Baier, Alexander Basse, Jan-Niclas Hilgert, Martin Lambertz**  \n\u003e *TLS key material identification and extraction in memory: current state and future challenges*  \n\u003e Forensic Science International: Digital Investigation, Volume 49, 2024, 301766.  \n\u003e [https://doi.org/10.1016/j.fsidi.2024.301766](https://doi.org/10.1016/j.fsidi.2024.301766)\n\n### 📄 BibTeX\n\n```bibtex\n@article{baier2024tls,\n  title={TLS key material identification and extraction in memory: current state and future challenges},\n  author={Baier, Daniel and Basse, Alexander and Hilgert, Jan-Niclas and Lambertz, Martin},\n  journal={Forensic Science International: Digital Investigation},\n  volume={49},\n  pages={301766},\n  year={2024},\n  publisher={Elsevier},\n  doi={10.1016/j.fsidi.2024.301766}\n}\n```\n\nAlternatively, you can find a citation file in `CITATION.cff` or use the “Cite this repository” button on GitHub.\n\n## Support\n\nIf you have any suggestions, or bug reports, please create an issue in the Issue Tracker.\n\nIn case you have any questions or other problems, feel free to send an email to:\n\n[daniel.baier@fkie.fraunhofer.de](mailto:daniel.baier@fkie.fraunhofer.de).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkie-cad%2Ffritap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffkie-cad%2Ffritap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkie-cad%2Ffritap/lists"}