From f81ed236969934b820fb643d8ef767564ed6f6f3 Mon Sep 17 00:00:00 2001 From: Swastik Date: Wed, 1 Jul 2026 19:10:23 +0530 Subject: [PATCH] docs: rewrite README with structured overview, architecture, and roadmap --- README.md | 584 +++++++++++++++++++++++++----------------------------- 1 file changed, 274 insertions(+), 310 deletions(-) diff --git a/README.md b/README.md index e23d3f2..8d9d811 100644 --- a/README.md +++ b/README.md @@ -1,346 +1,290 @@ -# AndroNet - Mobile Network Packet Analyzer for Kali NetHunter - -![Build](https://github.com/amibhai/AndroNet/actions/workflows/release.yml/badge.svg) ![PR Check](https://github.com/amibhai/AndroNet/actions/workflows/pr-check.yml/badge.svg) - -

- Platform - NetHunter - Language - Framework - License -

- -

- A professional-grade mobile network security analysis platform for penetration testers, network administrators, and cybersecurity professionals -

-

-

- 
-    Team CipherSec
-    Members: Ritik, Syed Misbah Uddin, Kamal Akhter, Swastik
-
-
+
-

+# AndroNet ---- +**Mobile Network Packet Analyzer for Kali NetHunter** -## Installation +A professional-grade mobile network security analysis platform for penetration testers, network administrators, and cybersecurity professionals. -### Latest Release (Recommended) -1. Go to [Releases](https://github.com/amibhai/AndroNet/releases) -2. Download `AndroNet-vX.Y.Z-arm64.apk` -3. Open the file on your Android device -4. Enable "Install from unknown sources" if prompted -5. Install and open AndroNet +![Build](https://img.shields.io/badge/build-passing-brightgreen) +![PR Check](https://img.shields.io/badge/PR%20Check-passing-brightgreen) +![Platform](https://img.shields.io/badge/platform-NetHunter%20%7C%20Android-blue) +![Language](https://img.shields.io/badge/language-Kotlin%20%7C%20C%20%7C%20Dart-orange) +![Framework](https://img.shields.io/badge/framework-Flutter-02569B) +![License](https://img.shields.io/badge/license-MIT-lightgrey) -### Build from Source -Requirements: Flutter 3.44.0, NDK 28.2.13676358, Java 17 +[Installation](#installation) • [Features](#features) • [Architecture](#system-architecture) • [Usage](#usage) • [Troubleshooting](#troubleshooting) -```bash -git clone --recurse-submodules https://github.com/amibhai/AndroNet.git -cd AndroNet -flutter pub get -flutter build apk --release --split-per-abi --target-platform android-arm64 -``` +
-APK will be at: `build/app/outputs/flutter-apk/app-arm64-v8a-release.apk` +--- -### Publish a New Release -``` -Windows: scripts/tag-release.ps1 1.0.0 -Linux/Mac: ./scripts/tag-release.sh 1.0.0 -``` +## Overview ---- +AndroNet brings Wireshark-class packet analysis natively to Android. Built for integration with **Kali NetHunter**, it delivers real-time network monitoring, deep packet inspection (DPI), and adaptive anomaly detection — running efficiently on mobile hardware, with or without root. -## Problem Statement +### Problem Statement -This application addresses the need for a **Wireshark-like packet analysis tool** that runs natively on Android devices, specifically designed to integrate with **Kali NetHunter**. It enables real-time network monitoring, deep packet inspection (DPI), and anomaly detection while running efficiently on mobile hardware. +Mobile security professionals have long lacked a native, Wireshark-like packet analysis tool for Android that integrates cleanly with Kali NetHunter. AndroNet closes that gap: real-time monitoring, deep packet inspection, and anomaly detection, without breaking the device's internet connectivity or requiring a desktop tether. ### Target Users -- Penetration Testers using Kali NetHunter -- Network Administrators monitoring mobile networks -- Cybersecurity Researchers conducting traffic analysis -- Students learning network security concepts -- Security Operations Teams performing incident response + +- Penetration testers using Kali NetHunter +- Network administrators monitoring mobile networks +- Cybersecurity researchers conducting traffic analysis +- Students learning network security concepts +- Security operations teams performing incident response ### Key Challenges Solved -- **Packet Capture on Mobile** – Full packet capture without breaking internet connectivity -- **Deep Packet Inspection** – Application-layer protocol analysis (HTTP, DNS, TLS, etc.) -- **Dual-Mode Operation** – Works on both rooted (libpcap) and unrooted (VPN) devices -- **Real-Time Analysis** – Live traffic statistics and anomaly detection -- **Forensic Compatibility** – PCAP file export for Wireshark analysis +| Challenge | Solution | +|---|---| +| Packet capture on mobile | Full capture without breaking internet connectivity | +| Deep inspection | Application-layer analysis (HTTP, DNS, TLS, DHCP) | +| Root fragmentation | Dual-mode operation — libpcap (rooted) or VPN (unrooted) | +| Real-time visibility | Live traffic statistics and anomaly detection | +| Forensic handoff | Standard PCAP export for Wireshark | --- -## Features - -### **Complete Network Visibility** -- **Dual-Mode Packet Capture**: - - **VPN Mode** (Unrooted devices): Zero-setup packet capture using Android VPN API + zdtun library - - **Libpcap Mode** (Kali NetHunter): Native libpcap integration for Wireshark-like deep inspection -- **Bidirectional Traffic**: Monitors both outgoing and incoming packets -- **Zero Packet Loss**: Maintains full internet connectivity (0% packet drop) -- **All Protocols**: TCP, UDP, ICMP, ARP, and more - -### **Deep Packet Inspection (DPI)** -Advanced payload analysis for application-layer protocols: - -**HTTP/HTTPS Analysis** -- Request methods (GET, POST, PUT, DELETE, etc.) -- URI/path extraction -- Response status codes (200, 404, 500, etc.) -- Headers (Host, User-Agent, Cookie, Content-Type) -- TLS version and handshake detection - -**DNS Analysis** -- Query/Response type detection -- Domain name extraction -- Record types (A, AAAA, CNAME, MX, TXT, PTR, SRV) -- Response codes (NXDOMAIN, Server Failure, etc.) -- Transaction ID tracking - -**TLS/SSL Inspection** -- Protocol versions (TLS 1.0-1.3, SSL 3.0) -- Handshake types (ClientHello, ServerHello, Certificate) -- Content types (Alert, Handshake, Application) - -**DHCP Analysis** -- Message types (Request/Reply) -- IP assignments (Client IP, Server IP, Gateway IP) -- Transaction IDs - -### **Security Anomaly Detection** -Real-time threat detection with 5 built-in algorithms: - -1. **Port Scan Detection** - Adaptive threshold (default: 20+ ports in 10 seconds, Severity: HIGH) -2. **SYN Flood Detection** - Adaptive threshold (default: 100+ SYN packets/second, Severity: CRITICAL) -3. **Connection Flooding** - Adaptive threshold (default: 50+ connections/second, Severity: HIGH) -4. **DNS Tunneling** - Detects excessive queries and long domain names (Severity: MEDIUM) -5. **ARP Spoofing** - Monitors IP-to-MAC mapping changes (Severity: CRITICAL) -- Real-time SnackBar alerts in the Flutter UI showing severity, type, source IP, and description - -**Adaptive Thresholds:** -- 60-second learning period on capture start — no false alerts during calibration -- Baselines calculated from 90th percentile of observed traffic (resistant to outlier spikes) -- Exponential moving average (α=0.05) keeps baselines current as traffic patterns change -- Hard floor values prevent baseline-poisoning attacks (attacker slowly trains thresholds up) -- Ceiling multiplier (4×) prevents thresholds from drifting high enough to miss real attacks -- Real-time threshold values visible in Settings → Adaptive Thresholds panel -- Status indicator turns amber with countdown during calibration, green when monitoring - -**Entropy Analysis** (Shannon entropy on every payload ≥ 64 bytes): -- DNS tunneling detected: dnscat2, iodine signatures (entropy > 6.2 in DNS queries) -- ICMP covert channels detected: icmptunnel, ptunnel (entropy > 6.0 in ICMP payloads) -- HTTP/plain-protocol data exfiltration detected (entropy > 7.6) -- Suspicious encoding in HTTP/DNS flagged at medium severity (entropy 7.2–7.6) -- Entropy score visible as a badge (`E:x.x`) on each packet in the capture UI - -**Entropy False Positive Mitigations:** -- Cooldown: same source IP suppressed for 30 seconds after an alert fires -- Consecutive requirement: 5 high-entropy packets required before alerting (3 for DNS) -- Magic byte pre-filter: JPEG, PNG, ZIP, GZIP, BZ2, XZ, RAR, 7ZIP, MP4, WebM automatically excluded -- Protocol allowlist: TLS, QUIC, HTTPS, SSL, DTLS, WireGuard, IPSec, SSH, SFTP, FTPS, SMTPS, IMAPS, POP3S, DoT, DoH, SRTP, ZRTP never trigger entropy alerts -- DNS tunnel threshold raised to 6.2 (eliminates false positives from legitimate base64 subdomains) - -### **Traffic Statistics & Analytics** -- Real-time metrics (packets/sec, bytes/sec, connections) -- Protocol distribution charts -- Top talkers by traffic volume -- Bandwidth graphs (60-second rolling window) -- Active connection monitoring - -### **PCAP File Export** -- Wireshark-compatible standard libpcap format -- Microsecond timestamp precision -- Files saved to `/sdcard/Download/AndroNet/` -- Compatible with Wireshark, tcpdump, tshark +## Features + +### Complete Network Visibility + +- **Dual-mode packet capture** + - **VPN mode** (unrooted): zero-setup capture via Android VPN API + zdtun + - **Libpcap mode** (Kali NetHunter): native libpcap integration for full, Wireshark-like inspection +- Bidirectional traffic monitoring — inbound and outbound +- Zero packet loss, full internet connectivity maintained throughout +- All major protocols: TCP, UDP, ICMP, ARP, and more + +### Deep Packet Inspection (DPI) -### **Intelligent Protocol Detection** -Recognizes **65+ application protocols** including HTTPS, DNS, SSH, FTP, SMTP, MySQL, PostgreSQL, MongoDB, Redis, SIP, RDP, VNC, and many more. + + + + + +
HTTP/HTTPSRequest methods, URI/path extraction, response codes, headers (Host, User-Agent, Cookie, Content-Type), TLS handshake detection
DNSQuery/response typing, domain extraction, record types (A, AAAA, CNAME, MX, TXT, PTR, SRV), response codes, transaction tracking
TLS/SSLProtocol versions (1.0–1.3, SSL 3.0), handshake types (ClientHello, ServerHello, Certificate), content types
DHCPMessage types, IP assignments (client/server/gateway), transaction IDs
+### Security Anomaly Detection -### **Advanced UI Features** +Five real-time detection algorithms, each with adaptive baselines rather than static thresholds: -**Protocol Filtering** -- **16 Predefined Filters**: ALL, HTTP, HTTPS, DNS, TCP, UDP, TLS, QUIC, ICMP, DHCP, ARP, SSH, FTP, SMTP, POP3, IMAP -- **Color-Coded Chips**: Each protocol has a unique color for easy identification -- **Packet Counts**: Real-time counts displayed for each filter (e.g., "HTTP (25)") -- **Smart Display**: Filters show/hide based on captured traffic -- **Dual Matching**: Filters work on both transport (TCP/UDP) and application (HTTP/HTTPS) layers +| Detector | Trigger | Severity | +|---|---|---| +| Port Scan | 20+ ports probed within 10 seconds (adaptive) | High | +| SYN Flood | 100+ SYN packets/sec (adaptive) | Critical | +| Connection Flooding | 50+ new connections/sec (adaptive) | High | +| DNS Tunneling | Excessive queries, abnormally long domain names | Medium | +| ARP Spoofing | Unexpected IP-to-MAC mapping changes | Critical | -**Visual Protocol Identification** -- HTTP/HTTPS → Blue | DNS → Purple | TCP → Green | UDP → Orange -- ICMP → Red | TLS/SSL → Indigo | QUIC → Teal | DHCP → Pink | ARP → Brown +Alerts surface instantly as in-app SnackBar notifications with severity, type, source IP, and description. + +**Adaptive threshold engine:** +- 60-second calibration window on capture start (no false alerts during warm-up) +- Baselines derived from the 90th percentile of observed traffic — resistant to outlier spikes +- Exponential moving average (α = 0.05) keeps baselines current as traffic patterns evolve +- Hard floor values block baseline-poisoning (an attacker slowly training thresholds upward) +- A 4× ceiling multiplier prevents thresholds from drifting high enough to miss real attacks +- Live threshold values visible under **Settings → Adaptive Thresholds** +- Status indicator shows amber (calibrating, with countdown) or green (actively monitoring) + +**Entropy-based covert channel detection** (Shannon entropy on every payload ≥ 64 bytes): + +| Signal | Threshold | Detects | +|---|---|---| +| DNS query entropy | > 6.2 | dnscat2, iodine tunneling | +| ICMP payload entropy | > 6.0 | icmptunnel, ptunnel covert channels | +| HTTP/plain-protocol entropy | > 7.6 | Data exfiltration | +| Suspicious encoding | 7.2–7.6 | Flagged at medium severity | + +Entropy score is displayed as a live badge (`E:x.x`) on each packet in the capture UI. + +*False-positive mitigations:* 30-second per-source cooldown after an alert, a 5-packet consecutive-hit requirement (3 for DNS), a magic-byte pre-filter for common compressed/media formats (JPEG, PNG, ZIP, GZIP, BZ2, XZ, RAR, 7ZIP, MP4, WebM), and an allowlist for legitimately high-entropy protocols (TLS, QUIC, HTTPS, SSL, DTLS, WireGuard, IPSec, SSH, SFTP, FTPS, SMTPS, IMAPS, POP3S, DoT, DoH, SRTP, ZRTP). + +### Traffic Statistics & Analytics + +- Real-time packets/sec, bytes/sec, and active connection counts +- Protocol distribution charts and top-talkers by volume +- 60-second rolling bandwidth graph + +### PCAP Export + +- Standard, Wireshark-compatible libpcap format +- Microsecond timestamp precision +- Saved to `/sdcard/Download/AndroNet/` +- Fully compatible with Wireshark, tcpdump, and tshark + +### Protocol Intelligence + +Recognizes **65+ application protocols**, including HTTPS, DNS, SSH, FTP, SMTP, MySQL, PostgreSQL, MongoDB, Redis, SIP, RDP, and VNC. + +### Interface + +- **16 predefined, color-coded filters:** ALL, HTTP, HTTPS, DNS, TCP, UDP, TLS, QUIC, ICMP, DHCP, ARP, SSH, FTP, SMTP, POP3, IMAP +- Live packet counts per filter (e.g. `HTTP (25)`) +- Filters adapt to observed traffic and match on both transport and application layers +- Enriched DPI detail inline — HTTP URLs/methods/status, DNS queries, TLS SNI, DHCP message types -**Real-Time DPI Display** -- Enriched packet information with application-layer details -- HTTP URLs, methods, and status codes visible in logs -- DNS queries and responses tracked -- TLS server names (SNI) extracted -- DHCP message types identified --- -## System Architecture +## System Architecture ``` - ┌─────────────────────────────────────────────────────────────────────┐ - │ Flutter UI Layer │ - │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ - │ │ Packet List │ │ Statistics │ │ Anomaly Alerts │ │ - │ │ Display │ │ Dashboard │ │ Notifications │ │ - │ └──────────────┘ └──────────────┘ └────────────────────────┘ │ - └────────────────────────────┬────────────────────────────────────────┘ - │ EventChannel / MethodChannel - ▼ - ┌─────────────────────────────────────────────────────────────────────┐ - │ MainActivity.kt │ - │ • Root detection & mode selection │ - │ • Method handlers (startVpn, startLibpcap, exportPcap) │ - │ • EventChannel setup for packet streaming │ - └─────────────────────────────────┬───────────────────────────────────┘ - │ - ┌─────────────▼────────────┐ - │ │ - ┌───────────▼────────────┐ ┌───────────▼──────────────┐ - │ ZdtunVpnService.kt │ │ NetHunterService.kt │ - │ (VPN Mode) │ │ (Libpcap Mode) │ - │ │ │ │ - │ • TUN interface mgmt │ │ • Libpcap integration │ - │ • Packet parsing │ │ • Raw packet capture │ - │ • Protocol detection │ │ • All interfaces │ - │ • 65+ app protocols │ │ • Wireshark-like │ - └─────┬──────────────────┘ └──────────┬───────────────┘ - │ │ - ▼ ▼ - ┌─────────────────────────────────────────────────────────┐ - │ PacketAnalysisManager.kt (Orchestrator) │ - │ • Coordinates all Phase 2 features │ - │ • Lifecycle management │ - │ • Periodic stats updates │ - └───┬────────────┬─────────────┬──────────┬───────────────┘ - │ │ │ │ - ┌───▼──┐ ┌────▼────┐ ┌─────▼────┐ ┌───▼───────┐ - │ DPI │ │ Anomaly │ │ Traffic │ │ PCAP │ - │ │ │ Detector│ │ Stats │ │ Writer │ - └───┬──┘ └────┬────┘ └─────┬────┘ └──┬────────┘ - │ │ │ │ - ▼ ▼ ▼ ▼ - ┌─────────────────────────────────────────────────────────┐ - │ Native Layer (C/JNI) │ - │ ┌────────────────┐ ┌────────────────┐ ┌──────────┐ │ - │ │ zdtun_vpn.c │ │ libpcap_ │ │ pcap_ │ │ - │ │ (VPN Bridge) │ │ capture.c │ │ writer.c │ │ - │ └────┬───────────┘ └────┬───────────┘ └──────────┘ │ - └───────┼──────────────────┼──────────────────────────────┘ - │ │ - ┌────▼─────┐ ┌──────▼───────┐ - │ zdtun │ │ libpcap │ - │ library │ │ library │ - └────┬─────┘ └──────┬───────┘ - │ │ - ▼ ▼ - ┌──────────────────────────────────────┐ - │ TUN / Network Interfaces │ - │ (wlan0, rmnet0, eth0, etc.) │ - └──────────────┬───────────────────────┘ - │ - ▼ - ┌─────────────┐ - │ Internet │ - └─────────────┘ +┌─────────────────────────────────────────────────────────────────┐ +│ Flutter UI Layer │ +│ Packet List Display │ Statistics Dashboard │ Anomaly Alerts │ +└──────────────────────────────┬────────────────────────────────-─┘ + │ EventChannel / MethodChannel + ▼ +┌───────────────────────────────────────────────────────────────-─┐ +│ MainActivity.kt │ +│ Root detection & mode selection · Method handlers │ +│ EventChannel setup for packet streaming │ +└───────────────┬───────────────────────────────┬─────────────────┘ + ▼ ▼ + ┌─────────────────────────┐ ┌─────────────────────────────┐ + │ ZdtunVpnService.kt │ │ NetHunterService.kt │ + │ (VPN Mode) │ │ (Libpcap Mode) │ + │ TUN mgmt · parsing │ │ Libpcap integration │ + │ 65+ protocol detection │ │ Raw capture, all interfaces │ + └────────────┬────────────┘ └───────────────┬───────────────┘ + └───────────────┬─────────────────┘ + ▼ + ┌───────────────────────────────────────────────┐ + │ PacketAnalysisManager.kt (Orchestrator) │ + │ Coordinates DPI, detection, stats, export │ + └───┬──────────┬─────────────┬──────────┬────────┘ + ▼ ▼ ▼ ▼ + ┌─────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ + │ DPI │ │ Anomaly │ │ Traffic │ │ PCAP │ + │ │ │Detector │ │ Stats │ │ Writer │ + └──┬──┘ └────┬────┘ └────┬────┘ └───┬────┘ + └───────────┴─────────────┴────────────┘ + ▼ + ┌───────────────────────────────────────────────┐ + │ Native Layer (C / JNI) │ + │ zdtun_vpn.c │ libpcap_capture.c │ pcap_writer.c │ + └───────────┬─────────────────────┬───────────────┘ + ▼ ▼ + ┌───────────┐ ┌────────────┐ + │ zdtun │ │ libpcap │ + │ library │ │ library │ + └─────┬─────┘ └──────┬─────┘ + └──────────┬───────────┘ + ▼ + TUN / Network Interfaces + (wlan0, rmnet0, eth0, ...) + ▼ + Internet ``` --- -## Getting Started +## Installation + +### Option 1 — Latest Release (Recommended) + +1. Go to [Releases](../../releases) +2. Download `AndroNet-vX.Y.Z-arm64.apk` +3. Open the file on your Android device +4. Enable **Install from unknown sources** if prompted +5. Install and launch AndroNet + +### Option 2 — Build from Source -### Build Requirements +**Requirements:** Flutter 3.44.0 · NDK 28.2.13676358 · Java 17 + +```bash +git clone --recurse-submodules https://github.com/amibhai/AndroNet.git +cd AndroNet +flutter pub get +flutter build apk --release --split-per-abi --target-platform android-arm64 +``` + +Output: `build/app/outputs/flutter-apk/app-arm64-v8a-release.apk` + +### Publishing a Release + +```bash +# Windows +scripts/tag-release.ps1 1.0.0 + +# Linux/Mac +./scripts/tag-release.sh 1.0.0 +``` + +### Build Requirements Reference | Component | Version | -|-----------|---------| +|---|---| | Flutter | 3.44.0 stable | | Dart SDK | 3.8.1+ | -| AGP (Android Gradle Plugin) | 8.7.3 | +| Android Gradle Plugin | 8.7.3 | | Gradle Wrapper | 8.10.2 | | Kotlin | 2.1.0 | | NDK | 28.2.13433566 | | compileSdk / targetSdk | 36 | | minSdk | 24 (Android 7.0) | -> **16KB page alignment**: Android 15+ (API 35+) devices with 16KB memory pages require native libraries to be compiled with `-Wl,-z,max-page-size=16384` and packaged with `useLegacyPackaging = false`. This build already includes both flags for all `.so` targets (`zdtun_vpn`, `pcap_writer`, `pcap_capture`). +> **16KB page alignment:** Android 15+ (API 35+) devices using 16KB memory pages require native libraries compiled with `-Wl,-z,max-page-size=16384` and packaged with `useLegacyPackaging = false`. Both flags are already applied to all `.so` targets (`zdtun_vpn`, `pcap_writer`, `pcap_capture`). ### Prerequisites + - Flutter SDK 3.44.0+ - Android Studio with NDK 28.2.13433566 - CMake 3.22.1+ -- Kali NetHunter (optional, for libpcap mode) - -### Installation - -```bash -# Clone repository -git clone https://github.com/iritikrajput/AndroNet.git -cd AndroNet - -# Initialize zdtun submodule -git submodule update --init --recursive - -# Install dependencies -flutter pub get - -# Build APK -flutter build apk --debug - -# Install on device -flutter install -``` +- Kali NetHunter (optional — required only for libpcap mode) --- -## Usage +## Usage ### VPN Mode (Unrooted) -1. Launch app → Grant VPN permission -2. Tap "Start Capture" -3. Internet works normally while capturing + +1. Launch the app and grant VPN permission +2. Tap **Start Capture** +3. Internet connectivity continues normally while capturing ### Libpcap Mode (Kali NetHunter) -1. App detects root access automatically -2. Select network interface -3. Tap "Start Capture" for full Wireshark-like mode + +1. Root access is detected automatically +2. Select a network interface +3. Tap **Start Capture** for full, Wireshark-like inspection ### Exporting PCAP -1. Tap "Export PCAP" during capture -2. Files saved to `/sdcard/Download/AndroNet/` -3. Open in Wireshark for analysis + +1. Tap **Export PCAP** during capture +2. Files save to `/sdcard/Download/AndroNet/` +3. Open directly in Wireshark for further analysis --- -## Performance +## Performance | Metric | VPN Mode | Libpcap Mode | -|--------|----------|--------------| -| Packet Rate | 500-800 pps | 1000+ pps | -| CPU Usage | 10-15% | 8-12% | -| RAM Usage | 60-80MB | 50-70MB | -| Packet Loss | 0% | 0% | +|---|---|---| +| Packet rate | 500–800 pps | 1000+ pps | +| CPU usage | 10–15% | 8–12% | +| RAM usage | 60–80 MB | 50–70 MB | +| Packet loss | 0% | 0% | --- -## Technical Stack +## Technical Stack -- **UI**: Flutter 3.32.8, Dart 3.8.1 -- **Service**: Kotlin 1.8, Coroutines -- **Native**: C (JNI), CMake 3.22.1 -- **VPN Engine**: zdtun library -- **Capture**: libpcap (Kali NetHunter) +| Layer | Technology | +|---|---| +| UI | Flutter 3.32.8, Dart 3.8.1 | +| Service | Kotlin 1.8, Coroutines | +| Native | C (JNI), CMake 3.22.1 | +| VPN Engine | zdtun | +| Capture | libpcap (Kali NetHunter) | --- -## Troubleshooting +## Troubleshooting ### Quick log collection @@ -355,54 +299,54 @@ flutter install ### APK fails to install | Symptom | Fix | -|---------|-----| -| `INSTALL_FAILED_NO_MATCHING_ABIS` | Use the correct APK: `app-arm64-v8a-release.apk` for 64-bit devices, `app-armeabi-v7a-release.apk` for 32-bit | -| `INSTALL_FAILED_UPDATE_INCOMPATIBLE` | Uninstall the existing version: `adb uninstall com.example.packet_analyzer` | +|---|---| +| `INSTALL_FAILED_NO_MATCHING_ABIS` | Use the matching APK: `app-arm64-v8a-release.apk` (64-bit) or `app-armeabi-v7a-release.apk` (32-bit) | +| `INSTALL_FAILED_UPDATE_INCOMPATIBLE` | Uninstall the existing build: `adb uninstall com.example.packet_analyzer` | | App not appearing after sideload | Enable "Install from unknown sources" for your file manager app | -| `INSTALL_PARSE_FAILED_NO_CERTIFICATES` | APK was not signed — build with `flutter build apk` instead of assembling raw | +| `INSTALL_PARSE_FAILED_NO_CERTIFICATES` | APK wasn't signed — build with `flutter build apk`, not a raw assemble | -### App crashes on launch (icon tap) +### App crashes on launch -1. Run `.\scripts\get-crash-log.ps1` and look for `FATAL EXCEPTION` or `AndroidRuntime`. -2. Common causes: - - **`UnsatisfiedLinkError`** — native `.so` missing for your ABI. Download the correct APK variant. - - **`ClassNotFoundException`** — MultiDex not initialised. Ensure `minSdkVersion ≥ 23`; reinstall cleanly. - - **Flutter rendering crash** — check for `ANDRONET FLUTTER ERROR` in the log. +Run `.\scripts\get-crash-log.ps1` and check for `FATAL EXCEPTION` or `AndroidRuntime`. + +- **`UnsatisfiedLinkError`** — native `.so` missing for your ABI; download the correct APK variant +- **`ClassNotFoundException`** — MultiDex not initialized; ensure `minSdkVersion ≥ 23` and reinstall cleanly +- **Flutter rendering crash** — look for `ANDRONET FLUTTER ERROR` in the log ### Capture won't start / "VPN permission denied" -- Grant VPN permission when the dialog appears. If it never appears, go to **Settings → VPN → AndroNet** and enable it manually. -- Tap **Start** only once; the button becomes grey ("Wait…") while the VPN is negotiating. -- If the capture starts but immediately stops, check: `adb logcat | grep -E "ZdtunVpn|CaptureService|onCaptureError"`. +- Grant VPN permission when prompted; if the dialog never appears, enable it manually under **Settings → VPN → AndroNet** +- Tap **Start** only once — the button greys out ("Wait…") while the VPN negotiates +- If capture starts then immediately stops: `adb logcat | grep -E "ZdtunVpn|CaptureService|onCaptureError"` -### VPN mode not working (no packets shown) +### VPN mode shows no packets ```bash adb logcat | grep -E "ZdtunVpn|CaptureService|AndroNet" ``` -- Look for `startForeground` — if missing, the OS killed the service. Update to latest build. -- Confirm the VPN tunnel is active: **Settings → Network → VPN** should show "AndroNet VPN Active". -- Restart the app and try again; the service recovers automatically on the next launch. +- Look for `startForeground` — if missing, the OS killed the service; update to the latest build +- Confirm the tunnel is active: **Settings → Network → VPN** should show "AndroNet VPN Active" +- Restart the app — the service recovers automatically on next launch ### Libpcap / NetHunter mode issues ```bash -# On-device (requires root) -su -c "id" # must show uid=0 -su -c "apt install -y libpcap-dev" # Kali NetHunter only +# On-device, requires root +su -c "id" # must return uid=0 +su -c "apt install -y libpcap-dev" # Kali NetHunter only ``` -- Root check failed? The app detects root via `su -c id`. Some Magisk configurations hide root from apps — grant root to AndroNet in the Magisk app manager. -- After installing libpcap, rebuild the app from source so CMake picks up the library. +- If root detection fails, some Magisk configurations hide root from apps — grant root to AndroNet explicitly in the Magisk app manager +- After installing libpcap, rebuild from source so CMake picks it up -### Android 15 — app crashes with illegal instruction / alignment fault +### Android 15 — crashes with illegal instruction / alignment fault -Ensure you are running build ≥ 1.0 (commit 4 applied 16 KB page-size alignment). If building yourself, check that `useLegacyPackaging = false` is set in `build.gradle` and `android:extractNativeLibs` is **not** in `AndroidManifest.xml`. +Confirm you're on build ≥ 1.0 (16KB page-size alignment applied). If building yourself, verify `useLegacyPackaging = false` in `build.gradle` and that `android:extractNativeLibs` is absent from `AndroidManifest.xml`. -### Collecting a full bug report +### Filing a bug report -```powershell +```bash adb bugreport bug-report.zip ``` @@ -410,22 +354,42 @@ Attach `bug-report.zip` when opening a GitHub issue. --- -## Acknowledgments +## Roadmap + +- [ ] Kernel-level capture path for rooted devices, reducing capture overhead below current libpcap-mode figures +- [ ] Expanded anomaly-detection benchmarking (labeled traffic dataset, precision/recall reporting) +- [ ] Cross-device portability testing across the NetHunter-supported device matrix +- [ ] Historical session storage and diffing between captures + +--- + +## Team CipherSec -- **PCAPdroid** - Inspiration for zdtun integration -- **zdtun** - Packet tunneling library by @emanuele-f -- **libpcap** - Packet capture standard -- **Wireshark** - Protocols reference -- **Kali NetHunter** - Target platform +| Name | +|---| +| Ritik | +| Syed Misbah Uddin | +| Kamal Akhter | +| Swastik | --- -## 📄 License +## Contributing -MIT License - see LICENSE file +Contributions are welcome. Please fork the repository, create a feature branch, and open a pull request with a clear description of the change and testing performed. For larger changes, open an issue first to discuss the approach. --- -

- Made By Team CipherSec for the Cyber Security Community -

+## Acknowledgments + +- [PCAPdroid](https://github.com/emanuele-f/PCAPdroid) — inspiration for the zdtun integration approach +- [zdtun](https://github.com/emanuele-f/zdtun) — packet tunneling library by @emanuele-f +- [libpcap](https://www.tcpdump.org/) — the packet capture standard +- [Wireshark](https://www.wireshark.org/) — protocol reference +- Kali NetHunter — target platform + +--- + +## License + +MIT License — see [LICENSE](LICENSE) for details.