Name: Lookup Shodan
Availability: InStock
Author: Liberty91LTD

Install

$ agentstack add skill-liberty91ltd-cti-skills-lookup-shodan

✓ scanned · ✓ verified — works with Claude Code, Cursor, and more.

Security review

✓ Passed

No issues found. Passed automated security review. · v0.1.0 How review works →

✓ Prompt-injection patterns
✓ Secret / credential exfiltration
✓ Dangerous shell & filesystem operations
✓ Untrusted network calls
✓ Known-malicious package signatures

What it can access

✓ Network access No
✓ Filesystem access No
✓ Shell / process execution No
✓ Environment & secrets No
✓ Dynamic code execution No

From automated source analysis of v0.1.0. “Used” means the capability is present in the source — more access means more to trust, not that it’s unsafe.

About

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 
node tools/clis/shodan.js 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  [--history] [--minify]
python3 tools/clis/shodan.py search "" [--limit N] [--page N] [--facets F1:N,F2:N]
python3 tools/clis/shodan.py count "" [--facets F1:N,F2:N]
python3 tools/clis/shodan.py dns resolve 
python3 tools/clis/shodan.py dns reverse 
python3 tools/clis/shodan.py dns 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: 
resolved_ip:     # present if input was domain
query_time: 
hostnames: []
org: 
isp: 
country: 
os: 
open_ports: []
services:
  - port: 
    product: 
    version: 
    banner: 
vulnerabilities: []
last_update:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

Author: Liberty91LTD
Source: Liberty91LTD/cti-skills
License: MIT
Homepage: https://liberty91.com/cti-skills

Install and usage instructions live in the source repository linked above.

Reviews

No reviews yet — be the first.

Write a review

Versions

v0.1.0 Imported from the upstream source.

Lookup Shodan