Skip to content

Example workflows

Prompts you can give an agent with mcp-shodan connected, and the tool calls they lead to. Use targets you are authorized to investigate.

Triage an IP from an alert

"What is exposed on 8.8.8.8? Summarize open ports, TLS certificates and anything that looks risky."

  1. ip_lookup with {"ip": "8.8.8.8"}.
  2. For any product and version in the banners, cves_by_product with {"product": "<name>", "is_kev": true, "limit": 20}.

Size up a vulnerability

"Is CVE-2021-44228 being exploited, and how bad is it?"

  1. cve_lookup with {"cve": "CVE-2021-44228"}. The KEV flag, EPSS score and proposed action answer the question.

Find the riskiest CVEs for a product

"List the 10 log4j CVEs most likely to be exploited."

  1. cpe_lookup with {"product": "log4j", "limit": 20} to pick the right CPE, if the version matters.
  2. cves_by_product with {"product": "log4j", "sort_by_epss": true, "limit": 10}, or with cpe23 set to the chosen CPE.

Map a domain's footprint

"What subdomains and mail servers does example.com have, and what's exposed on them?"

  1. domain_info with {"domain": "example.com"} (1 query credit).
  2. domain_info with {"domain": "example.com", "type": "MX"} if you only need mail servers.
  3. ip_lookup on the A records that look interesting.

Size a query before spending credits

"How many hosts are vulnerable to CVE-2021-44228, broken down by country and organization? Check my credits first."

  1. api_info to see remaining query credits.
  2. shodan_count with {"query": "vuln:CVE-2021-44228", "facets": "country:10,org:10"}. Free, no results fetched.
  3. shodan_search only if you need the hosts themselves.

Map exposure for a query

"How many nginx servers in Germany expose port 443, and which countries host the most nginx overall?"

  1. shodan_search with {"query": "product:nginx country:DE port:443", "max_results": 5}.
  2. shodan_count with {"query": "product:nginx", "facets": "country:10"}. The breakdown covers all matches and costs no credits.

Filtered searches need a Shodan membership and use one query credit each.

Pivot between names and addresses

"Resolve these domains, then tell me what else is hosted on those IPs."

  1. dns_lookup with {"hostnames": ["example.com", "example.org"]}.
  2. reverse_dns_lookup with the resulting IPs.
  3. ip_lookup on anything interesting.