mobilesecurity/mdast_cli repository overview

⁠Mobile DAST CI/CD

Python script for automating security analysis of mobile applications.

This script is designed to integrate mobile applications' security analysis in the continuous development process (CI / CD).
You can also only download applications from supported integrations with distribution systems without scanning.

During the execution of the script, the application is sent for the dynamic analysis. The output is a json/pdf file with detailed results. You can use the local file or download the application from one of the distribution systems. You should have write permissions to download the application.

⁠Launch options

Currently, several distribution systems are supported:

• Local file
• Applications from Google Play⁠
• Applications from Appstore⁠
• Applications from Firebase⁠
• Applications from AppCenter⁠
• Applications from Nexus Repository 3.x⁠ from maven repo.

⁠Launch parameters

⁠Download only

If you just want to download the application without scanning, specify --download_only or -d
After that you will need to specify the distribution system and mandatory parameters for specified system

• distribution_system - distribution method for the application
  possible values file/google_play/appstore/firebase/appcenter/nexus
  For detailed information refer to the respective sections below.

If you want to integrate security analysis of downloaded application in the CI/CD you should specify these parameters.

⁠Scan parameters

The launch options depend on the location of the apk file sent for analysis. Also, there are required parameters that must be specified for launch:

• url - network address for system (the path to the root without the final /)
• profile_id - ID of the profile to be analyzed
• testcase_id - ID of the test case to be executed. This is an optional parameter, if not set - manual scan with 20 seconds delay until finish will be executed;
• token - CI/CD access token (refer to our documentation for ways to retrieve the token)
• company_id - identifier of the company within which the scan will be performed
• architecture_id - identifier of the operating system architecture on which the scan will be performed
• nowait - an optional parameter specifying whether to wait for the scan to complete. If this flag is set, the script will not wait for the scan to complete but will exit immediately after starting. If the flag is not selected, the script will wait for the completion of the analysis process and generate a report.
• summary_report_json_file_name - an optional parameter defining the name of the json file into which the scanning information in json format is uploaded. If the parameter is absent, the information will not be saved.
• pdf_report_file_name - an optional parameter that specifies the name of the pdf file into which information on scanning in pdf format is uploaded. If the parameter is absent, the report will not be saved.

⁠Distribution systems

⁠Local file launch

⁠Parameters

This type of launch implies that the application file is located locally. To select this method at startup, you must specify the parameter distribution_system file.
In this case, the required parameter must specify the path to the file: file_path

Where:

• {path_to_folder_with_application} - absolute path to the folder where build application locating
• {path_to_report_folder} - absolute path to the folder where reports will be generated
• {application_file_name} - full name of the built apk inside the {path_to_folder_with_application} folder

⁠Google play

To download application from Google Play Store you need temporary account with 2fa authentication disabled.

You should specify the package name of the application you want to download, you can get it directly from the Google Play app page or any other way.

Also, you need to select the distribution_system google_play.

During the initial launch of the script you should specify the mandatory parameters: email + password, after that the application will not be downloaded if you don't specify optional parameter google_play_download_with_creds and the scan will not run, but you will receive gsfid and token for google authentication, which you should use later on for the successful Google Play application scan.

⁠Parameters

• google_play_package_name - package name of application you want to download
• google_play_email - email of your Google account for first login only
• google_play_password - password of your Google account for login only

You can download app while logging in by email and password with an optional parameter:

• google_play_download_with_creds - app will be downloaded during initial login

At the initial run of the script you will get the gsfId and auth token in the script logs, you should copy and save them. They are required for stable and successful execution of the script afterwards.

Using these parameters you will have all parameters for successful downloading applications from Google Play Store:

• google_play_package_name - package name of application you want to download
• google_play_gsfid - The Google Services Framework Identifier (GSF ID)
• google_play_auth_token - Google auth token for access to Google Play API

You can also specify downloaded app file name with an optional parameter

• google_play_file_name - file name for app to be saved with

You should use either email + pass ("--google_play_email" + "--google_play_password") or gsfid + token ("--google_play_gsfid" + "google_play_auth_token") arguments for mdast_cli script. For the continuous process you need only gsfid and token.

⁠AppStore

To download application from AppStore you need to know application_id and have iTunes account and credentials for it: email and password with 2FA code.

You need to select the --distribution_system appstore and specify mandatory parameters.

To successfully sign in to iTunes, you will need to obtain and save the 2fa code for later use.
When you run the script for the first time, use your email and password, you will get a login error in the console and at this point a two-factor authentication code will come to your device

