macOS Platform Guide¶

This guide covers macOS-specific setup, considerations, and best practices for using friTap on macOS systems.

Prerequisites¶

System Requirements¶

• macOS — friTap does not enforce a version floor. The keylog-offset table has named buckets down to macOS 11 (Big Sur); anything reporting an older major version falls into an unmeasured catch-all (see BoringSSL keylog offsets).
• Administrator access (required for most analysis)
• Python 3.10+ (setup.py sets python_requires=">=3.10")
• Xcode Command Line Tools
• Apple silicon (arm64) or Intel — with one real asymmetry: the run-time keylog-offset derivation decodes arm64 instructions only. On an Intel Mac friTap silently falls back to the version table.

Development Environment Setup¶

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew (recommended package manager)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python (if not using system Python)
brew install python@3.12

# Install friTap
pip3 install fritap

System Setup¶

SIP (System Integrity Protection)¶

# Check SIP status
csrutil status

To disable SIP:

1. Boot into Recovery:
   • Apple silicon: shut down, then press and hold the power button until "Loading startup options" appears, then choose Options → Continue.
   • Intel: hold Command+R during boot.
2. Open Terminal from the Utilities menu.
3. Run csrutil disable.
4. Reboot normally.

Re-enable it with csrutil enable from Recovery when you are done.

Frida Installation¶

# Install frida-tools
pip3 install frida-tools

# Verify installation
frida --version

# Test local device
frida-ps

BPF Devices (only for -f/--full_capture)¶

friTap's normal --pcap output is synthesized from the decrypted payloads — it does not read from the network at all and needs no BPF access. Raw packet capture is only used by -f/--full_capture, which drives scapy and therefore needs read/write access to a /dev/bpf* node:

# Inspect the BPF nodes
ls -la /dev/bpf*

# The simplest correct answer: run the full capture as root
sudo fritap -f -p traffic.pcap -k keys.log -s "$(pwd)/my_client"

friTap Usage on macOS¶

Spawn vs. attach: pass -s when you give a path or a command¶

-s/--spawn is opt-in. Without it friTap attaches to an already-running process, and the positional argument is matched against running processes. If you pass an executable path or a command with arguments, you must add -s, otherwise friTap looks for a process that does not exist.

# Attach to a process that is already running (match by name or PID)
sudo fritap -k keys.log "Google Chrome"
sudo fritap -k keys.log 4711

# Spawn: any executable path, or a command with arguments
sudo fritap -s -k keys.log "$(pwd)/my_client"
sudo fritap -s -k keys.log curl https://httpbin.org/get
sudo fritap -s -k keys.log python3 my_script.py

sudo fritap -do -v -k keys.log my_client > fritap.log 2>&1
grep -i boringssl fritap.log

Native Apple-stack applications¶

Apple's Network.framework, CFNetwork and URLSession all run their TLS on top of /usr/lib/libboringssl.dylib, which friTap hooks. A plain Swift URLSession client is capturable: the verification rig in dev/macos_verify/ drives exactly that path and gets well-formed keys attributed to libboringssl.dylib.

Check a target before you spend time on it:

# Is it signed with the hardened runtime / library validation?
codesign -d -vvv "/Applications/App.app" 2>&1

# Does it carry the debugging entitlement friTap needs?
codesign -d --entitlements - "/Applications/App.app" 2>&1 | grep -i get-task-allow

# Which TLS libraries does the binary link against?
otool -L "/Applications/App.app/Contents/MacOS/App" | grep -Ei "ssl|tls|boringssl|Network"

Only Apple's legacy SecureTransport (libcoretls, SSLCreateContext, CFStream) has no friTap hooks at all.

Command-Line Applications¶

# curl (links against LibreSSL on macOS → keys *and* plaintext)
sudo fritap -s -k curl_keys.log curl https://httpbin.org/get

# Python
sudo fritap -s -k python_keys.log python3 my_script.py

# Node.js
sudo fritap -s -k node_keys.log node app.js

Application Bundle Analysis¶

# Find the executable inside the bundle
ls -la "/Applications/Some App.app/Contents/MacOS/"

# Spawn it by path
sudo fritap -s -k app_keys.log "/Applications/Some App.app/Contents/MacOS/Some App"

# Or attach to it once it is running
sudo fritap -k app_keys.log "Some App"

SSH Targets¶

SSH hooks are registered under protocol: "ssh", and registry entries are protocol-gated. The default is --protocol tls, so an SSH capture must select the protocol explicitly:

# OpenSSH client — SHARED_SECRET keylog
sudo fritap --protocol ssh -k ssh_keys.log -s ssh user@remote.host

# Both families in one session
sudo fritap --protocol all -k keys.log -s ssh user@remote.host

Dry Run: --probe¶

--probe loads the agent, reports the detected platform and the platform code path it selected, installs no hooks, and exits. It produces no keys, pcap or plaintext, and exits non-zero if the bundle does not acknowledge probe mode — which also makes it a quick check that the loaded bundle is current.

sudo fritap --probe -s "$(pwd)/my_client" > probe.log 2>&1
grep -i "platform" probe.log

