API v1#
PyVulnerabilityLookup is a Python library to access Vulnerability-Lookup via its REST API.
OpenAPI specification#
.. http:get:: /browse/ :synopsis: Get the known vendors
Get the known vendors
Get the known vendors.
:status 200: Success
.. http:get:: /browse/{vendor} :synopsis: Get the known products for a vendor
Get the known products for a vendor
Get the known products for a vendor.
:param string vendor: :status 200: Success
.. http:get:: /bundle/ :synopsis: List all bundles
List all bundles
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string uuid: UUID of the bundle. :query string author: Author (login) of the bundle. :query string vuln_id: Id of a vulnerability referenced by the bundle. :query string meta: Query for the meta JSON field. Example: meta=[{‘tags’: [‘tcp’]}] :query string date_from: The date of the bundles must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the bundles must be smaller or equal than this value. Format: YYYY-MM-DD :status 200: Success :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the bundle. (read only) :>json string [].data[].description: Description. :>json object [].data[].meta: Zero or more meta-fields. :>json string [].data[].name: Bundle name. :>json string [].data[].related_vulnerabilities[]: :>json string [].data[].timestamp: Updated time of the bundle. (read only) :>json string [].data[].uuid: Bundle id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metada related to the result.
.. http:post:: /bundle/ :synopsis: null
Create a bundle.
:<json any author: (read only) :<json string creation_timestamp: Creation time of the bundle. (read only) :<json string description: Description. :<json object meta: Zero or more meta-fields. :<json string name: Bundle name. :<json string related_vulnerabilities[]: :<json string timestamp: Updated time of the bundle. (read only) :<json string uuid: Bundle id. :<json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
:status 201: Success. :status 400: JSON validation failed or incorrect payload to instantiate a bundle. :status 403: Administrator permission required. :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the bundle. (read only) :>json string [].data[].description: Description. :>json object [].data[].meta: Zero or more meta-fields. :>json string [].data[].name: Bundle name. :>json string [].data[].related_vulnerabilities[]: :>json string [].data[].timestamp: Updated time of the bundle. (read only) :>json string [].data[].uuid: Bundle id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metada related to the result.
.. http:delete:: /bundle/ :synopsis: Delete bundles by vulnerability_lookup_origin
Delete bundles by vulnerability_lookup_origin
Delete bundles by vulnerability_lookup_origin (admin only).
:query string vulnerability_lookup_origin: Delete bundles from this origin instance UUID. :status 200: Deleted bundles successfully. :status 400: Invalid UUID format. :status 403: Admin permission required. :status 404: No bundles matched the filter.
.. http:get:: /bundle/{bundle_uuid} :synopsis: null
Get a bundle with its UUID.
:param string bundle_uuid: :status 200: Success. :status 404: Bundle not found. :reqheader X-Fields: An optional fields mask
:>json any author: (read only) :>json string creation_timestamp: Creation time of the bundle. (read only) :>json string description: Description. :>json object meta: Zero or more meta-fields. :>json string name: Bundle name. :>json string related_vulnerabilities[]: :>json string timestamp: Updated time of the bundle. (read only) :>json string uuid: Bundle id. :>json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
.. http:delete:: /bundle/{bundle_uuid} :synopsis: Endpoint for deleting a bundle
Endpoint for deleting a bundle
Delete a bundle. Only an admin can delete a bundle.
:param string bundle_uuid: :status 204: Success. :status 403: Administrator permission required or not the author of the bundle. :status 404: Bundle not found.
.. http:get:: /capec/ :synopsis: List all CAPECs
List all CAPECs
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].@Description: Description. (read only) :>json string [].data[].@ID: Identifiant. (read only) :>json string [].data[].@Name: Name. (read only) :>json any [].metadata: Metada related to the result.
.. http:get:: /capec/{capec_id} :synopsis: Get detailed information about a CAPEC
Get detailed information about a CAPEC
Get detailed information about a CAPEC.
:param string capec_id: :status 200: Success
.. http:get:: /cisa_kev/ :synopsis: List all CISA KEV
List all CISA KEV
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].CVE: CVE identifier (required) :>json string [].data[].EUVD: EUVD identifier :>json string [].data[].cwes: CWE identifiers :>json string [].data[].dateReported: Date when reported :>json string [].data[].exploitationType: Type of exploitation observed :>json string [].data[].notes: Additional notes or links :>json string [].data[].originSource: Source reporting the vulnerability :>json string [].data[].product: Product affected by the vulnerability :>json string [].data[].shortDescription: Short description of the vulnerability :>json string [].data[].threatActorsExploiting: Threat actors exploiting the vulnerability :>json string [].data[].vendorProject: Vendor or project name :>json string [].data[].vulnerabilityName: Vulnerability name :>json any [].metadata: Metada related to the result.
.. http:get:: /cnw_kev/ :synopsis: List all CNW KEV
List all CNW KEV
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].CVE: CVE identifier (required) :>json string [].data[].EUVD: EUVD identifier :>json string [].data[].cwes: CWE identifiers :>json string [].data[].dateReported: Date when reported :>json string [].data[].exploitationType: Type of exploitation observed :>json string [].data[].notes: Additional notes or links :>json string [].data[].originSource: Source reporting the vulnerability :>json string [].data[].product: Product affected by the vulnerability :>json string [].data[].shortDescription: Short description of the vulnerability :>json string [].data[].threatActorsExploiting: Threat actors exploiting the vulnerability :>json string [].data[].vendorProject: Vendor or project name :>json string [].data[].vulnerabilityName: Vulnerability name :>json any [].metadata: Metada related to the result.
.. http:get:: /comment/ :synopsis: List all comments
List all comments
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string uuid: UUID of the comment. :query string vuln_id: Vulnerability related to the comment. :query string author: Author of the comment. :query string meta: Query for the meta JSON field. Example: meta=[{‘tags’: [‘PoC’]}] :query string date_from: The date of the comments must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the comments must be smaller or equal than this value. Format: YYYY-MM-DD :status 200: Success :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the comment. (read only) :>json string [].data[].description: Description. :>json string [].data[].description_format: Description format (markdown or text). :>json object [].data[].meta: Zero or more meta-fields. :>json string [].data[].related_vulnerabilities[]: :>json string [].data[].timestamp: Updated time of the comment. (read only) :>json string [].data[].title: Comment title. :>json string [].data[].uuid: Comment uuid. :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metada related to the result.
.. http:post:: /comment/ :synopsis: Create a new comment related to a security advisory (vulnerability)
Create a new comment related to a security advisory (vulnerability)
Create a comment related to a security advisory.
:<json any author: (read only) :<json string creation_timestamp: Creation time of the comment. (read only) :<json string description: Description. :<json string description_format: Description format (markdown or text). :<json object meta: Zero or more meta-fields. :<json string related_vulnerabilities[]: :<json string timestamp: Updated time of the comment. (read only) :<json string title: Comment title. :<json string uuid: Comment uuid. :<json string vulnerability: Vulnerability id. :<json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
:status 201: Success. :status 400: JSON validation failed or incorrect payload to instantiate a comment. :status 403: Commenter permission required or not the author of the comment. :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the comment. (read only) :>json string [].data[].description: Description. :>json string [].data[].description_format: Description format (markdown or text). :>json object [].data[].meta: Zero or more meta-fields. :>json string [].data[].related_vulnerabilities[]: :>json string [].data[].timestamp: Updated time of the comment. (read only) :>json string [].data[].title: Comment title. :>json string [].data[].uuid: Comment uuid. :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metada related to the result.
.. http:delete:: /comment/ :synopsis: Delete comments by vulnerability_lookup_origin
Delete comments by vulnerability_lookup_origin
Delete comments by vulnerability_lookup_origin (admin only).
:query string vulnerability_lookup_origin: Delete comments from this origin instance UUID. :status 200: Deleted comments successfully. :status 400: Invalid UUID format. :status 403: Admin permission required. :status 404: No comments matched the filter.
.. http:get:: /comment/{comment_uuid} :synopsis: null
Get a comment with its UUID.
:param string comment_uuid: :status 200: Success. :status 404: Comment not found. :reqheader X-Fields: An optional fields mask
:>json any author: (read only) :>json string creation_timestamp: Creation time of the comment. (read only) :>json string description: Description. :>json string description_format: Description format (markdown or text). :>json object meta: Zero or more meta-fields. :>json string related_vulnerabilities[]: :>json string timestamp: Updated time of the comment. (read only) :>json string title: Comment title. :>json string uuid: Comment uuid. :>json string vulnerability: Vulnerability id. :>json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
.. http:delete:: /comment/{comment_uuid} :synopsis: Endpoint for deleting a comment
Endpoint for deleting a comment
Delete a comment.
:param string comment_uuid: :status 204: Success. :status 403: Commenter permission required or not the author of the comment. :status 404: Comment not found.
.. http:get:: /cwe/ :synopsis: List all CWEs
List all CWEs
:query string vuln_id: ID of a vulnerability that references one or more CWE identifiers. :query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].@Abstraction: Abstraction of the CWE (required) :>json string [].data[].@ID: CWE ID (required) :>json string [].data[].@Name: Name of the CWE (required) :>json string [].data[].@Status: Status of the CWE (required) :>json string [].data[].@Structure: Structure of the CWE (required) :>json string [].data[].Description: Description of the CWE (required) :>json any [].data[].Potential_Mitigations: Potential mitigations :>json any [].data[].Related_Weaknesses: Related weaknesses :>json any [].metadata: Metada related to the result.
.. http:get:: /cwe/{cwe_id} :synopsis: Get detailed information about a CWE
Get detailed information about a CWE
Get detailed information about a CWE.
:param string cwe_id: :status 200: Success
.. http:get:: /emb3d/ :synopsis: List all Adversarial Techniques from MITRE EMB3D
List all Adversarial Techniques from MITRE EMB3D
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string vuln_id: Vulnerability identifier. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json object [].data[].CWE: CWE (read only) :>json string [].data[].Type: Type (read only) :>json string [].data[].description: Description (read only) :>json string [].data[].id: Identifiant (read only) :>json any [].metadata: Metada related to the result.
.. http:get:: /emb3d/{emb3d_id} :synopsis: Get detailed information about a MITRE EMB3D Adversarial Technique
Get detailed information about a MITRE EMB3D Adversarial Technique
Get detailed information about a MITRE EMB3D Adversarial Technique.
:param string emb3d_id: :status 200: Success
.. http:get:: /epss/{vulnerability_id} :synopsis: Get the EPSS score of a vulnerability
Get the EPSS score of a vulnerability
Get the EPSS score of a vulnerability.
:param string vulnerability_id: :status 200: Success. :status 404: EPSS score not found. :status 502: Bad Gateway: Invalid response from EPSS service. :status 503: Service Unavailable: Unable to reach EPSS service or misconfigured.
.. http:get:: /gcve/registry :synopsis: List the GNAs from the local GCVE registry of the Vulnerability-Lookup instance
List the GNAs from the local GCVE registry of the Vulnerability-Lookup instance
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string short_name: Short name of the organization. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].cpe_vendor_name: Official CPE vendor name. (read only) :>json string [].data[].full_name: Full legal name of the organization. (read only) :>json string [].data[].gcve_allocation: URL of the interface used to allocate or register new vulnerabilities. (read only) :>json string [].data[].gcve_api: URL of the API endpoint providing vulnerability data. (read only) :>json string [].data[].gcve_dump: URL to a machine-readable dump (e.g., JSON) of vulnerability information. (read only) :>json string [].data[].gcve_pull_api: URL of the interface compatible to retrieve the local GNA publications. (read only) :>json string [].data[].gcve_url: URL to the public vulnerability disclosure website. (read only) :>json string [].data[].id: Unique identifier for the GCVE Numbering Authority. (read only) :>json string [].data[].short_name: Short name of the organization. (read only) :>json any [].metadata: Metada related to the result.
.. http:get:: /gcve/registry/integrity :synopsis: Verify the integrity of the local registry
Verify the integrity of the local registry
:status 200: Success
.. http:get:: /kev :synopsis: List KEV entries with pagination and filtering
List KEV entries with pagination and filtering
:query integer page: Page number :query integer per_page: Items per page (max 1000) :query string vuln_id: Filter by vulnerability ID :query string status_reason: :query boolean exploited: Filter by exploited status :query string vulnerability_lookup_origin: Filter by origin instance UUID :query string date_from: Filter from date (YYYY-MM-DD) :query string date_to: Filter to date (YYYY-MM-DD) :query string author: Filter by author login :status 200: Success :reqheader X-Fields: An optional fields mask
:>json object data[].characteristics: Technical characteristics :>json object data[].evidence[].confidence: Confidence (number 0.0-1.0 or string) :>json object data[].evidence[].details: Implementation-specific details :>json object data[].evidence[].signal: Evidence signal (string or array of strings) :>json string data[].evidence[].source: Evidence source (required) (required) :>json string data[].evidence[].type: Evidence type (optional) :>json any data[].gcve: GCVE origin metadata for the KEV assertion :>json object data[].references: Related references :>json object data[].scope: Geographical/sectoral context :>json boolean data[].status.exploited: Exploitation observed (required) :>json string data[].status.status_reason: Status reason (required) :>json string data[].status.status_updated_at: Status update time (required) :>json object data[].timestamps: Temporal context :>json string data[].uuid: KEV entry UUID (read only) :>json string data[].vulnerability.altId[]: :>json string data[].vulnerability.vulnId: Vulnerability ID (required) :>json integer metadata.count: Total number of the items of the data. (read only) :>json integer metadata.page: Number of the page. (read only) :>json integer metadata.per_page: Requested limit data. (read only)
.. http:post:: /kev :synopsis: Create new KEV entry (requires reporter or admin role)
Create new KEV entry (requires reporter or admin role)
:status 200: Success
.. http:get:: /kev/ :synopsis: List KEV entries with pagination and filtering
List KEV entries with pagination and filtering
:query integer page: Page number :query integer per_page: Items per page (max 1000) :query string vuln_id: Filter by vulnerability ID :query string status_reason: :query boolean exploited: Filter by exploited status :query string vulnerability_lookup_origin: Filter by origin instance UUID :query string date_from: Filter from date (YYYY-MM-DD) :query string date_to: Filter to date (YYYY-MM-DD) :query string author: Filter by author login :status 200: Success :reqheader X-Fields: An optional fields mask
:>json object data[].characteristics: Technical characteristics :>json object data[].evidence[].confidence: Confidence (number 0.0-1.0 or string) :>json object data[].evidence[].details: Implementation-specific details :>json object data[].evidence[].signal: Evidence signal (string or array of strings) :>json string data[].evidence[].source: Evidence source (required) (required) :>json string data[].evidence[].type: Evidence type (optional) :>json any data[].gcve: GCVE origin metadata for the KEV assertion :>json object data[].references: Related references :>json object data[].scope: Geographical/sectoral context :>json boolean data[].status.exploited: Exploitation observed (required) :>json string data[].status.status_reason: Status reason (required) :>json string data[].status.status_updated_at: Status update time (required) :>json object data[].timestamps: Temporal context :>json string data[].uuid: KEV entry UUID (read only) :>json string data[].vulnerability.altId[]: :>json string data[].vulnerability.vulnId: Vulnerability ID (required) :>json integer metadata.count: Total number of the items of the data. (read only) :>json integer metadata.page: Number of the page. (read only) :>json integer metadata.per_page: Requested limit data. (read only)
.. http:post:: /kev/ :synopsis: Create new KEV entry (requires reporter or admin role)
Create new KEV entry (requires reporter or admin role)
:status 200: Success
.. http:delete:: /kev/catalog/{catalog_uuid} :synopsis: Delete all KEV entries from a specific catalog (admin only)
Delete all KEV entries from a specific catalog (admin only)
:param string catalog_uuid: :status 200: Success
.. http:get:: /kev/{kev_uuid} :synopsis: Get single KEV entry
Get single KEV entry
:param string kev_uuid: :status 200: Success :reqheader X-Fields: An optional fields mask
:>json object characteristics: Technical characteristics :>json object evidence[].confidence: Confidence (number 0.0-1.0 or string) :>json object evidence[].details: Implementation-specific details :>json object evidence[].signal: Evidence signal (string or array of strings) :>json string evidence[].source: Evidence source (required) (required) :>json string evidence[].type: Evidence type (optional) :>json any gcve: GCVE origin metadata for the KEV assertion :>json object references: Related references :>json object scope: Geographical/sectoral context :>json boolean status.exploited: Exploitation observed (required) :>json string status.status_reason: Status reason (required) :>json string status.status_updated_at: Status update time (required) :>json object timestamps: Temporal context :>json string uuid: KEV entry UUID (read only) :>json string vulnerability.altId[]: :>json string vulnerability.vulnId: Vulnerability ID (required)
.. http:delete:: /kev/{kev_uuid} :synopsis: Delete KEV entry (admin only)
Delete KEV entry (admin only)
:param string kev_uuid: :status 200: Success
.. http:put:: /kev/{kev_uuid} :synopsis: Update KEV entry (author or admin only)
Update KEV entry (author or admin only)
:param string kev_uuid: :status 200: Success
.. http:get:: /organization/ :synopsis: List all organizations
List all organizations
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query integer id: ID of the organization. :query string uuid: UUID of the organization. :query string name: The name of the organization. :query integer gna_id: The reserved GNA identifier of the organization. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].creation_timestamp: Creation time of the organization. (read only) :>json string [].data[].description: Description. :>json integer [].data[].gna_id: The reserved GNA identifier of the organization. :>json string [].data[].id: Organization id. :>json string [].data[].name: Organization name. :>json string [].data[].short_name: Organization short name. :>json string [].data[].updated_timestamp: Updated time of the organization. (read only) :>json string [].data[].uuid: Organization uuid. :>json any [].metadata: Metada related to the result.
.. http:get:: /product/ :synopsis: List all products
List all products
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string uuid: UUID of the product. :query string name: The name of the product. :query string organization_name: The name of the organization related to the product. :query string organization_id: The id of the organization related to the product. :query string organization_uuid: The uuid of the organization related to the product. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json string [].data[].creation_timestamp: Creation time of the product. (read only) :>json string [].data[].description: Description. :>json string [].data[].id: Product id. :>json string [].data[].name: Product name. :>json string [].data[].updated_timestamp: Updated time of the product. (read only) :>json string [].data[].uuid: Product uuid. :>json any [].metadata: Metada related to the result.
.. http:get:: /rulezet/search_rules_by_vulnerabilities/{vulnerability_id} :synopsis: Get rules from Rulezet by vulnerability id
Get rules from Rulezet by vulnerability id
Get rules from Rulezet by vulnerability id.
:param string vulnerability_id: :query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success. :status 404: Rule not found in Rulezet. :status 502: Bad Gateway: Invalid response from Rulezet. :status 503: Service Unavailable: Unable to reach Rulezet or misconfigured. :reqheader X-Fields: An optional fields mask
:>json string [].data[].creation_date: Date the ule was created. (required) :>json string [].data[].description: Description of the rule. (required) :>json string [].data[].detail_url: URL of the rule. (required) :>json string [].data[].format: Format of the rule. (required) :>json integer [].data[].id: Rule ID. (required) :>json string [].data[].raw: raw version of the rule. (required) :>json string [].data[].title: Title of the rule. (required) :>json string [].data[].updated_date: Date the rule was updated. (required) :>json string [].data[].uuid: Rule UUID. (required) :>json string [].data[].vulnerability_id: Related vulnerability. (required) :>json any [].metadata: Metada related to the result.
.. http:get:: /sighting :synopsis: List all sightings
List all sightings
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string uuid: UUID of the sighting. :query string type: 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. :query string vuln_id: Vulnerability related to the sighting. :query string author: Author of the sighting (login). :query string date_from: The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD :query string source: Source of the sighting. :query string advisory_status: Filter sightings by the status of the related advisory. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the sighting. :>json string [].data[].source: The source of the sighting (Fediverse status URI, link, tool, etc.). :>json string [].data[].type: Type of the sighting. :>json string [].data[].uuid: Sighting UUID. (read only) :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metadata related to the result.
.. http:post:: /sighting :synopsis: Create a new sighting
Create a new sighting
Create a new sighting.
:<json any author: (read only) :<json string creation_timestamp: Creation time of the sighting. :<json string source: The source of the sighting (Fediverse status URI, link, tool, etc.). :<json string type: Type of the sighting. :<json string uuid: Sighting UUID. (read only) :<json string vulnerability: Vulnerability id. :<json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
:status 201: Success. :status 400: Incorrect payload to instantiate a sighting. :status 409: Duplicate sighting. :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the sighting. :>json string [].data[].source: The source of the sighting (Fediverse status URI, link, tool, etc.). :>json string [].data[].type: Type of the sighting. :>json string [].data[].uuid: Sighting UUID. (read only) :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metadata related to the result.
.. http:delete:: /sighting :synopsis: Delete sightings by filters (author, source, date)
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 string author: Author of the sightings to delete (login). Only the author themselves or an admin can delete. :query string source: Source of the sightings (supports partial match using ilike). :query string date_from: Delete sightings from this date (inclusive). Format: YYYY-MM-DD. :query string date_to: Delete sightings up to this date (inclusive). Format: YYYY-MM-DD. :query string vulnerability_lookup_origin: Delete sightings from this origin instance UUID. :status 200: Deleted sightings successfully. :status 403: Not allowed to delete these sightings. :status 404: No sightings matched the filters.
.. http:get:: /sighting/ :synopsis: List all sightings
List all sightings
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string uuid: UUID of the sighting. :query string type: 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. :query string vuln_id: Vulnerability related to the sighting. :query string author: Author of the sighting (login). :query string date_from: The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD :query string source: Source of the sighting. :query string advisory_status: Filter sightings by the status of the related advisory. :status 200: Success :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the sighting. :>json string [].data[].source: The source of the sighting (Fediverse status URI, link, tool, etc.). :>json string [].data[].type: Type of the sighting. :>json string [].data[].uuid: Sighting UUID. (read only) :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metadata related to the result.
.. http:post:: /sighting/ :synopsis: Create a new sighting
Create a new sighting
Create a new sighting.
:<json any author: (read only) :<json string creation_timestamp: Creation time of the sighting. :<json string source: The source of the sighting (Fediverse status URI, link, tool, etc.). :<json string type: Type of the sighting. :<json string uuid: Sighting UUID. (read only) :<json string vulnerability: Vulnerability id. :<json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
:status 201: Success. :status 400: Incorrect payload to instantiate a sighting. :status 409: Duplicate sighting. :reqheader X-Fields: An optional fields mask
:>json any [].data[].author: (read only) :>json string [].data[].creation_timestamp: Creation time of the sighting. :>json string [].data[].source: The source of the sighting (Fediverse status URI, link, tool, etc.). :>json string [].data[].type: Type of the sighting. :>json string [].data[].uuid: Sighting UUID. (read only) :>json string [].data[].vulnerability: Vulnerability id. :>json string [].data[].vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only) :>json any [].metadata: Metadata related to the result.
.. http:delete:: /sighting/ :synopsis: Delete sightings by filters (author, source, date)
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 string author: Author of the sightings to delete (login). Only the author themselves or an admin can delete. :query string source: Source of the sightings (supports partial match using ilike). :query string date_from: Delete sightings from this date (inclusive). Format: YYYY-MM-DD. :query string date_to: Delete sightings up to this date (inclusive). Format: YYYY-MM-DD. :query string vulnerability_lookup_origin: Delete sightings from this origin instance UUID. :status 200: Deleted sightings successfully. :status 403: Not allowed to delete these sightings. :status 404: No sightings matched the filters.
.. http:get:: /sighting/{sighting_uuid} :synopsis: null
Get a sighting with its UUID.
:param string sighting_uuid: :status 200: Success. :status 404: Sighting not found. :reqheader X-Fields: An optional fields mask
:>json any author: (read only) :>json string creation_timestamp: Creation time of the sighting. :>json string source: The source of the sighting (Fediverse status URI, link, tool, etc.). :>json string type: Type of the sighting. :>json string uuid: Sighting UUID. (read only) :>json string vulnerability: Vulnerability id. :>json string vulnerability_lookup_origin: UUID of the Vulnerability-Lookup origin instance. (read only)
.. http:delete:: /sighting/{sighting_uuid} :synopsis: Delete a single sighting by UUID
Delete a single sighting by UUID
Delete a single sighting by its UUID.
:param string sighting_uuid: :status 200: Sighting deleted successfully. :status 403: Not allowed to delete this sighting. :status 404: Sighting not found.
.. http:get:: /stats/assigners/ranking :synopsis: null
Returns the assigners ranking.
:query integer limit: The top elements to take into account in the query. :query string output: The format of the output. :query string period: The period of the stats. Format: YYYY[-MM] :query string source: The source of the vulnerability advisories. :status 200: Success
.. http:get:: /stats/cwe/most_used :synopsis: null
Returns the most used CWEs based on sightings
:query integer limit: The top elements to take into account in the query. :query string output: The format of the output. :query string period: The period of the stats. Format: YYYY[-MM] :status 200: Success
.. http:get:: /stats/vendors/ranking :synopsis: null
Returns the vendors ranking.
:query integer limit: The top elements to take into account in the query. :query string output: The format of the output. :query string period: The period of the stats. Format: YYYY[-MM] :query string source: The source of the vulnerability advisories. :status 200: Success
.. http:get:: /stats/vulnerability/count :synopsis: null
Returns the number of published/reserved vulnerabilities for a specific period.
:query string state: The state of the advisory. :query string period: The period of the stats. Format: YYYY[-MM] :query string source: The source of the vulnerability advisories. :status 200: Success
.. http:get:: /stats/vulnerability/most_commented :synopsis: null
Returns the most commented vulnerabilities.
:query string date_from: The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD :query integer limit: The top elements to take into account in the query. :query string output: The format of the output. :status 200: Success
.. http:get:: /stats/vulnerability/most_sighted :synopsis: null
Returns the most sighted vulnerabilities.
:query string date_from: The date of the sightings must be bigger or equal than this value. Format: YYYY-MM-DD :query string date_to: The date of the sightings must be smaller or equal than this value. Format: YYYY-MM-DD :query string sighting_type: The type of the sighting. :query integer limit: The top elements to take into account in the query. :query string output: The format of the output. :status 200: Success
.. http:get:: /system/checkProcess :synopsis: Checks the heartbeats of the various processes
Checks the heartbeats of the various processes
Checks the heartbeats of the various processes.
:status 200: Success
.. http:get:: /system/checkSMTP :synopsis: Checks the SMTP connection
Checks the SMTP connection
Checks the SMTP connection.
:status 200: Success
.. http:get:: /system/configInfo :synopsis: Returns non-sensitive information about the configuration of the system
Returns non-sensitive information about the configuration of the system
Returns non-sensitive information about the configuration of the system.
:status 200: Success
.. http:get:: /system/dbInfo :synopsis: 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
Returns information about the current sources in the Kvrocks database in use and when it was updated.
:status 200: Success
.. http:get:: /system/pgInfo :synopsis: Returns information about the PostgreSQL database
Returns information about the PostgreSQL database
Returns information about the PostgreSQL database.
:status 200: Success
.. http:get:: /system/redis_up :synopsis: Check if Valkey/Redis is up and running
Check if Valkey/Redis is up and running
Alias for /api/system/redis_up
:status 200: Success
.. http:get:: /system/valkey_up :synopsis: Check if Valkey/Redis is up and running
Check if Valkey/Redis is up and running
Check if Valkey/Redis is up and running.
:status 200: Success
.. http:get:: /user/ :synopsis: List all users
List all users
Only available to administrators.
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :status 200: Success. :status 403: Admin permission required. :reqheader X-Fields: An optional fields mask
:>json string [].data[].created_at: Creation time of the user. (read only) :>json boolean [].data[].is_admin: Boolean specifying whether the user is administrator. :>json boolean [].data[].is_commenter: Boolean specifying whether the user is commenter. :>json boolean [].data[].is_reporter: Boolean specifying whether the user is reporter. :>json string [].data[].last_seen: Last seen time of the user. (read only) :>json string [].data[].login: User login. :>json string [].data[].uuid: User UUID. :>json any [].metadata: Metada related to the result.
.. http:post:: /user/ :synopsis: null
Create a non-admin user.
:query integer page: Number of the page. :query integer per_page: Maximum number of elements to return.
:<json string email: :<json string login: :<json string name: :<json string organisation:
:status 200: Success :status 201: Success. :status 403: Self-registration is disabled. :status 422: Email address not accepted (disposable email detected, blocked domain, or invalid domain). :status 429: Too many requests (maximum 3 registrations/hour per IP) :reqheader X-Fields: An optional fields mask
:>json string created_at: Creation time of the user. (read only) :>json boolean is_admin: Boolean specifying whether the user is administrator. :>json boolean is_commenter: Boolean specifying whether the user is commenter. :>json boolean is_reporter: Boolean specifying whether the user is reporter. :>json string last_seen: Last seen time of the user. (read only) :>json string login: User login. :>json string uuid: User UUID.
.. http:post:: /user/api_key :synopsis: 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
Regenerating the API key of the authenticated user with the current API key.
:<json string apikey: The current API key of the user.
:status 200: Success. :status 403: Wrong API key submitted. :status 404: User not found. :reqheader X-Fields: An optional fields mask
:>json string created_at: Creation time of the user. (read only) :>json boolean is_admin: Boolean specifying whether the user is administrator. :>json boolean is_commenter: Boolean specifying whether the user is commenter. :>json boolean is_reporter: Boolean specifying whether the user is reporter. :>json string last_seen: Last seen time of the user. (read only) :>json string login: User login. :>json string uuid: User UUID.
.. http:get:: /user/me :synopsis: Get information about the currently authenticated user
Get information about the currently authenticated user
Get information about the currently authenticated user.
:status 200: Success. :status 404: User not found. :reqheader X-Fields: An optional fields mask
:>json string created_at: Creation time of the user. (read only) :>json boolean is_admin: Boolean specifying whether the user is administrator. :>json boolean is_commenter: Boolean specifying whether the user is commenter. :>json boolean is_reporter: Boolean specifying whether the user is reporter. :>json string last_seen: Last seen time of the user. (read only) :>json string login: User login. :>json string uuid: User UUID.
.. http:delete:: /user/{user_id} :synopsis: Endpoint for deleting a user
Endpoint for deleting a user
Delete a user.
:param integer user_id: :status 204: Success. :status 403: Administrator permission required or not the current user. :status 404: User not found. :status 500: Internal server error.
.. http:post:: /vlai/severity-classification :synopsis: null
Classify vulnerabilities by severity based on their descriptions.
:<json string description: :<json string model:
:status 200: Success. :status 500: Unexpected error. :status 502: Bad content: Invalid response from ML-Gateway. :status 503: Connection Error: Unable to reach ML-Gateway.
.. http:get:: /vulnerability/ :synopsis: Retrieve vulnerabilities with optional filters
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#
source : str
Optional source to filter vulnerabilities (e.g., ‘CVE’, ‘GHSA’, ‘PySec’).
per_page : int, default=30
Maximum number of results (capped at 100).
date_sort : str
Field to sort by. Options: ‘’, ‘published’, ‘updated’, ‘reserved’.
sort_order : str
Sort order: ‘asc’ or ‘desc’.
since : str
Retrieve vulnerabilities published/updated after the specified date.
page : int
Pagination page number.
cwe : str
Filter vulnerabilities by a specific CWE ID.
product : str
Optional product name to filter vulnerabilities (case-insensitive). If set, the endpoint returns vulnerabilities related to this product across all vendors. Use with assigner to further narrow results.
assigner : str
Optional CNA/assigner short name to filter results (case-insensitive). Only effective when used with product or vendor filters.
light : str
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 product: Optional product name to filter vulnerabilities (case-insensitive). When provided, results are returned for the product across all vendors. :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 data source to filter vulnerabilities (e.g., ‘cvelistv5’, ‘github’, ‘nvd’) :status 200: Success
.. http:post:: /vulnerability/ :synopsis: Endpoint for creating and editing vulnerabilities in the local source
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 string product: Optional product name to filter vulnerabilities (case-insensitive). When provided, results are returned for the product across all vendors. :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 data source to filter vulnerabilities (e.g., ‘cvelistv5’, ‘github’, ‘nvd’)
:<json string data:
:status 200: Success. :status 400: JSON validation failed. :status 403: Reporter permission required. :status 422: Not possible to edit a vulnerability from the requested source.
.. http:get:: /vulnerability/browse/ :synopsis: Get the known vendors
Get the known vendors
Get the known vendors.
:status 200: Success
.. http:get:: /vulnerability/browse/assigners :synopsis: Get the known CNAs
Get the known CNAs
Get the known CNAs.
:status 200: Success
.. http:get:: /vulnerability/cpesearch/{cpe} :synopsis: Get vulnerabilities by CPE (based on the extracted CPE vendor and product)
Get vulnerabilities by CPE (based on the extracted CPE vendor and product)
Get vulnerabilities by CPE (based on the extracted CPE vendor and product).
:param string cpe: :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., ‘cvelistv5’, ‘nvd’) :status 200: Success. :status 404: No match found in the CPE string.
.. http:get:: /vulnerability/last :synopsis: Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results. Supports light mode for minimal data and provides backward-compatible routes.The light mode only returns the vulnerability id and the sources. Supports light mode for minimal data and provides backward-compatible routes. The light mode only returns the vulnerability id and the sources.
:query integer page: Number of the page. :query string cwe: CWE mentioned in the vulnerability. :status 200: Success
.. http:get:: /vulnerability/last/{number} :synopsis: Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results. Supports light mode for minimal data and provides backward-compatible routes.The light mode only returns the vulnerability id and the sources. Supports light mode for minimal data and provides backward-compatible routes. The light mode only returns the vulnerability id and the sources.
:param integer number: :query integer page: Number of the page. :query string cwe: CWE mentioned in the vulnerability. :status 200: Success
.. http:get:: /vulnerability/last/{source} :synopsis: Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results. Supports light mode for minimal data and provides backward-compatible routes.The light mode only returns the vulnerability id and the sources. Supports light mode for minimal data and provides backward-compatible routes. The light mode only returns the vulnerability id and the sources.
:param string source: :query integer page: Number of the page. :query string cwe: CWE mentioned in the vulnerability. :status 200: Success
.. http:get:: /vulnerability/last/{source}/{number} :synopsis: Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results
Retrieve the latest vulnerabilities, with optional filters for source and number of results. Supports light mode for minimal data and provides backward-compatible routes.The light mode only returns the vulnerability id and the sources. Supports light mode for minimal data and provides backward-compatible routes. The light mode only returns the vulnerability id and the sources.
:param string source: :param integer number: :query integer page: Number of the page. :query string cwe: CWE mentioned in the vulnerability. :status 200: Success
.. http:get:: /vulnerability/recent :synopsis: Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data.
:status 200: Success
.. http:get:: /vulnerability/recent/{date} :synopsis: Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data.
:param string date: :status 200: Success
.. http:get:: /vulnerability/recent/{date}/{number} :synopsis: Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data.
:param string date: :param integer number: :status 200: Success
.. http:get:: /vulnerability/recent/{date}/{source} :synopsis: Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data.
:param string date: :param string source: :status 200: Success
.. http:get:: /vulnerability/recent/{date}/{source}/{number} :synopsis: Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results
Retrieve vulnerabilities reported after a specified date, with optional filters for source and number of results. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data. Defaults to the last 24 hours if no date is provided. Supports light mode for minimal data.
:param string date: :param string source: :param integer number: :status 200: Success
.. http:get:: /vulnerability/search/{vendor}/{product} :synopsis: Returns a list of vulnerabilities related to the vendor and product
Returns a list of vulnerabilities related to the vendor and product
Returns a list of vulnerabilities related to the product. Optionally filter vulnerabilities published or updated after the specified date (format: YYYY-MM-DD).
:param string vendor: :param string product: :query integer page: Number of the page. :query integer per_page: Maximum number of elements to return. :query string since: Filter vulnerabilities published or updated after the specified date (format: YYYY-MM-DD). :status 200: Success
.. http:get:: /vulnerability/{vulnerability_id} :synopsis: Get a vulnerability with its id
Get a vulnerability with its id
Get a vulnerability.
:param string vulnerability_id: :query boolean with_meta: Include metada. :query boolean with_linked: Include the linked vulnerabilities. :query boolean with_comments: Include the comments. :query boolean with_bundles: Include the bundles. :query boolean with_sightings: Include the sightings. :status 200: Success
.. http:delete:: /vulnerability/{vulnerability_id} :synopsis: Endpoint for deleting a vulnerability
Endpoint for deleting a vulnerability
Delete a vulnerability from the local source. We only accept to delete vulnerabilities from the local source.
:param string vulnerability_id: :status 204: Success. :status 403: Admin permission required. :status 422: Not possible to edit a vulnerability from the requested source.
Response format#
All list endpoints return a paginated response with the following structure:
{
"metadata": {
"count": 42,
"page": 1,
"per_page": 10
},
"data": []
}
Examples#
Vulnerabilities#
Looking up a vulnerability by ID:
$ curl -X 'GET' 'http://127.0.0.1:10001/api/vulnerability/cve-2024-38063' -H 'accept: application/json'
Cross-source correlation — retrieving all advisories linked to a given vulnerability:
$ curl -X 'GET' 'http://127.0.0.1:10001/api/vulnerability/cve-2024-38063/links' -H 'accept: application/json'
Bundles#
Getting the list of bundles:
$ curl -X 'GET' 'http://127.0.0.1:10001/api/bundle/' -H 'accept: application/json'
Sightings#
Getting the list of sightings:
$ curl -X 'GET' 'http://127.0.0.1:10001/api/sighting/' -H 'accept: application/json'
Getting sightings for a specific vulnerability:
$ curl -X 'GET' 'http://127.0.0.1:10001/api/sighting/?vuln_id=cve-2024-38063' -H 'accept: application/json'
KEV (Known Exploited Vulnerabilities)#
Getting the list of KEV entries (BCP-07 format):
$ curl -X 'GET' 'http://127.0.0.1:10001/api/kev/' -H 'accept: application/json'
Comments#
Getting the list of comments:
Getting the list of comments made by a specific author:
Getting the list of comments related to a vulnerability:
Getting the list of comments that are related to a Proof of Concept: