Hermes Plugin Shodan: security tool for Hermes Agent

Shodan host intel, search, DNS and CVE lookups for Hermes Agent, with credit budgeting

What Hermes Plugin Shodan does

Hermes Plugin Shodan connects Hermes Agent to Shodan.io with twelve tools, three skills, a CLI and a slash command, and it touches nothing in Hermes core. Host lookups use Shodan's InternetDB and vulnerability lookups use CVEDB, so both work without an API key. Adding a key enables search, DNS domain enumeration, alerts and the remaining features.

The design targets two problems. Raw Shodan host responses can run to hundreds of kilobytes, so the plugin shapes them for the model; the README's example for 1.1.1.1 shrinks 225,130 characters to a 4,321-character summary or a 13,379-character detail view. The second problem is credit spend, since Membership accounts get 100 query credits a month, so the plugin includes credit budgeting, and count queries cost no query credits. Once installed, the tools appear in the desktop app, CLI, TUI, gateway, ACP and cron.

Key features

Twelve tools, three skills, a CLI and a slash command
Keyless host intel through InternetDB and vulnerability data through CVEDB
Search, DNS domain enumeration and alerts when a SHODAN_API_KEY is set
Response shaping that cuts a 1.1.1.1 lookup from 225,130 to 4,321 characters
Credit budgeting, with count queries that use no query credits
Tools available in the desktop app, CLI, TUI, gateway, ACP and cron

When to use it

Checking which services an IP address exposes without leaving the Hermes chat
Sizing internet-wide exposure, such as open RDP or expired TLS certificates, with count queries
Looking up known vulnerabilities for a host during a security review

Who it is for: Security researchers and sysadmins who want Hermes Agent to query Shodan without flooding its context window or burning query credits.

How it fits with Hermes Agent

Built for Hermes Agent as a plugin installed with hermes plugins install, and its tools register in the shared tool registry that every Hermes frontend uses.

How to install Hermes Plugin Shodan

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

hermes plugins install Adolanium/hermes-plugin-shodan --enable

Requirements: Hermes Agent; a Shodan API key for search, DNS enumeration and alerts (host intel and CVE lookups work without one)

Note: Search, DNS enumeration and alerts require a Shodan API key, and available query credits depend on your Shodan plan.

FAQ

What is Hermes Plugin Shodan?

Hermes Plugin Shodan is a Hermes Agent plugin that brings Shodan.io into the agent. It adds twelve tools, three skills, a CLI and a slash command for host intel, search, DNS, CVE lookups, monitoring and scanning.

How do I install Hermes Plugin Shodan?

Run hermes plugins install Adolanium/hermes-plugin-shodan --enable. The installer clones the plugin, can prompt for SHODAN_API_KEY, writes it to ~/.hermes/.env and enables the plugin. Restart the gateway if one is running.

What do I need to run Hermes Plugin Shodan?

You need Hermes Agent. Host intel and vulnerability lookups work with no API key, but search, DNS domain enumeration and alerts need a Shodan API key.