Bounding Agent Load: --script-load-timeout¶

--script-load-timeout <seconds> bounds Frida's script.load(), which blocks until the agent finishes its startup, so a wedged load aborts with a diagnostic instead of hanging forever.

• Default: 20 seconds.
• Any non-positive value disables the bound (--script-load-timeout 0).
• The value is tripled when --patterns, --library-scan or --scan-keys-region is requested, because those scan inside the load.
• It is a give-up, not a cancellation: the load thread is abandoned, not killed.

# Large pattern scan on a slow target
sudo fritap --patterns macos_patterns.json --script-load-timeout 60 -k keys.log my_client

# Disable the bound entirely while debugging
sudo fritap --script-load-timeout 0 -do -k keys.log my_client > fritap.log 2>&1

SSL/TLS Libraries on macOS¶

agent/platforms/macos.ts registers twelve entries for macOS:

| OpenSSH | ssh, sshd, sshd-session, scp, sftp-server | SSH | Needs --protocol ssh. |

Apple BoringSSL keylog offsets¶

Apple does not export SSL_CTX_set_keylog_callback from /usr/lib/libboringssl.dylib, so friTap cannot simply call it. Instead it:

1. hooks the exported SSL_CTX_set_info_callback, and
2. writes friTap's keylog callback pointer directly into the live SSL_CTX struct at a byte offset.

The offset is derived at run time from the target's own binary: friTap disassembles the non-exported setter, whose whole body is str x1, [x0, #imm]; ret, and reads #imm. This decoding is arm64-only. If it fails — or on Intel — friTap falls back to a version table (agent/legacy/tls/shared/apple_keylog_offset.ts):

Derive the ground truth for your own machine, or check the tables in CI:

# Print the offsets derived from the binaries on this machine
python dev/derive_boringssl_keylog_offset.py

# Compare the derived values against friTap's checked-in tables (exit 1 on conflict)
python dev/derive_boringssl_keylog_offset.py --check

LibreSSL (best plaintext support on macOS)¶

/usr/lib/libssl.48.dylib is the one macOS library with full plaintext support: unlike Apple's BoringSSL, its SSL_get_fd works, so SSL_read/SSL_write hooks are enabled and you get decrypted payloads, not just keys.

# curl and many other CLI tools link against system LibreSSL
sudo fritap -s -k libressl_keys.log -p libressl.pcap curl https://httpbin.org/get

Python Applications (Special Support)¶

# Python's bundled OpenSSL is matched by path and gets keylog + plaintext hooks
sudo fritap -s -k python_keys.log python3 script.py

sudo fritap -s -k python_keys.log python3 -c \
  "import urllib.request; urllib.request.urlopen('https://example.com')"

Pattern-based Hooking¶

For statically-linked TLS (Chromium frameworks, Flutter, stripped binaries), supply byte patterns:

sudo fritap --patterns macos_patterns.json -k keys.log -s "$(pwd)/my_client"

See Pattern-Based Hooking for the file format.

Library Detection Commands¶

# Which SSL/TLS libraries does a binary link against?
otool -L "/path/to/application" | grep -E "(ssl|tls|crypto|boringssl)"

# Framework dependencies
otool -L "/Applications/App.app/Contents/MacOS/App" | grep -Ei "security|network"

# Which modules friTap actually sees in the live process
sudo fritap -ll "Some App" > libs.log 2>&1

Apple Silicon Considerations¶

# Check the architectures in a binary
file "/Applications/App.app/Contents/MacOS/App"
lipo -info "/Applications/App.app/Contents/MacOS/App"

Rebuilding the Agent¶

