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

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "APIKEY: " \
     --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: " \
     --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"

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

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_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

keyword

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

dropped

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

private_registration

computed_organization

3. 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”