Shodan Integration Guide

Overview

The Shodan integration allows your NINA workflows to connect with Shodan, a search engine for internet-connected devices. This integration enables automated asset discovery, vulnerability scanning, network monitoring, and threat intelligence enrichment directly from your workflows.

Status

The integration currently supports 26 operations across 6 resources:

• Host Lookup & Search: Look up IP addresses, search for devices, count results, and explore available search facets and filters
• DNS Intelligence: Resolve hostnames, reverse DNS lookup, and enumerate subdomains and DNS entries for domains
• On-Demand Scanning: Request Shodan to crawl IP addresses and netblocks, check scan status, and list available ports and protocols
• Network Alerts: Create and manage network monitoring alerts with configurable triggers for change detection
• Account Management: View API plan details, remaining credits, and account profile information
• Utility Tools: Get your public IP address and inspect HTTP headers

Advanced features include:

• Faceted Search: Break down search results by country, organization, port, OS, and 80+ other properties
• Query Tokenization: Analyze and validate search queries before execution
• Alert Triggers: Monitor for malware, industrial control systems, uncommon services, and more
• CIDR Support: Scan and monitor entire network ranges using CIDR notation

Credential Configuration

Before using the Shodan integration in your workflows, you need to configure credentials for authentication. The integration uses API key authentication.

Authentication Method

Field	Description	Example
API Key	Your Shodan API key	aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

How to obtain your API Key:

1. Visit Shodan and create an account
2. Confirm your email address
3. Your API key is displayed on the account dashboard
4. Copy the API key for use in your credential configuration

API Plans:

• Free (OSS): Basic access to count, facets, filters, tokens, ports, protocols, tools, and account endpoints
• Membership ($49 one-time): Adds host lookup, search, DNS resolve/reverse, and 100 query/scan credits
• Freelancer ($69/month): 10,000 query credits, 5,120 scan credits, commercial use
• Small Business ($359/month): 200,000 query credits, vulnerability search
• Corporate ($1,099/month): Unlimited queries, all filters, batch lookups

Important Notes:

• Free tier is limited to 1 request per second
• Some operations (host lookup, search, DNS) require at least a Membership plan
• On-demand scanning and alerts require a paid subscription plan
• Query credits are consumed when using search filters or accessing results past page 1

Creating a Shodan Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Shodan Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Shodan"
   • API Key: Paste your Shodan API key
4. Click Test Connection to verify credentials
5. Click Save to store the credential

Supported Resources and Operations

Host

Operation	Name	Description	Plan Required
get	Get Host	Get all information on an IP (ports, services, location)	Membership+
search	Search Hosts	Search Shodan using query syntax	Membership+
count	Count Hosts	Get match count and facet info without results	Free
facets	List Search Facets	Get available facet properties	Free
filters	List Search Filters	Get available search filter keywords	Free
tokens	Break Search Into Tokens	Analyze a query string into components	Free

DNS

Operation	Name	Description	Plan Required
resolve	Resolve Domain	Resolve hostnames to IP addresses	Membership+
reverse	Reverse DNS Lookup	Look up hostnames for IP addresses	Membership+
domain	Domain Information	Get subdomains and DNS entries for a domain	Membership+ (1 credit)

Account

Operation	Name	Description	Plan Required
info	API Info	Get API plan details and remaining credits	Free
profile	Account Profile	Get account information	Free

Scan

Operation	Name	Description	Plan Required
create	Request Scan	Crawl IP/netblock (1 IP = 1 scan credit)	Paid
status	Get Scan Status	Check scan progress	Paid
list	List Scans	List all active on-demand scans	Paid
ports	List Ports	List port numbers Shodan crawlers check	Free
protocols	List Protocols	List protocols for on-demand scans	Free

Alert

Operation	Name	Description	Plan Required
create	Create Alert	Create network monitoring alert	Paid
list	List Alerts	List all active alerts	Paid
get	Get Alert	Get details for a specific alert	Paid
edit	Edit Alert	Update monitored networks	Paid
delete	Delete Alert	Remove an alert	Paid
listTriggers	List Triggers	List available alert triggers	Paid
enableTrigger	Enable Trigger	Enable trigger on an alert	Paid
disableTrigger	Disable Trigger	Disable trigger on an alert	Paid

Tools

Operation	Name	Description	Plan Required
myip	My IP Address	Get your public IP address	Free
httpheaders	HTTP Headers	Show client HTTP headers	Free

Parameter Merging

The Shodan integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Shodan Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Shodan Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the Shodan operation

Examples

Looking Up a Host

{
  "resource": "host",
  "operation": "get",
  "parameters": {
    "ip": "8.8.8.8",
    "minify": false
  }
}

This returns all available information about the IP address including open ports, running services, banners, location data, and organization details.

Searching for Devices

