Admin Guide

Synapse-Shodan Admin Guide

Configuration

Synapse-Shodan requires you to have a Shodan API key. For information on how to signup, please visit the Shodan API Requirements.

Setting API key for global use

To set-up a global API key:

> shodan.config.add default myapikey
Synapse-Shodan config "default" added

Creating a configuration for role-based use

Add an unscoped configuration:

> shodan.config.add myunscoped myapikey --scope unscoped
Synapse-Shodan config "myunscoped" added

Grant another user admin permissions to the new configuration:

> shodan.config.update myunscoped --perm user visi admin
Updated Synapse-Shodan config "myunscoped"

Grant a role read permissions to the new configuration:

> shodan.config.update myunscoped --perm role ninjas read
Updated Synapse-Shodan config "myunscoped"

Overriding the proxy configuration

In order to override the default proxy configuration in the Cortex the user must have the power-ups.shodan.admin or storm.lib.inet.http.proxy permission.

When the proxy configuration is set to (false) or a URL the permission will be checked when a configuration is created/updated, and when it is used to make an HTTP request.

Permissions

Package (synapse-shodan) defines the following permissions:
power-ups.shodan.user            : Controls user access to Synapse-Shodan. ( default: false )
power-ups.shodan.admin           : Controls access to Synapse-Shodan admin options. ( default: false )
power-ups.shodan.spend           : Used in addition to power-ups.shodan.user to allow users to spend query credits. ( default: false )

You may add rules to users/roles directly from storm:

> auth.user.addrule visi power-ups.shodan.user
Added rule power-ups.shodan.user to user visi.

or:

> auth.role.addrule ninjas power-ups.shodan.user
Added rule power-ups.shodan.user to role ninjas.

Additionally, if the synapse-fileparser power-up is available, users will need the power-ups.fileparser.user permission in order to allow processing X509 certificates and various image file formats.

Exported APIs

Synapse-Shodan does not currently export any APIs.

Node Actions

Synapse-Shodan provides the following node actions in Optic:

Name : enrich
Desc : Enrich the node using the shodan API.
Forms: inet:ipv4, inet:ipv6

Name : enrich FQDN
Desc : Enrich the FQDN using the shodan API.
Forms: inet:fqdn

Ingesting CPE strings

The Shodan API may sometimes return invalid CPE strings. Invalid CPE strings will be rejected by Synapse when attempting to ingest the API data. As a workaround, the Synapse-Shodan Power-Up peforms the following transformations on CPE strings before attempting to ingest them:

Extend truncated CPE 2.3 strings with * in the missing parts. The CPE 2.3 specification requires CPE 2.3 strings to include values for all parts of the string. The Shodan API truncates trailing parts if the value is *.

Synapse v2.187.0 migration

Synapse v2.187.0 added a model migration (v0.2.31) that removed all invalid it:sec:cpe nodes from the Cortex. The Synapse-Shodan migration uses the above transformations to attempt to automatically repair and restore invalid it:sec:cpe nodes that originated from the Synapse-Shodan Power-Up.