Ostorlab GitHub Action

1. 新しいAPIキーを生成する

Ostorlab Github Actionを使用するには、まずAPIキーを生成する必要があります。これを行うには、次の手順に従います。

report.ostorlab.co に移動します。

`Menu`ボタンをクリックします。

Menuボタン

`Integrations/API`をクリックして展開します。

Integrations/API展開

`API Keys`をクリックします。

API Keys

`New API Key` をクリックし、キーの名前とロールを選んで `Create Key` をクリックします。有効期限も設定できます。

新しいAPIキー

バナーの `Copy Key` でキーをコピーします。キーは一度しか表示されません。

APIキーをコピー

2. ワークフローにOstorlab Github Actionを追加する

APIを生成したら、それをGitHub Secretsに追加します。YAMLファイルの`secrets.`に一致する名前であることを確認してください。詳細な手順については、次のリンクのGithubドキュメントの手順に従うことができます。

GitHub Secrets

次のステップは、スキャンをトリガーするOstorlabステップを追加するためにワークフローを更新することです。以下は、Android APKで高速スキャンを実行し、スキャンのリスク評価がHIGHより高い（つまり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 # スキャンに使用するスキャンプロファイルを指定します（スキャンセクションを確認してください）。
          asset_type: android-apk # スキャンするアセットのタイプ。
          target: ostorlab.apk # スキャンするターゲットへのパス。
          scan_title: title_scan_ci # スキャンのタイトルを入力します。
          ostorlab_api_key: ${{ secrets.ostorlab_api_key }} # シークレットAPIキー。
          break_on_risk_rating: HIGH # スキャン結果を待ち、スキャンのリスクがこの値より高い場合（ここでは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. Webアプリケーションのスキャン

モバイルアプリケーションに加えて、OstorlabはGitHubワークフローを介したWebアプリケーションのスキャンもサポートしています。Webアプリケーションをスキャンするには、以下の例に示すようにワークフローを構成します。

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 }}/"

Webアプリケーションスキャンの場合：

scan_profile: full_web_scan を使用します。
asset_type: link --url を設定します。
追加のURLごとに --url フラグを使用してターゲットURLをリストします。

Ostorlab Githubアクションは、次の入力を受け取ります。

scan_profile：スキャンプロファイルを指定する必須オプションです。高速静的解析のみの場合はfast_scan、完全な静的、動的、バックエンドカバレッジの場合はfull_scan、またはWebアプリケーションスキャンの場合はfull_web_scanを指定できます。

スキャンプロファイル

asset_type：ターゲットのアセットタイプを指定する必須オプションです。たとえば、Android APK、iOS IPA、またはWebアプリケーションのリンクなどです。

アセットタイプ

target：必須のオプションです。スキャンするターゲットファイル、またはWebアプリケーションのURLです。

ターゲットファイル

scan_title：オプションです。スキャンを識別するためのタイトルです。

スキャンタイトル

ostorlab_api_key：必須のオプションです。Ostorlabダッシュボードの「Integrations/API」にある「API Keys」から取得できます。

Ostorlab APIキー

break_on_risk_rating：オプションです。設定すると、アクションはスキャンの完了を待ち、スキャンのリスク評価が指定された値より厳密に高い場合にパイプラインを失敗させます。HIGH を指定すると CRITICAL のスキャンでのみ失敗します。このオプションがない場合、アクションは結果を待ちません。

リスク評価での中断

max_wait_minutes：オプションです。break_on_risk_rating を設定した場合の最大待機時間（分単位、デフォルト：20）です。待機時間内にスキャンが完了しない場合、ステップはタイムアウトエラーで失敗します。

最大待機時間（分）

extra：オプションです。Ostorlab CLIに渡す追加の引数です。一般的なユースケースは、スキャンのテスト認証情報を渡すことです。

追加の引数

SBOMまたはLockファイルを提供してスキャン解析を強化できます。これを行うには、extra入力を使用してSBOMを渡します。たとえば、package lock dot jsonファイルを追加するには、次の例を使用します。

SBOMの例

ここにサポートされているファイルのリストが表示されます。

サポートされているファイル

Ostorlabは、シンプルなログインパスワード、または名前やラベルで識別されて値を渡すカスタム入力による認証済みテストの実行をサポートしています。GithubのYAML Actionは複雑なオブジェクトの受け渡しをサポートしていないため、テスト認証情報を渡すには、extra入力を使用できます。たとえば、ログインとパスワード、およびカスタム名と値を持つカスタム認証情報を追加するには、次の入力を追加します。

テスト認証情報

アクションの出力については、次の構文を使用して scan_id にアクセスできます：${{ steps.STEP_ID.outputs.scan_id }}。

4. Ostorlab Security Scanner GitHub Appを使用して、PR内で直接アクション可能なインサイトを提供する

Ostorlab Security Scanner GitHub Appは、ステップ1と2で説明したOstorlab Github Actionsワークフローと組み合わせて使用する必要があります。

Ostorlab Security Scanner GitHub Appは、Pull Requestsで直接アクション可能なインサイトを提供することで、開発者がコードのセキュリティを向上させるのを支援するように設計されています。これは、どのコードが脆弱性を導入したかを正確に特定し、自動的にコミットできるアクション可能なインサイトとコード提案を提供することを主な目的として、セキュリティを開発ワークフローに統合します。このドキュメントでは、Appのセットアップ方法と使用方法について説明します。

