### Install or Upgrade Shodan Python Library

Source: https://github.com/achillean/shodan-python/blob/master/docs/tutorial.rst

Instructions for installing the Shodan Python library using easy_install. The second command shows how to upgrade an existing installation to the latest version, ensuring backwards-compatibility.

```bash
$ easy_install shodan
```

```bash
$ easy_install -U shodan
```

--------------------------------

### Install Shodan Python Library via Package Managers

Source: https://github.com/achillean/shodan-python/blob/master/README.rst

These commands demonstrate how to install the official Shodan Python library using common Python package managers. The first example uses `pip`, the recommended tool, while the second provides an alternative using `easy_install`.

```bash
$ pip install shodan
```

```bash
$ easy_install shodan
```

--------------------------------

### Shodan.search Method Return Structure Example

Source: https://github.com/achillean/shodan-python/blob/master/docs/tutorial.rst

An example of the dictionary structure returned by the 'Shodan.search' method. It includes the total number of results and a list of 'matches', each containing detailed information about a host such as IP, hostnames, OS, port, and banner data.

```APIDOC
{
	'total': 8669969,
	'matches': [
		{
			'data': 'HTTP/1.0 200 OK\r\nDate: Mon, 08 Nov 2010 05:09:59 GMT\r\nSer...',
			'hostnames': ['pl4t1n.de'],
			'ip': 3579573318,
			'ip_str': '89.110.147.239',
			'os': 'FreeBSD 4.4',
			'port': 80,
			'timestamp': '2014-01-15T05:49:56.283713'
		},
		...
	]
}
```

--------------------------------

### Initialize Shodan API Object in Python

Source: https://github.com/achillean/shodan-python/blob/master/docs/tutorial.rst

This snippet demonstrates how to import the Shodan library and initialize the API object. Users must replace 'insert your API key here' with their actual Shodan API key obtained from the Shodan account page.

```python
import shodan

SHODAN_API_KEY = "insert your API key here"

api = shodan.Shodan(SHODAN_API_KEY)
```

--------------------------------

### Initialize Shodan API and Perform Basic Searches in Python

Source: https://github.com/achillean/shodan-python/blob/master/README.rst

This Python snippet demonstrates how to set up the Shodan API client using your API key. It includes examples for looking up IP information, iterating through search results for specific website titles, and counting services based on tags, providing a quick start to Shodan API interactions.

```python
from shodan import Shodan

api = Shodan('MY API KEY')

# Lookup an IP
ipinfo = api.host('8.8.8.8')
print(ipinfo)

# Search for websites that have been "hacked"
for banner in api.search_cursor('http.title:"hacked by"'):
    print(banner)

# Get the total number of industrial control systems services on the Internet
ics_services = api.count('tag:ics')
print('Industrial Control Systems: {}'.format(ics_services['total']))
```

--------------------------------

### Perform a Search on Shodan using Python

Source: https://github.com/achillean/shodan-python/blob/master/docs/tutorial.rst

This code shows how to use the 'api.search' method to query Shodan for specific terms, such as 'apache'. It includes error handling for API exceptions and iterates through the results to print the IP address and banner data for each match.

```python
# Wrap the request in a try/ except block to catch errors
try:
	# Search Shodan
	results = api.search('apache')
	
	# Show the results
	print('Results found: {}'.format(results['total']))
	for result in results['matches']:
		print('IP: {}'.format(result['ip_str']))
		print(result['data'])
		print('')
except shodan.APIError as e:
	print('Error: {}'.format(e))
```

--------------------------------

### Look Up Host Information by IP in Python

Source: https://github.com/achillean/shodan-python/blob/master/docs/tutorial.rst

This snippet demonstrates how to use the 'api.host' function to retrieve comprehensive information about a specific IP address. It prints general details like organization and operating system, and then iterates through the host's data to display port and banner information.

```python
# Lookup the host
host = api.host('217.140.75.46')

# Print general info
print("""
		IP: {}
		Organization: {}
		Operating System: {}
	""".format(host['ip_str'], host.get('org', 'n/a'), host.get('os', 'n/a')))

# Print all banners
for item in host['data']:
	print("""
		Port: {}
		Banner: {}
		
	""".format(item['port'], item['data']))
```

--------------------------------

### Python Shodan Facet Count Example

Source: https://github.com/achillean/shodan-python/blob/master/docs/examples/query-summary.rst

This Python script demonstrates how to use the `shodan.Shodan.count()` method to search Shodan and retrieve aggregated summary information (facets) instead of individual host results. It configures a list of facets (organization, domain, port, ASN, and country with a limit of 3) and then processes the command-line arguments as a search query. The script prints the total results and then iterates through the returned facets, displaying the top terms and their counts for each category. This method is faster and does not require a paid API plan, making it ideal for statistical analysis. Sample output is included to illustrate the format of the summary information.

