Advanced PHP5 REST API for Shodan.Shodan-PHP-REST-API-master.zip

# Shodan-PHP-REST-API  **Lean and easily extendible PHP API for Shodan.io, supporting both the free API and the paid one. Requests are auto-generated by structure that defines the API protocol.** ## Authors and License <p align="center"> <a href="http://www.isgroup.biz"> <img src="https://camo.githubusercontent.com/601da18d1aee75ad236b59e7e07188e5df3bb223/687474703a2f2f7777772e697367726f75702e69742f696d672f6c6f676f2d636f6c6f722e706e67"/> </a> </p> Shodan-PHP-REST-API is licensed under the GNU GPL v3 and is a project sponsored by [ISGroup SRL](http://www.isgroup.biz) and authored by [Alex Salvetti](https://github.com/alexsalvetti) and [Francesco `ascii` Ongaro](https://github.com/isgroup-srl). This software is currently used by [ScadaExposure](http://www.scadaexposure.com/), a permanent observatory on the exposure of ICS and SCADA devices on the Internet, to generate it's datasets. ## Features - Search Shodan. - Streaming API support for real-time consumption of Shodan data. - Exploit search API fully implemented. ## Notes * Shodan.php is the API class: costants, shodan methods and the generation of the HTTP requests are defined here. * The script uses PHP magic methods (http://php.net/manual/en/language.oop5.magic.php). * shodan-api.php is the CLI interface, allowing to run differents commands; it also provides an how-to function. * Our API implementation uses 3 different base URLs: Shodan API, Streaming API and Exploits API. * Tests folder provides some examples on how to write your own search query, use the CLI ```-r``` flag for running them all or call one with the ```-t``` flag. * If you're in search of better and more thorough documentation, please refer to Shodan's REST API documentation (https://developer.shodan.io/api). * For Shodan EXPLOITS API refer to the documentation (https://developer.shodan.io/api/exploits/rest). * For Shodan STREAM API refer to the documentation (https://developer.shodan.io/api/stream). ## Usage You can implement the class API directly in your code or experiment with the CLI. In both cases you'll need to change your API KEY in shodan-api.php or anywhere you istantiate the API object: https://github.com/ScadaExposure/Shodan-PHP-REST-API/blob/master/src/shodan-api.php#L7 ```php $key = 'Insert your API key here'; ``` Following are the options: | Short form | Long form | Variables | | :----------: | :---------: | --- | | -r | --run-tests | | | -t | --run-test | STRING | | -m | --method | ShodanHost --ip STRING [--history BOOLEAN] [--minify BOOLEAN] | | -m | --method | ShodanHostCount --query STRING [--facets STRING] | | -m | --method | ShodanHostSearch --query STRING [--facets STRING] | | -m | --method | ShodanHostSearchTokens --query STRING | | -m | --method | ShodanPorts | | -m | --method | ShodanProtocols | | -m | --method | ShodanScan --ips STRING | | -m | --method | ShodanScanInternet --port INTEGER --protocol STRING | | -m | --method | ShodanScan_Id --id STRING | | -m | --method | ShodanServices | | -m | --method | ShodanQuery [--page INTEGER] [--sort STRING] [--order STRING] | | -m | --method | ShodanQuerySearch --query STRING [--page INTEGER] | | -m | --method | ShodanQueryTags [--size INTEGER] | | -m | --method | LabsHoneyscore --ip STRING | | -m | --method | Search --query STRING [--facets STRING] [--page INTEGER] | | -m | --method | Count --query STRING [--facets STRING] | | -m | --method | ShodanBanners | | -m | --method | ShodanAsn --asn STRING | | -m | --method | ShodanCountries --countries STRING | | -m | --method | ShodanPorts_Stream --ports STRING | ## Some CLI Run Examples ### Showing usage options:  ### Shodan Host method on Facebook ip:  ### Shodan Scan request on some ips:  ### Shodan Scan request status:  ## Handle overlapping methods Using PHP magic methods we call the method by its name and use it for generate the URL for the request. For doing that we use ```preg_replace``` inserting a ```/``` when an uppercase character is found and appending that character in lowercase. But we found that two methods in Shodan API were overlapping with other two methods, that are: **"ShodanScan"** and **"ShodanPorts"**. So we renamed **"ShodanScan"** given with "id" parameter in **"ShodanScan_Id"**, and **"ShodanPorts"** for the stream API in **"ShodanPorts_Stream"**. But the URL must not have those renaming, so we eliminate the ```_``` and all it comes next of it for getting the job done. You can find it at: https://github.com/ScadaExposure/Shodan-PHP-REST-API/blob/master/src/Shodan.php#L471 ## Tests class - REST API ### Shodan Host (```/tests/ip.php```): Return all services that have been found on the given host IP. ```php var_dump($client->ShodanHost(array( 'ip' => '69.171.230.68', // https://www.facebook.com/ ))); ``` ### Shodan Host Count (```/tests/count.php```): Returns the total number of results that matched the query and any facet information that was requested. ```php var_dump($client->ShodanHostCount(array( 'query' => 'Niagara Web Server', ))); ``` ### Shodan Host Search (```/tests/search.php```): Search Shodan using the same query syntax as the website and use facets to get summary information for different properties. - This method may use API query credits depending on usage. ```php var_dump($client->ShodanHostSearch(array( 'query' => 'Niagara Web Server', ))); ``` ### Shodan Host Search Tokens (```/tests/search.php```): This method lets you determine which filters are being used by the query string and what parameters were provided to the filters. ```php var_dump($client->ShodanHostSearchTokens(array( 'query' => 'Niagara Web Server country:"IT"', ))); ``` ### Shodan Ports (```/tests/ports.php```): This method returns a list of port numbers that the crawlers are looking for. ```php var_dump($client->ShodanPorts()); ``` ### Shodan Protocols (```/tests/protocols.php```): This method returns an object containing all the protocols that can be used when launching an Internet scan. ```php var_dump($client->ShodanProtocols()); ``` ### Shodan Scan (```/tests/crawl.php```): Use this method to request Shodan to crawl a network. - POST METHOD REQUIRE PAID API KEY. ```php var_dump($client->ShodanScan(array( 'ips' => '69.171.230.0/24', ))); ``` ### Shodan Scan Internet (```/tests/crawl.php```): Use this method to request Shodan to crawl the Internet for a specific port. - POST METHOD REQUIRE PAID API KEY AND SHODAN PERMISSION. ```php var_dump($client->ShodanScanInternet(array( 'port' => '80', 'protocol' => 'dns-tcp', ))); ``` ### Shodan Scan Id (```/tests/crawl.php```): Check the progress of a previously submitted scan request. ```php var_dump($client->ShodanScan_Id(array( 'id' => 'R2XRT5HH6X67PFAB', ))); ``` ### Shodan Services (```/tests/crawl.php```): This method returns an object containing all the services that the Shodan crawlers look at. It can also be used as a quick and practical way to resolve a port number to the name of a service. ```php var_dump($client->ShodanServices()); ``` ### Shodan Query (```/tests/saved_query.php```): Use this method to obtain a list of search queries that users have saved in Shodan. ```php var_dump($client->ShodanQuery(array( 'page' => '1', ))); ``` ### Shodan Query (```/tests/saved_query.php```): Use this method to search the directory of search queries that users have saved in Shodan. ```php var_dump($client->ShodanQuery(array( 'query' => 'fax', ))); ``` ### Shodan Que