コンテンツにスキップ

FutureVuls API#

FutureVuls では外部アプリケーションの開発用に REST API を用意しています。 FutureVuls のデータを API を利用して取得できます。

「APIドキュメント」から、API の詳細を確認できます。 API のパラメータやレスポンスの型を確認できます。

FutureVuls API は Authorization に API トークンを指定することで実行できます。 この API トークンはグループ・グループセット・オーガニゼーションの設定画面で管理（閲覧・作成・編集・削除・再生成・有効化/無効化）します。 API トークンは権限で分けることも可能です。

APIドキュメントの利用上の注意

「FutureVuls APIドキュメント」ページには、ブラウザ上からAPIを実行できる機能がありますが、現在こちらの機能は動作していませんのでご注意ください。

image

FutureVuls APIのトークン管理#

FutureVuls APIのトークンはグループ設定、グループセット設定、オーガニゼーション設定の「トークン」ページでそれぞれ管理されています。

image

ここでは、Scanner用のトークンや、FutureVuls API用のトークンを管理可能です。 この画面には以下の権限を持つユーザのみアクセス可能です（参考：ユーザ権限）

トークン種別 必要な権限
グループ グループ管理者権限
グループセット グループセット管理者権限
オーガニゼーション オーガニゼーション権限（オーナ・CSIRT）

FutureVuls APIのトークン作成#

トークン追加 からAPIトークンの追加を行えます。 APIトークンの名前と権限を設定して作成します。

image

設定できる権限は以下の通りです。

トークン種別 API権限 スキャン権限
グループトークン ・読み込み、更新、グループ設定
・読み込み、更新
・読み込み
・なし		 あり/なし
グループセットトークン ・読み込み、更新
・読み込み		 ー
オーガニゼーショントークン ・読み込み、更新、オーガニゼーション設定
・読み込み、更新
・読み込み		 ー

トークンの更新#

作成したトークンは、一覧から編集・再生成・削除・有効化/無効化ができます。

更新内容 説明
編集 API トークン名、API 権限、スキャン権限を編集できます
再生成 API トークンのハッシュを再生成できます。元には戻せないため、確認の上実行してください。
削除 API トークンを削除します。削除されたトークンを用いると認証に失敗します。
有効化/無効化 ステータス列のトグル切り替えでトークンのステータスを切り替えられます。
ステータスが無効のトークンを用いると認証に失敗します。

FutureVuls APIの注意点#

  • ソフトウェア一覧や、タスク一覧などのデータが多い物に関しては、フィルタを使用してアクセスすると短時間で取得可能です
  • パラメータのデフォルト値が設定されている API があるので、ドキュメント（Future Vuls Public API）でデフォルト値の確認をお願いします
  • パラメータを配列指定するものは、同じキーを複数 & で繋いでください (ex. filterStatus=new&filterStatus=investigating )

ページネーション#

FutureVuls API は大量データをサポートするために、ページネーション形式を採用しています。 一覧データを一度に取得できる最大件数(limit)は1000件ですが、ページ番号(page)をインクリメントすることで一覧データを全件取得可能です。 （参考：オプション指定可能なパラメータ）

全件取得をしたい場合などには、適切にページネーションのパラメータの設定をしてください。

  • limit の値を指定しない場合、デフォルト値として limit=20 が設定され、最大20件だけが取得されます
  • limit の値を小さくすることで、１回あたりのAPIの実行時間を短くできます（その分pageによる処理回数を増やします）
  • limit の値が全件数を超過していても問題ありません（全件数までのみ取得されます）

例1）全部で80件（<1000件）あるリストを全件取得したい。

  • ?limit=1000 などで実行してください

例2）全部で1500件（>1000件）あるリストを全件取得したい。

  1. ?page=1&limit=1000 で一度実行してください
  2. 次に ?page=2&limit=1000 で実行してください

