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) – Creation time of the bundle. (read only)

• description (string) – Description.

• meta (object) – Zero or more meta-fields.

• name (string) – Bundle name.

• 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) – Creation time of the bundle. (read only)

• [].data[].description (string) – Description.

• [].data[].meta (object) – Zero or more meta-fields.

• [].data[].name (string) – Bundle name.

• [].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) – Creation time of the bundle. (read only)

• [].data[].description (string) – Description.

• [].data[].meta (object) – Zero or more meta-fields.

• [].data[].name (string) – Bundle name.

• [].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) – Creation time of the bundle. (read only)

• description (string) – Description.

• meta (object) – Zero or more meta-fields.

• name (string) – Bundle name.

• 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

Get detailed information about a CAPEC.

Parameters:

• capec_id (string)

Status Codes:

• 200 OK – Success

GET /cisa_kev/

List all CISA KEV

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[].CVE (string) – CVE identifier (required)

• [].data[].EUVD (string) – EUVD identifier

• [].data[].cwes (string) – CWE identifiers

• [].data[].dateReported (string) – Date when reported

• [].data[].exploitationType (string) – Type of exploitation observed

• [].data[].notes (string) – Additional notes or links

• [].data[].originSource (string) – Source reporting the vulnerability

• [].data[].product (string) – Product affected by the vulnerability

• [].data[].shortDescription (string) – Short description of the vulnerability

• [].data[].threatActorsExploiting (string) – Threat actors exploiting the vulnerability

• [].data[].vendorProject (string) – Vendor or project name

• [].data[].vulnerabilityName (string) – Vulnerability name

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

GET /cnw_kev/

List all CNW KEV

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[].CVE (string) – CVE identifier (required)

• [].data[].EUVD (string) – EUVD identifier

• [].data[].cwes (string) – CWE identifiers

• [].data[].dateReported (string) – Date when reported

• [].data[].exploitationType (string) – Type of exploitation observed

• [].data[].notes (string) – Additional notes or links

• [].data[].originSource (string) – Source reporting the vulnerability

• [].data[].product (string) – Product affected by the vulnerability

• [].data[].shortDescription (string) – Short description of the vulnerability

• [].data[].threatActorsExploiting (string) – Threat actors exploiting the vulnerability

• [].data[].vendorProject (string) – Vendor or project name

• [].data[].vulnerabilityName (string) – Vulnerability name

• [].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/

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:

• vuln_id (string) – ID of a vulnerability that references one or more CWE identifiers.

• 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[].Potential_Mitigations (any) – Potential mitigations

• [].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 /emb3d/

List all Adversarial Techniques from MITRE EMB3D

Query Parameters:

• page (integer) – Number of the page.

• per_page (integer) – Maximum number of elements to return.

• vuln_id (string) – Vulnerability identifier.

Status Codes:

• 200 OK – Success

Request Headers:

• X-Fields – An optional fields mask

Response JSON Object:

• [].data[].CWE (object) – CWE (read only)

• [].data[].Type (string) – Type (read only)

• [].data[].description (string) – Description (read only)

• [].data[].id (string) – Identifiant (read only)

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

GET /emb3d/{emb3d_id}

Get detailed information about a MITRE EMB3D Adversarial Technique

Get detailed information about a MITRE EMB3D Adversarial Technique.

Parameters:

• emb3d_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.

GET /gcve/registry

List the GNAs from the local GCVE registry of the Vulnerability-Lookup instance

Query Parameters:

• page (integer) – Number of the page.

• per_page (integer) – Maximum number of elements to return.

• short_name (string) – Short name of the organization.

Status Codes:

• 200 OK – Success

Request Headers:

• X-Fields – An optional fields mask

Response JSON Object:

• [].data[].cpe_vendor_name (string) – Official CPE vendor name. (read only)

• [].data[].full_name (string) – Full legal name of the organization. (read only)

• [].data[].gcve_allocation (string) – URL of the interface used to allocate or register new vulnerabilities. (read only)

• [].data[].gcve_api (string) – URL of the API endpoint providing vulnerability data. (read only)

• [].data[].gcve_dump (string) – URL to a machine-readable dump (e.g., JSON) of vulnerability information. (read only)

• [].data[].gcve_pull_api (string) – URL of the interface compatible to retrieve the local GNA publications. (read only)

• [].data[].gcve_url (string) – URL to the public vulnerability disclosure website. (read only)

• [].data[].id (string) – Unique identifier for the GCVE Numbering Authority. (read only)

