Admin Guide

Synapse-SpyCloud Admin Guide

Configuration

Synapse-SpyCloud requires an API key. For information on how to signup, please visit the SpyCloud API documentation.

Adding configurations

API keys are stored in configurations. SpyCloud is three separately licensed products, each with its own API key, so each gets its own configuration type. A key issued for one product cannot be used with the others.

The consumer type is for a Consumer ATO Prevention key, investigative for an Investigations key, and enterprise for an Employee ATO protection key. Note that Consumer ATO Prevention and Employee ATO protection are different products despite the similar names.

The endpoints each command uses, and the API they are served from, are listed in the command’s help output.

To add a global configuration:

> spycloud.config.add investigative default myapikey
Synapse-SpyCloud investigative config "default" added

A configuration may also be scoped to a single user with --scope self, or left unscoped with --scope unscoped so that it is only used when selected by name. Only one global configuration and one per-user configuration may exist for each type, and configuration names are unique across scopes.

The remaining commands manage them:

> spycloud.config.list
 type            | name                      | scope      | owner
=================|===========================|============|==========================================
 investigative   | default                   | global     | n/a

> spycloud.config.show investigative
Type: investigative
Name: default
Scope: global
Owner: n/a
Configs:
  Proxy: true
  SSL Verify: true
Secrets:
  API Key: myapikey

Use spycloud.config.update to rotate a key, change the proxy, rename a configuration, or grant another user or role access to it, and spycloud.config.del to remove one.

Source address restrictions

SpyCloud restricts an API key to a set of allowlisted source addresses, per key rather than per account. If the Cortex does not egress from an address allowlisted for the key in question, requests are rejected with an HTTP 403.

Each configuration carries its own proxy setting, so a product whose key requires an allowlisted egress can be pointed at a proxy without affecting the others:

> spycloud.config.update investigative default --proxy socks5://proxy.host:1099
Updated Synapse-SpyCloud investigative config "default"

The default is to use the proxy set by the Cortex http:proxy configuration option if there is one. Setting a proxy on a configuration requires either the power-ups.spycloud.admin or the storm.lib.inet.http.proxy permission.

When the proxy is a URL, --proxy-user and --proxy-passwd may be used to authenticate to it:

> spycloud.config.update investigative default --proxy-user proxyuser --proxy-passwd secret
Updated Synapse-SpyCloud investigative config "default"

Both values must be URL safe; see $lib.inet.http.urlencode. The password is stored in the configuration secrets, so it is only visible to users with edit access to the configuration. Any stored credentials are removed if the proxy is later set back to true or false.

Permissions

Package (synapse-spycloud) defines the following permissions:
power-ups.spycloud.user          : Allows a user to issue queries to the SpyCloud API. ( default: false )
power-ups.spycloud.admin         : Allows a user to manage Synapse-SpyCloud configurations. ( default: false )

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

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

or:

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

Exported APIs

Synapse-SpyCloud does not currently export any APIs.

Onload Events

Synapse-SpyCloud does not use any onload events. It does use Storm package inits to migrate API keys set by earlier versions into configurations.

Node Actions

The SpyCloud Power-Up provides the following node actions in Optic:

Name : investigations
Desc : Enrich the node with SpyCloud Investigations breach data.
Forms: econ:bank:account, econ:pay:pan, gov:us:ssn, hash:sha256, inet:email, inet:fqdn, inet:ipv4, inet:passwd, inet:user, it:auth:passwdhash, it:host, ou:id:number, tel:phone, transport:land:license

Name : consumer.ato
Desc : Enrich the node with SpyCloud Consumer ATO Prevention breach data.
Forms: inet:email, inet:ipv4, inet:user