APIメソッド一覧#

  • https://rest.vuls.biz に、以下の URL を指定して HTTP リクエストを行ってください。
  • タスク一覧取得といった、レスポンスに複数のデータが含まれるAPIでは、その ID の昇順にデータが取得されます。
  • FutureVuls APIドキュメントで、各 API の 「Model」をクリックすると、リクエスト・レスポンスのデータモデルが確認できます。

image.png

APIサーバ状態確認#

HTTPメソッド URL 説明 必要な権限
GET /health health なし

グループAPI一覧#

グループAPIを利用するためには、各グループごとで発行されたAPIトークンを使用する必要があります。

オーガニゼーション設定とグループセット設定で発行されたトークンは利用できません。

HTTPメソッド URL 説明 必要な権限 備考
GET /v1/cve/{cveID} cve詳細 読み込み cveIDの取得方法
GET /v1/cves cve一覧 読み込み オプションあり
GET /v1/lockfiles Lockファイル一覧 読み込み オプションあり
GET /v1/lockfile/{lockfileID} Lockファイル詳細 読み込み lockfileIDの取得方法
POST /v1/lockfile Lockファイル追加 更新 Lockファイル追加
POST /v1/lockfile/sbom SBOMファイル追加 更新
PUT /v1/lockfile/{lockfileID} Lockファイル更新 更新 lockfileIDの取得方法
DELETE /v1/lockfile/{lockfileID} Lockファイル削除 更新 lockfileIDの取得方法
POST /v1/pkgCpe/cpe cpe追加 更新
DELETE /v1/pkgCpe/cpe/{cpeID} cpe削除 更新 cpeIDの取得方法
DELETE /v1/pkgCpe/cpe [DEPRECATED]cpe削除 更新 cpeIDの取得方法
GET /v1/pkgCpe/cpe/{cpeID} cpe詳細 読み込み cpeIDの取得方法
GET /v1/pkgCpe/pkg/{pkgID} package詳細 読み込み pkgIDの取得方法
GET /v1/pkgCpe/windowsPkg/{windowsPkgID} WindowsPkg詳細 読み込み windowsPkgIDの取得方法
GET /v1/pkgCpes package&cpe一覧 読み込み オプションあり
GET /v1/role/{roleID} ロール詳細 読み込み roleIDの取得方法
PUT /v1/role/{roleID} ロール更新 更新 roleIDの取得方法
DELETE /v1/role/{roleID} ロール削除 更新 roleIDの取得方法
GET /v1/roles ロール一覧 読み込み オプションあり
POST /v1/server/pseudo 擬似サーバの作成 更新
POST /v1/server/paste ペーストサーバの作成 更新
POST /v1/server/sbom SBOMインポート 更新
PUT /v1/server/paste/{serverID} ペーストサーバの更新 更新 serverIDの取得方法
GET /v1/server/uuid/{serverUuid} UUIDを使ったサーバ詳細 読み込み UUIDの取得方法
GET /v1/server/uuid/{serverUuid} UUIDを使ったサーバ詳細 読み込み UUIDの取得方法
POST /v1/server/scan/{serverID} サーバスキャン 更新 serverIDの取得方法
GET /v1/server/{serverID} サーバ詳細 読み込み serverIDの取得方法
PUT /v1/server/{serverID} サーバ更新 更新 serverIDの取得方法
DELETE /v1/server/{serverID} サーバ削除 更新 serverIDの取得方法
POST /v1/server/{serverID}/tag サーバタグ追加 更新 serverIDの取得方法
DELETE /v1/server/{serverID}/tag サーバタグ削除 更新 serverIDの取得方法
GET /v1/servers サーバ一覧 読み込み オプションあり
GET /v1/task/{taskID} タスク詳細 読み込み taskIDの取得方法
PUT /v1/task/{taskID} タスク更新 更新 taskIDの取得方法
POST /v1/task/{taskID}/comment タスクコメント追加 更新 taskIDの取得方法
PUT /v1/task/{taskID}/ignore タスク非表示設定 更新 taskIDの取得方法
GET /v1/tasks タスク一覧 読み込み オプションあり
GET /v1/members メンバ一覧 読み込み オプションあり
GET /v1/scanImports 外部スキャン結果一覧 読み込み オプションあり
GET /v1/scanImport/{scanImportID} 外部スキャン詳細 読み込み scanImportIDの取得方法
POST /v1/scanImport 外部スキャン結果追加 更新
PUT　 /v1/scanImport/{scanImportID} 外部スキャン結果更新 更新
DELETE /v1/scanImport/{scanImportID} 外部スキャン結果削除 更新

