Skip to content

friTap 2.0.4

Latest
Latest

Choose a tag to compare

View all tags
@monkeywave monkeywave released this 02 Jun 08:50
· 13 commits to main since this release
v2.0.4
875f3b3

Covers: all changes since the last formally published release, v1.4.1.9 (2026-02-25), including the untagged 1.5.x–1.6.3.2 PyPI line and the 2.0.0 → 2.0.4 series.

Introduces a major internal restructuring of the project while preserving the established CLI workflow. The release adds a typed event-driven architecture, modular output handling, a backend abstraction layer, structured configuration objects, an interactive TUI, a modern TypeScript agent path, improved BoringSSL/Cronet handling, .tap replay support, PCAPNG output with embedded TLS secrets, and clearer Frida compatibility handling.

Breaking changes

  • SemVer reset. friTap adopts clean 3-segment versioning (MAJOR.MINOR.PATCH). The old 4-segment MAJOR.MINOR.PATCH.MICRO scheme is retired.
  • Frida pin tightened. Requirements are now frida>=17.0.0,<18.0.0 and frida-tools>=14.0.0,<15.0.0. pip install fritap now refuses to install against frida 18 rather than crashing at runtime.
  • Legacy frida-16 agent removed. The unreachable fritap_agent_legacy.js is gone. Users still on frida 16 should pin fritap>=1.3.3.4,<=1.4.3.0.
  • Frida-major mismatch is now surfaced. A runtime warning fires when frida.__version__'s major doesn't match the supported value. Set FRITAP_STRICT_FRIDA=1 to make the mismatch fatal at startup.
  • Python 3.10+ required (previously 3.8).
  • CI version-guard added (dev/check_compat.py): the next time frida bumps a major version, friTap must bump its major in the same PR. Closes issue #63 (past patch releases silently raised the required frida major).

Headline new features

  • Interactive TUI mode. Running fritap with no arguments launches a Terminal User Interface with a guided setup wizard for device selection, target process, and capture mode. Supports local, USB (Android/iOS), and remote devices, and can automatically install and start frida-server on connected devices.
  • .tap capture format + replay. Plaintext hook output can now be stored in friTap's own .tap capture format and replayed/navigated later: fritap -r saved_capture.tap (-r / --replay). Includes a flow view for inspecting captured streams.
  • Library scanning. --library-scan / -ls pre-scans the target for TLS libraries using tlsLibHunter before hooking, discovering renamed or statically linked libraries.
  • Modern vs. legacy agent mode. --modern (EXPERIMENTAL) opts into the refactored agent code path, unlocking the three-tier BoringSSL keylog chain and improved Cronet hooks on Android/Windows. Legacy remains the default. Known regressions in modern mode vs. legacy: iOS/macOS Cronet, Windows LSASS, and IPsec.
  • Multi-protocol interception. --protocol {tls,ipsec,ssh,all,auto} (default tls). tls covers the TLS family — TLS, QUIC, and OHTTP. ssh and ipsec are exclusive (only their hooks install). all hooks every supported protocol and asks for confirmation (skip with -y / --yes); auto is a script-friendly alias for all.
  • Proxy redirection (in development — not yet usable). --proxy <host:port> is intended to redirect connections to a proxy (e.g., mitmproxy) and bypass certificate pinning. It depends on the separate fritap-proxy package, which is still under active development and not currently usable. The flag is present but should be treated as a preview only; full functionality will land in a future release.
  • Display filters. --filter "<expression>" applies a Wireshark-like display filter, e.g. --filter "http.response.code >= 400 and ip.dst == 10.0.0.1". Its primary purpose is the processing and analysis of captured .tap files.
  • HTTP/2 + HTTP/3 + compression decoding of captured flows (via pylsqpack, hpack, h11, brotli, zstandard).

New architecture (Python core)

