How to use the DSL

The SecurityTrails 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

AttributeDescription
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
asnthe 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_createdDomain create date on WHOIS record e.g. 2018-01-31 (YYYY-MM-DD)
whois_expiresDomain 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_countryThe country registered to a domain name in the WHOIS Record. e.g. United States
whois_registrarThe registrar of the domain name in the WHOIS Record. e.g. Amazon Registrar, Inc.
keyword Substring of a hostname. *e.g. oracle"
first_seenTimestamp 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

AttributeDescription
ptr_partmatches 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.
ptrmatches the full ptr record exactly
portmatches 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.
ipmatches 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.

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.