Documentation | ShadowTrackr

You can use the API to integrate ShadowTrackr with your other tools. This is useful to automate your workflow or build custom dashboards. There are endpoints for hosts, websites, certificates, mailservers and whois data that you can use to enrich the data you already have in your other security systems. A feed of your timeline is available in both JSON and ArcSight CEF formats, all other endpoints only support JSON.

If you want to use the API, make sure you've enabled it under Settings->API access. This is also where you’ll find your API key. API access is only available to Business and Enterprise subscriptions.

Note that you don't need API access to use the webhooks. ShadowTrackr will happily process any alert through a webhook for you, but there might be rate limits at some point in the future if this is eating too many resources.

The easiest way to get started is by using the ShadowTrackr Python module. For any other language you can use the endpoint as described below.

Installation


    pip install shadowtrackr

Usage


    from shadowtrackr import ShadowTrackr
    from pprint import pprint

    st = ShadowTrackr(api_key="[API_KEY]")

    d = st.query("index=hosts problem=yes earliest=-10d")
    pprint(d)

Some endpoints allow you to filter for specific urls, domains, ip addresses or date ranges (the specifics are mentioned below). In general, you post your API key and these parameters as JSON data to the endpoint. You post something like this:

{"api_key": "[API_KEY]", "update": true}

To the endpoint url: https://shadowtrackr.com/api/v3/timeline

Since we don't want to break existing scripts, the old way (adding parameters to your urlstring) is also still supported. It works like this:
https://shadowtrackr.com/api/v3/feed?api_key=[API_KEY]&update=true

If you are building new scripts, please opt for the new method. This will provide you more functionality.

Endpoint: https://shadowtrackr.com/api/v3/query
Example JSON post data:

{"api_key": "[API_KEY]", "q": "index=certificates by issuer earliest=-1m" }

From version 3 of the API you can use any query that works in the GUI. For more information on how to make queries, please see Search and Queries and Data Model. The returned data is a JSON formatted list of search results:

[
  {'issuer': 'COMODO RSA Domain Validation Secure Server CA', 'count': '53'},
  {'issuer': 'Cloudflare Inc ECC CA-3', 'count': '42'}}
]

Endpoint: https://shadowtrackr.com/api/v3/timeline
Example JSON post data:

{"api_key": "[API_KEY]", "update": true }

This endpoint provides a stream with all messages related to assets (ip address or url). Messages related to traps (keyword hits, canary tokens and cryptocoin wallets) do not appear in this feed. The endpoint by will always return the last 1000 messages. If you only want the updates this is not fun to parse, so here are some options to make things easier:

Only new messages
"update": true if you add this to the JSON post, you only get the messages that are new since the last time you checked. Note that calls without "update": true do not update the APIs internal "last updated" timestamp.

Messages since X
"start": "YYYY-MM-DD HH:MM:SS" to the JSON post, you get the first 1000 messages since that timestamp. The nasty bit here of course is the magic number 1000. What if there are more messages? Well, you need to add "stop": "YYYY-MM-DD HH:MM:SS" and then you'll be complete.

The returned data is a JSON formatted list of notifications:

[{
 "timestamp":"2020-06-22 13:10:08",
 "eventid":"124",
 "level":"60",
 "asset_type":"url",
 "asset":"shadowtrackr.com",
 "link":"url:shadowtrackr.com",
 "msg":"Found MX record for shadowtrackr.com: mail.shadowtrackr.com"
}]

Example for typical ArcSight feed
If you want to feed your timeline straight into ArcSight, there is a separate endpoint that outputs the notifications in ArcSight CEF format. Since it's ArcSight (we feel your pain) you'll probably want to use the legacy API style. And yes, we'll continue supporting this for the feed.

https://shadowtrackr.com/api/v3/feed?api_key=[API_KEY]&update=true&output_format=cef

The returned CEF data contains:

Name	JSON	CEF
timestamp (UTC)	yyyy-mm-dd HH:mm:ss	MMM dd yyyy HH:mm:ss zzz
eventid	int	int
msg	text/string	text/string
level	int (0-100)	int (0-100)
cat (source module name)	text/string	text/string
dst (ip address)	text/string	text/string
request (url)	text/string	text/string
fname (certificate name)	text/string	text/string
outcome (new http status)	text/string	text/string
act (port status)	text/string	text/string

