ShadowTrackr API v3

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.

API Key

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.

Python module

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)

Passing parameters to endpoints

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.

Query endpoint

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'}}
]

Timeline feed

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

List of your current mailservers

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.

List host data

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"]
    }
 ]}

List websites data

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_score": "4.3", 
              "cvss_severity": "MEDIUM", 
              "exploited": False,
              "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_score": "4.3", 
              "cvss_severity": "MEDIUM", 
              "exploited": False,
              "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"
    }
 ]}

List TLS certificate data

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":""
   }]
  }
]}

List DNS data

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"
    }
]}

List whois data

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"
 }
]}

List url data

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"]
 }
]}

List subnet data

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"]
 }
]}

List cloud providers

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"
 }
]}

List remote login services

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
    ]
 }]
}

List exposed email address 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]", "email": "*@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\"}
    ]
 }
]}

List blacklisted assets

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'}
]}

List software found

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',
             'cvss_score': '4.3',
             'cvss_severity': 'MEDIUM',
             'exploited': False,
             'description': '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',
             'cvss_score': '4.3',
             'cvss_severity': 'MEDIUM',
             'exploited': False,
             'description': 'In Bootstrap before 3.4.0, XSS is possible in the affix configuration target property.'},
            {'cve': 'CVE-2018-20676',
             'cvss_score': '4.3',
             'cvss_severity': 'MEDIUM',
             'exploited': False,
             'description': 'In Bootstrap before 3.4.0, XSS is possible in the tooltip data-viewport attribute.'},
            {'cve': 'CVE-2016-10735',
             'cvss_score': '4.3',
             'cvss_severity': '4.3',
             'exploited': False,
             'description': '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',
             'cvss_score': '4.3',
             'cvss_severity': 'MEDIUM',
             'exploited': False,
             'description': 'In Bootstrap before 4.1.2, XSS is possible in the data-container property of tooltip.'},
            {'cve': 'CVE-2018-14040',
             'cvss_score': '4.3',
             'cvss_severity': 'MEDIUM',
             'exploited': False,
             'description': 'In Bootstrap before 4.1.2, XSS is possible in the collapse data-parent attribute.'}
   ]}, 
  {'category': 'CMS',
   'count': 4,
   'product': 'Drupal 8',
   'cves': []
  }
]}

Get graph as PNG image

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.

Add assets

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"]

Remove assets

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"]

Ignore urls

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).

Unignore urls

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).

Delete all my data

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.

Initial scan progress

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
 }
]}

Get graphs

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

Shadowtrackr Node IP whitelist

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"
    }
 ]
}

Ip info

This endpoint provides some common info on IP addresses that are used in ShadowTrackr. It has data on clouds, IANA ranges, common DNS servers, VSAT ranges, VPNs, residential IP addresses, and some more.
We still intent to further develop this, but since it can be useful to prevent false positives when processing IoC lists and generating ip blocklist, the data we have is now available.

Use this endpoint:
https://shadowtrackr.com/api/v3/ip_info?api_key=[API_KEY]&ip=8.8.8.8

{"ip":"8.8.8.8",
 "false_positive_estimate":100,
 "cloud":false,
 "cloud_provider":"",
 "cloud_service":"",
 "cloud_region":"",
 "cdn":false,
 "cdn_provider":"",
 "reverse_dns":"dns.google",
 "tor":false,
 "vpn":false,
 "tags":{"Google DNS"},
 "notes":""
}

Get raw data

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.