IP Shield

IP Shield

Overview

User Agent Check API

Parse and detect malicious user agents

The User Agent Check API parses raw HTTP User-Agent headers against a database of malicious patterns. The endpoint classifies the traffic and returns detailed metadata about the scanner, crawler, or tool if it detects a match. Use this endpoint to dynamically block reconnaissance tools and vulnerability scanners at the edge.

Endpoint

Terminal
curl -X GET "https://ip-shield.riavzon.com/api/v1/check/user-agent/Nmap%20Scripting%20Engine%207.92" \
  -H "x-api-key: YOUR_API_KEY"

The Nmap%20Scripting%20Engine%207.92 parameter in the URL path represents the URL-encoded User-Agent string you want to check.

Ensure the User-Agent string is properly URL-encoded before sending it in the path to avoid routing errors.

Clean Response Example

When the API determines the User-Agent is safe, it returns a minimal payload indicating the check passed.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "date": "2025-06-12T00:00:00.000Z",
  "data": {
    "clean": true
  },
  "meta": {
    "total_credits": 10000,
    "credits_remaining": 9999
  }
}

Malicious Response Example

When the API detects a malicious or suspicious tool, it returns comprehensive data about the matched signature.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "date": "2025-06-12T00:00:00.000Z",
  "data": {
    "useragent": "Nmap Scripting Engine 7.92",
    "useragent_rx": "^Nmap Scripting Engine.*",
    "description": "Nmap Network Mapper",
    "tool": "Scanner",
    "category": "Reconnaissance",
    "link": "https://nmap.org/",
    "priority": "high",
    "severity": "critical"
  },
  "meta": {
    "total_credits": 10000,
    "credits_remaining": 9999
  }
}

Response Fields

ok
boolean
The API returns true when the request succeeds.
date
string
This field contains the ISO 8601 timestamp of the response.
data.clean
boolean
This field appears as true only if the User-Agent is benign, omitting the threat metadata.
data.useragent
string | null
This field reflects the raw, decoded User-Agent string that was evaluated.
data.useragent_rx
string | null
This field provides the underlying regular expression signature that triggered the match.
data.description
string | null
This field provides a brief description of the detected software or threat actor.
data.tool
string | null
This field identifies the specific tool or script name.
data.category
string | null
This field classifies the tool's behavior.
data.link
string | null
This field provides a reference URL containing more information about the tool.
data.priority
string | null
This field indicates the urgency of the alert (none, low, medium, high, critical).
data.severity
string | null
This field indicates the potential impact of the tool (none, low, medium, high, critical).
meta.total_credits
number
This field displays the total number of credits allocated to the account plan.
meta.credits_remaining
number
This field displays the number of credits remaining in the current billing cycle.

Error Response

Error responses, such as bad requests or rate limits, return the following JSON format.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "date": "2025-06-12T00:00:00.000Z",
  "reason": "Missing user-agent parameter"
}

Error Fields

ok
boolean
The API always returns false for error responses.
date
string
This field contains the ISO 8601 timestamp of the error event.
reason
string
This field provides a human-readable message that explains why the request failed.

Summary API

Logo