ShadowTrackr API v4

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 domain data that you can use to enrich the data you already have in your other security systems. A feed of your events is available in both JSON and ArcSight CEF formats, all other endpoints only support JSON.

All returned JSON data will have the following structure:

{ results: "a string that describes what happened if the call to the endpoints was successful",
  data: [{"fields": "with",
         "your": "data"}
        ],
  error: "an error message if something went wrong"

If you are looking for the old documentation (please don't), look at API Version 3.

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 endpoints as described below.

Installation

    pip install shadowtrackr

Usage

    from shadowtrackr import ShadowTrackr
    import json

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

    result = st.query("index=hosts problem=yes earliest=-10d")
    print(json.dumps(result, indent=2))

The current version of the python module uses the v4 API. If you updated the module with pip but your code still uses the v3 api, please do the following after initialization and you will be fine:

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

Query endpoint

Endpoint: https://api.shadowtrackr.com/api/v4/query

From version 3 of the API you can use any query that works in the GUI, including the magic queries. For more information on how to make queries, please see Query syntax and Data Model. The returned data is a JSON formatted list of your search results. The exact structure depends on your query, just like in the GUI.

All other endpoints are shortcuts that directly get data from the most used indexes. They often show more data fields than a standard query. This is because queries are designed to show you the most useful fields only and hide anything that clutters the screen. You can have queries show more columns, but you have to explictly select that. All other endpoints here are designed for API queries where you just want a bunch of useful data.

Event feed

Endpoint: https://api.shadowtrackr.com/api/v4/events
This endpoint provides a stream with all your events. The endpoint by will always return the last 1000 messages. If you only want the updates this is not fun to parse, set updates_only to True.

Options

Parameter	Type	Description
update_only	bool	If set to True, only the new events since your last poll will be returned.
start	Timestamp	Start of the time period you want events for in UTC, e.g. "2026-03-13T10:00:00"
stop	Timestamp	End of the time period you want events for in UTC, e.g. "2026-03-13T12:00:00"
output_format	String	"JSON" (default) or "CEF" (Arcsight)

Mailservers

Endpoint: https://api.shadowtrackr.com/api/v4/mailservers

This will return a list of all the mailservers we found in your DNS MX or SPF records. Only data from the last 7 days is returned, if you want to list historical data you can do that through the query endpoint. 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.

Hosts

Endpoint: https://api.shadowtrackr.com/api/v4/hosts

If you don't provide any of the optional parameters, all hosts seen in the last 7 days will be returned. You can add an ip address (ipv4 or ipv6) as an optional parameter.

Options

Parameter	Type	Description
ip	str	The ip address of the host you want data for
full	bool	If set to True, some extra data fields will be returned

Websites

Endpoint: https://api.shadowtrackr.com/api/v4/websites
If you don't provide any of the optional parameters, all websites seen in the last 7 days will be returned. You can add an ip address (ipv4 or ipv6), url ("www.shadowtrackr.com") or domain ("shadowtrackr.com") as optional parameters. Note that if a url has both an ipv4 and and ipv6 version you should see both returned.

Options

Parameter	Type	Description
url	str	The url of the website you want data for
domain	str	The domain of the websites you want data for
ip	str	The ip address of the websites you want data for
full	bool	If set to True, some extra data fields will be returned

Certificates

Endpoint: https://api.shadowtrackr.com/api/v4/certificates

If you don't provide any of the optional parameters, all certificates seen in the last 7 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.

Options

Parameter	Type	Description
url	str	The url of the certificates you want data for
domain	str	The domain of the certficates you want data for
ip	str	The ip address of the certificate you want data for
full	bool	If set to True, some extra data fields will be returned

DNS

Endpoint: https://api.shadowtrackr.com/api/v4/dns

If you don't provide any of the optional parameters, all DNS records we seen for your urls and domains in the last 7 days will be returned. You can add an optional url ("shadowtrackr.com"), rrtype (A, AAAA, MX, TXT, NS) or rrdata ("139.162.198.183", "SPF") as optional parameters.

Options

Parameter	Type	Description
url	str	The url of the DNS records you want data for
rrdata	str	The content (rrdata) of the DNS records you want data for
rrtype	str	The record type (rrtype:A, AAAA, MX, SOA, etc) of DNS records you want data for

Domains

Endpoint: https://api.shadowtrackr.com/api/v4/domains

If you don't provide any of the optional parameters, all domain records we have for your domains seen in the last 7 days will be returned. You can add an optional domain ("shadowtrackr.com") to search for a specific domain.

Options

Parameter	Type	Description
domain	str	The domain you want data for

Urls

Endpoint: https://api.shadowtrackr.com/api/v4/urls

If you don't provide any of the optional parameters, all urls we have seen in the last 7 days will be returned. You can add a keyword (wildcard * is allowed: "shadowtrackr.com") as optional parameter.
This example query will return the urls we have for the domain shadowtrackr.com (which matches the wildcard).

Options

Parameter	Type	Description
url	str	The url you want data for

Subnets

Endpoint: https://api.shadowtrackr.com/api/v4/subnets

If you don't provide any of the optional parameters, all your subnets will be returned (including those seen longer than 7 days ago. You can add a cidr (wildcard * is allowed: "1.1.1.*/27") as optional parameter.

Options

Parameter	Type	Description
cidr	str	The cidr (10.0.0.0/16) of the subnet you want data for

Cloud providers

Endpoint: https://api.shadowtrackr.com/api/v4/cloud_providers

This endpoint will return all cloud providers we have seen for your assets in the last 7 days.

Remote login services

Endpoint: https://api.shadowtrackr.com/api/v4/remote_login_services

This endpoint will return all remote login services we have seen on your assets in the last 7 days.

Phishy domains

Endpoint: https://api.shadowtrackr.com/api/v4/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 seen in the last 7 days will be returned.

Options

Parameter	Type	Description
domain	str	The domain you want the phishy domain data for

Exposed email addresses

Endpoint: https://api.shadowtrackr.com/api/v4/exposed_email_addresses

If you don't provide any of the optional parameters, all email addresses seen in the last 7 days will be returned. You can add an email address (wildcard * is allowed) as optional parameter.

Options

Parameter	Type	Description
email	str	The email address you want data for

Suggestions

Endpoint: https://api.shadowtrackr.com/api/v4/suggestions

This will return all your current suggestions. ShadowTrackr will try to determine if an asset found in the discovery process is yours. If we are sure, it will be automatically added. If not, it will appear in your suggestions and you can decide for yourself.

Blacklisted assets

Endpoint: https://api.shadowtrackr.com/api/v4/blacklisted_assets

If you don't provide any of the optional parameters, all blacklisted assets we have for you will be returned. You can add an ip or url (wildcard * is allowed) as optional parameter.
This example query will return all ip addresses (wildcard matches all ips, but no urls) that are or have been blacklisted in the last 7 days. Ip addresses will have a description, urls do not.

Options

Parameter	Type	Description
ip	str	The ip address you want data for
url	str	The url you want data for

Software

Endpoint: https://api.shadowtrackr.com/api/v4/software

This provides an overview of all software found on your external attack surface and seen in the last 7 days. 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.

Vulnerabilities

Endpoint: https://api.shadowtrackr.com/api/v4/vulnerabilities

This provides an overview of all vulnerabilities found on your external attack surface and seen in the last 7 days. It's grouped by software and shows which assets are affected and which CVEs are known for the software.

Suppliers

Endpoint: https://api.shadowtrackr.com/api/v4/suppliers

The endpoint will return all suppliers that have been seen in the last 7 days. Suppliers can be ISPs, Certificate Authorities, Domain registrars, software suppliers, etc.

Internet Standards

Endpoint: https://api.shadowtrackr.com/api/v4/internet_standards

This endpoint will return the data for items from the Internet Standards checks. The same checks as on internet.nl are done, although some are implemented differently.

CVEs assets

Endpoint: https://api.shadowtrackr.com/api/v4/cves_assets

This endpoint returns a denormalized list of all vulnerabilities seen on your assets in the last 7 days. Each output item contains one CVE and one asset.

Assets

Endpoint: https://api.shadowtrackr.com/api/v4/assets

This endpoint gives you the amount of assets you currently have. It also has the number of suggestions.

Add assets

Endpoint: https://api.shadowtrackr.com/api/v4/add_assets

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, to domain "shadowtrackr.com" will be extracted from "www.shadowtrackr.com" in the example and added. After this Shadowtrackrs discovery function will start finding and monitoring more subdomains of shadowtrackr.com.
If you leave the optional extract_domains flag out, then by default it is of and no domains will be extracted.

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
extract_domains	bool	If True, domains will be extracted from urls and added too

Delete assets

Endpoint: https://api.shadowtrackr.com/api/v4/delete_assets

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

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
timeline	bool	If True, deletes all messages on the timeline that relate to the deleted assets
related	bool	If True, deletes all related assets (like dns records, certificates, etc)
invclude	bool	If True, deletes all hosts in a subnet too (if you are deleting a subnet)

Add tags

Endpoint: https://api.shadowtrackr.com/api/v4/add_tags

This will add all listed tags to all assets mentioned. You can mix and match urls, ips and subnets in the asset list.
There is an optional inherit flag that is True by default. If true, all hosts in a subnet will inherit tags you add to the subnet and all websites, certificates and domains will inherit the tag from a url. If you don't want this you should set the inherit to False like this:

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
tags	list of str	A list of tags you want to the assets
inherit	bool	If True, all hosts in a subnet will inherit tags you add to the subnet and all websites, certificates and domains will inherit the tag from a url

Delete tags

Endpoint: https://api.shadowtrackr.com/api/v4/delete_tags

This will delete all listed tags from all assets mentioned. You can mix and match urls, ips and subnets in the asset list.
There is an optional inherit flag that is True by default. If true, all tags mentioned will be deleted from the hosts in a subnet too if your remove them from a subnet. Similarly, tags will be removed from all websites, certificates and domains for a url if you remove them from a url. If you don't want this you should set the inherit to False like this:

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
tags	list of str	A list of tags you want to the assets
inherit	bool	If True, all tags mentioned will be deleted from the hosts in a subnet too if your remove them from a subnet

Ignore urls

Endpoint: https://api.shadowtrackr.com/api/v4/ignore_urls

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


Options

Parameter	Type	Description
urls	list of str	A list of urls to ignore
ignore_subdomains	bool	If True, any existing and newly found subdomains of the urls listed too

Unignore urls

Endpoint: https://api.shadowtrackr.com/api/v4/unignore_urls

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


Options

Parameter	Type	Description
urls	list of str	A list of urls to unignore
unignore_subdomains	bool	If True, the ignore flag for subdomains is removed too

Delete all my data

Endpoint: https://api.shadowtrackr.com/api/v4/delete_all_my_data

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://api.shadowtrackr.com/api/v4/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.

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://api.shadowtrackr.com/api/v4/usergraphs

The JSON data is available at:
https://api.shadowtrackr.com/api/v4/usergraphs_data

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

Scannernode IP addresses

Endpoint: https://api.shadowtrackr.com/api/v4/scannernode_ip_addresses

If you need to whitelist the IP addresses of the shadowtrackr nodes in your firewall, it is best to automate it using this endpoint. Nodes ip addresses can change at any time.

Ip info

Endpoint: https://api.shadowtrackr.com/api/v4/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.

Add organization

Endpoint: https://api.shadowtrackr.com/api/v4/add_organization
This endpoint is only for multi-tenant users. It allows you to create an organization in your group. The organization is isolated from any other organizations in the group. The API endpoint returns the API key and admin code, so you can use it like any other organization.

Note that by default the API is always enabled when creating an organization through the API.

List organizations

Endpoint: https://api.shadowtrackr.com/api/v4/organizations
This endpoint is only for multi-tenant users. It shows a list of currently active organizations in your group. It returns the active organization names and IDs.

Delete organization

Endpoint: https://api.shadowtrackr.com/api/v4/delete_organization
This endpoint is only for multi-tenant users. It completely deletes the organization specified.