GitHub Action との統合¶

このガイドでは、プッシュのたびに Mayhem が自動的にコードまたは API をテストできるよう GitHub Actions Workflow をセットアップする方法を説明します。

前提条件

GitHub Action ワークフローで Mayhem を実行するには、以下が必要です

注意: コードまたは API をテストするのと同じトークンを使用できます。

Mayhem API token を作成します。
作成したトークンを MAYHEM_TOKEN という名前の変数を使用して GitHub シークレットに追加します。

コードをテストするためのワークフローの設定¶

Mayhem GitHub Action は、コードに変更が加えられるたびに、CI ワークフローを開始し (この後で、GHCR および Docker での使用例を説明します)、ターゲットアプリケーションの Docker イメージをビルドしてプッシュし、自動的にイメージをテストし、ワークフローの最後で最終的なセキュリティテストまたは SARIF レポートを生成します。

はじめに¶

GitHub リポジトリに GitHub Action を統合するのは簡単です。イメージレジストリとして GitHub Container Registry (GHCR) または Docker Hub を使用している場合、下の該当する手順に従います。

GHCR

GHCR を使用する mCode Action

GitHub リポジトリの GitHub シークレットに以下を追加します。
1. MAYHEM_TOKEN: Mayhem トークンです。
2. MAYHEM_URL: Mayhem インスタンスの URL です (例： https://app.mayhem.security)。
3. GitHub Container Registry から Docker イメージを取り込む権限を Mayhem に付与するために。リポジトリの package visibility 設定に Public が設定されていることを確認します。
  
  GitHub リポジトリの右側のペインでパッケージをクリックし、[Package Settings] に移動します。[Package Visibility] にスクロールダウンし、パッケージを Public に設定します。
コンテナー化されるアプリケーションのリポジトリのルートに Dockerfile を作成します。
リポジトリのルートに Mayhemfile を作成し、ｍCode GitHub Action が呼び出す Mayhem ランを構成します。ランはコンテナー化されたターゲットアプリケーションに対して実行されます。
.github/workflows/mayhem.yml に mayhem.yml ワークフローを作成します。ワークフローは Docker イメージをビルドしてプッシュし、mCode GitHub Action を使用して CI パイプラインでコンテナー化されたアプリケーションをファジングします。

Docker Hub

Docker Hub を使用する mCode Action

GitHub リポジトリの GitHub シークレットに以下を追加します。
1. DOCKER_USERNAME: Docker Hub ユーザー名です (大文字/小文字が区別されます)。
2. DOCKER_PASSWORD: Docker Hub パスワードです。
  
  2FA が有効な場合、Docker Hub アカウントのアクセストークンをセットアップする必要があります。GitHub シークレットに DOCKER_PASSWORD としてアクセストークンを指定します。
3. MAYHEM_TOKEN: Mayhem トークンです。
4. MAYHEM_URL: Mayhem インスタンスの URL です (例： https://app.mayhem.security)。
GitHub リポジトリに関連する Docker Hub リポジトリを作成します。

パイプライン実行時にビルドされ Docker Hub にプッシュされる Docker イメージには GitHub リポジトリに従ってタグが付けられるため、たとえば GitHub リポジトリ mayhemuser/lighttpd-demo には関連する Docker Hub リポジトリ mayhemuser/lighttpd-demo が必要です。
コンテナー化されるアプリケーションのリポジトリのルートに Dockerfile を作成します。
リポジトリのルートに Mayhemfile を作成し、ｍCode GitHub Action が呼び出す Mayhem ランを構成します。ランはコンテナー化されたターゲットアプリケーションに対して実行されます。
.github/workflows/mayhem.yml に mayhem.yml ワークフローを作成します。ワークフローは Docker イメージをビルドしてプッシュし、mCode GitHub Action を使用して CI パイプラインでコンテナー化されたアプリケーションをファジングします。

mCode Action の構成¶

mCode Action を使用するには、GitHub リポジトリの完全修飾パス .github/workflows/mayhem.yml に mayhem.yml ファイルを追加する必要があります。これは、mCode GitHub アクションワークフローの構成ファイルです。

mayhem.yml は次のようになります。

Note

次の mayhem.yml は完全修飾されており、必須入力パラメーターと任意入力パラメーターの両方を示しています (必須フィールドはハイライト表示されています)。mayhem.yml で利用可能な入力パラメーターについての詳細は mCode Action Usage を参照してください。

GHCR

name: Mayhem
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
  BRANCH_NAME: ${{ github.head_ref || github.ref_name }}

jobs:
  build:
    name: 'build'
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest]
        shared: [false]
        build_type: [Release]
        include:
          - os: ubuntu-latest
            triplet: x64-linux

    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Log in to the Container registry
        uses: docker/login-action@v2.1.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v4.1.1
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Set lowercase image name
        run: |
          echo "IMAGE_NAME=${GITHUB_REPOSITORY,,}" >> ${GITHUB_ENV}

      - name: Build and push Docker image
        uses: docker/build-push-action@v3.2.0
        with:
          context: .
          push: true
          file: Dockerfile
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.BRANCH_NAME }}
          labels: ${{ steps.meta.outputs.labels }}

    outputs:
      image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.BRANCH_NAME }}

  mayhem:
    needs: build
    name: 'fuzz'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        mayhemfile:
          - mayhem/Mayhemfile.lighttpd
          - mayhem/Mayhemfile.mayhemit
          # Specify one or many Mayhemfiles here

    steps:
      - uses: actions/checkout@v3

      - name: Start analysis for ${{ matrix.mayhemfile }}
        uses: ForAllSecure/mcode-action@v1
        with:
          mayhem-url: ${{ secrets.MAYHEM_URL }}
          mayhem-token: ${{ secrets.MAYHEM_TOKEN }}
          args: --image ${{ needs.build.outputs.image }} --file ${{ matrix.mayhemfile }} --duration 300
          sarif-output: sarif

      - name: Upload SARIF file(s)
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: sarif

