FutureVuls API

FutureVuls APIについて

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

「APIドキュメント」からAPIの詳細を確認できます。

FutureVuls APIの概略は以下のようになっています。

  • 日々の運用を便利にするツールを開発可能
  • ドキュメントでREST APIの出力のモデルを確認可能
  • APIトークンを作成することでFutureVuls APIからデータ取得可能
  • APIトークンには、権限が設定可能
  • APIトークンは、作成、編集、削除、再作成、有効化、無効化が可能
  • AuthorizationにAPIトークンを指定してAPIアクセスする
  • 配列のオプションは、複数指定する

image

FutureVuls APIのトークン管理

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

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

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

FutureVuls APIのトークン作成

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

image

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

  • グループトークンの場合
    • API権限
      • 読み込み、更新、グループ設定
      • 読み込み、更新
      • 読み込み
      • なし
    • スキャン権限
  • グループセットトークンの場合
    • API権限
      • 読み込み
      • 読み込み、更新
  • オーガニゼーショントークンの場合
    • API権限
      • 読み込み
      • 読み込み、更新
      • 読み込み、更新、オーガニゼーション設定

トークン編集

編集アイコンからAPIトークン名、API権限、スキャン権限を編集できます。

image

トークン再生成

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

APIトークン再生成

トークン削除

削除アイコンからAPIトークンを削除します。

image

トークンの無効化

ステータス列の 有効 をクリックすると該当のAPIトークンを無効化します。

image

トークンの有効化

ステータス列の 無効 をクリックすると該当のAPIトークンを有効化します。

image

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ファイル詳細 読み込み lockファイルIDの取得方法
POST /v1/lockfile Lockファイル追加 更新 Lockファイル追加
POST /v1/lockfile/sbom SBOMファイル追加 更新
PUT /v1/lockfile/{lockfileID} Lockファイル更新 更新 lockファイルIDの取得方法
DELETE /v1/lockfile/{lockfileID} Lockファイル削除 更新 lockファイルIDの取得方法
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/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の取得方法
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 タスク一覧 読み込み オプションあり

グループセット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/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トークンを使用する必要があります。

HTTPメソッド URL 説明 必要な権限 備考
GET /v1/org/groups グループ一覧 読み込み
GET /v1/org/groupsets グループセット一覧 読み込み
GET /v1/org/members メンバ一覧 読み込み
POST /v1/org/group グループ作成 オーガニゼーション設定
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 を参照する。

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

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

パラメータ タイプ デフォルト値 説明
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の場合に非表示にしたもののみ、falseの場合全件表示)
filterMainUserIDs array[integer] - 指定したuserIDのユーザが主担当であるタスクのみ取得
filterSubUserIDs array[integer] - 指定したuserIDのユーザが副担当であるタスクのみ取得

例えば、グループに登録されているサーバ一覧を取得する場合を考えます。 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 であるタスク一覧を取得できます。

FutureVuls APIサンプル

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

脆弱性一覧

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

$ curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/cves' | jq
{
    "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 -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/servers' | jq
{
    "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"
        }
    ]
}

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

ペーストサーバ作成

サンプルコマンド

# Ubuntuのサーバを登録する
$ curl -s -X POST 'https://rest.vuls.biz/v1/server/paste' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization:xxxxxxxxxxxxx' \
  -d '{
    "serverName":"vuls-paste-server-ubuntu",
    "osFamily":"ubuntu",
    "kernelRelease":"5.15.133.1",
    "osVersion":"22.04",
    "pkgPasteText":"hostname,ii ,3.23ubuntu2,,3.23ubuntu2\n dpkg,ii ,1.21.1ubuntu2.3,,1.21.1ubuntu2.3\n grep,ii ,3.7-1build1,,3.7-1build1"
  }'

# Windowsのサーバを登録する
$ curl -s -X POST 'https://rest.vuls.biz/v1/server/paste' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization:xxxxxxxxxxxxx' \
  -d '{
    "serverName":"vuls-paste-server-windows",
    "osFamily":"windows",
    "osVersion": "",
    "kernelRelease": "Windows Server 2022",
    "kernelVersion":"10.0.19045.4412",
    "pkgPasteText":"KB5036608,KB5012170,KB5015684,KB5037768,KB5014032,KB5020372",
    "windowsPkgPasteText":"Name         :Docker Desktop\nVersion      : 4.25.1\nProviderName : Programs\nName         : Everything 1.4.1.1022 (x64)\nVersion      : 1.4.1.1022\nProviderName : Programs\nName         : Git\nVersion      : 2.37.0\nProviderName : Programs"
  }'

ペースト登録

パラメータ タイプ Required
serverName 登録するサーバの名前 yes
osFamily OSの種類 yes
osVersion 以下詳細 yes
kernelRelease 以下詳細 yes
kernelVersion 以下詳細
pkgPasteText 以下詳細
windowsPkgPasteText Windowsのみ

Windows

Info Command
serverName 登録するサーバの名前
osFamily windows
osVersion “"（空文字を指定する）
kernelRelease （Edition から選択して入力する）
kernelVersion $CurrentVersion = (Get-ItemProperty -Path “Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion”); @($CurrentVersion.CurrentMajorVersionNumber, $CurrentVersion.CurrentMinorVersionNumber, $CurrentVersion.CurrentBuildNumber, $CurrentVersion.UBR) -join ‘.’
pkgPasteText (Get-Hotfix | Select-Object -Property HotFixID | % { If ($_ -match '(KB\d{6,7})') { $Matches[0] }}) -Join ','
windowsPkgPasteText Get-Package | Format-List -Property Name, Version, ProviderName

■ Edition（クリックで表示/非表示）
name
Windows 10 for 32-bit Systems
Windows 10 for x64-based Systems
Windows 10 Version 1511 for 32-bit Systems
Windows 10 Version 1511 for x64-based Systems
Windows 10 Version 1607 for 32-bit Systems
Windows 10 Version 1607 for HoloLens
Windows 10 Version 1607 for x64-based Systems
Windows 10 Version 1703 for 32-bit Systems
Windows 10 Version 1703 for x64-based Systems
Windows 10 Version 1709 for 32-bit Systems
Windows 10 Version 1709 for ARM64-based Systems
Windows 10 Version 1709 for x64-based Systems
Windows 10 Version 1803 for 32-bit Systems
Windows 10 Version 1803 for ARM64-based Systems
Windows 10 Version 1803 for x64-based Systems
Windows 10 Version 1809 for 32-bit Systems
Windows 10 Version 1809 for ARM64-based Systems
Windows 10 Version 1809 for HoloLens
Windows 10 Version 1809 for x64-based Systems
Windows 10 Version 1903 for 32-bit Systems
Windows 10 Version 1903 for ARM64-based Systems
Windows 10 Version 1903 for HoloLens
Windows 10 Version 1903 for x64-based Systems
Windows 10 Version 1909 for 32-bit Systems
Windows 10 Version 1909 for ARM64-based Systems
Windows 10 Version 1909 for x64-based Systems
Windows 10 Version 2004 for 32-bit Systems
Windows 10 Version 2004 for ARM64-based Systems
Windows 10 Version 2004 for HoloLens
Windows 10 Version 2004 for x64-based Systems
Windows 10 Version 20H2 for 32-bit Systems
Windows 10 Version 20H2 for ARM64-based Systems
Windows 10 Version 20H2 for x64-based Systems
Windows 10 Version 21H1 for 32-bit Systems
Windows 10 Version 21H1 for ARM64-based Systems
Windows 10 Version 21H1 for x64-based Systems
Windows 10 Version 21H2 for 32-bit Systems
Windows 10 Version 21H2 for ARM64-based Systems
Windows 10 Version 21H2 for x64-based Systems
Windows 10 Version 22H2 for 32-bit Systems
Windows 10 Version 22H2 for ARM64-based Systems
Windows 10 Version 22H2 for x64-based Systems
Windows 11 Version 21H2 for ARM64-based Systems
Windows 11 Version 21H2 for x64-based Systems
Windows 11 Version 22H2 for ARM64-based Systems
Windows 11 Version 22H2 for x64-based Systems
Windows 11 Version 23H2 for ARM64-based Systems
Windows 11 Version 23H2 for x64-based Systems
Windows Server 2016
Windows Server 2016 for x64-based Systems
Windows Server 2016 for x64-based Systems (Server Core installation)
Windows Server 2016 (Server Core installation)
Windows Server 2019
Windows Server 2019 (Server Core installation)
Windows Server 2022
Windows Server 2022, 23H2 Edition (Server Core installation)
Windows Server 2022 (Server Core installation)

