開発者API

開発用APIについて

FutureVulsでは外部アプリ開発用にAPIを用意しています。 FutureVulsのデータをAPIを利用して取得することが可能です。

開発者APIの概略は以下のようになっています

  • コードを使ったSecOpsに利用可能
  • ドキュメントでモデルを確認可能
  • トークンを作成することでAPIからデータ取得可能
  • トークンには、権限が設定可能
  • トークンは、作成、編集、削除、再作成、有効化、無効化が可能
  • Authorizationを指定してAPIアクセス
  • 配列のオプションは、複数指定する
  • GolangのSDKがある
  • APIドキュメントから詳細を確認できる

開発用APIのトークン管理

開発用のAPIのトークンはグループ設定のトークンで管理されています。 image.png

ここでは、Scanner用のトークンや、開発者API用のトークンを管理可能です。

グループ設定はグループ管理者権限をもつユーザのみアクセス可能です

開発者APIのトークン作成

トークンページで トークン追加 をクリックするとトークンの追加を行えます。

image.png

トークンの名前と権限を設定して作成します。

API権限は以下の通りです。

  • 読み込み、更新、グループ設定
  • 読み込み、更新
  • 読み込み

権限は各種文言の通りとなっています。 グループ設定 が必要なAPIは別ページで実装される予定です。

トークン編集

トークンの編集をクリックすることで、トークン名、API権限、スキャン権限を編集ができます。

image.png

トークン再作成

トークンの再作成では、トークンのハッシュを再作成できます。
元に戻すことができないため、確認の上、再作成してください。

image.png

この他にも、トークンの無効化、トークンの有効化、トークンの削除も行えます。

ドキュメント

開発者APIドキュメント: https://doc.vuls.biz/ image.png

各APIのmodelをクリックすると、データモデルが確認できます。

APIメソッド

HTTPメソッド URL 説明 必要な権限
GET /health health 読み込み
GET /v1/cve/{cveID} cve詳細 読み込み
GET /v1/cves cve一覧 読み込み
POST /v1/pkgCpe/cpe cpe追加 更新
DELETE /v1/pkgCpe/cpe cpe削除 更新
GET /v1/pkgCpe/cpe/{cpeID} cpe詳細 読み込み
GET /v1/pkgCpe/pkg/{pkgID} package詳細 読み込み
GET /v1/pkgCpes ソフトウェア一覧 読み込み
GET /v1/role/{roleID} ロール詳細 読み込み
PUT /v1/role/{roleID} ロール更新 更新
DELETE /v1/role/{roleID} ロール削除 更新
GET /v1/roles ロール一覧 読み込み
GET /v1/server/uuid/{serverUuid} UUIDを使ったサーバ詳細 読み込み
GET /v1/server/{serverID} サーバ詳細 読み込み
PUT /v1/server/{serverID} サーバ更新 更新
DELETE /v1/server/{serverID} サーバ削除 更新
GET /v1/servers サーバ一覧 読み込み
GET /v1/task/{taskID} タスク詳細 読み込み
PUT /v1/task/{taskID} タスク更新 更新
POST /v1/task/{taskID}/comment タスクコメント追加 更新
PUT /v1/task/{taskID}/ignore タスク非表示設定 更新
GET /v1/tasks タスク一覧 読み込み

12/17現在 各メソッドで取得できる値に関してはドキュメントを参照ください。

開発者APIサンプル

curlを使って開発者APIにアクセスする方法を紹介します。

脆弱性一覧

xxxxxxxxxxxxxにはトークンが入ります。

curl -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/cves'

{"paging":{"totalPage":8,"offset":0,"page":1,"limit":20,"totalCount":158},"cves":[{"cveID":"CVE-2016-3191","scoreV2s":{"jvn":7.5,"nvd":7.5},"scoreV3s":{"nvd":9.8},"vectorV2s":
...
...

サーバ一覧

curl -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/servers'

{"paging":{"totalPage":1,"offset":0,"page":1,"limit":20,"totalCount":2},"servers":[{"id":21384,"serverUuid":"","hostUuid":"","serverName":"ip-192-168-0-188","serverIpv4":"192.168.0.188","platformName":"aws","platformInstanceId":"","serverroleId":1522,"serverroleName":"default","osFamily":"amazon","osVersion":"2017.03","needKernelRestart":false,"lastScannedAt":"2018-12-17T00:05:22.376924Z","lastUploadedAt":"2018-12-17T00:05:28.254655Z","tags":[{"id":363,"name":"tag1"}],"successScanCount":12,"createdAt":"2018-11-22T07:16:35.665921Z","updatedAt":"2018-12-17T00:05:28.289345Z"},{"id":23772,"serverUuid":"","hostUuid":"","serverName":"dummy-server","serverIpv4":"","platformName":"","platformInstanceId":"","serverroleId":1522,"serverroleName":"default","osFamily":"pseudo","osVersion":"unknown","needKernelRestart":false,"lastScannedAt":"2018-12-16T22:06:16.629504Z","lastUploadedAt":"2018-12-16T22:08:52.065021Z","successScanCount":14,"createdAt":"2018-12-03T07:34:01.676822Z","updatedAt":"2018-12-16T22:08:52.071344Z"}]}

各種一覧には、フィルタも用意されているため、フィルタを利用してアクセスすることも可能です。

タスク一覧(すべてのタスク取得)

curl -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?filterStatus=new&&filterStatus=investigating&&filterStatus=ongoing&&filterStatus=workaround&&filterStatus=patch_applied'

{"paging":{"totalPage":8,"offset":0,"page":1,"limit":20,"totalCount":157},"tasks":[{"id":1331193,"cveID":"CVE-2014-9402","serverID":21384,"serverUuid":"","serverName":"ip-192-168-0-188","serverTags":["tag1"],"osFamily":"amazon","osVersion":"2017.03","roleID":1522,"roleName":"default","hasExploit":false,"hasMitigation":false,"hasWorkaround":false,"pkgCpeNames":["glibc","glibc-common","glibc-devel","glibc-headers"],"pkgNotFixedYet":false,"applyingPatchOn":"1970-01-01T00:00:00Z","status":"new","priority":"none","ignore":false,"detectionTools":[{"name":"vuls"}],"advisoryIDs":["ALAS-2018-1017"],"createdAt":"2018-11-22T07:16:39.677041Z","updatedAt":"2018-12-17T00:05:28.289345Z"},{"id":1331194,"cveID":"CVE-2015-5180","serverID":21384,"serverUuid":"","serverName":"ip-192-168-0-188","serverTags":["tag1"],"osFamily":"amazon","osVersion":"2017.03","roleID":1522,"
...
...

タスク一覧はデフォルトで、workaroundとpatch_appliedが除外されています。すべてのタスクを取得するには、上記のように、filterStatusで全てのステータスを指定する必要があります。

開発者APIの注意点

  • 一覧データの一度で取得できる最大件数は1000件
  • ソフトウェア一覧や、タスク一覧などのデータが多い物に関してはフィルタを使用して、アクセスすると、少ない取得時間で取得可能
  • デフォルトが指定されているものもあるので、ドキュメントでデフォルトを確認する
  • 配列指定するものは、同じキーを複数 && で繋いでいく。 (ex. filterStatus=new&&filterStatus=investigating )

SDK

FutureVulsではgolangのSDKを用意しています。 利用用途次第でこちらも参照ください。