<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Detecting Certificate Transparency Abuse

## crt.sh API

### Endpoints

| URL | Description |
|---|---|
| `https://crt.sh/?q=%25.example.com&output=json` | All certs for domain |
| `https://crt.sh/?q=%.example.com&output=json&exclude=expired` | Exclude expired |
| `https://crt.sh/?id=<cert_id>` | Specific certificate details |
| `https://crt.sh/?serial=<hex_serial>` | Search by serial number |

### JSON Response Fields

| Field | Description |
|---|---|
| `id` | crt.sh certificate ID |
| `name_value` | Subject names (SAN values, newline-separated) |
| `issuer_name` | Issuing CA distinguished name |
| `not_before` | Certificate validity start |
| `not_after` | Certificate validity end |
| `serial_number` | Certificate serial (hex) |

## DNS CAA Records

### Synopsis

```bash
dig +short CAA example.com
```

### CAA Record Tags

| Tag | Description |
|---|---|
| `issue` | CAs authorized to issue certificates |
| `issuewild` | CAs authorized for wildcard certificates |
| `iodef` | Incident reporting URL (mailto: or https:) |

### Example CAA Configuration

```
example.com. CAA 0 issue "letsencrypt.org"
example.com. CAA 0 issue "digicert.com"
example.com. CAA 0 issuewild "letsencrypt.org"
example.com. CAA 0 iodef "mailto:security@example.com"
```

## certstream

### Synopsis

```bash
pip install certstream
```

### Python API

```python
import certstream

def callback(message, context):
    if message["message_type"] == "certificate_update":
        domains = message["data"]["leaf_cert"]["all_domains"]
        print(domains)

certstream.listen_for_events(callback, url="wss://certstream.calidog.io/")
```

## Agent Script

```bash
# Query certificates for a domain
node agent.js query example.com

# Check CAA records
node agent.js caa example.com

# Find lookalike domains
node agent.js lookalikes mycompany

# Audit issuers against approved list
node agent.js audit example.com --approved "Let's Encrypt" "DigiCert"
```
