API v1#

PyVulnerabilityLookup is a Python library to access Vulnerability-Lookup via its REST API.

OpenAPI specification#

GET /browse/#

Get the known vendors

Get the known vendors.

Status Codes:

200 OK – Success

GET /browse/{vendor}#

Get the known products for a vendor

Get the known products for a vendor.

Parameters:

vendor (string)

Status Codes:

200 OK – Success

POST /bundle/#

Create a bundle.

Request JSON Object:

author (any) – (read only)
creation_timestamp (string) – Updated time of the bundle. (read only)
description (string) – Description.
meta (object) – Zero or more meta-fields.
name (string) – Bundle id.
related_vulnerabilities[] (string)
timestamp (string) – Updated time of the bundle. (read only)
uuid (string) – Bundle id.
vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)

Status Codes:

201 Created – Success.
400 Bad Request – JSON validation failed or incorrect payload to instantiate a bundle.
403 Forbidden – Administrator permission required.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Updated time of the bundle. (read only)
[].data[].description (string) – Description.
[].data[].meta (object) – Zero or more meta-fields.
[].data[].name (string) – Bundle id.
[].data[].related_vulnerabilities[] (string)
[].data[].timestamp (string) – Updated time of the bundle. (read only)
[].data[].uuid (string) – Bundle id.
[].data[].vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)
[].metadata (any) – Metada related to the result.

GET /bundle/#

List all bundles

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.
uuid (string) – UUID of the bundle.
author (string) – Author (login) of the bundle.
vuln_id (string) – Id of a vulnerability referenced by the bundle.
meta (string) – Query for the meta JSON field. Example: meta=[{‘tags’: [‘tcp’]}]
date_from (string) – The date of the bundles must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the bundles must be smaller or equal than this value. Format: YYYY-MM-DD

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Updated time of the bundle. (read only)
[].data[].description (string) – Description.
[].data[].meta (object) – Zero or more meta-fields.
[].data[].name (string) – Bundle id.
[].data[].related_vulnerabilities[] (string)
[].data[].timestamp (string) – Updated time of the bundle. (read only)
[].data[].uuid (string) – Bundle id.
[].data[].vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)
[].metadata (any) – Metada related to the result.

GET /bundle/{bundle_uuid}#

Get a bundle with its UUID.

Parameters:

bundle_uuid (string)

Status Codes:

200 OK – Success.
404 Not Found – Bundle not found.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

author (any) – (read only)
creation_timestamp (string) – Updated time of the bundle. (read only)
description (string) – Description.
meta (object) – Zero or more meta-fields.
name (string) – Bundle id.
related_vulnerabilities[] (string)
timestamp (string) – Updated time of the bundle. (read only)
uuid (string) – Bundle id.
vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)

DELETE /bundle/{bundle_uuid}#

Endpoint for deleting a bundle

Delete a bundle. Only an admin can delete a bundle.

Parameters:

bundle_uuid (string)

Status Codes:

204 No Content – Success.
403 Forbidden – Administrator permission required or not the author of the bundle.
404 Not Found – Bundle not found.

GET /capec/#

List all CAPECs

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].@Description (string) – Description. (read only)
[].data[].@ID (string) – Identifiant. (read only)
[].data[].@Name (string) – Name. (read only)
[].metadata (any) – Metada related to the result.

GET /capec/{capec_id}#

Get detailed information about a CAPEC.

Parameters:

capec_id (string)

Status Codes:

200 OK – Success

POST /comment/#

Create a new comment related to a security advisory (vulnerability)

Create a comment related to a security advisory.

Request JSON Object:

author (any) – (read only)
creation_timestamp (string) – Creation time of the comment. (read only)
description (string) – Description.
description_format (string) – Description format (markdown or text).
meta (object) – Zero or more meta-fields.
related_vulnerabilities[] (string)
timestamp (string) – Updated time of the comment. (read only)
title (string) – Comment id.
uuid (string) – Comment id.
vulnerability (string) – Vulnerability id.
vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)

Status Codes:

201 Created – Success.
400 Bad Request – JSON validation failed or incorrect payload to instantiate a comment.
403 Forbidden – Commenter permission required or not the author of the comment.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the comment. (read only)
[].data[].description (string) – Description.
[].data[].description_format (string) – Description format (markdown or text).
[].data[].meta (object) – Zero or more meta-fields.
[].data[].related_vulnerabilities[] (string)
[].data[].timestamp (string) – Updated time of the comment. (read only)
[].data[].title (string) – Comment id.
[].data[].uuid (string) – Comment id.
[].data[].vulnerability (string) – Vulnerability id.
[].data[].vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)
[].metadata (any) – Metada related to the result.

