Skip to content

Ostorlab Github Action

1. Generate a new API key

To use Ostorlab Github Action, 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 Library to expand

Click API Keys

Click New to generate a new API key

Copy the API key. You can also add a name and an expiry date to your key.

Don't forget to click the save button to save your key.

2. Add Ostorlab Github Action to your workflow

The next step is to update your workflow to add an Ostorlab step to trigger the scan. Following is a sample performing a rapid scan on an Android APK and failing the pipeline on vulnerabilities with HIGH severity.

on: [push]
jobs:
  ostorlab_test:
    runs-on: ubuntu-latest
    name: Test ostorlab ci actions.
    steps:
      - uses: actions/checkout@v2
      - name: build ostorlab.apk
        run: mv InsecureBankv2.apk ostorlab.apk
      - name: Launch Ostorlab scan
        id: start_scan
        uses: Ostorlab/ostorlab_actions@v1.1.0
        with:
          scan_profile: fast_scan # Specify which scan profile to use for the scan (check scan section).
          asset_type: android-apk # type of asset to scan.
          target: ostorlab.apk # path for target tto scan.
          scan_title: title_scan_ci # type a title for your scan.
          ostorlab_api_key: ${{ secrets.ostorlab_api_key }} # your secret api key.
          break_on_risk_rating: HIGH # Wait for the scan results and force the action to fail if the scan risk is higher
          max_wait_minutes: 30
      - name: Get scan id
        run: echo "Scan Created with id ${{ steps.start_scan.outputs.scan_id }} you can access the full report at https://report.ostorlab.co/scan/${{ steps.start_scan.outputs.scan_id }}/"

Ostorlab Github actions takes the following inputs:

scan_profile, which is a required option that specifies the scan profile, it can be fast scan for fast static analysis only or full_scan for full static, dynamic and backend coverage.

asset_type, a required option which specifies the target asset type, for example, Android APK or iOS IPA.

target, a required option. It's a target file to scan.

scan_title, an optional option. It's a title to identify your scan.

ostorlab_api_key, a required option. You can get it from ostorlab dashboard, in library then API keys section.

break_on_risk_rating, an optional option. It's a risk rating to break the pipeline if the scan result is equal or higher than the provided value.

max_wait_minutes, an optional option. its a max wait time in minutes, pipeline will not fail if the scan times out. if you want to run the scan without waiting, remove this option.

extra, an optional option. its an extra argument to pass to the Ostorlab CLI. Common use case is passing the scan test credentials.

You can supply your SBOM or Lock files to enhance the scan analysis, to do so use the extra input to pass SBOM, for example to add package lock dot json file use the following example:

Here you can see the list of the supported files:

Ostorlab supports performing authenticated testing with either simple login password or custom inputs identified with name or label and passing value. To pass test credentials, since the Github YAML Action do not support passing complex objects, you can use the extra input to pass test credentials. For instance to add login & password and a custom credentials with custom names and values, add the following input:

As for the action output, it is possible to access the scan_id using the following syntax ${{ steps.STEP_ID.outputs.scan_id }}.

This guide covered the steps required to effectively use Ostorlab Github Action. From creating a new API key to navigating through different Action inputs and output.