User Guide

Synapse-SpyCloud User Guide

Synapse-Spycloud adds additional Storm commands for querying the Spycloud API using your existing API key to retrieve breach records and compromised accounts. For more information on how SpyCloud models breach data see SpyCloud Data Schema.

Getting Started

Check with your Global Admin to enable permissions and find out if you need a personal API key.

Examples

Adding your personal configuration

API keys are stored in configurations. SpyCloud is three separately licensed products, so a configuration is created for one product at a time: consumer, investigative, or enterprise.

To add a personal configuration for the Investigations API:

> spycloud.config.add investigative mine myapikey --scope self
Synapse-SpyCloud investigative config "mine" added

The configurations you can access are listed with:

> spycloud.config.list
 type            | name                      | scope      | owner
=================|===========================|============|==========================================
 investigative   | mine                      | user       | root

Each command uses the configuration for its own product, so no configuration needs to be selected when only one exists. Where several do, --config selects one by name:

inet:user=cb2d@la | spycloud.investigations --config mine --yield

Enrich an `inet:user` to discover compromised credentials

> inet:user=cb2d@la | spycloud.investigations --yield
it:account=2d4e339ad0a3cd39a9c317a687279968
        .created = 2026/10/15 19:23:40.757
        .seen = ('2021/03/25 00:00:00.000', '2021/03/25 00:00:00.001')
        :contact = 7eefea44247c7174d1b49d7ba42a701e
        :user = cb2d@la

You may also use the yielded it:account nodes in subsequent storm operations. For example, you may pivot directly to the compromised credentials for the yielded results:

> inet:user=cb2d@la | spycloud.investigations --yield | -> auth:creds
WARNING: https://api.spycloud.io/investigations-v2/breach/data/usernames/cb2d@la/ HTTP: 403 Forbidden.

Once the command has completed, the results from the SpyCloud Investigations API have been fused with the rest of your existing knowledge about the inet:user. Subsequent queries will allow you to explore that knowledge holistically, for example:

> inet:user=cb2d@la -> it:account -> auth:creds
auth:creds=540c68c88c2323b0bfd0fd6b7a3eb595
        .created = 2026/10/15 19:23:40.757
        .seen = ('2021/03/25 00:00:00.000', '2021/03/25 00:00:00.001')
        :account = 2d4e339ad0a3cd39a9c317a687279968
        :passwd = a937
        :user = cb2d@la

The spycloud.investigations command may add additional nodes such as it:host and it:fs:file when context is available, all of which are automatically linked to the it:account node.

Additional input forms

In addition to the forms shown above, spycloud.investigations accepts the following input forms: econ:bank:account, econ:pay:pan, gov:us:ssn, hash:sha256, it:host, ou:id:number, and transport:land:license.

For forms that use a secondary property as the lookup value, the property is extracted automatically. Three forms apply preprocessing before querying:

Credit card PANs are SHA1-hashed before the API call:

econ:pay:pan=4111111111111111 | spycloud.investigations --yield

SSNs are zero-padded to nine digits and SHA1-hashed before the API call:

gov:us:ssn=123456789 | spycloud.investigations --yield

For ou:id:number, the endpoint (National ID or Passport) is determined by the ou:id:type:name property of the associated type node. Pivot from the type node by name to enrich all IDs of that type:

ou:id:type +:name=passport -> ou:id:number | spycloud.investigations --yield

ou:id:type +:name="national-id" -> ou:id:number | spycloud.investigations --yield

The it:host form queries by infected machine ID using the :ext:id property:

it:host:ext:id=<machine-id> | spycloud.investigations --yield

Ingest breach records for your watchlist

The spycloud.enterprise.watchlist command retrieves breach records for the domains, subdomains, email addresses, and IP addresses on your organization’s SpyCloud watchlist. Unlike the other commands it takes no inbound nodes, and by default retrieves records published in the last day.