Docker Hub

name: Mayhem
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  REGISTRY: docker.io
  IMAGE_NAME: ${{ github.repository }}
  BRANCH_NAME: ${{ github.head_ref || github.ref_name }}

jobs:
  build:
    name: 'build'
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest]
        shared: [false]
        build_type: [Release]
        include:
          - os: ubuntu-latest
            triplet: x64-linux
        mayhemfile:
          - mayhem/Mayhemfile
          # Specify one or many Mayhemfiles here

    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker BuildX
        uses: docker/setup-buildx-action@v2.2.1

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v4.1.1
        with:
          images: ${{ github.repository }}

      - name: Log in to Docker Hub
        uses: docker/login-action@v2.1.0
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v3.2.0
        with:
          context: .
          push: true
          file: Dockerfile
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.BRANCH_NAME }}
          labels: ${{ steps.meta.outputs.labels }}

      - name: Start analysis for ${{ matrix.mayhemfile }}
        uses: ForAllSecure/mcode-action@v1
        with:
          mayhem-url: ${{ secrets.MAYHEM_URL }}
          mayhem-token: ${{ secrets.MAYHEM_TOKEN }}
          args: --image ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.BRANCH_NAME }} --file ${{ matrix.mayhemfile }} --duration 300
          sarif-output: sarif

      - name: Upload SARIF file(s)
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: sarif

mayhem.yml を見ると、パイプラインランナーノードで次の GitHub Action プラグインが順に実行されていることがわかります。

GHCR

Info

actions/checkout: GitHub リポジトリからコードがチェックアウトされます。
docker/login-action: GitHub シークレット認証情報を使用して GitHub Container Registry にログインします。
docker/metadata-action: Git リファレンスおよび GitHub イベントのメタデータを抽出して Docker イメージにタグおよびラベル付けするのに使用されます。
docker/build-push-action: コードがビルドされ Docker イメージとして GitHub Container Registry にプッシュされます。
ForAllSecure/mcode-action: Mayhem が GitHub Container Registry イメージを取り込み、コンテナー化されたターゲットアプリケーションに対してファジングを開始します。
github/codeql-action/upload-sarif: ファズテスト結果から SARIF レポートが生成され、GitHub にアップロードされます。

