Package Documentation

Storm Package: synapse-polyswarm

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

Storm Commands

This package implements the following Storm Commands.

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.

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.

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).

Arguments:

  <query>                     : The query string.

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.

polyswarm.setup.apikey

Manage the PolySwarm API key.

Examples

    // Set a global PolySwarm API key
    polyswarm.setup.apikey abcd1234

    // Set a PolySwarm API key for the current user
    polyswarm.setup.apikey --self abcd1234

    // Display the API key scope of the current key
    polyswarm.setup.apikey --show-scope

    // Display the current API key.
    polyswarm.setup.apikey --show-apikey

    // Remove the current global API key.
    polyswarm.setup.apikey --remove

    // Remove the per-user API key for the current user.
    polyswarm.setup.apikey --self --remove


Usage: polyswarm.setup.apikey [options] <apikey>

Options:

  --help                      : Display the command usage.
  --self                      : Set or remove the key as a user variable. If not used, the key is set globally.
  --show-scope                : Display the API key scope in use (global vs self).
  --show-apikey               : Display the API key value (requires admin perms or a "self" scope key).
  --remove                    : Remove the configured API key. May be used with --self.

Arguments:

  [apikey]                    : The API key string.

polyswarm.setup.tagprefix

Set the tag prefix used when recording PolySwarm tags.
The default tag prefix is "rep.polyswarm" if not specified.

Any tags provided by a VirusTotal API will be added within the given namespace.
For example, the PolySwarm malware family "Emotet" would result in
"#rep.polyswarm.mal.emotet".  Any characters incompatible with tag names are
replaced with "_".


Usage: polyswarm.setup.tagprefix [options] <tagname>

Options:

  --help                      : Display the command usage.

Arguments:

  <tagname>                   : The tag prefix to use.

Storm Modules

This package does not export any Storm APIs.