Skip to content

Commit bc86f95

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

13 files changed

+854
-583
lines changed

‎CHANGELOG.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Next release
77

88
- We fixed Apache HTTPD and Apache Kafka importer.
99
- We removed excessive network calls from Redhat importer.
10+
- Add documentation for version 32.0.0.
1011

1112

1213
Version v32.0.0rc4

‎docs/source/api.rst‎

Lines changed: 204 additions & 2 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

@@ -34,10 +45,121 @@ Access the API using curl
3445

3546
curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/
3647

48+
.. _Package Vulnerabilities Query:
49+
50+
Query for Package Vulnerabilities
51+
------------------------------------
52+
53+
The package endpoint allows you to query vulnerabilities by package using a
54+
purl or purl fields.
55+
56+
Sample python script::
57+
58+
import requests
59+
60+
# Query by purl
61+
resp = requests.get(
62+
"https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/log4j@1.2.27",
63+
headers={"Authorization": "Token 123456789"},
64+
).json()
65+
66+
# Query by purl type, get all the vulnerable maven packages
67+
resp = requests.get(
68+
"https://public.vulnerablecode.io/api/packages?type=maven",
69+
headers={"Authorization": "Token 123456789"},
70+
).json()
71+
72+
The response will be a list of packages, these are packages
73+
that are affected by and/or that fix a vulnerability.
74+
75+
76+
.. _Package Bulk Search:
77+
78+
Package Bulk Search
79+
---------------------
80+
81+
82+
The package bulk search endpoint allows you to search for purls in bulk. You can
83+
pass a list of purls in the request body and the endpoint will return a list of
84+
purls with vulnerabilities.
85+
86+
87+
You can pass a list of ``purls`` in the request body. Each package should be a
88+
valid purl string.
89+
90+
You can also pass options like ``purl_only`` and ``plain_purl`` in the request.
91+
``purl_only`` will return only a list of vulnerable purls from the purls received in request.
92+
``plain_purl`` allows you to query the API using plain purls by removing qualifiers
93+
and subpath from the purl.
94+
95+
The request body should be a JSON object with the following structure::
96+
97+
{
98+
"purls": [
99+
"pkg:pypi/flask@1.2.0",
100+
"pkg:npm/express@1.0"
101+
],
102+
"purl_only": false,
103+
"plain_purl": false,
104+
}
37105

38-
API endpoints
39-
---------------
106+
Sample python script::
40107

108+
import requests
109+
110+
request_body = {
111+
"purls": [
112+
"pkg:npm/grunt-radical@0.0.14"
113+
],
114+
}
115+
116+
resp = requests.post('https://public.vulnerablecode.io/api/packages/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
117+
118+
119+
The response will be a list of packages, these are packages
120+
that are affected by and/or that fix a vulnerability.
121+
122+
.. _CPE Bulk Search:
123+
124+
CPE Bulk Search
125+
---------------------
126+
127+
128+
The CPE bulk search endpoint allows you to search for packages in bulk.
129+
You can pass a list of packages in the request body and the endpoint will
130+
return a list of vulnerabilities.
131+
132+
133+
You can pass a list of ``cpes`` in the request body. Each cpe should be a
134+
non empty string and a valid CPE.
135+
136+
137+
The request body should be a JSON object with the following structure::
138+
139+
{
140+
"cpes": [
141+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*",
142+
"cpe:2.3:a:apache:struts:2.3.2:*:*:*:*:*:*:*"
143+
]
144+
}
145+
146+
Sample python script::
147+
148+
import requests
149+
150+
request_body = {
151+
"cpes": [
152+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*"
153+
],
154+
}
155+
156+
resp = requests.post('https://public.vulnerablecode.io/api/cpes/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
157+
158+
The response will be a list of vulnerabilities that have the following CPEs.
159+
160+
161+
API endpoints reference
162+
--------------------------
41163

42164
There are two primary endpoints:
43165

@@ -48,3 +170,83 @@ There are two primary endpoints:
48170
And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
49171
and vulnerability by CPEs: cpes/ and aliases/
50172

173+
174+
.. list-table:: Table for the main API endpoints
175+
:widths: 30 40 30
176+
:header-rows: 1
177+
178+
* - Endpoint
179+
- Query Parameters
180+
- Expected Output
181+
* - ``/api/packages``
182+
-
183+
- ``purl`` (string) = package-url of the package
184+
- ``type`` (string) = type of the package
185+
- ``namespace`` (string) = namespace of the package
186+
- ``name`` (string) = name of the package
187+
- ``version`` (string) = version of the package
188+
- ``qualifiers`` (string) = qualifiers of the package
189+
- ``subpath`` (string) = subpath of the package
190+
- ``page`` (integer) = page number of the response
191+
- ``page_size`` (integer) = number of packages in each page
192+
- Return a list of packages using a package-url (purl) or a combination of
193+
type, namespace, name, version, qualifiers, subpath purl fields. See the
194+
`purl specification <https://github.com/package-url/purl-spec>`_ for more details. See example at :ref:`Package Vulnerabilities Query` section for more details.
195+
* - ``/api/packages/bulk_search``
196+
- Refer to package bulk search section :ref:`Package Bulk Search`
197+
- Return a list of packages
198+
* - ``/api/vulnerabilities/``
199+
-
200+
- ``vulnerability_id`` (string) = VCID (VulnerableCode Identifier) of the vulnerability
201+
- ``page`` (integer) = page number of the response
202+
- ``page_size`` (integer) = number of vulnerabilities in each page
203+
- Return a list of vulnerabilities
204+
* - ``/api/cpes``
205+
-
206+
- ``cpe`` (string) = value of the cpe
207+
- ``page`` (integer) = page number of the response
208+
- ``page_size`` (integer) = number of cpes in each page
209+
- Return a list of vulnerabilities
210+
* - ``/api/cpes/bulk_search``
211+
- Refer to CPE bulk search section :ref:`CPE Bulk Search`
212+
- Return a list of cpes
213+
* - ``/api/aliases``
214+
-
215+
- ``alias`` (string) = value of the alias
216+
- ``page`` (integer) = page number of the response
217+
- ``page_size`` (integer) = number of aliases in each page
218+
- Return a list of vulnerabilities
219+
220+
.. list-table:: Table for other API endpoints
221+
:widths: 30 40 30
222+
:header-rows: 1
223+
224+
* - Endpoint
225+
- Query Parameters
226+
- Expected Output
227+
* - ``/api/packages/{id}``
228+
-
229+
- ``id`` (integer) = internal primary id of the package
230+
- Return a package with the given id
231+
* - ``/api/packages/all``
232+
- No parameter required
233+
- Return a list of all vulnerable packages
234+
* - ``/api/vulnerabilities/{id}``
235+
-
236+
- ``id`` (integer) = internal primary id of the vulnerability
237+
- Return a vulnerability with the given id
238+
* - ``/api/aliases/{id}``
239+
-
240+
- ``id`` (integer) = internal primary id of the alias
241+
- Return an alias with the given id
242+
* - ``/api/cpes/{id}``
243+
-
244+
- ``id`` = internal primary id of the cpe
245+
- Return a cpe with the given id
246+
247+
Miscellaneous
248+
----------------
249+
250+
The API is paginated and the default page size is 100. You can change the page size
251+
by passing the ``page_size`` parameter. You can also change the page number by passing
252+
the ``page`` parameter.

0 commit comments

Comments
 (0)