Skip to content

Commit 7af5a86

Browse files
TG1999TG1999
committed
Add documentation for v32.0.0
Signed-off-by: Tushar Goel <tushar.goel.dav@gmail.com>
1 parent 33b3d92 commit 7af5a86

12 files changed

+810
-581
lines changed

‎docs/source/api.rst‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,17 @@ Browse the Open API documentation
1111
- https://public.vulnerablecode.io/api/schema/ for the OpenAPI schema
1212

1313

14+
How to use OpenAPI documentation
15+
--------------------------------------
16+
17+
The API documentation is available at https://public.vulnerablecode.io/api/docs/.
18+
To use the endpoints you need to authenticate with an API key. Request your API key
19+
from https://public.vulnerablecode.io/account/request_api_key/. Once you have
20+
your API key, click on the ``Authorize`` button on the top right of the page and enter
21+
your API key in the ``value`` field with ``Token`` prefix, so if your token is "1234567890abcdef"
22+
then you have to enter this: ``Token 1234567890abcdef``.
23+
24+
1425
Enable the API key authentication
1526
------------------------------------
1627

@@ -48,3 +59,153 @@ There are two primary endpoints:
4859
And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
4960
and vulnerability by CPEs: cpes/ and aliases/
5061

62+
The API is paginated and the default page size is 100. You can change the page size
63+
by passing the page_size parameter. You can also change the page number by passing
64+
the page parameter.
65+
66+
.. list-table:: Table for the API endpoints
67+
:widths: 30 40 30
68+
:header-rows: 1
69+
70+
* - Endpoint
71+
- Query Parameters
72+
- Expected Output
73+
* - /api/vulnerabilities/
74+
-
75+
- vulnerability_id (string) = VCID of the vulnerability
76+
- page (integer) = page number of the response
77+
- page_size (integer) = number of vulnerabilities in each page
78+
- Returns a list of vulnerabilities
79+
* - /api/vulnerabilities/{id}
80+
-
81+
- id = internal primary id of the vulnerability
82+
- Returns a vulnerability with the given id
83+
* - /api/packages
84+
-
85+
- type (string) = type of the package
86+
- namespace (string) = namespace of the package
87+
- name (string) = name of the package
88+
- version (string) = version of the package
89+
- qualifiers (string) = qualifiers of the package
90+
- subpath (string) = subpath of the package
91+
- page (integer) = page number of the response
92+
- page_size (integer) = number of packages in each page
93+
- Returns a list of packages
94+
* - /api/packages/{id}
95+
-
96+
- id = internal primary id of the package
97+
- Returns a package with the given id
98+
* - /api/packages/all
99+
- No parameter required
100+
- Returns a list of all vulnerable packages
101+
* - /api/packages/bulk_search
102+
- Refer to package bulk search section :ref:`Package Bulk Search`
103+
- Returns a list of packages
104+
* - /api/aliases
105+
-
106+
- alias (string) = value of the alias
107+
- page (integer) = page number of the response
108+
- page_size (integer) = number of aliases in each page
109+
- Returns a list of vulnerabilities
110+
* - /api/aliases/{id}
111+
-
112+
- id = internal primary id of the alias
113+
- Returns an alias with the given id
114+
* - /api/cpes
115+
-
116+
- cpe (string) = value of the cpe
117+
- page (integer) = page number of the response
118+
- page_size (integer) = number of cpes in each page
119+
- Returns a list of vulnerabilities
120+
* - /api/cpes/{id}
121+
-
122+
- id = internal primary id of the cpe
123+
- Returns a cpe with the given id
124+
* - /api/cpes/bulk_search
125+
- Refer to cpe bulk search section :ref:`CPE Bulk Search`
126+
- Returns a list of cpes
127+
128+
129+
.. _Package Bulk Search:
130+
131+
Package Bulk Search
132+
---------------------
133+
134+
135+
The package bulk search endpoint allows you to search for packages in bulk. You can
136+
pass a list of packages in the request body and the endpoint will return a list of
137+
packages with vulnerabilities.
138+
139+
140+
You can pass a list of ``purls`` in the request body. Each package should be a
141+
valid purl string.
142+
143+
You can also pass options like ``purl_only`` and ``plain_purl`` in the request.
144+
``purl_only`` will return only a list of vulnerable purls from the purls recieved in request.
145+
``plain_purl`` allows you to query API using plain purls by removing qualifiers
146+
and subpath from the purl.
147+
148+
The request body should be a JSON object with the following structure::
149+
150+
{
151+
"purls": [
152+
"pkg:pypi/flask@1.2.0",
153+
"pkg:npm/express@1.0"
154+
],
155+
"purl_only": false,
156+
"plain_purl": false,
157+
}
158+
159+
Sample python script::
160+
161+
import requests
162+
163+
request_body = {
164+
"purls": [
165+
"pkg:npm/grunt-radical@0.0.14"
166+
],
167+
}
168+
169+
resp = requests.post('https://public.vulnerablecode.io/api/packages/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
170+
171+
172+
The response will be a list of packages with vulnerabilities
173+
they are affected by or fixing any vulnerability.
174+
175+
.. _CPE Bulk Search:
176+
177+
CPE Bulk Search
178+
---------------------
179+
180+
181+
The CPE bulk search endpoint allows you to search for packages in bulk.
182+
You can pass a list of packages in the request body and the endpoint will
183+
return a list of vulnerabilities.
184+
185+
186+
You can pass a list of ``cpes`` in the request body. Each cpe should be a
187+
non empty string and a valid CPE.
188+
189+
190+
The request body should be a JSON object with the following structure::
191+
192+
{
193+
"cpes": [
194+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*",
195+
"cpe:2.3:a:apache:struts:2.3.2:*:*:*:*:*:*:*"
196+
]
197+
}
198+
199+
Sample python script::
200+
201+
import requests
202+
203+
request_body = {
204+
"cpes": [
205+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*"
206+
],
207+
}
208+
209+
resp = requests.post('https://public.vulnerablecode.io/api/cpes/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
210+
211+
The response will be a list of vulnerabilities that have the following CPEs.

0 commit comments

Comments
 (0)