GET /comment/#

List all comments

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.
uuid (string) – UUID of the comment.
vuln_id (string) – Vulnerability related to the comment.
author (string) – Author of the comment.
meta (string) – Query for the meta JSON field. Example: meta=[{‘tags’: [‘PoC’]}]
date_from (string) – The date of the comments must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the comments must be smaller or equal than this value. Format: YYYY-MM-DD

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the comment. (read only)
[].data[].description (string) – Description.
[].data[].description_format (string) – Description format (markdown or text).
[].data[].meta (object) – Zero or more meta-fields.
[].data[].related_vulnerabilities[] (string)
[].data[].timestamp (string) – Updated time of the comment. (read only)
[].data[].title (string) – Comment id.
[].data[].uuid (string) – Comment id.
[].data[].vulnerability (string) – Vulnerability id.
[].data[].vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)
[].metadata (any) – Metada related to the result.

GET /comment/{comment_uuid}#

Get a comment with its UUID.

Parameters:

comment_uuid (string)

Status Codes:

200 OK – Success.
404 Not Found – Comment not found.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

author (any) – (read only)
creation_timestamp (string) – Creation time of the comment. (read only)
description (string) – Description.
description_format (string) – Description format (markdown or text).
meta (object) – Zero or more meta-fields.
related_vulnerabilities[] (string)
timestamp (string) – Updated time of the comment. (read only)
title (string) – Comment id.
uuid (string) – Comment id.
vulnerability (string) – Vulnerability id.
vulnerability_lookup_origin (string) – UUID of the Vulnerability-Lookup origin instance. (read only)

DELETE /comment/{comment_uuid}#

Endpoint for deleting a comment

Delete a comment.

Parameters:

comment_uuid (string)

Status Codes:

204 No Content – Success.
403 Forbidden – Commenter permission required or not the author of the comment.
404 Not Found – Comment not found.

GET /cwe/#

List all CWEs

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].@Abstraction (string) – Abstraction of the CWE (required)
[].data[].@ID (string) – CWE ID (required)
[].data[].@Name (string) – Name of the CWE (required)
[].data[].@Status (string) – Status of the CWE (required)
[].data[].@Structure (string) – Structure of the CWE (required)
[].data[].Description (string) – Description of the CWE (required)
[].data[].Related_Weaknesses (any) – Related weaknesses
[].metadata (any) – Metada related to the result.

GET /cwe/{cwe_id}#

Get detailed information about a CWE

Get detailed information about a CWE.

Parameters:

cwe_id (string)

Status Codes:

200 OK – Success

GET /epss/{vulnerability_id}#

Experimental - Get the EPSS score of a vulnerability.

Parameters:

vulnerability_id (string)

Status Codes:

200 OK – Success.
404 Not Found – Problem when retrieving EPSS.

POST /sighting#

Create a new sighting

Create a new sighting.

Request JSON Object:

author (any) – (read only)
creation_timestamp (string) – Creation time of the sighting.
source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
type (string) – Type of the sighting.
uuid (string) – Sighting UUID. (read only)
vulnerability (string) – Vulnerability id.

Status Codes:

201 Created – Success.
400 Bad Request – Incorrect payload to instantiate a sighting.
409 Conflict – Duplicate sighting.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the sighting.
[].data[].source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
[].data[].type (string) – Type of the sighting.
[].data[].uuid (string) – Sighting UUID. (read only)
[].data[].vulnerability (string) – Vulnerability id.
[].metadata (any) – Metada related to the result.

GET /sighting#

List all sightings

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.
uuid (string) – UUID of the sighting.
type (string) –
Type of sightings:
- Seen: The vulnerability was mentioned, discussed, or seen somewhere by the user.
- Exploited: This vulnerability was exploited and seen by the user reporting the sighting.
- Not exploited: This vulnerability was not exploited or seen by the user reporting the sighting.
- Confirmed: The vulnerability is confirmed from an analyst perspective.
- Not confirmed: The user expresses doubt about the veracity of the vulnerability.
- Patched: This vulnerability was successfully patched by the user reporting the sighting.
- Not patched: This vulnerability was not successfully patched by the user reporting the sighting.
vuln_id (string) – Vulnerability related to the sighting.
author (string) – Author of the sighting (login).
date_from (string) – The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD
source (string) – Source of the sighting.

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the sighting.
[].data[].source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
[].data[].type (string) – Type of the sighting.
[].data[].uuid (string) – Sighting UUID. (read only)
[].data[].vulnerability (string) – Vulnerability id.
[].metadata (any) – Metada related to the result.

POST /sighting/#

