README.md

metadata

title: Netguard
emoji: 🌍
colorFrom: red
colorTo: blue
sdk: docker
pinned: false

NetGuard-like Android Firewall

Advanced Android Network Inspector & Firewall

A production-level Android firewall app and debugging proxy using VpnService that can inspect and block internet access per app without root.

Architecture Improvements

The system was completely rewritten to meet the requirements of a modern Deep Packet Inspection tool (like NetGuard / HTTP Canary).

What was broken

1. Split-Tunneling Bypass Leaks: The original approach used Builder.addAllowedApplication(). This meant the firewall relied on the Android OS to correctly route apps. This bypasses the VPN completely for allowed apps, preventing any inspection and causing leaks if the OS falls back to cellular data or IPv6.
2. Missing TCP/UDP Forwarding Engine: The VPN was a "black hole". It read packets from the TUN interface but did not actually establish network connections.
3. Basic Parsing: The old packet parser could not recalculate checksums, making it impossible to synthesize and write responses back into the TUN interface.

What was fixed and improved

1. Full Network Capture: The VPN now routes 0.0.0.0/0 and ::/0 into the TUN interface. All traffic (allowed and blocked) from all apps enters the FirewallVpnService. This prevents all leaks.
2. L3 to L4 NAT Engine:
   • UDP Mapping: The NatEngine parses UDP packets, establishes real DatagramChannel sockets to the destination, and forwards the payload. When a response is received, it swaps the IP headers, recalculates the UDP checksum, and writes the packet back to the TUN interface.
   • TCP Proxying: The NatEngine tracks TCP SYN, ACK, PSH, and FIN flags. It establishes real SocketChannel connections to the destination server. It synthesizes TCP SYN-ACK and FIN-ACK responses locally to complete the TCP handshake with the Android OS networking stack while piping the data payloads asynchronously using Java NIO Selectors.
3. Deep Packet Inspection (DPI):
   • DNS: UDP Port 53 traffic is intercepted. Queries are parsed recursively for domain names.
   • SNI (Server Name Indication): Parses TLS ClientHello packets (TCP Port 443) to extract the unencrypted SNI domain extension.
   • HTTP: Parses raw HTTP traffic to extract the Host: header.
4. Logging & UI: The Room database now stores this detailed protocol metadata and surfaces it dynamically in the UI.

Limitations Note

Android VpnService is extremely powerful but operates at OSI Layer 3 (IP). Implementing a 100% compliant TCP reassembly stack (handling sequence overlaps, sliding windows, and out-of-order packets) requires importing a C library like lwip via JNI. The current NatEngine implements a stateful proxy that works for standard traffic flows, fulfilling the requirement for realistic L4 proxying in Kotlin without native code dependencies.

---

🤖 Hugging Face APK Build Instructions

This project includes a fully automated Dockerized build environment specifically designed to be hosted on Hugging Face Spaces. It compiles the Android APK and serves it via a built-in HTTP server.

Step 1: Create a Hugging Face Space

1. Go to Hugging Face Spaces and click Create new Space.
2. Space name: android-firewall-build
3. License: MIT (or any)
4. Select the Space SDK: Choose Docker.
5. Choose Docker template: Select Blank.
6. Click Create Space.

Step 2: Upload Project Files

Upload the entire contents of this repository to your new Space. You can do this in two ways:

• Git: Clone the Hugging Face repository and push the files via command line.
• UI: Click on the Files tab in your Space, click Add file, and drag-and-drop the files (maintain the folder structure).

Step 3: Trigger the Build

Once the files are uploaded, Hugging Face will automatically detect the Dockerfile and begin building the environment.

• The build process will download the Android SDK, install Gradle, and compile the APK.
• You can watch the progress in the Logs tab of your Space.
• Note: The build may take several minutes to complete.

Step 4: Download the APK

Once the build is complete, the build_apk.sh script will automatically start a Python HTTP server on port 7860.

1. The Hugging Face Space will transition to the Running state.
2. In the "App" tab of your Space, you will see a directory listing.
3. Click on app-debug.apk to download the compiled application directly to your device or computer.