tips enterprise security

SecurityTrails Blog · Feb 19 · by Esteban Borges

What’s New at SecurityTrails: New Domain SSL, IP WHOIS and IP User Agent API Endpoints

Reading time: 8 minutes

Today, we are sharing the release of new API endpoints to fetch SSL certificate information for hostnames, IP WHOIS contacts and abuse information as well as User Agent information for IP addresses. In addition to the new API endpoints we have also updated our Console.

Check out the full Changelog which is updated whenever we roll out new changes.

API

API has been enriched with three new features. These new endpoints will allow you to fetch even more domain and IP data.

Domain SSL

Using the new Domain SSL endpoint you’ll be able to get current and historical data on the SSL certificates of a hostname. The SSL data that is returned using this endpoint comes from the certificate transparency logs. Let’s test it out:

curl --request GET --url 'https://api.securitytrails.com/v1/domain/securitytrails.com/ssl?include_subdomains=false&status=valid' --header 'apikey: yourapikey'

The output looks like this:

{
  "records": [
    {
      "subject": {...},
      "serial_number": "125216268788926101542761736323207409437",
      "not_before": 1502323200,
      "not_after": 1597017599,
      "issuer": {
        "province": [...],
        "organization": [
          "COMODO CA Limited"
        ],
        "locality": [...],
        "country": [
          "GB"
        ],
        "common_name": "COMODO RSA Domain Validation Secure Server CA"
      },
      "fingerprints": {
        "sha256": "8A856ED928054CF05C297D6F5C8D5600643D0B7023A2F2E2809CEAE8B7DC5F12",
        "sha1": "5A122F69762E0FD7C8E95892D3C5DE8D3DF676EC"
      },
      "dns_names": [
        "securitytrails.com",
        "www.securitytrails.com"
      ]
    },
    {
      "subject": {...},
      "serial_number": "167541106786547823992944284300355499636",
      "not_before": 1515369600,
      "not_after": 1610063999,
      "issuer": {
        "province": [...],
        "organization": [
          "COMODO CA Limited"
        ],
        "locality": [...],
        "country": [
          "GB"
        ],
        "common_name": "COMODO RSA Domain Validation Secure Server CA"
      },
      "fingerprints": {
        "sha256": "2D7553A4774C243797407E875DD23EE2C964CBD9163EB5E12769892807DFD740",
        "sha1": "A8065C55DE8CCC1FBBC7E2747C8F13A258BBE1E4"
      },
      "dns_names": [
        "*.securitytrails.com",
        "securitytrails.com"
      ]
    }
  ]
}

From there, in the results you’ll see records of valid certificates, who the certificate authority is that issued it, validity period and more.

Domain SSL endpoint is also a great way of finding subdomains: when querying the endpoint for a hostname, you can set the value of the include_subdomain parameter to true, which will then return you SSL data of the hostname and its subdomains. Let’s see how this looks:

curl --request GET --url 'https://api.securitytrails.com/v1/domain/stackoverflow.com/ssl?include_subdomains=true&status=valid' --header 'apikey:yourapikey'

The output looks like this:

