OSINT
Query the Shodan device index from a managed node
Search and inspect internet-facing hosts through the Shodan CLI.
overview
What shodan-python does
shodan-python exposes the Shodan CLI as search, host, count, stats, domain, and honeyscore modes. It takes api-key plus a query or target and writes a file with a results folder.
Use it to confirm what an IP exposes, size a query with count before spending credits, or pull subdomain and service context with domain mode. Trim columns with --fields and cap volume with --limit.
When you only need a one-shot json.gz dump of a full match set, switch to shodan-download. Keep scan mode limited to authorized targets; query modes stay passive against Shodan's index.
use cases
Where shodan-python fits
Look up everything about a host
Run host mode on an IP, with --history when you want past banners, to see every open port, service banner, and certificate Shodan has recorded for it.
Search the index for threat intelligence
Query Shodan for exposed products, ports, or vulnerable software versions, then break the results down with facets and stats to prioritize what matters.
Map a domain's hosts and subdomains
Run domain mode with --details to turn a domain into a list of subdomains and the service inventory behind each resolved IP.
Size a search before exporting
Use count mode to return the number of matches, so you know how large a bulk download will be before spending credits.
Flag likely honeypots
Run honeyscore on an IP to estimate whether a host is a honeypot before treating its banners as real infrastructure.
reference
shodan-python inputs and flags
| Name | Type | Flag | Description |
|---|---|---|---|
| search-mode | BOOLEAN | search | Search the Shodan database for hosts matching a query. |
| host-mdoe | BOOLEAN | host | View every open port, banner, and certificate for an IP address. |
| domain-mode | BOOLEAN | domain | Look up a domain's subdomains and associated IPs. |
| count-mode | BOOLEAN | count | Return only the number of results for a search. |
| honeyscore-mode | BOOLEAN | honeyscore | Check whether an IP is likely a honeypot. |
| api-key | STRING | · | Shodan API key used to authenticate requests. |
| fields | STRING | --fields | Comma-separated list of properties to output. |
| limit | STRING | --limit | Cap the number of results returned. |
Showing key inputs. shodan-python exposes 50 inputs in total.
Full flag reference (50 inputs)
| Name | Type | Flag | Description |
|---|---|---|---|
| type | STRING | --type | Result type for the query. |
| force | BOOLEAN | --force | Force the operation. |
| limit | STRING | --limit | Limit the number of results returned. |
| facets | STRING | --facets | List of facets to get statistics for. |
| fields | STRING | --fields | List of properties to output. |
| format | STRING | --format | Output format for the host information: pretty or tsv. |
| api-key | STRING | · | Shodan API key used to authenticate requests. |
| history | BOOLEAN | --history | Include historical data in the results. |
| verbose | BOOLEAN | --verbose | Verbose output. |
| data-set | STRING | --dataset | See the available files in the given dataset. |
| filename | STRING | --filename | Save the host information in the given file. |
| no-color | BOOLEAN | --no-color | Disable colors in the output. |
| org-mode | STRING | org | Manage your organization's access to Shodan. |
| data-mode | BOOLEAN | data | Bulk data access to Shodan. |
| host-mdoe | BOOLEAN | host | View all available information for an IP address. |
| scan-mode | BOOLEAN | scan | Scan an IP or netblock using Shodan. |
| separator | STRING | --separator | The separator between the properties of the search results. |
| count-mode | BOOLEAN | count | Return the number of results for a search. |
| parse-mode | BOOLEAN | parse | Extract information out of compressed JSON files. |
| stats-mode | BOOLEAN | stats | Provide summary information about a search query. |
| domain-mode | BOOLEAN | domain | Look up DNS records and subdomains for a domain. |
| domain-name | STRING | · | Domain name to look up in domain mode. |
| search-mode | BOOLEAN | search | Search the Shodan database. |
| silent-mode | STRING | --silent | Do not send a notification to the user. |
| convert-mode | BOOLEAN | convert | Convert the given input data file into a different format. |
| host-mode-ip | STRING | · | IP address to inspect in host mode. |
| org-mode-add | STRING | add | Add a new member to the organization. |
| scan-mode-ip | STRING | · | IP address or netblock to scan. |
| wait-results | STRING | --wait | How long to wait for results to come back. |
| honeyscore-ip | STRING | · | IP address to check whether it is a honeypot. |
| org-mode-info | BOOLEAN | info | Show an overview of the organization. |
| data-mode-list | BOOLEAN | list | List available bulk data files. |
| scan-mode-list | BOOLEAN | list | Show recently launched scans. |
| honeyscore-mode | BOOLEAN | honeyscore | Check whether the IP is a honeypot or not. |
| org-mode-remove | STRING | remove | Remove and downgrade a member. |
| save-information | BOOLEAN | --save | Save the information in a file. |
| scan-mode-status | STRING | status | Check the status of an on-demand scan by SCAN_ID. |
| scan-mode-submit | STRING | submit | Submit an IP or netblock to scan using Shodan. |
| stats-mode-query | STRING | · | Search query to summarize in stats mode. |
| search-mode-query | STRING | · | Search query to run in search mode. |
| count-search-query | STRING | · | Search query to count in count mode. |
| data-mode-download | FILE | download | Dataset to download in bulk data mode. |
| parse-mode-filters | STRING | --filters | Filter the results for specific values using key:value. |
| scan-mode-internet | STRING | internet | Scan the internet for a specific port and protocol using Shodan infrastructure. |
| domain-mode-details | STRING | --details | Look up host information for any IPs in the domain results. |
| parse-mode-filename | FILE | · | JSON file to parse. |
| scan-mode-protocols | STRING | protocols | List the protocols you can scan with using Shodan. |
| convert-mode-filename | FILE | · | Input file to convert. |
| data-mode-search-query | STRING | · | Search query used to select bulk data. |
| convert-mode-output-format | STRING | · | Convert output format, for example kml, csv, geo.json, images, xlsx. |
example
Run shodan-python
# search the index, cap the results, and print selected fieldsshodan search --limit 25 --fields ip_str,port,org,product 'product:nginx port:443'198.51.100.23 443 Example Networks nginx198.51.100.24 443 Example Networks nginx203.0.113.10 443 Cloud Example BV nginx203.0.113.42 8443 Example Hosting nginx198.51.100.9 443 Example Networks nginx203.0.113.77 443 Example Telecom nginxguidance
Choosing shodan-python
Use shodan-python for interactive Shodan work: searching the device index, inspecting a host, counting matches, or pulling stats. For a one-shot bulk dump to json.gz, use shodan-download.
shodan-download
Bulk-exports a query to json.gz for offline processing. Prefer it when you only need the raw dump.
securitytrails-subdomains
Passive DNS inventory rather than device banners. Complementary OSINT, not a substitute.
sherlock
Social-identity OSINT. A different axis from device and service intelligence.
workflows
Workflows using shodan-python
faq
shodan-python questions
related
More OSINT tools
dnsdumpster-dns-lookup
Passive DNS records from DNSDumpster.
dnstwist
Generate lookalike domains and flag registered typosquats.
favup
Look up the real IP of a host from its favicon via Shodan.
Infoga
Email OSINT from public sources, with optional breach checks.
maigret
Username search that collects accounts and profile data into one dossier.
socialscan
Check whether emails and usernames are available, taken, or invalid.
Run shodan-python yourself
A search query feeds shodan-python, which queries the device index and writes the matching hosts and services as a queryable output.
Facts on this page come from the live Trickest tool library.