# Pentest Shodan Helper

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

- Skill: `crtvrffnrt/pentest-shodan-helper` (Agent Skill)
- Install (CLI): `npx skillmds@latest add crtvrffnrt/pentest-shodan-helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crtvrffnrt/pentest-shodan-helper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: crtvrffnrt (https://skillmd.com/u/crtvrffnrt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crtvrffnrt/pentest-shodan-helper

---


# 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:

```bash
/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

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

### Organization scoping

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

### Web surface search

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

### Vulnerability-focused search

```bash
/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.