CentOS

Info Command
serverName 登録するサーバの名前
osFamily centos
osVersion awk ‘{print $4}’ /etc/redhat-release
kernelRelease uname -r
kernelVersion cat /etc/redhat-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

Red Hat Enterprise Linux

Info Command
serverName 登録するサーバの名前
osFamily redhat
osVersion awk ‘{print $7}’ /etc/redhat-release
kernelRelease uname -r
kernelVersion cat /etc/redhat-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

Amazon

Info Command
serverName 登録するサーバの名前
osFamily amazon
osVersion awk ‘{if ($0 ~ /Amazon\ Linux\ release\ 2/) printf("%s %s”,$4, $5); else if ($0 ~ /Amazon\ Linux\ 2/) for (i=3; i<=NF; i++) printf("%s “, $i); else if (NF==5) print $5}’ /etc/system-release
kernelRelease uname -r
kernelVersion awk '{if ($0 ~ /Amazon Linux release (2022|2023)/) print $4; else if ($0 ~ /Amazon Linux release 2/) printf("%s %s\n”,$4, $5); else if ($0 ~ /Amazon Linux 2/) for (i=3; i<=NF; i++) printf("%s “, $i); else if (NF==5) print $5}' /etc/system-release’
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"
pkgPasteText
if version is 2		 repoquery --all --pkgnarrow=installed --qf="%{NAME} %{EPOCH} %{VERSION} %{RELEASE} %{ARCH} %{UI_FROM_REPO}"

Debian

Info Command
serverName 登録するサーバの名前
osFamily debian
osVersion cat /etc/debian_version
kernelRelease uname -r
kernelVersion uname -a | awk '{print $7}'
pkgPasteText dpkg-query -W -f="\${binary:Package},\${db:Status-Abbrev},\${Version},\${source:Package},\${source:Version}\n"

Ubuntu

Info Command
serverName 登録するサーバの名前
osFamily ubuntu
osVersion lsb_release -sr
kernelRelease uname -r
kernelVersion lsb_release -sr | awk '{print $1}'
pkgPasteText dpkg-query -W -f="\${binary:Package},\${db:Status-Abbrev},\${Version},\${source:Package},\${source:Version}\n"

Fedora

Info Command
serverName 登録するサーバの名前
osFamily fedra
osVersion lsb_release -sr
kernelRelease uname -r
kernelVersion cat /etc/fedora-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

Alma

Info Command
serverName 登録するサーバの名前
osFamily alma
osVersion lsb_release -sr
kernelRelease uname -r
kernelVersion cat /etc/redhat-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

Rocky

Info Command
serverName 登録するサーバの名前
osFamily rocky
osVersion lsb_release -sr
kernelRelease uname -r
kernelVersion cat /etc/redhat-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

OpenSUSE、SLES、SLED

Info Command
serverName 登録するサーバの名前
osFamily opensuse
opensuse.leap
suse.linux.enterprise.server
suse.linux.enterprise.desktop
osVersion lsb_release -sr
kernelRelease uname -r
kernelVersion grep -oP '(?<=VERSION_ID=”).+(?=")' /etc/os-release
pkgPasteText rpm -qa --queryformat "%{NAME} %{EPOCHNUM} %{VERSION} %{RELEASE} %{ARCH}\n"

Lockファイル追加

