Skip to content

Ostorlab Integration with Bitbucket

Overview

In this guide, we will explore how to easily integrate security and privacy testing into your mobile application pipeline builds using the Bitbucket Pipeline.

Video Demonstration

Watch this brief video for a visual walkthrough of the integration process.

Generate an API Key:

The first step is to generate a new API key. In your organisation dashboard, click the menu button.

Click menu button

Next click "Integrations/API" to expand.

Click 'Integrations/API'

And choose API keys.

Click 'API Keys'

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

Click 'New'

Copy the key from the banner with Copy Key: it is shown only once.

Copy API key

Add the API Key to Bitbucket Variables:

Once you have generated your API key, add it to your Bitbucket variables.

Add variable

Update Your Pipeline:

Now, you need to update your Bitbucket pipeline to include an Ostorlab step for triggering the security scan. This is a sample configuration that performs a fast scan on an Android APK and fails the pipeline if the scan risk rating is higher than HIGH (that is, CRITICAL).

Add step

- step:
            name: Ostorlab Security Scan
            caches:
              - pip
            script:
              - pip install ostorlab[cli]
              - export OSTORLAB_API_KEY=$SECRET_OSTORLAB_API_KEY
              - export SCAN_TITLE="Test Bitbucket CI workflow"
              - export SCAN_PROFILE='fast_scan'
              - export BREAK_ON_RISK_RATING="HIGH"
              - export MAX_WAIT_MINUTES=15
              - export TARGET="oxo_insecure.apk"
              - export ASSET_TYPE="android-apk"
              - export EXTRA="--test-credentials-login test_login --test-credentials-password test_pass"
              - ostorlab --api-key="$OSTORLAB_API_KEY" ci-scan run  --title="$SCAN_TITLE" --scan-profile="$SCAN_PROFILE"  --break-on-risk-rating="$BREAK_ON_RISK_RATING" --max-wait-minutes="$MAX_WAIT_MINUTES" $EXTRA $ASSET_TYPE "$TARGET"

Let's explore each line in this configuration:

First, we will need to install the ostorlab package and its command-line interface components using pip.

Install ostorlab package

Next, create a variable to store the API key. Ensure that the variable's name matches the one added to your repository as a secret or environment variable.

Create API key variable

Add a title variable for your scan.

Add title variable

Add another variable for the scan profile. Choose between fast_scan for rapid static analysis or full_scan for a comprehensive analysis, including static, dynamic, and backend.

Add scan profile variable

Next, add a BREAK_ON_RISK_RATING variable. When it is set, the step waits for the scan to finish and fails if the scan risk rating is higher than this value (for example, HIGH fails only on CRITICAL).

Then, add a variable that defines the maximum time the build should wait (in minutes) for the security analysis to finish. It only applies when BREAK_ON_RISK_RATING is set, and the step fails if the scan does not finish in time (default: 30 minutes).

Add max wait time variable

Add a target variable to specify the path to your application.

Add target variable

Define the asset type as either Android or iOS. In my case, I am choosing Android as I intend to scan an Android app.

Define asset type

The extra parameter enables you to provide your Lock files for enhanced scan analysis.

Provide lock files

The following list outlines the supported SBOM/Lock files:

  • SPDX
  • CycloneDX
  • gradle.lockfile
  • pubspec.lock
  • buildscript-gradle.lockfile
  • pnpm-lock.yaml
  • package-lock.json
  • packages.lock.json
  • pom.xml
  • Gemfile.lock
  • yarn.lock
  • Cargo.lock
  • composer.lock
  • conan.lock
  • mix.lock
  • go.mod
  • requirements.txt
  • Pipfile.lock
  • poetry.lock

Additionally, it allows you to supply either simple credentials or custom credentials to enable authenticated testing.

For 2FA support, you can add the following credentials:

Provide credentials

You can also provide UI prompts to guide the scanner through your app's UI. UI prompts are a powerful feature that allows you to use natural language to tell the scanner how to navigate the app. For example, you can specify prompts like "click the login button" or "enter the username and password".

--ui-prompt-name accept-terms --ui-prompt-action "Scroll down and tap the 'Accept Terms' checkbox."
--ui-prompt-name submit --ui-prompt-action "Tap the 'Submit' button to complete the login process."

You can add multiple --ui-prompt-name and --ui-prompt-action flags for different steps in your app's flow.

Additionally, you can use the --ui-prompt-id flag to reference existing UI prompt flows by their IDs. This allows you to reuse previously defined UI prompt flows. You can add multiple --ui-prompt-id flags as needed. For example:

--ui-prompt-id 123 --ui-prompt-id 456

Finally, execute the Ostorlab command as follows:

Execute Ostorlab command

After updating the pipeline, check the progress here.

Check progress

Check the pipeline logs for details, retrieve the scan ID, and monitor your scan within your organization account on Ostorlab.

Monitor scan

For example, this is the report for the current scan.

Scan report

Conclusion

This guide covers the steps required to effectively and easily integrate Ostorlab autonomous security testing for Android and iOS mobile apps into your Bitbucket Pipeline.