Whisper Python SDK

Introduction

‍

The Whisper Python SDK provides a fully-typed client for the Whisper API v1, offering comprehensive intelligence gathering and monitoring capabilities for domains, IPs, and web infrastructure. Built with modern Python practices, it supports both synchronous and asynchronous programming patterns with complete type hints for excellent IDE support.

‍

Key Features

• Fully Typed: Complete type hints for IDE autocomplete and type checking
• Async Support: Built-in support for async/await patterns
• Pythonic Design: Follows Python best practices and conventions
• Performance: <500ms typical response time with strategic caching
• Comprehensive: IP, Domain, DNS, WHOIS, Routing, Geolocation, Screenshots, Monitoring

Getting Started

‍

Prerequisites

• Python 3.7 or higher
• pip package manager
• Whisper API key from dash.whisper.security

Installation

‍

# Using pip
pip install whisper_api_sdk

# Using pip with specific version
pip install whisper_api_sdk==1.0.0

# Using pipenv
pipenv install whisper_api_sdk

# Using poetry
poetry add whisper_api_sdk

‍

Quick Start Example

‍

import whisper_api_sdk
from whisper_api_sdk.rest import ApiException
from pprint import pprint

# Configure API client
configuration = whisper_api_sdk.Configuration(
    host="https://api.whisper.security",
    access_token="YOUR_API_KEY"
)

# Create API client
with whisper_api_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the Indicators API
    api = whisper_api_sdk.IndicatorsApi(api_client)
    
    try:
        # Enrich an IP address
        response = api.get_indicator("ip", "8.8.8.8")
        print(f"Organization: {response.summary.organization}")
        print(f"Risk Score: {response.reputation.risk_score}")
    except ApiException as e:
        print(f"API Error: {e}")

‍

Async Example

‍

import asyncio
import whisper_api_sdk
from whisper_api_sdk.api_async import IndicatorsApiAsync

async def enrich_ip():
    configuration = whisper_api_sdk.Configuration(
        host="https://api.whisper.security",
        access_token="YOUR_API_KEY"
    )
    
    async with whisper_api_sdk.ApiClient(configuration) as api_client:
        api = IndicatorsApiAsync(api_client)
        
        response = await api.get_indicator("ip", "8.8.8.8")
        print(f"Organization: {response.summary.organization}")
        
# Run async function
asyncio.run(enrich_ip())

‍

Core Concepts

‍

1. API Structure

‍

The SDK is organized into three main API classes:

• IndicatorsApi: Intelligence and enrichment operations
• LocationApi: Geolocation and ASN intelligence
• OperationsApi: Async job management and tools

2. Client Context Manager

‍

The SDK uses Python's context manager pattern for proper resource management:

‍

with whisper_api_sdk.ApiClient(configuration) as api_client:
    # API client is properly initialized and will be cleaned up
    api = whisper_api_sdk.IndicatorsApi(api_client)

‍

3. Type Hints

‍

All methods and models are fully typed:

‍

from typing import Optional, List
from whisper_api_sdk.models import IndicatorResponse, BulkRequest

def process_indicator(
    api: whisper_api_sdk.IndicatorsApi,
    indicator_type: str,
    value: str,
    include: Optional[str] = None
) -> IndicatorResponse:
    return api.get_indicator(indicator_type, value, include)

‍

‍

4. Data Modules

‍

When enriching indicators, you can request specific data modules:

• routing: BGP routing information
• rpki: RPKI validation status
• whois: WHOIS registration data
• dns_details: Detailed DNS records
• ip_intelligence: IP intelligence and reputation

Authentication

‍

import whisper_api_sdk

configuration = whisper_api_sdk.Configuration(
    host="https://api.whisper.security",
    access_token="wsk_live_your_api_key_here"
)

‍

API Overview

‍

IndicatorsApi - Intelligence & Enrichment

‍

Core API for gathering intelligence on IPs and domains.

‍

Methods:

‍

# Single indicator enrichment
get_indicator(
    type: str,              # 'ip' or 'domain'
    value: str,             # IP address or domain name
    include: str = None     # Optional data modules
) -> IndicatorResponse

# Historical data
get_indicator_history(
    type: str,
    value: str,
    limit: int = None
) -> HistoryResponse

# Infrastructure relationships
get_indicator_graph(
    type: str,
    value: str
) -> GraphResponse

# Domain subdomains
get_subdomains(
    domain: str,
    limit: int = None
) -> SubdomainsResponse

# Similar domains
generate_similar_domains_get(
    domain: str,
    type: str = None,
    limit: int = None
) -> SimilarDomainsResponse

generate_similar_domains_post(
    domain: str,
    similar_domains_request: SimilarDomainsRequest
) -> JobResponse

# Bulk operations (async)
bulk_enrichment(
    bulk_request: BulkRequest
) -> JobResponse

# Search indicators (async)
search_indicators(
    search_request: SearchRequest
) -> JobResponse

‍

LocationApi - Geolocation Intelligence

‍

Geographic and network location services.

‍

Methods:

‍

# IP geolocation
get_ip_location(ip: str) -> LocationResponse

# Search by location attributes
search_location(
    field: str,
    value: str,
    limit: int = None
) -> List[LocationResponse]

‍

OperationsApi - Async Jobs & Tools

‍

Long-running operations and monitoring tools.

‍

Methods:

‍

# Job management
get_job(job_id: str) -> Job
list_jobs(status: str = None, limit: int = None) -> List[Job]

# Screenshots
create_screenshot(
    screenshot_request: ScreenshotRequest
) -> JobResponse

# Infrastructure scanning
create_scan(
    infra_scan_request: InfraScanRequest
) -> JobResponse

‍

Error Handling

‍

Exception Types

‍

from whisper_api_sdk.rest import ApiException

# ApiException attributes:
# - status: HTTP status code
# - reason: Error reason
# - body: Response body
# - headers: Response headers

‍

Support and Resources

• API Documentation: developer.whisper.security
• API Playground: dash.whisper.security/playground
• Support Email: support@whisper.security
• GitHub Issues: github.com/whisper-sec/sdk-python/issues
• PyPI Package: pypi.org/project/whisper-api-sdk

‍

‍

‍

‍

‍