AbuseIPDB Integration Guide

Overview

The AbuseIPDB integration allows your NINA workflows to connect with AbuseIPDB's threat intelligence database for comprehensive IP reputation analysis and abuse reporting. This integration enables you to check IP addresses against known malicious activity, report abusive IPs, analyze CIDR blocks, retrieve blacklists, and manage abuse reports directly from your workflows.

Status

The integration currently supports comprehensive threat intelligence operations:

• IP Reputation Checking: Verify IP addresses against the AbuseIPDB database with configurable time ranges
• Abuse Reporting: Report malicious IP addresses with detailed categorization and comments
• CIDR Block Analysis: Check entire network subnets for abuse reports
• Blacklist Retrieval: Access the most reported IP addresses with confidence filtering
• Detailed Reports: Get paginated detailed reports for specific IP addresses (OPEN BETA)
• Report Management: Clear/delete reports for specific IP addresses from your account

Some advanced features include:

• Verbose IP Information: Retrieve country, usage type, ISP, and domain information
• Flexible Time Ranges: Configure report age from 1 to 365 days
• Confidence Thresholds: Filter results by confidence percentage (25-100%)
• Geographic Filtering: Include or exclude specific countries in blacklist queries
• Categorized Reporting: Report abuse using 23 predefined categories
• Pagination Support: Handle large result sets with page-based navigation

Credential Configuration

Before using the AbuseIPDB integration in your workflows, you need to configure credentials for authentication. The integration uses API key authentication with the AbuseIPDB API.

Authentication Method

The AbuseIPDB integration uses API key authentication:

Field	Description	Example
API Key	Your AbuseIPDB API key	a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Base URL	AbuseIPDB API base URL	https://api.abuseipdb.com/api/v2

How to obtain your API Key:

1. Visit AbuseIPDB and create an account
2. Navigate to your account settings or API section
3. Generate a new API key or retrieve your existing key
4. Copy the API key for use in your credential configuration
5. Verify the API key has the necessary permissions for your intended operations

Important Notes:

• API keys have different permission levels (read-only, reporting, etc.)
• Some operations require specific API key permissions
• Monitor your API usage to avoid rate limits
• Keep your API key secure and rotate it regularly

