4 releases

0.1.1 Apr 7, 2024
0.1.0 Apr 7, 2024
0.0.2 Jan 28, 2023
0.0.1 Jan 25, 2023

#1644 in Network programming

43 downloads per month

MIT/Apache

39KB
968 lines

Shodan-rs

A shodan client written in rust (if that wasn't clear yet). This library is heavily in flux and is missing a lot of components. I suggest waiting until the API is less in flux and we've reached 1.0.0. This library builds on tokio to provide the task runtime.

API support

The official shodan API documentation can be found here. This client does not support the entire API as I only have an account with a dev plan. You can review the support table below.

Usage

First off you'll want to create a ShodanClient. This requires an API key from shodan.io. Once you're acquired your key you can spawn a client like so:

use shodan_client::*;

let client = ShodanClient::new(String::from("API-KEY-GOES-HERE"));

You can then make calls to the shodan API. As an example we can fetch our shodan account details:

use shodan_client::*; // Include the trait the adds the account functionality

let account_details = client.get_account_profile().await.unwrap();
println!("Account Details: {:?}", account_details);

Note: the unwrap() here glosses over any possible errors that might occur if something odd happens with the transport itself (ex: SSL certificate errors, a general lack of connectivity, etc), or an error response from the shodan API itself (ex: rate limiting, plan constraints or owning insufficient credits for a call).. You should be handling this properly if you don't want to your program to panic. I have omitted this for the sake of brevity.

API support

✔️ indicates full support for the endpoint. ➗ indicates partial support for the endpoint. Emptyness indicates no support yet for the endpoint.

The client currently only supports the REST API although I do want to add support for the streaming API eventually.

Realm API Verb Endpoint Support
REST Search GET /shodan/host/{ip}
REST Search GET /shodan/host/count ✔️
REST Search GET /shodan/host/search
REST Search GET /shodan/host/search/facets ✔️
REST Search GET /shodan/host/search/filters ✔️
REST Search GET /shodan/host/search/tokens
REST Scanning GET /shodan/ports ✔️
REST Scanning GET /shodan/protocols ✔️
REST Scanning POST /shodan/scan
REST Scanning POST /shodan/scan/internet
REST Scanning GET /shodan/scans
REST Scanning GET /shodan/scan/{id}
REST Alerts POST /shodan/alert
REST Alerts GET /shodan/alert/{id}/info
REST Alerts GET /shodan/alert/{id}/info
REST Alerts DELETE /shodan/alert/{id}
REST Alerts POST /shodan/alert/{id}
REST Alerts GET /shodan/alert/info
REST Alerts GET /shodan/alert/triggers
REST Alerts PUT /shodan/alert/{id}/trigger/{trigger}
REST Alerts DELETE /shodan/alert/{id}/trigger/{trigger}
REST Alerts PUT /shodan/alert/{id}/trigger/{trigger}/ignore/{service}
REST Alerts DELETE /shodan/alert/{id}/trigger/{trigger}/ignore/{service}
REST Alerts PUT /shodan/alert/{id}/notifier/{notifier_id}
REST Alerts DELETE /shodan/alert/{id}/notifier/{notifier_id}
REST Notifiers GET /notifier
REST Notifiers GET /notifier/provider
REST Notifiers POST /notifier
REST Notifiers DELETE /notifier/{id}
REST Notifiers GET /notifier/{id}
REST Notifiers PUT /notifier/{id}
REST Directory GET /shodan/query ✔️
REST Directory GET /shodan/query/search ✔️
REST Directory GET /shodan/query/tags ✔️
REST Bulk GET /shodan/data
REST Bulk GET /shodan/data/{dataset}
REST Organization GET /org
REST Organization PUT /org/member/{user}
REST Organization DELETE /org/member/{user}
REST Account GET /account/profile ✔️
REST DNS GET /dns/domain/{domain} ✔️
REST DNS GET /dns/resolve ✔️
REST DNS GET /dns/reverse ✔️
REST Utility GET /tools/httpheaders ✔️
REST Utility GET /tools/myip ✔️
REST API Status GET /api-info ✔️

Tests

The client includes a set of tests that call out to the actual shodan API (for the time being). Once it's all proven to work it makes more sense mocking the responses so that testing becomes infinitely less flaky. Until then running the tests requires a shodan API key as well. You can supply said key to the testing suite by setting the SHODAN_TEST_KEY env var. Some endpoints in the test suite do use API credits. Running the tests is not free in that sense. Another thing to note is that there are no timeouts on the tests so you'll likely run into rate limiting errors coming from the shodan API.

Example invocation

$ SHODAN_TEST_KEY=<API-KEY-GOES-HERE> cargo test

Dependencies

~6–19MB
~261K SLoC