Docker Hub

Info

actions/checkout: GitHub リポジトリからコードがチェックアウトされます。
docker/setup-buildx-action: Docker がインストールされます。
docker/metadata-action: これからアップロードされる Docker Hub イメージのためのタグがセットアップされます。
Log in to Docker Hub: GitHub シークレット認証情報を使用してDocker Hub にログインします。
Build and Push: コードがビルドされ Docker イメージとして Docker Hub にプッシュされます。
Mayhem Scan: Mayhem が Docker Hub イメージを取り込み、コンテナー化されたターゲットアプリケーションに対してファジングを開始します。
Upload SARIF file(s): ファズテスト結果から SARIF レポートが生成され、GitHub にアップロードされます。

🤔 まだ疑問がある場合、mcode-actions-examples リポジトリを参照して、テンプレートとして利用可能な動作する mCode GitHub Action との統合サンプルを確認してください。必要に応じて自由にリポジトリをフォークしてください。

SARIF レポートの解析¶

アップロードされた Docker イメージを使用してコンテナー化されたターゲットアプリケーションをファジングした後、Mayhem が発見した課題は SARIF レポートとして生成され、プルリクエスト自体またはリポジトリの [Security] タブで結果を参照できます。

たとえば、プルリクエストの必須 Mayhem コードスキャニングの [Details] をクリックすると、Mayhem が発見した問題に関する追加情報が表示されます。

または、該当する GitHub リポジトリの [Security] > [Code scanning alerts] でセキュリティの問題を表示します。

次のコードスキャニング警告の 1 つをクリックすると、それらのセキュリティの問題が導入または修正された特定のコミット、タイムライン、ブランチが表示されます。

Mayhem CLI を使用した SARIF レポートの生成¶

他のオプションとして、Mayhem CLI を使用して SARIF レポートを生成することもできます。それには、mayhem run および mayhem wait --sarif <SARIF> の組み合わせを使用します。

Info

mayhem run および mayhem wait コマンドの詳細については「Mayhem CLI コマンド」ページを参照してください。

SARIF レポートが生成されたら、ユーザーは GitHub にSARIF ファイルをアップロードし、GitHub リポジトリの Security タブで結果を参照できます。

API をテストするためのワークフローの設定¶

Mayhem の GitHub Action を使用すると、API を変更するたびに、ただちに Mayhem でテストすることができます。

コードリポジトリのベースディレクトリに .github/workflows/mapi.yml ファイルを追加し、Mayhem を実行するよう GitHub Actions を構成します。ファイルは次のようになります。

name: Mayhem
on:
  push:
    branches: [main, master]
  pull_request:
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          # fetch a greater number of commits for computing diffs between jobs
          fetch-depth: 50

      - name: Start your API
        run: ./run_your_api.sh &
        #           ^-------------- update this, but keep the '&' to run
        #                           the API in the background.

      - name: Run Mayhem on your API to check for vulnerabilities
        uses: ForAllSecure/mapi-action@v1
        with:
          mapi-token: ${{ secrets.MAYHEM_TOKEN }}
          api-url: http://localhost:8000 # <- update this
          api-spec: your-openapi-spec-or-postman-collection.json # <- update this

この構成は、コードをチェックアウトし、API を開始し、API に対して Mayhem を実行するよう GitHub Actions に指示します。GitHub シークレット MAYHEM_TOKEN から Mayhem のトークンを渡しています。

テンプレートとして利用可能な模範的な統合を示した動作するサンプルリポジトリがこちらにあります。Mayhem Action に関する詳細については、GitHub Actions マーケットプレースの MAPI Action を参照してください。

SARIF レポートおよび GitHub コードスキャニング¶

