## https://sploitus.com/exploit?id=AE62B358-A533-5795-A29B-52F9E6A177FE
# Shodan API client for Go
A small Shodan API client and CLI built with Go's standard `http.Client`. It covers Internet search, host enrichment, DNS and certificate intelligence, vulnerability and exploit data, on-demand scanning, historical trends, and GeoNet measurements.
## Requirements
- Go 1.26.5 or later
- A Shodan API key in `SHODAN_API_KEY`
- The Shodan plan required by the endpoint you call
The client reads the API key when `shodan.NewClient` is created. Authenticated Shodan APIs receive it through the required `key` query parameter. Public APIs such as Certificate Transparency, CVEDB, and GeoNet do not receive the key, although the current shared client constructor still requires the environment variable.
## Install the CLI
### PowerShell (`pwsh`)
```powershell
$env:SHODAN_API_KEY = "your-api-key"
go install github.com/snowmerak/shodan/cmd/shodan@latest
shodan help
```
### Linux and macOS (Bash or Zsh)
```bash
export SHODAN_API_KEY="your-api-key"
go install github.com/snowmerak/shodan/cmd/shodan@latest
shodan help
```
Make sure the Go binary directory is in `PATH`. It is normally `$(go env GOPATH)/bin` on Linux and macOS, and `$(go env GOPATH)\bin` on Windows.
When working from a local clone, install the current checkout instead:
```console
go install ./cmd/shodan
```
You can also run the CLI without installing it:
```console
go run ./cmd/shodan help
go run ./cmd/shodan host "8.8.8.8"
```
## Internet search and host intelligence
The main Shodan REST API searches service banners already collected by Shodan. A normal search does not connect to or scan the target.
- `Search` returns matching service banners, up to 100 per page.
- `Count` returns the total and facet summaries without banners or query-credit usage.
- `HostInfo` returns services and enrichment data observed for an IP.
- `SearchFilters`, `SearchFacets`, and `SearchTokens` help build and validate queries.
- `Info` returns plan and remaining-credit information.
Filtered searches and pages after the first can consume query credits. Use `Count` first when you only need to estimate result size.
```console
shodan search -count "product:nginx country:KR"
shodan search "product:nginx country:KR"
shodan host "8.8.8.8"
shodan host -minify "8.8.8.8"
shodan host -history "8.8.8.8"
```
Host lookups do not consume query credits, but the main API requires at least a Shodan Membership for IP lookups. Corporate plans can enrich up to 100 IPs in one request through the library:
```go
hosts, err := client.HostInfoBulk(
ctx,
[]string{"8.8.8.8", "1.1.1.1"},
shodan.HostOptions{Minify: true},
)
```
## DNS and domain intelligence
Domain DNSDB results cost one query credit per page. Forward and reverse DNS utilities use the same authenticated main API.
```console
shodan dns domain "example.com"
shodan dns domain -type MX "example.com"
shodan dns domain -history -page 2 "example.com"
shodan dns resolve "example.com" "www.example.com"
shodan dns reverse "8.8.8.8" "1.1.1.1"
```
## Certificate Transparency
The public Certificate Transparency API is hosted at `ctl.shodan.io`. These requests do not include the Shodan API key.
```console
shodan certificate domain "example.com"
shodan certificate hostnames "example.com"
shodan certificate sha256 "e5e217863ae00d4f5cba5ef0b1714d652f7bc8ab6dd41ddbd5724d7a806f1642"
```
To find Internet services on which a CT certificate was observed, use its SHA-256 fingerprint with the main search API:
```go
result, err := client.Search(ctx, shodan.SearchOptions{
Query: `ssl.cert.fingerprint:"SHA256-FINGERPRINT"`,
Fields: []string{"ip_str", "port", "hostnames", "ssl.cert.subject", "ssl.cert.issuer"},
})
```
## Vulnerability and exploit intelligence
CVEDB is a public API hosted at `cvedb.shodan.io`. It provides CVSS and EPSS data, CISA KEV status, affected CPEs, and EUVD references. The API key is not sent. Non-commercial use is free; commercial use requires an Enterprise license.
```console
shodan vulnerability cve "CVE-2024-0204"
shodan vulnerability euvd "EUVD-2024-16003"
shodan vulnerability search -product "php" -kev -sort-epss -limit 10
shodan vulnerability search -cpe "cpe:2.3:a:php:php:8.0" -limit 10
shodan vulnerability count -product "php"
shodan vulnerability cpes -product "php" -limit 10
```
The authenticated Exploits API at `exploits.shodan.io/api` searches integrated CVE, ExploitDB, and Metasploit data.
```console
shodan exploit search -facets "source,type" "cve:CVE-2024-0204"
shodan exploit count -facets "platform,type" "platform:linux"
```
## On-demand active scanning
The scanning API asks Shodan's crawlers to actively scan a public IP or CIDR. Each target IP consumes one scan credit. Only scan systems you own or have explicit permission to test.
Read-only commands:
```console
shodan scan ports
shodan scan protocols
shodan scan list
shodan scan list -page 2
shodan scan status ""
```
Submission commands require `-execute` to reduce accidental scans. Replace the documentation-only address below with a public target you are authorized to scan.
### PowerShell (`pwsh`)
```powershell
shodan scan submit -execute "198.51.100.10"
shodan scan service -execute `
-service "53:dns-udp" `
-service "443:https" `
"198.51.100.10"
```
### Linux and macOS (Bash or Zsh)
```bash
shodan scan submit -execute "198.51.100.10"
shodan scan service -execute \
-service "53:dns-udp" \
-service "443:https" \
"198.51.100.10"
```
Scans are asynchronous. Use the returned ID with `shodan scan status`, then query `HostInfo`, Search, or the Streaming API after completion. This client intentionally does not expose the Internet-wide scan endpoint, which is limited to Enterprise Data customers and approved researchers.
## Historical Trends API
The Enterprise Historical Data API at `trends.shodan.io` returns month-to-month search counts and optional monthly facet distributions. It does not return raw historical service banners.
```console
shodan trends filters
shodan trends facets
shodan trends search -facets "country:10,org:5" "product:nginx"
```
`SearchTrends` stores the `month`/`count` time series in `Matches` and the monthly top values in `Facets`. All three Trends endpoints require Enterprise access and authenticate with `SHODAN_API_KEY`.
## GeoNet
The public GeoNet API at `geonet.shodan.io` runs DNS lookups or ICMP pings from Shodan nodes in multiple geographic regions. Requests do not include the API key. Non-commercial use is free, with a default public rate limit of one request per second.
```console
shodan geonet dns "example.com"
shodan geonet dns -type AAAA "example.com"
shodan geonet ping "8.8.8.8"
shodan geonet ping "example.com"
```
`GeoDNS` returns DNS answers and the measurement-node location for each region. `GeoPing` returns regional RTT, packet loss, and reachability. Unlike the main DNSDB API, GeoNet performs a current distributed measurement and does not search stored DNS history.
## Library usage
```go
package main
import (
"context"
"log"
"time"
"github.com/snowmerak/shodan"
)
func main() {
client, err := shodan.NewClient()
if err != nil {
log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
result, err := client.Search(ctx, shodan.SearchOptions{
Query: "product:nginx country:KR",
Facets: []string{"country", "org:10"},
Fields: []string{"ip_str", "port", "transport", "product", "org"},
})
if err != nil {
log.Fatal(err)
}
log.Printf("matches: %d", result.Total)
}
```
## Testing
The test suite uses local mock HTTP servers. It does not call live Shodan APIs or require a real API key.
```console
go test ./...
go vet ./...
```