How do I install the Lookup Shodan skill?

Run npx skillmds@latest add liberty91ltd/lookup-shodan in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Lookup Shodan skill do?

Use when you need host reconnaissance for an IP or domain — open ports, services, banners, OS detection, vulnerabilities. For domains, resolves DNS first then queries the IP. Commonly invoked by /ip-investigation and /domain-investigation. Retrieval only. It is listed under Coding & Dev Tools on SkillMD.

Is Lookup Shodan safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Lookup Shodan?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Lookup Shodan free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Lookup Shodan?

Liberty91LTD (@liberty91ltd) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Lookup Shodan by liberty91ltd — Agent Skill

Name: Lookup Shodan
Author: Liberty91LTD

lookup-shodan

Queries Shodan for host reconnaissance data on IPs. For domains, resolves DNS first then queries the resolved IP. Retrieval only — do not interpret results.

When to invoke

User asks what ports/services an IP exposes
Investigation skill needs infrastructure fingerprinting
Vulnerability scan context (CVEs on exposed services)

How to invoke

Two CLIs are provided. Pick by capability needed:

Basic host lookup — Node CLI (zero deps)

node tools/clis/shodan.js ip <ip>
node tools/clis/shodan.js domain <domain>     # resolves DNS first, then queries IP

Hits the host endpoint only. Best for fast retrieval inside an investigation chain. Throttles at 1 req/sec.

Full search + DNS surface — Python CLI (uses official shodan-python SDK)

python3 tools/clis/shodan.py host <ip> [--history] [--minify]
python3 tools/clis/shodan.py search "<query>" [--limit N] [--page N] [--facets F1:N,F2:N]
python3 tools/clis/shodan.py count "<query>" [--facets F1:N,F2:N]
python3 tools/clis/shodan.py dns resolve <hostname[,hostname]>
python3 tools/clis/shodan.py dns reverse <ip[,ip]>
python3 tools/clis/shodan.py dns domain <domain>
python3 tools/clis/shodan.py info
python3 tools/clis/shodan.py ports
python3 tools/clis/shodan.py services

Self-bootstraps a private venv at tools/clis/.venv-shodan/ on first run.

Capabilities the Node CLI doesn't have, ordered by CTI value:

Search — the killer pivot. Find every host on the internet matching a banner, certificate, JARM, favicon hash, HTTP title, exposed product+version, or geolocation+org combination. This is how you go from one piece of attacker infrastructure to the rest of the cluster.
Count — get the total result count for a query without burning result credits. Use this BEFORE a search to estimate scope and avoid query-credit waste on broad queries.
Facets — group result counts by country, org, port, product, asn, tag, vuln, etc. Single call gives you the breakdown.
Domain info — subdomains + DNS records for a domain in one call.
Reverse DNS for one or many IPs.
Account info — see remaining query credits BEFORE a campaign.
History — historical banner observations on a host (paid plans).

Search query examples:

# Find all Cobalt Strike Team Servers visible to Shodan
python3 tools/clis/shodan.py search 'product:"Cobalt Strike Team Server"'

# Count C2-pattern hosts in a country before searching
python3 tools/clis/shodan.py count 'http.title:"Login Page" country:RU'

# Facet a query — what orgs / countries host this software?
python3 tools/clis/shodan.py search 'product:"Sliver" port:443' --facets org:10,country:10

# Find all hosts presenting a specific certificate CN
python3 tools/clis/shodan.py search 'ssl.cert.subject.CN:"badcorp.example"'

# Pivot by JARM fingerprint (very strong infrastructure marker)
python3 tools/clis/shodan.py search 'ssl.jarm:1234567890abcdef...'

# Vulnerable version exposed
python3 tools/clis/shodan.py search 'vuln:CVE-2024-21887'

Both CLIs accept --dry-run. Both exit code 2 if $SHODAN_API_KEY is unset (when not in dry-run). Report missing key; do not fabricate.

Credit awareness

Shodan plans have query credits (search/count/facets) and scan credits (active scans). Run python3 tools/clis/shodan.py info to check your balance before a search-heavy session. Free tier is severely limited — most CTI use needs the Membership ($49 one-time, 100 query credits/month) or a higher tier.

Response format

source: shodan
indicator: <IP or domain>
resolved_ip: <IP>    # present if input was domain
query_time: <ISO8601>
hostnames: [<list>]
org: <organisation>
isp: <ISP>
country: <country>
os: <detected OS>
open_ports: [<list>]
services:
  - port: <port>
    product: <name>
    version: <version>
    banner: <truncated>
vulnerabilities: [<CVE list>]
last_update: <date>

Rate limits

Free tier: 1 request/sec, query credits limited. Paid tiers have higher limits.

Source reliability (Admiralty default)

Default rating for downstream /score-source: B2 (usually reliable, probably true). Banner grabs are empirical but can be stale — check last_update and downgrade to C3 if >30 days old.

Related skills

/lookup-censys — alternative infrastructure scanner
/lookup-virustotal, /lookup-abuseipdb, /lookup-greynoise — reputation context for the same IP
/ip-investigation, /domain-investigation

Lookup Shodan

File contents