Endpoint: https://shadowtrackr.com/api/v3/mailservers
Example JSON post data:

{"api_key": "[API_KEY]"}

This will return a list of all the mailservers we found in your DNS MX or SPF records. You can use it to check against firewall or netflow logs to find out if any non published mailservers are sending mail. This should expose the spammers and phishers in your network.

Endpoint: https://shadowtrackr.com/api/v3/hosts
If you don't provide any of the optional parameters (except of course the required API key), all hosts seen in the last 3 days will be returned. You can add an ip address (ipv4 or ipv6) as an optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "ip": "139.162.214.30"}

This example query will return the data we have on a specific IP address, including a list of security warnings and problems (if we found any).


{"results":4,
 "error":"",
 "data":[{
    "ip":"139.162.214.30",
    "tags":["mailserver"],
    "problems":[],
    "warnings":[],
    "tcp":[{
            "port":"80",
            "protocol":"tcp",
            "service":"http",
            "service_description":"World Wide Web HTTP",
            "state_description":"",
            "state":"ok"
          },
          {
            "port":"443",
            "protocol":"tcp",
            "service":"https",
            "service_description":"secure http (SSL)",
            "state_description":"",
            "state":"ok"
    }],
    "udp":[],
    "city":"London",
    "country":"UK",
    "latitude":"51.5164",
    "longitude":"-0.093",
    "asn":"63949",
    "asn_name":"LINODE-AP Linode, LLC, US",
    "asn_country":"US",
    "asn_allocated":"2015-02-16",
    "prefix":"139.162.192.0\/19",
    "prefix_registry":"ripencc",
    "prefix_allocated":"1990-03-24",
    "isp":"Linode, LLC",
    "organization":"",
    "reverse_dns":["rainbowdash.shadowtrackr.com"],
    "websites":["shadowtrackr.com"],
    "dns":["shadowtrackr.com", "rainbowdash.shadowtrackr.com"]
    }
 ]}

Endpoint: https://shadowtrackr.com/api/v3/websites
If you don't provide any of the optional parameters (except of course the required API key), all websites seen in the last 3 days will be returned. You can add an ip address (ipv4 or ipv6), url ("www.shadowtrackr.com"), domain ("shadowtrackr.com"), or software ("jQuery 3.4.1") as optional parameters. Note that if a url has both an ipv4 and and ipv6 version you should see both returned. In the example below we filtered out the ipv6 version for brevity. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadowtrackr.com"}

This example query will return the data we have on a specific website, including a list of security warnings and problems (if we found any). If we detect software with a versionnumber, we'll check it against existing exploits and list the CVE numbers and severity for you.


