Skip to content

FutureVuls API#

FutureVuls provides a REST API for developing external applications. You can use the API to retrieve data from FutureVuls.

Refer to the "API Documentation" for details on the API. You can check the API parameters and response types.

To access the FutureVuls API, specify an API token in the Authorization header. API tokens can be viewed, created, edited, deleted, regenerated, and enabled/disabled on the settings screen for Groups, Group Sets, and Organizations. API tokens can also be assigned different permission levels.

Note on Using the API Documentation

Please be aware that the feature on the "FutureVuls API Documentation" page that allows you to try out APIs directly from the browser is currently not working.

image

FutureVuls API Token Management#

FutureVuls API tokens are managed on the "Token" page within the Group, Group Set, and Organization settings.

image

Here, you can manage tokens for Scanners and the FutureVuls API. Only users with the following permissions can access this screen (Reference: User Permissions):

Token Type Required Permission
Group Group Admin
Group Set Groupset Admin
Organization Organization Permission (Owner, CSIRT)

Creating a FutureVuls API Token#

You can add an API token by clicking Add a new token. Create the token by setting its name and permissions.

image

The permissions that can be set are as follows:

Token Type API Permission Scan Permission
Group Token ・Read, Update, Group Settings
・Read, Update
・Read Only
・None		 Yes/No
Group Set Token ・Read, Update
・Read Only		 ー
Organization Token ・Read, Update, Organization Settings
・Read, Update
・Read Only		 ー

Updating a Token#

Created tokens can be edited, regenerated, deleted, and enabled/disabled from the list.

Action Description
Edit You can edit the API token name, API Permission, and Scan Permission.
Regenerate You can regenerate the API token hash. This action cannot be undone, so please proceed with caution.
Delete Deletes the API token. Using a deleted token will result in an authentication failure.
Enable/Disable You can toggle the token's status using the toggle switch in the status column.
Using a disabled token will result in an authentication failure.

How to Use the FutureVuls API#

Make an HTTP request to https://rest.vuls.biz using a URL path from the API Method List.

For APIs that return multiple items in the response, such as the task list API, the data is sorted in ascending order by ID. In the FutureVuls API Documentation, you can check the request/response data models for each API by clicking on "Model".

image.png

Example: To retrieve all vulnerability information for Server ID=1#

Please also refer to the "API Samples" page for specific examples of how to use the 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} is a Group API, so specify the group's token in the header.
  • To filter results for a specific server, specify filterServerID in the format ?filterServerID=1.
  • To limit the number of items retrieved per request, specify page and limit.

For detailed endpoint specifications, please check the relevant section of the documentation.

Notes on Using the FutureVuls API#

  • For large datasets like software lists or task lists, using filters can speed up retrieval.
  • Some APIs have default parameter values. Please check the documentation (FutureVuls Public API) for these default values.
  • For parameters that accept an array, join multiple instances of the same key with & (e.g., filterStatus=new&filterStatus=investigating).

How to Specify Array Parameters#

When specifying multiple array-type parameters in the API, you need to specify the same key multiple times, joined with &.

Example 1: Specifying multiple statuses when retrieving a task list

https://rest.vuls.biz/v1/tasks?filterStatus=new&filterStatus=investigating&filterStatus=ongoing

Example 2: Specifying multiple task IDs and comment types when batch retrieving task comments

https://rest.vuls.biz/v1/taskComments?taskIDs=1&taskIDs=2&taskIDs=3&commentTypes=user&commentTypes=api

Example 3: Specifying multiple CVE IDs when retrieving group set vulnerability information

https://rest.vuls.biz/v1/groupSet/cveVulnInfos?cveIDs=CVE-2023-1234&cveIDs=CVE-2023-5678

For more details, please also refer to "API Samples".

Pagination#

The FutureVuls API uses pagination to support large amounts of data. The maximum number of list items that can be retrieved at once (limit) is 1000, and you can retrieve all items by incrementing the page number (page). (Reference: Optional Parameters)

When you need to retrieve all items, please set the pagination parameters appropriately.

  • If the limit value is not specified, a default value of limit=20 is set, and a maximum of 20 items will be retrieved.
  • By reducing the limit value, you can shorten the execution time of a single API call (and increase the number of requests using page).
  • Setting limit higher than the total number of items is fine (only items up to the total count will be retrieved).

Example 1) You want to retrieve all 80 items (<1000) in a list.

  • Execute with ?limit=1000 or similar.

Example 2) You want to retrieve all 1500 items (>1000) in a list.

  1. First, execute with ?page=1&limit=1000.
  2. Next, execute with ?page=2&limit=1000.

API Method List#

APIs are divided into three types based on their token type. Each type provides different methods, so please check the manual for details.