```python
#!/usr/bin/env python
#
# query-summary.py
# Search Shodan and print summary information for the query.
#
# Author: achillean

import shodan
import sys

# Configuration
API_KEY = 'YOUR API KEY'

# The list of properties we want summary information on
FACETS = [
    'org',
    'domain',
    'port',
    'asn',

    # We only care about the top 3 countries, this is how we let Shodan know to return 3 instead of the
    # default 5 for a facet. If you want to see more than 5, you could do ('country', 1000) for example
    # to see the top 1,000 countries for a search query.
    ('country', 3),
]

FACET_TITLES = {
    'org': 'Top 5 Organizations',
    'domain': 'Top 5 Domains',
    'port': 'Top 5 Ports',
    'asn': 'Top 5 Autonomous Systems',
    'country': 'Top 3 Countries',
}

# Input validation
if len(sys.argv) == 1:
    print('Usage: %s <search query>' % sys.argv[0])
    sys.exit(1)

try:
    # Setup the api
    api = shodan.Shodan(API_KEY)

    # Generate a query string out of the command-line arguments
    query = ' '.join(sys.argv[1:])

    # Use the count() method because it doesn't return results and doesn't require a paid API plan
    # And it also runs faster than doing a search().
    result = api.count(query, facets=FACETS)
    
    print('Shodan Summary Information')
    print('Query: %s' % query)
    print('Total Results: %s\n' % result['total'])
    
    # Print the summary info from the facets
    for facet in result['facets']:
        print(FACET_TITLES[facet])
        
        for term in result['facets'][facet]:
            print('%s: %s' % (term['value'], term['count']))

        # Print an empty line between summary info
        print('')
    
except Exception as e:
    print('Error: %s' % e)
    sys.exit(1)

"""
Sample Output
=============

./query-summary.py apache
Shodan Summary Information
Query: apache
Total Results: 34612043

Top 5 Organizations
Amazon.com: 808061
Ecommerce Corporation: 788704
Verio Web Hosting: 760112
Unified Layer: 627827
GoDaddy.com, LLC: 567004

Top 5 Domains
secureserver.net: 562047
unifiedlayer.com: 494399
t-ipconnect.de: 385792
netart.pl: 194817
wanadoo.fr: 151925

Top 5 Ports
80: 24118703
443: 8330932
8080: 1479050
81: 359025
8443: 231441

Top 5 Autonomous Systems
as32392: 580002
as2914: 465786
as26496: 414998
as48030: 332000
as8560: 255774

Top 3 Countries
US: 13227366
DE: 2900530
JP: 2014506
"""

```

--------------------------------

### Install ImageMagick for GIF Creation

Source: https://github.com/achillean/shodan-python/blob/master/docs/examples/gifcreator.rst

This command installs the ImageMagick software package, which provides the 'convert' utility essential for merging multiple images into an animated GIF. It is a prerequisite for the Python GIF creator script.

```bash
sudo apt-get install imagemagick
```

--------------------------------

### Search Shodan and Print IPs (Python)

Source: https://github.com/achillean/shodan-python/blob/master/docs/examples/basic-search.rst

This Python script uses the Shodan API to perform a search based on a command-line query. It initializes the API with a provided key, executes the search, and then iterates through the results to print the IP address of each matching service. It includes basic error handling and input validation.

```python
#!/usr/bin/env python
#
# shodan_ips.py
# Search SHODAN and print a list of IPs matching the query
#
# Author: achillean

import shodan
import sys

# Configuration
API_KEY = "YOUR_API_KEY"

# Input validation
if len(sys.argv) == 1:
	print 'Usage: %s <search query>' % sys.argv[0]
	sys.exit(1)

try:
	# Setup the api
	api = shodan.Shodan(API_KEY)

	# Perform the search
	query = ' '.join(sys.argv[1:])
	result = api.search(query)
	
	# Loop through the matches and print each IP
	for service in result['matches']:
		print service['ip_str']
except Exception as e:
	print 'Error: %s' % e
	sys.exit(1)
```

--------------------------------

### Stream SSL Certificates with Shodan Streaming API (Python)

Source: https://github.com/achillean/shodan-python/blob/master/docs/examples/cert-stream.rst

This Python script demonstrates how to connect to the Shodan Streaming API to receive real-time SSL certificate data. It requires a Shodan API key and a subscription API plan. The script listens for data on specified ports (443, 8443) and prints the 'ssl' field from banners containing SSL information. By default, the Streaming API returns only 1% of the data.

