Package Documentation

Storm Package: synapse-polyswarm

The following Commands are available from this package. This documentation is generated for version 2.0.0 of the package.

Storm Commands

This package implements the following Storm Commands.

polyswarm.config.add

Add a Synapse-PolySwarm configuration.

The proxy argument can be set to one of the following values:
  true: Use the Cortex configured proxy if set.
  false: Do not use the Cortex configured proxy if set.
  <str>: A proxy URL to use.

Examples:

  // Add a global configuration
  polyswarm.config.add default myapikey1234

  // Add a configuration for the current user
  polyswarm.config.add --scope self myconfig myapikey5678


Usage: polyswarm.config.add [options] <name> <apikey>

Options:

  --help                      : Display the command usage.
  --ssl-noverify              : Do not perform SSL/TLS verification.
  --proxy <proxy>             : Configure the proxy usage. (default: True)
  --tag-prefix <tag_prefix>   : The tag prefix to use when recording data from PolySwarm. (default: rep.polyswarm)
  --scope <scope>             : Set the scope on the configuration. (default: global, choices: global, self, unscoped)

Arguments:

  <name>                      : A unique name for the configuration.
  <apikey>                    : The PolySwarm API key string.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.config.del

Delete a Synapse-PolySwarm configuration.

Examples:

  // Delete the "myconfig" configuration
  polyswarm.config.del myconfig


Usage: polyswarm.config.del [options] <name>

Options:

  --help                      : Display the command usage.

Arguments:

  <name>                      : The name of the configuration.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.config.list

Display the list of Synapse-PolySwarm configurations you have access to.


Usage: polyswarm.config.list [options]

Options:

  --help                      : Display the command usage.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.config.migrate

Migrate options for all Synapse-PolySwarm configurations.

The proxy argument can be set to one of the following values:
  true: Use the Cortex configured proxy if set.
  false: Do not use the Cortex configured proxy if set.
  <str>: A proxy URL to use.

Examples:

  // Migrate the tag prefix for all configurations
  polyswarm.config.migrate --tag-prefix my.tagpref


Usage: polyswarm.config.migrate [options]

Options:

  --help                      : Display the command usage.
  --ssl-verify <ssl_verify>   : Set whether to verify the SSL certificate of the server. (default: None)
  --proxy <proxy>             : Configure the proxy usage. (default: None)
  --tag-prefix <tag_prefix>   : The tag prefix to use when recording data from PolySwarm. (default: None)

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

polyswarm.config.show

Show the details of a configuration.

Examples:

  // Show the in-use configuration for the current user
  polyswarm.config.show

  // Show a configuration by name
  polyswarm.config.show myconfig


Usage: polyswarm.config.show [options] <name>

Options:

  --help                      : Display the command usage.

Arguments:

  [name]                      : The name of the configuration.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.config.update

Update the configuration of a defined Synapse-PolySwarm configuration.

The proxy argument can be set to one of the following values:
  true: Use the Cortex configured proxy if set.
  false: Do not use the Cortex configured proxy if set.
  <str>: A proxy URL to use.

Examples:

  // Set the permission level for user "myuser" to "admin" on the "myconfig"
  // configuration
  polyswarm.config.update myconfig --perm user myuser admin

  // Set the permission level for the "all" role to "deny" on the
  // "myconfig" configuration
  polyswarm.config.update myconfig --perm role all deny

  // Do not verify the SSL certificate when connecting to "myconfig"
  polyswarm.config.update myconfig --ssl-verify (false)

  // Change the tag prefix used by the "myconfig" configuration
  polyswarm.config.update myconfig --tag-prefix my.prefix

  // Change the name of the "myconfig" configuration to "otherconfig"
  polyswarm.config.update myconfig --name otherconfig


Usage: polyswarm.config.update [options] <config>

