Puma is a Python library for executing app-specific actions on mobile devices such as sending a message or starting a
call. The goal is that you can focus on what should happen rather than how this should happen, so rather than write
code to "tap on Bob's conversation on Alice's phone, enter the message, and press send", you can simply write "send a
Telegram message to Bob from Alice's phone".
See the full demo video here.
To execute actions on the mobile device, Puma uses Appium, and open-source project for UI automation.
Puma was created at the NFI to improve our process of creating test and reference datasets. Our best practices on creating test data can be found here. If you are wondering whether you should make your own test data, or whether you should use Puma for it, this document goes into the advantages of doing so.
Puma is an open-source non-commercial project, and community contributions to add support for apps, or improve support of existing apps are welcome! If you want to contribute, please read CONTRIBUTING.md.
| Platform | Devices | Runs on | Setup |
|---|---|---|---|
| Android | Physical devices, emulators | Linux, macOS, Windows | Setting up Android |
| iOS | Physical devices, simulators | macOS (with Xcode) | Setting up iOS |
- Install the required software with the installation script for your operating system, see installation.
- Connect your device (or start an emulator or simulator), and get its UDID. See
setting up Android or setting up iOS.
⚠️ Make sure the device is set to English!
- Install Puma. We recommend installing packages within a Python venv.
pip install pumapy- Run Appium. This starts the Appium server, a process that needs to run while you use Puma.
appium- Use Puma! The API is the same on both platforms:
from puma.utils import configure_default_logging
configure_default_logging() # Use Puma's logging configuration. You can also implement your own
# Android
from puma.apps.android.google_chrome.google_chrome import GoogleChrome
android_phone = GoogleChrome("emulator-5554")
android_phone.visit_url_new_tab("example.com")
# iOS
from puma.apps.ios.safari.safari import Safari
iphone = Safari("A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D")
iphone.visit_url_new_tab("example.com")See using Puma for more examples, and how navigation, contexts and verification of actions work. For a
demo of Puma on iOS, run python -m demo.ios_demo --udid <udid> from the root of the repository. The demo uses Safari,
Contacts, Calendar, Reminders and Messages, and travels a bike route in Apple Maps by simulating the location of the
device. On real devices, it turns off Auto-Lock in Settings during the demo, and restores it afterwards. For an
extensive step-by-step guide on how to use (and develop) Puma, see the Puma Tutorial.
The following apps are supported by Puma. Each app has its own documentation page detailing the supported actions with example implementations. Each version of Puma supports one version of each app, see supported versions.
| App | Platform | Supported version |
|---|---|---|
| Google Camera | Android | 8.8.225.510547499.09 |
| Google Chrome | Android | 145.0.7632.159 |
| Google Maps | Android | 26.10.01 |
| Google Play Store | Android | 48.3.25-31 |
| Open Camera | Android | 1.55 |
| Settings (Google Pixel) | Android | Android 16 |
| Snapchat | Android | 12.89.0.40 |
| Telegram | Android | 12.0.1 |
| TeleGuard | Android | 4.0.9 |
| Android | 2.26.40.76 | |
| WhatsApp for Business | Android | 2.25.24.78 |
| App Store (real devices only) | iOS | iOS 26.6 |
| Apple Maps | iOS | iOS 26.2 |
| Calendar | iOS | iOS 26.2 |
| Contacts | iOS | iOS 26.2 |
| Messages | iOS | iOS 26.6 |
| Reminders | iOS | iOS 26.2 |
| Safari | iOS | iOS 26.2 |
| Settings (real devices only) | iOS | iOS 26.6 |
| Telegram (real devices only) | iOS | 13.0 |
- Installation
- Setting up Android devices
- Setting up iOS devices
- Using Puma: examples, navigation, verifying actions and supported versions
- Logging: Puma's logging and the ground truth logger
- Troubleshooting
- Writing Puma apps: how Puma apps work, and how to add a new app
- Test data guidelines and why make your own test data
If you use Puma in your research, please cite our paper:
@article{CLAIJSWART2025301985,
title = {Automatically generating digital forensic reference data triggered by mobile application updates},
journal = {Forensic Science International: Digital Investigation},
volume = {54},
pages = {301985},
year = {2025},
issn = {2666-2817},
doi = {https://doi.org/10.1016/j.fsidi.2025.301985},
url = {https://www.sciencedirect.com/science/article/pii/S2666281725001258},
author = {Angelina A. Claij-Swart and Erik Oudsen and Bouke Timbermont and Christopher Hargreaves and Lena L. Voigt},
keywords = {Digital forensics, Datasets, Reference data, Data synthesis, Tool validation, Tool testing, Mobile forensics},
abstract = {Mobile applications are subject to frequent updates, which poses a challenge for validating digital forensic tools. This paper presents an approach to automate the generation of reference data on an ongoing basis, and how this can be integrated into the overall validation process of a digital forensic analysis platform. Specifically, it describes the architecture of the mobile data synthesis framework Puma, shares its capabilities via an open-source project, and shows how it can be used in a tool testing workflow triggered by application updates. The value of this approach is demonstrated with three example use cases, documenting the use of the approach over six months and reporting insights and experiences gained from this integration. Finally, this work highlights additional contributions the proposed approach and tooling could make to the digital forensics community.}
}Claij-Swart, A. A., Oudsen, E., Timbermont, B., Hargreaves, C., & Voigt, L. L. (2025). Automatically generating digital forensic reference data triggered by mobile application updates. Forensic Science International: Digital Investigation, 54(Supplement), 301985. https://doi.org/10.1016/j.fsidi.2025.301985