Skip to content

Commit 3ae491e

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

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`` (integer) = 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`` (integer) = 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`` (integer) = 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 purls in bulk. You can
136+
pass a list of purls in the request body and the endpoint will return a list of
137+
purls 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 received in request.
145+
``plain_purl`` allows you to query the 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, these are packages
173+
that are affected by and/or that fix a 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)