develop.md

Requirements

Requirements for setting up MobSF locally.

System Requirements: 8GB+ RAM, 3GHz CPU, 80GB+ Free Disk Space

Operating Systems: Mac, Linux, Windows

Static Analysis

• Mac

  • Install Git

    brew install git

  • Install Python 3.10+

  • Install OpenJDK 21+ and configure JAVA_HOME environment variable

  • Install command line tools

    xcode-select --install
    sudo xcode-select --switch /Applications/Xcode.app

  • Install wkhtmltopdf as per the wiki instructions

  • Windows App Static analysis requires a Windows Host or Windows VM for Mac and Linux. More Info

• Ubuntu/Debian based Linux

  • Install Git

    sudo apt install git -y

  • Install Python 3.10+

  • Install OpenJDK 21+ and configure JAVA_HOME environment variable.

    sudo apt install openjdk-21-jdk -y

  • Install the following dependencies:

    sudo apt install python3-dev python3-venv python3-pip build-essential \
      libffi-dev libssl-dev libxml2-dev libxslt1-dev \
      libjpeg8-dev zlib1g-dev wkhtmltopdf -y

  • Windows App Static analysis requires a Windows Host or Windows VM for Mac and Linux. More Info

• Windows

  • Install Git
  • Install Python 3.10+
  • Install OpenJDK 21+ and configure JAVA_HOME environment variable.
  • Install Microsoft Visual C++ Build Tools
  • Install OpenSSL (non-light)
  • Download & Install wkhtmltopdf as per the wiki instructions
  • Add the folder that contains wkhtmltopdf binary to environment variable PATH.

?> IMPORTANT: iOS IPA Analysis works only on Mac, Linux and Docker containers.

---

Installation

Tested on Windows 10, Ubuntu 22.04 , macOS 14.3 (M3)

!> Please make sure that all the requirements mentioned are installed first.

# Clone the MobSF repo
git clone https://github.com/MobSF/Mobile-Security-Framework-MobSF.git
cd Mobile-Security-Framework-MobSF

# Linux or Mac
./setup.sh

# Windows
setup.bat

?> Windows users, before running setup.bat close any opened folders of MobSF or text editors with MobSF opened. Either of these can interrupt the setup by causing permission errors.

---

Running MobSF

# Linux or Mac
./run.sh 127.0.0.1:8000

# Windows
run.bat 127.0.0.1:8000

!> MobSF server will listen on 0.0.0.0:8000 if you use the run script without arguments.

In your web browser, navigate to http://localhost:8000/ to access MobSF web interface. The default credentials are mobsf/mobsf.

---

Asynchronous Scan Queues

MobSF also supports asynchronous task queues.

# Linux or Mac
MOBSF_ASYNC_ANALYSIS=1 ./run.sh

# Windows
set MOBSF_ASYNC_ANALYSIS=1
run.bat

# Run DjangoQ2 cluster to accept scan jobs.
poetry run python manage.py qcluster

Dynamic Analysis

You need one of the following Android/iOS virtual device for Dynamic Analysis.

• Genymotion Desktop
• Genymotion Cloud
• Android Studio Emulator
• Corellium Android
• Corellium iOS

!> Dynamic analysis using real mobile device is possible for Android, but not supported by us.

Genymotion Android

?> Supports arm64, x86, x86_64 architecture Android 4.1 - 11.0, upto API 30

Genymotion is the preferred dynamic analysis environment that you can setup with the least friction. Run a Genymotion Android VM before starting MobSF. Everything will be configured automatically at runtime. We recommend using Android 7.0 and above.

• Android 5.0 - 11.0 - These versions uses Frida and works out of the box with zero configuration or setup.
• Android 4.1 - 4.4 - These versions uses Xposed Framework and requires that you should MobSFy the runtime prior to Dynamic Analysis for the first time. These versions also require VM reboot after installing Xposed Modules.

Click MobSFy Android Runtime button in Android Dynamic Analyzer page to MobSFy the android runtime environment.

HTTPS Proxy

• For Android versions 4.4 - 11.0, global proxy settings are automatically applied at runtime.
• For Android version 4.1 - 4.3, set Android VM proxy as displayed in Dynamic Analyzer page.

If MobSF Dynamic Analyzer doesn't detect your android device, set the device identifier via the environment variable MOBSF_ANALYZER_IDENTIFIER before running MobSF.

Example: MOBSF_ANALYZER_IDENTIFIER='192.168.56.101:5555'. You can find the Android Device IP from the Genymotion title bar and the default port is 5555.

Android Studio Emulator

?> Supports arm, arm64, x86 and x86_64 architecture Android 5.0 - 11.0, upto API 30

Install or upgrade your Android Studio to the latest. Android Emulator image with Google Play Store is considered as production image and you cannot use that with MobSF.

Create an Android Virtual Device (AVD) without Google Play Store.

!> You must not choose non-rooted production images. MobSF requires rooted images without Google Playstore pre-installed.

After creating the AVD, run it once and make sure everything is alright. Close it along with Android Studio if it's running.

Run Android Virtual Device (AVD)

Run an AVD before starting MobSF using scripts/start_avd.sh or scripts/start_avd.ps1

# Run the script to list out available AVDs
scripts/start_avd.sh 
Available AVDs:

Medium_Phone_API_35
Pixel_5_API_30
Pixel_6a_API_29

Use any Android AVD 5.0 - 11.0, up to API 30 without Google Play (production image).
Usage: scripts/start_avd.sh AVD_NAME [START_PORT] [open_gapps.zip path]
Example: scripts/start_avd.sh Pixel_6_Pro_API_28 5554 /path/to/open_gapps.zip

