Shodan Eye: keyword searches for internet-connected devices

Shodan Eye's place in keyword-based asset discovery

Shodan Eye addresses a narrow part of internet asset discovery: finding indexed devices through user-supplied keywords and collecting information returned by Shodan. Its intended users include administrators checking company or home infrastructure, security researchers working within an authorized scope, and learners exploring Shodan's service-banner index. The README gives examples that range from desktops and refrigerators to routers, webcams, servers and infrastructure associated with nuclear power plants.

The distinction from a conventional web search engine is partly technical and partly editorial. The README says Shodan indexes internet-connected devices rather than restricting discovery to documents on the World Wide Web. It also describes Shodan as a search engine for service banners, which are metadata returned by a server to a client. This makes Shodan Eye relevant when an investigator knows a product name, technology or other indexed characteristic but does not know the target address.

This is discovery, not proof that a result is owned by the searcher or permitted for testing. The README does not describe ownership validation, network-range restrictions, query quotas, result normalization or an authorization gate. Those omissions matter because a broad keyword can return devices belonging to unrelated organizations. The repository presents vulnerability research as one possible use, but Shodan Eye is not documented as a vulnerability scanner or exploitation workflow.

How Shodan Eye handles queries and credentials

The documented interaction flow begins when the script asks for a Shodan API key. The README also calls this credential a "Shodan password," so users should expect the prompt wording to differ from normal API terminology. The sole declared dependency is `shodan`, which makes it reasonable to expect that the Python client library communicates with Shodan, although the README does not describe function calls, response handling, pagination, rate limits or error recovery.

After access is established, the user enters search keywords. Based on the repository layout, `shodan-eye.py` is the application entry point and `requirements.txt` supplies its declared package dependency. The README does not expose the source, so it is not possible to confirm whether queries run interactively, how many results are requested or which Shodan endpoints are used. It is also unclear whether host details, ports, banners, locations and product metadata are normalized or saved exactly as returned.

The documented feature list says results can be saved. It does not identify the output directory, file name, format or whether raw API responses are retained. A separate file named `Shodan_Dorks_The_Internet_of_Shit.txt` contains example queries according to the README. That file is a query collection, not evidence that Shodan Eye automatically executes every query. Users should not confuse a dork file with a safe-scope list.

Installing Shodan Eye from the repository

The README documents a conventional Python setup with Git, a virtual environment and the dependency file. The documented first command clones the repository and enters its directory. A reader should see the cloned `shodan-eye` directory created and the shell's current directory changed.

git clone https://github.com/BullsEye0/shodan-eye.git
cd shodan-eye

The next documented step creates a virtual environment and activates it. The command includes the README's Windows activation alternative as a comment, but the listed repository entry point uses a hyphen rather than the underscore in the README's usage command. This should be checked before installation continues.

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

After activation, install the declared dependency from `requirements.txt`. The repository file contains `shodan`, so this step installs the dependency named there.

pip3 install -r requirements.txt

The README says Linux was tested on Kali Linux, Parrot Security OS, BlackArch, Ubuntu, Arch-based systems and Debian-based systems. It also lists Termux and Windows. That list is not a formal support matrix, and the README does not state supported Python versions. No package version is pinned in `requirements.txt`, so an exact dependency environment is not documented.

The first run and its filename mismatch

The usage section instructs the reader to start the script with `python3`. It then says that a Shodan API key will be requested. Before entering the key, the user should confirm that it belongs to an account allowed to make the queries needed by the application.

python3 shodan_eye.py

There is a concrete conflict. The top-level repository contains `shodan-eye.py`, while the README uses `shodan_eye.py` in its command. On a case-sensitive filesystem, the documented command does not match the listed file. A tutorial should not silently substitute another command because that would depart from the README. The reader must inspect the checkout and resolve the mismatch.

Once launched successfully, the README indicates that the application asks for keywords and can request an API key for additional data collection. It does not show the prompt text, interactive search loop, success output, saved-file location or noninteractive usage. The attached dork examples may provide search terms, but the README does not say how to load that file into the program. It also does not document a dry-run mode, maximum result count, filtering syntax, export flag or noninteractive automation interface.

Saved results are underspecified

Result persistence is one of two explicit features in the README, alongside hiding entry of the Shodan password. However, the documentation does not define the storage format. A user cannot determine from the README whether output is JSON, text, CSV or a direct copy of Shodan responses. There is no documented output path, overwrite rule, timestamp convention or separation between banner data and host metadata.

That limitation affects adoption more than the simple presence of a save feature. Shodan results can contain IP addresses, ports, product names, software banners, locations and other metadata associated with exposed systems. Anyone using the output for inventory needs to know whether the tool deduplicates records, preserves timestamps, records the original query or distinguishes devices from services on the same host. None of those behaviors is documented.

The README references screenshots that may illustrate the interface, but it does not transcribe their fields or filenames. They are not a substitute for output specifications. Until the source and actual generated file are inspected, the safe conclusion is that saving exists, while its format and reproducibility remain unspecified.

Shodan Eye versus direct Shodan API access

The real alternative is to use the Shodan API through its client or API workflow without the Shodan Eye wrapper. Both approaches share the same underlying source of indexed service banners and depend on a Shodan account and API key. The meaningful difference is control over the collection layer.

Shodan Eye reduces the interface to a Python program that requests a key, accepts keywords and saves results. That can be convenient for a user who wants a small command-line starting point and does not want to build query and storage logic. Its limitation is opacity. The README does not publish the supported API operations or a clear export contract.

Direct API use places more responsibility on the caller but can make query construction, response handling, pagination, rate-limit handling and data storage explicit. That makes it easier to audit exactly what is requested and retained. Shodan Eye is the better choice only when its simple keyword workflow meets the requirement and its source has been checked for the desired behavior. It is the wrong choice for an unattended asset pipeline that needs documented, reproducible output.

GPL-3.0 licensing and maintenance boundaries

The repository is licensed under `GPL-3.0`. That is relevant to an engineer planning to modify or distribute the code, but this review does not provide legal advice about a particular deployment or derivative work. The repository has no GitHub releases, so there is no published release version or formal upgrade series to use as a dependency baseline. The only declared Python package is `shodan`, with no version constraint shown in `requirements.txt`.

The repository is not archived, and its last push was on 2026-10-01. That indicates recent repository activity, but the absence of GitHub releases means release frequency and upgrade policy cannot be inferred. Operators should treat the default branch as the source of truth and record which commit they reviewed.

Adopt Shodan Eye for a small, authorized keyword collection workflow after checking `shodan-eye.py` and confirming the documented launch command. Do not adopt it as a complete exposure-management system, vulnerability scanner, ownership verifier or production integration without evidence for those functions. For this repository, the first concrete gate is simple: reconcile `shodan_eye.py` in the README with `shodan-eye.py` in the repository before treating the documented tutorial as runnable.

Editorial conclusion

Security practitioners with authorized Shodan access may adopt Shodan Eye for lightweight keyword collection, while users who need validated ownership, documented filtering or reproducible output should inspect `shodan-eye.py` first. The first verification is whether the documented `python3 shodan_eye.py` command matches the repository file named `shodan-eye.py`.

Frequently asked questions

Official sources

1. BullsEye0/shodan-eye on GitHub
2. Issues
3. License: GPL-3.0
4. README