securitytrails v2.0.0

SecurityTrails API Wrapper

Installation

npm install securitytrails-js

How to use

In Node.js to create a new API Client:

const securitytrails = require("securitytrails-js");

const STAPI = new securitytrails(API_KEY);

You can then run the API functions which will return a node-fetch Promise, and handle the responses as needed.

See (SecurityTrails API Reference)

Example

const securitytrails = require("securitytrails-js");
const STAPI = new securitytrails(process.env.API_KEY);

const domain = "example.com";
const associatedDomains = await STAPI.domains_associated_domains(domain)
  .then(STAPI.handleErrors)
  .then((response) => {
    return response.json();
  })
  .catch((err) => console.error("error:" + err));

console.log(associatedDomains);

Available Methods

General

Ping

You can use this simple endpoint to test your authentication and access to the SecurityTrails API.

STAPI.ping();

Usage

Usage statistics of the API for the current month

STAPI.usage();

Scroll

A fast and easy way to fetch many results. Currently only available for the DSL API endpoints.

STAPI.scroll(scrollId);

Company

Details

Returns details for a company domain.

STAPI.company_details(domain);

Associated IPs

Returns associated IPs for a company domain. The result is not paginated nor limited. The data is based on whois data with the names matched to the domains.

STAPI.company_associated_ips(domain);

Domains

Details

Returns the current data about the given hostname. In addition to the current data, you also get the current statistics associated with a particular record. For example, for a records you'll get how many other hostnames have the same IP

STAPI.domains_details(hostname);

Subdomains

Returns child and sibling subdomains for a given hostname. Limited to 2000 results for the Free plan and to 10000 for all paid subscriptions.

STAPI.domains_subdomains(
  hostname,
  (childrenOnly = false),
  (includeInactive = true)
);

Tags

Returns tags for a given hostname

STAPI.domains_tags(hostname);

WHOIS

Returns the current WHOIS data about a given hostname with the stats merged together

STAPI.domains_whois(hostname);

Search

Filter and search specific records using this endpoint. With pagination a maximum of 10000 results can be retrieved. To access more results you can use scrolling.

STAPI.domains_search(
  (includeIps = false),
  (page = 1),
  (scroll = false),
  (body = {})
);

Statistics

Domain statistics

STAPI.domains_statistics((body = {}));

Associated domains

Find all domains that are related to a hostname you input. Limited to 10000 results.

STAPI.domains_associated_domains(hostname, (page = 1));

SSL Certificates (Pages)

Fetch current and historical certificate information for any hostname. Limited to 10000 results

STAPI.domains_ssl(
  hostname,
  (includeSubdomains = false),
  (status = "valid"),
  (page = 1)
);

SSL Certificates (Stream)

Fetch current and historical certificate information for any hostname. Returns all results.

STAPI.domains_ssl_stream(
  hostname,
  (includeSubdomains = false),
  (status = "valid")
);

History

DNS

Lists out specific historical information about the given hostname parameter. In addition of fetching the historical data for a particular type, the count statistic is returned as well, which represents the number of that particular resource against current data. (a records will have an ip_count field which will represent the number of records that has the same IP as that particular record) The results are sorted first_seen descending. The number of results is not limited.

STAPI.history_dns(hostname, (type = "a"), (page = 1));

WHOIS

Returns historical WHOIS information about the given domain. The number of results is not limited.

STAPI.history_whois(hostname, (page = 1));

IPs

Neighbors

Returns the neighbors in any given IP level range and essentially allows you to explore closeby IP addresses. It will divide the range into 16 groups. Example: a /28 would be divided into 16 /32 blocks or a /24 would be divided into 16 /28 blocks

STAPI.ips_neighbors(ipAddress);

Search with DSL

Search for IP addresses. A maximum of 10000 results can be retrieved.

STAPI.ips_dsl((page = 1), (body = {}));

Statistics

Statistics like Reverse DNS pattern identification (RDNS entries are grouped and displayed as x), ports (number of open ports found) or total results are returned

STAPI.ips_statistics((body = {}));

Whois

Fetch current IP information for a single IPv4 address.

STAPI.ips_whois(ipAddress);

Useragents

Fetch user agents seen during the last 30 days for a specific IPv4 address. It shows devices with egressing traffic based on large scale web server logs. The number of results is not limited.

STAPI.ips_useragents(ipAddress, (page = 1));

Feeds

Domains

Fetch zone files including authoritative nameservers with ease. The method returns a .csv.gz file if successful. If ns is true the columns are apex_domain,nameservers (namerservers delimiter: |) and just apex_domain if ns is false.

STAPI.feeds_domains(
  (type = "all"),
  (filter = ""),
  (tld = ""),
  (ns = ""),
  (date = "")
);

DMARC

Download a list of DMARC records. The column is apex_domain.

STAPI.feeds_dmarc((type = "all"), (date = ""));

Subdomains

Download a list of subdomains, with the possibility of filtering by TLD. The response itself is streamed to a file, which means the data is received in chunks. When using filter you must specify the tld parameter and vise versa. The method returns a .csv.gz file if successful. The columns are apex_domain,hostname.

STAPI.feeds_subdomains((type = "all"), (filter = ""), (tld = ""), (date = ""));

Firehose

Certificate Transparency

Stream Certificate Transparency entries

STAPI.firehose_ct((start = ""), (end = ""));

Miscellaneous

Submit Hostnames

Submit discovered hostnames. With the request header 'Content-Encoding: gzip' it is also possible to submit gzip'd data

STAPI.misc_submit(filePath);