グループセットAPI一覧#

グループセットAPIを利用するためには、各グループセットごとで発行されたAPIトークンを使用する必要があります。

オーガニゼーション設定とグループ設定で発行されたトークンは利用できません。

HTTPメソッド URL 説明 必要な権限 備考
GET /v1/groupSet/cve/{cveID} cve詳細 読み込み cveIDの取得方法
GET /v1/groupSet/cves cve一覧 読み込み オプションあり
GET /v1/groupSet/pkgCpe/cpe/{cpeID} cpe詳細 読み込み cpeIDの取得方法
GET /v1/groupSet/pkgCpe/pkg/{pkgID} package詳細 読み込み pkgIDの取得方法
GET /v1/groupSet/pkgCpe/windowsPkg/{windowsPkgID} WindowsPkg詳細 読み込み windowsPkgIDの取得方法
GET /v1/groupSet/pkgCpes package&cpe一覧 読み込み オプションあり
GET /v1/groupSet/server/uuid/{serverUuid} UUIDを使ったサーバ詳細 読み込み UUIDの取得方法
GET /v1/groupSet/server/{serverID} サーバ詳細 読み込み serverIDの取得方法
GET /v1/groupSet/servers サーバ一覧 読み込み オプションあり
GET /v1/groupSet/task/{taskID} タスク詳細 読み込み taskIDの取得方法
GET /v1/groupSet/tasks タスク一覧 読み込み オプションあり

オーガニゼーションAPI一覧#

オーガニゼーションAPIを利用するためには、オーガニゼーション設定で発行されたAPIトークンを使用する必要があります。

グループセット設定とグループ設定で発行されたトークンは利用できません。

オーガニゼーショントークンにより、組織内の「グループ一覧、グループセット一覧、メンバ一覧」が取得可能です。 API のレスポンスには「メンバの氏名、メールアドレスなどの個人情報」が含まれます。トークンの管理には厳重に注意してください。

また、今後のリリースにて以下のようなオーガニゼーション全体に関する設定が可能になる見込みです。オーガニゼーションのトークンの取り扱いには注意してください。

  • オーガニゼーション設定から実行可能なメニュー（例えば外部の人を招待する機能など
  • オーガニゼーション内のすべてのグループセット、すべてのグループのAPIを実行可能にする
HTTPメソッド URL 説明 必要な権限 備考
GET /v1/org/groups グループ一覧 読み込み
GET /v1/org/groupsets グループセット一覧 読み込み
GET /v1/org/members メンバ一覧 読み込み
GET /v1/org/auditLogs 監査ログ一覧 読み込み
POST /v1/org/group グループ作成 オーガニゼーション設定
PUT /v1/org/group/{groupID} グループ設定更新 オーガニゼーション設定
POST /v1/org/users グループ・グループセットへのユーザ追加 オーガニゼーション設定

各種情報の取得方法#

cveIDの取得方法#

以下の2つの方法のどちらかで取得できます。

  • 脆弱性タブを開き、IDを取得したい脆弱性の CVE ID 列を参照する。
  • REST APIリクエストで取得する。
    • グループAPIの場合
      • https://rest.vuls.biz/v1/cves にGETリクエストを実行し、脆弱性一覧を取得する。レスポンスJSONの cves に含まれるデータのうち、IDを取得したい脆弱性の cveID を参照する。
    • グループセットAPIの場合
      • https://rest.vuls.biz/v1/groupSet/cves にGETリクエストを実行し、脆弱性一覧を取得する。レスポンスJSONの cves に含まれるデータのうち、IDを取得したい脆弱性の cveID を参照する。