API Server Health Check#

HTTP Method URL Description Required Permission
GET /health health None

Group API List#

To use the Group API, you must use a group-specific API token issued for each group.

Token Type

Tokens issued in Organization settings and Group Set settings cannot be used with the Group API.

HTTP Method URL Description Required Permission Remarks
GET /v1/cve/{cveID} CVE Detail Read How to get cveID
GET /v1/cves CVE List Read With Options
GET /v1/lockfiles Lockfile List Read With Options
GET /v1/lockfile/{lockfileID} Lockfile Detail Read How to get lockfileID
POST /v1/lockfile Add Lockfile Update Add Lockfile
PUT /v1/lockfile/{lockfileID} Update Lockfile Update How to get lockfileID
DELETE /v1/lockfile/{lockfileID} Delete Lockfile Update How to get lockfileID
POST /v1/pkgCpe/cpe Add CPE Update
DELETE /v1/pkgCpe/cpe/{cpeID} Delete CPE Update How to get cpeID
DELETE /v1/pkgCpe/cpe [DEPRECATED] Delete CPE Update How to get cpeID
GET /v1/pkgCpe/cpe/{cpeID} CPE Detail Read How to get cpeID
GET /v1/pkgCpe/pkg/{pkgID} Package Detail Read How to get pkgID
GET /v1/pkgCpe/windowsPkg/{windowsPkgID} WindowsPkg Detail Read How to get windowsPkgID
GET /v1/pkgCpes Package & CPE List Read With Options
GET /v1/role/{roleID} Role Detail Read How to get roleID
PUT /v1/role/{roleID} Update Role Update How to get roleID
DELETE /v1/role/{roleID} Delete Role Update How to get roleID
GET /v1/roles Role List Read With Options
POST /v1/server/pseudo Create Pseudo Server Update
POST /v1/server/paste Create Paste Server Update
POST /v1/server/sbom Import SBOM Update
GET /v1/server/{serverID}/sbom Download Server's SBOM Read How to get serverID
API Usage Example
PUT /v1/server/paste/{serverID} Update Paste Server Update How to get serverID
GET /v1/server/uuid/{serverUuid} Server Detail by UUID Read How to get UUID
POST /v1/server/scan/{serverID} Scan Server Update How to get serverID
GET /v1/server/{serverID} Server Detail Read How to get serverID
PUT /v1/server/{serverID} Update Server Update How to get serverID
DELETE /v1/server/{serverID} Delete Server Update How to get serverID
POST /v1/server/{serverID}/tag Add Server Tag Update How to get serverID
DELETE /v1/server/{serverID}/tag Delete Server Tag Update How to get serverID
GET /v1/servers Server List Read With Options
GET /v1/task/{taskID} Task Detail Read How to get taskID
PUT /v1/task/{taskID} Update Task Update How to get taskID
PUT /v1/tasks Bulk Update Tasks Update Bulk update status/priority for up to 1,000 task IDs
POST /v1/task/{taskID}/comment Add Task Comment Update How to get taskID
GET /v1/taskComments Batch Get Task Comments Read With Options
How to specify multiple Task IDs or comment types
PUT /v1/task/{taskID}/ignore Set Task to Ignore Update How to get taskID
GET /v1/tasks Task List Read With Options
GET /v1/members Member List Read With Options
GET /v1/scanImports External Scan Result List Read With Options
GET /v1/scanImport/{scanImportID} External Scan Detail Read How to get scanImportID
POST /v1/scanImport Add External Scan Result Update
PUT /v1/scanImport/{scanImportID} Update External Scan Result Update
DELETE /v1/scanImport/{scanImportID} Delete External Scan Result Update
GET /v1/sbom/{sbomID} Get SBOM Detail Read
GET /v1/sboms Get SBOM List Read
POST /v1/sbom Add SBOM Update
PUT /v1/sbom/{sbomID} Update SBOM Update
DELETE /v1/sbom/{sbomID} Delete SBOM Update

Group Set API List#

To use the Group Set API, you must use a group set-specific API token issued for each group set.

Token Type

Tokens issued in Organization settings and Group settings cannot be used with the Group Set API.

