Determining whether or not a server’s IP address is blacklisted is a crucial step in securing your web app. Blacklist checks are important for protecting your front end web forms from spam and bad actors who might try to use techniques like SQL injection, cross-site scripting (XSS), formjacking, and phishing to steal sensitive data, gain access to systems, inject malicious content, or launch further attacks.
In this article, we’ll use the IPstack IP geolocation API with fraud detection to integrate a simple IP blacklist check into your front end.
Table of Contents
You Will Learn:
- How IP-based fraud detection works using geolocation
- How to implement IPstack’s fraud security module
- How to use that module to blacklist an IP address
How Does an IP Blacklist API Work?
A blacklist API allows you to do IP-based fraud detection by analyzing the IP address of an incoming network request and looking for factors associated with that IP address that could indicate fraud.
Most APIs that do IP geolocation lookup will provide geographic information about an IP address, such as the city, state, country and even latitude and longitude coordinates. A geo API with fraud detection goes one step further, proving security information about the IP address – such as whether the device in question is using a VPN or Tor network, and even assigning a threat score to let you know how risky the IP address is.
Once you’ve received your response from the API, you can reject the incoming request and blacklist the IP address to prevent the bad actor behind it from attempting to access your system again.
Build a Real-Time IP Blacklist Check with IPstack
Prerequisites
This IP blacklisting tutorial assumes knowledge of React and experience making API requests. We’ll use IPstack’s Security Module to analyze incoming IP addresses, and Node.js with Express to handle backend requests.
Step One: Enable IPstack’s IP Security Module
IPstack is a geolocation API providing accurate and reliable geolocation data for any IP address, in JSON format, via secure HTTPS. In addition to geolocation data, the API also provides optional security data, which you can use to screen potentially risky IP addresses.
Sign Up for a Plan
IPstack offers a free tier that allows up to 100 requests per month. To access advanced security features and detect suspicious IP addresses, however, you need a Professional Plus Plan. Sign up for an IPstack account to get your API key.
Once you sign up, head to your IPstack dashboard to retrieve your API key. From there, check out the documentation to enable the Security Module by appending &security=1 to your requests.
Send a Test API Request
To access the security module, append &security=1 to your request URL. The API will send back an additional field on the response object containing the security data. Look for the “Run API Request” button in the “Enable Security Module” section of the documentation to test the request:
This sends an example request to the API to check a known IP address used by the Tor system, and appending your access key and the security parameter query string. The output loads into a new browser tab. Scroll to the bottom of the results to see the security data:
Don’t forget: Advanced IP risk detection is only available on IPstack’s Professional Plus plan.Upgrade here for full access.
Step Two: How to Score and Flag Suspicious IPs
You can use the threat_level, threat_types, is_proxy and is_tor fields from this object to determine whether or not this IP address poses a risk and should be blacklisted.
Write an Algorithm
Let’s write a simple algorithm that checks those fields and returns true or false depending on their values:
export const shouldBlacklistIP = (IPstackResponseObject) => {
const securityModule = IPstackResponseObject.security || {};
if (Object.keys(securityModule).length === 0) {
return false;
}
const {is_proxy, is_tor, threat_level, threat_types} = securityModule;
const riskyThreatTypes = ["tor", "spam", "attack", "phishing", "malware"];
if (is_proxy || is_tor) {
return true;
}
if (threat_level && threat_level === "high") {
return true;
}
if (Array.isArray(threat_types) && riskyThreatTypes.some(threat_types)) {
return true;
}
return false;
}
Next, we’ll use this algorithm on our back end to check the risk posed by each incoming request.
Step Three: Real-Time IP Blacklist Detection in Node
Let’s walk through a basic implementation of this in Node.js.
Get Started with Express
If you’re unfamiliar with Node or Express, check out the documentation here. First let’s set up our project structure and install express.
$ mkdir ip-blacklist-app
$ cd ip-blacklist-app && mkdir server
$ cd server && npm init
$ npm install -s express
$ touch index.js
Open the project in your code editor and navigate to the index.js file. Add the following code:
const express = require('express')
const app = express()
const port = 3000
app.get('/api/ip-blacklist-check', (req, res) => {
res.send('Hello World!')
})
app.listen(port, () => {
console.log(`Example app listening on port ${port}`)
})
This imports the Express dependency, uses Express to create the server (called app), assigns it to a port, and establishes an endpoint called api/blacklist-check.
Test the endpoint by starting up the server in your terminal:
$ node index.js
Navigate to localhost:3000/api/ip-blacklist-check in your browser. You should see the following:
Next, we need to secure our API access key in a Dotenv file so the backend can use it to send requests to the API, but the key doesn’t get accidentally committed to an online repository.
Create a Dotenv File
Run the following in your root directory:
$ npm install -s dotenv
$ cd server && touch .env
This adds the Dotenv dependency and creates the file. In the file, add your access key and API URL:
API_ACCESS_KEY="your access key"
API_URL="https://api.ipstack.com"
In index.js, initialize Dotenv at the top of the file, and you’ll be able to grab the key and URL from process.env:
require('dotenv').config()
const BASE_URL = process.env.API_URL;
const ACCESS_KEY = process.env.API_ACCESS_KEY;
Finally, create a .gitignore file in the root of your project, and add .env. This tells git to ignore the file during a commit, so that file will never be pushed to an online repository. If you deploy the app through a platform like AWS, Digital Ocean, Github pages, or Heroku, you can manually add these secret values through the provided interface.
Step Four: Simulate Real IPs in Dev with Nginx Proxy
Grab the incoming IP address from the request object that Express provides:
app.get('/api/fraud-score', (req, res) => {
const ip = req.ip;
console.log(ip);
// send the IP to IPstack
// analyze the response and assign a fraud score
res.send('Your fraud score is: __')
})
You’ll notice that when you test via your browser in development, the IP address will be ::1, the IPv6 address for the localhost. We can’t send this to the IPstack API to check if it should be blacklisted because it isn’t a public IP address. To simulate a production environment so you can get a public-facing IP address while testing, set up a reverse proxy with Nginx.
Install Nginx
Run the following command in your terminal to install Nginx using Homebrew:
$ brew install nginx
Configure Nginx
Open the default config file (on Mac this is /opt/homebrew/etc/nginx/nginx.conf) in your code editor, and add the following configuration:
http {
# ... other configs ...
server {
listen 8080;
location / {
proxy_pass http://localhost:3000;
# simulate client IP
proxy_set_header X-Forwarded-For 103.3.61.114;
# required by express if trust proxy is on
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
}
This spins up a proxy server that listens on port 8080 and forwards the request to the Express server on port 3000. It attaches a “real” simulated client IP to the request, which we can then send to IPstack. For testing, use the IP address IPstack uses in their security documentation, which is the Tor system IP.
Start Nginx
$ brew services start nginx
Tell Express to Trust the Proxy
In your index.js file, add the following line to tell Express to trust the incoming proxied request from Nginx:
app.set('trust proxy', true)
Instead of visiting the app at localhost:3000/api/ip-blacklist-check in your browser, visit localhost:8080/api/ip-blacklist-check. You’ll see the Tor IP address logged to the terminal. You should still see “Hello World!” in the browser.
Step Five: Send the IP Address to IPstack
To get the security information about this IP address from IPstack, we’ll construct a URL from our dotenv values, and append the IP and the &security=1 flag:
app.get('/api/ip-blacklist-check', async (req, res) => {
const ip = req.ip;
const response = await fetch(BASE_URL + `/${ip}?access_key=${ACCESS_KEY}&security=1`);
const json = await response.json();
console.log(json);
res.send('Hello World!')
})
Take a look at your terminal to view the data returned by the IPstack fraud prevention API:
The next step is to check the IP address using our algorithm, and decide whether we want to trust the IP address or not.
Step Six: Check and Respond to Risky IP
Make sure you’re in the server directory of your app, and then, in your terminal, run the following command to create a service file:
$ touch blacklist-check.js
Inside this file, paste the shouldBlacklistIP function we created earlier. Import this function into index.js and pass it the security object we received from the API:
const { shouldBlacklistIP } = require('./blacklist-check);
...
app.get('/api/ip-blacklist-check', async (req, res) => {
const ip = req.ip;
const response = await fetch(BASE_URL + `/${ip}?access_key=${ACCESS_KEY}&security=1`);
const json = await response.json();
const shouldBlacklist = shouldBlacklistIP(json);
res.send({blacklistIP: shouldBlacklist})
})
Now, when you visit localhost:8080/api/ip-blacklist-check in your browser, you should see the following:
From here, it’s up to the client to block the device associated with that IP address from making any further progress through the page (i.e. prevent a web form from being submitted, etc.) On the back end, our next step would be to store this IP address in a database to begin to maintain a list of blacklisted IP addresses so we can manage our own IP check in the future.
Next Steps
You can now use this backend to check incoming requests from any front end you build. Check out the How to Build a Secure User Registration System with Mailboxlayer Email Validation tutorial, and hook up that front end to this server as a trial.
Complete Code
Here’s the full IP security module implementation.
index.js
require('dotenv').config()
const BASE_URL = process.env.API_URL;
const ACCESS_KEY = process.env.API_ACCESS_KEY;
const express = require('express');
const { shouldBlacklistIP } = require('./blacklist-check');
const app = express()
app.set('trust proxy', true)
const port = 3000
app.get('/api/ip-blacklist-check', async (req, res) => {
const ip = req.ip;
const response = await fetch(BASE_URL + `/${ip}?access_key=${ACCESS_KEY}&security=1`);
const json = await response.json();
const shouldBlacklist = shouldBlacklistIP(json);
res.send({blacklistIP: shouldBlacklist})
})
app.listen(port, () => {
console.log(`Example app listening on port ${port}`)
})
blacklist-check.js
export const shouldBlacklistIP = (IPstackResponseObject) => {
const securityModule = IPstackResponseObject.security || {};
if (Object.keys(securityModule).length === 0) {
return false;
}
const {is_proxy, is_tor, threat_level, threat_types} = securityModule;
const riskyThreatTypes = ["tor", "spam", "attack", "phishing", "malware"];
if (is_proxy || is_tor) {
return true;
}
if (threat_level && threat_level === "high") {
return true;
}
if (Array.isArray(threat_types) && riskyThreatTypes.some(threat_types)) {
return true;
}
return false;
}
.env
API_ACCESS_KEY="your access key"
API_URL="https://api.ipstack.com"
/opt/homebrew/etc/nginx/nginx.conf (for development only)
#user nobody;
worker_processes 1;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
server {
listen 8080;
location / {
proxy_pass http://localhost:3000;
# simulate client IP
proxy_set_header X-Forwarded-For 103.3.61.114;
# required by express if trust proxy is on
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
include servers/*;
}
IPstack: A Secure Network IP Check API
IPstack is an IP reputation API for developers seeking a simple, lightweight solution to their security needs. This tutorial covered the basics of getting started with IPstack for fraud prevention, but there are many more use cases for this powerful API. Check out our IP-Based Fraud Detection tutorial for an in-depth look at another way to use this module.
FAQs
What is an IP Blacklist Check API, and how does it work?
An IP blacklist check API is a fraud-prevention API that provides developers with security information about a given IP address. This information can then be used to determine the threat level posed by the system at that IP address, and block or blacklist the IP address to prevent future attacks.
How can developers use the IPstack API for IP blacklist checks?
IPstack provides an optional security module as part of their geolocation API response. When querying the API for information about an IP address, simply append &security=1 to the request URL to receive this additional object. You can then use the fields provided (is_tor, is_proxy, threat_level, threat_types, etc.) to determine if the IP address poses a threat to your system.
What are the benefits of integrating an IP reputation API into my application?
Using an IP-based threat-detection API like IPstack to validate the safety of incoming requests is a critical first step in securing front end components of your application like web forms, payment systems, and email signup pages.
Can an IP blacklist check API also provide geolocation or fraud detection features?
Yes, if the API has access to that information. IPstack has geographical information and additional fraud detection features beyond IP blacklisting to help you secure your application. By combining the data from a geo API with fraud detection data, you can not only secure your system from bad actors in countries with known high cybersecurity risk, but also do things like geofencing, targeted advertising, and localized mailing list sends.
