The following steps allow organizations to automatically scan pre-production releases of their mobiles mobile apps using existing developer tools & and processes. DevOps can fully automate the SDLC by integrating our API to existing CI/CD tools such as Travis CI, Jenkins, Bitrise, fastlaneFastlane, Xcode server, etc. Please send the following info do your developers.

Image Removed

...

Quickstart guide

The Upload API can be used to upload PreProd mobile binaries directly to Data Theorem for scanning.

In order to upload a PreProd mobile app binary, two API calls are needed:

• The first one is to generate and retrieve an upload_url.
• The second one is a standard multipart upload to the upload_url with the actual App binary (IPA, APK, etc.) and some additional, optional meta data (such as comments, or credentials needed for dynamic scanning).

Current Version

There is only one version: v1, available at https://api.securetheorem.com/uploadapi/v1/.

Endpoints

Step 1 - Upload Init

The upload process can be initialized by calling the this method.

Authentication

Authentication is done by passing your organization’s Upload API key as part of the the Authorizationheader:

Authorization: Bearer 1234567890abcdefgh

The Upload API key can be retrieved by users in the Data Theorem portal athttps://www.securetheorem.com/sdlc within the “API Key” section.

Request

POST /uploadapi/v1/upload_init

For example, this method can be called via curl using:

...

The full documentation is available at: https://datatheorem.github.io/PortalApi/upload_api.html.

Step 1: Retrieving the Upload API key

First, you will need to retrieve your organization's Upload API key from the portal, at https://securetheorem.com/devsecops/v2/scancicdat the top of the page:

Image Added

Step 2: Configuring an upload step in CI/CD

Most CI/CD systems (Travis CI, Bitrise, CircleCI, etc.) allow running a bash script as a step within the CI pipeline. A new step should be added at the end of your existing mobile pipeline to upload the signed application binary (APK or IPA) to Data Theorem.

This new upload step requires:

• The Upload API key retrieved in step 1 to be available in the CI system via the DT_UPLOAD_API_KEY environment variable.
• The path to the compiled and signed mobile binary to be available in the CI system via the SIGNED_BINARY_PATH environment variable.

The following bash script can then be used as the upload step:

#!/usr/bin/env bash
# Fail if any commands fails
set -ex

maxRetries=3
for (( retry = 0; retry < maxRetries; retry++ ))
do
  # Step 1: get the upload URL
  echo "Get upload url"
  step1_response=$(curl -s -w "%{http_code}" -X POST -H "Authorization: 

...

APIKey ${DT_UPLOAD_API_KEY}"  --data ""  https://api.securetheorem.com/uploadapi/v1/upload_init)

...

Response

...

...

The response contains the upload_url, to be used for uploading the mobile binary; this URL will only be valid for 10 minutes.

Step 2 - Actual upload

After retrieving the upload_url, the mobile app binary should be sent as a standard multipart file upload, with the following arguments:

• file: The mobile binary (APK, IPA, APPX or XAP) to be scanned.
• username (optional): Username to be used to log into the application for dynamic scanning.
• password (optional): Password to be used to log into the application for dynamic scanning.
• comments (optional): Miscellaneous comments regarding the upload.
• release_id (optional): Only useful when processing results via the Webhook API. This custom ID will be present in the result payload and can be used to map a specific build with its scan results. If not set, it will default to the build version.

Authentication

Since the upload_url is unique for each upload, there is no need to authenticate with the Upload API Key.

Request

POST {upload_url}

The request must be a standard multipart file upload, the mobile app binary is expected in the file field.

For example, this method can be called via curl using:

$ curl -F file=@androidapp.apk -F "comments=uploaded with curl" -F "username=testuser" -F "password=testpass" https://appupload.securetheorem.com/_ah/upload/Aewsadw[...]/

Note: Pay special attention to the @ character that needs to be put in front of the file’s name, for the curl command to work.

Since the upload_url is unique for each upload, there is no need to authenticate with the Upload API key.

Response

A successful upload returns a status code 200 and status text ok.

{
  "session_id": "<session_id>",
  "status": "ok",
  "bundle_id": "com.myapp",
  "name": "My App",
  "is_app_new": false,
  "platform": "IOS"
}

Errors are also JSON formatted.

{
  "status": "package_corrupted",
  "error": "Build looks corrupted",
  "session_id": "<session_id>"
}

Status/error code mapping

• 200/ok: upload succeed
• 401/unauthorized: unauthorized (bad credentials or the url may have expired)
• 403/mobile_app_has_no_subscription: this mobile app has no active subscription, please contact Data Theroem
• 415/unauthorized_package_extension: unauthorized extension, must be ipa/apk/xap/appx, case insensitive
• 422/package_corrupted: package corrupted
• 500/error: internal server error

...

http_code=${step1_response: -3}
  response_body=${step1_response::-3}

  # For older versions of bash e.g. GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin21)
  # response_body=${step1_response%???}
  # http_code=${step1_response#${response_body}}

  # Check that http status code is 200
  [ ! ${http_code} -eq 200 ] && echo ${response_body} && exit 1
  upload_url=$(echo ${response_body} | jq -r ".upload_url")
  echo ${upload_url}

  # Step 2: upload the APK
  echo "Upload app"
  step2_response=$(curl -F file=@${SIGNED_BINARY_PATH} ${upload_url}) && echo ${step2_response} && break
done

if [ ${retry} -ge ${maxRetries} ]; then
  echo "Upload failed after ${maxRetries} attempts"
  exit 1
fi

It is possible to specify optional data elements with the submission.  Optional parameters include

• test credentials (username and password) to be used during the dynamic analysis of the application
• release_id and external_id to help you identify this application and build
• platform variant for iOS applications
• and more

For more information on the available optional data elements, please see the Upload API documentation.  You can add one or more -F "key=value" blocks to the curl command used in Step 2.  For example, if you would like to submit test credentials for dynamic testing and the external id of the app, you can modify the Step 2 curl command as follows, while keeping the rest of the script unchanged.

step2_response=$(curl -F file=@${SIGNED_BINARY_PATH} -F "username=test" -F "password=${TEST_PASSWORD}" -F "external_id=12345" ${upload_url}) && echo ${step2_response} && break

Once the CI/CD uploads are enabled, pre-production scans will be completed automatically. Please note:

• Scan alerts will still be sent when pre-production scans start and complete
• Public app store releases will still be scanned as well
• All results will be published to the portal (where pre-prod apps are labeled as “PreProd”)

Additional Resources

More detailed guides are available for specific CI/CD systems:

• Pre-Production Scans: Uploads via Jenkins
• Pre-Production Scans: Uploads via Bitrise