IP Quality Score

Enrichment Fraud Detection Threat Intelligence

Synopsis

A multi-purpose enrichment processor that leverages IP Quality Score APIs to provide fraud detection, validation, and threat intelligence for IP addresses, email addresses, URLs/domains, and phone numbers.

Schema

ipqs:
  - field: <ident>
  - api_key: <string>
  - query_type: <enum>
  - strictness: <number>
  - fast_mode: <boolean>
  - description: <text>
  - if: <script>
  - ignore_failure: <boolean>
  - ignore_missing: <boolean>
  - light_mode: <boolean>
  - user_agent: <string>
  - user_language: <string>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - tag: <string>
  - target_field: <ident>

Configuration

Field	Required	Default	Description
field	Y	-	Field containing the value to analyze
api_key	Y	-	IPQS API key
query_type	N	ip	Type of query: ip, email, url, or phone
strictness	N	0	Fraud scoring strictness (0-3)
fast_mode	N	false	Enable faster response with less accuracy
target_field	N	field	Field to store the API response
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue if API call fails
ignore_missing	N	false	Continue if source field doesn't exist
light_mode	N	false	Return limited data for faster response
user_agent	N	-	User agent for URL analysis
user_language	N	-	Language for URL analysis
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier

Details

The processor provides its service through multiple endpoints such as IP reputation and proxy/VPN detection, email validation and disposable email detection, URL/domain intelligence and malicious URL scanning, and phone number validation and fraud scoring.

note

Consider API rate limits in high-volume scenarios.

Multiple validation services are used to gather intelligence. Phone and email validation checks multiple fraud indicators.

User agent and language can help improve URL analysis accuracy.

Strictness level is configurable. Higher strictness levels provide more accurate fraud detection, while fast mode and light mode can reduce API response times. Similarly, higher strictness levels may increase false positives whereas fast mode may reduce detection accuracy.

Performance optimization is also available.

warning

Store API keys securely using environment variables.

Examples

IPs

Checking IP reputation...

{ "source_ip": "8.8.8.8" } ipqs: - field: source_ip - query_type: ip - api_key: "${IPQS_API_KEY}" - strictness: 2

returns detailed IP information:

{ "ip": { "ASN": 15169, "ISP": "Google", "abuse_velocity": "Premium required.", "active_tor": false, "active_vpn": false, "bot_status": true, "city": "Mountain View", "connection_type": "Premium required.", "country_code": "US", "fraud_score": 0, "host": "dns.google", "is_crawler": false, "latitude": 37.38999939, "longitude": -122.06999969, "message": "Success", "mobile": false, "organization": "Google", "proxy": false, "recent_abuse": false, "region": "California", "request_id": "UhAZv6m3uc", "success": true, "timezone": "America/Los_Angeles", "tor": false, "vpn": false, "zip_code": "N/A" } }

Emails

Checking an email address...

{ "email": "test@example.com" } ipqs: - field: email - query_type: email - api_key: "${IPQS_API_KEY}" - target_field: email_check

provides detailed validation results:

{ "email": { "a_records": ["192.0.2.1", "192.0.2.2"], "associated_names": { "names": [], "status": "Enterprise Plus or higher required." }, "associated_phone_numbers": { "phone_numbers": [], "status": "Enterprise Plus or higher required." }, "catch_all": false, "common": false, "deliverability": "high", "disposable": false, "dmarc_record": true, "dns_valid": true, "domain_age": { "human": "2 years ago", "iso": "2022-02-09T00:00:00-05:00", "timestamp": 1644382800 }, "domain_trust": "Upgraded plan required.", "domain_velocity": "Enterprise Mini or higher required.", "first_name": "Unknown", "first_seen": { "human": "1 day ago", "iso": "2024-02-08T00:00:00-05:00", "timestamp": 1707364800 }, "fraud_score": 0, "frequent_complainer": false, "generic": true, "honeypot": false, "leaked": false, "message": "Success.", "mx_records": ["mail.example.com"], "overall_score": 4, "recent_abuse": false, "request_id": "ABC123XYZ", "risky_tld": false, "sanitized_email": "test@example.com", "smtp_score": 3, "spam_trap_score": "none", "spf_record": true, "success": true, "suggested_domain": "N/A", "suspect": false, "timed_out": false, "user_activity": "Enterprise L4+ required.", "valid": true } }