{
  "records": [
    {
      "subject": {},
      "serial_number": "330678280546627171363850661252520159219070",
      "not_before": 1574406315,
      "not_after": 1582182315,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "88B7DED99593D1E209A925119E5CD81EAE274D4237BC57AF7A6B8DF575B3743F",
        "sha1": "AE67D95D2AA9FD54D7399993A9D3F36530CEE343"
      },
      "dns_names": [
        "*.askubuntu.com",
        "*.blogoverflow.com",
        "*.mathoverflow.net",
        "*.meta.stackexchange.com",
        "*.meta.stackoverflow.com",
        "*.serverfault.com",
        "*.sstatic.net",
        "*.stackexchange.com",
        "*.stackoverflow.com",
        "*.stackoverflow.email",
        "*.superuser.com",
        "askubuntu.com",
        "blogoverflow.com",
        "mathoverflow.net",
        "openid.stackauth.com",
        "serverfault.com",
        "sstatic.net",
        "stackapps.com",
        "stackauth.com",
        "stackexchange.com",
        "stackoverflow.blog",
        "stackoverflow.com",
        "stackoverflow.email",
        "stackoverflowbusiness.com",
        "stacksnippets.net",
        "superuser.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "320980140431133322705628325286467630959505",
      "not_before": 1574578829,
      "not_after": 1582354829,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "F85AB23B2B289C5FD2C0F2D94A4A51A8D7A2A62996D5321897B8ACB72E9C172D",
        "sha1": "4C7585999E902CC14981604429F8511A4A896229"
      },
      "dns_names": [
        "*.askubuntu.com",
        "*.blogoverflow.com",
        "*.mathoverflow.net",
        "*.meta.stackexchange.com",
        "*.meta.stackoverflow.com",
        "*.serverfault.com",
        "*.sstatic.net",
        "*.stackexchange.com",
        "*.stackoverflow.com",
        "*.stackoverflow.email",
        "*.superuser.com",
        "askubuntu.com",
        "blogoverflow.com",
        "mathoverflow.net",
        "openid.stackauth.com",
        "serverfault.com",
        "sstatic.net",
        "stackapps.com",
        "stackauth.com",
        "stackexchange.com",
        "stackoverflow.blog",
        "stackoverflow.com",
        "stackoverflow.email",
        "stacksnippets.net",
        "superuser.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "394276462844744645968984858214571667510573",
      "not_before": 1578121545,
      "not_after": 1585897545,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "B740637BD84425750E8014713E0A1E454F360F2E49CD45AA9146A2F3130B2D59",
        "sha1": "BE78CE42BFFE2398FC8079C79F34369EBC322871"
      },
      "dns_names": [
        "cdn-dev.sstatic.net",
        "clc.dev.stackoverflow.com",
        "dev.api.stackexchange.com",
        "dev.area51.stackexchange.com",
        "dev.careers.stackoverflow.com",
        "dev.channels.stackoverflow.com",
        "dev.contests.stackoverflow.com",
        "dev.email.stackoverflow.com",
        "dev.insights.stackoverflow.com",
        "dev.meta.stackoverflow.com",
        "dev.mobile.stackexchange.com",
        "dev.openid.stackauth.com",
        "dev.openid.stackexchange.com",
        "dev.promote.stackexchange.com",
        "dev.qa.sockets.stackexchange.com",
        "dev.serverfault.com",
        "dev.sockets.qa.stackexchange.com",
        "dev.sstatic.net",
        "dev.stackauth.com",
        "dev.stackexchange.com",
        "dev.stackoverflow.com",
        "dev.stackoverflow.email",
        "dev.stacksnippets.net",
        "dev.superuser.com",
        "dev.talent.stackoverflow.com",
        "dev.webapps.stackexchange.com",
        "discuss.dev.area51.stackexchange.com",
        "meta.dev.stackexchange.com",
        "meta.dev.webapps.stackexchange.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "295977639090727951424273530286548106552480",
      "not_before": 1578207623,
      "not_after": 1585983623,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "4A9CF195063B2FB8FD0A9138392C68A3620497937FC67BB4C59E7F450F1EBCE9",
        "sha1": "DAF5D43EE4C1039C1F3D0799C87562C0AAEC3DC2"
      },
      "dns_names": [
        "cdn-dev.sstatic.net",
        "clc.dev.stackoverflow.com",
        "dev.api.stackexchange.com",
        "dev.area51.stackexchange.com",
        "dev.careers.stackoverflow.com",
        "dev.channels.stackoverflow.com",
        "dev.contests.stackoverflow.com",
        "dev.email.stackoverflow.com",
        "dev.insights.stackoverflow.com",
        "dev.meta.stackoverflow.com",
        "dev.mobile.stackexchange.com",
        "dev.openid.stackauth.com",
        "dev.openid.stackexchange.com",
        "dev.promote.stackexchange.com",
        "dev.qa.sockets.stackexchange.com",
        "dev.serverfault.com",
        "dev.sockets.qa.stackexchange.com",
        "dev.sstatic.net",
        "dev.stackauth.com",
        "dev.stackexchange.com",
        "dev.stackoverflow.com",
        "dev.stackoverflow.email",
        "dev.stacksnippets.net",
        "dev.superuser.com",
        "dev.talent.stackoverflow.com",
        "dev.webapps.stackexchange.com",
        "discuss.dev.area51.stackexchange.com",
        "meta.dev.stackexchange.com",
        "meta.dev.stackoverflow.com",
        "meta.dev.webapps.stackexchange.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "333888686488006426227053892020986418116825",
      "not_before": 1579762828,
      "not_after": 1587538828,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "717B3143DEF4E6AAFFDB49945BBEAF008421EE6620E17644B45BE85F83DC3FD2",
        "sha1": "F10577D6F13C0CC618BEC54F877C049CA74A2848"
      },
      "dns_names": [
        "*.askubuntu.com",
        "*.blogoverflow.com",
        "*.mathoverflow.net",
        "*.meta.stackexchange.com",
        "*.meta.stackoverflow.com",
        "*.serverfault.com",
        "*.sstatic.net",
        "*.stackexchange.com",
        "*.stackoverflow.com",
        "*.stackoverflow.email",
        "*.superuser.com",
        "askubuntu.com",
        "blogoverflow.com",
        "mathoverflow.net",
        "openid.stackauth.com",
        "serverfault.com",
        "sstatic.net",
        "stackapps.com",
        "stackauth.com",
        "stackexchange.com",
        "stackoverflow.blog",
        "stackoverflow.com",
        "stackoverflow.email",
        "stacksnippets.net",
        "superuser.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "279496228386524295576467227942772171335399",
      "not_before": 1579706583,
      "not_after": 1587482583,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "C19CF5F9D8CCA7C4DBFCE6CDCF76A177435C6694A924D880ABFB311D6E76A2D3",
        "sha1": "D1121B074E8D887201AA36F8BDCFBF20F2D66D5E"
      },
      "dns_names": [
        "*.askubuntu.com",
        "*.blogoverflow.com",
        "*.mathoverflow.net",
        "*.meta.stackexchange.com",
        "*.meta.stackoverflow.com",
        "*.serverfault.com",
        "*.sstatic.net",
        "*.stackexchange.com",
        "*.stackoverflow.com",
        "*.stackoverflow.email",
        "*.superuser.com",
        "askubuntu.com",
        "blogoverflow.com",
        "mathoverflow.net",
        "openid.stackauth.com",
        "serverfault.com",
        "sstatic.net",
        "stackapps.com",
        "stackauth.com",
        "stackexchange.com",
        "stackoverflow.blog",
        "stackoverflow.com",
        "stackoverflow.email",
        "stackoverflowbusiness.com",
        "stacksnippets.net",
        "superuser.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "270378465781404795712546425779605045904513",
      "not_before": 1581001068,
      "not_after": 1588777068,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "632C50CD3346F038CB29E24648F4B5C97090ABDB82EE2DF252F9B41A971561A1",
        "sha1": "4AC01D44F1B74E22E244B2A12021C6B088A7A0A0"
      },
      "dns_names": [
        "cdn-dev.sstatic.net",
        "clc.dev.stackoverflow.com",
        "dev-switchrelay.stackexchange.com",
        "dev.api.stackexchange.com",
        "dev.area51.stackexchange.com",
        "dev.careers.stackoverflow.com",
        "dev.channels.stackoverflow.com",
        "dev.contests.stackoverflow.com",
        "dev.email.stackoverflow.com",
        "dev.insights.stackoverflow.com",
        "dev.meta.stackoverflow.com",
        "dev.mobile.stackexchange.com",
        "dev.openid.stackauth.com",
        "dev.openid.stackexchange.com",
        "dev.promote.stackexchange.com",
        "dev.qa.sockets.stackexchange.com",
        "dev.secretoverflow.com",
        "dev.serverfault.com",
        "dev.sockets.qa.stackexchange.com",
        "dev.sstatic.net",
        "dev.stackauth.com",
        "dev.stackexchange.com",
        "dev.stackoverflow.com",
        "dev.stackoverflow.email",
        "dev.stacksnippets.net",
        "dev.superuser.com",
        "dev.talent.stackoverflow.com",
        "dev.webapps.stackexchange.com",
        "discuss.dev.area51.stackexchange.com",
        "meta.dev.stackexchange.com",
        "meta.dev.stackoverflow.com",
        "meta.dev.webapps.stackexchange.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "378973140888279511604802564319303590225710",
      "not_before": 1578207742,
      "not_after": 1585983742,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "35CCAF3804FD4FDEA0AF24E868EABC43B8D401CB5C90C48FB8378C2CD52EB31B",
        "sha1": "31BD7E6388E7B148F2E81B44EE7E996442224B73"
      },
      "dns_names": [
        "chat.meta.stackexchange.com",
        "chat.stackexchange.com",
        "chat.stackoverflow.com",
        "dev-bonfire.stackoverflow.com",
        "dev-sockets.chat.stackexchange.com"
      ]
    },
    {
      "subject": {
        "province": [
          "New York"
        ],
        "organization": [
          "Stack Exchange, Inc."
        ],
        "locality": [
          "New York"
        ],
        "country": [
          "US"
        ]
      },
      "serial_number": "13610149854288639704888752657757942764",
      "not_before": 1576972800,
      "not_after": 1641384000,
      "issuer": {
        "organizational_unit": [
          "www.digicert.com"
        ],
        "organization": [
          "DigiCert Inc"
        ],
        "country": [
          "US"
        ],
        "common_name": "DigiCert SHA2 High Assurance Server CA"
      },
      "fingerprints": {
        "sha256": "F495BFF8A50E88D4415E00AF4EBC84E75A9152A5982F830534DFC9BE6F0A2329",
        "sha1": "3ABC21BED5444C5DA477E806CC0BED035620FE7B"
      },
      "dns_names": [
        "gh.stackoverflow.com",
        "github.ds.stackexchange.com"
      ]
    },
    {
      "subject": {},
      "serial_number": "280276123691702712202402117351480341505808",
      "not_before": 1579417310,
      "not_after": 1587193310,
      "issuer": {
        "organization": [
          "Let's Encrypt"
        ],
        "country": [
          "US"
        ],
        "common_name": "Let's Encrypt Authority X3"
      },
      "fingerprints": {
        "sha256": "AC5123E0D22D8FF76A5D86E083EE5011B8DBA9B2146FB328C54DCBFB762ADCB0",
        "sha1": "FC1274C945FC12004276606C0E9AA989ECBBF8BF"
      },
      "dns_names": [
        "cdn-dev.sstatic.net",
        "clc.dev.stackoverflow.com",
        "dev-switchrelay.stackexchange.com",
        "dev.api.stackexchange.com",
        "dev.area51.stackexchange.com",
        "dev.careers.stackoverflow.com",
        "dev.channels.stackoverflow.com",
        "dev.contests.stackoverflow.com",
        "dev.email.stackoverflow.com",
        "dev.insights.stackoverflow.com",
        "dev.meta.stackoverflow.com",
        "dev.mobile.stackexchange.com",
        "dev.openid.stackauth.com",
        "dev.openid.stackexchange.com",
        "dev.promote.stackexchange.com",
        "dev.qa.sockets.stackexchange.com",
        "dev.serverfault.com",
        "dev.sockets.qa.stackexchange.com",
        "dev.sstatic.net",
        "dev.stackauth.com",
        "dev.stackexchange.com",
        "dev.stackoverflow.com",
        "dev.stackoverflow.email",
        "dev.stacksnippets.net",
        "dev.superuser.com",
        "dev.talent.stackoverflow.com",
        "dev.webapps.stackexchange.com",
        "discuss.dev.area51.stackexchange.com",
        "meta.dev.stackexchange.com",
        "meta.dev.stackoverflow.com",
        "meta.dev.webapps.stackexchange.com"
      ]
    }
  ],
  "record_count": 10,
  "meta": {
    "total_pages": 1,
    "query": {
      ...
    },
    "page": 1,
    "max_page": 1
  },
  "endpoint": "/v1/domain/stackoverflow.com/ssl"
}

IP User Agent

A valuable addition to our IP lookup is the IP User Agent endpoint. Querying this endpoint allows you to fetch data on the user agent for a given IP address such as the type of device, operating system, its version, when it was last seen and more. Let’s try it out on an example; in this case, Amazon UK’s IP address.

curl --request GET --url 'https://api.securitytrails.com/v1/ips/3.8.86.191/useragents?apikey=yourapikey'

The output looks like this:

{
  "records": [
    {
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/77.0.3865.75 Safari/537.36",
      "os": {
        "version": "n/a",
        "platform": "x64",
        "name": "GNU/Linux"
      },
      "lastseen": 1580256000,
      "device": {
        "type": "desktop",
        "model": "n/a",
        "brand": "n/a"
      },
      "client": {
        "version": "77.0.3865.75",
        "type": "browser",
        "name": "Headless Chrome",
        "engine_version": "n/a",
        "engine": "Blink"
      }
    }
  ]
}

IP WHOIS

Another newly added API feature is the IP WHOIS endpoint, where you can get current WHOIS data of a given IPv4 address. For any allocated IP address, just use the GET https://api.securitytrails.com/v1/ips/ipaddress/whois. In the results you will see details on the assigned owner, the Regional Internet Registry (RIR) who assigns the IP, contact information and location as well as technical and abuse reporting details. This information will be very valuable for the information gathering phase when tracking down attackers.

