1. Overview
  2. Getting started
  3. Using the Threat Intelligence API Platform

Using the Threat Intelligence API Platform

SSHwatch Threat Intelligence API Documentation

This technical documentation provides developers with detailed information about the SSHwatch Threat Intelligence API endpoints, request/response formats, error handling, and implementation guidelines.

API Overview

The SSHwatch Threat Intelligence API provides programmatic access to our SSH threat intelligence database. The API consists of two primary endpoints:

  1. IP Threat Rating Lookup API - Query detailed threat information for a specific IP address
  2. IP Threat Feed API - Retrieve a complete list of malicious IPs for bulk implementation

Authentication

Currently, the API does not require authentication. However, rate limiting is enforced to prevent abuse.

Rate Limits

To ensure service availability, the following rate limits apply:

Endpoint Rate Limit
/ip/{ip_address} 60 requests per minute
/feed 10 requests per minute

When a rate limit is exceeded, the API will return a 429 Too Many Requests status code.

Base URL

All API requests should be made to:

https://api.sshwatch.com/

IP Threat Rating Lookup API

Endpoint

GET /ip/{ip_address}

Parameters

Parameter Type Description
ip_address string The IP address to query (IPv4 format)

Response

The response is in JSON format with the following structure:

{
  "status": "success",
  "found": true,

  "data": {
    "ip_address": "192.0.2.1",
    "avg_score": 87.5,
    "submission_count": 42,
    "last_updated": "2025-03-15 14:30:45"
  }
}

Response Fields

Field Type Description
status string Request status: "success" or "error"
found boolean Whether the IP was found in the database
data object Contains threat details if found
data.ip_address string The queried IP address
data.avg_score float Threat score (0-100, where higher indicates more malicious behavior)
data.submission_count integer Number of times this IP was reported by users
data.last_updated string ISO 8601 timestamp of the last update

If the IP is not found in the database, the response will be:

{
  "status": "success",
  "found": false,
  "message": "IP not found in threat database"
}

Error Responses

Status Code Description Response Body
400 Invalid IP address {"status": "error", "message": "Invalid IP address format"}
429 Rate limit exceeded {"status": "error", "message": "Rate limit exceeded. Please try again later."}
500 Server error {"status": "error", "message": "Database error: {error details}"}

Example

Request:

curl https://api.sshwatch.com/ip/192.0.2.1

Response:

{
  "status": "success",
  "found": true,
  "data": {
    "ip_address": "192.0.2.1",
    "avg_score": 87.5,
    "submission_count": 42,
    "last_updated": "2025-03-15 14:30:45"
  }
}

IP Threat Feed API

Endpoint

GET /feed

Response

The response is a plaintext list of IP addresses with comment headers. Each IP is on a new line.

# SSHwatch.com Threat IP Feed
# This list contains known malicious IP addresses detected by SSHwatch
# Last Updated: 2025-03-18 14:30:45
# For more information visit: https://sshwatch.com
#
192.0.2.1
198.51.100.2
203.0.113.3
...

Response Format Details

  • Content-Type: text/plain
  • IPs are sorted by threat score in descending order (highest threat first)
  • Comment lines begin with # for compatibility with firewall implementations
  • No trailing newline at the end of the file

Error Responses

Status Code Description Response Body
429 Rate limit exceeded Error: Rate limit exceeded. Please try again later.
500 Server error Error: Database error: {error details}

Example

Request:

curl https://api.sshwatch.com/feed

Response:

# SSHwatch.com Threat IP Feed
# This list contains known malicious IP addresses detected by SSHwatch
# Last Updated: 2025-03-18 14:30:45
# For more information visit: https://sshwatch.com
#
192.0.2.1
198.51.100.2
203.0.113.3
...

Implementation Guidelines

Integrating with Firewalls

The IP Threat Feed API is designed to be compatible with most firewall systems. Here are implementation examples for common firewall platforms:

iptables (Linux)

#!/bin/bash
# Download the threat feed
curl -s https://api.sshwatch.com/feed > /tmp/sshwatch_threat_ips.txt

# Clear existing SSHwatch rule chain if it exists
iptables -D INPUT -j SSHWATCH_BLOCK 2>/dev/null
iptables -F SSHWATCH_BLOCK 2>/dev/null
iptables -X SSHWATCH_BLOCK 2>/dev/null

