pentest-shodan-helper

name	pentest-shodan-helper
description	Shodan CLI-only search workflow for query design, filter selection, count/stats validation, and search-result retrieval through /root/.local/bin/shodan.

Shodan CLI Search Helper

Purpose

Use this skill to build, validate, and run Shodan search queries from the command line only.

This skill is intentionally narrow:

• Use /root/.local/bin/shodan for every command.
• Use Shodan search features only.
• Do not use the web UI unless the user explicitly asks for a browser-based workflow.
• Do not pivot into unrelated Shodan commands unless they directly support search work.

Canonical References

Treat these as the source of truth for syntax, fundamentals, filters, and example queries:

• Shodan search query fundamentals
• Shodan filter reference
• Shodan search examples
• jakejarvis/awesome-shodan-queries

If the local query or filter behavior is uncertain, verify against those references before guessing.

Supported CLI Commands

Use these Shodan CLI commands for search work:

• search for interactive result retrieval
• count for quick query validation and result sizing
• stats for summary breakdowns
• download for larger result sets when search would be too small or too noisy
• parse only when you need to inspect a downloaded dataset
• trends only when the user explicitly wants historical search results

Avoid host, domain, scan, stream, alert, and other non-search commands unless the user explicitly asks for a pivot after a search lead.

Query Fundamentals

Shodan searches banner data by default.

• Plain terms search the banner data field.
• Filters use filter:value.
• Do not add spaces around the colon.
• Wrap values containing spaces in quotes.
• Combine filters to narrow results.
• Start broad, then tighten.

Examples:

/root/.local/bin/shodan count nginx
/root/.local/bin/shodan count org:"Example Corp" country:DE
/root/.local/bin/shodan search port:443 ssl

Recommended Search Workflow

1. Convert the user request into a precise Shodan hypothesis.
2. Pick the smallest set of filters that express that hypothesis.
3. Run count first when the query may be broad or expensive.
4. Run search once the query shape is sane.
5. Use stats when the user needs a distribution or summary.
6. Use download when the result set is large enough that interactive search is inefficient.
7. Use parse only after a download if the user needs structured inspection.

Filter Selection Rules

Prefer exact, high-signal filters over vague banner text.

Core filter families to reach for first:

• Scope and ownership: asn, org, isp, net, country, city, region, hostname, ip
• Service and port: port, product, version, os, tag
• Web and HTTP: http.title, http.server, http.html, http.component, http.status
• TLS and certs: ssl, ssl.cert.subject.cn, ssl.cert.issuer.cn, ssl.cert.fingerprint, ssl.version
• SSH and remote access: ssh, rdp, vnc, ftp, smtp, imap, pop3
• Exposure and weakness: vuln, cpe, cve
• Time and recency: before, after
• Structural narrowing: has_screenshot, has_ssl, has_ipv6

Use the official filter reference for the full canonical list and edge-case syntax.

Query Construction Tips

• Keep the first query minimal.
• Use org: and country: early when scoping to a target network.
• Use port: and product: when you know the service family.
• Use quoted strings for organizations, titles, and banner fragments.
• Prefer count before broad searches to avoid noisy result pulls.
• When you need ideas, mine awesome-shodan-queries for search patterns, then simplify them to the minimum useful filter set.

Practical Patterns

Service discovery

/root/.local/bin/shodan count port:22
/root/.local/bin/shodan search port:22 product:OpenSSH

Organization scoping

/root/.local/bin/shodan count org:"Example Corp" country:US
/root/.local/bin/shodan search org:"Example Corp" port:443

Web surface search

/root/.local/bin/shodan search http.title:"login"
/root/.local/bin/shodan search http.component:wordpress

Vulnerability-focused search

/root/.local/bin/shodan count vuln:CVE-2021-41773
/root/.local/bin/shodan search cve:CVE-2021-41773

Output Discipline

• Return the exact command used when it matters.
• Summarize what the query matched and why it is relevant.
• If the result set is too broad, explain which filter should be tightened next.
• If the query is invalid or the CLI rejects it, restate the syntax issue and correct the query.

Guardrails

• Do not invent filters.
• Do not claim a filter works unless it is supported by the official references or already validated locally.
• Do not use the browser UI as a fallback for search.
• Do not expand into host lookups, scans, or streaming unless the user explicitly changes the task.