NAME

WWW::Shodan::API - Interface for the Shodan Computer Search Engine API

VERSION

Version 0.021

OVERVIEW

This module provides Perl applications with easy access to the Shodan API.

SYNOPSIS

use WWW::Shodan::API;
use Data::Dumper;

use constant APIKEY => '7hI5i5n07@re@L@Pik3Yd0n7b3@dumMY';

my $shodan = WWW::Shodan::API->new( APIKEY );

print Dumper $shodan->api_info;
print Dumper $shodan->profile;
print Dumper $shodan->host_ip({ IP => '8.8.8.8' });

# Search
my $results = $shodan->search({ port => 80, product => 'Apache' }, ['org', 'country'], {});
print Dumper $results;

# Alerts
my $alert = $shodan->create_alert({ name => 'My Network', ips => ['1.2.3.0/24'] });
print "Alert ID: $alert->{id}\n";

GETTING STARTED

• In order to use the Shodan API you need to have an API key, which can be obtained for free by creating a Shodan account.

• Become familiar with the Shodan REST API Documentation.

METHODS

new

Constructor - Creates a new WWW::Shodan::API object.

my $shodan = WWW::Shodan::API->new($apikey);

Takes a Shodan API key as its only argument.

SHODAN SEARCH METHODS

$shodan->host_ip

Host Information - Returns all services that have been found on the given host IP.

$shodan->host_ip({ IP => '12.34.56.78' [, HISTORY => 1 [, MINIFY => 1]] })

Parameters: Hash reference with keys:

IP (required): Host IP address

HISTORY (optional): True to return all historical banners (default: false)

MINIFY (optional): True to return only ports and general host info, no banners (default: false)

$shodan->search

Search Shodan using the same query syntax as the website. May consume query credits.

my $query  = { product => 'Apache', port => 80, country => 'US' };
my $facets = [ { isp => 3 }, { os => 2 }, 'version' ];
$shodan->search( $query, $facets, { PAGE => 2 } )

Parameters:

$query (required): Hash reference of search filter key/value pairs.

$facets (optional): Array reference of facets. Each element is either a string (e.g. 'org') or a hash ref specifying a count limit (e.g. { os => 5 }).

$args (optional): Hash reference with optional keys PAGE (page number, default 1) and NO_MINIFY (if set, larger fields are not truncated).

$shodan->count

Search Shodan without returning results - returns only the total count and facet data. Does not consume query credits.

$shodan->count( $query, $facets )

Arguments are identical to $shodan->search except PAGE and NO_MINIFY are not accepted.

$shodan->tokens

Break a search query string into its component tokens and filters.

$shodan->tokens({ product => 'Apache', port => 80 })

$shodan->search_facets

List all search facets available in Shodan.

$shodan->search_facets

$shodan->search_filters

List all filters that can be used when searching Shodan.

$shodan->search_filters

ON-DEMAND SCANNING METHODS

$shodan->ports

List all ports that Shodan is currently crawling on the Internet.

$shodan->ports

$shodan->protocols

List all protocols that can be used for on-demand Internet scans.

$shodan->protocols

$shodan->scan

Request Shodan to crawl one or more IPs or netblocks.

$shodan->scan([ '1.2.3.4', '5.6.7.0/24' ])

Parameters: Array reference of IP addresses and/or CIDR netblocks.

$shodan->scan_internet

Crawl the entire Internet for a specific port and protocol. Requires an academic or enterprise API plan.

$shodan->scan_internet({ port => 80, protocol => 'http' })

$shodan->scans

Get a list of all scans you have submitted.

$shodan->scans

$shodan->scan_status

Get the status of a previously submitted scan request.

$shodan->scan_status('SCAN_ID')

NETWORK ALERT METHODS

$shodan->create_alert

Create a network alert to monitor a set of IPs or netblocks.

$shodan->create_alert({ name => 'My Network', ips => ['1.2.3.0/24'], expires => 0 })

Parameters: Hash reference with keys:

name (required): Name of the alert.

ips (required): Array reference of IPs or CIDR netblocks to monitor.

expires (optional): Unix timestamp when the alert expires (0 = never).

$shodan->alerts_info

Get a list of all network alerts you have created.

$shodan->alerts_info

$shodan->alert_info

Get details for a specific network alert.

$shodan->alert_info('ALERT_ID')

$shodan->edit_alert

Edit the networks monitored by an existing alert.

$shodan->edit_alert({ id => 'ALERT_ID', ips => ['1.2.3.0/24', '5.6.7.0/24'] })

$shodan->delete_alert

Delete a network alert.