friTap loads a pre-compiled agent bundle, friTap/fritap_agent.js. Nothing compiles agent/*.ts at run time, so editing the TypeScript changes nothing until you rebuild:

./dev/compile_agent.sh

[compile_agent.sh] done. Agent: <bytes> bytes

To point friTap at a bundle somewhere else, set FRITAP_AGENT_BUNDLE. Resolution order is:

1. FRITAP_AGENT_BUNDLE — an arbitrary bundle path, not ABI-filtered;
2. an ABI-matched fritap.agent_bundle entry point;
3. the shipped friTap/fritap_agent.js.

FRITAP_AGENT_BUNDLE=/path/to/fritap_agent.js sudo -E fritap -k keys.log my_client

Verifying a macOS Build¶

dev/macos_verify/verify.sh is a device-free, end-to-end check of the Apple TLS capture path. It builds a loopback HTTPS server plus a Swift URLSession client (so it exercises CFNetwork → libboringssl.dylib, the exact path friTap hooks) and drives friTap against them — no outbound network, nothing that expires.

./dev/macos_verify/verify.sh          # run every applicable check
./dev/macos_verify/verify.sh --list   # list the checks without running them
./dev/macos_verify/verify.sh --keep   # keep the work dir to inspect raw output

Nine checks: the Python unit suite, a deterministic compile_agent.sh build, attach capture, spawn capture (without killing the target), both agent handshake stages, --script-load-timeout firing and being disabled, --probe reporting without installing hooks, and child gating instrumenting a second process. Exit code is 0 only if every applicable check passed; inapplicable checks report SKIP. See dev/macos_verify/README.md for what each check proves and how to drive the rig by hand.

Troubleshooting macOS Issues¶

The Target Dies During Instrumentation¶

This is the failure mode dev/macos_verify/ exists to regression-test, and the symptom behind fkie-cad/friTap#65. Work down this ladder:

# 1. Does the agent even load? --probe installs no hooks.
sudo fritap --probe -s "$(pwd)/my_client" > probe.log 2>&1
#    Survives --probe  → the agent is fine, the crash is in hook installation.
#    Dies under --probe → the problem is the load/bootstrap, not the hooks.

# 2. Attach instead of spawn — spawn-mode bootstrap is its own failure class.
sudo fritap -k keys.log my_client > fritap.log 2>&1

# 3. Try --modern, which does NOT write into SSL_CTX.
sudo fritap --modern -k keys.log my_client > modern.log 2>&1
#    Surviving under --modern points at a wrong keylog offset (see the table above).
#    Dying under --modern proves nothing — it installs its own additional hooks.

# 4. Collect the platform report for a bug report.
sudo fritap -do -v -k keys.log my_client > debug.log 2>&1
grep "Agent platform report" debug.log

Include that Agent platform report: … (agent ABI N) line, your sw_vers output and csrutil status when you report the issue.

Cannot Attach / Permission Denied¶

# SIP must normally be off for local attach
csrutil status

# Run as root
sudo fritap -k keys.log my_client

# Is the target signed in a way that forbids instrumentation?
codesign -d -vvv "/Applications/App.app" 2>&1
codesign -d --entitlements - "/Applications/App.app" 2>&1 | grep -i get-task-allow

Hardened runtime, library validation, or a missing com.apple.security.cs.get-task-allow entitlement all block injection — friTap probes for exactly these and says so. Apple's SIP-protected platform binaries stay unattachable regardless.

Application Won't Start¶

# Check the quarantine attribute
xattr -l "/Applications/App.app"

# Remove it
sudo xattr -rd com.apple.quarantine "/Applications/App.app"

# Verify the signature is intact
codesign -v "/Applications/App.app"

No Keys Captured¶

# Confirm friTap hooked anything at all
sudo fritap -do -v -k keys.log my_client > fritap.log 2>&1
grep -Ei "hook|boringssl|libressl|keylog" fritap.log

# Verify the keylog lines are well formed (must print 0)
grep -cvE '^[A-Z_0-9]+ [0-9A-F]+ [0-9A-F]+$' keys.log

If the target is a Chromium-based browser, see the warning above — its statically-linked BoringSSL is not matched by any macOS registry entry.

Network Interface Issues¶

# List network interfaces
ifconfig

# Check raw capture works at all (only relevant for -f/--full_capture)
sudo tcpdump -i en0 -c 1

System Log Monitoring¶

# Watch for SSL/TLS related system messages during a session
log stream --predicate 'eventMessage CONTAINS "SSL" OR eventMessage CONTAINS "TLS"'

Console.app lives at /System/Applications/Utilities/Console.app on modern macOS.

Wireshark Integration¶

# Install Wireshark
brew install --cask wireshark

# Live analysis via the named pipe
sudo fritap -l -s "$(pwd)/my_client"

# Or decrypt an offline capture with the extracted keys
wireshark -o "tls.keylog_file:keys.log" traffic.pcap

Best Practices for macOS¶

1. System Preparation¶

• Disable SIP on a test machine, not a production one, and re-enable it afterwards.
• Install the Xcode Command Line Tools.
• Rebuild the agent bundle after any agent/*.ts change (./dev/compile_agent.sh).

2. Application Analysis¶

# Start simple: keys only
sudo fritap -k keys.log my_client > fritap.log 2>&1

# Then add pcap and metadata
sudo fritap -k keys.log --pcap traffic.pcap -j metadata.json my_client > fritap.log 2>&1

libraries_detected is a top-level array and lists only libraries friTap actually hooked — so a library missing from it was never instrumented, whatever else the log said:

jq '.libraries_detected' metadata.json

3. Security Considerations¶

• Use dedicated test systems and test accounts.
• Do not disable security features on production machines.
• Re-enable everything you turned off once the analysis is done.

4. Data Organization¶

# Create an analysis workspace
mkdir -p ~/Desktop/friTap_Analysis
cd ~/Desktop/friTap_Analysis

# Organize by date and application
mkdir "$(date +%Y%m%d)_ApplicationName"
cd "$(date +%Y%m%d)_ApplicationName"

# Run with organized output (stdout to a file, never a pipe)
sudo fritap -k keys.log --pcap traffic.pcap -j metadata.json my_client > fritap.log 2>&1

Next Steps¶

• iOS Analysis: Check iOS Platform Guide for mobile analysis
• Windows Analysis: See Windows Platform Guide
• Linux Analysis: Review Linux Platform Guide
• Advanced Features: Learn about Pattern-based Hooking
• Troubleshooting: Check Common Issues