HTTP Method URL Description Required Permission Remarks
GET /v1/groupSet/cve/{cveID} CVE Detail Read How to get cveID
GET /v1/groupSet/cves CVE List Read With Options
GET /v1/groupSet/cveVulnInfos List of CVE Vulnerability Information Read With Options
How to specify multiple CVE IDs
GET /v1/groupSet/pkgCpe/cpe/{cpeID} CPE Detail Read How to get cpeID
GET /v1/groupSet/pkgCpe/pkg/{pkgID} Package Detail Read How to get pkgID
GET /v1/groupSet/pkgCpe/windowsPkg/{windowsPkgID} WindowsPkg Detail Read How to get windowsPkgID
GET /v1/groupSet/pkgCpes Package & CPE List Read With Options
GET /v1/groupSet/deletedPkgCpes Deleted Software List Read With Options
API Sample
GET /v1/groupSet/server/uuid/{serverUuid} Server Detail by UUID Read How to get UUID
GET /v1/groupSet/server/{serverID} Server Detail Read How to get serverID
GET /v1/groupSet/servers Server List Read With Options
GET /v1/groupSet/task/{taskID} Task Detail Read How to get taskID
GET /v1/groupSet/tasks Task List Read With Options

Organization API List#

To use the Organization API, you must use an organization-specific API token issued in the organization settings.

Token Type

Tokens issued in Group Set settings and Group settings cannot be used with the Organization API.

Note on Token Management

The Organization token can be used to retrieve the "Group List, Group Set List, Member List" within the organization. The API response includes "personal information such as members' names and email addresses." Please manage the token with extreme care.

Also, future releases are expected to add organization-wide settings, including those listed below. Please be careful with the handling of the organization token.

  • Actions available from organization settings (e.g., adding external users).
  • The ability to call APIs across all group sets and groups in the organization.
HTTP Method URL Description Required Permission Remarks
GET /v1/org/groups Group List Read
GET /v1/org/groupsets Group Set List Read
GET /v1/org/members Member List Read
GET /v1/org/auditLogs Audit Log List Read
POST /v1/org/group Create Group Organization Settings
PUT /v1/org/group/{groupID} Update Group Settings Organization Settings
POST /v1/org/users Add User to Group/Group Set Organization Settings
GET /v1/org/privateEndoflifeDates Private EOL Information List Read API Sample
POST /v1/org/privateEndoflifeDate Register Private EOL Information Organization Settings API Sample
PUT /v1/org/privateEndoflifeDate/{privateEndoflifeDateID} Update Private EOL Information Organization Settings API Sample
DELETE /v1/org/privateEndoflifeDate/{privateEndoflifeDateID} Delete Private EOL Information Organization Settings API Sample

How to Get Parameters for API Calls#

When using the FutureVuls API, you may need to specify parameters such as cveID or cpeID. This section explains how to obtain these parameters.

How to get cveID#

You can obtain it in one of the following two ways:

  • Open the Vulnerabilities tab and refer to the CVE ID column for the desired vulnerability.
  • Retrieve it via a REST API request.
    • For the Group API:
      • Execute a GET request to https://rest.vuls.biz/v1/cves to get the vulnerability list. In the response JSON, refer to the cveID of the desired vulnerability within the cves data.
    • For the Group Set API:
      • Execute a GET request to https://rest.vuls.biz/v1/groupSet/cves to get the vulnerability list. In the response JSON, refer to the cveID of the desired vulnerability within the cves data.

image

How to get cpeID#

You can obtain it using the following method:

  • When using the Group API:
    • Execute a GET request to https://rest.vuls.biz/v1/pkgCpes to get the package & cpe list. In the response JSON, refer to the cpeID of the desired CPE within the pkgCpes data.
  • When using the Group Set API:
    • Execute a GET request to https://rest.vuls.biz/v1/groupSet/pkgCpes to get the package & cpe list. In the response JSON, refer to the cpeID of the desired CPE within the pkgCpes data.

How to get pkgID#

You can obtain it using the following method:

  • When using the Group API:
    • Execute a GET request to https://rest.vuls.biz/v1/pkgCpes to get the package & cpe list. In the response JSON, refer to the pkgID of the desired package within the pkgCpes data.
  • When using the Group Set API:
    • Execute a GET request to https://rest.vuls.biz/v1/groupSet/pkgCpes to get the package & cpe list. In the response JSON, refer to the pkgID of the desired package within the pkgCpes data.

How to get UUID#

You can obtain it in one of the following two ways:

  • Open the Servers tab and refer to the Server UUID column for the desired server. (The Server UUID column can be displayed from "Edit displayed items").
  • Retrieve it via a REST API request.
    • For the Group API:
      • Execute a GET request to https://rest.vuls.biz/v1/servers to get the server list. In the response JSON, refer to the serverUuid of the desired server within the servers data.
    • For the Group Set API:
      • Execute a GET request to https://rest.vuls.biz/v1/groupSet/servers to get the server list. In the response JSON, refer to the serverUuid of the desired server within the servers data.

How to get serverID#

