Package Documentation
Storm Package: synapse-spycloud
The following Commands are available from this package. This documentation is generated for version 1.9.0 of the package.
Storm Commands
This package implements the following Storm Commands.
spycloud.config.add
Add a Synapse-SpyCloud configuration.
SpyCloud is three separately licensed products, each with its own API key, so a
configuration is created for one product at a time. The valid types are
'consumer' (Consumer ATO Prevention), 'investigative' (Investigations), and
'enterprise' (Enterprise ATO Prevention, sold as Employee ATO protection).
The proxy argument can be set to one of the following values:
true: Use the Cortex configured proxy if set.
false: Do not use a proxy.
<string>: A proxy URL to use for requests to this API.
When the proxy is set to a URL, the proxy-user and proxy-passwd arguments may be
used to authenticate to it. They 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 to true or false.
Examples:
// Add a global configuration for the Investigations API
spycloud.config.add investigative default mykey
// Add a personal configuration for the Employee ATO protection API
spycloud.config.add enterprise mine mykey --scope self
// Add a configuration which egresses through an allowlisted proxy
spycloud.config.add enterprise default mykey --proxy socks5://proxy.host:1099
Usage: spycloud.config.add [options] <type> <name> <apikey>
Options:
--help : Display the command usage.
--scope <scope> : The scope of the configuration. (default: global, choices: global, self, unscoped)
--proxy <proxy> : The proxy to use for requests made with this configuration. (default: True)
--proxy-user <proxy_user> : The username to authenticate to the proxy with.
--proxy-passwd <proxy_passwd>: The password to authenticate to the proxy with.
--ssl-noverify : Disable SSL/TLS verification for requests made with this configuration.
Arguments:
<type> : The SpyCloud API the configuration is for. (choices: consumer, investigative, enterprise)
<name> : A unique name for the configuration.
<apikey> : The SpyCloud API key string.
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.config.del
Delete a Synapse-SpyCloud configuration.
Examples:
// Delete the configuration used by default for the Investigations API
spycloud.config.del investigative
// Delete a configuration by name
spycloud.config.del enterprise myconfig
Usage: spycloud.config.del [options] <type> <name>
Options:
--help : Display the command usage.
Arguments:
<type> : The SpyCloud API the configuration is for. (choices: consumer, investigative, enterprise)
[name] : The name of the configuration. If not used, the configuration which would be used by default is deleted.
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.config.list
List the Synapse-SpyCloud configurations the current user can access.
Examples:
// List every configuration
spycloud.config.list
// List only the Employee ATO protection configurations
spycloud.config.list --type enterprise
Usage: spycloud.config.list [options]
Options:
--help : Display the command usage.
--type <type> : Only list configurations for the given SpyCloud API. (choices: consumer, investigative,
enterprise)
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.config.show
Show a Synapse-SpyCloud configuration.
The API key is only displayed to users with permission to read the
configuration secrets.
Examples:
// Show the configuration used by default for the Investigations API
spycloud.config.show investigative
// Show a configuration by name
spycloud.config.show enterprise myconfig
Usage: spycloud.config.show [options] <type> <name>
Options:
--help : Display the command usage.
Arguments:
<type> : The SpyCloud API the configuration is for. (choices: consumer, investigative, enterprise)
[name] : The name of the configuration. If not used, the configuration which would be used by default is shown.
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.config.update
Update a Synapse-SpyCloud configuration.
When the proxy is set to a URL, the proxy-user and proxy-passwd arguments may be
used to authenticate to it. They 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 to true or false.
Examples:
// Replace the API key on a configuration
spycloud.config.update enterprise --apikey mynewkey
// Point a configuration at a proxy
spycloud.config.update enterprise --proxy socks5://proxy.host:1099
// Grant a role read access to a configuration
spycloud.config.update enterprise --perm role analysts read
Usage: spycloud.config.update [options] <type> <config>
Options:
--help : Display the command usage.
--apikey <apikey> : A new SpyCloud API key for the configuration.
--name <name> : Rename the configuration.
--proxy <proxy> : The proxy to use for requests made with this configuration.
--proxy-user <proxy_user> : The username to authenticate to the proxy with.
--proxy-passwd <proxy_passwd>: The password to authenticate to the proxy with.
--ssl-verify <ssl_verify> : Set whether to verify the SSL certificate of the server.
--perm <perm> : Set a permission on the configuration, as a scope (user or role), a name, and a level
(read, edit, admin or deny).
Arguments:
<type> : The SpyCloud API the configuration is for. (choices: consumer, investigative, enterprise)
[config] : The name of the configuration to update. If not used, the configuration which would be used by default is updated.
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.consumer.ato
Enrich nodes with SpyCloud Consumer ATO Prevention breach data.
This command queries the SpyCloud Consumer ATO Prevention API to retrieve breach
records. Queries can be performed by email address, username, or IP address, which
can be provided by a relevant inbound node.
The results of the query are used to create it:account, ps:contact, and depending on
the data available in the breach record, an auth:creds node linking the it:account to
inet:passwd or it:auth:passwdhash nodes.
If infected user data is present, it:host, it:fs:file, it:exec:url, it:logon, and auth:access nodes
may also be created to represent the infected user assets.
This command will create an it:exec:query node to represent the query syntax,
with a -(refs)> edge to the node that was enriched and -(found)> edges to results.
Examples:
// Use inbound inet:ipv4 node to search
inet:ipv4=1.2.3.4 | spycloud.consumer.ato
// Use inbound inet:ipv4 node to search and yield resulting it:account nodes
inet:ipv4=1.2.3.4 | spycloud.consumer.ato --yield
// Use inbound inet:ipv4 node to search and filter by severity
inet:ipv4=1.2.3.4 | spycloud.consumer.ato --severity 25
// Filter by more than one severity
$sevs = (20, 25) inet:ipv4=1.2.3.4 | spycloud.consumer.ato --severity $sevs
Endpoints:
https://api.spycloud.io/sp-v1
/breach/data/emails/{valu}: Retrieve breach records for an email address.
/breach/data/ips/{valu}/ : Retrieve breach records for an IP address.
/breach/data/usernames/{valu}/: Retrieve breach records for a username.
/breach/catalog/{valu} : Retrieve the metadata for a breach source.
Usage: spycloud.consumer.ato [options]
Options:
--help : Display the command usage.
--config <config> : The name of the configuration to use. If not used, the configuration which would be
used by default is selected.
--debug : Output debug messages.
--since <since> : Starting point for a date range query on the spycloud_publish_date field. (default:
None)
--until <until> : Ending point for a date range query on the spycloud_publish_date field. (default: None)
--severity <severity> : Filter results by one or more severity codes.
--source-id <source_id> : Filter results by one or more breach sources.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
Inputs:
inet:email : inet:email nodes
inet:ipv4 : inet:ipv4 nodes
inet:user : inet:user nodes
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.enterprise.watchlist
Ingest breach records for the assets on your SpyCloud watchlist.
This command queries the SpyCloud Enterprise ATO Prevention API. It takes no
inbound nodes, and creates the same nodes as spycloud.investigations. A meta:feed
node represents the feed, with -(found)> edges to the results.
The --since-last option retrieves only the records published since the previous
run, using the :latest property of that meta:feed node. Only a single cron job
using --since-last should be created per view for a given set of filters, to
avoid duplicate ingests.
Examples:
// Ingest watchlist records published in the last day
spycloud.enterprise.watchlist
// Ingest infected user records with a severity of 25
spycloud.enterprise.watchlist --type infected --severity 25
// Filter by more than one severity
$sevs = (20, 25) spycloud.enterprise.watchlist --severity $sevs
// Create a cron job to ingest new results every day
cron.add --name "SpyCloud Watchlist" --hour 3 { spycloud.enterprise.watchlist --since-last }
Endpoints:
https://api.spycloud.io/enterprise-v2
/breach/data/watchlist : Retrieve breach records for the assets on the watchlist.
/breach/catalog/{valu} : Retrieve the metadata for a breach source.
Usage: spycloud.enterprise.watchlist [options]
Options:
--help : Display the command usage.
--config <config> : The name of the configuration to use. If not used, the configuration which would be
used by default is selected.
--debug : Output debug messages.
--since <since> : Starting point for a date range query on the spycloud_publish_date field. (default:
-24hours)
--until <until> : Ending point for a date range query on the spycloud_publish_date field.
--since-modification-date <since_modification_date>: Starting point for a date range query on the record_modification_date field.
--until-modification-date <until_modification_date>: Ending point for a date range query on the record_modification_date field.
--type <type> : Filter results by record type. (choices: corporate, infected, email_domain,
target_domain)
--watchlist-type <watchlist_type>: Filter results by watchlist entry type. (choices: domain, email, ip, subdomain)
--severity <severity> : Filter results by one or more severity codes.
--source-id <source_id> : Filter results by one or more breach sources.
--salt <salt> : Provide a dynamic salt to use if hashing result assets is enabled for your API key.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size.
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
spycloud.investigations
Enrich nodes with SpyCloud Investigations v2 breach data.
This command queries the SpyCloud Investigations v2 API to retrieve breach records.
Queries can be performed by domain, email address, username, IP address, password,
phone number, infected machine ID, log ID, bank account number, credit card number,
Social Security Number, driver's license, or national/passport ID number, which can
be provided by a relevant inbound node.
The results of the query are used to create it:account, ps:contact, and depending on
the data available in the breach record, an auth:creds node linking the it:account to
inet:passwd or it:auth:passwdhash nodes.
If infected user data is present, it:host, it:fs:file, it:exec:url, it:logon, and auth:access nodes
may also be created to represent the infected user assets.
When result records contain additional asset fields (cc_number, bank_number,
social_security_number, drivers_license, national_id, passport_number), those assets
are surfaced as econ:pay:pan, econ:bank:account, gov:us:ssn, transport:land:license,
or ou:id:number nodes referenced from the resulting it:account.
This command will create an it:exec:query node to represent the query syntax,
with a -(refs)> edge to the node that was enriched and -(found)> edges to results.
Examples:
// Use inbound inet:ipv4 node to search
inet:ipv4=1.2.3.4 | spycloud.investigations
// Use inbound inet:ipv4 node to search and yield resulting it:account nodes
inet:ipv4=1.2.3.4 | spycloud.investigations --yield
// Use inbound inet:ipv4 node to search and filter by severity
inet:ipv4=1.2.3.4 | spycloud.investigations --severity 25
// Filter by more than one severity
$sevs = (20, 25) inet:ipv4=1.2.3.4 | spycloud.investigations --severity $sevs
// Use inbound it:host (infected machine) to search by machine ID
it:host:ext:id=<machine-id> | spycloud.investigations --yield
// Use inbound econ:pay:pan to search by credit card number (SHA1-hashed automatically)
econ:pay:pan=4111111111111111 | spycloud.investigations --yield
// Use inbound gov:us:ssn to search by SSN (SHA1-hashed automatically)
gov:us:ssn=123456789 | spycloud.investigations --yield
Endpoints:
https://api.spycloud.io/investigations-v2
/breach/data/emails/{valu}: Retrieve breach records for an email address.
/breach/data/domains/{valu}/: Retrieve breach records for a domain.
/breach/data/ips/{valu}/ : Retrieve breach records for an IP address.
/breach/data/passwords/{valu}/: Retrieve breach records for a password or password hash.
/breach/data/usernames/{valu}/: Retrieve breach records for a username.
/breach/data/phone-numbers/{valu}: Retrieve breach records for a phone number.
/breach/data/infected-machine-ids/{valu}/: Retrieve breach records for an infected machine ID.
/breach/data/log-ids/{valu}/: Retrieve breach records for a malware log ID.
/breach/data/bank-numbers/{valu}/: Retrieve breach records for a bank account number.
/breach/data/cc-numbers/{valu}/: Retrieve breach records for a SHA1 hashed credit card number.
/breach/data/social-security-numbers/{valu}/: Retrieve breach records for a SHA1 hashed Social Security number.
/breach/data/drivers-licenses/{valu}/: Retrieve breach records for a driver's license number.
/breach/data/national-ids/{valu}/: Retrieve breach records for a national ID number.
/breach/data/passport-numbers/{valu}/: Retrieve breach records for a passport number.
/breach/catalog/{valu} : Retrieve the metadata for a breach source.
Usage: spycloud.investigations [options]
Options:
--help : Display the command usage.
--config <config> : The name of the configuration to use. If not used, the configuration which would be
used by default is selected.
--debug : Output debug messages.
--since <since> : Starting point for a date range query on the spycloud_publish_date field. (default:
None)
--until <until> : Ending point for a date range query on the spycloud_publish_date field. (default: None)
--severity <severity> : Filter results by one or more severity codes.
--source-id <source_id> : Filter results by one or more breach sources.
--salt <salt> : Provide a dynamic salt to use if hashing result assets is enabled for your API key.
(default: None)
--type <type> : Filter results by type. Only applies to domain queries. (choices: corporate, infected)
--fuzzy : Use fuzzy matching when searching. Only applies to username and password queries.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
Inputs:
econ:bank:account : econ:bank:account nodes
econ:pay:pan : econ:pay:pan nodes
gov:us:ssn : gov:us:ssn nodes
hash:sha256 : hash:sha256 nodes
inet:email : inet:email nodes
inet:fqdn : inet:fqdn nodes
inet:ipv4 : inet:ipv4 nodes
inet:passwd : inet:passwd nodes
inet:user : inet:user nodes
it:auth:passwdhash : it:auth:passwdhash nodes
it:host : it:host nodes
ou:id:number : ou:id:number nodes
tel:phone : tel:phone nodes
transport:land:license : transport:land:license nodes
The command is accessible to users with one or more of the following permissions:
power-ups.spycloud.adminpower-ups.spycloud.user
Storm Modules
This package does not export any Storm APIs.