Create a new sighting

Create a new sighting.

Request JSON Object:

author (any) – (read only)
creation_timestamp (string) – Creation time of the sighting.
source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
type (string) – Type of the sighting.
uuid (string) – Sighting UUID. (read only)
vulnerability (string) – Vulnerability id.

Status Codes:

201 Created – Success.
400 Bad Request – Incorrect payload to instantiate a sighting.
409 Conflict – Duplicate sighting.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the sighting.
[].data[].source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
[].data[].type (string) – Type of the sighting.
[].data[].uuid (string) – Sighting UUID. (read only)
[].data[].vulnerability (string) – Vulnerability id.
[].metadata (any) – Metada related to the result.

GET /sighting/#

List all sightings

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.
uuid (string) – UUID of the sighting.
type (string) –
Type of sightings:
- Seen: The vulnerability was mentioned, discussed, or seen somewhere by the user.
- Exploited: This vulnerability was exploited and seen by the user reporting the sighting.
- Not exploited: This vulnerability was not exploited or seen by the user reporting the sighting.
- Confirmed: The vulnerability is confirmed from an analyst perspective.
- Not confirmed: The user expresses doubt about the veracity of the vulnerability.
- Patched: This vulnerability was successfully patched by the user reporting the sighting.
- Not patched: This vulnerability was not successfully patched by the user reporting the sighting.
vuln_id (string) – Vulnerability related to the sighting.
author (string) – Author of the sighting (login).
date_from (string) – The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD
source (string) – Source of the sighting.

Status Codes:

200 OK – Success

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].author (any) – (read only)
[].data[].creation_timestamp (string) – Creation time of the sighting.
[].data[].source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
[].data[].type (string) – Type of the sighting.
[].data[].uuid (string) – Sighting UUID. (read only)
[].data[].vulnerability (string) – Vulnerability id.
[].metadata (any) – Metada related to the result.

GET /sighting/{sighting_uuid}#

Get a sighting with its UUID.

Parameters:

sighting_uuid (string)

Status Codes:

200 OK – Success.
404 Not Found – Sighting not found.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

author (any) – (read only)
creation_timestamp (string) – Creation time of the sighting.
source (string) – The source of the sighting (Fediverse status URI, link, tool, etc.).
type (string) – Type of the sighting.
uuid (string) – Sighting UUID. (read only)
vulnerability (string) – Vulnerability id.

GET /stats/vulnerability/most_commented#

Returns the most commented vulnerabilities.

Query Parameters:

date_from (string) – The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD
limit (integer) – The top elements to take into account in the query.
output (string) – The format of the output.

Status Codes:

200 OK – Success

GET /stats/vulnerability/most_sighted#

Returns the most sighted vulnerabilities.

Query Parameters:

date_from (string) – The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD
date_to (string) – The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD
sighting_type (string) – The type of the sighting.
limit (integer) – The top elements to take into account in the query.
output (string) – The format of the output.

Status Codes:

200 OK – Success

GET /system/checkSMTP#

Checks the SMTP connection

Checks the SMTP connection.

Status Codes:

200 OK – Success

GET /system/configInfo#

Returns non-sensitive information about the configuration of the system

Returns non-sensitive information about the configuration of the system.

Status Codes:

200 OK – Success

GET /system/dbInfo#

Returns information about the current sources in the Kvrocks database in use and when it was updated

Returns information about the current sources in the Kvrocks database in use and when it was updated.

Status Codes:

200 OK – Success

GET /system/pgInfo#

Returns information about the PostgreSQL database

Returns information about the PostgreSQL database.

Status Codes:

200 OK – Success

GET /system/redis_up#

Check if Valkey/Redis is up and running

Check if Valkey/Redis is up and running.

Status Codes:

200 OK – Success

GET /system/valkey_up#

Check if Valkey/Redis is up and running

Check if Valkey/Redis is up and running.

Status Codes:

200 OK – Success

POST /user/#

Create a non-admin user

Create a non-admin user. The user will be active but must have to confirm the account with the email sent by the instance.

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.

Request JSON Object:

email (string)
login (string)
name (string)
organisation (string)

Status Codes:

200 OK – Success
201 Created – Success.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

apikey (string) – User API key. (read only)
created_at (string) – Creation time of the user. (read only)
email (string) – User email.
id (integer) – User id.
is_admin (boolean) – Boolean specifying whether the user is administrator.
is_commenter (boolean) – Boolean specifying whether the user is commenter.
is_reporter (boolean) – Boolean specifying whether the user is reporter.
last_seen (string) – Last seen time of the user. (read only)
login (string) – User login.
name (string) – User name.
organisation (string) – User organisation.
uuid (string) – User UUID.