パブリックリポジトリまたは GitHub Enterprise プランのプライベートリポジトリをテストする場合、SARIF レポートを生成することが推奨されます。mapi run に --sarif 引数を指定することで、Mayhem は SARIF ファイルを生成できます。GitHub を使用しているのであれば、SARIF ファイルは GitHub に課題をアップロードするのによい方法です。

GitHub

Mayhem Issues in GitHub

Microsoft の提供する SARIF 拡張を使用すると、VSCode に SARIF ファイルをロードすることもできます。

GitHub

Mayhem Issues in VSCode

Info

各問題について正確なファイルおよび行情報をレポートするには、API の "500 Internal Server Error" レスポンスの本文にスタックトレース情報が含まれている必要があります。開発およびテスト環境でだけスタックトレース情報を有効にし、運用環境では絶対に有効にしないでください。

GitHub に SARIF レポートをアップロードすると、Mayhem が発見した問題をリポジトリの [セキュリティ] タブで参照できます。さらに、API がエラーレスポンスボディの一部としてスタックトレースを返す場合、Mayhem は PR diff で問題は起きたコードの場所を表示します。

GitHub アクションの使用¶

ワークフローでは API を開始した後、Mayhem アクションを実行してから、github/codeql-action/upload-sarif@v1 を使用してレポートをアップロードします。

Note

Mayhem が問題を発見しても次のステップを実行するには、Mayhem アクションで continue-on-error に true を設定する必要があります。

- name: Run Mayhem to check for vulnerabilities
  uses: ForAllSecure/mapi-action@v1
  continue-on-error: true
  with:
    mapi-token: ${{ secrets.MAPI_TOKEN }}
    api-url: http://localhost:8000 # <- update this
    api-spec: your-openapi-spec-or-postman-collection.json # <- update this
    sarif-report: mapi.sarif

# Upload SARIF file (only available on public repos or github enterprise)
- name: Upload SARIF file
  uses: github/codeql-action/upload-sarif@v1
  with:
    sarif_file: mapi.sarif

CLI の使用¶

ローカルまたは CI など任意の場所から GitHub コードスキャンに結果をアップロードするのに Mayhem の CLI を使用できます。Mayhem が結果をアップロードできるよう、security_event スコープを持つ GitHub トークンを渡す必要があります。詳細についてはアクセストークンの作成に関する GitHub ドキュメントを参照してください。トークンを作成したら、下記を実行します。

mapi run "<target>" "<duration>" "<spec>" --sarif "mapi.sarif" --github-token "<github-token>"

Mayhem は CI による環境設定およびファイルシステムの git リポジトリから git 情報の推測を試みます。これらの情報が利用できない場合、Mayhem は結果を適切な場所にアップロードできるよう、不足している情報を指定するようユーザーに要求します。

さらに、Mayhem はオンプレミスの GitHub Enterprise もサポートしています。mapi run に --github-api-url <your-github-api-url> を渡して、結果をアップロードする場所を Mayhem に指示するだけです。CLI を実行しているホストから GitHub インスタンスにアクセスできる必要がありますが、Mayhem のクラウド基盤から GitHub インスタンスにアクセスできる必要はありません。

役に立つヒント¶

下のセクションは、推奨される (必須ではない) ヒントであり、mCode GitHub Action を最大限に活用するのに役立ちます。

GitHub での Mayhem 資産の整理¶

mCode GitHub Action を使用する際、mCode GitHub Action が適切にターゲットアプリケーションをビルド、プッシュ、テストできるよう、GitHub リポジトリでファイルをどのように構成するべきかを知ることが重要です。

mCode GitHub Action を使用するには、以下のファイルが必要です。

mayhem.yml: mCode GitHub Action ワークフローの構成ファイルです。.github/workflows/mayhem.yml に存在する必要があります。
Dockerfile: コンテナー化されたターゲットアプリケーションの Docker イメージを作成するためのビルドファイルです。
Mayhemfile: 特定のコンテナー化されたターゲットの Mayhem ランを実行するために必要な構成ファイルです。

