Certificates API

The Certificates API allows you to list and monitor all SSL/TLS certificates discovered across your organization's assets.

info

This API endpoint is available for enterprise accounts only.

List Certificates

Retrieve all certificates discovered across your organization's assets.

HTTP Request

GET https://fullhunt.io/api/v1/enterprise/certificates

Query Parameters

Parameter	Required	Type	Description
q	No	string	Search query to filter certificates by domain name, date, or certificate type
page	No	integer	Pagination page number (default: 1)

Example Request

curl "https://fullhunt.io/api/v1/enterprise/certificates?q=kaspersky" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

Example Response

{
  "status": 200,
  "total_results": 42,
  "page": 1,
  "results": {
    "items": [
      {
        "id": "CERT-5231",
        "domain_name": "cloud.kaspersky.com",
        "date_added": "2024-03-15T14:22:31Z",
        "last_seen": "2024-03-15T14:22:31Z",
        "type": "Certificate"
      }
    ],
    "total": 42,
    "page": 1,
    "per_page": 10,
    "pages": 5
  }
}

Response Fields

Field	Type	Description
`status`	integer	HTTP status code
`total_results`	integer	Total number of certificates found
`page`	integer	Current page number
`results.items`	array	Array of certificate objects
`results.total`	integer	Total items in current response
`results.pages`	integer	Total number of pages

Certificate Object Fields

Field	Type	Description
`id`	string	Unique certificate identifier
`domain_name`	string	Primary domain name on the certificate
`date_added`	string	ISO timestamp when certificate was first discovered
`last_seen`	string	ISO timestamp when certificate was last seen
`type`	string	Certificate type (always "Certificate")

Certificate Details

For detailed certificate information, you can use the Domain APIs or Host APIs to get full certificate objects:

# Get detailed certificate info for a specific host
curl "https://fullhunt.io/api/v1/host/cloud.kaspersky.com" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

This will return detailed certificate information including:

Subject and issuer details
Valid date ranges
DNS names (SANs)
Fingerprints (MD5, SHA1, SHA256)
Signature algorithm

Integration Example

import requests
from datetime import datetime, timedelta
import json

