Skip to content

Commit c3e8e3f

Browse files
TG1999TG1999
committed
Add documentation for v32.0.0
Signed-off-by: Tushar Goel <[email protected]>
1 parent 3abdc3f commit c3e8e3f

14 files changed

+869
-595
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-admin.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _api_admin:
2+
3+
API usage administration for on-premise deployments
4+
====================================================
5+
6+
Enable the API key authentication
7+
------------------------------------
8+
9+
There is a setting VULNERABLECODEIO_REQUIRE_AUTHENTICATION for this. Use it this
10+
way::
11+
12+
$ VULNERABLECODEIO_REQUIRE_AUTHENTICATION=1 make run
13+
14+
15+
Create an API key-only user
16+
------------------------------------
17+
18+
This can be done in the admin and from the command line::
19+
20+
$ ./manage.py create_api_user --email "[email protected]" --first-name="Phil" --last-name "Goel"
21+
User [email protected] created with API key: ce8616b929d2adsddd6146346c2f26536423423491

‎docs/source/api.rst‎

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

1313

14-
Enable the API key authentication
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+
.. _Package Vulnerabilities Query:
25+
26+
Query for Package Vulnerabilities
1527
------------------------------------
1628

17-
There is a setting VULNERABLECODEIO_REQUIRE_AUTHENTICATION for this. Use it this
18-
way::
29+
The package endpoint allows you to query vulnerabilities by package using a
30+
purl or purl fields.
1931

20-
$ VULNERABLECODEIO_REQUIRE_AUTHENTICATION=1 make run
32+
Sample python script::
2133

34+
import requests
2235

23-
Create an API key-only user
24-
------------------------------------
36+
# Query by purl
37+
resp = requests.get(
38+
"https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/[email protected]",
39+
headers={"Authorization": "Token 123456789"},
40+
).json()
41+
42+
# Query by purl type, get all the vulnerable maven packages
43+
resp = requests.get(
44+
"https://public.vulnerablecode.io/api/packages?type=maven",
45+
headers={"Authorization": "Token 123456789"},
46+
).json()
47+
48+
Sample using curl::
49+
50+
curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/[email protected]
51+
52+
53+
The response will be a list of packages, these are packages
54+
that are affected by and/or that fix a vulnerability.
55+
56+
57+
.. _Package Bulk Search:
58+
59+
Package Bulk Search
60+
---------------------
61+
62+
63+
The package bulk search endpoint allows you to search for purls in bulk. You can
64+
pass a list of purls in the request body and the endpoint will return a list of
65+
purls with vulnerabilities.
66+
67+
68+
You can pass a list of ``purls`` in the request body. Each package should be a
69+
valid purl string.
70+
71+
You can also pass options like ``purl_only`` and ``plain_purl`` in the request.
72+
``purl_only`` will return only a list of vulnerable purls from the purls received in request.
73+
``plain_purl`` allows you to query the API using plain purls by removing qualifiers
74+
and subpath from the purl.
2575

26-
This can be done in the admin and from the command line::
76+
The request body should be a JSON object with the following structure::
2777

28-
$ ./manage.py create_api_user --email "[email protected]" --first-name="Phil" --last-name "Goel"
29-
User [email protected] created with API key: ce8616b929d2adsddd6146346c2f26536423423491
78+
{
79+
"purls": [
80+
"pkg:pypi/[email protected]",
81+
"pkg:npm/[email protected]"
82+
],
83+
"purl_only": false,
84+
"plain_purl": false,
85+
}
3086

87+
Sample python script::
3188

32-
Access the API using curl
33-
-----------------------------
89+
import requests
3490

35-
curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/
91+
request_body = {
92+
"purls": [
93+
"pkg:npm/[email protected]"
94+
],
95+
}
3696

97+
resp = requests.post('https://public.vulnerablecode.io/api/packages/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
3798

38-
API endpoints
39-
---------------
4099

100+
The response will be a list of packages, these are packages
101+
that are affected by and/or that fix a vulnerability.
102+
103+
.. _CPE Bulk Search:
104+
105+
CPE Bulk Search
106+
---------------------
107+
108+
109+
The CPE bulk search endpoint allows you to search for packages in bulk.
110+
You can pass a list of packages in the request body and the endpoint will
111+
return a list of vulnerabilities.
112+
113+
114+
You can pass a list of ``cpes`` in the request body. Each cpe should be a
115+
non empty string and a valid CPE.
116+
117+
118+
The request body should be a JSON object with the following structure::
119+
120+
{
121+
"cpes": [
122+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*",
123+
"cpe:2.3:a:apache:struts:2.3.2:*:*:*:*:*:*:*"
124+
]
125+
}
126+
127+
Sample python script::
128+
129+
import requests
130+
131+
request_body = {
132+
"cpes": [
133+
"cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*"
134+
],
135+
}
136+
137+
resp = requests.post('https://public.vulnerablecode.io/api/cpes/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
138+
139+
The response will be a list of vulnerabilities that have the following CPEs.
140+
141+
142+
API endpoints reference
143+
--------------------------
41144

42145
There are two primary endpoints:
43146

@@ -48,3 +151,83 @@ There are two primary endpoints:
48151
And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
49152
and vulnerability by CPEs: cpes/ and aliases/
50153

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

0 commit comments

Comments
 (0)