全体として、GitHub に Mayhem 資産を格納する場合、次のファイル構造が推奨されます。

├── GitHub Repository
    └── .github
        └── workflows
            └── mayhem.yml
    └── README.md
    └── mayhem
         └── testsuite <-- The compilation of test cases for the target. Can be used to seed a Mayhem run.
         └── Mayhemfile.mayhemit-c
         └── Mayhemfile.lighttpd
    └── Dockerfile
    └── Mayhemit-c
    └── lighttpd

Note

上記のリポジトリファイル構成が推奨されますが、個々の好みに応じて構成できます。

サンプルとして、mcode-action-examples リポジトリのファイル構造を参照してください。

GitHub での Mayhem プロジェクトバッジの追加¶

GitHub リポジトリに Mayhem プロジェクトバッジを表示し、Mayhem が欠陥を発見したかどうかを素早く識別したい場合、簡単な手順で実現できます。🎉

GitHub リポジトリにプロジェクトバッジを追加するには、次の操作を行います。

Mayhem UI を開き、ホームページ上部の [Project] に移動します。既存のプロジェクトを選択し、左側のナビゲーションペインで [Settings] > [General] に移動します。

[Project Badges] セクションにスクロールダウンします。動的に生成された SVG バッジのマークダウンリンクおよびバッジの説明が利用できます。

プロジェクトバッジを追加する GitHub リポジトリに移動し、README.md ファイルを編集します。

前のステップのバッジリンクを貼り付けて、[Preview] ボタンを使用してバッジが正常に描画されることを確認します。

バッジが適切に描画されることを確認したら、変更を main / master ブランチにコミットします。

これで完了です。GitHub レポジトリに Mayhem プロジェクトバッジが追加されました。

これで、GitHub リポジトリに Mayhem プロジェクトバッジを表示できるようになりました。プロジェクトバッジを使用して、Mayhem プロジェクトや関連するランの情報をすばやく表示します。

ブランチの保護および必須チェックの設定¶

オプションとして、必須のプルリクエスト、承認、Mayhem 必須チェックを設定し、より強力にコードを保護したり、潜在的な脆弱性があるコードが GitHub リポジトリの main または master ブランチにマージされるのを防いだりすることができます。

これらの保護策を設定するには、対象 GitHub リポジトリの [Settings] > [Branches] に移動し、[Add rule] をクリックします。その後、次の条件をオンにします。

Require a pull request before merging
Require approvals
要求される承認の回数を指定します。デフォルト値は 1 です。
Require status checks
Mayhem を検索し、要求されるステータスチェックとして設定します。

Note

Mayhem が必須ステータスチェックとして表示されるには、少なくとも 1 回 mCode Action を実行する必要がある場合があります。

構成後のブランチ保護設定は次のようになります。

これらの保護策を設定した後、提案された変更が main ブランチにマージされるプルリクエストで、設定がどのように動作するかを確認できます。mCode GitHub Action は、ターゲットアプリケーションにセキュリティ脆弱性がないかをテストし、何らかの脆弱性が検出された場合、コードの変更が主要ブランチにマージされるのを防ぎます。

Info

次の画面ショットは、提案されているコードの変更に脆弱性があるプルリクエストを示しています。そのため、意図されたとおり、開発者は main ブランチにマージできません。

pr-checks

GitHub Action との統合¶

コードをテストするためのワークフローの設定¶

はじめに¶

mCode Action の構成¶

SARIF レポートの解析¶

Mayhem CLI を使用した SARIF レポートの生成¶

API をテストするためのワークフローの設定¶

SARIF レポートおよび GitHub コード スキャニング¶

GitHub アクションの使用¶

CLI の使用¶

役に立つヒント¶

GitHub での Mayhem 資産の整理¶

GitHub での Mayhem プロジェクト バッジの追加¶

ブランチの保護および必須チェックの設定¶

SARIF レポートおよび GitHub コードスキャニング¶

GitHub での Mayhem プロジェクトバッジの追加¶