{"results":1,
 "error":"",
 "data":[{
    "url":"shadowtrackr.com",
    "problems":[
        "Content Security Policy (CSP) implemented unsafely. This includes 'unsafe-inline' or data: inside script-src, overly broad sources such as https: inside object-src or script-src, or not restricting the sources for object-src or script-src."
    ],
    "warnings":[],
    "host":"139.162.214.30",
    "cloud":"Microsoft Azure Europe West",
    "security_grade":"A",
    "tags":["webserver"],
    "jarmhash":"28d28d28d2ad28d00028d28d28d28de1e2a7f686507340c9c0e03ed68e0714",
    "mmh3":"953957588",
    "external_scripts":"",
    "external_css":"",
    "software":[
        "Google Analytics",
        "Nginx 1.17.10",
        "jQuery 3.4.1"
    ],
    "vulnerabilities": [
        {"name": "jQuery 1.11.2", 
         "vulnerabilities": [
             {"name": "CVE-2019-11358",
              "cvss": "4.3", 
              "description": "jQuery before 3.4.0, as used in Drupal, Backdrop CMS, and other products, mishandles jQuery.extend(true, {}, ...) because of Object.prototype pollution. If an unsanitized source object contained an enumerable __proto__ property, it could extend the native Object.prototype."
             }, 
             {"name": "CVE-2015-9251", 
              "cvss": "4.3", 
              "description": "jQuery before 3.0.0 is vulnerable to Cross-site Scripting (XSS) attacks when a cross-domain Ajax request is performed without the dataType option, causing text/javascript responses to be executed."
             }
         ]
        }
    ], 
    "http_server":"nginx\/1.17.10",
    "https_server":"nginx\/1.17.10",
    "http_status":"200",
    "https_status":"200",
    "http_redirect_history":[],
    "https_redirect_history":[],
    "http_title":"Find and monitor your attack surface - ShadowTrackr.com",
    "https_title":"Find and monitor your attack surface - ShadowTrackr.com",
    "http_raw_headers":"server: nginx\/1.17.10\ndate: Sun, 21 Jun 2020 05:33:01 GMT\ncontent-type: text\/html; charset=UTF-8\ntransfer-encoding: chunked\nconnection: keep-alive\nvary: Accept-Encoding\nset-cookie: __Secure-shadowtrackr_session=6bie1btuc290l59ket57abegb4; expires=Tue, 23-Jun-2020 05:33:01 GMT; Max-Age=172800; path=\/; secure; HttpOnly\nexpires: Thu, 19 Nov 1981 08:52:00 GMT\ncache-control: no-store, no-cache, must-revalidate\npragma: no-cache\nx-xss-protection: 1; mode=block\nstrict-transport-security: max-age=31536000; includeSubDomains\nreferrer-policy: strict-origin\nx-content-type-options: nosniff\ncontent-security-policy: connect-src 'self' www.google-analytics.com js.stripe.com; script-src 'unsafe-inline' ajax.googleapis.com www.gstatic.com 'self' js.stripe.com www.google-analytics.com data; form-action 'self'; img-src 'self' www.google-analytics.com chart.googleapis.com q.stripe.com js.stripe.com data; frame-src 'self' js.stripe.com; style-src 'self' 'unsafe-inline' js.stripe.com www.gstatic.com; default-src 'none'; frame-ancestors 'self'; base-uri 'self'; font-src 'self'\ncontent-encoding: gzip",
    "https_raw_headers":"server: nginx\/1.17.10\ndate: Sun, 21 Jun 2020 05:32:52 GMT\ncontent-type: text\/html; charset=UTF-8\ntransfer-encoding: chunked\nconnection: keep-alive\nvary: Accept-Encoding\nset-cookie: __Secure-shadowtrackr_session=eb7rj98olugrnp4581hpp6dfrf; expires=Tue, 23-Jun-2020 05:32:52 GMT; Max-Age=172800; path=\/; secure; HttpOnly\nexpires: Thu, 19 Nov 1981 08:52:00 GMT\ncache-control: no-store, no-cache, must-revalidate\npragma: no-cache\nx-xss-protection: 1; mode=block\nstrict-transport-security: max-age=31536000; includeSubDomains\nreferrer-policy: strict-origin\nx-content-type-options: nosniff\ncontent-security-policy: connect-src 'self' www.google-analytics.com js.stripe.com; script-src 'unsafe-inline' ajax.googleapis.com www.gstatic.com 'self' js.stripe.com www.google-analytics.com data; form-action 'self'; img-src 'self' www.google-analytics.com chart.googleapis.com q.stripe.com js.stripe.com data; frame-src 'self' js.stripe.com; style-src 'self' 'unsafe-inline' js.stripe.com www.gstatic.com; default-src 'none'; frame-ancestors 'self'; base-uri 'self'; font-src 'self'\ncontent-encoding: gzip"
    }
 ]}

Endpoint: https://shadowtrackr.com/api/v3/certificates
If you don't provide any of the optional parameters (except of course the required API key), all certificates seen in the last 3 days will be returned. You can add an ip address (ipv4 or ipv6), url ("www.shadowtrackr.com") or a domain ("shadowtrackr.com") as optional parameters. Note that if a url has both an ipv4 and and ipv6 version you should see both returned. In the example below we filtered out the ipv6 version for brevity. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadowtrackr.com"}

This example query will return the data we have on a specific certificate, including a list of security warnings and problems (if we found any).