# Create a new chain
iptables -N SSHWATCH_BLOCK

# Add each IP to the block list (skip comment lines)
grep -v "^#" /tmp/sshwatch_threat_ips.txt | while read ip; do
    iptables -A SSHWATCH_BLOCK -s $ip -j DROP
done

# Add the chain to the INPUT rules
iptables -A INPUT -j SSHWATCH_BLOCK

# Clean up
rm /tmp/sshwatch_threat_ips.txt

pfSense

  1. Navigate to Firewall > Aliases
  2. Create a new alias named "SSHwatch_Threat_IPs"
  3. Set Type to "URL Table (IPs)"
  4. Enter https://api.sshwatch.com/feed as the URL
  5. Set Update Frequency to your preferred value (e.g., 1 day)
  6. Create a firewall rule using this alias to block traffic

Using the IP Lookup API

Python Example

import requests
import json

def check_ip_threat(ip_address):
    url = f"https://api.sshwatch.com/ip/{ip_address}"
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        
        data = response.json()
        
        if data['status'] == 'success' and data['found']:
            threat_data = data['data']
            print(f"IP: {threat_data['ip_address']}")
            print(f"Threat Score: {threat_data['avg_score']}")
            print(f"Submissions: {threat_data['submission_count']}")
            print(f"Last Updated: {threat_data['last_updated']}")
            
            # Return True if threat score is above threshold
            return threat_data['avg_score'] > 50
        else:
            print(f"IP {ip_address} not found in threat database")
            return False
            
    except requests.exceptions.RequestException as e:
        print(f"Error checking threat: {e}")
        return False

# Example usage
is_threat = check_ip_threat("192.0.2.1")
if is_threat:
    print("This IP is potentially malicious!")
else:
    print("This IP appears to be safe.")

PHP Example

<?php

function checkIpThreat($ipAddress) {
    $url = "https://api.sshwatch.com/ip/" . $ipAddress;
    
    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($curl);
    
    if ($response === false) {
        $error = curl_error($curl);
        curl_close($curl);
        error_log("Error checking threat: " . $error);
        return false;
    }
    
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode !== 200) {
        error_log("API returned non-200 status code: " . $httpCode);
        return false;
    }
    
    $data = json_decode($response, true);
    
    if ($data['status'] === 'success' && $data['found'] === true) {
        $threatData = $data['data'];
        
        // Log threat information
        error_log("IP: " . $threatData['ip_address'] . 
                 ", Threat Score: " . $threatData['avg_score'] . 
                 ", Submissions: " . $threatData['submission_count']);
        
        // Consider IPs with score > 70 as high threats
        return $threatData['avg_score'] > 70;
    }
    
    return false;
}

// Example usage
$ipToCheck = "192.0.2.1";
if (checkIpThreat($ipToCheck)) {
    echo "High threat detected! Blocking access.\n";
    // Implement your blocking logic here
} else {
    echo "IP appears to be safe or has a low threat score.\n";
}
?>

Best Practices

  1. Caching: To minimize API requests, consider caching responses:

    • IP Lookup API responses can be cached for 1-4 hours
    • Threat Feed can be refreshed once or twice daily

  2. Error Handling: Implement proper error handling to manage API unavailability:

    • For IP Lookup API, default to allowing traffic if the API is unavailable
    • For Threat Feed, keep the last successful download as a fallback

  3. Rate Limiting: Implement client-side rate limiting to avoid hitting API limits:

    • For high-volume environments, consider a staggered approach to IP checks
    • For feed integration, schedule updates during off-peak hours

  4. Threat Score Interpretation:

    • 0-30: Low threat
    • 31-70: Medium threat
    • 71-100: High threat

Data Retention

The threat feed is automatically maintained with the following retention policy:

  • IPs are removed from the database after 30 days of inactivity
  • Historical data is not available through the API
  • The feed reflects the current threat landscape

Legal and Usage Restrictions

The SSHwatch Threat Intelligence API data may be used only for legitimate security purposes. Redistribution or commercial reselling of the API data is prohibited without explicit written permission from SSHwatch.

Was this article helpful?
© 2025 Beelytics Documentation