The monolithic logger has been decomposed into a modular, backend-agnostic core. The legacy implementation is preserved under friTap/legacy/ behind a _handlers_active guard so the old behavior remains the default.

  • EventBus (friTap/events.py): a publish-subscribe event system replacing the monolithic message handler, with typed events (KeylogEvent, DatalogEvent, ConsoleEvent, ErrorEvent, SessionEvent, …).
  • Backend abstraction (friTap/backends/): an abstract backend interface decoupling core logic from Frida, with a concrete FridaBackend plus scaffolding for GDB, LLDB, and eBPF backends. Selectable via --backend (default: frida).
  • Backend exception hierarchy: 7 backend-agnostic exception types (BackendNotRunningError, BackendInvalidArgumentError, …) mapping onto frida's exception types. ssl_logger.py and friTap.py now raise these instead of importing frida directly.
  • Output handlers (friTap/output/) and sinks (friTap/sinks/): a modular output system covering keylog, JSON, JSONL, PCAP, PCAPNG, console, live Wireshark, and live auto-decrypt.
  • Config dataclasses (friTap/config.py): typed configuration via FriTapConfig, DeviceConfig, OutputConfig, HookingConfig.
  • Builder / fluent API (friTap/api.py): a builder pattern for programmatic friTap usage.
  • Server Manager (friTap/server_manager/): cross-platform frida-server download, deployment, and lifecycle management (Android, iOS, Linux, macOS, Windows).
  • Plugin system (friTap/plugins/): an extensible plugin architecture for custom integrations.
  • Protocols layer (friTap/protocols/): protocol handlers/extractors for TLS and SSH plus a registry.
  • Flow subsystem (friTap/flow/): .tap reader/writer, flow collector, stream buffering, HTTP utilities, and reparse support.
  • Analysis modules (friTap/analysis/): credential extraction, IOC extraction, a protobuf analyzer, and reporters.
  • Filter engine (friTap/filter/): a Wireshark-like display-filter pipeline (lexer, parser, AST, evaluator).
  • Message schemas (friTap/schemas/): typed agent/host/canonical message definitions.
  • Additional new core modules: core.py, session.py, message_router.py, error_handler.py, connection_index.py, inspector.py, constants.py.

New agent engine (TypeScript)

  • HookingPipeline (agent/shared/hooking_pipeline.ts): an accumulation model combining SymbolStrategy, PatternStrategy, and MemoryScanStrategy.
  • HookRegistry (agent/shared/registry.ts): centralized, per-platform hook registration management.
  • Pattern system: default patterns auto-loaded from friTap/patterns/default_patterns.json, with deep-merge support for user-supplied patterns.
  • Restructured agent tree: new core/, platforms/, protocols/, tls/, ssh/, quic/, ohttp/, ipsec/, schemas/, shared/, and legacy/ directories. The main agent was renamed from _ssl_log.js to fritap_agent.js, and startup/loading was refactored.

New / changed CLI flags

Flag Description
-r, --replay <file.tap> Replay and navigate a stored .tap capture.
--modern EXPERIMENTAL: opt into the refactored "modern" agent path (legacy is default).
--library-scan, -ls Pre-scan for TLS libraries with tlsLibHunter before hooking.
--backend {frida,…} Select the instrumentation backend (default: frida).
--protocol {tls,ipsec,ssh,all,auto} Protocol(s) to intercept (default: tls).
--proxy <host:port> Redirect to a proxy (e.g. mitmproxy) and bypass cert pinning. Depends on fritap-proxy, which is still under development and not yet usable.
--filter "<expr>" Wireshark-like display filter for captured traffic.
-y, --yes Auto-confirm interactive prompts (e.g. the --protocol all warning).

Library & hooking improvements

  • Improved hooking of BoringSSL embedded in Android native libraries.
  • Improved Cronet hooks and patterns, including handling of stable_cronet variants.
  • Better OpenSSH integration (available in modern mode).
  • More robust plaintext hooking of SSL_read / SSL_write (_ex) when socket information cannot be obtained.
  • Plaintext PCAP hooks no longer fire during key extraction, preventing capture conflicts — applied across both legacy and modern paths.
  • Ongoing improvements to Android plaintext extraction and to the library support of the modern path.

