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

Once you have generated your API, add it to GitHub Secrets. Make sure the name matches the secrets. in the YAML file. You can follow the steps in Github documentation at the following link for more detailed instructions.

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

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.
   
3. Click Add.
   
4. Choose the account where you’d like to install the app.
   
5. Click Install for free.
   
6. Provide the necessary permissions:
   • Read & Write access to pull requests.
   • Metadata access for the repository.
     

7. Click Install to finalize the 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.
10. Create a pull request incorporating the updated workflow with Ostorlab. After the scan completes, the Ostorlab Security Scanner will automatically comment on your pull request, highlighting any vulnerabilities it detects.
    

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.