CI/CD パイプラインで MindFort を実行する

MindFort を CI/CD パイプラインに統合すると、設定したプッシュ、プルリクエスト、デプロイのイベントでセキュリティアセスメントをリクエストできます。これにより、セキュリティテストを開発ワークフローの定常的な一部にすることができます。

前提条件

パイプラインを設定する前に、次のものが必要です。

API Key: MindFort Dashboard の Settings > API Keys で生成します。
Target ID: Target Inventory で、アセスメントを実行したいターゲットをクリックすると確認できます。

API キーは CI/CD プラットフォームのシークレットとして保存してください。リポジトリには絶対にコミットしないでください。

GitHub Actions の例

アセスメントをトリガーする

この例では、main へのプッシュまたは PR 時に、ターゲットに対するセキュリティアセスメントをリクエストします。実行を開始できるかどうかは、ターゲットの準備状況、利用可能なクレジット、別のアセスメントがすでに実行中かどうかによって決まります。アセスメント方式は MINDFORT_ASSESSMENT_METHOD 変数 (balanced、deep、または ultra) で設定します。これらはダッシュボードのラベル Balanced、Deep、Ultra に対応します。任意で、assessment_type を black-box (デフォルト) または white-box に設定できます。

name: MindFort Security Assessment

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  mindfort-assessment:
    name: Trigger MindFort Assessment
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Assessment
        id: trigger
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" \
            -X POST "https://api.mindfort.app/v1/assessments/run" \
            -H "Authorization: Bearer ${{ secrets.MINDFORT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "target_id": "${{ vars.MINDFORT_TARGET_ID }}",
              "assessment_method": "${{ vars.MINDFORT_ASSESSMENT_METHOD || 'balanced' }}"
            }')

          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
          BODY=$(echo "$RESPONSE" | sed '$d')

          echo "status_code=$HTTP_CODE" >> "$GITHUB_OUTPUT"
          echo "response=$BODY" >> "$GITHUB_OUTPUT"

          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
            echo "::error::MindFort API returned HTTP $HTTP_CODE: $BODY"
            exit 1
          fi

          ASSESSMENT_ID=$(echo "$BODY" | jq -r '.assessment_id')
          echo "assessment_id=$ASSESSMENT_ID" >> "$GITHUB_OUTPUT"
          echo "Assessment triggered: $ASSESSMENT_ID"

      - name: Summary
        if: always()
        run: |
          echo "### MindFort Assessment" >> "$GITHUB_STEP_SUMMARY"
          if [ "${{ steps.trigger.outputs.assessment_id }}" != "" ]; then
            echo "- **Assessment ID:** \`${{ steps.trigger.outputs.assessment_id }}\`" >> "$GITHUB_STEP_SUMMARY"
            echo "- **Status:** Triggered" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "- **Status:** Failed (HTTP ${{ steps.trigger.outputs.status_code }})" >> "$GITHUB_STEP_SUMMARY"
          fi

必要なシークレットと変数

種類	名前	説明
Secret	`MINDFORT_API_KEY`	MindFort の API キー
Variable	`MINDFORT_TARGET_ID`	アセスメント対象のターゲットの UUID
Variable	`MINDFORT_ASSESSMENT_METHOD`	任意。`balanced` (デフォルト)、`deep`、または `ultra`

ターゲットと検出結果を一覧表示する

最初にターゲットを確認し、その後すべてのターゲットまたは 1 つのターゲット内の検出結果を一覧表示したい場合は、組織全体のエンドポイントを使用します。これらのエンドポイントは limit と offset によるページネーションを使用し、total 件数を含みます。

curl -G "https://api.mindfort.app/v1/targets" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=25"

curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "exclude_secured=true" \
  --data-urlencode "severity=critical" \
  --data-urlencode "sort_by=severity" \
  --data-urlencode "limit=25"

GET /v1/findings は、識別子、ターゲットのメタデータ、重大度と上書き値、ライフサイクルステータス、タイムスタンプ、再テストの状態を含む検出結果のサマリーを返します。レスポンスには、ページネーションのメタデータとして total、limit、offset、next_cursor が含まれます。デフォルトは status=ACTIVE です。ダッシュボードの Open タブ (脆弱性のみ) と一致させるには、exclude_secured=true を設定してください。1 回のアセスメント実行に絞り込むには assessment_id を使用します。すべてのフィルターについては、Findings API を参照してください。 description、impact、evidence、approach、remediation_advice を含む詳細を取得するには、GET /v1/findings/{finding_id} を使用します。

アセスメントをキャンセルする

POST /v1/assessments/run から返された、または Assessments ページからコピーした assessment_id を使用します。

curl -X POST "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}/cancel" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

このエンドポイントはリクエストボディを受け付けません。

アセスメントの進捗をポーリングする

パイプラインでステージ単位の進捗や最終的な失敗理由が必要な場合は、アセスメントの詳細エンドポイントを使用します。

curl "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

各アセスメントステージを追跡するには stage_progress を使用します。NOT_STARTED は状態がまだ記録されていないことを意味し、RUNNING または ACTIVE は処理が進行中であることを示します。失敗したアセスメントには、問題を説明する failure_reason が含まれる場合があります。アセスメントの作成に失敗した場合は、安定した公開エラーの code を確認してください。たとえば、assessment_credits_insufficient は請求上の容量不足を認可の問題と区別するためのもので、assessment_queue_loading は再試行可能であり Retry-After を含みます。

検出結果のステータスを更新する

ステータスの更新を使用して、自動化からトリアージの状態を同期させます。解決済みにする際は、resolve_reason (FIX または WONT_FIX) と任意の resolve_context を含めることができます。

curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","resolve_reason":"FIX"}'

有効なステータス値は ACTIVE、RESOLVED、ARCHIVED です。

レポートを生成する

ターゲットのレポートを作成し、ステータスをポーリングして、準備ができたらダウンロードします。

curl -X POST "https://api.mindfort.app/v1/reports" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "'"${MINDFORT_TARGET_ID}"'",
    "include_secured_findings": true,
    "include_resolved_findings": false,
    "report_detail_level": "full"
  }'

curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}/download" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

​前提条件

​GitHub Actions の例

​アセスメントをトリガーする

​ターゲットと検出結果を一覧表示する

​アセスメントをキャンセルする

​アセスメントの進捗をポーリングする

​検出結果のステータスを更新する

​レポートを生成する