image

cpeIDの取得方法#

以下の方法で取得できます。

  • グループAPIを使用する場合
    • https://rest.vuls.biz/v1/pkgCpes に GET リクエストを実行し、package&cpe 一覧を取得する。レスポンス JSON の pkgCpes に含まれるデータのうち、ID を取得したい cpe の cpeID を参照する。
  • グループセットAPIを使用する場合
    • https://rest.vuls.biz/v1/groupSet/pkgCpes に GET リクエストを実行し、package&cpe 一覧を取得する。レスポンス JSON の pkgCpes に含まれるデータのうち、ID を取得したい cpe の cpeID を参照する。

pkgIDの取得方法#

以下の方法で取得できます。

  • グループAPIを使用する場合
    • https://rest.vuls.biz/v1/pkgCpes に GET リクエストを実行し、package&cpe 一覧を取得する。レスポンス JSON の pkgCpes に含まれるデータのうち、ID を取得したいパッケージの pkgID を参照する。
  • グループセットAPIを使用する場合
    • https://rest.vuls.biz/v1/groupSet/pkgCpes に GET リクエストを実行し、package&cpe 一覧を取得する。レスポンス JSON の pkgCpes に含まれるデータのうち、ID を取得したいパッケージの pkgID を参照する。

UUIDの取得方法#

以下の2つの方法のどちらかで取得できます。

  • サーバタブを開き、IDを取得したいサーバの サーバUUID 列を参照する。（サーバUUID 列は表示項目の編集から表示）
  • REST APIリクエストで取得する。
    • グループAPIの場合
      • https://rest.vuls.biz/v1/servers に GET リクエストを実行し、サーバ一覧を取得する。レスポンス JSON の servers に含まれるデータのうち、ID を取得したいサーバの serverUuid を参照する。
    • グループセットAPIの場合
      • https://rest.vuls.biz/v1/groupSet/servers にGETリクエストを実行し、サーバ一覧を取得する。レスポンスJSONの servers に含まれるデータのうち、IDを取得したいサーバの serverUuid を参照する。

serverIDの取得方法#

以下の2つの方法のどちらかで取得できます。

  • サーバタブを開き、IDを取得したいサーバの サーバID 列を参照する。（サーバID 列は表示項目の編集から表示）
  • REST APIリクエストで取得する。
    • グループAPIの場合
      • https://rest.vuls.biz/v1/servers にGETリクエストを実行し、サーバ一覧を取得する。レスポンスJSONの servers に含まれるデータのうち、IDを取得したいサーバの id を参照する。
    • グループセットAPIの場合
      • https://rest.vuls.biz/v1/groupSet/servers にGETリクエストを実行し、サーバ一覧を取得する。レスポンスJSONの servers に含まれるデータのうち、IDを取得したいサーバの id を参照する。

taskIDの取得方法#

以下の2つの方法のどちらかで取得できます。

  • タスクタブを開き、IDを取得したいタスクの タスクID 列を参照する。（タスクID 列は表示項目の編集から表示）
  • REST APIリクエストで取得する。
    • グループAPIの場合
      • https://rest.vuls.biz/v1/tasks にGETリクエストを実行し、タスク一覧を取得する。レスポンスJSONの tasks に含まれるデータのうち、IDを取得したいタスクの id を参照する。
    • グループセットAPIの場合
      • https://rest.vuls.biz/v1/groupSet/tasks にGETリクエストを実行し、タスク一覧を取得する。レスポンスJSONの tasks に含まれるデータのうち、IDを取得したいタスクの id を参照する。

roleIDの取得方法#

以下の方法で取得できます。

  • ロールタブを開き、IDを取得したいロールの ロールID 列を参照する。（ロールID 列は表示項目の編集から表示）
  • REST APIリクエストで取得する。
    • https://rest.vuls.biz/v1/roles にGETリクエストを実行し、ロール一覧を取得する。レスポンスJSONの roles に含まれるデータのうち、IDを取得したいロールの id を参照する。

lockfileIDの取得方法#

