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

Source

CIRCL.py CIRCL.yml
Download History Raw 
category: Data Enrichment & Threat Intelligence
provider: LHC
commonfields:
  id: CIRCL
  version: -1
configuration:
- defaultvalue: https://www.circl.lu
  display: Server URL (e.g. https://www.circl.lu)
  name: url
  required: true
  type: 0
- display: Username
  name: credentials
  required: true
  type: 9
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  required: false
description: |-
  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.
display: CIRCL
name: CIRCL
script:
  commands:
  - arguments:
    - description: IP address, hostname, or domain name.
      name: queryValue
      required: true
    description: Get DNS records for your query value from CIRCL's Passive DNS.
    name: circl-dns-get
    outputs:
    - contextPath: CIRCLdns.Query.Value
      description: Query Value.
      type: string
    - contextPath: CIRCLdns.Query.Record.Data
      description: DNS Record or IP Address.
      type: string
    - contextPath: CIRCLdns.Query.Record.LastTime
      description: DNS record last recorded time.
      type: date
  - arguments:
    - description: IP address or CIDR block.
      name: queryValue
      required: true
    description: Query IP address or CIDR blocks (/32 up to /23) for SSL certificates history.
    name: circl-ssl-list-certificates
    outputs:
    - contextPath: CIRCLssl.IPAddress.Value
      description: IP address.
      type: string
    - contextPath: CIRCLssl.IPAddress.Certificate.SHA1
      description: ' The SHA-1 fingerprint of the certificate.'
      type: string
    - contextPath: CIRCLssl.IPAddress.Certificate.Subjects
      description: Certificate subjects.
      type: string
  - arguments:
    - description: SHA-1 fingerprint of a certificate.
      name: certificate
      required: true
    - defaultValue: '100'
      description: Limit the results number (Increasing number can cause browser slowdowns).
      name: limitResults
    description: Query a certificate value to get all associated addresses
    name: circl-ssl-query-certificate
    outputs:
    - contextPath: CIRCLssl.Certificate.SHA1
      description: ' The SHA-1 fingerprint of the certificate.'
      type: string
    - contextPath: CIRCLssl.Certificate.Hits
      description: Number of hits for the certificate (number of associated addresses).
      type: number
    - contextPath: CIRCLssl.Certificate.IPAddress
      description: IP address associated to the certificate.
      type: string
  - arguments:
    - description: SHA-1 fingerprint of a certificate.
      name: certificate
      required: true
    description: Get the raw certificate and related information.
    name: circl-ssl-get-certificate
    outputs:
    - contextPath: CIRCLssl.Certificate.SHA1
      description: The SHA-1 fingerprint of the certificate.
      type: string
    - contextPath: CIRCLssl.Certificate.Usage
      description: Extended key usage.
      type: string
    - contextPath: CIRCLssl.Certificate.Distribution
      description: CRL distribution points.
      type: string
    - contextPath: CIRCLssl.Certificate.Issuer
      description: Certificate issuer.
      type: string
    - contextPath: CIRCLssl.Certificate.Time
      description: Certificate issued time (***not_before).
      type: date
    - contextPath: CIRCLssl.Certificate.Subject
      description: Certificate subject.
      type: string
    - contextPath: CIRCLssl.Certificate.Key
      description: Certificate public key.
      type: string
    - contextPath: CIRCLssl.Certificate.Pem
      description: Certificate in PEM format.
      type: string
    - contextPath: CIRCLssl.Certificate.Seen
      description: Number of times the certificate was seen.
      type: number
  runonce: false
  script: '-'
  type: python
  subtype: python3
  dockerimage: demisto/python3:3.12.13.10116658
tests:
- CirclIntegrationTest
fromversion: 5.0.0