How to use the DSL

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 "domain-contact_ww_grp@oracle.com"

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "APIKEY: <<your_api_key>>" \
     --data-binary "{
  \"query\" : \"whois_email = 'domain-contact_ww_grp@oracle.com'\"
}" \
'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 = 'domain-contact_ww_grp@oracle.com') 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.registrar@godaddy.com
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.admin@securitytrails.com
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.

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.