-
Notifications
You must be signed in to change notification settings - Fork 75
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added OpenAPI-based API descriptions for CVE submission.
- Loading branch information
1 parent
e25feea
commit cccf5c2
Showing
1 changed file
with
220 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,220 @@ | ||
| # this API specification is draft and subject to change. | ||
| openapi: "3.0.2" | ||
| info: | ||
| title: CVE Services API | ||
| description: The CVE services API which supports automation tooling for the CVE Project. | ||
| version: 0.1.0 | ||
| contact: | ||
| "name": "API Support" | ||
| "url": http://cve.org/api | ||
| "email": [email protected] | ||
| license: | ||
| name: Creative Commons Zero v1.0 Universal | ||
| url: https://creativecommons.org/publicdomain/zero/1.0/legalcode | ||
| termsOfService: http://cve.org/api/terms | ||
| # The following is notional | ||
| servers: | ||
| - url: https://api-dev.cve.org/v1 | ||
| description: Development and testing server | ||
| - url: https://api.cve.org/v1 | ||
| description: Production server | ||
| components: | ||
| parameters: | ||
| cve-id-path: | ||
| name: cve-id | ||
| in: path | ||
| description: The CVE id for which the record is being submitted | ||
| required: true | ||
| schema: | ||
| # CVE ID format | ||
| type: string | ||
| pattern: 'CVE-\d{4}-\d+' | ||
| api-entity-header: | ||
| name: X-API-ENTITY | ||
| description: > | ||
| The entity (e.g., CNA, ADP) that is authenticated or requesting authentication. \[TODO:: Is there a pattern for the format?\] | ||
| in: header | ||
| required: true | ||
| schema: | ||
| type: string | ||
| api-secret-header: | ||
| name: X-API-SECRET | ||
| description: > | ||
| The entity's (e.g., CNA, ADP) secret. \[TODO:: Is there a pattern for the format?\] | ||
| in: header | ||
| required: true | ||
| schema: | ||
| type: string | ||
| paths: | ||
| # CVE submission and retrieval service | ||
| /cve/{cve-id}: | ||
| parameters: | ||
| - "$ref": "#/components/parameters/cve-id-path" | ||
| get: | ||
| summary: Retrieves a CVE record by id | ||
| operationId: getCVERecordById | ||
| responses: | ||
| 200: | ||
| description: > | ||
| The requested CVE record associated with the CVE ID is returned. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| # add schema for CVE 5.0 format | ||
| 404: | ||
| description: The requested CVE ID has not been populated. | ||
| post: | ||
| summary: Creates a new CVE record entry | ||
| operationId: submitCVERecordById | ||
| parameters: | ||
| - "$ref": "#/components/parameters/api-entity-header" | ||
| - "$ref": "#/components/parameters/api-secret-header" | ||
| - name: X-API-AUTHOR | ||
| in: header | ||
| required: true | ||
| schema: | ||
| type: string | ||
| requestBody: | ||
| description: The CVE record data to populate | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| # add schema for CVE 5.0 format | ||
| responses: | ||
| 200: | ||
| description: the CVE record is posted | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| # schema for the body | ||
| 400: | ||
| description: the request body is malformed | ||
| 401: | ||
| description: the client is not authenticated | ||
| 403: | ||
| description: > | ||
| the client is not authorized to submit this CVE. A likely | ||
| cause is the client's authentication context is not | ||
| associated with the reserved CVE id. | ||
| 404: | ||
| description: > | ||
| the requested CVE ID has not been reserved \[TODO:: do we want | ||
| this as it leaks info about the reserved status of a CVE ID? \] | ||
| put: | ||
| summary: Updates an existing CVE record entry | ||
| operationId: updateCVERecordById | ||
| parameters: | ||
| - "$ref": "#/components/parameters/api-entity-header" | ||
| - "$ref": "#/components/parameters/api-secret-header" | ||
| - name: X-API-AUTHOR | ||
| in: header | ||
| required: true | ||
| schema: | ||
| type: string | ||
| responses: | ||
| 200: | ||
| description: the update has been applied | ||
| content: | ||
| application/json: | ||
| schema: | ||
| # schema for the body | ||
| 400: | ||
| description: the request body is malformed | ||
| 401: | ||
| description: the client is not authenticated | ||
| 403: | ||
| description: > | ||
| the client is not authorized to update this CVE or a part that was | ||
| changed. The latter might be caused by a change to a record | ||
| container for which the authenticated entity is not authorized to | ||
| change. | ||
| 404: | ||
| description: > | ||
| the requested CVE ID has not been previously published. | ||
| requestBody: | ||
| description: The CVE record data to update | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| # add schema for CVE 5.0 format | ||
| /cve/{cve-id}/{entity-type}/{entity-id}: | ||
| parameters: | ||
| - "$ref": "#/components/parameters/cve-id-path" | ||
| - name: entity-type | ||
| in: path | ||
| description: The type of entity (i.e., CNA, ADP) | ||
| required: true | ||
| schema: | ||
| type: string | ||
| enum: | ||
| - CNA | ||
| - ADP | ||
| - name: entity-id | ||
| in: path | ||
| description: The identifier for the entity's container | ||
| required: true | ||
| schema: | ||
| type: string | ||
| # what is this syntax? | ||
| get: | ||
| description: > | ||
| Retrieves a given container in a CVE record entry. | ||
| operationId: getCVERecordContainerById | ||
| responses: | ||
| 200: | ||
| description: > | ||
| The requested CVE record container associated with the CVE ID and entity is returned. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| # add schema for CVE 5.0 format | ||
| 404: | ||
| description: The requested CVE ID or container has not been populated. | ||
| put: | ||
| description: > | ||
| Updates a given container in a CVE record entry. | ||
| operationId: updateCVERecordContainerById | ||
| parameters: | ||
| - "$ref": "#/components/parameters/api-entity-header" | ||
| - "$ref": "#/components/parameters/api-secret-header" | ||
| - name: X-API-AUTHOR | ||
| in: header | ||
| required: true | ||
| schema: | ||
| type: string | ||
| requestBody: | ||
| description: The CVE record container data to update | ||
| content: | ||
| application/json: | ||
| schema: | ||
| # add schema for CVE 5.0 format | ||
| responses: | ||
| 200: | ||
| description: the update has been applied | ||
| content: | ||
| application/json: | ||
| schema: | ||
| # schema for the body | ||
| 400: | ||
| description: the request body is malformed | ||
| 401: | ||
| description: the client is not authenticated | ||
| 403: | ||
| description: > | ||
| the client is not authorized to update this CVE or a part that was | ||
| changed. The latter might be caused by a change to a record | ||
| container for which the authenticated entity is not authorized to | ||
| change. | ||
| 404: | ||
| description: > | ||
| the requested CVE ID has not been previously published. | ||
| # /cve-id: | ||
| # post: | ||
| # /cve-id/{cve-id}: | ||
| # get: | ||
| # delete: |