Introduction
This guide explains how to integrate and use the Shodan command-line tool within the Faraday Security Platform to discover and import internet-connected assets.
Prerequisites
The Faraday Platform: (either self-hosted or cloud).
The Faraday Client: (
faraday-cli
) installed and configured to connect to your Faraday instance. You can install it via pip:
pip install faraday-cli
Shodan API Key: You'll need a Shodan API key. You can get one by signing up on the Shodan website.
Shodan command-line tool: You can install it via pip:
pip install shodan
Configuration
This is a one-time setup step. Run the following command and provide your key when prompted:
faraday-cli shodan init YOUR_API_KEY
Replace YOUR_API_KEY
with the key from your Shodan account dashboard. The CLI will store the key for all subsequent commands.
Running Shodan Requests in Faraday Client
Querying a Single Host
To get all available information for a specific IP address and import it into Faraday, use the shodan host
command.
faraday-cli shodan host 8.8.8.8
Faraday will create a Host for 8.8.8.8 and add associated services (open ports) and banners returned by Shodan.
8.8.8.8Hostnames: dns.googleCity: Mountain ViewCountry: United StatesOrganization: Google LLCUpdated: 2025-08-06T02:04:19.355139Number of open ports: 2
Ports: 53/tcp 53/udp 443/tcp |-- HTTP title: Google Public DNS |-- Cert Issuer: C=US, CN=WR2, O=Google Trust Services |-- Cert Subject: CN=dns.google |-- SSL Versions: -SSLv2, -SSLv3, -TLSv1, -TLSv1.1, TLSv1.2, TLSv1.3
Querying a Domain
To discover all subdomains, associated IP addresses, and open ports for a specific domain, use the shodan domain
command.
faraday-cli shodan domain bing.com
Faraday's plugin will parse the output, creating multiple Host entities for each IP address discovered for bing.com
and its subdomains.
BING.COM
A 150.171.27.10 A 150.171.28.10 AAAA 2620:1ec:33:1::10 AAAA 2620:1ec:33::10* CNAME star-bing-com.ax-0001.ax-msedge.net0.freebasics.com CNAME star-bing-com.ax-0001.ax-msedge.net0.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1000071.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1000278.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1000377.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1002643.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1004758.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net10059.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net1006482.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
Sending Shodan Search to Faraday Workspace
Before running any commands that interact with your workspaces, you must log in to your Faraday server. This action saves a session token on your machine, so you don't have to enter your credentials for every command.
faraday-cli auth
Find all Apache servers in Germany and add them to your workspace
Activate the Faraday CLI
Terminal window faraday-cliCreate and select the new workspace.
Terminal window workspace create shodan_testworkspace select shodan_testRun the Shodan search.
Terminal window shodan search "apache country:DE" --limit 100
After running the shodan search
, the generated report is automatically sent to your Faraday workspace. You can then access and view the detailed findings directly from the Faraday platform's graphical user interface (GUI). This allows you to centralize and analyze the Shodan data alongside other security assessment results within a single, unified environment.