ShodanClient 1.0.0

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package ShodanClient --version 1.0.0
                    


                    

                
NuGet\Install-Package ShodanClient -Version 1.0.0
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.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ShodanClient" Version="1.0.0" />
                    


                            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.0
                    


                    

                
#r "nuget: ShodanClient, 1.0.0"
#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.0
#: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.0
                    


                            Install as a Cake Addin
                        

                    

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


                            Install as a Cake Tool

ShodanClient

CI Release App 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. Not yet published to NuGet.

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

(not yet published)

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 zips for win-x64/win-arm64 via GitHub Releases, tagged app-vX.Y.Z.

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 33 7/2/2026
1.0.0 41 7/1/2026