You can obtain it in one of the following two ways:

  • Open the Servers tab and refer to the Server ID column for the desired server. (The Server ID column can be displayed from "Edit displayed items").
  • Retrieve it via a REST API request.
    • For the Group API:
      • Execute a GET request to https://rest.vuls.biz/v1/servers to get the server list. In the response JSON, refer to the id of the desired server within the servers data.
    • For the Group Set API:
      • Execute a GET request to https://rest.vuls.biz/v1/groupSet/servers to get the server list. In the response JSON, refer to the id of the desired server within the servers data.

How to get taskID#

You can obtain it in one of the following two ways:

  • Open the Tasks tab and refer to the Task ID column for the desired task. (The Task ID column can be displayed from "Edit displayed items").
  • Retrieve it via a REST API request.
    • For the Group API:
      • Execute a GET request to https://rest.vuls.biz/v1/tasks to get the task list. In the response JSON, refer to the id of the desired task within the tasks data.
    • For the Group Set API:
      • Execute a GET request to https://rest.vuls.biz/v1/groupSet/tasks to get the task list. In the response JSON, refer to the id of the desired task within the tasks data.

How to get roleID#

You can obtain it using the following method:

  • Open the Roles tab and refer to the Role ID column for the desired role. (The Role ID column can be displayed from "Edit displayed items").
  • Retrieve it via a REST API request.
    • Execute a GET request to https://rest.vuls.biz/v1/roles to get the role list. In the response JSON, refer to the id of the desired role within the roles data.

How to get lockfileID#

You can obtain it using the following method:

  • Open the Servers tab and select the server where the desired Lockfile exists. From the Applications tab, select the desired Lockfile and refer to the value after the #. image
  • Retrieve it via a REST API request.
    • Execute a GET request to https://rest.vuls.biz/v1/lockfiles to get the Lockfile list. In the response JSON, refer to the id of the desired Lockfile within the lockfiles data.

How to get windowsPkgID#

You can obtain it using the following method:

  • Open the Servers tab and select the server where the desired package exists. Open the Software tab and refer to the ID column.
  • Open the Servers tab and select the server where the desired package exists. From the Software tab, select the desired package and refer to the value after the # in the displayed windowsPkg.

image

How to get scanImportID#

You can obtain it using the following method:

  • Retrieve it via a REST API request
    • Execute a GET request to https://rest.vuls.biz/v1/scanImports to get the scan result list. In the response JSON, refer to the id of the desired scan result within the scanImports data.

Optional Parameters#

Depending on the API, the following options can be specified when retrieving data. Please refer to the FutureVuls API Documentation for the options available for each API.

When specifying array parameters

If you are specifying an array parameter, you need to specify it multiple times.

For example, if you want to filter tasks with a status of either "new" or "investigating" using the task list retrieval API, you must execute it with a URL like this:

"https://rest.vuls.biz/v1/tasks?filterStatus=new&filterStatus=investigating"
Parameter Type Default Value Description
page integer 1 The page number to retrieve from paginated data.
limit integer 20 The number of items per page for paginated data.
offset integer 0 The number of items to skip before starting pagination.
filterCveID string ー Retrieves only data related to the specified cveID.
filterTaskID integer ー Retrieves only data related to the specified taskID.
filterServerID integer ー Retrieves only data related to the specified serverID.
filterRoleID integer ー Retrieves only data related to the specified roleID.
filterPkgID integer ー Retrieves only data related to the specified pkgID.
filterCpeID integer ー Retrieves only data related to the specified cpeID.
filterStatus array[string] ["new", "investigating", "ongoing"] Retrieves only tasks with the specified statuses.
filterPriority array[string] ー Retrieves only tasks with the specified priorities.
filterIgnore boolean ー true: Retrieves only tasks with the ignore flag OFF.
false: Retrieves all items.
filterMainUserIDs array[integer] ー Retrieves only tasks where the specified user ID is the primary assignee.
filterSubUserIDs array[integer] ー Retrieves only tasks where the specified user ID is a secondary assignee.
filterIsExternalScan boolean ー Retrieves only tasks and vulnerabilities where external scan is enabled.

For example, consider retrieving a list of servers registered in a group. A GET request to https://rest.vuls.biz/v1/servers?page=1&limit=20&offset=5 will retrieve 20 items, excluding the first 5, in serverID order. That is, data from the 6th to the 25th item will be retrieved.

If you use https://rest.vuls.biz/v1/servers?page=2&limit=20&offset=5, data from the 26th to the 45th item will be retrieved. If you do not specify an offset, https://rest.vuls.biz/v1/servers?page=1&limit=20 will retrieve data from the 1st to the 20th item.

Also, executing a GET request to https://rest.vuls.biz/v1/tasks?filterPriority=high&filterPriority=medium will retrieve a list of tasks with a priority of HIGH or MEDIUM.