Acknowledgement:
This project is a coraboration from the original Giovanni Android Framework created by John S. Madaha.
Original Repository: https://github.com/GiovanniJohnArthur/FinalYearProject
This documentation covers my the capabilities and its extent, using python scripts to automate adb commands to a CLI program.

Story Behind the project

Back then 2024, While I was a student, sitting in Computer lab on Our Cyber Security Auditing class, and saw this guy using python scripts to connect remotely to android devices. The funny thing is it was his FinalYear project and by the time I was very interested into the Android Penetration Testing, but not that good (Or may be still I'm not). Till then I had worked with ADB but for sure didn't know one can do that, to connect to a remote Host that has enabled Android Debugging service. So I teamed with him and added a few modules running them with basicly python os.system() commands It was simple but really fascinating what one can automate with scripts Good Thinking Mr @GiovanniJohnArthur.

Project Overview

The Giovanni Android Framework represents a sophisticated approach to Android device management through automated ADB (Android Debug Bridge) commands. This Python-based tool transforms complex command-line operations into an intuitive menu-driven interface, making advanced Android manipulation accessible to security professionals, developers, and digital forensics experts.

My involvement in this project focused on extending the original framework with enhanced features, improved error handling, and comprehensive documentation to create a more robust and user-friendly security testing platform.

Framework Interface

The Giovanni Framework presents users with a comprehensive ASCII interface that organizes 44+ different ADB operations into logical categories:

``` ______ _______ _ _ ___ _ / _____) (_______) | | (_) _ / __) | | | / ___ _ _ ____ _____ _ _ ____ | | ___ _ | |_ | |__ ____ ____ ____ ____ _ _ _ ___ ____ | | _ | | (___)| | | || _ \ | ___) ( \ / )| _ \ | | / _ \ | || _) | __) / ___) / _ || \ / _ )| | | | / _ \ / ___)| | / ) | \____/| \ V / | | | || |_____ ) X ( | | | || || |_| || || |__ | | | | ( ( | || | | |( (/ / | | | || |_| || | | |< ( \_____/ \_/ |_| |_||_______)(_/ \_)| ||_/ |_| \___/ |_| \___)|_| |_| \_||_||_|_|_| \____) \____| \___/ |_| |_| \_) | | | | BY John S. Madaha |_| Giovanni Exploitation Framework BY John S. Madaha Exploitation Framework for Android Remote Access HomePage: github.com/GiovanniJohnArthur/FinalYearProject ┌─ DEVICE MANAGEMENT ────────┐ ┌─ SECURITY TESTING ─────────┐ │ 1 - Show connected devices│ │ 23 - Remove device password│ │ 2 - Disconnect all devices│ │ 31 - Start a keylogger │ │ 3 - Connect a new device │ │ 35 - Clipboard hijacking │ │ 8 - Restart gvn Server │ │ 37 - Bluetooth interaction │ └────────────────────────────┘ └────────────────────────────┘ ┌─ APPLICATION CONTROL ──────┐ ┌─ MEDIA OPERATIONS ─────────┐ │ 5 - Install an APK │ │ 6 - Screen recording │ │ 11 - Uninstall an app │ │ 7 - Device screenshot │ │ 14 - List all device apps │ │ 30 - Camera photo capture │ │ 15 - Run a device app │ │ 32 - Audio recording │ │ 19 - Extract APK from app │ │ 39 - Screen mirroring │ └────────────────────────────┘ └────────────────────────────┘ ┌─ INFORMATION GATHERING ────┐ ┌─ ADVANCED FEATURES ────────┐ │ 12 - Show device log │ │ 28 - Call specific number │ │ 13 - Dump system info │ │ 29 - Get GPS location │ │ 18 - Show MAC/IP addresses │ │ 40 - Simulate gestures │ │ 20 - Get battery status │ │ 41 - GPS spoofing │ │ 21 - Get network status │ │ 42 - Process monitoring │ │ 33 - Get SMS messages │ │ 43 - Live log monitoring │ │ 34 - Get browser history │ │ 44 - Kill processes │ └────────────────────────────┘ └────────────────────────────┘ ```

Comprehensive Feature Set

The framework encompasses a wide range of Android device manipulation capabilities:

Core Device Management

  • Multi-Device Support: Connect and manage multiple Android devices simultaneously
  • Network Connectivity: Support for both USB and TCP/IP connections
  • Device State Control: Power management, restart capabilities, and connection handling
  • System Information Extraction: Comprehensive device profiling and status monitoring

Application Ecosystem Management

  • APK Installation/Removal: Silent installation and uninstallation of applications
  • Application Inventory: Complete listing of installed applications with detailed metadata
  • APK Extraction: Pull installed applications from devices for reverse engineering
  • Application Launch Control: Remote application execution and management

Digital Forensics Capabilities

  • File System Access: Comprehensive file pulling and analysis capabilities
  • Data Extraction: SMS, call logs, browser history, and contact information
  • Network Configuration: WiFi credentials, network settings, and connection analysis
  • System Monitoring: Real-time process monitoring and system state analysis

Security Testing Features

  • Security Bypass: Password removal and lock screen bypass techniques
  • Input Simulation: Keylogging, gesture simulation, and input injection
  • Privacy Invasion: Clipboard monitoring, location tracking, and communication interception
  • Hardware Control: Camera, microphone, flashlight, and sensor manipulation

Installation & Environment Setup

Setting up the Giovanni Framework requires careful preparation of both the host system and target Android devices:

System Prerequisites

Required Components
Python 3.6+ Android Debug Bridge (ADB) USB Drivers for target devices Network connectivity (for TCP/IP mode) Root access on target device (for advanced features)

Framework Installation

Installation Process
git clone https://github.com/GiovanniJohnArthur/FinalYearProject.git cd FinalYearProject chmod +x gvn # Install ADB platform tools sudo apt-get install android-tools-adb android-tools-fastboot # Verify ADB installation adb version Android Debug Bridge version 1.0.41

Or using custom installer script

Installation Process
git clone https://github.com/GiovanniJohnArthur/FinalYearProject.git cd FinalYearProject chmod +x install # Install ADB platform tools sudo apt-get install android-tools-adb android-tools-fastboot # To add the framework to /opt dir and dlobal the binary into system path ./install.sh # Now you can call the binary anywhere in your path gvn

Target Device Configuration

Proper device setup is crucial for framework functionality:

  1. Developer Options: Navigate to Settings → About Phone → Tap "Build Number" 7 times
  2. USB Debugging: Enable in Settings → Developer Options → USB Debugging
  3. Network ADB: Enable "Wireless debugging" for TCP/IP connections
  4. Root Access: Required for advanced security testing features
  5. Unknown Sources: Allow installation of apps from unknown sources
Security Considerations: These settings significantly reduce device security. Only enable on test devices and disable after testing.

Comprehensive Usage Guide

The Giovanni Framework operates through an interactive menu system that abstracts complex ADB commands into simple numbered selections:

Framework Initialization

Starting Giovanni Framework
./gvn [+] Starting Giovanni Android Framework... [+] Initializing ADB server... [+] ADB server started on port 5037 ╔══════════════════════════════════════════╗ ║ Giovanni Android Framework ║ ║ Security Testing Suite ║ ╚══════════════════════════════════════════╝ Select an option [1-44]:

Device Connection Workflow

Establishing connectivity with target devices involves several methods:

USB Connection

USB Device Connection
# Connect device via USB cable adb devices List of devices attached 1A2B3C4D5E6F device # Giovanni automatically detects USB-connected devices

Network Connection

TCP/IP Connection Process
# Select option 3 from Giovanni menu [3] Connect a new device Enter device IP address: 192.168.1.100 [+] Attempting to connect to 192.168.1.100:5555... [+] Connection successful! [+] Device 192.168.1.100:5555 is now available connected to 192.168.1.100:5555

Core Operations Demonstration

Application Management

APK Installation Example
# Select option 5 - Install an APK Enter path to APK file: /home/elliot/malware_sample.apk [+] Installing APK... [+] Performing Streamed Install Success [+] APK installed successfully!

Information Gathering

Device Information Extraction
# Select option 13 - Dump System Info [+] Gathering system information... Device: Samsung SM-G973F Android Version: 11 API Level: 30 Kernel: 4.14.113-20758351 RAM: 8GB Storage: 128GB Root Status: Rooted (SuperSU v2.82) Security Patch: 2023-08-01

Complete Command Reference

The Giovanni Framework organizes its extensive command set into logical categories for efficient navigation:

Device Management Commands

Option Function Description Root Required
1 show-devices Display all connected Android devices with detailed information No
2 disconnect-all Safely disconnect all connected devices and reset ADB server No
3 connect-device Establish TCP/IP connection to remote Android device No
8 restart-server Restart Giovanni framework and reinitialize ADB connections No
10 shutdown-device Remotely shutdown target Android device Yes

Application Control & Management

Option Function Description Forensic Value
5 install-apk Silent installation of APK files on target device Malware deployment, tool installation
11 uninstall-app Remove applications from device without user interaction Evidence removal, cleanup operations
14 list-applications Comprehensive inventory of installed applications Software profiling, threat assessment
15 launch-application Remote execution of installed applications Behavior analysis, automated testing
19 extract-apk Pull APK files from device for reverse engineering Malware analysis, intellectual property

Security Testing & Penetration

Option Function Description Security Impact
23 remove-password Bypass device lock screens and remove security passwords Critical - Full device access
31 start-keylogger Capture all keyboard input and touch events High - Credential harvesting
35 clipboard-hijack Monitor and manipulate clipboard contents Medium - Data interception
37 bluetooth-control Manipulate Bluetooth settings and connections Medium - Network infiltration
41 gps-spoofing Manipulate GPS coordinates and location data Medium - Location fraud

Digital Forensics & Data Extraction

Option Function Description Data Types
9 pull-files Extract files and directories from device storage Documents, media, databases
17 extract-wifi Retrieve WiFi credentials and network configurations Network credentials, WPA keys
33 extract-sms Pull SMS messages and conversation history Text messages, MMS content
34 browser-history Extract web browsing history and cached data URLs, cookies, cached files
42 process-monitor Monitor running processes and system resource usage Process lists, memory usage, CPU stats

My Contributions & Enhancements

Building upon John S. Madaha's excellent foundation, I've implemented several significant improvements to enhance the framework's capabilities and user experience:

Advanced Error Handling & Stability

  • Connection Recovery: Implemented automatic reconnection logic for unstable network connections
  • Device State Validation: Added comprehensive device state checking before command execution
  • Graceful Failure Handling: Enhanced error messages with actionable troubleshooting suggestions
  • Resource Cleanup: Implemented proper cleanup routines to prevent resource leaks

Extended Security Testing Capabilities

Enhanced Security Features
# Advanced keylogging with file output def enhanced_keylogger(): output_file = f"keylog_{datetime.now().strftime('%Y%m%d_%H%M%S')}.txt" cmd = f"adb shell getevent | grep -E 'EV_(KEY|ABS)' >> {output_file}" # Monitor for specific applications target_apps = ["com.android.chrome", "com.whatsapp", "com.facebook.katana"] for app in target_apps: monitor_app_input(app, output_file) # Improved WiFi credential extraction def extract_wifi_advanced(): wpa_paths = [ "/data/misc/wifi/wpa_supplicant.conf", "/data/wifi/bcm_supp.conf", "/data/misc/wifi/p2p_supplicant.conf" ] credentials = [] for path in wpa_paths: if device_file_exists(path): credentials.extend(parse_wifi_config(path)) return deduplicate_credentials(credentials)

Comprehensive Logging & Documentation

  • Detailed Command Logging: Complete audit trail of all executed commands
  • Session Management: Save and restore framework sessions for long-term operations
  • Output Formatting: Structured output suitable for further analysis and reporting
  • Integration APIs: Hooks for integration with other security testing tools

Performance Optimizations

  • Parallel Operations: Concurrent command execution for multiple devices
  • Caching Mechanisms: Smart caching of device information and command results
  • Bandwidth Optimization: Compressed data transfer for large file operations
  • Memory Management: Efficient memory usage for extended testing sessions

Ethical Guidelines & Legal Considerations

Critical Legal Warning:
The Giovanni Android Framework contains powerful capabilities that can be misused for illegal activities. Users must understand and comply with all applicable laws and ethical guidelines.

Authorized Use Cases

  • Penetration Testing: Authorized security assessments with proper documentation
  • Digital Forensics: Law enforcement investigations with appropriate warrants
  • Security Research: Academic or corporate security research on owned devices
  • Personal Device Testing: Security testing of personally owned devices
  • Educational Purposes: Cybersecurity education in controlled environments

Prohibited Activities

Strictly Forbidden: Using this framework for unauthorized access, data theft, privacy violations, stalking, or any illegal surveillance activities.

Best Practices for Ethical Use

  1. Written Authorization: Always obtain explicit written permission before testing
  2. Scope Definition: Clearly define the scope and limitations of testing activities
  3. Data Protection: Secure handling and disposal of any extracted data
  4. Documentation: Maintain detailed logs of all testing activities
  5. Responsible Disclosure: Report discovered vulnerabilities through proper channels

Advanced Troubleshooting Guide

Common issues and their resolutions when working with the Giovanni Framework:

Connection Issues

Problem Symptoms Solution
Device Not Detected "No devices/emulators found" Enable USB debugging, install proper drivers, check cable connection
TCP/IP Connection Fails "Connection refused" or timeout Verify network connectivity, check firewall settings, ensure port 5555 is open
Unauthorized Access "Device unauthorized" Accept debugging prompt on device, regenerate RSA keys if necessary
Root Permission Denied "Permission denied" for root commands Verify root access, check SuperSU/Magisk configuration

Advanced Debugging Techniques

Debug Mode Activation
python3 gvn --debug --verbose [DEBUG] Initializing framework with debug mode... [DEBUG] ADB path: /usr/bin/adb [DEBUG] Checking ADB server status... [VERBOSE] ADB server response: daemon started successfully [DEBUG] Scanning for connected devices... [VERBOSE] Found device: 192.168.1.100:5555 (authorized) [DEBUG] Device capabilities: root=yes, api=30, arch=arm64

Performance Optimization

Framework Performance Tuning
# Optimize for multiple device operations export ADB_TRACE=all export ANDROID_SERIAL=device_id_here # Increase timeout for slow operations adb -s device_id shell "setprop service.adb.tcp.port 5555" adb -s device_id shell "setprop ctl.restart adbd"

Project Impact & Future Development

The Giovanni Android Framework represents a significant advancement in mobile security testing tools, combining the accessibility of a menu-driven interface with the power of comprehensive ADB automation. My contributions to this project have focused on enhancing reliability, expanding capabilities, and ensuring ethical usage.

Technical Achievements

  • Stability Improvements: Enhanced error handling and connection management for production use
  • Feature Expansion: Additional security testing capabilities and forensic analysis tools
  • Documentation Enhancement: Comprehensive documentation for ethical and effective usage
  • Performance Optimization: Improved efficiency for large-scale testing operations

Educational Value

This project serves as an excellent educational platform for understanding:

  • Android security architecture and vulnerabilities
  • ADB protocol and command-line automation
  • Mobile forensics techniques and data extraction
  • Ethical security testing methodologies

Future Enhancement Roadmap

  • GUI Development: Web-based interface for easier operation and result visualization
  • Cloud Integration: Remote device management and distributed testing capabilities
  • ML Integration: Automated threat detection and behavioral analysis
  • Reporting Engine: Professional report generation for security assessments
Professional Impact: This project demonstrates advanced Python programming skills, deep Android security knowledge, and a strong commitment to ethical security testing practices.
Final Acknowledgement:
Special thanks to John S. Madaha for creating the foundational Giovanni Android Framework. This project builds upon his excellent work to create a more robust and feature-complete security testing platform.

Original Author: John S. Madaha
GitHub: https://github.com/GiovanniJohnArthur
Repository: Giovanni Framework Repository