Field Reference

Detailed explanation of all response fields and their meanings.

Core Fields

asn

• Type: Integer
• Description: The Autonomous System Number being evaluated
• Example: 15169
• Note: Valid range is 1 to 4294967295 (32-bit ASN)

name

• Type: String or null
• Description: The organization name registered for this ASN
• Example: "GOOGLE", "CLOUDFLARENET"
• Note: Retrieved from WHOIS data. May be null for newly allocated ASNs

country_code

• Type: String or null
• Description: ISO 3166-1 alpha-2 country code where the ASN is registered
• Example: "US", "NL", "SG"
• Special Values:
  • "XX": Unknown or not yet determined
  • null: Data not available
• Note: Represents legal registration, not physical infrastructure location

registry

• Type: String or null
• Description: Regional Internet Registry managing this ASN
• Values: "ARIN", "RIPE", "APNIC", "LACNIC", "AFRINIC"
• Example: "ARIN" (North America), "RIPE" (Europe)
• Note: May be null if not yet determined from WHOIS data

risk_score

• Type: Integer (0-100)
• Description: Composite trust score (higher is better)
• Interpretation:
  • 90-100: Trusted, minimal risk
  • 70-89: Low to moderate risk
  • 50-69: Significant concerns
  • 0-49: High risk, known issues

risk_level

• Type: Enum
• Values: "LOW", "MEDIUM", "HIGH", "CRITICAL"
• Mapping:
  • LOW: score >= 90
  • MEDIUM: 70 <= score < 90
  • HIGH: 50 <= score < 70
  • CRITICAL: score < 50

last_updated

• Type: String (ISO 8601 timestamp)
• Description: When this ASN was last evaluated
• Example: "2026-01-11 23:03:28.308666+00:00"
• Note: Scores are recalculated on events or periodic refresh (typically every 5-15 minutes)

rank_percentile

• Type: Float (0.00-100.00)
• Description: Global safety ranking compared to all other ASNs
• Example: 95.4 means this ASN is less risky than 95.4% of the global internet
• Interpretation: Higher is better. 99+ is Elite, <50 is Hazardous.

downstream_score

• Type: Integer (0-100) or null
• Description: "Downstream Risk Algorithm" Score. Average risk score of this ASN's top downstream clients.
• Interpretation: logic "Guilt by association". If you sell to bad actors, your score drops.
• Threshold: <70 triggers a penalty.

Score Breakdown

breakdown.hygiene

• Type: Integer (0-100)
• Weight: 40% of total score
• Description: Routing best practices and protocol compliance
• Penalties Applied For:
  • RPKI invalid routes (RPKI_INVALID): -20 (threshold: > 1%)
  • Route leaks (ROUTE_LEAK): -20
  • Bogon advertisements (BOGON_AD): -10
  • Prefix over-deaggregation (FRAGMENTATION): -10 (threshold: granularity_score > 50)
  • Stub-to-transit violations (STUB_TRANSIT): -10
  • Zombie ASN — registered but zero active routes: -15

breakdown.threat

• Type: Integer (0-100)
• Weight: 35% of total score
• Description: Association with malicious infrastructure
• Penalties Applied For:
  • Spamhaus listing (THREAT_SPAMHAUS): -30
  • Botnet C2 hosting (THREAT_BOTNET): -20 per host, capped at -40
  • Phishing domains (THREAT_PHISHING): -5 per domain, capped at -20
  • Malware distribution (THREAT_MALWARE): -10 per endpoint, capped at -30
  • High spam emission rate (THREAT_SPAM): -15 (threshold: rate > 0.1)
  • Persistent threat recidivism: -10 (threshold: > 5 threat events in 30 days)
  • High WHOIS entropy (obfuscated name): -10 (threshold: entropy > 4.5)

breakdown.stability

• Type: Integer (0-100)
• Weight: 25% of total score
• Description: Operational reliability and BGP behavior
• Bonuses Applied For:
  • PeeringDB profile present: +5
  • Direct Tier-1 upstream count > 1: +5
• Penalties Applied For:
  • High upstream churn (> 2 providers in 90 days): -25
  • Predictive instability (high BGP event variance): -15
  • Excessive route withdrawals (> 100 in 7 days): -5
  • Bad neighborhood (avg upstream score < 50): -15
  • Suspicious upstreams (avg upstream score 50-69): -5
  • Toxic downstream clientele (avg downstream score < 70): -20
  • DDoS blackhole targeting (> 5 events in 7 days): -15
  • Excessive AS-PATH prepending (> 10 events in 7 days): -10

Signal Details

Hygiene Signals

rpki_invalid_percent

• Type: Float (0.0-100.0)
• Description: Percentage of announced prefixes with RPKI status INVALID
• Threshold: Any value > 0 triggers penalty
• Example: 2.5 means 2.5% of routes fail RPKI validation

rpki_unknown_percent

• Type: Float (0.0-100.0)
• Description: Percentage of announced prefixes without ROA coverage
• Threshold: Values > 50% trigger penalty
• Note: High values indicate lack of RPKI adoption, not necessarily malicious

has_route_leaks

• Type: Boolean
• Description: Detection of valley-free routing policy violations
• True When: ASN announces routes in violation of customer/peer/provider relationships
• Impact: Strong indicator of misconfiguration or hijacking

has_bogon_ads

• Type: Boolean
• Description: Advertisement of bogon/reserved IP space
• Examples: RFC 1918 private ranges, documentation ranges, unallocated space
• Impact: Severe penalty, indicates serious misconfiguration

is_stub_but_transit