class CertificateMonitor:
    def __init__(self, api_key):
        self.api_key = api_key
        self.headers = {"X-API-KEY": api_key}
    
    def get_all_certificates(self, search_query=None):
        """Get all certificates, optionally filtered by search query."""
        url = "https://fullhunt.io/api/v1/enterprise/certificates"
        params = {}
        
        if search_query:
            params["q"] = search_query
        
        all_certificates = []
        page = 1
        
        while True:
            params["page"] = page
            response = requests.get(url, headers=self.headers, params=params)
            
            if response.status_code == 200:
                data = response.json()
                certificates = data.get("results", {}).get("items", [])
                
                if not certificates:
                    break
                
                all_certificates.extend(certificates)
                
                # Check if there are more pages
                current_page = data.get("results", {}).get("page", 1)
                total_pages = data.get("results", {}).get("pages", 1)
                
                if current_page >= total_pages:
                    break
                
                page += 1
            else:
                print(f"Error: {response.status_code}")
                break
        
        return all_certificates
    
    def get_certificate_details(self, domain):
        """Get detailed certificate information for a domain."""
        url = f"https://fullhunt.io/api/v1/host/{domain}"
        response = requests.get(url, headers=self.headers)
        
        if response.status_code == 200:
            data = response.json()
            return data.get("cert_object")
        else:
            print(f"Error getting details for {domain}: {response.status_code}")
            return None
    
    def check_expiring_certificates(self, days_ahead=30):
        """Check for certificates expiring within specified days."""
        print(f"🔍 Checking for certificates expiring in {days_ahead} days...")
        
        certificates = self.get_all_certificates()
        expiring_certs = []
        
        for cert in certificates:
            domain = cert["domain_name"]
            details = self.get_certificate_details(domain)
            
            if details and details.get("not_after"):
                try:
                    # Parse expiration date
                    exp_date_str = details["not_after"]
                    exp_date = datetime.strptime(exp_date_str, "%d-%m-%Y %H:%M:%S")
                    
                    # Check if expiring soon
                    days_until_expiry = (exp_date - datetime.now()).days
                    
                    if 0 <= days_until_expiry <= days_ahead:
                        expiring_certs.append({
                            "domain": domain,
                            "expires": exp_date_str,
                            "days_remaining": days_until_expiry,
                            "issuer": details.get("issuer_common_name"),
                            "subject": details.get("subject_common_name")
                        })
                
                except ValueError as e:
                    print(f"Error parsing date for {domain}: {e}")
        
        # Sort by days remaining (most urgent first)
        expiring_certs.sort(key=lambda x: x["days_remaining"])
        
        if expiring_certs:
            print(f"⚠️  Found {len(expiring_certs)} certificates expiring soon:")
            
            for cert in expiring_certs:
                urgency = "🚨" if cert["days_remaining"] <= 7 else "⚠️"
                print(f"  {urgency} {cert['domain']} - expires in {cert['days_remaining']} days")
                print(f"     Expires: {cert['expires']}")
                print(f"     Issuer: {cert['issuer']}")
                print()
        else:
            print("✅ No certificates expiring soon")
        
        return expiring_certs
    
    def certificate_inventory_report(self):
        """Generate a comprehensive certificate inventory report."""
        print("📋 Certificate Inventory Report")
        print("=" * 50)
        
        certificates = self.get_all_certificates()
        
        # Statistics
        total_certs = len(certificates)
        
        # Get detailed info for analysis
        issuers = {}
        algorithms = {}
        upcoming_expirations = {"7_days": 0, "30_days": 0, "90_days": 0}
        
        print(f"Total Certificates: {total_certs}")
        print("\nAnalyzing certificate details...")
        
        for i, cert in enumerate(certificates, 1):
            print(f"Progress: {i}/{total_certs}", end="\r")
            
            domain = cert["domain_name"]
            details = self.get_certificate_details(domain)
            
            if details:
                # Count issuers
                issuer = details.get("issuer_common_name", "Unknown")
                issuers[issuer] = issuers.get(issuer, 0) + 1
                
                # Count signature algorithms
                algorithm = details.get("signature_algorithm", "Unknown")
                algorithms[algorithm] = algorithms.get(algorithm, 0) + 1
                
                # Check expiration timeframes
                if details.get("not_after"):
                    try:
                        exp_date = datetime.strptime(details["not_after"], "%d-%m-%Y %H:%M:%S")
                        days_until_expiry = (exp_date - datetime.now()).days
                        
                        if days_until_expiry <= 7:
                            upcoming_expirations["7_days"] += 1
                        elif days_until_expiry <= 30:
                            upcoming_expirations["30_days"] += 1
                        elif days_until_expiry <= 90:
                            upcoming_expirations["90_days"] += 1
                    except ValueError:
                        pass
        
        print("\n\n📊 Certificate Analysis:")
        
        print(f"\nTop Certificate Issuers:")
        for issuer, count in sorted(issuers.items(), key=lambda x: x[1], reverse=True)[:5]:
            print(f"  {issuer}: {count} certificates")
        
        print(f"\nSignature Algorithms:")
        for algorithm, count in sorted(algorithms.items(), key=lambda x: x[1], reverse=True):
            print(f"  {algorithm}: {count} certificates")
        
        print(f"\nExpiration Timeline:")
        print(f"  Next 7 days: {upcoming_expirations['7_days']} certificates")
        print(f"  Next 30 days: {upcoming_expirations['30_days']} certificates")
        print(f"  Next 90 days: {upcoming_expirations['90_days']} certificates")
        
        return {
            "total_certificates": total_certs,
            "issuers": issuers,
            "algorithms": algorithms,
            "expiration_timeline": upcoming_expirations
        }

# Usage examples
api_key = "your-api-key-here"
cert_monitor = CertificateMonitor(api_key)

# Check for expiring certificates
expiring = cert_monitor.check_expiring_certificates(days_ahead=30)

# Generate comprehensive report
report = cert_monitor.certificate_inventory_report()

# Search for specific certificates
kaspersky_certs = cert_monitor.get_all_certificates("kaspersky")
print(f"Found {len(kaspersky_certs)} certificates containing 'kaspersky'")

Certificate Monitoring Automation

import requests
import json
import smtplib
from email.mime.text import MIMEText
from datetime import datetime, timedelta

