Ostorlab Integration with GitLab

In this guide, we will explore how to easily Integrate Ostorlab autonomous security testing for Android and iOS mobile apps to your gitlab build process.

Generate new API key

Walkthrough: Menu → Integrations/API → API Keys → New API Key → Create Key → copy the key from the banner.

The first step is to generate an API key. To do so, simply follow the following steps:

Go to report.ostorlab.co

Click the Menu button

Click Integrations/API to expand

Click API Keys

Create the API key

Click New API Key, give the key a name and choose its role, then click Create Key. You can also set an expiry date.

Copy the API key

Copy the key from the banner with Copy Key. The key is shown only once: store it in your GitLab CI/CD variables before leaving the page.

Creating a Gitlab-CI Pipeline:

Example to use for your .gitlab-ci.yml

stages:
  - build
  - test

build:
  stage: build
  script:
      - Pre steps to build
      - ./gradlew assembleDebug
  artifacts:
    paths:
    - app/build/outputs/

runScanOstorlab:
  stage: test
  image: ostorlab/gitlab-ci
  variables:
    OSTORLAB_FILE_PATH: app/build/outputs/apk/debug/app-debug.apk
    OSTORLAB_PLATFORM: android
    OSTORLAB_UI_PROMPT_NAMES: "shop;profile;cart;settings"
    OSTORLAB_UI_PROMPT_ACTIONS: "search for a product named 'laptop' and add it to cart;open the profile tab and update email;review cart and proceed to checkout;open settings and enable notifications"
    OSTORLAB_UI_PROMPT_IDS: "123;456"
  script:
    - run_ostorlab.sh

Required Environment variables

• OSTORLAB_API_KEY=API_KEY - Specifies your API key.
• OSTORLAB_PLATFORM=PLATFORM - Specifies the platform: android, ios or link (web).
• OSTORLAB_FILE_PATH=FILE_PATH - Specifies the path to the Android APK or iOS IPA. Required for mobile scans.
• OSTORLAB_URLS=URLS - A space-separated list of URLs to scan. Required when OSTORLAB_PLATFORM is link.

Optional Environment variables

Following are optional parameters that can be set from environment variables:

• OSTORLAB_SCAN_PROFILE - Specifies the scan profile: Fast Scan (default), Full Scan or Full Web Scan.
• OSTORLAB_TITLE=My Title - Specifies the scan title (default: Gitlab scan).
• OSTORLAB_RISK_THRESHOLD=medium - Specifies your risk rating threshold. When set, the job waits for the scan to finish and fails if the scan risk rating is strictly higher than the threshold (for example, with high the job fails only on a critical risk rating).
• OSTORLAB_MAX_WAIT_MINUTES=30 - Specifies the number of minutes to wait for the scan result (default: 30). Only applies when OSTORLAB_RISK_THRESHOLD is set; the job fails if the scan does not finish in time.
• OSTORLAB_SBOM_FILES - A space-separated list of paths to SBOM files.
• OSTORLAB_CREDENTIALS - A semicolon-separated list of test credentials in the format login,password,role,url (role and url are optional for mobile scans). For example: user1,pass1;user2,pass2.
• OSTORLAB_CUSTOM_CREDENTIALS - A semicolon-separated list of custom credentials in the format name,value. For example: api_token,12345;secret_key,67890.
• OSTORLAB_API_SCHEMA - Path to an API schema file to use for the scan (web scans only).
• OSTORLAB_FILTERED_URL_REGEXES - A space-separated list of regular expressions to exclude URLs from the scan (web scans only).
• OSTORLAB_PROXY - Specifies the proxy to use for the scan (web scans only).
• OSTORLAB_QPS - Specifies the queries-per-second limit for the scan (web scans only).
• OSTORLAB_UI_PROMPT_NAMES - A semicolon-separated list of UI prompt names. For example: shop;profile;cart;settings. Each name corresponds by position to an action in OSTORLAB_UI_PROMPT_ACTIONS.
• OSTORLAB_UI_PROMPT_ACTIONS - A semicolon-separated list of UI prompt actions. For example: search for a product named "laptop" and add it to cart;open the profile tab and update email;review cart and proceed to checkout;open settings and enable notifications. Each action corresponds by position to a name in OSTORLAB_UI_PROMPT_NAMES.

• OSTORLAB_UI_PROMPT_IDS - A semicolon-separated list of integer IDs of existing UI prompts to reuse. For example: 123;456. You can use this in addition to or instead of the name/action variables.

  Note: The number of names and actions must match, and each name/action pair is positional. You can use both name/action and ID variables together.

Adding Environment variables in Gitlab Pipeline

To add environment variables in your Gitlab Pipeline, navigate to settings then CI/CD, and then jump to Variables section to add environment variables for your pipeline as following:

After that, you can see that the variable is added to the list of variables.

Once the job is done, if you set OSTORLAB_RISK_THRESHOLD, the job fails if the scan risk rating is higher than the threshold, or if the scan does not finish within OSTORLAB_MAX_WAIT_MINUTES. Otherwise, the job succeeds with a line indicating the scan risk rating.

This guide covered the steps required to effectively & easily Integrate Ostorlab autonomous security testing for Android and iOS mobile apps to your gitlab build process.