以下の方法で取得できます。

  • サーバタブを開き、IDを取得したいLockファイルが存在するサーバを選択。アプリケーションタブからIDを取得したいLockファイルを選択し、表示されるLockファイルの#以降の値を参照する。 image
  • REST APIリクエストで取得する。
    • https://rest.vuls.biz/v1/lockfiles にGETリクエストを実行し、Lockファイル一覧を取得する。レスポンスJSONの lockfiles に含まれるデータのうち、IDを取得したいLockファイルの id を参照する。

windowsPkgIDの取得方法#

以下の方法で取得できます。

  • サーバタブを開き、IDを取得したいパッケージが存在するサーバを選択。ソフトウェアタブを開き、 ID 列を参照する。
  • サーバタブを開き、IDを取得したいパッケージが存在するサーバを選択。ソフトウェアタブからIDを取得したいパッケージを選択し、表示されるwindowsPkgの#以降の値を参照する。

image

scanImportIDの取得方法#

以下の方法で取得できます。

  • REST APIリクエストで取得する
    • https://rest.vuls.biz/v1/scanImportsにGETリクエストを実行し、スキャン結果一覧を取得する。レスポンスJSONの scanImports に含まれるデータのうち、IDを取得したいスキャン結果の id を参照する。

オプション指定可能なパラメータ#

API によって、データを取得する際に以下のオプションが指定可能です。 各APIごとに指定可能なオプションはFuturevVuls APIドキュメントを参照してください。

配列のパラメータを指定する場合

配列（array）のパラメータを指定する場合は、複数指定する必要があります。

例えば、タスク一覧取得の API で、タスクステータスが「"new" または "investigating"」に該当するものにフィルターしたい場合は、以下のような url で実行する必要があります。

"https://rest.vuls.biz/v1/tasks?filterStatus=new&filterStatus=investigating"
パラメータ タイプ デフォルト値 説明
page integer 1 ページネーション分割されたデータの、取得するページ番号
limit integer 20 ページネーション分割するデータの、1ページあたりの件数
offset integer 0 ページネーション分割する前のデータのオフセット
filterCveID string ー 指定したcveIDの脆弱性に関連するデータのみ取得
filterTaskID integer ー 指定したtaskIDのタスクに関連するデータのみ取得
filterServerID integer ー 指定したserverIDのサーバに関連するデータのみ取得
filterRoleID integer ー 指定したroleIDのロールに関連するデータのみ取得
filterPkgID integer ー 指定したpkgIDのpackageに関連するデータのみ取得
filterCpeID integer ー 指定したcpeIDのcpeに関連するデータのみ取得
filterStatus array[string] ["new", "investigating", "ongoing"] 指定したステータスのタスクのみ取得
filterPriority array[string] ー 指定した優先度のタスクのみ取得
filterIgnore boolean ー true: 非表示フラグがOFFのタスクのみを取得
false: 全件取得
filterMainUserIDs array[integer] ー 指定したuserIDのユーザが主担当であるタスクのみ取得
filterSubUserIDs array[integer] ー 指定したuserIDのユーザが副担当であるタスクのみ取得
filterIsExternalScan boolean ー 外部スキャン列が有効になっているタスク、脆弱性のみ取得

例えば、グループに登録されているサーバ一覧を取得する場合を考えます。 https://rest.vuls.biz/v1/servers?page=1&limit=20&offset=5 にGETリクエストをすると、serverID順に先頭5件を除いた20件を取得します。つまり、6件目のデータから25件目のデータが取得されます。

https://rest.vuls.biz/v1/servers?page=2&limit=20&offset=5 とすると、26件目のデータから45件目のデータが取得されます。 オフセットを指定せず、https://rest.vuls.biz/v1/servers?page=1&limit=20 とした場合は、1件目のデータから20件目のデータが取得されます。

また、https://rest.vuls.biz/v1/tasks?filterPriority=high&filterPriority=medium にGETリクエストを実行すると、タスク優先度が HIGH もしくは MEDIUM であるタスク一覧を取得できます。