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"
}

Get Access Rules​

Retrieve the access rules configured for your workspace — one by ID, or all of them.

Endpoint: GET /v1/access-rules/{id}

The id is optional. Omit it to list every rule.

Query Parameters:

  • resolve (boolean, optional): resolve country codes and ASN numbers to the IP ranges they currently cover.

Why resolve matters. A rule you wrote against a country or an ASN is stored that way, but the agent only ever enforces on addresses — the ranges are resolved for it upstream. Setting resolve=true shows you what a rule expands to, which is the difference between "block AS15169" and the several hundred prefixes that actually becomes. With resolve=false (the default) the country and asn fields come back as the plain values you set.

Response: a paginated envelope — success, data, page, limit, total.

StatusMeaning
200The rule, or the list
400Malformed request
404No rule with that ID
500Server error
# every rule, as written
curl -u "api:$API_KEY" "https://api.gen0sec.com/v1/access-rules"

# one rule, expanded to the addresses it currently covers
curl -u "api:$API_KEY" "https://api.gen0sec.com/v1/access-rules/{id}?resolve=true"

See Access Rules for how these are enforced, and why the resolution happens before the rule reaches the agent.

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: