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 Integrations/API 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 if the scan risk rating is higher than HIGH (that is, CRITICAL).

on: [push]
jobs:
  ostorlab_test:
    runs-on: ubuntu-latest
    name: Test ostorlab ci actions.
    steps:
      - uses: actions/checkout@v4
      - name: build ostorlab.apk
        run: mv InsecureBankv2.apk ostorlab.apk
      - name: Launch Ostorlab scan
        id: start_scan
        uses: Ostorlab/ostorlab_actions@v2.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 of the target to 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 fail the action if the scan risk rating is higher (here: CRITICAL)
          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 }}/"

3. Scanning Web Applications

In addition to mobile applications, Ostorlab also supports scanning web applications through GitHub workflows. To scan web applications, configure your workflow as shown in the example below:

on: [push]
jobs:
  ostorlab_web_scan:
    runs-on: ubuntu-latest
    name: Test ostorlab web scan.
    steps:
      - uses: actions/checkout@v4
      - name: Launch Ostorlab web scan
        id: start_scan
        uses: Ostorlab/ostorlab_actions@v2.1.0
        with:
          scan_profile: full_web_scan
          asset_type: link --url
          target: https://target1.ostorlab.co --url https://target2.ostorlab.co --url https://target3.ostorlab.co
          scan_title: web_scan_ci
          ostorlab_api_key: ${{ secrets.ostorlab_api_key }}
          break_on_risk_rating: HIGH
          max_wait_minutes: 60
      - 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 }}/"

For web application scanning:

• Use scan_profile: full_web_scan
• Set asset_type: link --url
• List your target URLs with --url flag for each additional URL

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, full_scan for full static, dynamic and backend coverage, or full_web_scan for web application scanning.

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

target, a required option. It's a target file to scan or URL for web applications.

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 Integrations/API then API Keys.

break_on_risk_rating, an optional option. When set, the action waits for the scan to finish and fails the pipeline if the scan risk rating is strictly higher than the provided value (for example, HIGH fails only on CRITICAL). If it is not set, the action does not wait for the scan results.

max_wait_minutes, an optional option. It's the maximum time in minutes to wait for the scan results (default: 20). It only applies when break_on_risk_rating is set, and the pipeline fails if the scan does not finish in time.

extra, an optional option. It's 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 }}.

4. 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. It integrates security into the development workflow with the main goal of pinpointing exactly what piece of code introduced the vulnerability, provide actionable insights and code suggestion that you can automatically commit. This document provides instructions on how to set up and use the App.

1. Add the GitHub App:

   1. Navigate to the Ostorlab Security Scanner App.
      
   2. Click Add.
      
   3. Choose the account where you’d like to install the app.
      
   4. Click Install for free.
      

   5. Provide the necessary permissions:

      • Read & Write access to pull requests.
      • Metadata access for the repository.

      

   6. Click Install to finalize the setup.
      

2. How to Use:

   1. The next step is to update your workflow to add an Ostorlab step to trigger the scan as described in steps 1 and 2.
      
   2. 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, pinpointing exactly where the vulnerability was introduced & provide code snippets of the fix.
      

5. From scan to verified fix

To keep risky changes out of a release, run the scan in five stages:

Stage	What runs
1. Scan every pull request	The action runs on each pull request: a Fast Scan for a mobile build, or a Full Web Scan for a web application.
2. Gate on risk	The build fails when the scan risk rating is strictly higher than break_on_risk_rating.
3. Send tickets to Jira or Linear	Findings become Ostorlab tickets, synced to Jira or Linear.
4. Verify the fix	A later scan marks a fixed ticket as FIXED VERIFIED or re-opens it. A Single Vulnerability Assessment re-tests one finding.
5. Deep assessment before release	A Deep Agentic Scan runs before the release, not on every pull request.

Scan every pull request and gate on risk

Run the workflow on pull requests: set on: pull_request instead of on: [push]. break_on_risk_rating fails the build when the scan risk rating is strictly higher than the value you set, and max_wait_minutes bounds the wait (default 20 minutes). To choose a threshold, see Risk Rating for what each rating means.

Send tickets to Jira or Linear

Ostorlab automatically creates a ticket for each newly detected security issue, and aggregates later occurrences of the same vulnerability into the same ticket. To send these tickets to your team's tracker, turn on automatic issue creation in the Jira or Linear integration. Both require an enterprise subscription. In either integration, choose the ticket risk ratings to sync: only tickets with those ratings reach Jira or Linear.

Verify the fix

When a developer ships a fix, mark the ticket as fixed. A later scan that runs the same tests then checks the fix: if the vulnerability is absent, the ticket is automatically marked FIXED VERIFIED; otherwise, the same ticket is re-opened. Tickets marked as an exception or as a false positive are kept as they are. See Ticket Lifecycle.

To re-test one finding without a complete rescan, run a Single Vulnerability Assessment directly from the reported ticket. It typically takes 2 to 10 minutes.

Continuous checks and deep assessments

Continuous checks run on every pull request or on a schedule and finish in minutes. Deep assessments run before a release, take 1 to 3 hours, and validate attack chains and business logic with a proof of concept. See Scan Types Comparison.

Scan	When to run it	Typical duration	What it covers	AI provider
Fast Scan (continuous check)	Every pull request, in CI	1 to 5 minutes	Static analysis	None
Full Scan (continuous check)	On a schedule	15 to 45 minutes	Static, dynamic and backend testing	None
Deep Agentic Scan (deep assessment)	Before a release	1 to 3 hours	AI-agent pentest: attack chains, business logic, findings validated with a proof of concept	Cyber Models or bring-your-own-key (BYOK)

• Scheduled Full Scans: create a monitoring rule with a CRON schedule, or a CONTINUOUS rule that scans when the asset changes, and select Full Scan. See Creating a Monitoring Rule.
• Pre-release Deep Agentic Scan: start it from Scanning > New Scan in the platform. See Mobile Deep Agentic Scan or Web Deep Agentic Scan. It needs an AI provider: Cyber Models or your own key (BYOK). Its findings are produced by AI agents, with no human validation.

This guide outlined how to add the Ostorlab GitHub Action to a workflow, scan web applications, use the Ostorlab Security Scanner GitHub App, and run a release pipeline from scan to verified fix.