⚠️ DISCLAIMER: This repository is strictly for educational and authorized security research. Only test on devices and accounts you own. Unauthorized interception of traffic is illegal.

---

🎯 What You'll Learn

🔐 SSL/TLS Pinning Theory & Implementation

🛠️ Frida & Objection Dynamic Instrumentation

🕵️ Traffic Interception mitmproxy & Burp Suite

🧠 Advanced Hooks Custom Frida Scripts

⚖️ Ethics & Law Responsible Research

---

📚 Table of Contents

• 🚀 Quick Start
• 📖 Lesson Plan
• 📂 Repository Structure
• 🔧 Scripts Reference
• 💡 How SSL Pinning Works
• 🧪 Lab Setup
• ⚠️ Legal & Ethics
• 🤝 Contributing
• ⭐ Support This Project

---

🚀 Quick Start

Step 1 — Clone the repository

git clone https://github.com/algoanhaf/facebook-ssl-pinning-bypass.git
cd facebook-ssl-pinning-bypass

Step 2 — Run the automated setup (creates the virtual environment, installs every tool, and pushes a matching frida-server)

./setup.sh
source ssl-lab/bin/activate

Step 3 — Start frida-server on your device

adb shell su -c "/data/local/tmp/frida-server &"

Step 4 — Run the bypass

python run.py com.facebook.katana --script all

That's it. Open the app, log in, and watch the traffic in mitmproxy. Full detail lives in Lesson 3.

---

📖 Lesson Plan

Lesson	Topic	What You Learn	Level
01	🛠️ Environment Setup	ADB, Python, Frida, Objection, mitmproxy, Android emulator configuration	🟢 Beginner
02	🔐 SSL/TLS Concepts	Certificate vs public key pinning, how Facebook implements it, why proxies fail	🟡 Intermediate
03	🔬 Tool Walkthrough	Objection one-liner, raw Frida scripting, mitmproxy traffic inspection	🟡 Intermediate
04	🧠 Advanced Techniques	Writing custom hooks, CT bypass, anti-Frida detection, APK patching concepts	🔴 Advanced
05	⚖️ Ethics & Legal	Legal boundaries, lab rules, responsible disclosure, bug bounty programs	🟢 All Levels

---

📂 Repository Structure

📁 facebook-ssl-pinning-bypass/
│
├── 📁 lessons/
│   ├── 📄 01_setup.md          ← Environment setup (ADB, Frida, emulator)
│   ├── 📄 02_concepts.md       ← SSL/TLS pinning theory
│   ├── 📄 03_walkthrough.md    ← Step-by-step bypass walkthrough
│   ├── 📄 04_advanced.md       ← Advanced hooking techniques
│   └── 📄 05_ethics.md         ← Ethics, law & responsible disclosure
│
├── 📁 scripts/
│   ├── 📜 ssl_bypass_all.js    ← ★ Start here — comprehensive bypass
│   ├── 📜 ssl_bypass_basic.js  ← Hook Android TrustManager
│   └── 📜 ssl_bypass_okhttp.js ← Hook OkHttp3 CertificatePinner
│
├── 📁 .github/                 ← Issue & PR templates
├── 🐍 run.py                   ← Spawns the app and injects a script
├── ⚙️ setup.sh                 ← One-command lab bootstrap
├── 📋 requirements.txt         ← Pinned Python dependencies
├── 🔒 SECURITY.md              ← Responsible disclosure policy
├── 🤝 CONTRIBUTING.md          ← Contribution guidelines
├── 📄 README.md
└── 📄 LICENSE

---

🔧 Scripts Reference

📜 ssl_bypass_all.js — Recommended starting script

The comprehensive bypass script. Hooks all major pinning layers:

Hook	Target	What It Does
1	javax.net.ssl.SSLContext.init()	Replaces TrustManager with permissive version
2	HttpsURLConnection.setDefaultHostnameVerifier()	Accepts all hostnames
3	okhttp3.CertificatePinner.check()	Bypasses OkHttp3 pin check
4	com.squareup.okhttp.CertificatePinner	Bypasses OkHttp2 pin check
5	NetworkSecurityTrustManager.checkPins()	Bypasses Android 7+ NSC pins
6	Conscrypt TrustManagerImpl	Bypasses deep SSL provider check
7	Dynamic class enumeration	Auto-discovers anonymous TrustManager classes

python run.py com.facebook.katana --script all

📜 ssl_bypass_basic.js — TrustManager hooks

Targets the standard Java SSL stack. Good for apps that don't use OkHttp.

python run.py <package_name> --script basic

📜 ssl_bypass_okhttp.js — OkHttp-specific hooks

Targets OkHttp2 and OkHttp3 CertificatePinner plus Conscrypt internals.

