Shodan Complete Tutorial 2026: Search Filters, CLI, API & Attack Surface Monitoring

Shodan runs a fleet of crawlers that pick random public IP addresses around the clock, connect to a large set of common ports, and record the raw response — the "banner" — that each service sends back. It never follows links like a web crawler; it talks directly to services. A single result therefore describes one service on one host: its IP, port, transport, detected product and version, TLS certificate details, hostnames, ASN/organisation, country and city, and any CVEs historically tied to that product version.

The same dataset serves opposite missions. Defenders use Shodan to see themselves the way an attacker does — an external, unauthenticated view of every service they have accidentally left exposed. Offensive testers use it to build a target's footprint without sending a single probe, keeping the reconnaissance phase completely off the target's radar.

Almost every useful Shodan feature — the CLI, the API, monitoring — authenticates with a single API key. Register a free account first, then copy the key from your account page. Keep it secret: your key is tied to your credit balance and can be abused if leaked.

• 1Register at account.shodan.io/register and confirm your email.
• 2Sign in and open account.shodan.io — your API Key is shown at the top of the page.
• 3Treat it like a password. You will feed it to the CLI once with shodan init, and reference it from scripts via an environment variable.

A free account lets you log in and run basic searches, but the filter language, bulk export and monitoring are gated behind a paid tier. The most cost-effective option for individuals has long been the one-time Membership unlock (a lifetime upgrade, not a subscription); ongoing high-volume automation uses metered API subscription plans.

Shodan meters usage with three separate credit pools. Understanding them is the difference between a productive month and hitting a wall on day three. Credits from a Membership refresh monthly and do not roll over; the first page of any web search is free, and the count command never costs a credit.

The Shodan CLI is a Python package published on PyPI. On any Linux system with Python 3 and pip you can install it in one line. On modern Kali and Debian releases, the system Python is "externally managed", so prefer a per-user or pipx install to avoid clobbering distro packages.

The same pip package works everywhere Python runs. On macOS use Homebrew's Python or pipx; on Windows install from python.org (tick "Add Python to PATH") and use pip from PowerShell.

Before any command works you must bind your API key to the CLI. This is a one-time step; the key is written to a small config file in your home directory (~/.config/shodan/api_key on Linux) and reused by every subsequent command.

A virtualenv keeps Shodan and its dependencies out of your system Python entirely — the right choice on "externally managed" distros and when you script against the API library. Everything lives in one folder you can delete to uninstall.

If you want a throwaway, dependency-free environment — or you run Shodan inside CI — a container is ideal. There is no need for a heavyweight image: the official python:slim base plus a one-line pip install gives you a working CLI. Pass the API key as an environment variable so it never bakes into the image.

At shodan.io, the search bar accepts free-text and filter:value syntax. Every result shows the IP, hostnames, owning org/ISP, location, and a set of facet sidebars — top ports, top countries, top organisations, top products — that let you pivot instantly. Click any host to see its full banner set and a "Vulnerabilities" panel listing CVEs mapped to the detected versions.

• 1Type a query, e.g. product:MongoDB, and read the left facet rail to understand the population before drilling in.
• 2Use the map and "Images" tabs (screenshots) to triage exposed panels visually.
• 3Open a single host page to see all services, the TLS cert chain, and the CVE list Shodan attaches.

Without filters, a keyword search is noise. Filters are how you slice the internet down to exactly the population you care about. These are the filters you will use daily; combine them freely, and remember most require a paid tier.

Precision comes from stacking filters and negating noise with a leading minus. The queries below are the kind you run during an authorised engagement or a self-audit — each narrows the internet to one specific exposure class. Point org:/net: at ranges you own or are authorised to test.

The shodan host command is the fastest way to profile a single address: open ports, detected products, hostnames, org, and mapped vulnerabilities — all from cache, so it costs no query credit. Add --history to see how the host changed over time, or --details for the raw banners.

Always size a query with count (free) before spending credits with search. search prints matching results and accepts --fields to control columns and --limit to cap output — critical for not burning query credits on a huge result set.

Facets are aggregate breakdowns and they are the analyst's best friend: instead of listing hosts, they summarise a population by any field — top ports, top products, top ASNs, top vulns. This is how you understand an org's exposure at a glance, cheaply.

For a snapshot you can diff over time, download writes results to a compressed JSON lines file (costs export credits, one per result set page), and parse extracts fields from that file locally — free, repeatable, and perfect for feeding a spreadsheet or SIEM.

Three small commands earn their keep constantly. myip returns your current public IP (handy in scripts and VPN checks), domain dumps DNS + subdomain intel for a domain, and honeyscore estimates the probability that an IP is a honeypot — useful before you trust an "easy" target during authorised testing.

The same shodan package exposes a clean Python client. Read the key from an environment variable — never hard-code it — and you have programmatic access to search, host lookups, counts, facets and alerts.

Use count() first (free), then iterate results deliberately. The search_cursor() helper pages through large result sets one item at a time — but every page past the first costs a query credit, so gate it with a hard cap.

Here is something you can actually run weekly against ranges you own: it walks your networks, flags any service on a "should-never-be-public" port list, and prints a report you can email or push to a ticket queue. It uses only cached data and cheap host lookups.

Shodan Monitor (monitor.shodan.io) lets you register the IP ranges you are responsible for and get notified whenever the exposure changes — a new port opens, a new service appears, or a known CVE is detected. It is the single highest-value defensive feature Shodan offers, and Membership includes a modest IP quota.

• 1Open monitor.shodan.io and click Add IP / Network.
• 2Enter your CIDR ranges — only ranges you own or are authorised to watch.
• 3Configure notifications (email, and via API a webhook) for the trigger types you care about.

Everything Monitor does in the browser is scriptable through shodan alert. Create an alert bound to a range, list your alerts, and wire triggers so changes generate notifications — perfect for baking attack-surface monitoring into infrastructure-as-code.

The shodan stream command opens a live feed. Restricted to your own alerts with --alerts, it prints banner events as Shodan observes changes on your monitored ranges — pipe it to a script and you have a home-grown SOC feed.

Nmap ships a shodan-api NSE script that queries Shodan's cache for each target's host data — so you learn open ports and CVEs without sending scan packets. That is invaluable when you want an initial picture but must stay quiet on the wire.

Metasploit's auxiliary/gather/shodan_search module runs a Shodan query from inside the console and drops results into the workspace database, so hosts you discover flow straight into the rest of your (authorised) engagement.

Shodan's InternetDB API (internetdb.shodan.io) returns open ports, hostnames, tags and CVEs for a single IP with no key and no credits — ideal for lightweight enrichment in a pipeline. Pipe those IPs into a scanner like Nuclei to validate exposures on assets you are authorised to test.

Most Shodan work is passive, reading cached banners. But shodan scan asks Shodan to actively re-scan an IP or range now and costs scan credits. This does send packets at the target, so it is only appropriate against assets you own or are explicitly authorised to test.

Shodan makes exposure trivial to find, which makes discipline essential. Searching the index is passive and legal in most jurisdictions; the moment you interact with a discovered host — logging in, downloading data, exploiting a CVE — you leave OSINT and enter conduct that requires authorisation.

Most Shodan CLI and API problems come down to four causes: PATH, key binding, plan limits, or credit exhaustion. This table maps the message you see to the fix.