$shodan->delete_alert('ALERT_ID')

$shodan->alert_triggers

Get a list of available triggers that can be attached to alerts.

$shodan->alert_triggers

$shodan->enable_trigger

Enable a trigger on an alert.

$shodan->enable_trigger({ id => 'ALERT_ID', trigger => 'malware' })

$shodan->disable_trigger

Disable a trigger on an alert.

$shodan->disable_trigger({ id => 'ALERT_ID', trigger => 'malware' })

$shodan->add_whitelist

Add an IP/port service to the whitelist for a trigger (so it doesn't generate notifications).

$shodan->add_whitelist({ id => 'ALERT_ID', trigger => 'malware', service => '1.2.3.4:80' })

The service value must be in ip:port format.

$shodan->remove_whitelist

Remove a service from a trigger's whitelist.

$shodan->remove_whitelist({ id => 'ALERT_ID', trigger => 'malware', service => '1.2.3.4:80' })

$shodan->add_notifier

Attach a notifier to an alert so it receives trigger notifications.

$shodan->add_notifier({ id => 'ALERT_ID', notifier_id => 'NOTIFIER_ID' })

$shodan->remove_notifier

Remove a notifier from an alert.

$shodan->remove_notifier({ id => 'ALERT_ID', notifier_id => 'NOTIFIER_ID' })

NOTIFIER METHODS

$shodan->notifiers

List all notification services you have created.

$shodan->notifiers

$shodan->notifier_providers

List all available notification providers (e.g. email, Slack).

$shodan->notifier_providers

$shodan->notifier_info

Get information about a specific notifier.

$shodan->notifier_info('NOTIFIER_ID')

$shodan->create_notifier

Create a new notification service.

$shodan->create_notifier({
    provider    => 'email',
    description => 'My alert emails',
    to          => 'me@example.com',
})

$shodan->edit_notifier

Edit the destination address of an existing notifier.

$shodan->edit_notifier({ id => 'NOTIFIER_ID', to => 'new@example.com' })

$shodan->delete_notifier

Delete a notification service.

$shodan->delete_notifier('NOTIFIER_ID')

DIRECTORY METHODS

$shodan->queries

List saved search queries from the Shodan community directory.

$shodan->queries
$shodan->queries({ page => 1, sort => 'votes', order => 'desc' })

Optional parameters: page (default 1), sort ('votes' or 'timestamp'), order ('asc' or 'desc').

$shodan->search_queries

Search the directory of saved queries.

$shodan->search_queries({ query => 'apache' })
$shodan->search_queries({ query => 'apache', page => 2 })

$shodan->query_tags

List the most popular tags in the saved query directory.

$shodan->query_tags
$shodan->query_tags({ size => 10 })

DNS METHODS

$shodan->resolve_dns

DNS Lookup - Look up the IP address for the provided list of hostnames.

$shodan->resolve_dns([ qw/google.com bing.com/ ])

$shodan->reverse_dns

Reverse DNS Lookup - Look up the hostnames defined for the given list of IP addresses.

$shodan->reverse_dns([ qw/74.125.227.230 204.79.197.200/ ])

$shodan->domain_info

Get all DNS entries and subdomains for a domain. Accepts either a plain domain string or a hash reference for optional parameters.

$shodan->domain_info('google.com')
$shodan->domain_info({ domain => 'google.com', history => 1, type => 'A' })

Optional parameters: history (include historical DNS data), type (DNS record type filter, e.g. 'A', 'MX').

UTILITY METHODS

$shodan->my_ip

Get your current IP address as seen from the Internet.

$shodan->my_ip

$shodan->http_headers

View the HTTP headers that your client sends when connecting to a web server.

$shodan->http_headers

$shodan->services

List all services and their port numbers that Shodan recognises. Returns a hash of port => service-name mappings.

$shodan->services

API STATUS METHODS

$shodan->api_info

Returns information about the API plan belonging to the given API key.

$shodan->api_info

ACCOUNT METHODS

$shodan->profile

Returns information about the account associated with the API key.

$shodan->profile

AUTHOR

Dudley Adams, <dudleyadams at gmail.com>

BUGS

Please report any bugs or feature requests to bug-www-shodan-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Shodan-API.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::Shodan::API

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Shodan-API

• Search CPAN

  http://search.cpan.org/dist/WWW-Shodan-API/

SOURCE CODE

https://github.com/Dudley5000/WWW-Shodan-API

git clone https://github.com/Dudley5000/WWW-Shodan-API.git

LICENSE AND COPYRIGHT

Copyright 2014 Dudley Adams.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0