CIRCL

CIRCL Passive DNS is a database storing historical DNS records from various resources. CIRCL Passive SSL is a database storing historical X.509 certificates seen per IP address. The Passive SSL historical data is indexed per IP address.

Data Enrichment & Threat Intelligence · CIRCL

Details

IDCIRCL
ProviderLHC
CategoryData Enrichment & Threat Intelligence
From Version5.0.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM

README

Use the CIRCL integration to research malware history for IPs, DNSs, and hostnames, and to query certificate history and details.

This integration was integrated and tested with CIRCL v2.0.

Use Cases

  1. Query IP, DNS, or hostname for malware history.
  2. Query IP or IP CIDR for certificate history.
  3. Query certificate for IP history.
  4. Query certificate details.

Configure CIRCL on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for CIRCL.
  3. Click Add instance to create and configure a new integration instance.
    • Name: a textual name for the integration instance.
    • Server URL (e.g. https://www.circl.lu)
    • Enter Authentication details
    • Use system proxy settings
    • Trust any certificate (not secure)
  4. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Get DNS records: circl-dns-get
  2. Get SSL certificate history for IP address or CIDR blocks: circl-ssl-list-certificates
  3. Get IP addresses associated with an SSL certificate: circl-ssl-query-certificate
  4. Get information for an SSL certificate: circl-ssl-get-certificate

1. Get DNS records


Get DNS records for your query value from CIRCL's Passive DNS.

Base Command

circl-dns-get

Input
Argument Name Description Required
queryValue IP address, hostname, or domain name Required

 

Context Output
Path Type Description
CIRCLdns.Query.Value string Query Value
CIRCLdns.Query.Record.Data string DNS Record or IP Address
CIRCLdns.Query.Record.LastTime date DNS record last recorded time

 

Command Example

!circl-dns-get queryValue=69.172.200.235

Context Example
{
 "Query": [
  {
   "Record": [
    {
     "Data": "ns65.worldnic.com",
     "LastTime": "2018-10-28 20:43:59"
    },
    {
     "Data": "204.12.0.50",
     "LastTime": "2011-08-15 11:35:51"
    },
    {
     "Data": "50.23.225.49",
     "LastTime": "2012-01-02 16:44:53"
    },
    {
     "Data": "ns66.worldnic.com",
     "LastTime": "2018-10-28 20:43:59"
    },
    {
     "Data": "69.172.200.235",
     "LastTime": "2018-10-29 22:50:34"
    }
   ],
   "Value": "test.com"
  }
 ]
}

2. Get SSL certificate history for IP addresses or CIDR blocks


Query IP address or CIDR blocks (/32 up to /23) for SSL certificates history.

Base Command

circl-ssl-list-certificates

Input
Argument Name Description Required
queryValue IP address or CIDR block Required

 

Context Output
Path Type Description
CIRCLssl.IPAddress.Value string IP address
CIRCLssl.IPAddress.Certificate.SHA1 string The SHA-1 fingerprint of the certificate
CIRCLssl.IPAddress.Certificate.Subjects string Certificate subjects

 

Command Example

!circl-ssl-list-certificates queryValue=172.228.24.0/28

Context Example
{
 "Certificate": [
  {
   "SHA1": "780a06f6e9b4061cad0c6502710606eb535f1c26",
   "Subjects": [
    "C=US, O=GeoTrust, Inc., CN=GeoTrust SSL CA"
   ]
  },
  {
   "SHA1": "b47dcd32bcc997f769a008365b3ae418ae613c5b",
   "Subjects": [
    "serialNumber=NhYqVrM6jc9PtOjjwTmeTWpc5G6L9yq8, C=KR, ST=Gyeonggi-Do, L=Seongnam-City, O=NAVER Business Platform Corp., OU=NAVER Business Platform Corp., CN=mail.naver.com"
   ]
  },
  {
   "SHA1": "2d33eb5931c47f5bcec037658e77b7d0988ea3b9",
   "Subjects": [
    "C=KR, ST=Gyeonggi, L=Seongnam-City, O=NAVER Business Platform Corp., OU=NAVER Business Platform Corp., CN=mail.naver.com"
   ]
  },
  {
   "SHA1": "6c624f520f6fd75d4e05672806cfd384f35bbda1",
   "Subjects": [
    "C=KR, ST=Gyeonggi-Do, L=Seongnam-Si, O=NAVER Business Platform Corp., OU=NAVER Business Platform Corp., CN=mail.naver.com"
   ]
  },
  {
   "SHA1": "4f56644858829ffb85a770171accf9f8407a137b",
   "Subjects": [
    "C=US, O=GeoTrust Inc., CN=GeoTrust SSL CA - G2"
   ]
  }
 ],
 "Value": "172.228.24.209"
}

3. Get IP addresses associated with an SSL certificate


Query a certificate value to get all associated addresses.

Base Command

circl-ssl-query-certificate

Input
Argument Name Description Required
certificate SHA-1 fingerprint of a certificate Required
limitResults Limit the results number (Increasing number can cause browser slowdowns). Optional

 

Context Output
Path Type Description
CIRCLssl.Certificate.SHA1 string The SHA-1 fingerprint of the certificate
CIRCLssl.Certificate.Hits number Number of hits for the certificate (number of associated addresses)
CIRCLssl.Certificate.IPAddress string IP address associated to the certificate

 

Command Example

!circl-ssl-query-certificate certificate=c46fed822dadac3f31f9bb4d1a78a1d9eae4567b limitResults=10

Context Example
{
 "Hits": 1066,
 "IPAddress": [
  "172.231.209.35",
  "222.163.206.206",
  "104.98.248.71",
  "23.212.29.129",
  "23.7.44.197",
  "104.67.128.36",
  "96.16.84.130",
  "172.233.131.187",
  "23.197.219.175",
  "173.222.24.202"
 ],
 "SHA1": "c46fed822dadac3f31f9bb4d1a78a1d9eae4567b"
}

4. Get information for an SSL certificate


Get the raw certificate and related information.

Base Command

circl-ssl-get-certificate

Input
Argument Name Description Required
certificate SHA-1 fingerprint of a certificate Required

 

Context Output
Path Type Description
CIRCLssl.Certificate.SHA1 string The SHA-1 fingerprint of the certificate
CIRCLssl.Certificate.Usage string Extended key usage
CIRCLssl.Certificate.Distribution string CRL distribution points
CIRCLssl.Certificate.Issuer string Certificate issuer
CIRCLssl.Certificate.Time date Certificate issued time (***not_before)
CIRCLssl.Certificate.Subject string Certificate subject
CIRCLssl.Certificate.Key string Certificate public key
CIRCLssl.Certificate.Pem string Certificate in PEM format
CIRCLssl.Certificate.Seen number Number of times the certificate was seen

 

Command Example

!circl-ssl-get-certificate certificate=37221925980c05deefac014f9a72b4765e716341

Context Example
{
 "Distribution": "\nFull Name:\n  URI:http://vassg142.crl.omniroot.com/vassg142.crl\n",
 "Issuer": "C=NL, L=Amsterdam, O=Verizon Enterprise Solutions, OU=Cybertrust, CN=Verizon Akamai SureServer CA G14-SHA2",
 "Key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtp19/XP3H9LNDAt7PUF/\nK8ug35VTcMM6HJt+bIqzKMKdTogXLv2gI24k/pS/T0y19H80dlg3PpJDyuISUvHf\n33nKT1ad+Z3cddFvo/FJU1gJZulAuovqc5bF6tSP7IKMGIyY9By1R4PsqftUYSu0\nlnfwGc8JDbt6BPGzyOnrk+UFgv7BidKKhlvW3nbKN2ydvFhOWQeFTsNaxkp+PzA1\nm/MwEiCetorBuVFWi5wTo0CFko9cFCFyWUp5eEaNUcVxAHwxnqWu0B9Cwsli9ei7\ngcIDUgPIkAbuo+GSLc8tRyb+pvBe6TPq4qlN0LdPDcMjodM+wUNrA4ojTNmzjRFb\nEwIDAQAB\n-----END PUBLIC KEY-----\n",
 "Pem": "-----BEGIN CERTIFICATE-----\nMIIFkDCCBHigAwIBAgIUdIcF/AeOFgHhxbQhFzBZ+1ye94EwDQYJKoZIhvcNAQEL\nBQAwgY0xCzAJBgNVBAYTAk5MMRIwEAYDVQQHEwlBbXN0ZXJkYW0xJTAjBgNVBAoT\nHFZlcml6b24gRW50ZXJwcmlzZSBTb2x1dGlvbnMxEzARBgNVBAsTCkN5YmVydHJ1\nc3QxLjAsBgNVBAMTJVZlcml6b24gQWthbWFpIFN1cmVTZXJ2ZXIgQ0EgRzE0LVNI\nQTIwHhcNMTUwNDIzMTY1ODAzWhcNMTYwNDIzMTY1NzU5WjCBhDELMAkGA1UEBhMC\nSlAxDjAMBgNVBAgTBVRva3lvMRIwEAYDVQQHEwlNaW5hdG8ta3UxGTAXBgNVBAoT\nEFNvbnkgY29ycG9yYXRpb24xDDAKBgNVBAsTA05QUzEoMCYGA1UEAxMfcHNuLXJz\nYy5wcm9kLmRsLnBsYXlzdGF0aW9uLm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEP\nADCCAQoCggEBALadff1z9x/SzQwLez1BfyvLoN+VU3DDOhybfmyKsyjCnU6IFy79\noCNuJP6Uv09MtfR/NHZYNz6SQ8riElLx3995yk9Wnfmd3HXRb6PxSVNYCWbpQLqL\n6nOWxerUj+yCjBiMmPQctUeD7Kn7VGErtJZ38BnPCQ27egTxs8jp65PlBYL+wYnS\nioZb1t52yjdsnbxYTlkHhU7DWsZKfj8wNZvzMBIgnraKwblRVoucE6NAhZKPXBQh\ncllKeXhGjVHFcQB8MZ6lrtAfQsLJYvXou4HCA1IDyJAG7qPhki3PLUcm/qbwXukz\n6uKpTdC3Tw3DI6HTPsFDawOKI0zZs40RWxMCAwEAAaOCAe0wggHpMAwGA1UdEwEB\n/wQCMAAwTAYDVR0gBEUwQzBBBgkrBgEEAbE+ATIwNDAyBggrBgEFBQcCARYmaHR0\ncHM6Ly9zZWN1cmUub21uaXJvb3QuY29tL3JlcG9zaXRvcnkwga8GCCsGAQUFBwEB\nBIGiMIGfMC0GCCsGAQUFBzABhiFodHRwOi8vdmFzc2cxNDIub2NzcC5vbW5pcm9v\ndC5jb20wNgYIKwYBBQUHMAKGKmh0dHBzOi8vY2FjZXJ0LmEub21uaXJvb3QuY29t\nL3Zhc3NnMTQyLmNydDA2BggrBgEFBQcwAoYqaHR0cHM6Ly9jYWNlcnQuYS5vbW5p\ncm9vdC5jb20vdmFzc2cxNDIuZGVyMCoGA1UdEQQjMCGCH3Bzbi1yc2MucHJvZC5k\nbC5wbGF5c3RhdGlvbi5uZXQwDgYDVR0PAQH/BAQDAgWgMB0GA1UdJQQWMBQGCCsG\nAQUFBwMBBggrBgEFBQcDAjAfBgNVHSMEGDAWgBT4vfqvc3fGxxv5S00Rp9Ezr69y\nETA+BgNVHR8ENzA1MDOgMaAvhi1odHRwOi8vdmFzc2cxNDIuY3JsLm9tbmlyb290\nLmNvbS92YXNzZzE0Mi5jcmwwHQYDVR0OBBYEFECotIoqM/RYjCUGFD97O9KzLnrA\nMA0GCSqGSIb3DQEBCwUAA4IBAQAtdu6/cFEzzP3NxTLG0Zidap+g4id4gTru1593\nXOc/RFobetN1/z6PYDR0l1tivaA8q1PU7swF8anK9m2+3Tn/MD9CONhaWHNuE3OY\nJlFreviSUih4EnUB2GKF78ac5I3VgNZwaOT6khsIqvNkFVEX4s0r1BweoTU75/mn\nm22SlEuGYWsree/ltMjYw08k2B/6aBFuwIaFbv57/1V/IBjufqLUNBcp01Rz62gE\nWstynBavGrQQPXInqRUxMSiuhHUQEZNgff5yesowMk4e7A0Q8DUo1VlqSXM4T27X\n5pS20KmmlWetKd5WTjpQYzjetHf6TYRy8+E8eebww2A7uO3A\n-----END CERTIFICATE-----\n",
 "SHA1": "37221925980c05deefac014f9a72b4765e716341",
 "Seen": "16",
 "Subject": "C=JP, ST=Tokyo, L=Minato-ku, O=Sony corporation, OU=NPS, CN=psn-rsc.prod.dl.playstation.net",
 "Time": "2015-04-23T16:58:03+00:00",
 "Usage": "TLS Web Server Authentication, TLS Web Client Authentication"
}

Configuration parameters

  • url — Server URL (e.g. https://www.circl.lu) (required)
  • credentials — Username (required)
  • proxy — Use system proxy settings
  • insecure — Trust any certificate (not secure)

Commands (4)

  • circl-dns-get

    Get DNS records for your query value from CIRCL's Passive DNS.

  • circl-ssl-get-certificate

    Get the raw certificate and related information.

  • circl-ssl-list-certificates

    Query IP address or CIDR blocks (/32 up to /23) for SSL certificates history.

  • circl-ssl-query-certificate

    Query a certificate value to get all associated addresses

import demistomock as demisto
from CommonServerPython import *
from CommonServerUserPython import *
import requests
import json
import urllib3

# Disable insecure warnings
urllib3.disable_warnings()

""" GLOBAL VARS """
BASE_URL = demisto.getParam("url")
USERNAME = demisto.getParam("credentials")["identifier"]
PASSWORD = demisto.getParam("credentials")["password"]
AUTH = (USERNAME, PASSWORD)
USE_SSL = not demisto.params().get("insecure", False)
IS_USING_PROXY = demisto.params().get("proxy", False)
LAST_TIME_KEY = "time_last"


def http_request(method, url):
    response = requests.request(method, url, auth=AUTH, verify=USE_SSL)

    if response.status_code != 200:
        return_error(f"Error in API call: [{response.status_code}] - {response.reason}")
    return response


def validate_sha1(sha1):
    if len(sha1) != 40:
        return_error(f"Invalid SHA-1, expected 40 characters: {sha1}")


def validate_ip_of_cidr(ip):
    regex = r"^([0-9]{1,3}\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$"

    match = re.search(regex, ip)

    if match is None:
        return_error(f"Invalid IP or CIDR: {ip}")


def timestamp_to_string(timestamp):
    if timestamp is None:
        return None

    return datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")


def dns_get_command(url):
    response = http_dns_get(url)

    results = [json.loads(line) for line in response.text.splitlines()]
    results = merge_by_rdata(results)

    records = []

    for result in results:
        records.append(create_dns_record_context(result))

    demisto.results(
        {
            "Type": entryTypes["note"],
            "ContentsFormat": formats["text"],
            "Contents": response.text,
            "HumanReadable": tableToMarkdown(f"CIRCL Dns - {url}", records),
            "EntryContext": {
                "CIRCLdns.Query(val.Value===obj.Value)": {
                    "Value": url,
                    "Record": records,
                }
            },
        }
    )


def http_dns_get(url):
    query_url = f"{BASE_URL}/pdns/query/{url}"

    return http_request("GET", query_url)


# The results may contain several records with the same 'rdata' but different (not interesting) other properties.
# This function will merge the records and keep the later "last seen time".


def merge_by_rdata(results):
    results_map = {}  # type: dict

    for e in results:
        key = e["rdata"]
        other = results_map.get(key)

        if other is not None and other[LAST_TIME_KEY] > e[LAST_TIME_KEY]:
            e = other

        results_map[key] = e

    return list(results_map.values())


def create_dns_record_context(record):
    last_time = timestamp_to_string(record[LAST_TIME_KEY])

    return {
        "Data": record["rdata"],
        "LastTime": last_time,
    }


def list_certificates(queryValue):
    validate_ip_of_cidr(queryValue)
    response = http_list_certificates(queryValue)

    data = response.json()
    records = []

    for ip, ip_data in list(data.items()):
        records.append(create_ip_context(ip, ip_data))

    result = {
        "Type": entryTypes["note"],
        "ContentsFormat": formats["json"],
        "Contents": data,
        "HumanReadable": tableToMarkdown(f"List certificates for {queryValue}", records),
        "EntryContext": {"CIRCLssl.IPAddress(val.Value===obj.Value)": records},
    }

    demisto.results(result)


def http_list_certificates(queryValue):
    query_url = f"{BASE_URL}/v2pssl/query/{queryValue}"

    return http_request("GET", query_url)


def create_ip_context(ip, ipData):
    certificates = []

    for sha1 in ipData["certificates"]:
        subjects = ipData["subjects"].get(sha1, {}).get("values", [])
        certificates.append(create_list_certificate_context(sha1, subjects))

    return {"Value": ip, "Certificate": certificates}


def create_list_certificate_context(sha1, subjects):
    return {"SHA1": sha1, "Subjects": subjects}


def list_certificate_seen_ips(sha1, limit):
    validate_sha1(sha1)
    response = http_list_certificate_seen_ips(sha1)

    data = response.json()
    certificate = create_certificate_seen_ips_context(sha1, data, limit)

    result = {
        "Type": entryTypes["note"],
        "ContentsFormat": formats["json"],
        "Contents": data,
        "HumanReadable": f'Hits: {str(certificate["Hits"])}',
        "EntryContext": {
            "CIRCLssl.Certificate(val.SHA1===obj.SHA1)": certificate,
        },
    }

    demisto.results(result)


def http_list_certificate_seen_ips(sha1):
    query_url = f"{BASE_URL}/v2pssl/cquery/{sha1}"

    return http_request("GET", query_url)


def create_certificate_seen_ips_context(sha1, data, limit):
    return {
        "SHA1": sha1,
        "Hits": data["hits"],
        "IPAddress": data["seen"][:limit],
    }


def get_certificate_details(sha1):
    validate_sha1(sha1)
    response = http_get_certificate_details(sha1)

    data = response.json()
    certificate = create_certificate_details(sha1, data)

    result = {
        "Type": entryTypes["note"],
        "ContentsFormat": formats["json"],
        "Contents": data,
        "HumanReadable": tableToMarkdown(f"CIRCL ssl certificate - {sha1}", certificate),
        "EntryContext": {
            "CIRCLssl.Certificate(val.SHA1===obj.SHA1)": certificate,
        },
    }

    demisto.results(result)


def http_get_certificate_details(sha1):
    query_url = f"{BASE_URL}/v2pssl/cfetch/{sha1}"
    return http_request("GET", query_url)


def create_certificate_details(sha1, data):
    info = data["info"]
    usage = ""
    distribution = ""

    extension = info.get("extension", {})

    usage = extension.get("keyUsage", usage)
    usage = extension.get("extendedKeyUsage", usage)
    distribution = extension.get("crlDistributionPoints", distribution)
    times_seen = data.get("icsi", {}).get("times_seen")

    return {
        "SHA1": sha1,
        "Usage": usage,
        "Distribution": distribution,
        "Issuer": info["issuer"],
        "Time": info["not_before"],
        "Subject": info["subject"],
        "Key": info["key"],
        "Pem": data["pem"],
        "Seen": times_seen,
    }


""" EXECUTION CODE """

LOG(f"command is {demisto.command()}")
try:
    command = demisto.command()
    args = demisto.args()
    handle_proxy()

    if command == "test-module":
        result = http_dns_get("test.com")
        demisto.results("ok")

    elif command == "circl-dns-get":
        dns_get_command(args.get("queryValue"))

    elif command == "circl-ssl-list-certificates":
        list_certificates(args.get("queryValue"))

    elif command == "circl-ssl-query-certificate":
        limit = int(args.get("limitResults", 100))
        sha1 = args.get("certificate")

        list_certificate_seen_ips(sha1, limit)

    elif command == "circl-ssl-get-certificate":
        get_certificate_details(args.get("certificate"))

except Exception as e:
    return_error(str(e))