{"results":1,
 "error":"",
 "data":[{
    "url":"shadowtrackr.com",
    "scanned_urls":["shadowtrackr.com", "rainbowdash.shadowtrackr.com"],
    "tags":[],
    "problems":[],
    "warnings":[
        "Use of weak cryptographic suites: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"
    ],
    "vulnerabilities":["BREACH", "LUCKY13"],
    "host":"2a01:7e00:0:0:f03c:92ff:fea7:cd64",
    "cloud":"",
    "common_names":[
        "shadowtrackr.com"
    ],
    "subject_alternative_names":[
        "rainbowdash.shadowtrackr.com",
        "shadowtrackr.com"
    ],
    "security_grade":"A+",
    "servername":"nginx\/1.17.10",
    "not_valid_before":"2020-05-23 07:11:44",
    "not_valid_after":"2020-08-21 07:11:44",
    "signature_algorithm":"SHA256withRSA",
    "serialnumber":"04746b8252e002e41f91",
    "security_contact":"",
    "pinsha256":"",
    "sha1hash":"75133fc63f91584a1c32c04c52c81c23ae6ab8de",
    "sha256hash":"4932ff66b9ccf2867ea2916fdad7efc2d6f3c53605ff56084c65d88e3b47d3d9",
    "key_algorithm":"EC",
    "keysize":"256",
    "issuer":"Let's Encrypt Authority X3",
    "caa_email":"",
    "caa_issuers":[],
    "caa_policyhost":"",
    "protocols":[{
        "name":"TLS 1.2",
        "state":"ok",
        "description":""
    }],
    "cryptographic_suites":[{
        "name":"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
        "state":"warning",
        "description":""},{
        "name":"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
        "state":"ok",
        "description":""
        },{
        "name":"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
        "state":"ok",
        "description":""
   }]
  }
]}

Endpoint: https://shadowtrackr.com/api/v3/dns
If you don't provide any of the optional parameters (except of course the required API key), all DNS records we have for your domains will be returned. You can add an optional url ("shadowtrackr.com"), record_type (A, AAAA, MX, TXT, NS) or content ("139.162.198.183", "SPF") as optional parameters. Example JSON post data:

{"api_key": "[API_KEY]", "url": "www.shadowtrackr.com"}

This example query will return the DNS records we have on www.shadowtrackr.com (note that if you query a subdomain, you'll not get the TXT and MX records for the domainname itself).


{"results":2,
 "error":"",
 "data:[{
    "url": "shadowtrackr.com", 
    "tags": [],
    "rrtype": "AAAA", 
    "rrsubtype": "", 
    "rrdata": "2a01:7e00::f03c:92ff:fea7:cd64", 
    "mailserver": "",
    "priority": 0, 
    "weight": 0,
    "port": 0,
    "target": "",
    "mname": "", 
    "rname": "",
    "serial": 0 ,
    "refresh": 0,
    "retry":": 0,
    "expire": 0,
    "minimum": 0,
    "flags": 0,
    "tag": "",
    "value": "",
    "v": "",
    "k": "",
    "p": "",
    "t": "",
    "pct": "",
    "ruf": "", 
    "rua": "",
    "sp": "",
    "adkim": "",
    "aspf": "",
    "cloudprovider": "",
    "first_seen": "2020-06-26", 
    "last_seen": "2022-05-28"
    }, {
    "url": "shadowtrackr.com", 
    "tags": [],
    "rrtype": "SOA", 
    "rrsubtype": "", 
    "rrdata": "pdns13.domaincontrol.com. dns.jomax.net. 2021103122 28800 7200 604800 600", 
    "mailserver": "",
    "priority": 0, 
    "weight": 0,
    "port": 0,
    "target": "",
    "mname": "", 
    "rname": "",
    "serial": 0 ,
    "refresh": 0,
    "retry":": 0,
    "expire": 0,
    "minimum": 0,
    "flags": 0,
    "tag": "",
    "value": "",
    "v": "",
    "k": "",
    "p": "",
    "t": "",
    "pct": "",
    "ruf": "", 
    "rua": "",
    "sp": "",
    "adkim": "",
    "aspf": "",
    "cloudprovider": "",
    "first_seen": "2020-06-26", 
    "last_seen": "2022-05-28"
    }
]}

