IP Analysis Guide

Overview
‍

The IP Analysis endpoints are your primary tool for understanding a specific IP address. They move beyond simple geolocation to provide reputation, related domains, routing history, and a graph of connected assets. This is essential for incident response, alert enrichment, and infrastructure mapping.
‍

Core Endpoints

• GET /v1/indicators/ip/{ip}: The main endpoint to enrich a single IP address.
• GET /v1/indicators/ip/{ip}/history: Retrieves historical data (like BGP routing) for the IP.
• GET /v1/indicators/ip/{ip}/graph: Returns a node-and-link graph of related infrastructure.

Quick Example: Enriching a Single IP

‍

To get the core intelligence package for an IP, make a GET request to the indicators endpoint.

‍

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.whisper.security/v1/indicators/ip/8.8.8.8"

‍
Understanding the Response

‍

The response is a rich JSON object. Here are the key sections from the test data for 8.8.8.8:

• summary: This block provides the most critical, high-level data points for a quick assessment.
  • organization: The primary organization (e.g., "level 3").
  • location: A human-readable location (e.g., "mountain view, United States").
  • network: The parent CIDR block (e.g., "8.8.8.0/24").
  • asn_primary: The primary Autonomous System Number (e.g., "15169").
  • risk_score: A composite risk score (e.g., 85.5).
  • ip_type: Classification of the IP (e.g., "residential", "hosting", "vpn").
  • total_domains: The number of domains known to be associated with this IP (e.g., 99).
• geolocation: Detailed geographic and ISP data.
  • country: ISO code and name.
  • city: City name.
  • location: Latitude and longitude.
  • isp: Detailed ISP info, including name ("google llc") and asn (15169).
  • traits: Additional IP characteristics, like userType ("hosting").
• network: Deep network-layer intelligence.
  • data: Contains visibility, routing origins, and first/last seen timestamps for the prefix.
• relationships: One of the most powerful sections, detailing connections to other assets.
  • related_domains: An array of domain names that have been observed in relation to this IP (e.g., "dns.google.com", "viamericas.net", etc.).
• reputation: A breakdown of the risk score.
  • risk_score: The overall score.
  • blacklists: Scores based on IP, prefix, and ASN-level blacklist appearances.

Advanced Usage

‍

1. Filtering Data Modules

‍

You can filter the response data modulesby using the include query parameter.

‍

GET /v1/indicators/ip/8.8.8.8?include=routing,rpki

‍

This request will add a top-level routing block to the response, containing detailed BGP routing data (visibility, origins, specifics) for the IP's prefix.

‍

2. Getting Historical IP Data

‍

You can track how an IP's infrastructure has changed over time.

‍

GET /v1/indicators/ip/8.8.8.8/history?historyType=routing

‍

This endpoint returns a history of BGP routing announcements for the IP's prefix. The history.records array will be populated with objects showing originAsn, prefix, startTime, and endTime for each observed period.

‍

Note: whois history is only available for domain indicators. Requesting historyType=whois for an IP will return an empty list with a message.

‍

3. Visualizing Infrastructure Relationships

‍

To build a graph visualization, use the /graph endpoint.

‍

GET /v1/indicators/ip/8.8.8.8/graph

‍

The response provides a list of nodes (assets like IPs and Domains) and links (the relationships between them), ready to be fed into a visualization library.

• nodes: [{"id": "8.8.8.8", "type": "A_ADDRESS"}, {"id": "dns.google.com", "type": "DomainName"}, ...]

• links: [{"source": "8.8.8.8", "type": "hasIP", "target": "dns.google.com"}, ...]

API Reference

‍

For full details on parameters and response schemas, see the API Reference:

• Enrich Indicator: POST /v1/indicators/{type}/{value}
• Indicator History: GET /v1/indicators/{type}/{value}/history
• Indicator Graph: GET /v1/indicators/{type}/{value}/graph

‍

‍

‍

‍







‍

‍