sniff! Documentation

Overview

sniff! automates the full Android HTTPS interception pipeline — ADB device management, mitmproxy setup, and Frida-based SSL pinning bypass — from a single interface. Select an app, pick a bypass script, and start capturing decrypted traffic in seconds.

It provides both a terminal UI (TUI) built on BubbleTea and a modern web dashboard built on Next.js. The Go backend orchestrates all subprocesses and streams captured flows in real-time via Server-Sent Events.

Prerequisites

Device Setup

Your Android device needs to be rooted (Magisk recommended) with USB debugging enabled. The mitmproxy CA certificate must be installed as a system certificate, and frida-server must be pushed to the device.

# Push frida-server to device
adb push frida-server-16.x.x-android-arm64 /data/local/tmp/fs-helper-64
adb shell "chmod 755 /data/local/tmp/fs-helper-64"

# Install mitmproxy CA as system cert (requires root)
adb push ~/.mitmproxy/mitmproxy-ca-cert.cer /sdcard/
# Then: Settings > Security > Install from storage

Installation

Development

git clone https://github.com/x-lock/sniff.git
cd sniff

# Install frontend dependencies
cd site && bun install && cd ..

# Start both backend (:9090) and frontend (:3000)
./dev

The dev script starts the Go backend on port 9090 and the Next.js dev server on port 3000, then opens the browser automatically.

Production Build

# Build frontend + Go binary
./build-sniff!

# Run in web mode
./sniff! --web

# Run in TUI mode
./sniff!

# Run with a preset target package
./sniff! com.example.app

Usage

Web UI

Launch with ./sniff! --web or ./dev for development. The dashboard is organized into these pages:

TUI Mode

Launch with ./sniff! for a full terminal interface.

During capture:

Capture Workflow

When you start a standard capture, sniff! executes this sequence automatically:

On stop: proxy is cleared, Frida detaches, SELinux is restored to Enforcing.

Capture Modes

Beyond standard capture, sniff! includes specialized modes that encode app-specific bypass knowledge.

Frida Scripts

Built-in Scripts

Plus 7 app-specific scripts for Pilot Flying J, LinkedIn, DailyPay, Speedway, and Papa Johns.

Custom Scripts

Create custom scripts from the web UI (Scripts page → New Script) or upload .js files. Custom scripts are stored in frida_scripts/custom/ with a META header:

// META: {"label":"CUSTOM","desc":"My bypass script"}
Java.perform(function() {
  var TrustManager = Java.use("javax.net.ssl.X509TrustManager");
  // Your hooks here
});

All scripts — built-in and custom — can be edited from the web UI. Changes are saved directly to the script file on disk.

API Reference

The Go backend serves a REST API on port 9090 (configurable). All endpoints are prefixed with /api/.

State & Events

SSE event types:

Capture Control

Available modes: standard, mitm_only, signup_handoff, linkedin_cronet, linkedin_replay, dailypay, speedway, papajohns

Flows

Flow object shape:

{
  "ts": 1711584000.123,
  "method": "POST",
  "url": "https://api.example.com/v1/auth",
  "host": "api.example.com",
  "path": "/v1/auth",
  "status": 200,
  "req_size": 256,
  "resp_size": 1024,
  "content_type": "application/json",
  "req_headers": { "Authorization": "Bearer ..." },
  "resp_headers": { "Set-Cookie": "..." },
  "req_body": "{\"username\":\"...\"}",
  "resp_body": "{\"token\":\"...\"}"
}

Bodies are truncated to 5,000 characters.

Device

Scripts

Settings

Configuration

Settings are stored in settings.json and editable via the TUI or web UI.

Architecture

sniff!/
├── main.go              # TUI, capture sequences, ADB, Frida, mitmdump
├── web.go               # HTTP API, SSE streaming, REST handlers
├── go.mod               # Go dependencies (BubbleTea + stdlib)
├── frida_scripts/       # 14+ built-in .js bypass scripts
│   └── custom/          # User-created scripts
├── site/                # Next.js web dashboard
│   ├── src/app/         # App Router pages
│   ├── src/components/  # React components
│   └── src/lib/         # API client, state, filters, types
├── dev                  # Dev script (backend + frontend)
└── build-sniff!      # Production build script

The Go backend manages all subprocesses (Frida, mitmdump, ADB) via os/exec. Captured flows are written to a JSONL file by a mitmdump Python addon, then tailed by the Go process at 300ms intervals and streamed to connected clients via SSE.

The Frida injection works by hooking Java-level SSL methods (TrustManager, OkHttp CertificatePinner, etc.) or native functions (BoringSSL for Flutter) at runtime, making the app accept the mitmproxy CA certificate.