{
  "resource": "host",
  "operation": "search",
  "parameters": {
    "query": "apache country:US port:443",
    "facets": "org,country",
    "page": 1,
    "minify": true
  }
}

This searches for Apache servers in the US on port 443, with faceted breakdowns by organization and country.

Counting Search Results

{
  "resource": "host",
  "operation": "count",
  "parameters": {
    "query": "port:22 os:Linux",
    "facets": "country,org"
  }
}

This returns the total number of matching hosts and facet breakdowns without consuming query credits.

Analyzing a Search Query

{
  "resource": "host",
  "operation": "tokens",
  "parameters": {
    "query": "Raspbian port:22 country:DE"
  }
}

This breaks the query into its filters and string components, useful for validating queries before execution.

Resolving Hostnames

{
  "resource": "dns",
  "operation": "resolve",
  "parameters": {
    "hostnames": "google.com,github.com,cloudflare.com"
  }
}

This resolves multiple hostnames to their IP addresses in a single call.

Reverse DNS Lookup

{
  "resource": "dns",
  "operation": "reverse",
  "parameters": {
    "ips": "8.8.8.8,1.1.1.1,208.67.222.222"
  }
}

This looks up the hostnames associated with each IP address.

Domain Enumeration

{
  "resource": "dns",
  "operation": "domain",
  "parameters": {
    "domain": "example.com"
  }
}

This returns all subdomains and DNS entries for the domain. Uses 1 query credit.

Requesting an On-Demand Scan

{
  "resource": "scan",
  "operation": "create",
  "parameters": {
    "ips": "203.0.113.0/24,198.51.100.1"
  }
}

This requests Shodan to crawl the specified network range and IP. Each IP costs 1 scan credit.

Checking Scan Status

{
  "resource": "scan",
  "operation": "status",
  "parameters": {
    "id": "R2Vx5LcK3x8PQWKN"
  }
}

This checks the progress of a scan. Status values: SUBMITTING, QUEUE, PROCESSING, DONE.

Creating a Network Alert

{
  "resource": "alert",
  "operation": "create",
  "parameters": {
    "name": "Production Servers Monitor",
    "ips": "203.0.113.0/24,198.51.100.1",
    "expires": 0
  }
}

This creates a persistent alert to monitor the specified IP ranges for changes.

Enabling a Trigger on an Alert

{
  "resource": "alert",
  "operation": "enableTrigger",
  "parameters": {
    "id": "HKVGAIRWD79Z7W2T",
    "trigger": "malware"
  }
}

This enables malware detection notifications on the specified alert.

Getting Your Public IP

{
  "resource": "tools",
  "operation": "myip",
  "parameters": {}
}

Returns your current public IP address as seen from the Internet.

Response Structure

Host Lookup Response

{
  "ip_str": "8.8.8.8",
  "org": "Google LLC",
  "os": null,
  "ports": [443, 53],
  "city": "Mountain View",
  "country_code": "US",
  "country_name": "United States",
  "isp": "Google LLC",
  "asn": "AS15169",
  "last_update": "2024-01-15T10:30:00.000000",
  "data": [
    {
      "port": 443,
      "transport": "tcp",
      "product": "Google Frontend",
      "ssl": { "cert": { "subject": { "CN": "dns.google" } } }
    }
  ]
}

Search Response

{
  "matches": [
    {
      "ip_str": "203.0.113.10",
      "port": 443,
      "org": "Example Corp",
      "product": "Apache httpd",
      "version": "2.4.41"
    }
  ],
  "facets": {
    "country": [
      { "count": 4158554, "value": "US" },
      { "count": 1500465, "value": "JP" }
    ]
  },
  "total": 15521401
}

Count Response

{
  "total": 15521401,
  "facets": {
    "country": [
      { "count": 4158554, "value": "US" },
      { "count": 1500465, "value": "JP" }
    ]
  }
}

API Info Response

{
  "plan": "dev",
  "query_credits": 95,
  "scan_credits": 100,
  "monitored_ips": 16,
  "usage_limits": {
    "query_credits": 100,
    "scan_credits": 100,
    "monitored_ips": 16
  }
}

DNS Resolve Response

{
  "google.com": "142.250.185.238",
  "facebook.com": "157.240.1.35"
}

Alert Response

{
  "id": "HKVGAIRWD79Z7W2T",
  "name": "Production Servers Monitor",
  "created": "2024-01-15T10:30:00.000000",
  "filters": {
    "ip": ["203.0.113.0/24", "198.51.100.1"]
  },
  "triggers": {
    "any": { "enabled": true },
    "malware": { "enabled": false }
  },
  "expires": 0
}

Shodan Search Query Syntax

Shodan uses a powerful query syntax for searching. Here are commonly used filters:

