Skip to content

Faraday

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

  1. The Faraday Platform: (either self-hosted or cloud).

  2. The Faraday Client: (faraday-cli) installed and configured to connect to your Faraday instance. You can install it via pip:

Terminal window
pip install faraday-cli
  1. Shodan API Key: You'll need a Shodan API key. You can get one by signing up on the Shodan website.

  2. Shodan command-line tool: You can install it via pip:

Terminal window
pip install shodan

Configuration

This is a one-time setup step. Run the following command and provide your key when prompted:

Terminal window
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.

Terminal window
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.8
Hostnames: dns.google
City: Mountain View
Country: United States
Organization: Google LLC
Updated: 2025-08-06T02:04:19.355139
Number 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.

Terminal window
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.net
0.freebasics.com CNAME star-bing-com.ax-0001.ax-msedge.net
0.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1000071.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1000278.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1000377.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1002643.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1004758.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
10059.r.bat CNAME star-r-bat-bing-com.dual-a-0034.a-msedge.net
1006482.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.

Terminal window
faraday-cli auth

Find all Apache servers in Germany and add them to your workspace

  1. Activate the Faraday CLI

    Terminal window
    faraday-cli
  2. Create and select the new workspace.

    Terminal window
    workspace create shodan_test
    workspace select shodan_test
  3. Run 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.

Faraday Workspace

Faraday Dashboard