GitHub Appの追加:
1. Ostorlab Security Scanner App に移動します。
2. Addをクリックします。
3. アプリをインストールするアカウントを選択します。
4. Install for freeをクリックします。
5. 必要な権限を提供します。
  - Pull requestsへの Read & Write アクセス。
  - リポジトリの Metadata アクセス。
6. Installをクリックしてセットアップを完了します。
使用方法:
1. 次のステップは、ステップ1と2で説明したようにスキャンをトリガーするOstorlabステップを追加するためにワークフローを更新することです。
2. Ostorlabで更新されたワークフローを組み込んだプルリクエストを作成します。
  
  スキャンが完了すると、Ostorlab Security Scannerは自動的にプルリクエストにコメントし、脆弱性が導入された場所を正確に特定し、修正のコードスニペットを提供します。

5. スキャンから修正の検証まで

リスクのある変更をリリースに含めないために、スキャンを次の5つのステージで実行します。

ステージ	実行内容
1. すべてのプルリクエストをスキャンする	アクションはプルリクエストごとに実行されます。モバイルビルドにはFast Scan、WebアプリケーションにはFull Web Scanが実行されます。
2. リスクでゲートする	スキャンのリスク評価が `break_on_risk_rating` より厳密に高い場合、ビルドが失敗します。
3. チケットをJiraまたはLinearに送る	検出結果はOstorlabのチケットになり、JiraまたはLinearと同期されます。
4. 修正を検証する	後続のスキャンが、修正済みのチケットを `FIXED VERIFIED` としてマークするか、再オープンします。Single Vulnerability Assessmentは1つの検出結果を再テストします。
5. リリース前の詳細評価	Deep Agentic Scanは、すべてのプルリクエストではなく、リリース前に実行されます。

すべてのプルリクエストをスキャンし、リスクでゲートする

プルリクエストでワークフローを実行します。on: [push] の代わりに on: pull_request を設定します。break_on_risk_rating は、スキャンのリスク評価が設定した値より厳密に高い場合にビルドを失敗させ、max_wait_minutes は待機時間の上限を設定します（デフォルトは20分）。しきい値を選択するには、各評価の意味についてリスク評価を参照してください。

チケットをJiraまたはLinearに送る

Ostorlabは、新たに検出されたセキュリティ上の問題ごとにチケットを自動的に作成し、同じ脆弱性の以降の発生を同じチケットに集約します。これらのチケットをチームのトラッカーに送信するには、JiraまたはLinearの統合で課題の自動作成を有効にします。どちらもエンタープライズサブスクリプションが必要です。いずれの統合でも、同期するチケットのリスク評価を選択します。選択した評価のチケットのみがJiraまたはLinearに送られます。

修正を検証する

開発者が修正をリリースしたら、チケットを修正済みとしてマークします。その後、同じテストを実行する後続のスキャンで修正が確認されます。脆弱性が検出されなければ、チケットは自動的に FIXED VERIFIED としてマークされ、検出された場合は同じチケットが再オープンされます。例外または誤検知としてマークされたチケットはそのまま維持されます。チケットのライフサイクルを参照してください。

完全な再スキャンを実行せずに1つの検出結果を再テストするには、報告されたチケットから直接 Single Vulnerability Assessment を実行します。通常2〜10分かかります。

継続的チェックと詳細評価

継続的チェックは、すべてのプルリクエストで、またはスケジュールに従って実行され、数分で完了します。詳細評価はリリース前に実行され、1〜3時間かかり、攻撃チェーンとビジネスロジックを概念実証で検証します。スキャンタイプの比較を参照してください。

スキャン	実行タイミング	一般的な所要時間	対象範囲	AIプロバイダー
Fast Scan（継続的チェック）	すべてのプルリクエストで、CI内	1〜5分	静的解析	なし
Full Scan（継続的チェック）	スケジュールに従って	15〜45分	静的、動的、バックエンドのテスト	なし
Deep Agentic Scan（詳細評価）	リリース前	1〜3時間	AIエージェントによるペンテスト：攻撃チェーン、ビジネスロジック、概念実証で検証された検出結果	Cyber Modelsまたは独自のキー（BYOK）

スケジュールされたFull Scan： CRONスケジュールを持つモニタリングルール、またはアセットの変更時にスキャンするCONTINUOUSルールを作成し、Full Scanを選択します。モニタリングルールの作成を参照してください。
リリース前のDeep Agentic Scan： プラットフォームの Scanning > New Scan から開始します。Mobile Deep Agentic ScanまたはWeb Deep Agentic Scanを参照してください。AIプロバイダーとして、Cyber Modelsまたは独自のキー（BYOK）が必要です。検出結果はAIエージェントによって生成され、人による検証は行われません。

このガイドでは、Ostorlab GitHub Actionをワークフローに追加する方法、Webアプリケーションをスキャンする方法、Ostorlab Security Scanner GitHub Appを使用する方法、およびスキャンから修正の検証までのリリースパイプラインを実行する方法を説明しました。