Devin API でコードスキャンをトリガーする

v3 の組織および Enterprise API を使用して、Devin のコードスキャンをプログラムで開始し、ステータスをポーリングして検出結果を確認するためのガイド

コードスキャン API を使用すると、web app を使わずにスキャンの開始、ポーリング、検出結果の確認を行えます。すべての操作は、他の v3 API と同様に、組織と Enterprise の区分に従って 2 つのスコープで利用できます。

• 組織 (/v3/organizations/{org_id}/code-scans/...) は単一の組織を対象とし、組織レベルの UseCodeScans (書き込み) または ViewCodeScans (読み取り) 権限が必要です。
• Enterprise (/v3/enterprise/...) は Enterprise 内のすべての組織を対象とし、Enterprise レベルの UseAccountCodeScans (書き込み) または ViewAccountCodeScans (読み取り) 権限が必要です。スキャンは 1 つの組織に属するため、スキャン作成および修復のエンドポイントでは引き続きパスに org_id を指定します。

どちらのスコープでも、サービスユーザーの APIキーまたはパーソナルアクセストークンで認証し、リクエストとレスポンスの形式は共通です。

​

エンドポイント

操作	組織	Enterprise
コードスキャンを開始	POST /v3/organizations/{org_id}/code-scans	POST /v3/enterprise/organizations/{org_id}/code-scans
取り込みスキャンを開始	POST .../code-scans/ingestion	POST .../code-scans/ingestion
コードスキャンを一覧表示	GET /v3/organizations/{org_id}/code-scans/scans	GET /v3/enterprise/code-scans/scans
コードスキャンプロファイルを一覧表示	GET .../code-scans/profiles	GET /v3/enterprise/code-scans/profiles
コードスキャンプロファイルを取得	GET .../code-scans/profiles/{profile_id}	GET /v3/enterprise/code-scans/profiles/{profile_id}
コードスキャンの検出結果を一覧表示	GET .../code-scans/findings	GET /v3/enterprise/code-scans/findings
コードスキャンのメトリクスを取得	GET .../code-scans/metrics	GET /v3/enterprise/code-scans/enterprise-code-scans-metrics
コードスキャンの検出結果を修復	POST .../findings/{finding_id}/remediate	POST .../findings/{finding_id}/remediate

同じ操作は、リクエストおよびレスポンスの形式が同一の/v3beta1/...パスでも利用できます。この表ではスキャンワークフローを扱います。v3 OpenAPI仕様では、両方のスコープで自動スキャンのスケジュール設定 (POST .../code-scans/{scan_id}/auto-scan) とプロファイルの再割り当て (PUT .../code-scans/{scan_id}/profile) も利用できます。

以下の手順では組織スコープを使用します。認証情報がEnterpriseスコープの場合は、Enterprise用のパスと権限に置き換えてください。

​

一般的なフロー

1. プロファイルを選択する（任意）

   コードスキャンプロファイルを一覧表示 を呼び出し、discover モードのプロファイルを選択します。デフォルトのセキュリティスキャンを実行する場合は、プロファイルを指定しません。セキュリティ以外のスキャンでは、一致するスキャンタイプのプロファイルが必要です。

2. スキャンを開始する

   curl -X POST "https://api.devin.ai/v3/organizations/$ORG_ID/code-scans" \
     -H "Authorization: Bearer $DEVIN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"repo_name": "acme/payments"}'
   

   レスポンスとして、スキャンレコードを含む 201 が返されます。scan_id を保持してください。409 は、組織のスキャンバックログが満杯であることを示します。後で再試行してください。

3. 完了するまでポーリングする

   スキャンの status が completed (または failed / cancelled) になるまで、コードスキャンの一覧 を呼び出します (repo_name でフィルタリング) 。これら3つの状態は終端状態として扱います。awaiting_user_input は、web app から開始された対話型スキャンでのみ発生します。API で開始したスキャンは非対話型のため、この状態にはなりません。

4. 検出結果を確認する

   scan_id を指定して コードスキャンの検出結果を一覧表示 を呼び出し、検出結果をページ単位で取得します。必要に応じて、severity と status でフィルタリングできます。

5. 修復する

   コードスキャンの検出結果を修復 を呼び出すと、Devin が検出結果を修正するプルリクエストを作成します。

​

取り込みスキャン

別のスキャナーで生成された検出結果を Devin にトリアージさせるには、web app で ingest モードのプロファイルを作成します。次に、attachments API (コードスキャン権限に加え、UseDevinSessions 組織権限が必要な組織スコープのエンドポイント) を使用してスキャナーのレポートをアップロードし、profile_id と attachment_urls を指定して Start 取り込み コードスキャン (または Enterprise 相当のエンドポイント) を呼び出します。