SecurityTrails Developer Hub

The SecurityTrails Developer Hub

Welcome to the SecurityTrails developer hub. You'll find comprehensive guides and documentation to help you start working with SecurityTrails as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

How to use the DSL

The SecuriryTrails DSL provides a powerful SQL like query interface to our data via certain API end points.

One of the very unique things about SecurityTrails is the ability to build flexible and complex queries across out data sets with very fast results. This document will explain our DSL and how to practically use it as well as present a foundation so you can build complex queries.

1. Introduction

DSL stands for “Domains Specific Language”. It is a way for you to query our Exploration end point with flexible SQL like queries. This document will show you the fields available as well as give examples of how to make queries. The DSL for SecurityTrails is similar to the syntax used for SQL where predicates.

2. Example

Here is a sample using cURL. The reason we give a sample using cURL is because it's a simple way to query it right from your local computer. Notice here how we have "query" and the "query" is for the whois_email "[email protected]"

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "APIKEY: <<your_api_key>>" \
     --data-binary "{
  \"query\" : \"whois_email = '[email protected]'\"
}" \
'https://api.securitytrails.com/v1/search/list'

Here is a 2nd and slightly more complex cURL sample:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "APIKEY: <<your_api_key>>" \
     --data-binary "{
      \"query\": \"((whois_email = '[email protected]') OR ipv4 in           ('1.1.1.1', '2.2.2.2', '3.3.3.3/24')) AND tld = 'com''\"
}" \
'https://api.securitytrails.com/v1/search/list'

3. Attributes for "query"

Domains

Attribute

Description

ipv4

the IPv4 address an A record that a domain currently points to (can include a network mask) e.g. 127.0.0.1 or 122.22.22.22/24

ipv6

the IPv6 address an A record points to in a domain currently.
e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334

asn

the AS number that a domain currently points to.
e.g. 12989

mx

the MX (Mail Exchanger) DNS record a domain points to currently. e.g. mx.google.com

ns

the NS (Nameserver) DNS record a domain points to currently. e.g. ns1.dnsjunction.com

cname

the CNAME DNS record a domain points to currently. e.g. mail.google.com

subdomain

Find all domains that have a specific subdomain. *e.g. status"

apex_domain

Find all domains and hostnames for a specific apex domain. e.g. oracle.com

soa_email

e.g. [email protected]

tld

The top level domain of the domain you looked up. e.g. com

whois_email

The email address the WHOIS entry has listed as any of it's contacts. e.g. [email protected]

whois_street1

The first line of the physical street address a WHOIS record has. e.g. 3575 Cahuenga Blvd West

whois_street2

The second line of the physical street address a WHOIS record has

whois_street3

The third line of the physical street address a WHOIS record has

whois_street4

The fourth line of the physical street address a WHOIS record has

whois_telephone

The telephone number registered to a domain name in its WHOIS record. e.g. 323-620-1337

whois_postalCode

The postal code registered to a domain name in its WHOIS record. e.g. 90266

whois_organization

The organization registered to a domain name in its WHOIS record. e.g. SecurityTrails

whois_name

The full name (usually a person) registered to a domain name in its WHOIS Record. e.g. Jeremy Brown

whois_created

Domain create date on WHOIS record e.g. 2018-01-31 (YYYY-MM-DD)

whois_expires

Domain expires date on WHOIS record e.g. 2018-02-28 (YYYY-MM-DD)

whois_fax

The fax number registered to a domain name in its WHOIS Record. e.g. 323-620-1338

whois_city

The city registered to a domain name in its WHOIS Record. e.g. Los Angeles

whois_country

The country registered to a domain name in the WHOIS Record. e.g. United States

whois_registrar

The registrar of the domain name in the WHOIS Record. e.g. Amazon Registrar, Inc.

keyword

Substring of a hostname. *e.g. oracle"

first_seen

Timestamp when we first saw the hostname

dropped

Filter if a domain is still active (dropped = false) or dropped (dropped = true) false is the default - true or false

IPs

Attribute

Description

ptr_part

matches the end of the ptr record. it must exactly match a fragment so for example microsoft.com would match any ptr record that ends with microsoft.com test.microsoft.com would match, but test.otherserviceatmicrosoft.com would not.

ptr

matches the full ptr record exactly

port

matches open ports. These are numeric so operators like between gt lt > >= <= etc. are all supported. e.g. port between 1000 and 4000 or port <= 100.

ip

matches the ip address. network masks are supported. e.g. 1.1.1.1/24

4. Operators for "query"

Notice you can group boolean statements with () like you would with a SQL where statement. The comparison operators you can use:

  • You can also use IN for groups. Finally AND OR are both supported.
  • You can test for a missing field or a field that exists as well by comparing to null or nil . i.e. “cname != null” will only return results that have a cname.
  • Finally there is a LIKE expression as well like SQL. So cname LIKE '%apple%’ would return all domains with the word “apple” in a cname. For like * and % match multiple characters and ? matches a single character. bl?h% for example would match “blah” “bleh” “blahh” but won’t match “blaah”

With whois_created and whois_expires you can query date ranges in a few different ways. For example by using BETWEEN operator: whois_created between "2017-12-01" and "2018-01-01” or by using comparison operators (>, <, gt, lt, gte, lte, >=, <=) like this: whois_created > "2017-12-01" and whois_created < "2018-01-01". These two statements will produce the same output, domains that are created between 2017-12-01 and 2018-01-01.

Updated about a month ago

How to use the DSL


The SecuriryTrails DSL provides a powerful SQL like query interface to our data via certain API end points.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.