> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> GitHub Actions の例で、CI/CD から MindFort のアセスメントを開始し、検出結果のポーリングとレポートのダウンロードを行います。

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

## 前提条件

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

1. **API Key**: [MindFort Dashboard](https://cloud.mindfort.app) の **Settings > API Keys** で生成します。
2. **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` に設定できます。

```yaml theme={null}
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
```

> [accordion] 必要なシークレットと変数
>
> | 種類 | 名前 | 説明 |
> | - | - | - |
> | Secret | `MINDFORT_API_KEY` | MindFort の API キー |
> | Variable | `MINDFORT_TARGET_ID` | アセスメント対象のターゲットの UUID |
> | Variable | `MINDFORT_ASSESSMENT_METHOD` | 任意。`balanced` (デフォルト)、`deep`、または `ultra` |

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

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

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

```bash theme={null}
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](https://docs.mindfort.ai/ja/api-reference/findings) を参照してください。

`description`、`impact`、`evidence`、`approach`、`remediation_advice` を含む詳細を取得するには、`GET /v1/findings/{finding_id}` を使用します。

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

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

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

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

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

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

```bash theme={null}
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` を含めることができます。

```bash theme={null}
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` です。

### レポートを生成する

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

```bash theme={null}
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"
  }'
```

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.