Skip to main content

Threat API

The Threat API provides comprehensive threat intelligence analysis for IP addresses, including risk scores, confidence levels, threat categories, and remediation advice.

Base URL​

https://api.gen0sec.com

Authentication​

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

Endpoints​

Get Threat Analysis​

Analyze an IP address and retrieve comprehensive threat intelligence.

Endpoint: GET /v1/threat

Query Parameters:

  • ip (string, required): IP address to analyze (IPv4 or IPv6)
    • Example: 57.141.0.51

Response:

Success (200):

{
  "schema_version": "1.0",
  "tenant_id": "public",
  "ip": "57.141.0.51",
  "intel": {
    "score": 99,
    "confidence": 0.96,
    "score_version": "2025-09-01",
    "categories": ["botnet", "brute_force", "c2", "malware", "scanner", "spam"],
    "tags": ["default"],
    "first_seen": "2025-08-31T01:08:03Z",
    "last_seen": "2025-09-08T02:56:57Z",
    "source_count": 3,
    "reason_code": "MULTI_RECENT_SIGNALS",
    "reason_summary": "Indicators >=70 from 3 sources in last 7 days",
    "rule_id": "00000000-0000-0000-0000-000000000000"
  },
  "context": {
    "asn": 64500,
    "org": "ExampleNet",
    "ip_version": 4,
    "geo": {
      "country": "United States",
      "country_code": "US"
    }
  },
  "advice": "challenge",
  "ttl_s": 43200,
  "generated_at": "2025-09-08T03:00:00Z"
}

Response Fields:

  • intel.score (integer, 0-100): Threat risk score
  • intel.confidence (float, 0-1): Confidence level of the analysis
  • intel.categories (array): Threat categories (e.g., botnet, malware, scanner)
  • intel.tags (array): Free-form labels distinct from categories
  • intel.first_seen (string): ISO 8601 timestamp of first detection
  • intel.last_seen (string): ISO 8601 timestamp of most recent detection
  • intel.source_count (integer): Number of threat intelligence sources
  • intel.reason_code (string): Code explaining the threat assessment
  • intel.reason_summary (string): Human-readable summary of the threat
  • context.asn (integer): Autonomous System Number
  • context.org (string): Organization name
  • context.geo.country (string): Country name
  • context.geo.country_code (string): ISO country code
  • advice (string): Recommended action: "allow", "block", or "challenge"
  • ttl_s (integer): Cache TTL in seconds

No Data Found (200):

When no threat data is available, the API returns:

{
  "schema_version": "1.0",
  "tenant_id": "public",
  "ip": "192.168.1.1",
  "intel": {
    "score": 0,
    "confidence": 0.0,
    "score_version": "2025-09-01",
    "categories": [],
    "tags": [],
    "first_seen": "",
    "last_seen": "",
    "source_count": 0,
    "reason_code": "NO_DATA",
    "reason_summary": "No threat data available",
    "rule_id": "none"
  },
  "context": {
    "asn": 0,
    "org": "",
    "ip_version": 4,
    "geo": {
      "country": "",
      "country_code": ""
    }
  },
  "advice": "allow",
  "ttl_s": 60,
  "generated_at": "2025-09-08T03:00:00Z"
}

Error (400):

{
  "success": false,
  "error": "Missing IP address parameter",
  "details": {
    "required_param": "ip",
    "example": "/v1/threat?ip=192.168.1.1"
  }
}

Error (401):

{
  "success": false,
  "error": "Unauthorized - invalid or missing API key"
}

Error (402):

{
  "success": false,
  "error": "Payment required - subscription required"
}

Error (429):

{
  "success": false,
  "error": "Too many requests - rate limit exceeded"
}

Interactive Documentation​

Interactive API documentation is available at:

https://api.gen0sec.com/docs/threat/swagger/

Example Usage​

cURL​

curl -X GET "https://api.gen0sec.com/v1/threat?ip=57.141.0.51" \
  -H "Authorization: Bearer your-api-key"

Python​

import requests

url = "https://api.gen0sec.com/v1/threat"
headers = {
    "Authorization": "Bearer your-api-key"
}
params = {
    "ip": "57.141.0.51"
}

response = requests.get(url, params=params, headers=headers)
threat_data = response.json()

print(f"Threat Score: {threat_data['intel']['score']}")
print(f"Categories: {', '.join(threat_data['intel']['categories'])}")
print(f"Advice: {threat_data['advice']}")

Go​

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func main() {
    baseURL := "https://api.gen0sec.com/v1/threat"
    params := url.Values{}
    params.Add("ip", "57.141.0.51")

    req, _ := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    req.Header.Set("Authorization", "Bearer your-api-key")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var threatData map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&threatData)

    fmt.Printf("Threat Score: %v\n", threatData["intel"].(map[string]interface{})["score"])
}

Threat Categories​

Common threat categories include:

  • botnet - IP is part of a botnet
  • brute_force - IP involved in brute force attacks
  • c2 - Command and control server
  • malware - Associated with malware distribution
  • scanner - Port scanning activity
  • spam - Spam source
  • phishing - Phishing activities
  • exploit - Exploit attempts

Rate Limits​

API rate limits apply to prevent abuse. Contact support if you need higher limits.

Caching​

Responses include a ttl_s (time-to-live in seconds) field indicating how long you should cache the result. For IPs with no threat data, the TTL is typically 60 seconds. For IPs with threat data, the TTL is typically 43200 seconds (12 hours).

Support​

For API support, visit: