news tips

SecurityTrails Blog · Nov 12 · by The SecuriyTrails Team & Arjit Chaudhary

Introducing the SecurityTrails API™ PHP Wrapper

Reading time: 10 minutes

An API can be accessed in different ways, via your browser or your command line, but the easiest way is by using an API wrapper. While API access points may change over time, using an API wrapper will ensure the way you call the API always remains the same in your code.

Today we’re excited to announce the immediate availability of a new SecurityTrails API™ wrapper, and this time it’s written in PHP, one of the most popular programming languages powering a big part of the Internet. This wrapper was written by Arjit Chaudary, one of the new technical writers who has recently joined the SecurityTrails team.

Supported functions

Note: most of these functions require only 1 parameter ($domain). At the time of this writing, this PHP wrapper supports 17 functions; we’ll list the main ones here:

getDomain($domain)

The getDomain API call is used to return current data about the domain queried. For example, the getDomain API call returns how many domains are bound to the same IP address as well.

getSubDomain($domain)

The getSubDomain API call is used to return all subdomains which are found to be associated with a domain.

getDomainWHOIS($domain)

The getDomainWHOIS API call is used to return the domain WHOIS details, such as domain owner, registry date, expiry date, etc.

getAssociatedDomains($domain)

The getAssociatedDomains API call is used to return any associated domains with the domain looked up.

getDNSHistory($domain, $record_type)

The getDNSHistory API call is used to return historical DNS data about a domain being queried.

  1. $domain — The domain you are looking up
  2. $record_type — The record type being looked up; this can be A, AAAA, MX, NS, SOA or TXT
getWHOISHistory($domain)

The getWHOISHistory API call is used to return historical WHOIS information about a domain being queried.

getCompanyDetails($domain)

The getCompanyDetails API call is used to return information about a company via its domain.

Other functions

There are many other functions such as:

- checkPing()
- checkUsage()
- getDomainTags($domain)
- getCompanyAssociatedIPs($domain)
- getIPNeighbors($ip_address)
- getIPWHOIS($ip_address)
- getIPUseragents($ip_address)
- getSSLCertificatesPages($domain, $include_subdomains, $status, $page_number)
- getSSLCertificatesStream($domain, $include_subdomains, $status)
- getFirehoseCertificateTransparency($start_time, $end_time)

Get full insight into all of these extra functions by visiting the official Github docs.

Getting started

Let’s see what the required steps are to get this API wrapper working on your PHP applications.

Generate an API key

To use the PHP API wrapper, you first need a SecurityTrails API™ key. This can be obtained from your SecurityTrails account at https://securitytrails.com/app/account.

Head over to the API Keys option on the left menu:

PHP API wrapper

Once on the API Keys page, you can copy your API key by clicking on the copy button:

API Keys management

Installation

Installing the SecurityTrails API™ PHP Wrapper is super easy; all you need to do is clone the git repository or simply download the file securitytrails.php and include it in your projects to use it right away.

In most use cases, it is recommended to download the API wrapper via Git, as this allows you to easily update the wrapper (when there are any updates to it) by running a simple git pull command.

In our example, we’ll download the API wrapper by using Git.

Run the commands listed in the order below. This will download the SecurityTrails API™ PHP Wrapper into your current folder:

git clone https://github.com/arjitc/SecurityTrails-PHP-Wrapper.git
cd SecurityTrails-PHP-Wrapper

In this folder, you’ll find the API wrapper named securitytrails.php, which can now be included in your existing project.

How can I use it?

Here, we’ll try the getDomain API call which returns current data about the given hostname and more.

Create a file called test.php with the following code:

<?php
     require 'securitytrails.php';
     $securitytrails = new SecurityTrails("YOUR_API_KEY_HERE");
     $output = $securitytrails->getDomain("github.com");
     var_dump($output);
?>

Replace YOUR_API_KEY_HERE with the API key token obtained from your account in the previous step (do not remove the double quotes).

Once that’s done, head over to your website and visit the page test.php which we created above, and you’ll see the following output:

string(3472) "{ "subdomain_count": 19014, "hostname": "github.com", "endpoint": "/v1/domain/github.com", "current_dns": { "txt": { "values": [ { "value": "v=spf1 ip4:192.30.252.0/22 ip4:208.74.204.0/22 ip4:46.19.168.0/23 include:_spf.google.com include:esp.github.com include:_spf.createsend.com include:servers.mcsv.net ~all" }, { "value": "docusign=087098e3-3d46-47b7-9b4e-8a23028154cd" }, { "value": "MS=ms58704441" }, { "value": "MS=ms44452932" }, { "value": "MS=6BF03E6AF5CB689E315FB6199603BABF2C88D805" } ], "first_seen": "2019-10-25" }, "soa": { "values": [ { "ttl": 43200, "email_count": 3141403, "email": "hostmaster.nsone.net" } ], "first_seen": "2020-10-24" }, "ns": { "values": [ { "nameserver_organization": "Amazon.com, Inc.", "nameserver_count": 5043, "nameserver": "ns-520.awsdns-01.net" }, { "nameserver_organization": null, "nameserver_count": 5117, "nameserver": "ns-421.awsdns-52.com" }, { "nameserver_organization": "Amazon.com, Inc.", "nameserver_count": 5148, "nameserver": "ns-1707.awsdns-21.co.uk" }, { "nameserver_organization": "Amazon.com, Inc.", "nameserver_count": 5065, "nameserver": "ns-1283.awsdns-32.org" }, { "nameserver_organization": "NSONE Inc", "nameserver_count": 262914, "nameserver": "dns4.p08.nsone.net" }, { "nameserver_organization": "NSONE Inc", "nameserver_count": 262643, "nameserver": "dns3.p08.nsone.net" }, { "nameserver_organization": "NSONE Inc", "nameserver_count": 262661, "nameserver": "dns2.p08.nsone.net" }, { "nameserver_organization": "NSONE Inc", "nameserver_count": 262718, "nameserver": "dns1.p08.nsone.net" } ], "first_seen": "2020-07-21" }, "mx": { "values": [ { "priority": 10, "hostname_organization": "Google LLC", "hostname_count": 6806182, "hostname": "alt4.aspmx.l.google.com" }, { "priority": 10, "hostname_organization": "Google LLC", "hostname_count": 6867009, "hostname": "alt3.aspmx.l.google.com" }, { "priority": 5, "hostname_organization": "Google LLC", "hostname_count": 12271684, "hostname": "alt2.aspmx.l.google.com" }, { "priority": 5, "hostname_organization": "Google LLC", "hostname_count": 12353008, "hostname": "alt1.aspmx.l.google.com" }, { "priority": 1, "hostname_organization": "Google LLC", "hostname_count": 12612255, "hostname": "aspmx.l.google.com" } ], "first_seen": "2019-10-25" }, "aaaa": {}, "a": { "values": [ { "ip_organization": "GitHub, Inc.", "ip_count": 30, "ip": "140.82.112.3" } ], "first_seen": "2020-10-25" } }, "apex_domain": "github.com", "alexa_rank": 116 }"

Other usage examples

Finding domain WHOIS information

In our next example, we look at finding the WHOIS information of a domain. WHOIS information include who the domain belongs to, the registration date, the expiry date and more.

Create (or update) the test.php file created earlier with the following contents. You can replace “github.com” with another domain which you wish to find the WHOIS information for:

<?php
     require 'securitytrails.php';
     $securitytrails = new SecurityTrails("YOUR_API_KEY_HERE");
     $output = $securitytrails->getDomainWHOIS("github.com");
     var_dump($output);
?>

Then head over to your website and visit the page test.php which we created above and you’ll see the current domain WHOIS information:

string(1279) "{ "updatedDate": "2020-09-08T02:18:27-0700", "status": "clientUpdateProhibited clientTransferProhibited clientDeleteProhibited", "registrarName": "MarkMonitor, Inc.", "private_registration": false, "nameServers": [ "dns1.p08.nsone.net", "dns3.p08.nsone.net", "dns2.p08.nsone.net", "ns-1707.awsdns-21.co.uk", "ns-520.awsdns-01.net", "ns-1283.awsdns-32.org", "dns4.p08.nsone.net", "ns-421.awsdns-52.com" ], "expiresDate": "2022-10-09T00:00:00-0700", "endpoint": "/v1/domain/github.com/whois", "domain": "github.com", "createdDate": "2007-10-09T11:20:50-0700", "contacts": [ { "type": "technicalContact", "state": "CA", "organization_count": 198, "organization": "GitHub, Inc.", "countryCode": "US", "country": "UNITED STATES" }, { "type": "administrativeContact", "state": "CA", "organization_count": 198, "organization": "GitHub, Inc.", "countryCode": "US", "country": "UNITED STATES" }, { "type": "registrant", "state": "CA", "organization_count": 198, "organization": "GitHub, Inc.", "countryCode": "US", "country": "UNITED STATES" } ], "contactEmail": "abusecomplaints@markmonitor.com" }"

Looking up DNS history via the API wrapper

Now let’s look at finding the domain’s DNS history. DNS history can be found for A, AAAA, MX, NS, SOA or TXT records which are set on a domain.

Update the test.php file created earlier, change only the $output line as shown below. You can replace “github.com” with another domain which you wish to find the DNS history information for.

In the example below, we look up the DNS history for “github.com” for the “A” record,

$output = $securitytrails->getDNSHistory("github.com", "a");

which then gives you the following output:

string(26001) "{ "type": "a/ipv4", "records": [ { "values": [ { "ip_count": 37, "ip": "140.82.113.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-28", "first_seen": "2020-10-27" }, { "values": [ { "ip_count": 20, "ip": "140.82.112.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-27", "first_seen": "2020-10-25" }, { "values": [ { "ip_count": 22, "ip": "140.82.114.4" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-25", "first_seen": "2020-10-24" }, { "values": [ { "ip_count": 24, "ip": "140.82.113.4" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-24", "first_seen": "2020-10-22" }, { "values": [ { "ip_count": 37, "ip": "140.82.113.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-22", "first_seen": "2020-10-20" }, { "values": [ { "ip_count": 22, "ip": "140.82.114.4" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-20", "first_seen": "2020-10-18" }, { "values": [ { "ip_count": 37, "ip": "140.82.113.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-18", "first_seen": "2020-10-17" }, { "values": [ { "ip_count": 20, "ip": "140.82.112.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-17", "first_seen": "2020-10-16" }, { "values": [ { "ip_count": 37, "ip": "140.82.113.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-16", "first_seen": "2020-10-15" }, { "values": [ { "ip_count": 20, "ip": "140.82.112.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-15", "first_seen": "2020-10-14" }, { "values": [ { "ip_count": 22, "ip": "140.82.114.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-14", "first_seen": "2020-10-12" }, { "values": [ { "ip_count": 33, "ip": "140.82.112.4" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-12", "first_seen": "2020-10-11" }, { "values": [ { "ip_count": 22, "ip": "140.82.114.3" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-11", "first_seen": "2020-10-09" }, { "values": [ { "ip_count": 22, "ip": "140.82.114.4" } ], "type": "a", "organizations": [ "GitHub, Inc." ], "last_seen": "2020-10-09", "first_seen": "2020-10-06" }, { "values": [ { "ip_count": 20, "ip": "140.82.112.3" } ], ……..., "pages": 7, "endpoint": "/v1/history/github.com/dns/a" }"

Looking up domain tags

In our next example, we look at the getDomainTags function which allows us to find any related tags to a domain.

Update the test.php file created earlier, change only the $output line as shown below. You can replace “github.com” with another domain which you wish to find the domain tags for,

$output = $securitytrails->getDomainTags("github.com");

Visit test.php and you’ll find the following output:

string(60) "{ "tags": [], "endpoint": "/v1/domain/github.com/tags" }"

Finding all the subdomains of a domain

In our next example, we look at the getSubDomain function which allows us to find any subdomains of a domain.

Update the test.php file created earlier, changing only the $output line as shown below. You can replace “github.com” with another domain which you wish to find the subdomains for:

$output = $securitytrails->getSubDomain("github.com");

Visit test.php and you’ll find the following output:

string(32970) "{ "subdomains": [ "gist", "desktop", "help", "raw", "twitter", "pages", "harvesthq", "fortawesome", "blog", "taitems", "petewarden", "kolber", "guides", "octoverse", "octodex", "api", "assets-cdn", "documentcloud", "status", "es5", "git-lfs", "proloser", "rrthomas", "enterprise", "codeload", "cli", "evanw", "necolas", "hoyois", "support", "archiveprogram", "rogerdudler", "cloud", "visionmedia", "cqrsjourney", "mazko", "training", "toblerity", "benvie", "taglib", "oampo", "gattis", "sevntu-checkstyle", "vmml", "octicons", "xaviershay", "shop", "styleguide", "securitylab", "angular-ui", "visualstudio", "eightmedia", "keplerproject", "flusspferd", "paularmstrong", "addyosmani", "wise9", "vicchi", "osxfuse", "devtellect", "drslump", "lax", "banditmedia", "enricob", "fyaconiello", "ivaynberg", "wagerfield", "tsvensen", "soulwire", "jherrm", ……...], "meta": { "limit_reached": true }, "endpoint": "/v1/domain/github.com/subdomains" }"

How can I update this PHP Wrapper?

The SecurityTrails API™ gets new features added frequently. These newer features are added to the API wrapper as well, and in order to access these new features we need to update the API wrapper.

To update your PHP-based API wrapper, simply switch to the folder where you initially downloaded the API wrapper, and run the command git pull as shown here:

cd /path/to/the/SecurityTrails-PHP-Wrapper
git pull

This will sync any updates made to the API wrapper to your local folder.

Summary

While PHP is no longer the king of the web, as it had been during the previous decade, it’s still ranked as one of the most popular programming languages around. That’s why having a PHP wrapper is useful for many users.

If you have any difficulty setting up this new wrapper, head over to our support team, or report the bug to the developer at the original Github repository at https://github.com/arjitc/SecurityTrails-PHP-Wrapper/issues. Be sure to include as much information as possible to help debug the issue quickly and efficiently.

If PHP isn’t your preffered programming language, remember we have other wrappers for Python, NodeJS, Ruby, R, and more! Check our Integrations page today.