Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Introduction to the Sqreen API

 

Welcome to the Sqreen API

The Sqreen API allows you to tap into our extensive knowledge base to discover security risks hiding in your own data. Find out whether that email address is from an anonymizing service, or that IP address is a Tor exit point. You can even find out if the address has been implicated in a past security attack.

For example, you might want to know whether ChunkLover53@aol.com represents a risk, and should be barred from signing up for your service. You can query the Sqreen API to discover that this user has a high risk score.

{
  "email": "ChunkyLover53@aol.com",
  "risk_score": 80,
  "is_known_attacker": true,
  "high_risk_security_events_count": 3,
  "security_events_count": 15,
  "is_disposable": false,
  "is_email_malformed": false,
  "is_email_harmful": false
}

Getting started

Sound interesting? Getting started requires a few more steps.

Do I need an account?

Yes. To use the APIs, you'll need to create account with Sqreen and register a new app. Don't worry if you don't have a web app running somewhere that you want to monitor, you can get started quickly with the API by selecting the "Developer Sandbox" app type. The Developer Sandbox lets you get started building with the Sqreen API without committing to install the Sqreen Agent into a production web app. The Developer Sandbox is completely free, and although rate-limited, can be used for standalone access to the API for as long as you want.

I am already a Sqreen customer

If you already have a Sqreen account, you can either create a new Developer Sandbox app to get started playing with the Sqreen API, or you can use the API key we have generated for any apps you already have registered. Click on the API tab for any existing apps to reveal the API key.

State of the API & our Roadmap

At the moment, the Screen API comprises two endpoints—one for learning more about email addresses, and one for learning more about IP addresses, both detailed below.

In the future, however, we have planned more ways for your app to integrate into the Sqreen service. We would love to hear your feedback on the API, and the future: Drop us a line and tell us what you think.

General observations on the structure of the API

All API endpoints are served over HTTP, and require encryption with SSL.

All API endpoints return JSON objects (although we'd certainly consider support other formats).

API Keys

Ready to get started learning about the Sqreen API? You can read the documentation without an account, but playing with the APIs requires an API key.

Sign up for a developer account and get your free API key.

Authentication

 

All Sqreen API endpoints require authentication with a Sqreen API key. You can find instructions above for getting your key.

Once you have an account, you can retrieve your API key from the API tab in your account dashboard. You'll want to copy it so you can paste it into the interactive documentation below.

To authenticate API calls in your own code, add a header to your HTTP request called X-API-Key whose value is your is API key. For example, if your API key is TODO_API_KEY_HERE, you would add the following header to your request:

X-API-Key: TODO_API_KEY_HERE

With curl, this would look like:

curl https://api.sqreen.io/v1/ips/8.8.8.8 -H "X-API-Key: TODO_API_KEY_HERE"

Attempts to call the Sqreen API without a valid API key specified in this way will be denied with a 401 error.

Swagger

 

All Sqreen API endpoints have Swagger definitions available. Swagger—now called OpenAPI—is a structured way to describe API endpoints readable by computers and developers alike. It's pretty nifty.

/emails

Uncover security risks hiding in email addresses

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.sqreen.io/v1/emails/email
curl --request GET \
  --url https://api.sqreen.io/v1/emails/ChunkyLover53%40aol.com
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.sqreen.io/v1/emails/ChunkyLover53%40aol.com' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.sqreen.io/v1/emails/ChunkyLover53%40aol.com")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.sqreen.io/v1/emails/ChunkyLover53%40aol.com");

xhr.send(data);
import requests

url = "https://api.sqreen.io/v1/emails/ChunkyLover53%40aol.com"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "email": "ChunkyLover53@aol.com",
  "risk_score": 0,
  "is_known_attacker": false,
  "high_risk_security_events_count": 0,
  "security_events_count": 0,
  "is_disposable": false,
  "is_email_malformed": false,
  "is_email_harmful": false
}

Path Params

email
string
required

The email address to research

 