def automated_certificate_monitoring(api_key, email_config=None):
    """Automated certificate monitoring with email alerts."""
    
    cert_monitor = CertificateMonitor(api_key)
    
    # Check for certificates expiring in different timeframes
    timeframes = [7, 14, 30]
    alerts = {}
    
    for days in timeframes:
        expiring = cert_monitor.check_expiring_certificates(days_ahead=days)
        if expiring:
            alerts[f"{days}_days"] = expiring
    
    if alerts and email_config:
        send_certificate_alert_email(alerts, email_config)
    
    # Save monitoring results
    monitoring_result = {
        "timestamp": datetime.now().isoformat(),
        "alerts": alerts,
        "total_certificates_checked": len(cert_monitor.get_all_certificates())
    }
    
    with open("certificate_monitoring_log.json", "a") as f:
        f.write(json.dumps(monitoring_result) + "\n")
    
    return monitoring_result

def send_certificate_alert_email(alerts, email_config):
    """Send email alert for expiring certificates."""
    
    subject = "🔒 Certificate Expiration Alert"
    
    body = "The following SSL/TLS certificates are expiring soon:\n\n"
    
    for timeframe, certs in alerts.items():
        days = timeframe.replace("_days", "")
        body += f"Expiring in {days} days:\n"
        
        for cert in certs:
            body += f"  • {cert['domain']} - {cert['days_remaining']} days remaining\n"
            body += f"    Expires: {cert['expires']}\n"
            body += f"    Issuer: {cert['issuer']}\n\n"
    
    body += "\nPlease take action to renew these certificates before they expire.\n"
    body += "Generated by FullHunt Certificate Monitoring"
    
    # Send email
    msg = MIMEText(body)
    msg["Subject"] = subject
    msg["From"] = email_config["from"]
    msg["To"] = email_config["to"]
    
    try:
        server = smtplib.SMTP(email_config["smtp_server"], email_config["smtp_port"])
        server.starttls()
        server.login(email_config["username"], email_config["password"])
        server.send_message(msg)
        server.quit()
        print("📧 Certificate alert email sent successfully")
    except Exception as e:
        print(f"❌ Failed to send email: {e}")

# Email configuration example
email_config = {
    "smtp_server": "smtp.gmail.com",
    "smtp_port": 587,
    "username": "your-email@gmail.com",
    "password": "your-app-password",
    "from": "your-email@gmail.com",
    "to": "security-team@acme.com"
}

# Run automated monitoring
api_key = "your-api-key-here"
result = automated_certificate_monitoring(api_key, email_config)

Use Cases

Certificate Lifecycle Management

Monitor certificate expiration dates
Track certificate issuers and validate trust chains
Identify certificates that need renewal

Security Compliance

Ensure all certificates use strong encryption algorithms
Verify certificate issuers are from trusted CAs
Monitor for weak or deprecated algorithms

Asset Discovery

Discover all SSL/TLS enabled services
Identify shadow IT through certificate monitoring
Map certificate coverage across your infrastructure

Incident Response

Quickly identify potentially compromised certificates
Track certificate changes over time
Monitor for unauthorized certificate installations

Best Practices

Certificate Management

Automated Renewal: Implement automated certificate renewal where possible
Monitoring: Set up alerts for certificates expiring in 30, 14, and 7 days
Documentation: Maintain an inventory of all certificates and their purposes
Testing: Regularly test certificate renewal processes

Security Considerations

Strong Algorithms: Ensure all certificates use strong signature algorithms (SHA-256 or better)
Trusted CAs: Only use certificates from trusted Certificate Authorities
Key Management: Secure private keys and use hardware security modules when possible
Certificate Transparency: Monitor Certificate Transparency logs for unauthorized certificates

Rate Limiting

Rate limit: 60 requests per minute
Use pagination for large certificate inventories
Consider caching results for frequently accessed data

List Certificates​

Certificate Object Fields​

Certificate Details​

Integration Example​

Certificate Monitoring Automation​

Use Cases​

Certificate Lifecycle Management​

Security Compliance​

Asset Discovery​

Incident Response​

Best Practices​

Certificate Management​

Security Considerations​

Rate Limiting​