コンテンツにスキップ
Aikido Docs 日本語版

Aikido CI API

Base URL https://app.aikido.dev

Aikido CI APIを使うと、リポジトリ内の特定のブランチに対して新しいスキャンを開始できます。スキャンの状態をポーリングできるため、CI/CDプラットフォーム内にゲーティング機構を構築できます。

Aikidoでは、特定のスキャンを自分で管理することもできます。独自のCheckov SARIFやカスタムSBOMをAikidoに直接アップロードし、フィーチャーブランチのスキャンに反映させることができます。

認証

Section titled “認証 ”
  1. CI integration detail pageにアクセスします。
  2. 認証トークンを生成してコピーします。このトークンは一度しか表示されない点にご注意ください。
  3. すべてのリクエストにX-AIK-API-SECRETヘッダーを追加し、その値として認証トークンを設定します。

新しいフィーチャーブランチスキャンを開始する

Section titled “新しいフィーチャーブランチスキャンを開始する ”

この非同期APIは、特定のコミットに対して新しいフィーチャーブランチスキャンを開始します。

POST /api/integrations/continuous_integration/scan/repository

Body:

{
    "version": "1.0.5",
    "branch_name": "branch-name",
    "repository_id": "R_kgDOJf6H8g",
    "base_commit_id": "1c5a7dda074aa19ebc6aa9f25884b5e0b6bb3662",
    "head_commit_id": "b7deb06d8be6bc4c62277e0a28911b2284cab6da",
    "minimum_severity": "HIGH",
    "fail_on_sast_scan": true,
    "fail_on_dependency_scan": true,
    "fail_on_iac_scan": true,
    "fail_on_secrets_scan": true,
    "fail_on_malware_scan": false,
    "pull_request_metadata": {
        "url": "https://github.com/AikidoSec/some-repo/pull/12",
        "title": "checkov"
    },
    "self_managed_scanners": ["checkov", "json-sbom"],
    "expected_amount_json_sboms": 1,
}

Required fields:

  • repository_id: GitHub/Gitlab/Bitbucket/..の内部リポジトリID
  • base_commit_id: ベースコミット（PRのブランチ元となったコミット。PRと無関係な場合はend_commit_idの直前のコミット）
  • head_commit_id: スキャン対象となる最新のコミット（ブランチ上の最後のコミット）
  • branch_name: ブランチ名

Optional fields:

  • pull_request_metadata.url: プルリクエストのURL
  • pull_request_metadata.title: プルリクエストのタイトル
  • self_managed_scanners: カスタムスキャン種別の配列（checkovとjson-sbomをサポート）。デフォルトは空配列[]。
  • expected_amount_json_sboms: 待機中のカスタムjson-sbomアップロード数を表す整数。
  • fail_on_dependency_scan（デフォルトtrue）: 新規の依存関係Issue（CVE）でAikidoをブロックするかどうかを指定します。
  • fail_on_sast_scan（デフォルトfalse）: 新規のSAST Issueでブロックするかどうかを指定します。
  • fail_on_iac_scan（デフォルト: false）: 新規のIaCスキャンでブロックするかどうかを指定します。
  • fail_on_secrets_scan（デフォルトfalse）: 新規の漏洩シークレットIssueでブロックするかどうかを指定します。
  • fail_on_malware_scan（デフォルトfalse）: 新規のマルウェアIssueでブロックするかどうかを指定します。
    • Note: この機能は全員が利用できるわけではありません。有効化を希望する場合はAikidoまでご連絡ください。
  • minimum_severity（デフォルトCRITICAL）: AikidoがFAILEDを返す（最低）深刻度を指定します。指定できる値はLOW、MEDIUM、HIGH、CRITICALのいずれかです。

Response:

{
    "scan_id": 22
}

フィーチャーブランチスキャンのステータスをポーリングする

Section titled “フィーチャーブランチスキャンのステータスをポーリングする ”

スキャンの現在の状態を取得します。CI/CDでのゲーティングを実装するには、ポーリング機構（例: 5秒ごと）を使用してください。

GET /api/integrations/continuous_integration/scan/repository?scan_id=1

Params:

  • scan_id (int)

Response:

フィーチャーブランチのスキャン実行中の例

{
    "all_scans_completed": false,
    "dependency_scan_completed": true,
    "sast_scan_completed": false,
    "iac_scan_completed": false,
    "secrets_scan_completed": false,
    "malware_scan_completed": false,
    "sbom_scan_completed": false // if 'json-sbom' in self_managed_scanners
}

フィーチャーブランチのスキャン完了の例

{
    "all_scans_completed": true,
    "dependency_scan_completed": true,
    "sast_scan_completed": true,
    "iac_scan_completed": true,
    "secrets_scan_completed": true,
    "malware_scan_completed": true,
    "sbom_scan_completed": true, // if 'json-sbom' in self_managed_scanners
    "new_issues_found": 1,
    "new_dependency_issues_found": 1,
    "new_sast_issues_found": 0,
    "new_iac_issues_found": 0,
    "new_leaked_secret_issues_found": 0,
    "diff_url": "https://app.aikido.dev/featurebranch/scan/1?groupId=1",
    "gate_passed": false
}

デフォルトブランチのスキャン完了の例

{
    "all_scans_completed": false,
    "dependency_scan_completed": true,
    "sast_scan_completed": false,
    "iac_scan_completed": false,
    "secrets_scan_completed": false,
    "malware_scan_completed": false,
    "open_issues_found": 2,
    "issue_links": [
        "https://app.aikido.dev/queue?sidebarIssue=1",
        "https://app.aikido.dev/queue?sidebarIssue=2",
    ],
    "gate_passed": false
}
{
    "all_scans_completed": false,
    "dependency_scan_completed": true,
    "sast_scan_completed": false,
    "iac_scan_completed": false,
    "secrets_scan_completed": false,
    "malware_scan_completed": false,
    "open_issues_found": 2,
    "issue_links": [
        "https://app.aikido.dev/queue?sidebarIssue=1",
        "https://app.aikido.dev/queue?sidebarIssue=2",
    ],
    "gate_passed": false,
}
{
    "all_scans_completed": false,
    "dependency_scan_completed": true,
    "sast_scan_completed": false,
    "iac_scan_completed": false,
    "secrets_scan_completed": false,
    "malware_scan_completed": false,
    "open_issues_found": 2,
    "issue_links": [
        "https://app.aikido.dev/queue?sidebarIssue=1",
        "https://app.aikido.dev/queue?sidebarIssue=2",
    ],
    "gate_passed": false,
}

カスタムスキャン結果をアップロードする

Section titled “カスタムスキャン結果をアップロードする ”

このAPIは、独自のCheckov SARIFや、Syftで生成したカスタムSBOMをアップロードするために使用できます。Syft SBOMを生成する際はJSON形式を使用してください。

POST /api/integrations/continuous_integration/scan/custom

Body:

Checkovの例

{
    "scan_id": 22, // optional
    "repository_id": 12,
    "payload_type": "checkov",
    "payload": <checkov_sarif_response>
}

Syft SBOMの例

{
    "scan_id": 22, // optional
    "repository_id": 12,
    "container_image_name": "image-name",
    "payload_type": "json-sbom",
    "payload": <syft_json_sbom_response>
}

Required fields:

  • container_image_name: json-sbomの場合は必須です。イメージタグは含めず、イメージの一意な名前のみを指定してください。
  • payload_type
  • payload

Optional fields:

  • scan_id: （Start Scanで取得）。ペイロードをAikidoのライブフィードに送りたい場合は設定しないでください。
  • repository_id: GitHub/Gitlab/Bitbucket/..の内部リポジトリID（scan_idが未設定の場合のみ必須）

Response:

{
    "success": 1
}