=head1 NAME

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

=head1 VERSION

Version 0.021

=cut


=head1 OVERVIEW

This module provides Perl applications with easy access to the L<Shodan API|https://developer.shodan.io/api>.

=head1 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";

=head1 GETTING STARTED

=over 2

=item * In order to use the Shodan API you need to have an API key, which can be obtained for free by creating a L<Shodan account|https://account.shodan.io/register>.

=item * Become familiar with the L<Shodan REST API Documentation|https://developer.shodan.io/api>.

=back

=head1 METHODS

=head3 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.

=head1 SHODAN SEARCH METHODS

=head3 $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]] })

B<Parameters>: Hash reference with keys:

=over 2

=item C<IP> (required): Host IP address

=item C<HISTORY> (optional): True to return all historical banners (default: false)

=item C<MINIFY> (optional): True to return only ports and general host info, no banners (default: false)

=back

=head3 $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 } )

B<Parameters>:

=over 2

=item C<$query> (required): Hash reference of search filter key/value pairs.

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

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

=back

=head3 $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 C<$shodan-E<gt>search> except C<PAGE> and C<NO_MINIFY> are not accepted.

=head3 $shodan->tokens

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

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

=head3 $shodan->search_facets

List all search facets available in Shodan.

    $shodan->search_facets

=head3 $shodan->search_filters

List all filters that can be used when searching Shodan.

    $shodan->search_filters

=head1 ON-DEMAND SCANNING METHODS

=head3 $shodan->ports

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

    $shodan->ports

=head3 $shodan->protocols

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

    $shodan->protocols

=head3 $shodan->scan

Request Shodan to crawl one or more IPs or netblocks.

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

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

=head3 $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' })

=head3 $shodan->scans

Get a list of all scans you have submitted.

    $shodan->scans

=head3 $shodan->scan_status

Get the status of a previously submitted scan request.

    $shodan->scan_status('SCAN_ID')

=head1 NETWORK ALERT METHODS

=head3 $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 })

B<Parameters>: Hash reference with keys:

=over 2

=item C<name> (required): Name of the alert.

=item C<ips> (required): Array reference of IPs or CIDR netblocks to monitor.

=item C<expires> (optional): Unix timestamp when the alert expires (0 = never).

=back

=head3 $shodan->alerts_info

Get a list of all network alerts you have created.

    $shodan->alerts_info

=head3 $shodan->alert_info

Get details for a specific network alert.

    $shodan->alert_info('ALERT_ID')

=head3 $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'] })

=head3 $shodan->delete_alert

Delete a network alert.

    $shodan->delete_alert('ALERT_ID')

=head3 $shodan->alert_triggers

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

    $shodan->alert_triggers

=head3 $shodan->enable_trigger

Enable a trigger on an alert.

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

=head3 $shodan->disable_trigger

Disable a trigger on an alert.

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

=head3 $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 C<service> value must be in C<ip:port> format.

=head3 $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' })

=head3 $shodan->add_notifier

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

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

=head3 $shodan->remove_notifier

Remove a notifier from an alert.

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

=head1 NOTIFIER METHODS

=head3 $shodan->notifiers

List all notification services you have created.

    $shodan->notifiers

=head3 $shodan->notifier_providers

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

    $shodan->notifier_providers

=head3 $shodan->notifier_info

Get information about a specific notifier.

    $shodan->notifier_info('NOTIFIER_ID')

=head3 $shodan->create_notifier

Create a new notification service.

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

=head3 $shodan->edit_notifier

Edit the destination address of an existing notifier.

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

=head3 $shodan->delete_notifier

Delete a notification service.

    $shodan->delete_notifier('NOTIFIER_ID')

=head1 DIRECTORY METHODS

=head3 $shodan->queries

List saved search queries from the Shodan community directory.

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

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

=head3 $shodan->search_queries

Search the directory of saved queries.

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

=head3 $shodan->query_tags

List the most popular tags in the saved query directory.

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

=head1 DNS METHODS

=head3 $shodan->resolve_dns

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

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

=head3 $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/ ])

=head3 $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' })

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

=head1 UTILITY METHODS

=head3 $shodan->my_ip

Get your current IP address as seen from the Internet.

    $shodan->my_ip

=head3 $shodan->http_headers

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

    $shodan->http_headers

=head3 $shodan->services

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

    $shodan->services

=head1 API STATUS METHODS

=head3 $shodan->api_info

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

    $shodan->api_info

=head1 ACCOUNT METHODS

=head3 $shodan->profile

Returns information about the account associated with the API key.

    $shodan->profile

=head1 AUTHOR

Dudley Adams, C<< <dudleyadams at gmail.com> >>

=head1 BUGS

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

=head1 SUPPORT

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

    perldoc WWW::Shodan::API

=over 4

=item * RT: CPAN's request tracker

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

=item * Search CPAN

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

=back

=head1 SOURCE CODE

L<https://github.com/Dudley5000/WWW-Shodan-API>

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

=head1 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:

L<http://www.perlfoundation.org/artistic_license_2_0>

=cut