For the subsequent work of the script without repeating the step with the manual receipt of 2fa code you need to remember the received code, the session with it will be active for 6 months. After that, try to repeat the login with password and 2FA, formatting it like password2FA. You do not need to get new 2fa codes later, this parameter will work for 6 months.

For example, password is P@ssword and 2FA is 742877, so your parameter --appstore_password2FA P@ssword742877.

To get the app_id, go to the app page in the AppStore in your browser, you can extract the required parameter from the url:

appstore_app_id 398129933 in this example.

⁠Parameters

You need to select the distribution_system appstore and specify the following mandatory parameters:

• appstore_bundle_id or appstore_app_id
  • appstore_bundle_id - bundle id of application
  • appstore_app_id - Application id from AppStore, you can get it on app page from url,
    format: apps.apple.com/app/id{appstore_app_id}
• appstore_apple_id - Your email for iTunes login.
• appstore_password2FA - Your password and 2FA code for iTunes login, format: password2FA_code

You can specify downloaded app file name with an optional parameter

• appstore_file_name - file name for app to be saved with

⁠Details

If you lost the 2fa code and the login has already been made, the session will be active for a few time without using 2fa, only apple_id + password. You also will not be able to end your session via this script, so for the script to work correctly you need to login again after session expires and save the two-factor authentication code in your notes.

If there is an error associated with the wrong Apple ID when you start scanning:

or error in logs:

"Logging in to the App Store. To open app, log in with the Apple ID with which you made the purchase."

Then contact the support team to agree on an Apple ID, which will be used for AppStore integration, you will be offered a solution to this problem.

While creating AppStore integration ipatool⁠ helped a lot, huge thanks for everyone who contributed to this nice open-source tool.

⁠Firebase

To download the application from firebase platform you need to know some cookies for Google SSO authentication and project_id, app_id, app_code, api_key and file_extension parameters from firebase project.
You need to select the --distribution_system firebase and specify mandatory parameters.

First, you should log in via Google SSO to Firebase⁠ and get necessary cookies from your Chrome session local storage(F12 -> Application -> Cookies)
And copy SID, SSID, APISID, SAPISID, HSID to your launch command. The lifetime of them are 2 years, so you don't have to do it often :)

⁠Parameters

• firebase_SID_cookie - SID
• firebase_HSID_cookie - HSID
• firebase_SSID_cookie - SSID
• firebase_APISID_cookie - APISID
• firebase_SAPISID_cookie - SAPISID

So, you just extract missing parameters from this request and your launch command for CI/CD mobile applications' security analysis is ready! Request url will match this pattern, you should extract 4 parameters from url. /v1/projects/{project_id}/apps/{app_id}/releases/{app_code}:getLatestBinary?alt=json&key={api_key}

• firebase_project_id - project id of your Firebase project
• firebase_app_id - application id
• firebase_app_code - application code
• firebase_api_key - your api key
• firebase_app_extension - your app extension, it can be apk for android and ipa for iOS

You can specify the downloaded app file name with an optional parameter

• firebase_file_name - file name for app to be saved with

⁠AppCenter

⁠Parameters

To download the application from AppCenter distribution system you need to select the distribution_system appcenter parameter. Also, you need to specify the following mandatory parameters:

• appcenter_token - API access token. Look in official documentation to learn how to retrieve it⁠.
• appcenter_owner_name - owner of the application. Look in official documentation to learn how to retrieve the owner name⁠.
• appcenter_app_name - the name of the application in the AppCenter system. Look in official documentation to learn how to retrieve it⁠
• appcenter_release_id or appcenter_app_version
  • appcenter_release_id - ID of the specific release of the application to be downloaded from AppCenter. There is a possibility to select the "latest" value - the latest available version⁠ of the application will be downloaded.
  • appcenter_app_version - this parameter finds and downloads the specific version of the application by its version ID (shown in Android Manifest) (the "version" field in the AppCenter Documentation⁠)

⁠Nexus

To download the application from maven repository you need to know the repository where the mobile application is stored and its group_id, artifact_id and version. To upload mobile application to Nexus you can use this snippet⁠ for android apk and this one⁠ for iOS ipa.

Also, you need to select the distribution_system nexus and specify the following mandatory parameters:

• nexus_url - http(s) url for Nexus server where the mobile application is located.
• nexus_login - username for Nexus server with permissions to the repository where mobile application is located.
• nexus_password - password for the Nexus server with permissions to the repository where mobile application is located.
• nexus_repo_name - repository name in Nexus where mobile application is located.
• nexus_group_id - group_id of the uploaded mobile application from maven data.
• nexus_artifact_id - artifact_id of the uploaded mobile application from maven data.
• nexus_version - version of the uploaded mobile application from maven data.