Endpoint: https://shadowtrackr.com/api/v3/whois
If you don't provide any of the optional parameters (except of course the required API key), all whois records we have for your domains will be returned. You can add an optional domain ("shadowtrackr.com") as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadowtrackr.com"}

This example query will return the whois data we have on the domain shadowtrackr.com.


{"results":1,
 "error":"",
 "data":[{
    "url":"shadowtrackr.com",
    "tags":[],
    "name":"",
    "organization":"",
    "registrar":"GoDaddy.com, LLC",
    "dnssec":"signedDelegation",
    "status": [ "clientDeleteProhibited https:\/\/icann.org\/epp#clientDeleteProhibited", 
                "clientRenewProhibited https:\/\/icann.org\/epp#clientRenewProhibited", 
                "clientTransferProhibited https:\/\/icann.org\/epp#clientTransferProhibited",
                "clientUpdateProhibited https:\/\/icann.org\/epp#clientUpdateProhibited"
              ]
    "whois_server":"whois.godaddy.com",
    "nameservers":[
        "PDNS13.DOMAINCONTROL.COM",
        "PDNS14.DOMAINCONTROL.COM"
    ],
    "creation_date":"2017-05-15",
    "expiration_date":"2021-05-15",
    "updated_date":"2020-05-16"
 }
]}

Endpoint: https://shadowtrackr.com/api/v3/urls
If you don't provide any of the optional parameters (except of course the required API key), all urls we have for you will be returned. You can add a keyword (wildcard * is allowed: "shadowtrackr.com") as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadow*"}

This example query will return the urls we have for the domain shadowtrackr.com (which matches the wildcard).


{"results":1,
 "error":"",
 "data":[{
    "url":"shadowtrackr.com",
    "tags": [],
    "created":"2017-05-15",
    "pay_level_domain":"1"
 }
]}

List domain data

Endpoint: https://shadowtrackr.com/api/v3/domains
If you don't provide any of the optional parameters (except of course the required API key), all your domains will be returned. You can filter for a domain (wildcard * is allowed: "shadow*") as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "domain": "shadowtrackr.com"}

This example query will return the data we have for the domain shadowtrackr.com. Note that if you want more whois data you'll have to use the whois endpoint.


{"results":1,
 "error":"",
 "data":[{
    "domain":"shadowtrackr.com",
    "tags": [],
    "dnssec":"yes",
    "mx":2,
    "spf": "\"v=spf1 mx -all\"",
    "subdomains":["www.shadowtrackr.com", "mail.shadowtrackr.com"]
 }
]}

Endpoint: https://shadowtrackr.com/api/v3/subnets
If you don't provide any of the optional parameters (except of course the required API key), all your subnets will be returned. You can add a cidr (wildcard * is allowed: "1.1.1.*/27") as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "cidr": "2.2.2.*"}

This example query will return the subnets we have for the ip range 2.2.2.0 - 2.2.2.255 (which matches the wildcard).


{"results":1,
 "error":"",
 "data":[{
    "url":"2.2.2.0/16",
    "tags": [],
    "created":"2017-05-15",
    "hosts":["2.2.2.1", "2.2.2.13"]
 }
]}

Endpoint: https://shadowtrackr.com/api/v3/cloud_providers
This endpoint will return all cloud providers we have seen for your assets in the last 3 weeks. Example JSON post data:

{"api_key": "[API_KEY]"}

This example query will return:


{"results":1,
 "error":"",
 "data":[{
    "cloudprovider":"Amazon EC2 us-east-2",
    "assets":"1",
    "urls":"shadowtracker.com, mail.shadowtrackr.com"
 }
]}

Endpoint: https://shadowtrackr.com/api/v3/remote_login_services
This endpoint will return all remote login services we have seen on your assets in the last 3 weeks. Example JSON post data:

{"api_key": "[API_KEY]"}

This example query will return:


{"results":1,
 "error":"",
 "data":[{
    "url":"remote.shadowtrackr.com",
    "ip":"139.162.214.30",
    "first_seen":"2017-05-15",
    "last_seen":"2021-01-15",
    "type":"Citrix Netscaler"
 }]
}

