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
| ID | CIRCL |
|---|---|
| Provider | LHC |
| Category | Data Enrichment & Threat Intelligence |
| From Version | 5.0.0 |
| Docker Image | demisto/python3:3.12.13.10116658 |
| Supported Modules | Agentix 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
- Query IP, DNS, or hostname for malware history.
- Query IP or IP CIDR for certificate history.
- Query certificate for IP history.
- Query certificate details.
Configure CIRCL on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services.
- Search for CIRCL.
- 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)
- 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.
- Get DNS records: circl-dns-get
- Get SSL certificate history for IP address or CIDR blocks: circl-ssl-list-certificates
- Get IP addresses associated with an SSL certificate: circl-ssl-query-certificate
- 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 settingsinsecure— Trust any certificate (not secure)
Commands (4)
-
circl-dns-getGet DNS records for your query value from CIRCL's Passive DNS.
-
circl-ssl-get-certificateGet the raw certificate and related information.
-
circl-ssl-list-certificatesQuery IP address or CIDR blocks (/32 up to /23) for SSL certificates history.
-
circl-ssl-query-certificateQuery 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))