コンテンツにスキップ

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 の使い方#

https://rest.vuls.biz に、APIメソッド一覧 にある URL を指定して、 HTTP リクエストを行ってください。

タスク一覧取得といった、レスポンスに複数のデータが含まれる API では、その ID の昇順にデータが取得されます。 FutureVuls APIドキュメントで、各 API の 「Model」をクリックすると、リクエスト・レスポンスのデータモデルが確認できます。

image.png

例：サーバID=1のすべての脆弱性情報を取得したい場合#

「APIサンプル」のページに API の使い方の具体例を示しているので、そちらも併せて参照してください。

curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/cves?filterServerID=1&page=1&limit=20' | jq
  • /cve/{cve ID} はグループ API なので、グループのトークンをヘッダに指定します
  • filterServerID を指定すると特定のサーバ内の情報に絞ることができるため、?filterServerID=1 の形で指定します
  • 一度に取得する件数を絞る場合は、page と limit を指定します

詳しいエンドポイントの仕様は、ドキュメントの該当箇所 を確認してください。

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 の値が全件数を超過していても問題ありません（全件数までのみ取得されます）

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

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

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

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

APIメソッド一覧#

API はトークン種別に応じて以下のように大きく3種類に分かれています。 それぞれ提供しているメソッドが異なるため、詳しくはマニュアルを確認してください。

APIサーバ状態確認#

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

グループAPI一覧#

グループ 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の取得方法
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 トークンを使用する必要があります。

トークン種別

オーガニゼーション設定とグループ設定で発行されたトークンは、グループセット 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 のレスポンスには「メンバの氏名、メールアドレスなどの個人情報」が含まれます。トークンの管理には厳重に注意してください。

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

  • オーガニゼーション設定から実行可能なメニュー（例えば外部の人を招待する機能など）
  • オーガニゼーション内のすべてのグループセット、すべてのグループの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 グループ・グループセットへのユーザ追加 オーガニゼーション設定

API を使用する際に指定する各パラメータの取得方法#

FutureVuls API を使用する際、場合により cveID や cpeID 等のパラメータを指定する場合があります。 これらのパラメータを取得する方法について説明します。

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 であるタスク一覧を取得できます。