List phishy domains

Endpoint: https://shadowtrackr.com/api/v3/phishy_domains
Phishy domains are domain names that resemble your domain name (think of typosquatting) and can be used for phishing. If you don't provide the optional domain, data for all phishy domains will be returned. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadowtrackr.com"}

This example query will return the phishy domains we track for the domain shadowtrackr.com.


{"results":1,
 "error":"",
 "data":[{
    "url":"shad0wtrackr.com",
    "registrar":"GoDaddy.com, LLC",
    "isp":"Linode",
    "city":"London",
    "country":"UK",
    "jarmhash":"2ad2ad0002ad2ad00042d42d0000005d86ccb1a0567e012264097a0315d7a7",
    "mmh3":"-1561873722",
    "nameservers":[
        "PDNS13.DOMAINCONTROL.COM",
        "PDNS14.DOMAINCONTROL.COM"
    ],
    "mailservers":[
    ],
    "whois": [
        // optional whois data
    ],
    "web": [
        // optional website metadata
    ],
    "cert": [
        // optional certificate data
    ]
 }]
}

Endpoint: https://shadowtrackr.com/api/v3/exposed_email_addresses
If you don't provide any of the optional parameters (except of course the required API key), all email addresses we have for you will be returned. You can add an email address (wildcard * is allowed) as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "url": "*@shadowtrackr.com"}

This example query will return the email addresses we have for the domain shadowtrackr.com (which matches the wildcard).


