Developer REST API

About Developer REST API

FutureVuls provides an API for external application development. Developers can use the API to obtain data from FutureVuls.

The Developer API overview is as follows:

• Available for SecOps using code
• Model can be checked in the documentation
• Data can be obtained from the API by creating a token
• Permissions can be set for tokens
• Tokens can be created, edited, deleted, recreated, enabled, and disabled
• API access is specified by Authorization
• Options for arrays can be specified multiple times
• Detailed information can be found in the API documentation

Token Management for Developer API

Tokens for the developer API are managed on the token pages for group settings and group set settings.

Here, tokens for the Scanner and Developer API can be managed.

Only users with group administrator privileges can access group settings, and only users with group set administrator privileges can access group set settings.

Creating Developer API Tokens

You can add a token by selecting Add Token.

Set the name and permissions of the token and create it.

The following permissions can be set:

• For group tokens
  • API permission
    • Read, Update, Group settings
    • Read, Update
    • Read only
    • None
  • Scan permission
• For group set tokens
  • API permission
    • Read only
    • None

Editing Tokens

You can edit the token name, API permission, and scan permission from the edit icon.

Regenerating Tokens

You can regenerate the hash of a token with the regenerate token function. Please confirm before regenerating as it cannot be undone.

Disabling Tokens

Clicking Enable in the status column will disable the corresponding token.

Activate a token

Click on the Disable button in the status column to activate the corresponding token.

Delete a token

Remove a token by clicking on the delete icon.

API Method List

Perform an HTTP request by specifying the following URL to https://rest.vuls.biz.

• API server status check

• Group API list
  • To use the group API, you need to use the API token issued for each group.

• Group Set API list
  • To use the Group Set API, you need to use the API token issued for each Group Set.

• For APIs that return multiple data in the response, such as obtaining a list of tasks, data is obtained in ascending order of ID.

• If you click on the model of each API in the developer API documentation, you can check the response data model.

Obtaining CVE ID

You can obtain CVE ID in either of the following two methods:

• Open the Vulnerability tab and refer to the CVE ID column of the vulnerability for which you want to obtain the ID.
• Use a REST API request.
  • For Group API
    • Make a GET request to https://rest.vuls.biz/v1/cves to obtain a list of vulnerabilities. Refer to the cveID of the vulnerability for which you want to obtain the ID in the data contained in the response JSON cves.
  • For Group Set API
    • Make a GET request to https://rest.vuls.biz/v1/groupSet/cves to obtain a list of vulnerabilities. Refer to the cveID of the vulnerability for which you want to obtain the ID in the data contained in the response JSON cves.

Obtaining CPE ID

You can obtain CPE ID using the following method:

• When using Group API
  • Make a GET request to https://rest.vuls.biz/v1/pkgCpes to obtain a list of package & cpe. Refer to the cpeID of the cpe for which you want to obtain the ID in the data contained in the response JSON pkgCpes.
• When using Group Set API
  • Make a GET request to https://rest.vuls.biz/v1/groupSet/pkgCpes to obtain a list of package & cpe. Refer to the cpeID of the cpe for which you want to obtain the ID in the data contained in the response JSON pkgCpes.

Obtaining pkgID

You can obtain pkgID using the following method:

• When using Group API
  • Make a GET request to https://rest.vuls.biz/v1/pkgCpes to obtain a list of package & cpe. Refer to the pkgID of the package for which you want to obtain the ID in the data contained in the response JSON pkgCpes.
• When using Group Set API
  • Make a GET request to https://rest.vuls.biz/v1/groupSet/pkgCpes to obtain a list of package & cpe. Refer to the pkgID of the package for which you want to obtain the ID in the data contained in the response JSON pkgCpes.

Obtaining UUID

You can obtain UUID in either of the following two methods:

• Open the Server tab and refer to the Server UUID column of the server for which you want to obtain the ID. (The Server UUID column can be displayed by editing the display item.)
• Use a REST API request.
  • For Group API
    • Make a GET request to https://rest.vuls.biz/v1/servers to obtain a list of servers. Refer to the serverUuid of the server for which you want to obtain the ID in the data contained in the response JSON servers.
  • For Group Set API
    • Make a GET request to https://rest.vuls.biz/v1/groupSet/servers to obtain a list of servers. Refer to the serverUuid of the server for which you want to obtain the ID in the data contained in the response JSON servers.

How to get serverID

You can obtain serverID by either of the following two methods.

• Open the server tab and refer to the “serverID” column of the server you want to get the ID of. (The “serverID” column can be displayed by editing the display items.)
• Get it by a REST API request.
  • In the case of a group API:
    • Perform a GET request to https://rest.vuls.biz/v1/servers to get a list of servers. Refer to the “id” of the data contained in “servers” in the response JSON, which is the ID of the server you want to get.
  • In the case of a group set API:
    • Perform a GET request to https://rest.vuls.biz/v1/groupSet/servers to get a list of servers. Refer to the “id” of the data contained in “servers” in the response JSON, which is the ID of the server you want to get.

How to get taskID

You can obtain taskID by either of the following two methods.

• Open the task tab and refer to the “taskID” column of the task you want to get the ID of. (The “taskID” column can be displayed by editing the display items.)
• Get it by a REST API request.
  • In the case of a group API:
    • Perform a GET request to https://rest.vuls.biz/v1/tasks to get a list of tasks. Refer to the “id” of the data contained in “tasks” in the response JSON, which is the ID of the task you want to get.
  • In the case of a group set API:
    • Perform a GET request to https://rest.vuls.biz/v1/groupSet/tasks to get a list of tasks. Refer to the “id” of the data contained in “tasks” in the response JSON, which is the ID of the task you want to get.

How to obtain scanImportID

You can obtain scanImportID by this method.

• Obtain by REST API request
  • Make a GET request to https://rest.vuls.biz/v1/scanImports to get a list of scan results. Refer to the id of the scan result whose ID you want to obtain from the data contained in scanImports in the response JSON.

Optional parameters that can be specified

The FutureVuls REST API adopts a pagination format to support large amounts of data. The following options can be specified when retrieving data with the API.

Refer to the Developer API documentation for the options that can be specified for each API.

For example, if you send a GET request to https://rest.vuls.biz/v1/servers?page=1&limit=20&offset=5 to obtain a list of servers registered in a group, you will get the first 20 items of data separated into 20 items per page, excluding the first 5 items sorted by serverID. In other words, the data from the 6th item to the 25th item will be obtained.

If you send a GET request to https://rest.vuls.biz/v1/servers?page=2&limit=20&offset=5, you will get the data from the 26th item to the 45th item. If you do not specify the offset and send a GET request to https://rest.vuls.biz/v1/servers?page=1&limit=20, you will get the data from the 1st item to the 20th item.

Also, if you send a GET request to https://rest.vuls.biz/v1/tasks?filterPriority=high&&filterPriority=medium, you can obtain a list of tasks with the priority of HIGH or MEDIUM.

Developer API Example

Here is an example of accessing the developer API using curl.

Vulnerability List

Replace xxxxxxxxxxxxx with your own token.

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":
...
...

Server List

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"}]}

Each list also has filters available, so it is possible to access them using filters.

Create a Paste Server

• Check here about paste servers

curl -X POST "https://rest.vuls.biz/v1/server/paste" -H  "accept: application/json" -H  "Authorization: xxxxxxxxxxxxx" -d '{  "serverName": "amazonLinuxPaste", "osFamily": "amazon", "kernelRelease": "4.9.75-25.55.amzn1.x86_64",  "osVersion": "2018.03",  "pkgPasteText": "libgcc48 0 4.8.5 28.142.amzn1 x86_64\n python27-kitchen 0 1.1.1 5.6.amzn1 noarch\n nspr 0 4.21.0 1.43.amzn1 x86_64\n openssl 1 1.0.2k 16.153.amzn1 x86_64\n python27-docutils 0 0.11 1.15.amzn1 noarch\n info 0 5.1 4.10.amzn1 x86_64\n python27 0 2.7.18 2.141.amzn1 x86_64\n python27-iniparse 0 0.3.1 2.1.9.amzn1 noarch\n file-libs 0 5.37 8.49.amzn1 x86_64\n python27-requests 0 1.2.3 5.10.amzn1 noarch\n tcp_wrappers-libs 0 7.6 77.12.amzn1 x86_64\n rubygem20-psych 0 2.0.0 2.39.amzn1 x86_64\n python27-pystache 0 0.5.3 2.8.amzn1 noarch\n lua 0 5.1.4 4.1.9.amzn1 x86_64\n ruby20 0 2.0.0.648 2.39.amzn1 x86_64\n libevent 0 2.0.21 4.19.amzn1 x86_64\n nss 0 3.44.0 7.84.amzn1 x86_64\n libffi 0 3.0.13 16.5.amzn1 x86_64\n python26 0 2.6.9 2.92.amzn1 x86_64\n words 0 3.0 17.8.amzn1 noarch\n perl-macros 4 5.16.3 294.43.amzn1 x86_64\n fontpackages-filesystem 0 1.41 1.1.2.amzn1 noarch\n libedit 0 2.11 4.20080712cvs.1.6.amzn1 x86_64\n procps 0 3.2.8 45.16.amzn1 x86_64\n ncurses-base 0 5.7 4.20090207.14.amzn1 x86_64\n p11-kit-trust 0 0.18.5 2.3.amzn1 x86_64\n nss-tools 0 3.44.0 7.84.amzn1 x86_64\n libselinux 0 2.1.10 3.22.amzn1 x86_64\n perl-Encode 0 2.51 7.5.amzn1 x86_64\n file 0 5.37 8.49.amzn1 x86_64\n bzip2-libs 0 1.0.6 8.12.amzn1 x86_64\n perl-Storable 0 2.45 3.5.amzn1 x86_64\n python27-jinja2 0 2.7.2 3.16.amzn1 noarch\n audit-libs 0 2.6.5 3.28.amzn1 x86_64\n perl-File-Temp 0 0.23.01 3.5.amzn1 noarch\n libtirpc 0 0.2.4 0.16.15.amzn1 x86_64\n shadow-utils 2 4.1.4.2 13.10.amzn1 x86_64\n perl-Digest-MD5 0 2.52 3.5.amzn1 x86_64\n libnghttp2 0 1.33.0 1.1.6.amzn1 x86_64\n cyrus-sasl-lib 0 2.1.23 13.16.amzn1 x86_64\n rsync 0 3.0.6 12.13.amzn1 x86_64\n rpm 0 4.11.3 40.78.amzn1 x86_64\n libidn 0 1.18 2.8.amzn1 x86_64\n pinentry 0 0.7.6 6.11.amzn1 x86_64\n rpm-build-libs 0 4.11.3 40.78.amzn1 x86_64\n libassuan 0 2.0.3 3.3.amzn1 x86_64\n mingetty 0 1.08 5.9.amzn1 x86_64\n system-release 0 2018.03 0.2 noarch\n libsmartcols 0 2.23.2 63.33.amzn1 x86_64\n python27-PyYAML 0 3.10 3.10.amzn1 x86_64\n subversion 0 1.9.7 1.61.amzn1 x86_64\n perl-Pod-Perldoc 0 3.20 4.7.amzn1 noarch\n git-core-doc 0 2.18.5 2.73.amzn1 noarch\n perl-Exporter 0 5.68 3.5.amzn1 noarch\n python27-backports 0 1.0 3.14.amzn1 x86_64\n ntpdate 0 4.2.8p15 1.44.amzn1 x86_64\n perl-threads-shared 0 1.43 6.5.amzn1 x86_64\n newt-python27 0 0.52.11 3.11.amzn1 x86_64\n kernel 0 4.14.225 121.362.amzn1 x86_64\n perl-Digest 0 1.17 245.5.amzn1 noarch\n freetype 0 2.3.11 19.15.amzn1 x86_64\n keyutils 0 1.5.8 3.12.amzn1 x86_64\n copy-jdk-configs 0 3.3 10.3.amzn1 noarch\n dejavu-fonts-common 0 2.33 6.6.amzn1 noarch\n kernel-headers 0 4.14.225 121.362.amzn1 x86_64\n autogen-libopts 0 5.18 5.8.amzn1 x86_64\n golang-src 0 1.15.5 1.65.amzn1 noarch\n libXcomposite 0 0.4.3 4.6.amzn1 x86_64\n libX11 0 1.6.0 2.2.13.amzn1 x86_64\n pam 0 1.1.8 12.33.amzn1 x86_64\n vim-enhanced 2 8.0.0503 1.47.amzn1 x86_64\n zlib 0 1.2.8 7.18.amzn1 x86_64\n irqbalance 2 1.5.0 1.27.amzn1 x86_64\n python27-configobj 0 4.7.2 7.15.amzn1 noarch\n chkconfig 0 1.3.49.3 2.14.amzn1 x86_64\n openssh-server 0 7.4p1 21.75.amzn1 x86_64\n readline 0 6.2 9.14.amzn1 x86_64\n yum-plugin-upgrade-helper 0 1.1.31 46.30.amzn1 noarch"}'

• AmazonLinux command to get parameters

• RHEL command to get parameters

• Debian command to get parameters

• Ubuntu command to get parameters

Add a Lock File

curl -X POST -H 'accept: application/json' -H Authorization:XXXXXX '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"}'

Task List（Get All Tasks）

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,"
...
...

By default, the task list excludes workaround and patch_applied. To get all tasks, you need to specify all statuses with filterStatus as shown above.

Developer API Notes

• The maximum number of items that can be obtained at once in the list data is 1000.
• For data with a large number of software and task lists, using filters allows you to obtain the data quickly.
• Some defaults are specified, so check the documentation for the default values.
• For items that need to be specified as arrays, connect the same key with &&. (ex. filterStatus=new&&filterStatus=investigating )