• [].data[].short_name (string) – Short name of the organization. (read only)

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

GET /gcve/registry/integrity

Verify the integrity of the local registry

Status Codes:

• 200 OK – Success

GET /organization/

List all organizations

Query Parameters:

• page (integer) – Number of the page.

• per_page (integer) – Maximum number of elements to return.

• id (integer) – ID of the organization.

• uuid (string) – UUID of the organization.

• name (string) – The name of the organization.

• gna_id (integer) – The reserved GNA identifier of the organization.

Status Codes:

• 200 OK – Success

Request Headers:

• X-Fields – An optional fields mask

Response JSON Object:

• [].data[].creation_timestamp (string) – Creation time of the organization. (read only)

• [].data[].description (string) – Description.

• [].data[].gna_id (integer) – The reserved GNA identifier of the organization.

• [].data[].id (string) – Organization id.

• [].data[].name (string) – Organization name.

• [].data[].short_name (string) – Organization short name.

• [].data[].updated_timestamp (string) – Updated time of the organization. (read only)

• [].data[].uuid (string) – Organization uuid.

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

GET /product/

List all products

Query Parameters:

• page (integer) – Number of the page.

• per_page (integer) – Maximum number of elements to return.

• uuid (string) – UUID of the product.

• name (string) – The name of the product.

• organization_name (string) – The name of the organization related to the product.

• organization_id (string) – The id of the organization related to the product.

• organization_uuid (string) – The uuid of the organization related to the product.

Status Codes:

• 200 OK – Success

Request Headers:

• X-Fields – An optional fields mask

Response JSON Object:

• [].data[].creation_timestamp (string) – Creation time of the product. (read only)

• [].data[].description (string) – Description.

• [].data[].id (string) – Product id.

• [].data[].name (string) – Product name.

• [].data[].updated_timestamp (string) – Updated time of the product. (read only)

• [].data[].uuid (string) – Product uuid.

• [].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.

  • Published Proof of Concept: A public proof of concept is available for this vulnerability.

  • 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.

• advisory_status (string) – Filter sightings by the status of the related advisory.

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.

DELETE /sighting

Delete sightings by filters (author, source, date)

Delete sightings by filters (author, source, date). At least one filter must be specified. At least one filter must be specified.

Query Parameters:

• author (string) – Author of the sightings to delete (login). Only the author themselves or an admin can delete.

• source (string) – Source of the sightings (supports partial match using ilike).

• date_from (string) – Delete sightings from this date (inclusive). Format: YYYY-MM-DD.

• date_to (string) – Delete sightings up to this date (inclusive). Format: YYYY-MM-DD.

Status Codes:

• 200 OK – Deleted sightings successfully.

• 403 Forbidden – Not allowed to delete these sightings.

• 404 Not Found – No sightings matched the filters.

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.

  • Published Proof of Concept: A public proof of concept is available for this vulnerability.

  • 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.

• advisory_status (string) – Filter sightings by the status of the related advisory.

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.

DELETE /sighting/

Delete sightings by filters (author, source, date)

Delete sightings by filters (author, source, date). At least one filter must be specified. At least one filter must be specified.

Query Parameters:

• author (string) – Author of the sightings to delete (login). Only the author themselves or an admin can delete.

• source (string) – Source of the sightings (supports partial match using ilike).

• date_from (string) – Delete sightings from this date (inclusive). Format: YYYY-MM-DD.

• date_to (string) – Delete sightings up to this date (inclusive). Format: YYYY-MM-DD.

Status Codes:

• 200 OK – Deleted sightings successfully.

• 403 Forbidden – Not allowed to delete these sightings.

• 404 Not Found – No sightings matched the filters.

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.

DELETE /sighting/{sighting_uuid}

Delete a single sighting by UUID

Delete a single sighting by its UUID.

Parameters:

• sighting_uuid (string)

Status Codes:

• 200 OK – Sighting deleted successfully.

• 403 Forbidden – Not allowed to delete this sighting.

• 404 Not Found – Sighting not found.

GET /stats/cwe/most_used

Returns the most used CWEs based on sightings

Query Parameters:

• limit (integer) – The top elements to take into account in the query.

• output (string) – The format of the output.

• period (string) – The period of the stats. Format: YYYY[-MM]

Status Codes:

• 200 OK – Success

GET /stats/vendors/ranking

Returns the vendors ranking.

Query Parameters:

• limit (integer) – The top elements to take into account in the query.

• output (string) – The format of the output.

• period (string) – The period of the stats. Format: YYYY[-MM]