Use this endpoint to uncover more information about an email address. Sqreen has an extensive database of known attackers, as well as analysis on an email address's origins. Discover whether this email address is from an anonymizing service, or was used in an attack, and use this data to make policy decisions based on how risky we assess the email address to be.

Response

Field
Type
Description

email

string

The email address queried.

risk_score

number

The assessed risk that this email address is being used by a malevolent actor.
Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.

is_email_harmful

boolean

Does the email address itself pose a direct security risk? E.g., does the email address contain embedded JavaScript?

is_known_attacker

boolean

Was this email address used as part of a security attack?

high_risk_security_events_count

number

The number of high-risk security events (e.g. SQL injection attacks) involving this email address.

security_events_count

number

The number of all security events (both high-risk and low-risk) involving this email address.

is_disposable

boolean

Does this email's domain belong to a known vendor of disposable, temporary, or anonymized email addresses?

is_email_malformed

boolean

Is the email malformed according to RFC 5322?

/ips

Uncover security risks hidden in IP addresses

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.sqreen.io/v1/ips/ip
curl --request GET \
  --url https://api.sqreen.io/v1/ips/8.8.8.8
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.sqreen.io/v1/ips/8.8.8.8' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.sqreen.io/v1/ips/8.8.8.8")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.sqreen.io/v1/ips/8.8.8.8");

xhr.send(data);
import requests

url = "https://api.sqreen.io/v1/ips/8.8.8.8"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ip": "8.8.8.8",
  "ip_version": 4,
  "risk_score": 5,
  "is_known_attacker": false,
  "security_events_count": 0,
  "high_risk_security_events_count": 0,
  "ip_geo": {
    "latitude": 37.38600158691406,
    "city": "Mountain View",
    "longitude": -122.08380126953125,
    "country_code": "USA"
  },
  "is_datacenter": true,
  "is_vpn": false,
  "is_proxy": false,
  "is_private": false,
  "is_tor": false
}
{
  "code": 400,
  "details": "Invalid IP",
  "errno": 400,
  "error": "Invalid request",
  "info": "",
  "message": "Validation error occured while trying to parse an ip"
}

Path Params

ip
string
required

The IP address to research

 

Use this endpoint to uncover more information about an IP address. Sqreen has an extensive database of known attackers, as well as analysis on who or what an IP address belongs to. Discover whether this IP address is a Tor exit point or was used in an attack, and use this data to make policy decisions based on how risky we assess the IP address to be.

Response

Field
Type
Description

ip

string

The IP address queried.

ip_version

number

The version of the IP address queried. Either 4 or 6.

risk_score

number

The assessed risk that this IP address is being used by a malevolent actor.
Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.

is_known_attacker

boolean

Was this IP address used as part of a security attack?

high_risk_security_events_count

number

The number of high-risk security events (e.g. SQL injection attacks) originating from this IP address.

security_events_count

number

The number of all security events (both high-risk and low-risk) originating from this IP address.

ip_geo

object

The geographical location associated with this IP address.

ip_geo.latitude

number

The latititude of the location.

ip_geo.longitude

number

The longitude of the location.

ip_geo.country_code

string

The ISO ALPHA-3 Code for the country that this location exists within.

is_datacenter

boolean

Does this IP address belong to a known datacenter, such as AWS or Google Cloud?

is_vpn

boolean

Does this IP address belong to a known VPN?

is_proxy

boolean

Does this IP address belong to a known proxy server?

is_tor

boolean

Is this IP address a known Tor exit point?

Integrations with Third-Party Tools

 

Here you can find a list of contributed integrations of the Sqreen API with other services that you can use in your own apps.

Devise

Devise is a popular authentication library for Rails. Now you can use the Sqreen API to screen out risky signups to your Rails app. devise_sqreener passes to you metadata from the Sqreen API about email and IP addresses, and allows you to configure rules around that metadata to reject signups based on their risk to your app's security.

And you…?

Built something cool with the Sqreen API you'd like to share with the world? We'd love to help! Drop us a line, and we'll include your project right here.