パラメータ 説明 備考
serverID Lockファイルを追加するサーバのID serverIDの取得方法
path Lockファイルのパスとファイル名 サポートされているLockファイル
fileContent Lockファイルの内容 
curl -s -X POST -H 'Content-Type: application/json' -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/lockfile' -d '{ "serverID": 192730, "path": "/REST_API/go.sum", "fileContent": "github.com/apache/thrift v0.12.0/go.mod h1:cp2SuWMxlEZw2r+iP2GNCdIi4C1qmUzdZFSVb+bacwQ=\n github.com/go-gitea/gitea v1.2.3 h1:L0SC8kIr3+UnxNAte9M9bmdQ8Bdrc6I5b4Zuz/T+NCw=\n github.com/go-gitea/gitea v1.2.3/go.mod h1:g8iUbfFNyuJp8u7GsSggxI8NQyuxeGTyqxogl3imbQM=\n github.com/gorilla/websocket v1.4.0/go.mod h1:E7qHFY5m1UJ88s3WnNqhKjPHQ0heANvMoAMk2YaljkQ=\n github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0=\n golang.org/x/crypto v0.0.0-20180820150726-614d502a4dac/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=\n golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=\n golang.org/x/crypto v0.0.0-20190122013713-64072686203f/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=\n golang.org/x/crypto v0.0.0-20190219172222-a4c6cb3142f2/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=\n golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 h1:VklqNMn3ovrHsnt90PveolxSbWFaJdECFbxSq0Mqo2M=\n golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=\n golang.org/x/crypto v0.0.0-20190320223903-b7391e95e576/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=\n golang.org/x/crypto v0.0.0-20190325154230-a5d413f7728c/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=\n golang.org/x/crypto v0.0.0-20190510104115-cbcb75029529/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20190605123033-f99c8df09eb5/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20190611184440-5c40567a22f8/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20190617133340-57b3e21c3d56/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20190701094942-4def268fd1a4/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20190927123631-a832865fa7ad/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\n golang.org/x/crypto v0.0.0-20191119213627-4f8c1d86b1ba h1:9bFeDpN3gTqNanMVqNcoR/pJQuP5uroC3t1D7eXozTE=\n golang.org/x/crypto v0.0.0-20191119213627-4f8c1d86b1ba/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=\n gopkg.in/yaml.v2 v2.0.0-20170812160011-eb3733d160e7/go.mod h1:JAlM8MvJe8wmxCU4Bli9HhUf9+ttbYbLASfIpnQbh74=\n gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=\n gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=\n gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=\n"}'

タスク一覧を取得する

$ curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?filterStatus=new&&filterStatus=investigating&&filterStatus=ongoing&&filterStatus=workaround&&filterStatus=patch_applied' | jq
{
    "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,"
...
...

タスクの作成された日（初回検知日時）でフィルタする

  • 日付フィルタなしの場合
curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?limit=1000'
  • 日本時間の 2024年5月17日「以降」 に作成されたタスクを取得したい
curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?limit=1000&filterNewedAtAfter=2024-05-16T15:00:00Z'

# ex. タスク数をカウントしたい場合
curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?limit=1000&filterNewedAtAfter=2024-05-16T15:00:00Z' | jq .tasks[].newedAt | wc -l
  • 日本時間の 2024年5月17日「以前」 に作成されたタスクを取得したい
curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?filterNewedAtBefore=2024-05-16T15:00:00Z'
  • 日本時間の 2024年5月17日から2024年5月23日の間 に作成されたタスクを取得したい
curl -s -H 'accept: application/json' -H 'Authorization:xxxxxxxxxxxxx' 'https://rest.vuls.biz/v1/tasks?limit=1000&filterNewedAtAfter=2024-05-16T00:00:00Z&filterNewedAtBefore=2024-05-22T15:00:00Z'

FutureVuls APIの注意点

  • ソフトウェア一覧や、タスク一覧などのデータが多い物に関しては、フィルタを使用してアクセスすると短時間で取得可能です
  • パラメータのデフォルト値が設定されているAPIがあります
    • ドキュメント（Future Vuls Public API）でデフォルト値の確認をお願いします
    • ex. /v1/tasks の場合
      • filterStatus のデフォルト値は「Default value : List [ “new”, “investigating”, “ongoing” ]」となります
  • パラメータを配列指定するものは、同じキーを複数 && で繋いでください (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 で実行してください