• source (string) – The source of the vulnerability advisories.

Status Codes:

• 200 OK – Success

GET /stats/vulnerability/count

Returns the number of published/reserved vulnerabilities for a specific period.

Query Parameters:

• state (string) – The state of the advisory.

• period (string) – The period of the stats. Format: YYYY[-MM]

• source (string) – The source of the vulnerability advisories.

Status Codes:

• 200 OK – Success

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

Checks the heartbeats of the various processes

Checks the heartbeats of the various processes.

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.

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.

• 500 Internal Server Error – Internal server error.

POST /vlai/severity-classification

Involves a classification model aimed to assist in classifying vulnerabilities by severity based on their descriptions.

Request JSON Object:

• description (string)

• model (string)

Status Codes:

• 200 OK – Success.

• 500 Internal Server Error – Unexpected error.

• 503 Service Unavailable – Connection Error: Unable to reach ML-Gateway.

POST /vulnerability/

Endpoint for creating and editing vulnerabilities in the local source

Retrieve vulnerabilities with optional filtering and pagination.

Supports light mode for minimal data (returns only vulnerability ID and source). Create a vulnerability with the CVE version 5 format.

Query Parameters:

• light (string) – If ‘1’, returns only vulnerability ID and source

• cwe (string) – Filter vulnerabilities by a specific CWE ID

• since (string) – Retrieve vulnerabilities reported after the specified date.

• sort_order (string) – Sort order: ‘asc’ or ‘desc’

• date_sort (string) – Sort field: ‘’, ‘published’, ‘updated’, ‘reserved’

• per_page (string) – Maximum number of results (capped at 100)

• page (string) – Pagination page number

• source (string) – Optional source to filter vulnerabilities (e.g., ‘CVE’, ‘GHSA’, ‘PySec’)

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/

Retrieve vulnerabilities with optional filters

Retrieve vulnerabilities with optional filtering and pagination.

Supports light mode for minimal data (returns only vulnerability ID and source). Returns full vulnerability details by default, or only IDs and sources in light mode.

Query Parameters

sourcestr

Optional source to filter vulnerabilities (e.g., ‘CVE’, ‘GHSA’, ‘PySec’).

per_pageint, default=30

Maximum number of results (capped at 100).

date_sortstr

Field to sort by. Options: ‘’, ‘published’, ‘updated’, ‘reserved’.

sort_orderstr

Sort order: ‘asc’ or ‘desc’.

sincestr

Retrieve vulnerabilities published/updated after the specified date.

pageint

Pagination page number.

cwestr

Filter vulnerabilities by a specific CWE ID.

lightstr

If ‘1’, returns only (vulnerability_id, source) instead of full details.

Returns

list[dict[str, Any]] | list[tuple[str, str | None]]

Full vulnerability details or minimal tuples if light mode is enabled.

query string light:

If ‘1’, returns only vulnerability ID and source

query string cwe:

Filter vulnerabilities by a specific CWE ID

query string since:

Retrieve vulnerabilities reported after the specified date.

query string sort_order:

Sort order: ‘asc’ or ‘desc’

query string date_sort:

Sort field: ‘’, ‘published’, ‘updated’, ‘reserved’

query string per_page:

Maximum number of results (capped at 100)

query string page:

Pagination page number

query string source:

Optional source to filter vulnerabilities (e.g., ‘CVE’, ‘GHSA’, ‘PySec’)

status 200:

Success

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/search/{vendor}/{product}

Returns a list of vulnerabilities related to the vendor and product

Returns a list of vulnerabilities related to the product. Optionnaly filter vulnerabilities published or updated after the specified date (format: YYYY-MM-DD).

Parameters:

• vendor (string)

• product (string)

Query Parameters:

• page (integer) – Number of the page.

• per_page (integer) – Maximum number of elements to return.

• since (string) – Filter vulnerabilities published or updated after the specified date (format: YYYY-MM-DD).

Status Codes:

• 200 OK – Success

GET /vulnerability/{vulnerability_id}

Get a vulnerability with its id

Get a vulnerability.

Parameters:

• vulnerability_id (string)

Query Parameters:

• with_meta (boolean) – Include metada.

• with_linked (boolean) – Include the linked vulnerabilities.

• with_comments (boolean) – Include the comments.

• with_bundles (boolean) – Include the bundles.

• with_sightings (boolean) – Include the sightings.

Status Codes:

• 200 OK – Success

DELETE /vulnerability/{vulnerability_id}

Endpoint for deleting a vulnerability

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'