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

Menu Button

Click Library to expand

Library Expanded

Click API Keys

API Keys

Click New to generate a new API key

New API Key

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

Copy API Key

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

Save API Key

2. Add Ostorlab Github Action to your workflow

GitHub Secrets

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.

Scan Profile

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

Asset Type

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

Target File

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

Scan Title

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

Ostorlab API Key

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.

Break on Risk Rating

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.

Max Wait Minutes

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

Extra Argument

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:

SBOM Example

Here you can see the list of the supported files:

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:

Test Credentials

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

3. Use Ostorlab Security Scanner GitHub App to Provide actionable insights directly in your PR

The Ostorlab Security Scanner GitHub App should be used in conjunction with an Ostorlab Github Actions workflow as explained in steps 1 and 2.

The Ostorlab Security Scanner GitHub App is designed to help developers improve their code security by providing actionable insights directly in pull requests. This document provides instructions on how to set up and use the app.

  1. Add the GitHub App:
  2. Navigate to the Ostorlab Security Scanner App.
    Ostorlab Security Scanner App
  3. Click Add.
    Add App
  4. Choose the account where you’d like to install the app.
    Choose Account
  5. Click Install for free.
    Install for Free
  6. Provide the necessary permissions:
    • Read & Write access to pull requests.
    • Metadata access for the repository.
      Permissions
  7. Click Install to finalize the setup.
    Finalize Setup

  8. How to Use:

  9. The next step is to update your workflow to add an Ostorlab step to trigger the scan as described in steps 1 and 2. Update Workflow
  10. Create a pull request incorporating the updated workflow with Ostorlab. Create Pull Request After the scan completes, the Ostorlab Security Scanner will automatically comment on your pull request, highlighting any vulnerabilities it detects.
    Scan Results

This guide outlined the necessary steps to successfully utilize the Ostorlab GitHub Action and the Ostorlab Security Scanner App, including generating a new API key, exploring various action inputs, installing the app, and viewing the results.