API Documentation

This page provides information on how to use the The Cert Graveyard API.

The recommended method of reporting certificates is to use the webform, certReport, or certReportCentral, but some advanced users may desire additional capabilities offered through using the API.

Authentication

For some most queries, an API key is required. Your API key is accessible through your profile page. The API key should be included as follows:

        X-API-KEY: your_api_key_here
    

Endpoints

Query database

Query the database using a search parameter and a search term. This is very similar to the webform.

Required headers:

• X-API-KEY: your_api_key_here
• Content-Type: application/json

Required parameters:

• search_parameter
Supported types
• sha256
• malware
• signer
• issuer-short
• issuer
• serial
• thumbprint
• valid-from
• valid-to
• country
• state
• locality
• email
• search_term
(String to search for)

Example with Python:

        import requests
        import json

        url = "https://certgraveyard.org/api/query_database"
        data = {"search_parameter": "sha256", "search_term": "c36338fbc2b1913fd79443706dedbc9f58adcfaf5af1dab06a592446e8f6dec6"}
        headers = {
            "X-API-KEY": "your_api_key_here",
            "Content-Type": "application/json"
        }

        response = requests.post(url, headers=headers, data=json.dumps(data))

        print(response.text)
    

Update attribution

Update the attribution of an existing entry, looked up by its SHA256 hash. Requires the analyst, bot, or admin role.

Endpoint: POST /api/update_attribution
Required headers:

• X-API-KEY: your_api_key_here
• Content-Type: application/json

Required parameters:

• hash
(SHA256 hash of the entry to update)

Optional parameters (at least one is required):

• malware
• malware_type
• malware_notes
• cluster
• super_cluster

Only the fields you include are changed. Send an empty string or null to clear a field.

Responses:

• 200: Attribution updated (the response lists each changed field's old and new value), or no changes were needed
• 400: Missing or invalid hash, no attribution fields provided, or a field value that is not a string
• 401: Invalid or missing API key
• 403: Your account does not have the analyst, bot, or admin role
• 404: Hash does not exist in the database

Example with Python:

        import requests

        url = "https://certgraveyard.org/api/update_attribution"
        data = {
            "hash": "c36338fbc2b1913fd79443706dedbc9f58adcfaf5af1dab06a592446e8f6dec6",
            "malware": "Lumma",
            "malware_type": "Infostealer",
            "malware_notes": "Example notes",
            "cluster": "ExampleCluster",
            "super_cluster": "ExampleSuperCluster"
        }
        headers = {
            "X-API-KEY": "your_api_key_here",
            "Content-Type": "application/json"
        }

        response = requests.post(url, headers=headers, json=data)

        print(response.status_code, response.json())
    

Download CSV

Download a CSV of the The Cert Graveyard database. This endpoint is unauthenticated to allow for easy use.

Example with python:

        import requests

        url = "https://certgraveyard.org/api/download_csv"

        response = requests.get(url)

        with open("certgraveyard_data.csv", "wb") as file:
            file.write(response.content)