Certificate Transparency Skill

Purpose

Query Certificate Transparency logs to discover certificates issued for a domain, extract Subject Alternative Names (SANs), and identify internal naming conventions.

Operations

1. query_crt_sh_json

Query crt.sh for all certificates matching a domain.

Endpoint:

GET https://crt.sh/?q=%25.{domain}&output=json

Request Headers:

User-Agent: TechStackAgent/1.0
Accept: application/json

Process:

1. URL encode domain with wildcard prefix
2. Make HTTP GET request to crt.sh
3. Parse JSON response array
4. Extract certificate metadata

Response Fields:

{
  "issuer_ca_id": 183267,
  "issuer_name": "C=US, O=Let's Encrypt, CN=R3",
  "common_name": "example.com",
  "name_value": "example.com\nwww.example.com\napi.example.com",
  "id": 1234567890,
  "entry_timestamp": "2024-01-15T10:30:00.000",
  "not_before": "2024-01-15T09:00:00",
  "not_after": "2024-04-15T09:00:00",
  "serial_number": "abc123..."
}

2. extract_sans

Parse Subject Alternative Names from certificate data.

Process:

1. Split name_value field by newlines
2. Filter for domain matches
3. Deduplicate entries
4. Validate format (no wildcards in extracted names)

Example:

Input: "example.com\n*.example.com\napi.example.com\nwww.example.com"
Output: ["example.com", "api.example.com", "www.example.com"]

3. identify_naming_patterns

Analyze SANs to detect internal naming conventions.

Pattern Detection:

patterns = {
    "environment_prefix": r"^(prod|staging|dev|test|qa|uat)-",
    "environment_suffix": r"-(prod|staging|dev|test|qa|uat)$",
    "numbered_instances": r"(\d+)$",
    "geo_prefix": r"^(us|eu|apac|asia|emea|latam)-",
    "service_pattern": r"^(api|app|web|cdn|static|assets)-"
}

Example Output:

{
  "patterns": [
    {
      "type": "environment_prefix",
      "regex": "^(prod|staging|dev)-",
      "matches": ["prod-api", "staging-api", "dev-api"]
    },
    {
      "type": "geo_prefix",
      "regex": "^(us|eu)-",
      "matches": ["us-east-api", "eu-west-api"]
    }
  ]
}

4. find_wildcard_certs

Identify wildcard certificate usage.

Process:

1. Filter certificates where common_name starts with "*."
2. Note wildcard scope (*.domain.com vs *.subdomain.domain.com)
3. Flag potential security implications

Wildcard Analysis:

{
  "wildcards": [
    {
      "pattern": "*.example.com",
      "scope": "root_domain",
      "certificates_count": 5,
      "latest_issue": "2024-01-15"
    },
    {
      "pattern": "*.api.example.com",
      "scope": "subdomain",
      "certificates_count": 2,
      "latest_issue": "2024-01-10"
    }
  ]
}

Output

{
  "skill": "certificate_transparency",
  "domain": "string",
  "results": {
    "certificates": [
      {
        "id": "number",
        "issuer": "string",
        "common_name": "string",
        "sans": ["array"],
        "not_before": "date",
        "not_after": "date",
        "is_wildcard": "boolean"
      }
    ],
    "unique_subdomains": ["array"],
    "naming_patterns": [
      {
        "type": "string",
        "pattern": "string",
        "examples": ["array"]
      }
    ],
    "wildcard_analysis": {
      "wildcards_found": "number",
      "patterns": ["array"]
    },
    "issuers": {
      "issuer_name": "count"
    }
  },
  "evidence": [
    {
      "type": "ct_certificate",
      "id": "number",
      "common_name": "string",
      "issuer": "string",
      "timestamp": "ISO-8601"
    }
  ],
  "metadata": {
    "total_certificates": "number",
    "unique_subdomains": "number",
    "query_timestamp": "ISO-8601"
  }
}

Certificate Issuer Analysis

Track which CAs are used (reveals hosting/security practices):

Issuer Pattern	Indicates
Let's Encrypt	Cost-conscious, automated cert management
DigiCert, Sectigo	Enterprise/compliance requirements
AWS Certificate Manager	AWS infrastructure
Cloudflare	Cloudflare CDN/proxy
Google Trust Services	GCP infrastructure

Rate Limiting

• crt.sh: Max 10 requests/minute
• Implement exponential backoff on 429 responses
• Cache results to avoid repeated queries

Error Handling

• If crt.sh returns 503, wait 30s and retry
• If timeout, retry with longer timeout (60s)
• If JSON parse fails, log raw response
• Continue with partial results if some queries fail

Security Considerations

• Only query public CT logs
• Do not attempt to access certificate private keys
• Log all queries for audit trail
• Respect crt.sh rate limits