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

GET /bundle/

List all bundles

Query Parameters:

• 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’]}]

• per_page (integer) – Number of elements to return.

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.

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/{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 /comment/

List all comments

Query Parameters:

• 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’]}]

• per_page (integer) – Number of elements to return.

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.

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/{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 /cve/{vulnerability_id}

Alias for /api/vulnerability/<string:vulnerability_id Get a vulnerability.

Parameters:

• vulnerability_id (string)

Query Parameters:

• with_meta (boolean) – Include metada.

Status Codes:

• 200 OK – Success

DELETE /cve/{vulnerability_id}

Endpoint for deleting a vulnerability

Alias for /api/vulnerability/<string:vulnerability_id Delete a vulnerability from the local source. We only accept to delete vulnerabilities from the local source.

Parameters:

• vulnerability_id (string)

Status Codes:

• 204 No Content – Success.

• 403 Forbidden – Admin permission required.

• 422 Unprocessable Entity – Not possible to edit a vulnerability from the requested source.

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.

GET /search/{vendor}/{product}

Returns a list of vulnerabilities related to the product

Alias for /api/vulnerability/search/<string:vendor>/<string:product>

Parameters:

• vendor (string)

• product (string)

Status Codes:

• 200 OK – Success

GET /sighting

List all sightings

Query Parameters:

• 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

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:

• 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

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/{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/configInfo

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

Status Codes:

• 200 OK – Success

GET /system/dbInfo

Get more information about the current databases in use and when it was updated

Status Codes:

• 200 OK – Success

GET /system/info

Alias for /api/sytem/dbInfo

Status Codes:

• 200 OK – Success

GET /system/redis_up

Check if redis is up and running

Status Codes:

• 200 OK – Success

GET /user/

List all users

Only available to administrators.

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.

• [].metadata (any) – Metada related to the result.

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.

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.

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.

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.

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/last

Get the last vulnerabilities

Status Codes:

• 200 OK – Success

GET /vulnerability/last/{number}

Get the last vulnerabilities

Parameters:

• number (integer)

Status Codes:

• 200 OK – Success

GET /vulnerability/last/{source}

Get the last vulnerabilities

Parameters:

• source (string)

Status Codes:

• 200 OK – Success

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

Get the last vulnerabilities

Parameters:

• source (string)

• number (integer)

Status Codes:

• 200 OK – Success

GET /vulnerability/search/{vendor}/{product}

Returns a list of vulnerabilities related to the product

Returns a list of vulnerabilities related to the product.

Parameters:

• vendor (string)

• product (string)

Status Codes:

• 200 OK – Success

GET /vulnerability/{vulnerability_id}

Alias for /api/vulnerability/<string:vulnerability_id Get a vulnerability.

Parameters:

• vulnerability_id (string)

Query Parameters:

• with_meta (boolean) – Include metada.

Status Codes:

• 200 OK – Success

DELETE /vulnerability/{vulnerability_id}

Endpoint for deleting a vulnerability

Alias for /api/vulnerability/<string:vulnerability_id Delete a vulnerability from the local source. We only accept to delete vulnerabilities from the local source.

Parameters:

• vulnerability_id (string)

Status Codes:

• 204 No Content – Success.

• 403 Forbidden – Admin permission required.

• 422 Unprocessable Entity – Not possible to edit a vulnerability from the requested source.

Examples

Comments

Getting the list of comments:

$ curl -X 'GET' 'http://127.0.0.1:5000/api/comment/' -H 'accept: application/json'

Getting the list of comments made by a specific author:

$ curl -X 'GET' 'http://127.0.0.1:5000/api/comment/?author=john' -H 'accept: application/json'

Getting the list of comments related to a vulnerability:

$ curl -X 'GET' 'http://127.0.0.1:5000/api/comment/?vuln_id=cve-2024-38063' -H 'accept: application/json'

Getting the list of comments that are related to a Proof of Concept:

$ curl -X 'GET' 'http://127.0.0.1:5000/api/comment/?meta=[{"tags":["PoC"]}]' -H 'accept: application/json'