python run.py <package_name> --script okhttp

---

💡 How SSL Pinning Works

Without Pinning:              With Pinning (Facebook):
┌──────────┐                  ┌──────────┐
│  App     │                  │  App     │
│          │                  │          │
│ ✅ Is cert│                  │ ✅ Is cert│  ← CA validation (same)
│ signed   │                  │ signed   │
│ by a     │                  │ by a     │
│ trusted  │                  │ trusted  │
│ CA?      │                  │ CA?      │
│          │                  │          │
│ ✅ YES   │                  │ ✅ YES   │
│ → ALLOW  │                  │          │
└──────────┘                  │ 🔒 Does  │  ← Pin check (extra step)
                              │ public   │
                              │ key hash │
                              │ match?   │
                              │          │
                              │ ❌ NO    │  ← Burp/mitmproxy cert fails here
                              │ → BLOCK  │
                              └──────────┘

Facebook uses 3 pinning layers:

1. OkHttp3 CertificatePinner — primary, checks SHA-256 of public key
2. Custom X509TrustManager — secondary validation layer
3. Network Security Config — OS-level pins (Android 7+)

---

🧪 Lab Setup

Prerequisites Checklist

[ ] Rooted Android device or emulator (Genymotion / AVD "Google APIs" image)
[ ] Android 9.0 – 12.0 recommended (less aggressive anti-tampering)
[ ] ADB installed and device recognized (adb devices)
[ ] frida-server pushed to /data/local/tmp/ and running
[ ] mitmproxy CA installed in SYSTEM certificate store (not just user store)
[ ] Python 3.8+ with frida==16.5.9, frida-tools, objection, mitmproxy
[ ] Dummy Facebook account (NEVER use your real account)

Verify Your Setup

adb devices
frida-ps -U | grep facebook
frida --version
objection --version
mitmproxy --version

adb devices shows your device, frida-ps -U confirms the client reaches the server, and frida --version must match the frida-server version on the device.

Common Fixes

Problem	Solution
Unable to connect to frida-server	adb shell su -c "/data/local/tmp/frida-server &"
App crashes after hook	Use -f (spawn) mode, not -n (attach)
No traffic in mitmproxy	Re-check proxy IP: adb shell settings get global http_proxy
Frida version mismatch	Re-download frida-server to match pip show frida version
mitmproxy CA not trusted	Push cert to /system/etc/security/cacerts/ (needs root)

---

⚠️ Legal & Ethics

✅ Legal	❌ Illegal
Testing on your own device + dummy account Intercepting your own traffic in a private lab Reporting vulnerabilities via bug bounty Security research on apps you developed	Intercepting someone else's traffic Targeting accounts you don't own Distributing patched APKs Scraping user data without authorization

Three Lab Rules — confirm all before every session:

1. 📱 The device is yours
2. 👤 The account is yours (dummy account)
3. 🌐 The network is yours (isolated lab network)

Found a real vulnerability? Report it responsibly:

• 🐛 Meta Bug Bounty: hackerone.com/facebook
• 📧 Facebook WhiteHat: facebook.com/whitehat

---

🤝 Contributing

Contributions are welcome! Here's how:

Step 1 — Fork, then clone your fork

git clone https://github.com/<your-username>/facebook-ssl-pinning-bypass.git

Step 2 — Create a feature branch

git checkout -b feature/your-feature-name

Step 3 — Commit your changes

git commit -m "Add: description of your changes"

Step 4 — Push and open a Pull Request

git push origin feature/your-feature-name

Ideas for contributions:

• 📝 Add Frida scripts for other pinning implementations
• 🌍 Translate lessons to other languages
• 🐛 Fix issues or improve explanations
• 📸 Add screenshots / demo GIFs

Please read CONTRIBUTING.md before submitting.

---

📊 Learning Path

BEGINNER ──────────────────────────────────────► ADVANCED

[Lesson 1]    [Lesson 2]    [Lesson 3]    [Lesson 4]    [Lesson 5]
   │              │              │              │              │
Setup &       SSL/TLS       Objection &    Write your    Ethics &
  Tools       Theory         Frida Lab     own hooks      Law
   │              │              │              │              │
  30m           45m           60m           90m           20m

Total estimated time: ~4 hours for a complete first run

---

⭐ Support This Project

If this repository helped your learning journey:

⭐ Star this repository to help others find it!

---

📜 License

MIT License — Copyright (c) 2026 HADI ANHAF AIMAN

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files, to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell copies of the Software,
subject to the conditions in the LICENSE file.

FOR EDUCATIONAL PURPOSES ONLY.

---

Made with ❤️ for the Security Research Community

Knowledge shared is knowledge multiplied.