VulnDB APIv2

This describes the resources that make up the official VulnDB HQ API v2. If you have any problems or requests please contact support.

Jump to: Open-source libraries | URLs | API versions | Authentication

Resources:

• Private pages: List & search| Create | Update | Delete
• Public pages: List & search

Open-source libraries

Below is the list of available bindings. If you have created or know of other bindings, let us know and we'll add them to the list.

• Ruby: vulndbhq gem

URLs

All API access is over HTTPS, and accessed from your private domain (e.g. john.vulndbhq.com). All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Current version

VulnDB HQ API versioning follows the GitHub approach of using the Accept header to identify the target API version.

All VulnDB HQ mime types look like this:

application/vnd.vulndbhq; v=[version]

For API v2 this should be:

application/vnd.vulndbhq; v=2

HTTP Verbs

Where possible, API v2 strives to use appropriate HTTP verbs for each action.

• HEAD := Can be issued against any resource to get just the HTTP header info.
• GET := Used for retrieving resources.
• POST := Used for creating resources
• PUT := Used for updating resources with partial JSON data. For instance, a Private Page resource has name and content attributes. A PUT request may accept one or more of the attributes to update the resource.
• DELETE := Used for deleting resources.

Authentication

Teh VulnDB HQ API v2 supports two different authentication modes: API token and HTTP Basic.

API token

Find your API token in your Profile page and provide it as part of the HTTP Authorization header:

Authorization: Token token="<API_token>"

Note that the header requires you to use double-quotes ("). For example:

$ curl -H 'Authorization: Token token="d4d1b4e3aa7a272333409c638e000007"' \
  https://john.vulndbhq.com/api/private_pages/1
{"content":"h1. Welcome to VulnDB HQ...","id":1,"name":"Welcome"}

Basic Authentication

Use the same credentials you log in with:

$ curl -u 'your@email.com' https://john.vulndbhq.com/api/private_pages/1
Enter host password for user 'your@email.com':
{"content":"h1. Welcome to VulnDB HQ...","id":1,"name":"Welcome"}

Resources

Private Page

Private Pages are entries in your private library. You have complete (and exclusive) control over your private library.

List

List all your private pages:

GET /api/private_pages

Sample request:

$ curl -v -H 'Authorization: Token token="d4d1b4e3aa7a272333409c638e000007"' https://john.vulndbhq.com/api/private_pages.json

Result:

[
  {
    "id": 1,
    "name": "MyPrivatePage",
    "content": "#[Title]#\r\nThis is my Private Page..."
  },
  {
    "id": 2,
    "name": "ReflectedXSS",
    "content": "#[Title]#\r\nReflected cross-site..." },
  },
  //...
]

Parameters:

• q := Search query to filter the results by. Default: none / unfiltered

Example:

GET /api/private_pages?q=XSS

Result:

[
  {
    "id": 2,
    "name": "ReflectedXSS",
    "content": "#[Title]#\r\nReflected cross-site..." },
  }
]

To retrieve a single element:

GET /api/private_pages/1

Sample request:

$ curl -v -H 'Authorization: Token token="d4d1b4e3aa7a272333409c638e000007"' https://john.vulndbhq.com/api/private_pages/1.json

Result:

{
  "content": "#[Title]#\r\nThis is my Private Page\r\n\r\n",
       "id": 1,
     "name": "MyPrivatePage"
}

Creating private pages

POST /api/private_pages

This call creates a single page in your Private library. The data for the entry must be given in the post body as JSON.

Sample request:

$ curl -v -d @private_page.json -H 'Content-type: application/json' -H 'Authorization: Token token="d4d1b4e3aa7a272333409c638e000007"' https://john.vulndbhq.com/api/private_pages.json

You'll need a private_page.json with the contents of your private page:

{
  "private_page": {
    "name": "PageName",
    "content": "#[Field1]#\r\nValue 1\r\n\r\n..."
  }
}

Response codes

201 Created means that the entry was successfully created in is now visible in VulnDB. The Location header in the HTTP response contains the path to this new entry in the API. This path contains the entry ID which your application can store so it can update the same entry later.

Here's an example response:

HTTP/1.1 201 Created
Server: nginx
Date: Mon, 06 May 2013 21:38:21 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1
Connection: keep-alive
Status: 201 Created
Location: /api/private_pages/11

422 Unprocessable Entity means the request data was not valid, for example a required field was omitted.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
Cache-Control: no-cache
Connection: keep-alive

{"errors":{"name":["can't be blank"]}}

Updating private pages

TBC

Deleting private pages

TBC

Public Page

Public Pages are entries in the Public Library. You can read from the Public Library but you can't edit/delete records from it.

List

GET /api/public_pages/1

Result:

{
  "content": "#[Title]#\r\nPersistent cross-site scripting...",
       "id": 1,
     "name": "PersistentXSS"
}

List all the pages in the Public library:

GET /api/public_pages

Parameters:

• q := Search query to filter the results by. Default: none / unfiltered

Example:

GET /api/public_pages?q=XSS