Shodan module.
Shodan enriches your organization's IP and domain IOCs with exposed services, open ports, and device fingerprints. It answers a question the other providers do not: not whether an address has been reported, but what it is actually running and how exposed that makes it. It is a bring-your-own-key integration: create a Shodan account, generate an API key, and paste it into the module once for the whole billing account. Every new IP or domain indicator that arrives after that is looked up automatically.
You need a Shodan account and an API key generated from it. The key is the only thing this module asks for.
How to connect Shodan
- Sign in to Shodan, or create an account if you do not have one, and generate an API key.
- In Liberty91, go to Modules, open the Analysis Modules section, and click the Shodan tile.
- Paste the key into the API key field.
- Turn on Active and click update.
Checking the connection
There is no separate Test button, because saving is the health check. When you save, Liberty91 calls Shodan with the key you pasted and reports what came back. A green Connected banner means the credential works, and a red banner means it does not. If you leave the page and return later, a blue Status banner shows the result of the last save rather than re-testing.
| Message | What it means |
|---|---|
API key validated | The key works and the module is ready to enrich |
Invalid API key | Shodan rejected the key. Generate a new one and paste it again |
Shodan rate limit reached, try again later | Your Shodan plan is out of requests for the moment. Nothing is wrong with the key |
Could not reach Shodan | Liberty91 got no response at all, usually a transient network problem |
Shodan returned HTTP <code> | Shodan answered with something unexpected, and the code says what |
Leave the API key field blank when you save and the stored key is kept. That is how you turn Active off and on again without retyping it. Keys are encrypted at rest and never sent back to the browser, so the field looks empty even when a key is stored.
The module also shows IOCs enriched as a running total, which is the quickest way to confirm that indicators really are being processed.
What you get from Shodan enrichment
Every IP and domain indicator that arrives after the key is saved is looked up, and what Shodan knows about the host becomes one of the four verdicts used across the platform, together with a score from 0 to 100.
| What Shodan reports about the host | Verdict |
|---|---|
| Known CVEs on the host | Malicious, with the score rising as the number of CVEs rises |
A malicious or compromised tag | Malicious |
| Any other tag | Suspicious |
| Nothing Shodan can tell you about | Unknown |
In the platform you see a Shodan chip on the indicator's row and in its panel, showing the
number of open ports and then up to six of the port numbers themselves, so you can read the
shape of the host without opening anything. In an IOC CSV export, SHODAN appears in the
enrichment_providers column, and over the API the same value comes back in the
enrichment_providers and enrichments fields on the IOC endpoints, where
you can also filter for it with ?enrichment_provider=SHODAN.
Shodan describes exposure rather than intent, so read its verdict alongside the others. IOC enrichment and decay scoring explains how the readings from several vendors combine into the verdict and the confidence you finally see.
Permissions and limits
Any member of the billing account can configure this module. There is no Owner or Admin gate on it, unlike the ransomware domain alerts, which are restricted.
- One key per billing account, shared by everyone on it.
- Saving is rate-limited to 12 attempts a minute per user, so repeated retries pause briefly.
- Enrichment runs in batches of up to 100 indicators.
Frequently asked questions
Which indicators does Shodan enrich?
IP addresses and domains. Indicators of any other type are left alone: Shodan adds no chip and no verdict to them.
Why is an address with known CVEs marked Malicious rather than Suspicious?
Because a host running software with known vulnerabilities is a concrete finding about that host, and the score rises with the number of CVEs. Read the chip alongside the verdict: it names the open ports the judgement came from.
Do I have to retype the key to turn the module off and on?
No. Leave the API key field blank when you save and the stored key is kept, so you can flip Active off or on without it.