Creating an AbuseIPDB Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "AbuseIPDB Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "AbuseIPDB"
   • API Key: Paste your AbuseIPDB API key
   • Base URL: Enter the API base URL (default: https://api.abuseipdb.com/api/v2)

4. Click Test Connection to verify credentials

5. Click Save to store the credential

Supported Resources and Operations

The AbuseIPDB integration supports the following resource and operations:

IP Address

Operation	Description
Check IP	Check an IP address against the AbuseIPDB database
Report IP	Report an abusive IP address to AbuseIPDB
Check CIDR Block	Check a network subnet (CIDR block) for abuse reports
Get Blacklist	Get the most reported IP addresses from AbuseIPDB
Get Reports	Get detailed reports for a specific IP address with pagination (OPEN BETA)
Clear Reports	Delete reports for a specific IP address from your account

Parameter Merging

The AbuseIPDB integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the AbuseIPDB Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When an AbuseIPDB Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the AbuseIPDB operation

Examples

Checking IP Reputation

Below is an example of checking an IP address against the AbuseIPDB database:

Node Configuration:

{
  "resource": "ip",
  "operation": "check",
  "parameters": {
    "ipAddress": "192.168.1.100",
    "maxAgeInDays": 30,
    "verbose": true
  }
}

This will check the IP address 192.168.1.100 for abuse reports within the last 30 days, including detailed information about country, ISP, and domain.

Reporting Abusive IP

Example of reporting an abusive IP address:

Node Configuration:

{
  "resource": "ip",
  "operation": "report",
  "parameters": {
    "ip": "198.51.100.42",
    "categories": "14,15,18",
    "comment": "Observed multiple port scan attempts from this IP targeting SSH and HTTP services",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

This will report the IP address 198.51.100.42 for port scanning (14), hacking (15), and brute-force attacks (18) with a detailed comment.

Checking CIDR Block

Example of checking a network subnet for abuse reports:

Node Configuration:

{
  "resource": "ip",
  "operation": "checkBlock",
  "parameters": {
    "network": "192.168.1.0/24",
    "maxAgeInDays": 7
  }
}

This will check the entire 192.168.1.0/24 subnet for abuse reports within the last 7 days.

Getting Blacklist

Example of retrieving the most reported IP addresses:

Node Configuration:

{
  "resource": "ip",
  "operation": "blacklist",
  "parameters": {
    "confidenceMinimum": 90,
    "limit": 1000,
    "plaintext": false,
    "exceptCountries": "US,GB,CA"
  }
}

This will retrieve up to 1000 IP addresses with a confidence of at least 90%, excluding IPs from US, GB, and CA.

Getting Detailed Reports

Example of retrieving detailed reports for a specific IP (OPEN BETA):

Node Configuration:

{
  "resource": "ip",
  "operation": "reports",
  "parameters": {
    "ipAddress": "203.0.113.10",
    "maxAgeInDays": 60,
    "page": 1,
    "perPage": 50
  }
}

This will retrieve the first 50 detailed reports for IP address 203.0.113.10 within the last 60 days.

Clearing Reports

Example of clearing reports for a specific IP address:

Node Configuration:

{
  "resource": "ip",
  "operation": "clearAddress",
  "parameters": {
    "ipAddress": "192.168.1.50"
  }
}

This will delete all reports for IP address 192.168.1.50 from your account.

Abuse Categories

AbuseIPDB uses 23 predefined categories for classifying abuse types:

Category	ID	Description
DNS Compromise	1	Altering DNS records resulting in improper redirection
DNS Poisoning	2	Falsifying domain server cache (cache poisoning)
Fraud Orders	3	Fraudulent orders
DDoS Attack	4	Participating in distributed denial-of-service (DDoS) attacks
FTP Brute-Force	5	Brute-force attacks on FTP services
Ping of Death	6	Oversized IP packet attacks
Phishing	7	Phishing websites and emails
Fraud VoIP	8	Fraudulent VoIP
Open Proxy	9	Open proxy, open relay, or Tor exit node
Web Spam	10	Comment/forum spam, HTTP referer spam
Email Spam	11	Spam email content, infected attachments
Blog Spam	12	Blog spam
VPN IP	13	VPN IP
Port Scan	14	Scanning for open ports and vulnerable services
Hacking	15	Hacking
SQL Injection	16	Attempts at SQL injection
Spoofing	17	IP spoofing
Brute-Force	18	Credential brute-force attacks
Bad Web Bot	19	Malicious web bot
Exploited Host	20	Compromised host
Web App Attack	21	Attempts to probe for or exploit installed web applications
SSH	22	Secure Shell (SSH) abuse
IoT Targeted	23	IoT targeted attacks

Response Structure

IP Check Response

The check operation returns detailed information about an IP address:

{
  "data": {
    "ipAddress": "192.168.1.100",
    "isPublic": true,
    "ipVersion": 4,
    "isWhitelisted": false,
    "abuseConfidencePercentage": 75,
    "countryCode": "US",
    "countryName": "United States",
    "usageType": "ISP",
    "isp": "Example Internet Service Provider",
    "domain": "example.com",
    "totalReports": 15,
    "numDistinctUsers": 8,
    "lastReportedAt": "2024-01-15T10:30:00Z"
  }
}

Blacklist Response

The blacklist operation returns a list of the most reported IP addresses:

{
  "meta": {
    "generatedAt": "2024-01-15T10:30:00Z"
  },
  "data": [
    {
      "ipAddress": "198.51.100.42",
      "abuseConfidencePercentage": 95,
      "lastReportedAt": "2024-01-15T09:45:00Z",
      "countryCode": "CN",
      "usageType": "hosting"
    },
    {
      "ipAddress": "203.0.113.10",
      "abuseConfidencePercentage": 87,
      "lastReportedAt": "2024-01-15T08:20:00Z",
      "countryCode": "RU",
      "usageType": "ISP"
    }
  ]
}

Reports Response

The reports operation returns paginated detailed reports:

{
  "data": {
    "ipAddress": "203.0.113.10",
    "reports": [
      {
        "reportedAt": "2024-01-15T10:30:00Z",
        "comment": "Multiple SSH brute-force attempts",
        "categories": [18, 22],
        "reporterId": 12345,
        "reporterCountryCode": "US",
        "reporterCountryName": "United States"
      }
    ],
    "total": 45,
    "page": 1,
    "perPage": 25,
    "lastPage": 2
  }
}

CIDR Block Response

The checkBlock operation returns subnet abuse information:

{
  "data": {
    "networkAddress": "192.168.1.0/24",
    "netmask": "255.255.255.0",
    "minAddress": "192.168.1.0",
    "maxAddress": "192.168.1.255",
    "numPossibleHosts": 254,
    "addressSpaceDesc": "Private Use",
    "reportedAddress": [
      {
        "ipAddress": "192.168.1.100",
        "numReports": 5,
        "mostRecentReport": "2024-01-15T10:30:00Z",
        "abuseConfidencePercentage": 75,
        "countryCode": "US"
      }
    ]
  }
}

Integration in Workflow Context

The AbuseIPDB integration is particularly effective for security monitoring and threat intelligence workflows:

Common Workflow Patterns:

1. IP Reputation Monitoring:

   • Log Analysis Node → Extract IP Node → AbuseIPDB Node (check) → Filter Node (high confidence) → Alert Node (suspicious IPs)

2. Automated Threat Reporting:

   • Security Event Node → Script Node (analyze attack) → AbuseIPDB Node (report) → Database Node (log report) → Notification Node

3. Firewall Rule Generation:

   • Schedule Node → AbuseIPDB Node (blacklist) → Script Node (format rules) → Firewall Integration Node (update rules)

4. Incident Response Enhancement:

   • Incident Alert Node → AbuseIPDB Node (check) → Script Node (enrich with threat intel) → SIEM Integration Node (update case)

5. Network Security Assessment:

   • Network Scan Node → AbuseIPDB Node (checkBlock) → Report Node (security assessment) → Email Node (send report)

6. Threat Intelligence Gathering:

   • IOC Feed Node → AbuseIPDB Node (check) → Database Node (store intel) → Dashboard Node (visualize threats)

Advanced Features

Confidence-Based Filtering

Filter results based on abuse confidence percentage:

{
  "confidenceMinimum": 75
}

Geographic Filtering

Include or exclude specific countries:

{
  "onlyCountries": "US,GB,CA",
  "exceptCountries": "CN,RU"
}

Verbose Information

Get detailed ISP and geographic data:

{
  "verbose": true
}

Flexible Time Ranges

Configure report age from 1 to 365 days:

{
  "maxAgeInDays": 90
}

Pagination Support

Handle large result sets with page-based navigation:

{
  "page": 2,
  "perPage": 100
}

Multiple Abuse Categories

Report IPs for multiple abuse types:

{
  "categories": "14,15,18,22"
}

Best Practices

1. Use Appropriate Time Ranges: Set maxAgeInDays based on your use case - shorter for real-time monitoring, longer for historical analysis.

2. Set Confidence Thresholds: Use confidenceMinimum to filter out low-confidence reports and focus on high-risk IPs.

3. Implement Rate Limiting: Be aware of AbuseIPDB API rate limits and implement appropriate delays between requests.

4. Cache Results: Cache IP reputation results for frequently checked IPs to reduce API calls.

5. Use Verbose Mode Selectively: Enable verbose mode only when you need detailed geographic and ISP information.

6. Categorize Reports Accurately: Use appropriate abuse categories when reporting to ensure data quality.

7. Monitor API Usage: Track your API key usage to avoid hitting limits during critical operations.

8. Validate IP Addresses: Always validate IP address formats before making API calls.

9. Handle Private IPs: Remember that private IP addresses (RFC 1918) may not return meaningful results.

10. Implement Error Handling: Add comprehensive error handling for API failures, rate limits, and invalid responses.

IP Address Validation

The integration handles various IP address formats:

• IPv4: 192.168.1.100, 10.0.0.1
• IPv6: 2001:db8::1, ::1
• CIDR Notation: 192.168.1.0/24, 10.0.0.0/8

Rate Limiting

AbuseIPDB implements rate limiting based on your subscription level:

• Free: 1,000 requests per day
• Basic: 3,000 requests per day
• Premium: 10,000 requests per day
• Enterprise: Custom limits

Monitor your usage and implement appropriate delays to avoid hitting limits.

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
Authentication failed	Verify API key is valid and has necessary permissions
Rate limit exceeded	Implement delays between requests; check your subscription limits
Invalid IP address	Validate IP address format before making requests
No results returned	Check if IP is public (private IPs may not have reports)
Permission denied	Ensure API key has permissions for the operation (reporting, etc.)
Invalid abuse category	Verify category IDs are valid (1-23)
CIDR block too large	Use smaller CIDR blocks for better performance
Connection timeout	Check network connectivity and API service status

Error Response Format

The integration returns standardized error responses:

{
  "errors": [
    {
      "detail": "The IP address is not a valid IPv4 or IPv6 address.",
      "status": 422,
      "source": {
        "parameter": "ipAddress"
      }
    }
  ]
}

Common Error Codes

Status Code	Description
401	Unauthorized - Invalid API key
402	Payment Required - Subscription limit reached
422	Unprocessable Entity - Invalid parameters
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Service unavailable

Support

If you encounter issues with the AbuseIPDB integration, please contact our support team with:

• The operation you were attempting
• Your API key permissions (without the actual key)
• Any error messages received
• The IP addresses or parameters you were using
• The workflow context where the issue occurred

This information will help us provide faster and more accurate assistance. Updated: 2025-12-02