Integrations & API

GoCD

Easily integrate Ostorlab automated security scanning for Android and iOS mobile applications into your GoCd build process.

Usage:

Generate an Ostorlab API key

1. Go to the API keys menu
2. Click the new button to generate a new key
3. Copy the API key (You can add a name and an expiry date to your key)
4. Click the save button to save your key

Add Ostorlab as a Command Line Stage on GoCd

1. Head to your GoCd Dashboard and select your pipeline.

   

2. Click Edit on your pipeline.

   

3. Select Stages.

   

4. Add new stage and fill the form.

   • For the initial Job type Select Custom Command.
   • And give it the following arguments:
     • Command: bash
     • Arguments: |

       -c
       pip install ostorlab
       

   • click save.

   

5. Navigate to JOBS tab and select your newly added job.

   

6. Add one more task to run the job.

   • Click add Task of type Custom Command.
   • And give it the following arguments:
     • Command: bash
     • Arguments: |

       -c
       ostorlab --api-key=$OSTORLAB_API_KEY ci-scan run --title=$Scan_Title --scan-profile=$SCAN_PROFILE android-apk /path/to/app.apk
       

       Check Additional options below for the full list of options.

   

7. Add environment variables

   • Navigate to the ENVIRONMENT VARIABLES tab.
   • Add the OSTORLAB_API_KEY as a Secure Variable.
   • Add the other variables (Scan_Title, SCAN_PROFILE, ...) as Plain Text Variables.

   

Additional options

The following is the full list of options for the ostorlab ci-scan run command:

ostorlab --api-key <API_KEY> ci-scan run [options] <asset-type> <target>

• --api-key: Ostorlab generated API key.

• --title: Scan title

• --scan-profile: Type of the scan. Possible options are:

  1. fast_scan (alias fast): Only runs the static analysis;
  2. full_scan (alias full): Runs static, dynamic, and backend analysis;
  3. full_web_scan (alias full_web): Runs a web application scan.

• --break-on-risk-rating: Wait for the scan to finish and fail the step if the scan risk rating is higher than this value (for example, high fails only on critical). If it is not set, the command does not wait for the scan results.

• --max-wait-minutes: Maximum time in minutes to wait for the scan results when --break-on-risk-rating is set (default: 30). The step fails if the scan does not finish in time.

• Test credentials: Automatic authentication in the dynamic analysis full scan:

  • --test-credentials-login: Username to be used in log-in fields;
  • --test-credentials-password: Password to be used in password fields;
  • --test-credentials-role: Optional role field;
  • Custom/Generic test credentials:
    • --test-credentials-name: Custom name of the field;
    • --test-credentials-value: Custom value of the field

• 2FA Credentials:

  • SMS 2FA:
    • --sms-2fa-sender: Learn more about SMS 2FA
  • Email 2FA:
    • --email-2fa-sender-email-address, --email-2fa-email-address, --email-2fa-password: Learn more about Email 2FA
  • TOTP 2FA:
    • --totp-2fa-seed: Learn more about TOTP 2FA

• --sbom: Path to the sbom file.

• UI Prompts (Optional): Ostorlab supports UI prompts to guide the scanner through your app's user interface. You can use:

  • --ui-prompt-name and --ui-prompt-action: Define a UI step by specifying the name and the action. You can add multiple pairs for a sequence of steps. For example:

    --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."
    

  • --ui-prompt-id: Reference existing UI prompt flows by their IDs. You can add multiple IDs. For example:

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

• asset-type: Type of the asset to scan. Possible values:

  • android-aab: Scan an android .AAB package file;
  • android-apk: Scan an android .APK package file;
  • ios-ipa: Scan an iOS .IPA package file;

• target: Path to the target application.