For example, let’s query Netflix’s IP, 54.164.254.216:

curl --request GET --url 'https://api.securitytrails.com/v1/ips/54.164.254.216/whois?apikey=yourapikey'

And the output looks like this:

{
  "record": {
    "source": "ARIN",
    "ip": "54.164.254.216",
    "contacts": [
      {
        "type": "technicalContact",
        "telephone": "12062664064",
        "organization": "Amazon EC2 Network Operations",
        "email": "amzn-noc-contact@amazon.com"
      },
      {
        "type": "administrativeContact",
        "telephone": "12062664064",
        "organization": "Amazon EC2 Abuse",
        "email": "abuse@amazonaws.com"
      },
      {
        "type": "registrant",
        "street1": "410 Terry Ave N.",
        "state": "WA",
        "postal_code": "98109",
        "organization": "Amazon Technologies Inc.",
        "country_code": "US",
        "country": "UNITED STATES",
        "city": "Seattle"
      },
      {
        "type": "zoneContact",
        "telephone": "12062664064",
        "organization": "Amazon AWS Network Operations",
        "email": "amzn-noc-contact@amazon.com"
      }
    ],
    "contact_email": "abuse@amazonaws.com"
  },
  "endpoint": "/v1/ips/54.164.254.216/whois"
}

Using the new API endpoints requires a custom subscription. For more information on including these endpoints in your subscription, please contact us.

Console

As with everything on our website, the SecurityTrails Console undergoes small changes constantly, in an effort to make access easier for you and deliver exactly what you need more quickly and efficiently.

When looking through your API usage, you’ll now see usage grouped by the endpoint name, in both Usage Stats and Usage Log, fore a better overview of past queries:

SecurityTrails Console SecurityTrails Console 2

Conclusion

We hope you like the latest addition to our API. If you want to get started right away, feel free to contact us and we will help you get started. What else are you looking forward to? Let us know at hello@securitytrails.com

We look forward to hearing from you!

ESTEBAN BORGES

Esteban Borges is a security researcher and technical writer specialized in Linux security. He has been working in the cybersecurity industry for more than 15 years, with a focus on technical server security and open source intelligence.