• Type: Boolean
• Description: Stub ASN (single upstream) providing transit to others
• True When: Single-homed ASN appears in AS_PATH between unrelated networks
• Impact: Suspicious behavior, possible hijack or misconfiguration

prefix_granularity_score

• Type: Integer (0-100) or null
• Description: Score based on prefix announcement granularity
• Lower Values: Excessive deaggregation (many small prefixes)
• Higher Values: Appropriate aggregation
• Note: null when insufficient data

Threat Signals

spamhaus_listed

• Type: Boolean
• Description: Presence on Spamhaus DROP (Don't Route Or Peer) or EDROP lists
• True When: ASN is confirmed as controlled by spammers or malicious actors
• Data Source: Updated hourly from Spamhaus feeds
• Impact: Major penalty (-30)

spam_emission_rate

• Type: Float
• Description: Normalized spam emission score based on external reports
• Range: Typically 0.0 to 1.0, higher is worse
• Threshold: > 0.1 triggers penalty (-15)
• Data Source: Aggregated spam trap data

botnet_c2_count

• Type: Integer
• Description: Count of known botnet command and control servers
• Data Source: Threat intelligence feeds (Spamhaus, CINS Score)
• Note: Historical data retained for 90 days

phishing_hosting_count

• Type: Integer
• Description: Count of active phishing domains or IPs
• Data Source: PhishTank, OpenPhish, URLhaus
• Update Frequency: Hourly

malware_distribution_count

• Type: Integer
• Description: Count of malware distribution endpoints
• Data Source: URLhaus, VirusTotal
• Note: Includes both active and recently remediated

Metadata Signals

has_peeringdb_profile

• Type: Boolean
• Description: Presence of PeeringDB entry for this ASN
• False When: No public peering information available
• Impact: Reduces transparency score
• Note: Not having PeeringDB is not inherently malicious, but reduces trust

upstream_tier1_count

• Type: Integer
• Description: Count of direct Tier-1 upstream providers
• Range: Typically 0-10
• Interpretation:
  • 0: Single-homed or stub network (higher risk)
  • 1-2: Typical for most networks
  • 3+: Well-connected, higher resilience
• Data Source: AS relationship inference from BGP data

is_whois_private

• Type: Boolean
• Description: WHOIS information is hidden or uses privacy services
• True When: Contact information is redacted or uses privacy proxies
• Impact: Minor transparency penalty
• Note: Some legitimate organizations use privacy services

Forensics Signals (Deep Validation)

ddos_blackhole_count

• Type: Integer
• Description: Count of prefixes tagged with Blackhole communities by upstreams
• Interpretation: High values (>5) indicate the ASN is a DDoS target/victim
• Impact: Stability penalty (-15)

excessive_prepending_count

• Type: Integer
• Description: Count of AS paths with >3x prepending
• Interpretation: Indicates manual traffic engineering struggles or instability
• Impact: Stability penalty (-10)

Enterprise Headers

X-RateLimit-Limit

• Type: Integer
• Description: Maximum requests allowed per window (default 100)

X-RateLimit-Remaining

• Type: Integer
• Description: Requests remaining in current window

X-RateLimit-Reset

• Type: Integer (Unix Timestamp)
• Description: Time when the rate limit window resets

Details Array

The details field is no longer a list of strings but a list of Actionable Objects.

Structure

• code (string): Stable error code for programmatic handling (e.g., RPKI_INVALID)
• severity (enum): LOW, MEDIUM, HIGH, CRITICAL
• description (string): Human-readable explanation
• action (string): Recommended remediation step

Example Entries

[
  {
    "code": "RPKI_INVALID",
    "severity": "HIGH",
    "description": "2.5% of routes have INVALID RPKI status",
    "action": "Review ROA configuration for advertised prefixes."
  },
  {
    "code": "THREAT_SPAMHAUS",
    "severity": "CRITICAL",
    "description": "Listed on Spamhaus DROP/EDROP",
    "action": "Immediate removal required. Contact Spamhaus."
  }
]

Complete Penalty Code Reference

Every entry in details[] carries a code that is stable across API versions and safe to match programmatically.

Code	Sub-score	Penalty	Trigger Condition
RPKI_INVALID	Hygiene	-20	Any prefix with RPKI status INVALID
RPKI_UNKNOWN	Hygiene	-10	> 50% of prefixes lack ROA coverage
ROUTE_LEAK	Hygiene	-20	Valley-free routing violations detected
BOGON_AD	Hygiene	-10	RFC 1918 / reserved space announced
STUB_TRANSIT	Hygiene	-15	Stub ASN appears in transit paths
META_NO_PDB	Hygiene	-5	No PeeringDB profile found
META_NO_TIER1	Hygiene	-5	Zero direct Tier-1 upstream providers
META_PRIVATE	Hygiene	-5	WHOIS contact data hidden/private
THREAT_SPAMHAUS	Threat	-30	Listed on Spamhaus DROP or EDROP
THREAT_SPAM	Threat	-15	Spam emission rate > 0.1
THREAT_BOTNET	Threat	-20/host (max -40)	One or more botnet C2 servers hosted
THREAT_PHISHING	Threat	-5/domain	Active phishing domains detected
THREAT_MALWARE	Threat	-10/sample	Malware distribution endpoints detected

Null vs Zero Values

Understanding the difference between null and zero:

• null: Data not yet available or unknown
• 0 or false: Data collected, no issues detected
• Empty array []: No details to report (good sign)

Examples:

• "registry": null - Registry not yet determined from WHOIS
• "botnet_c2_count": 0 - Checked, none found
• "details": [] - All signals clean