```python
#!/usr/bin/env python
#
# cert-stream.py
# Stream the SSL certificates that Shodan is collecting at the moment
#
# WARNING: This script only works with people that have a subscription API plan!
# And by default the Streaming API only returns 1% of the data that Shodan gathers.
# If you wish to have more access please contact us at sales@shodan.io for pricing
# information.
#
# Author: achillean
import shodan
import sys

# Configuration
API_KEY = 'YOUR API KEY'

try:
    # Setup the api
    api = shodan.Shodan(API_KEY)

    print('Listening for certs...')
    for banner in api.stream.ports([443, 8443]):
	if 'ssl' in banner:
		# Print out all the SSL information that Shodan has collected
		print(banner['ssl'])
    
except Exception as e:
    print('Error: {}'.format(e))
    sys.exit(1)
```

--------------------------------

### Python Script to Generate GIFs from Shodan Screenshots

Source: https://github.com/achillean/shodan-python/blob/master/docs/examples/gifcreator.rst

This Python script processes a Shodan data file (json.gz) containing historical IP information, extracts screenshots, and generates animated GIFs. It requires 'arrow' and 'shodan' Python packages, and the 'ImageMagick' software. The script utilizes `shodan.helpers.iterate_files()` to parse data and the `shodan.Shodan.host` method with the `history` flag to retrieve all banners for an IP. GIFs are saved in a 'data' directory, and temporary image files are cleaned up.

```python
#!/usr/bin/env python
# gifcreator.py
#
# Dependencies:
# - arrow
# - shodan
#
# Installation:
# sudo easy_install arrow shodan
# sudo apt-get install imagemagick
#
# Usage:
# 1. Download a json.gz file using the website or the Shodan command-line tool (https://cli.shodan.io).
#    For example:
#        shodan download screenshots.json.gz has_screenshot:true
# 2. Run the tool on the file:
#        python gifcreator.py screenshots.json.gz

import arrow
import os
import shodan
import shodan.helpers as helpers
import sys


# Settings
API_KEY = ''
MIN_SCREENS = 5	# Number of screenshots that Shodan needs to have in order to make a GIF
MAX_SCREENS = 24

if len(sys.argv) != 2:
	print('Usage: {} <shodan-data.json.gz>'.format(sys.argv[0]))
	sys.exit(1)

# GIFs are stored in the local "data" directory
os.mkdir('data')

# We need to connect to the API to lookup the historical host information
api = shodan.Shodan(API_KEY)

# Use the shodan.helpers.iterate_files() method to loop over the Shodan data file
for result in helpers.iterate_files(sys.argv[1]):
	# Get the historic info
	host = api.host(result['ip_str'], history=True)
	
	# Count how many screenshots this host has
	screenshots = []
	for banner in host['data']:
		# Extract the image from the banner data
		if 'opts' in banner and 'screenshot' in banner['opts']:
			# Sort the images by the time they were collected so the GIF will loop
			# based on the local time regardless of which day the banner was taken.
			timestamp = arrow.get(banner['timestamp']).time()
			sort_key = timestamp.hour
			screenshots.append((
				sort_key,
				banner['opts']['screenshot']['data']
			))
				
			# Ignore any further screenshots if we already have MAX_SCREENS number of images
			if len(screenshots) >= MAX_SCREENS:
				break
		
	# Extract the screenshots and turn them into a GIF if we've got the necessary
	# amount of images.
	if len(screenshots) >= MIN_SCREENS:
		for (i, screenshot) in enumerate(sorted(screenshots, key=lambda x: x[0], reverse=True)):
			open('/tmp/gif-image-{}.jpg'.format(i), 'w').write(screenshot[1].decode('base64'))
			
		# Create the actual GIF using the  ImageMagick "convert" command
		os.system('convert -layers OptimizePlus -delay 5x10 /tmp/gif-image-*.jpg -loop 0 +dither -colors 256 -depth 8 data/{}.gif'.format(result['ip_str']))
	
		# Clean up the temporary files
		os.system('rm -f /tmp/gif-image-*.jpg')
	
		# Show a progress indicator
		print(result['ip_str'])
```

--------------------------------

### Python Project Requirements (requirements.txt)

Source: https://github.com/achillean/shodan-python/blob/master/requirements.txt

This snippet details the Python packages and their versions required for the project. It includes standard libraries, version-locked dependencies (e.g., requests>=2.2.1), and conditional dependencies (e.g., ipaddress for Python 2.7 or older).

```pip requirements
click
click-plugins
colorama
requests>=2.2.1
XlsxWriter
ipaddress;python_version<='2.7'
tldextract
```

--------------------------------

### Shodan Python Library API Reference

Source: https://github.com/achillean/shodan-python/blob/master/docs/api.rst

Defines the core classes and exceptions available in the 'shodan' Python module, including the main Shodan client, its nested Exploits and Stream classes, and the APIError exception.

```APIDOC
Module: shodan
  Class: Shodan
    Inherited Members: Yes
    Nested Class: shodan.Shodan.Exploits
      Inherited Members: Yes
    Nested Class: shodan.Shodan.Stream
      Inherited Members: Yes
  Exception: shodan.APIError
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.