Filter	Description	Example
port	Filter by port number	port:22
country	Filter by country code	country:US
org	Filter by organization	org:"Google LLC"
product	Filter by software product	product:nginx
os	Filter by operating system	os:Linux
city	Filter by city	city:"San Francisco"
net	Filter by CIDR range	net:203.0.113.0/24
hostname	Filter by hostname	hostname:example.com
has_ssl	Filter for SSL support	has_ssl:true
http.title	Filter by page title	http.title:"Dashboard"
http.status	Filter by HTTP status	http.status:200
ssl.cert.subject.cn	Filter by SSL cert CN	ssl.cert.subject.cn:example.com
vuln	Filter by vulnerability	vuln:CVE-2021-44228

Use the host.facets and host.filters operations to get the complete list of available properties.

Alert Trigger Types

Trigger	Description
any	Any change detected on the monitored network
malware	Malware detected on monitored IPs
industrial_control_system	ICS/SCADA systems detected
internet_scanner	Known scanner detected
new_service	New service/port detected
open_database	Open database detected
ssl_expired	Expired SSL certificate detected
uncommon	Uncommon service or port detected
vulnerability	Known vulnerability detected

Integration in Workflow Context

The Shodan integration is particularly effective for security operations and threat intelligence workflows:

Common Workflow Patterns:

1. Asset Discovery & Inventory:

   • Schedule Node -> Shodan Node (search) -> Script Node (parse results) -> Database Node (update inventory) -> Alert Node (new assets)

2. Vulnerability Monitoring:

   • Schedule Node -> Shodan Node (alert create) -> Shodan Node (enableTrigger: vulnerability) -> Webhook -> Incident Response Workflow

3. DNS Reconnaissance:

   • Input Node (domain list) -> Shodan Node (dns domain) -> Script Node (enumerate subdomains) -> Shodan Node (host get per IP) -> Report Node

4. Perimeter Monitoring:

   • Schedule Node -> Shodan Node (search: net:your-range) -> Script Node (diff with baseline) -> Alert Node (unexpected services)

5. Threat Intelligence Enrichment:

   • IOC Feed Node -> Shodan Node (host get) -> Script Node (extract service banners) -> SIEM Node (enrich indicators)

6. On-Demand Security Assessment:

   • Trigger Node (new asset) -> Shodan Node (scan create) -> Wait Node -> Shodan Node (scan status) -> Shodan Node (host get) -> Report Node

7. Certificate Monitoring:

   • Schedule Node -> Shodan Node (search: ssl.cert.subject.cn:yourdomain.com) -> Script Node (check expiry) -> Alert Node (expiring certs)

Best Practices

1. Use Count Before Search: Use host.count to estimate result size before executing host.search to manage query credit consumption.

2. Leverage Facets: Use faceted search to get statistical breakdowns without iterating through all results.

3. Respect Rate Limits: Free tier allows 1 request per second. Implement delays between calls in workflows.

4. Monitor Credit Usage: Use account.info to check remaining query and scan credits before running credit-consuming operations.

5. Use Minify for Large Searches: Enable the minify parameter when you only need basic host information to reduce response size.

6. Set Alert Expiration: Use the expires parameter on alerts to auto-cleanup temporary monitoring configurations.

7. Validate Queries First: Use host.tokens to validate and analyze search queries before executing them.

8. Batch DNS Lookups: Both dns.resolve and dns.reverse accept comma-separated lists, so batch multiple lookups into single calls.

9. Cache Reference Data: Cache results from host.facets, host.filters, scan.ports, and scan.protocols as they change infrequently.

10. Handle Paid-Only Errors: Many operations return 403 on free plans. Implement graceful fallbacks in workflows.

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
401 Unauthorized	Verify API key is valid on the account page
403 Requires membership	Operation needs at least a Membership plan ($49 one-time)
403 Requires paid plan	Scanning and alerts require a paid subscription
Rate limit exceeded	Implement 1-second delays between requests on free tier
No results for host lookup	IP may not have been recently scanned by Shodan crawlers
Query credits exhausted	Check credits via account.info; upgrade plan or wait for monthly reset
Scan credits exhausted	Check remaining credits; each IP costs 1 scan credit
Empty search results	Verify query syntax using host.tokens; check if filters require paid plan
Connection timeout	Check network connectivity; Shodan API may be under heavy load

Error Response Format

{
  "error": "Requires membership or higher to access"
}

Common Error Codes

Status Code	Description
401	Unauthorized - Invalid or missing API key
403	Forbidden - Operation requires a higher plan tier
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Shodan service issue

Support

If you encounter issues with the Shodan integration, please contact our support team with:

• The operation you were attempting
• Your API plan tier (visible via account.info)
• Any error messages received
• The parameters you were using
• The workflow context where the issue occurred

Additional Resources

• Shodan API Documentation
• Shodan Search Query Syntax
• Shodan Account & Plans
• Shodan CLI Documentation

Updated: 2026-03-25