288 lines
11 KiB
Python
288 lines
11 KiB
Python
import logging
|
|
import re
|
|
import shutil
|
|
import subprocess
|
|
|
|
from pathlib import Path
|
|
|
|
import frida
|
|
import requests
|
|
|
|
from frida.core import Device
|
|
|
|
# Suppress urllib3 warnings
|
|
logging.getLogger("urllib3.connectionpool").setLevel(logging.ERROR)
|
|
|
|
|
|
def shell(prompt: list) -> subprocess.CompletedProcess:
|
|
"""
|
|
Executes a shell command and returns the result.
|
|
|
|
Parameters:
|
|
prompt (list): The command to execute as a list of strings.
|
|
|
|
Returns:
|
|
subprocess.CompletedProcess: The result containing return code, stdout, and stderr.
|
|
"""
|
|
prompt = list(map(str, prompt)) # Ensure all command parts are strings
|
|
# logging.getLogger("Shell").debug(" ".join(prompt))
|
|
return subprocess.run(prompt, capture_output=True) # Run the command and capture output
|
|
|
|
|
|
class ADB:
|
|
"""
|
|
Class for managing interactions with the Android device via ADB.
|
|
"""
|
|
|
|
def __init__(self, device: str = None, timeout: int = 5):
|
|
"""
|
|
Initializes ADB connection to the device.
|
|
|
|
Parameters:
|
|
device (str, optional): Device ID to connect to, defaults to the first USB device.
|
|
timeout (int, optional): Timeout for connection in seconds. Defaults to 5.
|
|
|
|
Raises:
|
|
EnvironmentError: If ADB is not found in the system path.
|
|
Exception: If connection to the device fails.
|
|
"""
|
|
self.logger = logging.getLogger(self.__class__.__name__)
|
|
|
|
# Ensure ADB is available
|
|
if not shutil.which("adb"):
|
|
raise EnvironmentError(
|
|
"ADB is not recognized as an environment variable. "
|
|
"Ensure ADB is installed and refer to the documentation: "
|
|
"https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md#adb-android-debug-bridge"
|
|
)
|
|
|
|
# Start the ADB server if not already running
|
|
sp = shell(['adb', 'start-server'])
|
|
if sp.returncode != 0:
|
|
self.logger.warning("ADB server startup failed (Error: %s)", sp.stdout.decode("utf-8").strip())
|
|
|
|
# Connect to device (or default to the first USB device)
|
|
try:
|
|
self.device: Device = frida.get_device(id=device, timeout=timeout) if device else frida.get_usb_device(timeout=timeout)
|
|
self.logger.info("Connected to device: %s (%s)", self.device.name, self.device.id)
|
|
except Exception as e:
|
|
self.logger.error("Failed to connect to device: %s", e)
|
|
raise e
|
|
|
|
self.prompt = ['adb', '-s', self.device.id, 'shell']
|
|
|
|
# Retrieve and log device properties
|
|
properties = self.device_properties()
|
|
if properties:
|
|
self.logger.info("SDK API: %s", properties.get("ro.build.version.sdk", "Unknown"))
|
|
self.logger.info("ABI CPU: %s", properties.get("ro.product.cpu.abi", "Unknown"))
|
|
else:
|
|
self.logger.warning("No device properties retrieved")
|
|
|
|
def device_properties(self) -> dict:
|
|
"""
|
|
Retrieves system properties from the device.
|
|
|
|
Returns:
|
|
dict: A dictionary mapping property keys to their corresponding values.
|
|
"""
|
|
# https://source.android.com/docs/core/architecture/configuration/add-system-properties?#shell-commands
|
|
properties = {}
|
|
|
|
# Execute the shell command to retrieve device properties
|
|
sp = shell([*self.prompt, 'getprop'])
|
|
if sp.returncode != 0:
|
|
self.logger.error("Failed to retrieve device properties (Error: %s)", sp.stdout.decode("utf-8").strip())
|
|
return properties
|
|
|
|
# Parse the output and cast values accordingly
|
|
for line in sp.stdout.decode("utf-8").splitlines():
|
|
match = re.match(r"\[(.*?)\]: \[(.*?)\]", line)
|
|
if match:
|
|
key, value = match.groups()
|
|
|
|
# Cast numeric and boolean values where appropriate
|
|
if value.isdigit():
|
|
value = int(value)
|
|
elif value.lower() in ("true", "false"):
|
|
value = value.lower() == "true"
|
|
|
|
properties[key] = value
|
|
|
|
return properties
|
|
|
|
def list_applications(self, user: bool = True, system: bool = False) -> dict:
|
|
"""
|
|
Lists installed applications on the device, with optional filters for user/system apps.
|
|
|
|
Parameters:
|
|
user (bool, optional): Include user-installed apps. Defaults to True.
|
|
system (bool, optional): Include system apps. Defaults to False.
|
|
|
|
Returns:
|
|
dict: A dictionary of application packages and their file paths.
|
|
"""
|
|
applications = {}
|
|
|
|
# Validate input; return empty dict if no filter is set
|
|
if not user and not system:
|
|
return applications
|
|
|
|
# Set the appropriate shell command based on user/system filters
|
|
prompt = [*self.prompt, 'pm', 'list', 'packages', '-f']
|
|
if user and not system:
|
|
prompt.append("-3")
|
|
elif not user and system:
|
|
prompt.append("-s")
|
|
|
|
# Execute the shell command to list applications
|
|
sp = shell(prompt)
|
|
if sp.returncode != 0:
|
|
self.logger.error("Failed to retrieve app list (Error: %s)", sp.stdout.decode("utf-8").strip())
|
|
return applications
|
|
|
|
# Parse and add applications to the dictionary
|
|
for line in sp.stdout.decode("utf-8").splitlines():
|
|
try:
|
|
path, package = line.strip().split(":", 1)[1].rsplit("=", 1)
|
|
applications[package] = path
|
|
except Exception as e:
|
|
pass
|
|
|
|
return applications
|
|
|
|
def start_application(self, package: str) -> bool:
|
|
"""
|
|
Starts an application by its package name.
|
|
|
|
Parameters:
|
|
package (str): The package name of the application.
|
|
|
|
Returns:
|
|
bool: True if the app was started successfully, False otherwise.
|
|
"""
|
|
# Get package information using dumpsys
|
|
sp = shell([*self.prompt, 'dumpsys', 'package', package])
|
|
lines = sp.stdout.decode("utf-8").splitlines()
|
|
|
|
# Remove empty lines to ensure backwards compatibility
|
|
lines = [l.strip() for l in lines if l.strip()]
|
|
|
|
# Look for MAIN activity to identify entry point
|
|
for i, line in enumerate(lines):
|
|
if "android.intent.action.MAIN" in line:
|
|
match = re.search(fr"({package}/[^ ]+)", lines[i + 1])
|
|
if match:
|
|
# Start the application by its main activity
|
|
main_activity = match.group()
|
|
sp = shell([*self.prompt, 'am', 'start', '-n', main_activity])
|
|
if sp.returncode == 0:
|
|
return True
|
|
|
|
self.logger.error("Failed to start app %s (Error: %s)", package, sp.stdout.decode("utf-8").strip())
|
|
break
|
|
|
|
self.logger.error("Package %s not found or no MAIN intent", package)
|
|
return False
|
|
|
|
def enumerate_processes(self) -> dict:
|
|
"""
|
|
Lists running processes and maps process names to their PIDs.
|
|
|
|
Returns:
|
|
dict: Dictionary of process names and corresponding PIDs.
|
|
"""
|
|
# https://github.com/frida/frida/issues/1225#issuecomment-604181822
|
|
processes = {}
|
|
|
|
# Attempt to get the list of processes using the 'ps -A' command
|
|
prompt = [*self.prompt, 'ps']
|
|
sp = shell([*prompt, '-A'])
|
|
lines = sp.stdout.decode("utf-8").splitlines()
|
|
|
|
# If the output has less than 10 lines, retry with a simpler 'ps' command
|
|
if len(lines) < 10:
|
|
sp = shell(prompt)
|
|
if sp.returncode != 0:
|
|
self.logger.error("Failed to execute ps command (Error: %s)", sp.stdout.decode("utf-8").strip())
|
|
return processes
|
|
lines = sp.stdout.decode("utf-8").splitlines()
|
|
|
|
# Iterate through lines starting from the second line (skipping header)
|
|
for line in lines[1:]:
|
|
try:
|
|
parts = line.split() # USER,PID,PPID,VSZ,RSS,WCHAN,ADDR,S,NAME
|
|
pid = int(parts[1]) # Extract PID
|
|
name = " ".join(parts[8:]).strip() # Extract process name
|
|
|
|
# Handle cases where process name might be in brackets (e.g., kernel threads)
|
|
name = name if name.startswith("[") else Path(name).name
|
|
processes[name] = pid
|
|
except Exception as e:
|
|
pass
|
|
|
|
return processes
|
|
|
|
def install_application(self, path: Path = None, url: str = None) -> bool:
|
|
"""
|
|
Installs an application on the device either from a local file or by downloading from a URL.
|
|
|
|
Parameters:
|
|
path (Path, optional): The local file path of the APK to install. Defaults to None.
|
|
url (str, optional): The URL to download the APK from. Defaults to None.
|
|
|
|
Returns:
|
|
bool: True if the installation was successful, False otherwise.
|
|
"""
|
|
# Prepare the shell command for installation
|
|
prompt = [*self.prompt[:-1], 'install']
|
|
|
|
# Install from a local file path if a valid path is provided
|
|
if path and path.is_file():
|
|
sp = shell([*prompt, path]) # Run the installation command with the local file path
|
|
if sp.returncode == 0:
|
|
return True
|
|
self.logger.error("Installation failed for local path: %s (Error: %s)", path, sp.stdout.decode("utf-8").strip())
|
|
|
|
# If URL is provided, attempt to download the APK and install it
|
|
status = False
|
|
if url:
|
|
file = Path("tmp.apk") # Temporary file to store the downloaded APK
|
|
try:
|
|
# Download the APK from the provided URL
|
|
r = requests.get(url, headers={"Accept": "*/*", "User-Agent": "KeyDive/ADB"})
|
|
r.raise_for_status()
|
|
|
|
# Save the downloaded APK to a temporary file
|
|
file.write_bytes(r.content)
|
|
|
|
# Attempt installation from the downloaded APK
|
|
status = self.install_application(path=file)
|
|
except Exception as e:
|
|
self.logger.error("Failed to download application from URL: %s (Error: %s)", url, e)
|
|
file.unlink(missing_ok=True) # Clean up the temporary file, even if there was an error
|
|
|
|
return status
|
|
|
|
def open_url(self, url: str) -> bool:
|
|
"""
|
|
Opens a specified URL on the device.
|
|
|
|
Parameters:
|
|
url (str): The URL to be opened on the device.
|
|
|
|
Returns:
|
|
bool: True if the URL was successfully opened, False otherwise.
|
|
"""
|
|
# Execute the shell command to open the URL using the Android 'am' (Activity Manager) command.
|
|
sp = shell([*self.prompt, 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', url])
|
|
|
|
# Check the result of the command execution and log if there is an error
|
|
if sp.returncode != 0:
|
|
self.logger.error("URL open failed for: %s (Return: %s)", url, sp.stdout.decode("utf-8").strip())
|
|
return False
|
|
return True
|
|
|
|
|
|
__all__ = ("ADB",)
|