Skip to content

Cheatsheet · OSINT

Shodan: assessing an organisation’s exposure

Shodan search filters, CLI commands, monitoring alerts and limits for assessing the internet exposure of an organisation you are authorised to test.

By Steven Carrier Published

Official website: Shodan CLI

Shodan indexes services reachable from the internet (banners, certificates, technologies) and makes them searchable. For an exposure assessment it is a passive reconnaissance source: you query what Shodan has already collected, without sending a single packet to the target. This cheatsheet covers search filters, the CLI, alerts and the tool’s limits. Examples use fictitious values (target.example, 192.0.2.0/24, Example Organisation): replace them with the scope agreed in the penetration test scoping checklist. For the full approach, see the OSINT exposure assessment methodology and the domain OSINT cheatsheet.

Search filters (web interface and CLI)

A query combines keywords and name:value filters. Quote values that contain spaces.

Filter Purpose Example
org: Organisation declared in the IP address data org:"Example Organisation"
net: CIDR range net:192.0.2.0/24
hostname: Host name (reverse DNS) containing the value hostname:target.example
port: Service port net:192.0.2.0/24 port:3389
product: Product identified in the banner product:nginx
ssl.cert.subject.cn: Common name of the TLS certificate ssl.cert.subject.cn:target.example
http.title: Title of the web page http.title:"Dashboard"
# Everything tied to the domain through reverse DNS
hostname:target.example

# Services exposed on the client's range, excluding ordinary web ports
net:192.0.2.0/24 -port:80,443

# Certificates issued for the domain, including on addresses outside the known range
ssl.cert.subject.cn:target.example

# Likely administration interfaces
org:"Example Organisation" http.title:"login"

An org: filter relies on the name the registry assigns to the address block: a hosting provider appears under its own name, not your client’s. Always combine several filters (net:, ssl.cert.subject.cn:, hostname:) to limit blind spots.

Install and initialise the CLI

# Installation (Python)
pip install shodan

# Store the account API key (kept in the user's profile)
shodan init YOUR_API_KEY

# Plan and remaining credits
shodan info

The API key is a secret: keep it out of repositories, shared scripts and deliverables. Preferably use a Shodan account dedicated to the engagement or to your company.

Search, count, aggregate

# Number of results: shows no results, useful to calibrate a query
shodan count 'net:192.0.2.0/24'

# Results with chosen fields (address, port, organisation, host names)
shodan search --fields ip_str,port,org,hostnames 'net:192.0.2.0/24'

# Limit the number of results (maximum 1000 per command)
shodan search --limit 50 --fields ip_str,port,product 'ssl.cert.subject.cn:target.example'

# Statistics by facet: ports, products, countries
shodan stats --facets port,product 'net:192.0.2.0/24'

Start with count, then stats: you gauge the size of the scope and spot unexpected ports or products before spending credits listing results.

Look up a specific host

# Everything known for an address: ports, banners, reported vulnerabilities
shodan host 192.0.2.10

# Full history of observations
shodan host --history 192.0.2.10

# Save the record to a file as evidence
shodan host --save 192.0.2.10

# Information tied to a domain: known subdomains and DNS records
shodan domain target.example

The "vulnerabilities" section of shodan host is inferred from the software version announced in the banner, without any real test: treat it as a lead, not a finding. A version backported by the distribution or hidden behind a proxy produces both false positives and false negatives.

Download and process results

# Download results to a compressed file (spends query credits)
shodan download --limit 500 client-exposure 'net:192.0.2.0/24'

# Extract fields from the downloaded file, with no new query
shodan parse --fields ip_str,port,org --separator , client-exposure.json.gz

# Filter on a value (here port 3389)
shodan parse --fields ip_str,port --filters port:3389 client-exposure.json.gz

Working from the downloaded file ensures the findings in your report match a dated, reproducible capture, even if Shodan’s data changes afterwards. Keep that file with the engagement’s other evidence.

Monitoring alerts

Alerts notify you when Shodan observes a change on a network you monitor (a newly opened service, for example). They suit continuous-monitoring engagements agreed with the client.

# Monitor a range owned by the client
shodan alert create "Example Client" 192.0.2.0/24

# Monitor the addresses tied to a domain
shodan alert domain target.example

# List alerts and inspect one
shodan alert list
shodan alert info ALERT_ID

# Remove an alert at the end of the engagement
shodan alert remove ALERT_ID

An alert only notifies for the triggers that are enabled: list them with shodan alert triggers, then enable the useful ones with shodan alert enable ALERT_ID TRIGGER_NAME. Available triggers depend on the plan. Only create alerts on addresses listed in the agreement, and remove them when the engagement ends.

Limits to keep in mind

  • Data freshness: each record carries a timestamp; a service may have been closed or changed since. Check the date before concluding, and reconfirm with the client.
  • Partial coverage: Shodan only sees the ports it scans and the addresses it encounters. No result is not proof of no exposure.
  • Credits: browsing pages beyond the first, advanced filters, download and on-demand scans consume credits depending on the plan. count and host generally do not, but check with shodan info.
  • Passive nature: querying Shodan sends nothing to the client. Verifying a finding directly afterwards (connecting, scanning) is an active action, which must be covered by the agreement and will appear in the client’s logs.
  • Third-party data: a shared address (CDN, shared hosting) can return services that do not belong to the client. Exclude them from the scope.

Engagement precautions

  • Only search for organisations, ranges and domains covered by the agreement.
  • Record the date and exact query behind every finding: that is what makes the result reproducible.
  • Treat collected banners and screenshots as sensitive data: some contain credentials or personal data. Do not keep them longer than necessary.
  • Report any critical exposure (open database, administration interface) to the client straight away, without waiting for the final report.

Sources

Related resources

  • AI prompt · Infrastructure and AD pentesting · OSINT · Cloud

    Attack surface prompt

    Prompt that analyses an asset inventory from the authorised scope (domains, IPs, services, cloud) to prioritise testing: exposure, criticality, checks.

    Published

  • Cheatsheet · OSINT

    Domain OSINT cheatsheet

    Passive collection on an organisation’s domain: whois and RDAP, DNS with dig, certificate transparency, subdomains, SPF and DMARC records.

    Published

  • Methodology · OSINT

    Organisation OSINT exposure

    Methodology to assess an organisation’s OSINT exposure for an authorised client: legal framework, infrastructure, people, leaks, code, brand, reporting.

    Published

BEAROPS

Need an OSINT investigation?

BEAROPS carries out OSINT investigations lasting from a few days to several weeks, using open sources within a legal framework.