Options:

  --help                      : Display the command usage.
  --apikey <apikey>           : The PolySwarm API key string. (default: None)
  --perm <perm>               : Set the permission level for a user or role on this configuration.
                                Arguments to this option are ``scope``, ``name``, ``level``:
                                  <scope>: The scope for the permission, either "user" or "role".
                                  <name>: The user/role name depending on scope.
                                  <level>: The $lib.auth.easyperm.level name, or (null) to remove the
                                           permission, which falls back to the config default.
                                 (default: None)
  --ssl-verify <ssl_verify>   : Set whether to verify the SSL certificate of the server. (default: None)
  --proxy <proxy>             : Configure the proxy usage. (default: None)
  --tag-prefix <tag_prefix>   : The tag prefix to use when recording data from PolySwarm. (default: None)
  --name <name>               : Rename the configuration. (default: None)

Arguments:

  <config>                    : The name of the configuration to modify.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.family.list

Query the PolySwarm API to retrieve the list of PolyUnite malware families.

This command creates risk:tool:software nodes to represent PolyUnite malware
families and the corresponding tags that will be applied to the file:bytes nodes
which belong to them.

Examples:

  // Ingest the current list of PolySwarm malware families
  polyswarm.family.list


Usage: polyswarm.family.list [options]

Options:

  --help                      : Display the command usage.
  --debug                     : Show verbose debug output.
  --config <config>           : Override the default config with the provided name.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.iocs.byhash

Retrieve IOCs related to a file hash.

This command takes a file:bytes or hash:sha256 node as input and queries
the corresponding /v3/ioc/sha256/{hash} endpoint to retrieve associated IOCs.

The inbound node will be linked to the IOCs created by this command with a
"refs" edge.

Examples:

  // Retrieve IOCs related to a hash:sha256 node and yield the results.
  hash:sha256#myhash | polyswarm.iocs.byhash --yield

  // Perform a metadata search and retrieve IOCs for the file:bytes nodes.
  polyswarm.metadata.search --size 5 "cape_sandbox_v2.network.tcp:*"
  | polyswarm.iocs.byhash --yield


Usage: polyswarm.iocs.byhash [options]

Options:

  --help                      : Display the command usage.
  --debug                     : Show verbose debug output.
  --size <size>               : Limit the number of results ingested to the given size.
  --yield                     : Yield the newly created nodes.
  --community <community>     : Name of the Community to use for the query. (default: default)
  --hide-known-good           : Do not return known good results.
  --config <config>           : Override the default config with the provided name.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.metadata.search

Query the PolySwarm metadata search API using Elastic Search syntax.

The file:bytes nodes yielded by the command will be linked to it:av:filehit nodes
to record malicious detections and other available metadata.

Examples:

  // Search for 10 results with the PolyUnite family "Emotet"
  polyswarm.metadata.search --size 10 "polyunite.malware_family:Emotet"

  // Search for results with the PolyUnite family "Emotet" which were updated in a
  // specific timeframe
  polyswarm.metadata.search "updated.polyunite:[2022-09-01 TO 2022-09-02] AND polyunite.malware_family:Emotet"


Usage: polyswarm.metadata.search [options] <query>

Options:

  --help                      : Display the command usage.
  --debug                     : Show verbose debug output.
  --size <size>               : Limit the number of results ingested to the given size. (default: 50)
  --use-strings-tool          : Ingest results from the 'strings' tool (may contain false positives).
  --config <config>           : Override the default config with the provided name.

Arguments:

  <query>                     : The query string.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

polyswarm.search.mapping

Query the PolySwarm API to retrieve the list of available fields.

Note: Not all fields may be usable for searching, this is a full list of
      any fields that the results may contain.

Examples:

  // Display the current list of available fields
  polyswarm.search.mapping

  // Display the current list of available fields containing 'network'
  polyswarm.search.mapping --filter network


Usage: polyswarm.search.mapping [options]

Options:

  --help                      : Display the command usage.
  --filter <filter>           : Only display fields containing this string.
  --debug                     : Show verbose debug output.
  --config <config>           : Override the default config with the provided name.

The command is accessible to users with one or more of the following permissions:

• power-ups.polyswarm.admin

• power-ups.polyswarm.user

Storm Modules

This package does not export any Storm APIs.