Skip to content

Commit 44362ea

Browse files
david-waltermiredavid-waltermire
committed
Added OpenAPI-based API descriptions for CVE submission.
1 parent f752bf9 commit 44362ea

File tree

1 file changed

+220
-0
lines changed

1 file changed

+220
-0
lines changed

‎openapi.yaml

+220
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# this API specification is draft and subject to change.
2+
openapi: "3.0.2"
3+
info:
4+
title: CVE Services API
5+
description: The CVE services API which supports automation tooling for the CVE Project.
6+
version: 0.1.0
7+
contact:
8+
"name": "API Support"
9+
"url": http://cve.org/api
10+
"email": [email protected]
11+
license:
12+
name: Creative Commons Zero v1.0 Universal
13+
url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
14+
termsOfService: http://cve.org/api/terms
15+
# The following is notional
16+
servers:
17+
- url: https://api-dev.cve.org/v1
18+
description: Development and testing server
19+
- url: https://api.cve.org/v1
20+
description: Production server
21+
components:
22+
parameters:
23+
cve-id-path:
24+
name: cve-id
25+
in: path
26+
description: The CVE id for which the record is being submitted
27+
required: true
28+
schema:
29+
# CVE ID format
30+
type: string
31+
pattern: 'CVE-\d{4}-\d+'
32+
api-entity-header:
33+
name: X-API-ENTITY
34+
description: >
35+
The entity (e.g., CNA, ADP) that is authenticated or requesting authentication. \[TODO:: Is there a pattern for the format?\]
36+
in: header
37+
required: true
38+
schema:
39+
type: string
40+
api-secret-header:
41+
name: X-API-SECRET
42+
description: >
43+
The entity's (e.g., CNA, ADP) secret. \[TODO:: Is there a pattern for the format?\]
44+
in: header
45+
required: true
46+
schema:
47+
type: string
48+
paths:
49+
# CVE submission and retrieval service
50+
/cve/{cve-id}:
51+
parameters:
52+
- "$ref": "#/components/parameters/cve-id-path"
53+
get:
54+
summary: Retrieves a CVE record by id
55+
operationId: getCVERecordById
56+
responses:
57+
200:
58+
description: >
59+
The requested CVE record associated with the CVE ID is returned.
60+
content:
61+
application/json:
62+
schema:
63+
type: object
64+
# add schema for CVE 5.0 format
65+
404:
66+
description: The requested CVE ID has not been populated.
67+
post:
68+
summary: Creates a new CVE record entry
69+
operationId: submitCVERecordById
70+
parameters:
71+
- "$ref": "#/components/parameters/api-entity-header"
72+
- "$ref": "#/components/parameters/api-secret-header"
73+
- name: X-API-AUTHOR
74+
in: header
75+
required: true
76+
schema:
77+
type: string
78+
requestBody:
79+
description: The CVE record data to populate
80+
content:
81+
application/json:
82+
schema:
83+
type: object
84+
# add schema for CVE 5.0 format
85+
responses:
86+
200:
87+
description: the CVE record is posted
88+
content:
89+
application/json:
90+
schema:
91+
type: object
92+
# schema for the body
93+
400:
94+
description: the request body is malformed
95+
401:
96+
description: the client is not authenticated
97+
403:
98+
description: >
99+
the client is not authorized to submit this CVE. A likely
100+
cause is the client's authentication context is not
101+
associated with the reserved CVE id.
102+
404:
103+
description: >
104+
the requested CVE ID has not been reserved \[TODO:: do we want
105+
this as it leaks info about the reserved status of a CVE ID? \]
106+
put:
107+
summary: Updates an existing CVE record entry
108+
operationId: updateCVERecordById
109+
parameters:
110+
- "$ref": "#/components/parameters/api-entity-header"
111+
- "$ref": "#/components/parameters/api-secret-header"
112+
- name: X-API-AUTHOR
113+
in: header
114+
required: true
115+
schema:
116+
type: string
117+
responses:
118+
200:
119+
description: the update has been applied
120+
content:
121+
application/json:
122+
schema:
123+
# schema for the body
124+
400:
125+
description: the request body is malformed
126+
401:
127+
description: the client is not authenticated
128+
403:
129+
description: >
130+
the client is not authorized to update this CVE or a part that was
131+
changed. The latter might be caused by a change to a record
132+
container for which the authenticated entity is not authorized to
133+
change.
134+
404:
135+
description: >
136+
the requested CVE ID has not been previously published.
137+
requestBody:
138+
description: The CVE record data to update
139+
content:
140+
application/json:
141+
schema:
142+
type: object
143+
# add schema for CVE 5.0 format
144+
/cve/{cve-id}/{entity-type}/{entity-id}:
145+
parameters:
146+
- "$ref": "#/components/parameters/cve-id-path"
147+
- name: entity-type
148+
in: path
149+
description: The type of entity (i.e., CNA, ADP)
150+
required: true
151+
schema:
152+
type: string
153+
enum:
154+
- CNA
155+
- ADP
156+
- name: entity-id
157+
in: path
158+
description: The identifier for the entity's container
159+
required: true
160+
schema:
161+
type: string
162+
# what is this syntax?
163+
get:
164+
description: >
165+
Retrieves a given container in a CVE record entry.
166+
operationId: getCVERecordContainerById
167+
responses:
168+
200:
169+
description: >
170+
The requested CVE record container associated with the CVE ID and entity is returned.
171+
content:
172+
application/json:
173+
schema:
174+
type: object
175+
# add schema for CVE 5.0 format
176+
404:
177+
description: The requested CVE ID or container has not been populated.
178+
put:
179+
description: >
180+
Updates a given container in a CVE record entry.
181+
operationId: updateCVERecordContainerById
182+
parameters:
183+
- "$ref": "#/components/parameters/api-entity-header"
184+
- "$ref": "#/components/parameters/api-secret-header"
185+
- name: X-API-AUTHOR
186+
in: header
187+
required: true
188+
schema:
189+
type: string
190+
requestBody:
191+
description: The CVE record container data to update
192+
content:
193+
application/json:
194+
schema:
195+
# add schema for CVE 5.0 format
196+
responses:
197+
200:
198+
description: the update has been applied
199+
content:
200+
application/json:
201+
schema:
202+
# schema for the body
203+
400:
204+
description: the request body is malformed
205+
401:
206+
description: the client is not authenticated
207+
403:
208+
description: >
209+
the client is not authorized to update this CVE or a part that was
210+
changed. The latter might be caused by a change to a record
211+
container for which the authenticated entity is not authorized to
212+
change.
213+
404:
214+
description: >
215+
the requested CVE ID has not been previously published.
216+
# /cve-id:
217+
# post:
218+
# /cve-id/{cve-id}:
219+
# get:
220+
# delete:

0 commit comments

Comments
 (0)