{"results":1,
 "error":"",
 "data":[{
    "email":"support@shadowtrackr.com",
    "websites": ["shadowtrackr.com"],
    "breaches": [
        {\"name\": \"PDL\", \"breached\": \"2019-10-16\"},
        {\"name\": \"YouveBeenScraped\", \"breached\": \"2018-10-05\"}
    ]
 }
]}

Endpoint: https://shadowtrackr.com/api/v3/blacklisted_assets
If you don't provide any of the optional parameters (except of course the required API key), all blacklisted assets we have for you will be returned. You can add an ip or url (wildcard * is allowed) as optional parameter. Example JSON post data:

{"api_key": "[API_KEY]", "ip": "*"}

This example query will return all ip addresses (wildcard matches all ips, but no urls) that are or have been blacklisted in the last week. Ip addresses will have a description, urls do not.


{"results":1,
 "error":"",
 "data":[
    {'ip': '2.2.2.2', 
     'first_seen': '2021-01-26 03:16:35', 
     'last_seen': '2021-10-24 03:16:35', 
     'blacklist': 'Sorbs.net spammer list', 
     'desc': 'test.shadowtrackr.com'}
]}

Endpoint: https://shadowtrackr.com/api/v3/software
This provides an overview of all software found on your external attack surface. It's grouped by software category with a tally for how often the software is found and shows if any CVEs are known for the software. If you want to find the assets with the software, please use the websites endpoint for that. Example JSON post data:

{"api_key": "[API_KEY]", "url": "shadowtrackr.com"}

This example query will return the software found on all your assets.


[{'category': 'Font Scripts', 
   'count': 6, 
   'product': 'Google Font API',
   'cves': []
  },
  {'category': 'Web Frameworks', 
   'count': 1,
   'product': 'Bootstrap 3.3.5',
   'cves': [{'cve': 'CVE-2019-8331',
             'cvss2': '4.3',
             'cvss2_severity': 'MEDIUM',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap before 3.4.1 and 4.3.x before 4.3.1, XSS is possible in the tooltip or popover data-template attribute.'
            },
            {'cve': 'CVE-2018-20677',
             'cvss2': '4.3',
             'cvss2_severity': 'MEDIUM',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap before 3.4.0, XSS is possible in the affix configuration target property.'},
            {'cve': 'CVE-2018-20676',
             'cvss2': '4.3',
             'cvss2_severity': 'MEDIUM',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap before 3.4.0, XSS is possible in the tooltip data-viewport attribute.'},
            {'cve': 'CVE-2016-10735',
             'cvss2': '4.3',
             'cvss2_severity': '4.3',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap 3.x before 3.4.0 and 4.x-beta before 4.0.0-beta.2, XSS is possible in the data-target attribute, a different vulnerability than CVE-2018-14041.'},
            {'cve': 'CVE-2018-14042',
             'cvss2': '4.3',
             'cvss2_severity': 'MEDIUM',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap before 4.1.2, XSS is possible in the data-container property of tooltip.'},
            {'cve': 'CVE-2018-14040',
             'cvss2': '4.3',
             'cvss2_severity': 'MEDIUM',
             'cvss3': '6.1',
             'cvss3_severity': 'MEDIUM',
             'summary': 'In Bootstrap before 4.1.2, XSS is possible in the collapse data-parent attribute.'}
   ]}, 
  {'category': 'CMS',
   'count': 4,
   'product': 'Drupal 8',
   'cves': []
  }
]}

Endpoint: https://shadowtrackr.com/api/v3/graph

This endpoint is decommissioned. It relied on software that is no longer maintained and proved quite a burden to keep it running. Since no one used this in production, it is gone now. If you do have a need to use this in production, please let us know and we'll put it on the backlog again.

Endpoint: https://shadowtrackr.com/api/v3/add_assets
Example JSON post data:

{"api_key": "[API_KEY]", "assets": ["asset1", "asset2"]}

This will (bulk) add assets. You can mix and match urls, ips and subnets.

If you add the optional extract_domains flag then all pay level domains will automatically be extracted from subdomains and added too. So this:

{"api_key": "[API_KEY]", "assets": ["www.shadowtrackr.com"], "extract_domains": True}

Will add both "www.shadowtrackr.com" and "shadowtrackr.com".

Each of these is a valid list of assets:


"assets": ["www.shadowtrackr.com"]
"assets": ["www.shadowtrackr.com", "mail.shadowtrackr.com"]
"assets": ["www.shadowtrackr.com", "139.162.249.50"] 
"assets": ["www.shadowtrackr.com", "139.162.249.50", "176.58.118.132"]
"assets": ["www.shadowtrackr.com", "139.162.249.50", "1.1.1.1/29"]

Endpoint: https://shadowtrackr.com/api/v3/remove_assets
Example JSON post data:

{"api_key": "[API_KEY]", "assets": ["asset1", "asset2"]}

This will (bulk) remove assets. You can mix and match urls, ips and subnets.

Note that this endpoint has extra options:

"timeline": true
Removes all messages on the timeline that relate to the deleted assets

"related": true
Removes all related assets (like dns records, certificates, etc)

"include_hosts": true
Removes all hosts in a subnet too (if you are deleting a subnet)

Each of these is a valid list of assets:


"assets": ["www.shadowtrackr.com"]
"assets": ["www.shadowtrackr.com", "mail.shadowtrackr.com"]
"assets": ["www.shadowtrackr.com", "139.162.249.50"] 
"assets": ["www.shadowtrackr.com", "139.162.249.50", "176.58.118.132"]
"assets": ["www.shadowtrackr.com", "139.162.249.50", "1.1.1.1/29"]

Endpoint: https://shadowtrackr.com/api/v3/ignore_urls
Example JSON post data:

{"api_key": "[API_KEY]", "urls": ["test1.shadowtrackr.com", "test2.shadowtrackr.com"]}

This will ignore all urls you specify. If you add extra options, these will be used for all urls listed.

This endpoint has extra options:

"ignore_subdomains": true
Sets the ignore flag for any existing and newly found subdomains of the urls listed too (default: true).

Endpoint: https://shadowtrackr.com/api/v3/unignore urls
Example JSON post data:

{"api_key": "[API_KEY]", "urls": ["test1.shadowtrackr.com", "test2.shadowtrackr.com"]}

This will ignore all urls you specify. If you add extra options, these will be used for all urls listed.

This endpoint has extra options:

"unignore_subdomains": true
Also removes the ignore flag for subdomains (default: true).

Endpoint: https://shadowtrackr.com/api/v3/delete_all_my_data
Example JSON post data:

{"api_key": "[API_KEY]", "admincode": "[ADMINCODE]"}

This will delete all your data. Everything. So only use this if you want to start over with a clean account.

Note that you'll need an extra [ADMINCODE] for this to work. The admin code can be found on the Settings->API access page if you are an admin. If you're not an admin, you'll have to ask one.

Endpoint: https://shadowtrackr.com/api/v3/initial_scan_progress
If you can't wait to play with the API but don't know if you're data is ready yet, you can use the endpoint to check the scan status. If total_assets is bigger than zero and scan_activity_in_last_5m is nearing zero (preferably zero), then your initial scan is done. See the Python API on Github for a working example. This endpoint has no parameters other then the api_key. Example:

{"api_key": "[API_KEY]"}

This example query will return how many assets you have and how many new things were found in the last five minutes.


{"results":1,
 "error":"",
 "data":{'hosts_in_last_5m': '1', 
         'websites_in_last_5m': '0', 
         'certificates_in_last_5m': '0', 
         'dns_in_last_5m': '2', 
         'suggestions_in_last_5m': '0', 
         'scan_activity_in_last_5m': 3, 
         'total_urls': '5', 
         'total_hosts': '2', 
         'total_subnets': '0', 
         'total_assets': 7
 }
]}

You can get the graphs from the GUI in two ways: as an HTML rendered page that you can embed in a website, or as raw JSON data.

The HTML rendered graph is available at this endpoint:
https://shadowtrackr.com/api/v3/usergraphs?api_key=[API_KEY]

The JSON data is available at:
https://shadowtrackr.com/api/v3/usergraphs_data?api_key=[API_KEY]

For both endpoints, you get the default configured Attack Surface graph. It is possible to get other, custom graphs that you have created in the GUI. To do this, lookup the GID (Graph ID) in the GUI and add it to the endpoint url. For example, if your GID is 13, then add &gid=13 to get that graph. The default color scheme has a white background. If you rather have it dark, then add &darkmode=1 to the endpoint url.

The JSON data returned by usergraphs_data is returned as a list of nodes, follow by a list of links (or "edges") between those nodes. This is what you need if you're creating your own force-directed graph. The nodes have a label with the URL, IP or ASN information and a group. The group is what determines the color of the node in the graph:

Group	Color	Meaning
1	● #5659B1	ASN/ISP
2	● #46AF80	Host
3	● #477DA3	URL
5	● #000	Cloud
100	● #F70A03	Problem
101	● #FF8300	Warning

If you need to whitelist the IP addresses of the shadowtrackr nodes in your firewall, it is best to automate it.
To do that you can use this endpoint:
https://shadowtrackr.com/api/v3/shadowtrackr_ip_whitelist?api_key=[API_KEY]


{"results": 2, 
 "data": [
    {"node": "newark-node-2",
     "ipv4": "104.237.147.98",
     "ipv6":"2600:3c03::f03c:92ff:fe30:1bd7"
    },
    {"node": "fremont-node-2",
     "ipv4": "104.237.155.167",
     "ipv6": "2600:3c01::f03c:92ff:feb3:df29"
    }
 ]
}

Some endpoints can provide extra data that can be handy if you want to do data science. Endpoints supporting this are: hosts, certificates, websites, whois and dns. All you have to do is add the extra parameter "full" and set it to true, example:

{"api_key": "[API_KEY]", "full", True}

Note that the extra data varies per endpoint. It varies from first of last seen dates to raw scan output.

Overview
Use cases
Plans and pricing
FAQ

Resources
API
Blog
Documentation

Apps
Web
iOS
Android

Company
About
Contact us
Legal & Policy

ShadowTrackr

ShadowTrackr API v3

API Key

Python module

Passing parameters to endpoints

Query endpoint

Timeline feed

List of your current mailservers

List host data

List websites data

List TLS certificate data

List DNS data

List whois data

List url data

List domain data

List subnet data

List cloud providers

List remote login services

List phishy domains

List exposed email address data

List blacklisted assets

List software found

Get graph as PNG image

Add assets

Remove assets

Ignore urls

Unignore urls

Delete all my data

Initial scan progress

Get graphs

Shadowtrackr Node IP whitelist

Get raw data