Error handling & robustness

  • EventBus failure tracking: per-handler failure counting with auto-unsubscribe after 10 failures.
  • Automatic ErrorEvent emission when a handler fails, with a recursion guard.
  • Output handler I/O protection: try/except wrapping around file I/O in the keylog, JSON, PCAPNG, and PCAP handlers.

Testing, CI & documentation

  • Comprehensive test suite: 145 tests (104 unit, 20 integration, 21 agent-compilation).
  • CI pipeline with automated test execution, Ruff lint workflow, and PyPI publish workflow.
  • Re-enabled pytest tests/unit -q in CI (previously commented out); unit suite is green.
  • Test-suite cleanup: removed tests probing a phantom packet-construction API and ~22 tests probing private methods that were never part of SSL_Logger's public surface; replaced with shape/behavior tests against current methods.
  • Re-exported frida/logging symbols in friTap/ssl_logger.py so tests can patch them via the documented entry point.
  • New/expanded docs: getting-started guide, API reference, development guides, pattern-system docs, contributing guidelines, RELEASING.md, and constraints/README.md.

Fixed

  • Startup deadlock with the new protocol state on startup.
  • Bug in detecting whether a user-provided pattern was supplied.
  • Error in the new PCAP writer and improved debug logging.
  • Multiple bugs related to the new versioning scheme.
  • Numerous linter fixes across the new modules.

Changes by patch release (since 2.0.0)

2.0.0 (2026-05-13) — the architectural rewrite, SemVer reset, and frida-pin breaking changes described above, plus improved BoringSSL hooking in Android native libraries.

2.0.1 (2026-05-18)

  • Added missing constraints files (for legacy frida-major installs).
  • Improved Cronet hooking; improved OpenSSH integration.
  • Users can now switch between legacy (default) and modern mode.

2.0.4 (2026-05-19)

  • Ensured plaintext PCAP hooks won't fire during key extraction, now consistently for both legacy and modern paths.
  • Improved library support for the modern path.
  • Further modern-path improvements and the start of improved Android plaintext extraction.

Frida compatibility

friTap targets a single frida major per friTap major. From 2.0.0 onward, every frida-major bump forces a friTap-major bump in the same commit (CI-enforced).

friTap range frida required frida-tools required Constraints file
1.3.0.0 – 1.3.3.3 15.x 10.x – 11.x constraints/frida15.txt
1.3.4.0 – 1.4.3.0 16.x 12.x – 13.x constraints/frida16.txt
1.4.4.0 – 1.6.3.1 17.x 14.x constraints/frida17-legacy.txt
2.0.0+ 17.x 14.x (none — requirements.txt)

If you can't upgrade frida-server, install a matching friTap version via the constraints file above, or use the dev/install_legacy.py helper.

Dependencies

  • Python ≥ 3.10
  • frida (≥ 17, < 18) and frida-tools (≥ 14, < 15)
  • hexdump, scapy, watchdog, rich, textual, pydantic, psutil, platformdirs, h11, hpack
  • tlsLibHunter, pylsqpack, zstandard, brotli (HTTP/2 + HTTP/3 + compression decoding)
  • AndroidFridaManager (Android device management); adb must be in your PATH for Android hooking

Upgrade notes

  • Standard upgrade: pip install --upgrade fritap.
  • You must be on Python 3.10+ and frida 17.x / frida-tools 14.x. Installation will refuse frida 18.
  • Still on frida 15/16 (or needing the 4-segment line on frida 17)? Install a pinned legacy version using the constraints files in the compatibility table, or run python dev/install_legacy.py --frida-major <15|16|17>.
  • The --proxy feature depends on the fritap-proxy package, which is still under development and not currently usable. More on this in a future release.
  • --modern is experimental; keep using the default legacy path for production captures, especially on iOS/macOS Cronet, Windows LSASS, and IPsec targets.
Assets 2
Loading