GET /user/#

List all users

Only available to administrators.

Query Parameters:

page (integer) – Number of the page.
per_page (integer) – Maximum number of elements to return.

Status Codes:

200 OK – Success.
403 Forbidden – Admin permission required.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

[].data[].apikey (string) – User API key. (read only)
[].data[].created_at (string) – Creation time of the user. (read only)
[].data[].email (string) – User email.
[].data[].id (integer) – User id.
[].data[].is_admin (boolean) – Boolean specifying whether the user is administrator.
[].data[].is_commenter (boolean) – Boolean specifying whether the user is commenter.
[].data[].is_reporter (boolean) – Boolean specifying whether the user is reporter.
[].data[].last_seen (string) – Last seen time of the user. (read only)
[].data[].login (string) – User login.
[].data[].name (string) – User name.
[].data[].organisation (string) – User organisation.
[].data[].uuid (string) – User UUID.
[].metadata (any) – Metada related to the result.

POST /user/api_key#

Regenerating the API key of the authenticated user with the current API key

Regenerating the API key of the authenticated user with the current API key.

Request JSON Object:

apikey (string) – The current API key of the user.

Status Codes:

200 OK – Success.
403 Forbidden – Wrong API key submitted.
404 Not Found – User not found.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

apikey (string) – User API key. (read only)
created_at (string) – Creation time of the user. (read only)
email (string) – User email.
id (integer) – User id.
is_admin (boolean) – Boolean specifying whether the user is administrator.
is_commenter (boolean) – Boolean specifying whether the user is commenter.
is_reporter (boolean) – Boolean specifying whether the user is reporter.
last_seen (string) – Last seen time of the user. (read only)
login (string) – User login.
name (string) – User name.
organisation (string) – User organisation.
uuid (string) – User UUID.

GET /user/me#

Get information about the currently authenticated user

Get information about the currently authenticated user.

Status Codes:

200 OK – Success.
404 Not Found – User not found.

Request Headers:

X-Fields – An optional fields mask

Response JSON Object:

apikey (string) – User API key. (read only)
created_at (string) – Creation time of the user. (read only)
email (string) – User email.
id (integer) – User id.
is_admin (boolean) – Boolean specifying whether the user is administrator.
is_commenter (boolean) – Boolean specifying whether the user is commenter.
is_reporter (boolean) – Boolean specifying whether the user is reporter.
last_seen (string) – Last seen time of the user. (read only)
login (string) – User login.
name (string) – User name.
organisation (string) – User organisation.
uuid (string) – User UUID.

DELETE /user/{user_id}#

Endpoint for deleting a user

Delete a user.

Parameters:

user_id (integer)

Status Codes:

204 No Content – Success.
403 Forbidden – Administrator permission required or not the current user.
404 Not Found – User not found.

POST /vulnerability/#

Endpoint for creating and editing vulnerabilities in the local source

Create a vulnerability with the CVE version 5 format.

Request JSON Object:

data (string)

Status Codes:

200 OK – Success.
400 Bad Request – JSON validation failed.
403 Forbidden – Reporter permission required.
422 Unprocessable Entity – Not possible to edit a vulnerability from the requested source.

GET /vulnerability/browse/#

Get the known vendors

Get the known vendors.

Status Codes:

200 OK – Success

GET /vulnerability/cpesearch/{cpe}#

Get vulnerabilities by CPE

Get vulnerabilities by CPE.

Parameters:

cpe (string)

Status Codes:

200 OK – Success.
404 Not Found – No match found.

GET /vulnerability/last#

Retrieve the latest vulnerabilities, with optional filters for source and number of results

Get the last vulnerabilities Supports light mode for minimal data and provides backward-compatible routes.

Status Codes:

200 OK – Success

GET /vulnerability/last/{number}#

Retrieve the latest vulnerabilities, with optional filters for source and number of results

Get the last vulnerabilities Supports light mode for minimal data and provides backward-compatible routes.

Parameters:

number (integer)

Status Codes:

200 OK – Success

GET /vulnerability/last/{source}#

Retrieve the latest vulnerabilities, with optional filters for source and number of results

Get the last vulnerabilities Supports light mode for minimal data and provides backward-compatible routes.

Parameters:

source (string)

Status Codes:

200 OK – Success

GET /vulnerability/last/{source}/{number}#

Retrieve the latest vulnerabilities, with optional filters for source and number of results

Get the last vulnerabilities Supports light mode for minimal data and provides backward-compatible routes.

Parameters:

source (string)
number (integer)

Status Codes:

200 OK – Success

GET /vulnerability/recent#