Skip to content

Introduction

Your own tools can interact with OpenCVE using its REST API. You can list the last CVEs per vendor, filter them by CVSS or analyse the changes in your reports.

All the following endpoints are available under https://example.com/api.

We also provide a running instance of OpenCVE, in this case the API can be found on https://www.opencve.io/api.

Warning

The OpenCVE API is still in Beta, some changes may appear until the stable version.

Authentication

We only support basic authentication for now, but we plan to add other ones like token based authentication.

To use the Basic Authentication with the OpenCVE API, simply pass your credentials in the Authorization header.

Most clients do it for you, for example using curl :

curl -u username:password https://www.opencve.io/api/cve

You can omit your password, curl will interactively ask you.

Pagination

Some endpoints can return lots of results (get the list of CVEs, the list of vendors, the list of reports, etc). In these cases the request must be paginated with the ?page parameter.

Example with the list of CVEs:

curl https://www.opencve.io/api/cve?page=100

When no result is found (the page parameter is too high), a 404 HTTP status code is returned.

The default number of returned items per page in 20. You can change it in your opencve.cfg file:

cves_per_page = 20
vendors_per_page = 20
products_per_page = 20
cwes_per_page = 20
reports_per_page = 20
alerts_per_page = 20

Rate limit

A rate limit can be applied using the [api] section of the opencve.cfg configuration file:

[api]
; Enable the API ratelimit
ratelimit_enabled = False

; Default value accross all API routes
; see https://flask-limiter.readthedocs.io/en/stable/#rate-limit-string-notation
ratelimit_value = 3600/hour

; Ratelimit storage URI
; see https://limits.readthedocs.io/en/latest/storage.html
ratelimit_storage_url = redis://127.0.0.1:6379/2

Tip

The rate limit is shared between all API routes.

When enabled, the API returned HTTP headers showing your current rate limit state:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 9621
Date: Mon, 05 Apr 2021 13:18:21 GMT
X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3596
X-RateLimit-Reset: 1617632265
Retry-After: 3563

Here are the explanations of these headers:

Header Description
X-RateLimit-Limit Total number of requests allowed in an hour.
X-RateLimit-Remaining Number of requests remaining.
X-RateLimit-Reset UTC seconds since epoch when the window will be reset.
Retry-After Seconds to wait before the Rate Limit will be reset.

Info

A ratelimit of 1000 requests per hour and per user is applied on OpenCVE.io.