ShodanClient 1.0.1

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package ShodanClient --version 1.0.1
                    


                    

                
NuGet\Install-Package ShodanClient -Version 1.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ShodanClient" Version="1.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ShodanClient" Version="1.0.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ShodanClient" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ShodanClient --version 1.0.1
                    


                    

                
#r "nuget: ShodanClient, 1.0.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ShodanClient@1.0.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ShodanClient&version=1.0.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ShodanClient&version=1.0.1
                    


                            Install as a Cake Tool

ShodanClient

C# 14 .NET 10 Native AOT CI Release NuGet License: MIT

A modern, fully-typed, high-performance .NET 10 / C# 14 client for the Shodan API covering all five API surfaces: Search, On-Demand Scanning, Network Alerts, Notifiers, Directory, DNS, Account, Organization, Bulk Data, Utility, API Status, Streaming, Trends, Exploits and InternetDB.

Status: feature-complete against Shodan's published REST, Streaming, Trends and InternetDB APIs. Native-AOT/trim-safe, source-generated JSON throughout.

Why

Shodan exposes its functionality across five distinct API surfaces, each with its own base URL and authentication style: the core REST API, the long-lived Streaming API, the historical Trends API, the key-less InternetDB, and the Exploits API. ShodanClient wraps all of them behind a single, ergonomic, dependency-injection-friendly client with first-class support for resilience, client-side rate limiting, cancellation, and Native AOT.

builder.Services.AddShodanClient(builder.Configuration); // binds the "Shodan" config section

var shodan = app.Services.GetRequiredService<IShodanClient>();

var host = await shodan.Hosts.GetAsync("8.8.8.8");
var results = await shodan.Search.SearchAsync("apache country:US");
var summary = await shodan.InternetDb.GetAsync("1.1.1.1"); // no API key required

await foreach (var banner in shodan.Stream.StreamAllBannersAsync())
{
    Console.WriteLine($"{banner.IpString}:{banner.Port}");
}

Architecture

The solution follows Clean Architecture, with all five Shodan API surfaces modeled as bounded contexts inside the same layers rather than as separate packages:

ShodanClient.Domain          → pure Shodan domain models, zero dependencies
ShodanClient.Application     → service & repository interfaces, options, exceptions
ShodanClient.Infrastructure  → HTTP repositories, routes, auth, resilience, rate limiting
ShodanClient                 → public facade, DI extensions, the package you install

Only ShodanClient is published to NuGet; the inner layers are merged into that single package so consumers add one dependency.

Sub-clients

IShodanClient.* Covers
.Hosts GET /shodan/host/{ip}
.Search /shodan/host/search, /count, /search/facets\|filters\|tokens (with auto-paging SearchAllAsync)
.Scans On-demand scanning: /shodan/ports, /protocols, /scan, /scan/internet, /scans*
.Alerts Network alerts: CRUD, triggers, notifier links
.Notifiers Notification services CRUD
.Directory Saved search query directory
.BulkData Bulk datasets (Enterprise)
.Organization Organization management (Enterprise)
.Account The account linked to the API key
.Dns Domain info, forward/reverse DNS
.Tools HTTP header echo, caller IP
.ApiInfo Plan info and remaining credits
.InternetDb Key-less fast IP summaries
.Trends Historical month-to-month search trends
.Exploits Exploit & vulnerability search
.Stream Real-time banner firehose, as IAsyncEnumerable<Banner>

Performance & correctness

  • Source-generated JSON everywhere (ShodanJsonContext) — no reflection-based serialization, JsonSerializerIsReflectionEnabledByDefault=false enforces it at compile time.
  • Native AOT / trim compatible — every project builds with IsAotCompatible=true and EnableTrimAnalyzer=true.
  • Per-surface HttpClients with SocketsHttpHandler connection pooling, Microsoft.Extensions.Http.Resilience ( retry, circuit breaker, timeouts) on every surface except Streaming, which uses an infinite timeout instead.
  • Client-side rate limiting via System.Threading.RateLimiting (token bucket, paced to Shodan's ~1 req/s default).
  • Clean base-URL ⇄ route separation — routes never carry a host or API key; a single delegating handler injects ?key= only on the surfaces that require it (all except InternetDB).

Installation

dotnet add package ShodanClient

Configuration

// appsettings.json
{
  "Shodan": {
    "ApiKey": "YOUR_SHODAN_API_KEY" // or set the Shodan__ApiKey environment variable
  }
}

builder.Services.AddShodanClient(builder.Configuration);
// or: builder.Services.AddShodanClient(options => options.ApiKey = "...");

See Samples/ShodanClient.Samples.ConsoleApp for a runnable example.

Tools

Tools/ShodanClient.App is an Avalonia desktop GUI built on top of the SDK, Windows-only for now. It ships as Native AOT, self-contained .zip archives and .msi installers for win-x64/win-arm64, built and published from the same GitHub Release pipeline as the SDK package, tagged vX.Y.Z. Each release also includes a SHA256SUMS.txt for integrity verification.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.1 0 7/2/2026
1.0.0 38 7/1/2026