An async-first Python library and CLI for the Shodan search engine.
Based on the original shodan-python
library by John Matherly (jmath@shodan.io) and all
its contributors,
released under the MIT License.
This fork adds a fully async API layer built on aiohttp.
Shodan is a search engine for Internet-connected devices. This library gives developers non-blocking access to all of the data stored in Shodan so they can automate tasks and integrate into modern async Python applications.
- Fully async REST and Streaming APIs via
AsyncShodan/AsyncStream(Python 3.8+, powered byaiohttp) - Search Shodan
- Fast / bulk IP lookups
- Streaming API support for real-time banner consumption (
async for) - Network alerts / private firehose
- Manage email notifications
- Exploit search and bulk data downloads
- Shodan DNS DB — domain information lookup
- Trends historical search
- Command-line interface (backed by the async client via
asyncio.run())
Grab your API key from https://account.shodan.io
$ pip install shodanimport asyncio
from shodan import AsyncShodan
async def main():
async with AsyncShodan('MY_API_KEY') as api:
# API plan information
info = await api.info()
print(info)
# Single IP lookup
host = await api.host('8.8.8.8')
print(host['ip_str'], host.get('org', 'n/a'))
# Count results
result = await api.count('tag:ics')
print('ICS devices:', result['total'])
# Iterate over all results with the async cursor
async for banner in api.search_cursor('apache'):
print(banner['ip_str'])
# Real-time banner stream (stops after 30 seconds)
async for banner in api.stream.banners(timeout=30):
print(banner)
asyncio.run(main())import asyncio
from shodan import AsyncShodan
async def main():
ips = ['8.8.8.8', '1.1.1.1', '9.9.9.9']
async with AsyncShodan('MY_API_KEY') as api:
results = await asyncio.gather(*[api.host(ip) for ip in ips])
for r in results:
print(r['ip_str'], r.get('org', 'n/a'))
asyncio.run(main())All stream methods are async generators — consume them with async for:
from shodan import AsyncShodan
async def main():
async with AsyncShodan('MY_API_KEY') as api:
# All banners
async for banner in api.stream.banners():
print(banner)
# Filtered by port
async for banner in api.stream.ports([22, 80, 443]):
print(banner)
# Filtered by country
async for banner in api.stream.countries(['US', 'DE']):
print(banner)
# Filtered by ASN
async for banner in api.stream.asn(['AS15169']):
print(banner)
# Custom filter query
async for banner in api.stream.custom('port:8080 country:US'):
print(banner)
# Network alert (private firehose)
async for banner in api.stream.alert(aid='MY_ALERT_ID'):
print(banner)Use the async context manager to ensure the HTTP session is properly closed:
async with AsyncShodan('MY_API_KEY') as api:
result = await api.search('nginx')Or close manually when the context manager is not convenient:
api = AsyncShodan('MY_API_KEY')
try:
result = await api.search('nginx')
finally:
await api.aclose()Python 3.8 or newer is required. aiohttp >= 3.9.0 is used for all
HTTP and streaming communication.
$ pip install shodanOr from source:
$ git clone https://github.com/achillean/shodan-python
$ cd shodan-python
$ pip install -e .This library follows OWASP best practices:
- All communication uses HTTPS exclusively; plain-HTTP base-URL overrides
via
SHODAN_API_URLare rejected at startup (OWASP A02). - API keys are never included in
__repr__output or exception messages to prevent accidental exposure in logs and tracebacks (OWASP A02 / A09). - URL path parameters are validated to reject null bytes and newline characters, guarding against null-byte and HTTP header injection (OWASP A03).
aiohttpperforms TLS certificate verification by default.
- Official Shodan API reference: https://developer.shodan.io/api
- Shodan help centre: https://help.shodan.io
- ReadTheDocs: https://shodan.readthedocs.org/
This project is a fork of shodan-python, the official Shodan Python library originally created and maintained by John Matherly (Shodan founder, jmath@shodan.io) and the contributor community.
The original library is copyright (c) 2014- John Matherly and is released under the MIT License.
This async fork retains all original functionality and replaces the
requests-based implementation with a fully non-blocking AsyncShodan /
AsyncStream API layer built on aiohttp.
