Whisper C# SDK

Features

‍

The SDK provides access to powerful APIs for:

• Domain Intelligence: WHOIS data, DNS analysis, subdomain discovery
• IP Intelligence: Geolocation, network analysis, BGP routing information
• Infrastructure Monitoring: Health checks, relationship mapping
• Real-time Data: Streaming support for intelligence data with Server-Sent Events

Requirements

• .NET 9.0 or later
• Bearer token for API authentication (Sign up to get a free API key)

Installation

‍

Package Manager Console

‍

Install-Package Noctis.FrontGraph.Sdk

‍

‍.NET CLI

‍

dotnet add package Noctis.FrontGraph.Sdk

‍

PackageReference

‍

<PackageReference Include="Noctis.FrontGraph.Sdk" Version="1.0.0" />

‍

Quick Start

‍

1. Configure Services

‍

Add the SDK to your application's dependency injection container:

‍

using Noctis.FrontGraph.Sdk.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configure the SDK
builder.Services.AddApi(config =>
{
    config.AddApiHttpClients(client =>
    {
        // Set the base URL (default: https://api.whisper.security)
        client.BaseAddress = new Uri("https://api.whisper.security");

        // Add authentication header
        client.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
    });
});

var app = builder.Build();

‍

2. Use the APIs

‍

Inject and use the APIs in your services or controllers:

‍

using Noctis.FrontGraph.Sdk.Api;

public class IntelligenceService
{
    private readonly IIntelligenceServicesApi _intelligenceApi;
    private readonly IDomainManagementApi _domainApi;

    public IntelligenceService(
        IIntelligenceServicesApi intelligenceApi,
        IDomainManagementApi domainApi)
    {
        _intelligenceApi = intelligenceApi;
        _domainApi = domainApi;
    }

    public async Task<DomainIntelligenceResponse> GetDomainInfoAsync(string domain)
    {
        var response = await _intelligenceApi.GetDomainIntelligenceAsync(domain);

        if (response.IsOk)
        {
            return response.Ok;
        }

        // Handle error cases
        if (response.IsBadRequest)
            throw new ArgumentException("Invalid domain format");
        if (response.IsUnauthorized)
            throw new UnauthorizedAccessException("Invalid API token");

        throw new Exception("Failed to fetch domain intelligence");
    }
}

‍

API Usage Examples

‍

The SDK is divided into logical API clients for different functionalities.

‍

IP Intelligence

‍

Analyzes an IP address to return geolocation, network topology, and risk scoring data.

‍

var response = await intelligenceApi.GetIpIntelligenceAsync("8.8.8.8");

if (response.IsOk)
{
    var data = response.Ok;

    // Access summary and geolocation details
    var summary = data.Summary;
    var country = data.Geolocation?.Country?.Name;
    var city = data.Geolocation?.City;
}

‍

Domain Intelligence

‍

Provides comprehensive data for a domain, including WHOIS, DNS records, and IP intelligence for all resolved addresses.

‍

var response = await intelligenceApi.GetDomainIntelligenceAsync("example.com");

if (response.IsOk)
{
    var data = response.Ok;
    
    // Access various parts of the domain data
    var whois = data.Registration;
    var dnsRecords = data.Dns;
}

‍

Subdomain Discovery

‍

Finds subdomains for a given base domain with filtering options.

‍

var response = await domainApi.FindSubdomainsAsync(
    baseDomain: "example.com",
    limit: 100,
    level: "ALL" // Options: ALL, IMMEDIATE, MAX_DEPTH
);

if (response.IsOk)
{
    var subdomains = response.Ok?.Domains;
    // Process the list of found subdomains...
}

‍

Advanced Features

‍

Streaming with Server-Sent Events (SSE)

‍

For lower latency, you can stream responses from the intelligence APIs. To enable this, configure the HttpClient to accept the text/event-stream media type. The response will stream events like whois, dns, subdomains, and more.

‍

Error Handling

The SDK uses typed response objects, making it easy to handle different HTTP status codes cleanly without needing to inspect the raw response.

‍

var response = await api.GetDomainIntelligenceAsync(domain);

if (response.IsOk)
{
    // Success
}
else if (response.IsBadRequest)
{
    // 400 - Invalid request
}
else if (response.IsUnauthorized)
{
    // 401 - Authentication failed
}
else if (response.IsTooManyRequests)
{
    // 429 - Rate limit exceeded
}

‍

Event Handling

‍

You can subscribe to events to monitor API interactions, such as when a call succeeds or fails.

‍

// Subscribe to success and error events
api.Events.OnFindSubdomains += (sender, args) => Console.WriteLine($"Success: {args.StatusCode}");
api.Events.OnErrorFindSubdomains += (sender, args) => Console.WriteLine($"Error: {args.Exception.Message}");

‍

Custom HTTP Client Configuration

‍

The SDK allows for advanced configuration of the underlying HttpClient, such as adding Polly retry policies for transient network errors.

‍

builder.Services.AddApi(config =>
{
    config.AddApiHttpClients(
        client => { /* ... */ },
        builder =>
        {
            // Add a Polly retry policy
            builder.AddPolicyHandler(GetRetryPolicy());
        }
    );
});

‍

‍

‍

‍

‍

‍