-
Notifications
You must be signed in to change notification settings - Fork 68
Developer Guide to CVE Services API
This is an informal guide for developers in order to have a better experience while integrating with the services.
For every request to the CVE Services, three headers are required for authentication and authorization:
CVE-API-USER - a unique name for the organization it belongs to.
CVE-API-ORG - a unique "shortname" identifying the organization.
CVE-API-KEY - a string of characters used to authenticate.
If any of these details do not match up, a 401 Unauthorized will be returned.
When first attempting reservation with the IDR, it would be a good idea to see the organization's ID quota:
curl --location --request GET 'https://cveawg.mitre.org/api/org/education/id_quota' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>' \Example response:
{
"id_quota": 1000,
"total_reserved": 650,
"available": 350
}This example response indicates that the organization's ID quota is 1k IDs and there are already 650 CVE IDs for this organization in the RESERVED state. This organization can reserve 350 more before it would have to start publishing CVEs, which would make the CVE IDs used for those CVEs move to the PUBLIC state and no longer count against their quota.
By using this endpoint, your software could prevent a user from requesting more IDs than the organization can have before sending the request and having IDR return that error message.
In a gesture to encourage the community to reserve IDs on demand, IDR has a feature for those that request one ID and do not specify a batch_type. This is a "priority" ID which is the range 1-20k. These IDs go out lowest to highest. If the range is taken, IDR will transition as if the client had asked for a batch_type of sequential and return what is essentially the lowest ID available for that year. Please use this feature responsibly.
Example request:
curl --location --request POST 'https://cveawg.mitre.org/api/cve-id?amount=1&cve_year=2021&short_name=education' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>' \Example response:
{
"cve_ids": [
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-0023",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:37:34.854Z"
}
]
}This method of reservation is the traditional method everyone is accustomed to. It is recommended that if the goal is to reserve a large amount of IDs immediately in a single HTTP request to use the sequential batch_type. We currently do not limit how many sequential IDs can be asked for, so the organization's ID quota is essentially the limit. Upwards of 1k IDs have been asked for and response times are right under 2s.
However, we still encourage CNAs, if they can, to not reserve large amounts to have those IDs sit since IDR can reserve new IDs at any time. A more proper use of sequential batch_type's is to reserve a sequence of CVE IDs in order to publish a group of related CVEs.
Example request:
curl --location --request POST 'https://cveawg.mitre.org/api/cve-id?amount=5&cve_year=2021&short_name=education&batch_type=sequential' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
"cve_ids": [
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20288",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:48:36.845Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20289",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:48:36.845Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20290",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:48:36.846Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20291",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:48:36.846Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20292",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T19:48:36.846Z"
}
]
}This is a new method of reservation coming with IDR. IDR chooses IDs to reserve at random, so the array of CVE IDs returned are assorted across a range. Due to the random selection, this request takes longer to process. There's currently a limit of 10 on the amount one can request in one HTTP request as response times for 10 nonsequential IDs fall in the 1.7s range. If more than 10 nonsequential IDs are needed, we recommend simply making another request for more nonsequential IDs, as there is no limit to how many requests users or organizations as a whole can make against the IDR. Please do note that these requests should be made sequentially, as any concurrent requests risk receiving a 403 with { error: "RESERVATION_IN_PROGRESS" } and a message field containing additional explanation text. This is in order to avoid a long running reservation request causing an organization to exceed their id quota by having other smaller requests process concurrently before the longer request completes its reservations.
Example request:
curl --location --request POST 'https://cveawg.mitre.org/api/cve-id?amount=10&cve_year=2021&short_name=education&batch_type=nonsequential' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
"cve_ids": [
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20196",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.301Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20074",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.397Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20117",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.495Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20049",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.591Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20056",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.734Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20017",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.828Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20201",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.921Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20214",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:47.016Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20077",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:47.134Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20127",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:47.224Z"
}
]
}This is returned to indicate that another reservation request is processing for this organization. A client could catch this response, wait a few seconds, and try again if desired and it is possible the request would succeed.
Example: (Note HTTP status code will be 403)
{
"error": "RESERVATION_IN_PROGRESS",
"message": "<human readable message>"
}When asking for nonsequential IDs, there is the most minute chance that IDR has approached the end of the range it is set to allocate (somewhere around 50M per year for most years) but it has not done so at the start of a nonsequential request. But due to the asynchronous nature of REST APIs, multiple other nonsequential requests could be depleting the pool to the point that the pool can not be replenished and IDR can no longer reserve the amount it thought it could to fulfill the request. Due to the nature of nonsequential, that request would have made transactions to reserve some of those IDs. To be clear, this scenario should never happen. If IDR even comes close to approaching the ends of its ranges for any year, the Secretariat should update that range to allow IDR to continue running for that year. That being said, if IDR is in this bind, a 206 status code will be returned in order to indicate that not all the IDs were reserved with a JSON response containing various details and the successfully reserved CVE IDs.
Example:
{
"error": "RESERVED_PARTIAL_AMOUNT",
"message": "<human readable message>",
"details": {
"amount_reserved": 5,
},
"cve_ids": [
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20196",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.301Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20117",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.495Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20056",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.734Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20201",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:46.921Z"
},
{
"requested_by": {
"cna": "education",
"user": "[email protected]"
},
"cve_id": "CVE-2021-20077",
"cve_year": "2021",
"state": "RESERVED",
"owning_cna": "education",
"reserved": "2020-11-13T21:09:47.134Z"
}
]
}Every other error response falls under this section. These are errors that clients probably can't answer in code and instead should log or present to a user or both.
These errors use the following status codes:
- 400 -> The request either lacked a necessary parameter or input for the parameter wasn't valid
- 401 -> Authentication didn't match up
- 403 -> This user isn't allowed to do what was requested
- 404 -> Either the endpoint doesn't exist or the resource could not be found.
- 500 -> The service or a necessary component is down.