# Choose the AVD you created, make sure it is a non-production AVD.
# MobSF will not work with production AVDs.

sscripts/start_avd.sh Pixel_5_API_30

Everything will be configured automatically at runtime. MobSF requires AVD version 5.0 to 11.0 for dynamic analysis.

HTTPS Proxy

• For Android versions 5.0 - 8.0, MobSF attempts to set global proxy, but might fail due to a bug in adb. Configure proxy settings manually in such cases.
• For Android version 9.0 and above, global proxy settings are automatically applied at runtime.

GApps on AVD (Optional)

If you need Google Playstore, download the appropriate package from https://opengapps.org/. Run the start_avd script with path to the GApps zip file. This is currently not supported in Windows. You will have to manually do the necessary steps.

scripts/start_avd.sh Pixel_6a_API_29 5554 ~/Downloads/open_gapps-arm64-10.0-stock-20220215.zip

If MobSF Dynamic Analyzer doesn't detect your android device, idenify the emulator serial number.

You can set the device identifier via the environment variable MOBSF_ANALYZER_IDENTIFIER before running MobSF.

Example: MOBSF_ANALYZER_IDENTIFIER='emulator-5554'

Genymotion Cloud Android

?> Supports arm64, x86, x86_64 architecture Android 5.1 - 11.0, upto API 30

Run a Genymotion Android VM in cloud and connect to it via adb before starting MobSF. Everything will be configured automatically at runtime. We recommend using Android 7.0 and above.

This documentation uses Amazon Web Services (AWS) as an example. You need to follow similar steps in Genymotion Cloud SaaS, Microsoft Azure, Google Cloud Platform, or Alibaba Cloud.

1. Launch an EC2 instance with Genymotion AMI

2. Modify the Security Group of the AMI to allow inbound TCP connections to port 5555. This is required for remote adb connection to Genymotion Cloud VM.

3. Access Genymotion Cloud VM by navigating to it's Public IP. The default username is genymotion and the password is EC2 instance id. More Info

4. Go to Configuration and Enable ADB

5. From your local machine, ensure that you can connect to Genymotion Cloud VM via adb.

adb connect <public_ip>:5555
adb devices

6. You can now perform MobSF Dynamic Analysis with Genymotion Cloud VM in AWS.

If MobSF Dynamic Analyzer doesn't detect your Cloud VM, set the device identifier via the environment variable MOBSF_ANALYZER_IDENTIFIER before running MobSF.

Example: MOBSF_ANALYZER_IDENTIFIER='<public_ip>:5555'.

If MobSF cannot detect adb, you need to configure ADB_BINARY in <user_home_dir>/.MobSF/config.py.

Example: ADB_BINARY='/Applications/Genymotion.app/Contents/MacOS/tools/adb'.

Corellium Android VM

?> Supports rooted userdebug builds, arm64 architecture Android 7.1.2 - 11.0, upto API 30

!> You must not choose non-rooted user builds. MobSF requires rooted userdebug builds.

1. After creating a supported rooted userdebug Android device, Follow Corellium's Connect via VPN instructions.

2. Do connect to Corellium network using provided VPN configuration.

3. Run adb connect locally to ensure that the connection is working from your host.

4. Set the environment variable MOBSF_ANALYZER_IDENTIFIER as <private_ip>:<port> of Corellium Android device before running MobSF. (Example: 10.11.1.1:5001).

Corellium iOS VM

Supports jailbroken Corellium iOS VMs from MobSF v3.8.0 onwards.

!> Non jailbroken devices cannot be used with MobSF. Real devices are not supported at this time.

1. After setting up Corellium account, create an API key from https://app.corellium.com/profile/api

2. Set the API key in the environment variable MOBSF_CORELLIUM_API_KEY. If you are using enterprise version of Corellium using a different domain. You must also supply the environment variable MOBSF_CORELLIUM_API_DOMAIN with the correct domain value.

3. To enable MobSF HTTPs proxying, You will have to configure the proxy settings in the iOS VM. Go to iPhone Settings -> Wi-Fi -> Choose the Corellium WiFi -> Scroll down and choose Configure Proxy -> ChooseManual configuration -> Set the Server as 127.0.0.1 and Port as 1337 -> Click Save.

4. Run MobSF and now you can create or manage jailbroken iOS VMs with Corellium for Dynamic Analysis.

---

Updating MobSF

cd Mobile-Security-Framework-MobSF/
git pull origin master
poetry update
poetry run python manage.py makemigrations
poetry run python manage.py makemigrations StaticAnalyzer
poetry run python manage.py migrate
poetry run python manage.py create_roles
# For Linux/Mac
poetry run python mobsf/MobSF/tools_download.py ~/.MobSF
DJANGO_SUPERUSER_PASSWORD=mobsf poetry run python manage.py createsuperuser --noinput --username "mobsf" --email ""
# For Windows
poetry run python mobsf/MobSF/tools_download.py %USERPROFILE%\.MobSF
set DJANGO_SUPERUSER_PASSWORD=mobsf && poetry run python manage.py createsuperuser --noinput --username "mobsf" --email ""

!> If database migration fails, delete the MobSF directory (~/.MobSF on Linux & Mac, C:\Users\<user>\.MobSF on Windows) and rerun the setup script (setup.sh for Linux & Mac or setup.bat for Windows). Note that this will remove all previous scan results and data.

---

Running Tests

We use tox for running tests.

pip install tox

#For linting
tox -e lint

# For running lint + test
tox -e lint,test