This command uses an enterprise configuration:

> spycloud.config.add enterprise mine myapikey --scope self
Synapse-SpyCloud enterprise config "mine" added

> spycloud.enterprise.watchlist --since 2026-08-19 --yield
it:account=5f581aac3306e099ff8fd1a4d437cad0
        .created = 2026/10/15 19:23:41.073
        .seen = ('2026/08/19 14:12:58.000', '2026/08/19 14:12:58.001')
        :contact = 17966a950ff112051df61e4d60a6c685
        :user = fwong
it:account=969eb404ea0d13105d3cf525d3202141
        .created = 2026/10/15 19:23:41.105
        .seen = ('2026/08/19 09:41:02.000', '2026/08/19 09:41:02.001')
        :contact = 23646e1945cbc81f9b66d42a3f2a06dc

The records are ingested exactly as they are for spycloud.investigations, so the yielded it:account nodes may be used in subsequent Storm operations, and the rest of the record is reachable from them afterwards:

> meta:feed -(found)> it:account -> auth:creds
auth:creds=2f4a6114fe8b88449d0ac2bf3ce4ba38
        .created = 2026/10/15 19:23:41.072
        .seen = ('2026/08/19 14:12:58.000', '2026/08/19 14:12:58.001')
        :account = 5f581aac3306e099ff8fd1a4d437cad0
        :passwd = kn0ttyPine!42
        :user = fwong
auth:creds=7f19cc28b4704300eeb23171e1aad3a4
        .created = 2026/10/15 19:23:41.105
        .seen = ('2026/08/19 09:41:02.000', '2026/08/19 09:41:02.001')
        :account = 969eb404ea0d13105d3cf525d3202141
        :passwd = correcthorse

Results may be narrowed to a type of record, a type of watchlist entry, a severity, or a breach source:

spycloud.enterprise.watchlist --type infected --severity 25

spycloud.enterprise.watchlist --watchlist-type domain

The command creates a single meta:feed node representing the feed and links each result to it with a -(found)> light edge. Repeated runs with the same filters reuse that node.

Running the watchlist as a feed

The --since-last option retrieves only the records published since the previous run, using the :latest property of the meta:feed node. It is only advanced when every page of results was retrieved, so a failed request does not skip records.

The first run defines its starting point with --since, and subsequent runs resume from :latest:

spycloud.enterprise.watchlist --since -30days --since-last

spycloud.enterprise.watchlist --since-last

To run the watchlist on a regular schedule, set up a cron job in Storm:

cron.add --name "SpyCloud Watchlist" --hour 3 { spycloud.enterprise.watchlist --since-last }

Only a single cron job using --since-last should be created per view for a given set of filters, to avoid duplicate ingests.

The high-water mark may be inspected, or reset to re-ingest from a chosen point, on the feed node itself:

meta:feed:url="https://api.spycloud.io/enterprise-v2/breach/data/watchlist"

Use of `meta:source` nodes

Synapse-Spycloud uses a meta:source node and -(seen)> light edges to track nodes observed from the SpyCloud API.

> meta:source=bcc6912a4688db874a0eaf78cfee212c
meta:source=bcc6912a4688db874a0eaf78cfee212c
        .created = 2026/10/15 19:23:40.642
        :name = spycloud api

Storm can be used to filter nodes to include/exclude nodes which have been observed by Synapse-SpyCloud. The following example shows how to filter the results of a query to include only results observed by Synapse-SpyCloud:

> inet:user=cb2d@la -> it:account +{ <(seen)- meta:source=bcc6912a4688db874a0eaf78cfee212c }
it:account=2d4e339ad0a3cd39a9c317a687279968
        .created = 2026/10/15 19:23:40.757
        .seen = ('2021/03/25 00:00:00.000', '2021/03/25 00:00:00.001')
        :contact = 7eefea44247c7174d1b49d7ba42a701e
        :user = cb2d@la