URLs

Analyzing URLs for malicious content...

{ "url": "http://example.com/download.exe" } ipqs: - field: url - query_type: url - api_key: "${IPQS_API_KEY}" - user_agent: "Mozilla/5.0" - user_language: "en-US"

provides detailed security analysis:

{ "url": { "a_records": ["192.0.2.1"], "adult": false, "category": "N/A", "content_type": "application/x-msdownload", "country_code": "US", "dmarc_record": true, "dns_valid": true, "domain": "example.com", "domain_age": { "human": "2 days ago", "iso": "2024-02-07T00:00:00-05:00", "timestamp": 1707278400 }, "domain_rank": 0, "domain_trust": "Upgraded plan required.", "final_url": "http://example.com/download.exe", "hosted_content": false, "ip_address": "192.0.2.1", "language_code": "en", "malware": true, "message": "Success.", "mx_records": ["mail.example.com"], "ns_records": ["ns1.example.com", "ns2.example.com"], "page_size": 256000, "page_title": "Download Page", "parking": false, "phishing": true, "redirected": false, "request_id": "ABC123XYZ", "risk_score": 85, "risky_tld": false, "root_domain": "example.com", "scanned_url": "http://example.com/download.exe", "server": "Apache", "short_link_redirect": false, "spamming": false, "spf_record": true, "status_code": 200, "success": true, "suspicious": true, "technologies": [], "unsafe": true } }

Fast Mode

IP checks using reduced detail...

{ "ip": "1.1.1.1" } ipqs: - field: ip - query_type: ip - api_key: "${IPQS_API_KEY}" - fast_mode: true - light_mode: true

returns detailed IP analysis:

{ "ip": { "ASN": 13335, "ISP": "Cloudflare", "abuse_velocity": "Premium required.", "active_tor": false, "active_vpn": false, "bot_status": false, "city": "Example City", "connection_type": "Premium required.", "country_code": "US", "fraud_score": 0, "host": "one.one.one.one", "is_crawler": false, "latitude": 37.0, "longitude": -122.0, "message": "Success", "mobile": false, "organization": "Cloudflare", "proxy": false, "recent_abuse": false, "region": "Example State", "request_id": "ABC123XYZ", "success": true, "timezone": "America/Los_Angeles", "tor": false, "vpn": false, "zip_code": "N/A" } }

Phones

Validating phone number...

{ "phone": "+1234567890" } ipqs: - field: phone - query_type: phone - api_key: "${IPQS_API_KEY}" - strictness: 1

provides detailed phone analysis:

{ "phone": { "VOIP": false, "accurate_country_code": true, "active": true, "active_status": "N/A", "associated_email_addresses": { "emails": [], "status": "Enterprise Plus or higher required." }, "carrier": "Example Carrier", "city": "Example City", "country": "US", "dialing_code": 1, "do_not_call": false, "formatted": "+1 (234) 567-890", "fraud_score": 0, "leaked": false, "line_type": "Wireless", "local_format": "234-567-890", "mcc": "N/A", "message": "Phone is valid.", "mnc": "N/A", "name": "N/A", "prepaid": false, "recent_abuse": false, "region": "Example State", "request_id": "ABC123XYZ", "risky": false, "sms_domain": "N/A", "sms_email": "N/A", "spammer": false, "success": true, "timezone": "America/New_York", "user_activity": "Enterprise L4+ required.", "valid": true, "zip_code": "N/A" } }