PolySwarm Customer CLI v3

A Command Line Interface tool for interacting with version 3 of the PolySwarm Customer APIs, to view the Legacy Version 2 documentation navigate here.

Supports Python 3.7 and later.

Getting Started

Installation

From PyPI:

$ pip install polyswarm

If you get an error about a missing package named wheel, that means your version of pip is too old. You need pip version 19 or newer. To update pip, run pip install -U pip.

From source:

$ python setup.py install

If you get an error about a missing package named wheel, that means your version of setuptools is too old. You need setuptools version 40.8.0 or newer. To update setuptools, run pip install -U setuptools.

Upgrade

Check the current version installed
```
$ pip3 list | grep polyswarm
```
Response Example: polyswarm 3.1.0 and polyswarm-api 3.1.1

Upgrade the PolySwarm Package

$ pip3 install -U polyswarm polyswarm-api

Confirm the upgraded version
```
$ pip3 list | grep polyswarm
```
Response Example: polyswarm 3.8.0 and polyswarm-api 3.9.0

Configuration

Several parameters can be set up Globally in your environment instead of defining these with each command.

Set your API key

$ export POLYSWARM_API_KEY=<Your API key from polyswarm.network>

You will need to get your own API key from polyswarm.network/account/api-keys

Set the community name: "default" is the default public community.

$ export POLYSWARM_COMMUNITY=default

You can define your own private community name replacing the default community above if you have this feature on your plan.

Enable tab completion

$ eval "$(_POLYSWARM_COMPLETE=source polyswarm)"

Using the PolySwarm CLI

General Usage

The polyswarm command has several sub-commands. You can run the command or a sub-command by itself or use the -h option to get help output.

Request

$ polyswarm -h

Response

Usage: polyswarm [OPTIONS] COMMAND [ARGS]...

  This is a PolySwarm CLI client, which allows you to interact directly with
  the PolySwarm network to scan files, search hashes, and more.

Options:
  -a, --api-key TEXT              Your API key for polyswarm.network
                                  (required).  [env var: POLYSWARM_API_KEY]

  -u, --api-uri TEXT              The API endpoint (ADVANCED).  [env var:
                                  POLYSWARM_API_URI]

  -o, --output-file FILENAME      Path to output file.
  --output-format, --fmt [text|json|pretty-json|sha256|sha1|md5]
                                  Output format. Human-readable text or JSON.
  --color / --no-color            Use colored output in text mode.
  -v, --verbose
  -c, --community TEXT            Community to use.  [env var:
                                  POLYSWARM_COMMUNITY]

  --parallel INTEGER              Number of threads to be used in parallel
                                  http requests.

  --verify / --no-verify          Verify TLS connections.
  --version                       Show the version and exit.
  --api-version                   Show the version and exit.
  -h, --help                      Show this message and exit.

Commands:
  account          Interact with Accounts in Polyswarm.
  activity         Interact with Yara Rules stored in Polyswarm.
  cat              Output artifact contents to stdout.
  download         Download file(s).
  download-id      Download file(s).
  engine           Interact with engines.
  family           Interact with Malware Families in Polyswarm.
  historical       Interact with historical hunts.
  known            Interact with known ioc api.
  link             Interact with Tag links in Polyswarm.
  live             Interact with live hunts.
  lookup           Lookup a scan id(s).
  metadata         Interact with Metadata in Polyswarm.
  providers        List the names of available sandbox providers and VMs.
  report           Interact with the Polyswarm reporting system.
  report-template  Interact with the Polyswarm reporting templates system.
  rescan           Rescan files(s) by hash.
  rescan-id        Rescan by scan id.
  rules            Interact with Yara Rules stored in Polyswarm.
  sandbox          Interact with the Polyswarm sandbox system.
  scan             Interact with Scans sent to Polyswarm.
  search           Interact search api.
  stream           Access the polyswarm file stream.
  tag              Interact with Tags in Polyswarm.
  wait             Wait for a  scan to finish.

Further Usage Details

The command line structure is split into several sections; further details for the most used options and arguments are listed below. '[OPTIONS]' can be used in combination with a number of [COMMANDS].

polyswarm [OPTIONS] COMMAND [ARGS]...

[OPTIONS]

-a api key, overrides the global setting of the api key, useful for moving between the default public community and the private community.
–fmt Define an output format of the returned results; available outputs include json, pretty-json and sha256 values. This –fmt is optional; if not defined, it defaults to the engine verdict and artifact details.
-o output the returned results of the command to a file path of choice
-v Verbose allows for debugging and viewing the API/HTTP request

[COMMANDS]

These will be listed in the following chapters but are hierarchical in structure. Each main command will have a sub-command most of the time; these sub-command options can be found with the command polyswarm <command> -h.

For example, polyswarm search -h will list the available sub-commands for the command search

[ARGS]

Most commands require one or more Parameters; these could be IPs, URLs, Artifact ID, or a Hunt ID.

Still, the possibilities are significant with commands like metadata, allowing the ability to search through many fields. The Searching Metadata section will review these in further detail.

Retrieve account information

Account details

Format: polyswarm account whois

Description: Command to show information for your account, this includes what teams you are part of and account numbers.

Request

$ polyswarm account whois

Response

Account Number: 123456789
User Account Number: 987654321
Account Name: PolySwarm Demo
Account Type: team
Tenant: polyswarm
Communities: pcdemo

Account features and quotas

Format: polyswarm account features

Description: Command to show the features enabled and disabled for your account and team, quota usage and other details.

Request

$ polyswarm account features

Response

========================= Account Plan =========================
Account Number: 123456789
User Account Number: 987654321
Tenant: polyswarm
Account Plan Name: Enterprise
Plan Period Start: 2024-01-02T10:54:51.631182+00:00
Plan Period End: 2026-01-15T00:00:00+00:00
Window Start: 2024-07-30T10:54:51.631182+00:00
Window End: 2024-08-29T10:54:51.631182+00:00
Daily API Limit: 12,500
Daily API Remaining: 11,000
Has Stream Access?: No
Is Trial?: No

================== Account Features and Quota ==================
Name: Daily Api Limit
Tag: daily_api_limit
Value: True
---
.......

Private Communities

PolySwarm offers a service called “Private Communities” that restricts artifacts submitted into a Private Community and any metadata from the artifact to be accessible only by members of the private community and not to the wider public PolySwarm community.

Currently, once Private Communities has been enabled for your Team Account, it can be used via the API and CLI.

While setting up the environment as highlighted in the section "Configuration", you can set the API Key and Community to relate to the Team and Private Community Name going forward.

Alternatively, all cli commands discussed in this section support Private Communities, and to use this function, two options need to be fed into the [OPTIONS].

-a - Define the Team API Key that has access to the Private Community, to get the key see here
--community - Input the name of the Private Community, this will have been provided by the PolySwarm Team. If you omit the --community option from a CLI command, it will first look for the POLYSWARM_COMMUNITY variable in your environment, and if that is not defined, it will use the default public community.

Request Example

polyswarm -a 1234123412341234123412341234 --community mypc --fmt sha256 search metadata 'artifact.created:>now-1000d '

Scanning an Artifact

Scan a File

Format: polyswarm scan file <file>

Description: Command to scan a local file with PolySwarm to retrieve engine verdict details.

Options

Option	Type	Required	Description
`-r`, `--recursive`	-	false	Scan directories recursively
`-t`, `--timeout`	integer	false	How long to wait for results (default:900)
`-z`, `--is-zip`	bool	false	Will handle the provided file as a zip and decompress server side.
`-p`, `--zip-password`	string	false	Used to provide a password to decompress the zip file with.
`-n`, `--nowait`	-	false	Does not wait for the scan window to close
`-s`, `--scan-config`	string	false	Template to be used in the scan i.e. default, more-time, most-time

Request

$ polyswarm scan file /tmp/eicar

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Detections: 6/12 engines reported malicious
	Qihoo 360: Malicious, metadata: {"malware_family": "qex.eicar.gen.gen", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}}}
	Lionic: Clean
	XVirus: Clean
	Nucleon: Clean
	Virusdie: Malicious, metadata: {"malware_family": "EICAR.TEST", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "vendor_version": "1.3.0", "version": "0.3.0"}}
	Ikarus: Malicious, metadata: {"malware_family": "EICAR-Test-File", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "21.02.2020 13:15:46 (102417)", "vendor_version": "5.2.9.0", "version": "0.2.0"}}
	ClamAV: Clean
	Alibaba: Clean
	K7: Malicious, metadata: {"malware_family": "EICAR_Test_File", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "11.95.33362, 21-Feb-2020", "vendor_version": "15.2.0.42", "version": "0.2.0"}}
	NanoAV: Malicious, metadata: {"malware_family": "Marker.Dos.EICAR-Test-File.dyb", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "0.14.33.17090", "vendor_version": "1.0.134.90567", "version": "0.1.0"}}
	VenusEye: Clean
	DrWeb: Malicious, metadata: {"malware_family": "EICAR Test File (NOT a Virus!)", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42", "vendor_version": "7.00.44.12030", "version": "0.3.0"}}
Scan id: 50446025732260182
SHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
SHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c
MD5: a6a57bf20416a4c712c4a1eabcaeb235
File type: mimetype: text/plain, extended_info: EICAR virus test files
SSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX
TLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8
First seen: 2020-01-24 21:56:21.456900
Last seen: 2020-02-21 19:21:59.196578
Status: Assertion window closed
Filename: malicious.txt
Community: lima
Country: US
PolyScore: 0.07193209420451106284

Scan a URL

Format: polyswarm scan url <URL>

When scanning a URL, you should always include the protocol (http:// or https://).

Description: Command to scan a url with PolySwarm to retrieve engine verdict details. The command can be used to scan a qr code and extract the url from the code.

Options

Option	Type	Required	Description
`-r` ,`--url-file`	string	false	Path of file that contains multiple URLs, one per line.
`--qrcode-file`	string	false	Path of a QR Code image file that contains an URL as a payload.
`-t`, `--timeout`	integer	false	How long to wait for results (default:900).
`-n`, `--nowait`	-	false	Does not wait for the scan window to close.
`-s`, `--scan-config`	string	false	Template to be used in the scan i.e. default, more-time, most-time.

Request

$ polyswarm scan url https://google.com

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d
Detections: 0/4 engines reported malicious
	CyRadar: Clean
	Phishtank: Clean
	Nucleon: Clean
	Virusdie: Clean
Scan id: 47022542941158297
SHA256: 05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d
SHA1: 72fe95c5576ec634e214814a32ab785568eda76a
MD5: 99999ebcfdb78df077ad2727fd00969f
File type: mimetype: text/plain, extended_info: ASCII text, with no line terminators
SSDEEP: 3:N8r3uK:2LuK
TLSH:
First seen: 2019-06-25 01:53:43.954091
Last seen: 2020-02-21 19:40:12.136225
Status: Assertion window closed
Filename: https://google.com
Community: lima
Country: US
PolyScore: 0.00000000000000000000

Rescanning an Artifact

Format: polyswarm rescan <hash>

Description: Rescans also triggered by referencing the SHA256/SHA1/MD5 hash of the artifact. Rescan will submit the sample through the engines to retrieve an updated verdict.

Options

Option	Type	Required	Description
`-r`, `--hash-file`	string	false	File path and name for file that contains hashes, one per line
`-t`, `--timeout`	integer	false	How long to wait for results (default:900)
`-n`, `--nowait`	-	false	Does not wait for the scan window to close
`-s`, `--scan-config`	string	false	Template to be used in the scan i.e. default, more-time, most-time
`--hash-type`	string	false	Hash type to search [default:autodetect, sha256, sha1, md5]

Request

$ polyswarm rescan 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Detections: 5/11 engines reported malicious
	Qihoo 360: Malicious, metadata: {"malware_family": "qex.eicar.gen.gen", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}}}
	ClamAV: Clean
	Ikarus: Malicious, metadata: {"malware_family": "EICAR-Test-File", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "21.02.2020 13:15:46 (102417)", "vendor_version": "5.2.9.0", "version": "0.2.0"}}
	Nucleon: Clean
	VenusEye: Clean
	K7: Malicious, metadata: {"malware_family": "EICAR_Test_File", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "11.95.33362, 21-Feb-2020", "vendor_version": "15.2.0.42", "version": "0.2.0"}}
	Lionic: Clean
	Virusdie: Malicious, metadata: {"malware_family": "EICAR.TEST", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "vendor_version": "1.3.0", "version": "0.3.0"}}
	Alibaba: Clean
	DrWeb: Malicious, metadata: {"malware_family": "EICAR Test File (NOT a Virus!)", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "0599371BD3AE76D460E15A9719E64059, 2020-Feb-21 18:06:10", "vendor_version": "7.00.44.12030", "version": "0.3.0"}}
	XVirus: Clean
Scan id: 87555975730729927
SHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
SHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c
MD5: a6a57bf20416a4c712c4a1eabcaeb235
File type: mimetype: text/plain, extended_info: EICAR virus test files
SSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX
TLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8
First seen: 2020-01-24 21:56:21.456900
Last seen: 2020-02-21 20:03:30.398950
Status: Assertion window closed
Filename: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Community: lima
Country: US
PolyScore: 0.08376258884586366971

Downloading & Reporting

Downloading Artifacts

Format: polyswarm download <hash>

Description: Artifacts are downloaded by referencing their SHA256/SHA1/MD5 hash and stored locally.

Options

Option	Type	Required	Description
`-r`, `--hash-file`	string	false	File of hashes to download, one per line
`-d`, `--destination`	string	false	Path where to store the downloaded files
`--hash-type`	string	false	Hash type to search [default:autodetect, sha256, sha1, md5]

Request

$ polyswarm download 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 test/

Response

Successfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/test/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267

Downloading Artifacts via id

Commonly used to download sandbox artifacts, this command can be used to download artifacts directly via their instance_id see this section for command.

Reporting

Downloading reports and zip files

PolySwarm provides the reporting cli command, this provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing sessions, and download a ZIP file of which can contain the PDF report alongside other Sandbox artifacts like pcaps, reports and jarm files.

The following are the 3 sequential steps in a report generation operation, that can be performed via the CLI one step at a time:

Inform PolySwarm to start creating the report, or create and download the zip file. If only wanting the zip file there is no need to proceed with the next two steps.
Poll PolySwarm to understand when the report has finished being created.
Download the report locally once generation is successful.

Format: polyswarm report create [OPTIONS] <html|pdf|zip> <scan|sandbox> <OBJECT_ID>

Description: Start to generate the PolySwarm report, choose a PDF or HTML report for Sandbox or a Scanning instance. Or create a zip file with Sandbox Artifacts to download directly.

NOTE: If generating a Scanning report the OBJECT_ID will be the artifact_id, find this with the command: polyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id'. If generating a Sandboxing report the OBJECT_ID will be the sandbox_id, find this with the command: polyswarm sandbox search <hash> then choose from the desired sandbox sessions.

Options

Option	Type	Required	Description
`--includes`	string	false	Comma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis
`--sandbox_artifact_types`	string	false	Comma-separated list of sandbox artifact types to include in the downloaded zip. Can be one or more of: `report`, `raw_report`, `screenshot`, `recording`, `dropped_file`, `memory_dump`, `pcap`, `jarm`. Only applicable to zip type.
`--zip-report-ids`	string	false	Comma-separated list of report task ids to include in the zip. This only needs to be used if you require the PDF report to be included in the ZIP. Note that the PDF report must be generated first.
`--template-id`	integer	false	Provide the `id` for the template used

Example 1 Request: Create a PDF Report

$ polyswarm report create pdf scan 97903321852386706

Example 1 Response

Successfully downloaded artifact scan-97903321852386706.pdf to /Users/John/Documents/scan-97903321852386706.pdf
============================= Report =============================
ID: 59403308938961820
Community: _public
Created: 2024-06-11T10:19:48.211143
Type: scan
Format: pdf
Template ID: 95389624286242180
Scan ID: 97903321852386706
State: PENDING

Example 2 Request: Download a ZIP file

$ polyswarm report create --sandbox_artifact_types report,raw_report,pcap zip sandbox 97903321852386706

Example 2 Response

Successfully downloaded artifact sandbox_zip-97903321852386706.zip to /Users/John/Documents/sandbox_zip-97903321852386706.zip

Format: polyswarm report get <REPORT_ID>

Description: Retrieve the report's details to understand if the report generation has been successful and then retrieve the download link. REPORT_ID provided from the previous command.

Request

$ polyswarm report get 59403308938961820

Response

============================= Report =============================
ID: 59403308938961820
Community: _public
Created: 2024-06-11T10:19:48.211143
Type: scan
Format: pdf
Template ID: 95389624286242180
Scan ID: 97903321852386706
State: SUCCEEDED
URL: https://s3.us-east-2.amazonaws.com/ps-storage-prod-reports/{AWS_LINK}...

Format: polyswarm report download <REPORT_ID>

Description: Download the generated report locally.

Options

Option	Type	Required	Description
`--destination`	string	false	Local path to store the downloaded file.

Request

$ polyswarm report download 59403308938961820

Response

Successfully downloaded artifact scan-97903321852386706.pdf to /Users/John/Documents/scan-97903321852386706.pdf

Report templates

PolySwarm provides the ability to manage the report templates, this can include uploading a new template, deleting a current template and managing the logo for each one.

List templates

Format: polyswarm report-template list

Description: List the available templates available to the team.

Request

$ polyswarm report-template list

Response

============================= Report Template =============================
ID: 95389624286242180
Template Name: default
Created: 2024-06-05T19:33:03.232395
Primary Color: 6D3AEC
Is Default: True

Create a template

Format: polyswarm report-template create <TEMPLATE_NAME>

Description: Create a new template with a number of option below.

Options

Option	Type	Required	Description
`--is-default`	-	false	If declared this template will be the default template for the team.
`--primary-color`	string	false	Six-character hex color code.
`--last-page-text`	string	false	Text to be displayed on the last page of the template (cannot be used with `--last-page-text-file`).
`--last-page-text-file`	string	false	File path to the document that contains the text for the last page text (cannot be used with `--last-page-text`).
`--includes`	string	false	Comma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis.

Request

$ polyswarm report-template create --primary-color ec6560 --footer-text 'Company A INC 2024' --includes network,droppedFiles,extractedConfig snd_box_test

Response

============================= Report Template =============================
ID: 60430384589833968
Template Name: sndboxtest
Created: 2024-06-11T12:42:45.950422
Primary Color: ec6560
Includes: network, droppedFiles, extractedConfig
Footer Text: Company A INC 2024

Delete a template

Format: polyswarm report-template delete <REPORT_ID>

Description: Delete the template.

Request

$ polyswarm report-template delete 60430384589833968

Response

Template Deleted

Get template details

Format: polyswarm report-template get <REPORT_ID>

Description: Get the details for s specific template.

Request

polyswarm report-template get 60430384589833968

Response

============================= Report Template =============================
ID: 60430384589833968
Template Name: sndboxtest
Created: 2024-06-11T12:42:45.950422
Primary Color: ec6560
Includes: network, droppedFiles, extractedConfig
Footer Text: Company A INC 2024

Update a template

Format: polyswarm report-template update <TEMPLATE_ID>

Description: Update the template with new values and configuration.

Options

Only the passed options are updated, leaving the rest of the values untouched. | Option | Type | Required | Description | |------|------|----------|-------------| |--is-default| - | false | If declared this template will be the default template for the team. | |--primary-color| string | false | Six-character hex color code. | |--last-page-text| string | false | Text to be displayed on the last page of the template. | |--last-page-text-file| string | false | File path to the document that contains the text for the last page text. | |--includes| string | false | Comma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis. |

Request

$ polyswarm report-template update --primary-color 6D3AEC  98453877554394669

Response

============================= Report Template =============================
ID: 98453877554394669
Template Name: test
Created: 2024-06-11T12:36:17.511289
Primary Color: 6D3AEC

Upload template logo

Format: polyswarm report-template logo-upload <TEMPLATE_ID> <PATH>

Description: Upload a new logo for the template.

Request

polyswarm report-template logo-upload 98453877554394669 /Users/John/Downloads/Logo_Purple.png

Response

============================= Report Template =============================
ID: 98453877554394669
Template Name: test
Created: 2024-06-11T12:36:17.511289
Primary Color: 6D3AEC
Logo Content Length: 6284
Logo Content Type: image/png
Logo URL: https://api.polyswarm.network/v3/reports/templates/logo?id=98453877554394669
Logo Height: 42
Logo Width: 250

Delete template logo

Format: polyswarm report-template logo-delete <TEMPLATE_ID>

Description: Delete the current logo for the template.

Request

polyswarm report-template logo-delete 98453877554394669

Response

Template logo deleted

Download template logo

Format: polyswarm report-template logo-download <TEMPLATE_ID>

Description: Download the template logo locally.

Options

Option	Type	Required	Description
`--destination`	string	false	Local path to store the downloaded file.

Request

$ polyswarm report-template logo-download 98453877554394669

Response

Successfully downloaded artifact logo to /Users/ruebenburrows/Documents/python/logo

Searching

Hash Searching

Format: polyswarm search <hash>

Description: Artifacts are searched by referencing their SHA256/SHA1/MD5.

Options

Option	Type	Required	Description
`-r`, `--hash-file`	string	false	File of hashes to search, one per line
`--hash-type`	string	false	Hash type to search [default:autodetect, sha256, sha1, md5]

Request

$ polyswarm search hash 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Detections: 6/12 engines reported malicious
	Qihoo 360: Malicious, metadata: {"malware_family": "qex.eicar.gen.gen", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}}}
	Lionic: Clean
	XVirus: Clean
	Nucleon: Clean
	Virusdie: Malicious, metadata: {"malware_family": "EICAR.TEST", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "vendor_version": "1.3.0", "version": "0.3.0"}}
	Ikarus: Malicious, metadata: {"malware_family": "EICAR-Test-File", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "21.02.2020 13:15:46 (102417)", "vendor_version": "5.2.9.0", "version": "0.2.0"}}
	ClamAV: Clean
	Alibaba: Clean
	K7: Malicious, metadata: {"malware_family": "EICAR_Test_File", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "11.95.33362, 21-Feb-2020", "vendor_version": "15.2.0.42", "version": "0.2.0"}}
	NanoAV: Malicious, metadata: {"malware_family": "Marker.Dos.EICAR-Test-File.dyb", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "0.14.33.17090", "vendor_version": "1.0.134.90567", "version": "0.1.0"}}
	VenusEye: Clean
	DrWeb: Malicious, metadata: {"malware_family": "EICAR Test File (NOT a Virus!)", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42", "vendor_version": "7.00.44.12030", "version": "0.3.0"}}
Scan id: 50446025732260182
SHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
SHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c
MD5: a6a57bf20416a4c712c4a1eabcaeb235
File type: mimetype: text/plain, extended_info: EICAR virus test files
SSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX
TLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8
First seen: 2020-01-24 21:56:21.456900
Last seen: 2020-02-21 19:21:59.196578
Status: Assertion window closed
Filename: malicious.txt
Community: lima
Country: US
PolyScore: 0.07193209420451106284

URL Searching

Format: polyswarm search url <URL>

Description: Artifacts are searched by referencing their URL.

Request

$ polyswarm search url https://polyswarm.io

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/078e6c2d6ba818466fb9944a8717e249b3820c13addc9b7ebf59e3ca79166541
Detections: 0/6 engines reported malicious
	ZeroCERT: Clean
	CyRadar: Clean
	Quttera: Clean
	Notmining: Clean
	Virusdie: Clean
	Nucleon: Clean
Scan id: 61118021570495545
SHA256: 078e6c2d6ba818466fb9944a8717e249b3820c13addc9b7ebf59e3ca79166541
SHA1: 3a26c7a00fbeb54b49361457e99bb6cd59dcfe24
MD5: e82f49f9ef02b6b517748be47ba0005a
File type: mimetype: text/plain, extended_info: ASCII text, with no line terminators
SSDEEP: 3:N8OI+ILL:2OGLL
TLSH:
First seen: 2019-06-25 18:04:48.248039
Last seen: 2020-04-01 03:59:53.555767
Status: Assertion window closed
URL: https://polyswarm.io
Community: lima
Country: AU
PolyScore: 0.00000000000000000000

Metadata Searching

PolySwarm's Metadata Search is a powerful and flexible means to discover previously unknown malware. Metadata information covered in the section will be the building blocks in any Metadata query, and will apply to Metadata usage throughout PolySwarm (CLI,API,UI).

This section is broken down into the below high level sections

Getting Started with Metadata

As PolySwarm ingests Artifacts (Files, URLs, etc.), various "Metadata Extractors" are run against the Artifacts, producing a rich set of Attributes that describe the Artifacts, the Scans conducted against the Artifacts and contextual information such as the timestamp of ingestion.

All of the Attributes produced by the Metadata extraction process are "pivotable" (searchable), empowering users to hunt for Artifacts that exhibit (or don't exhibit) various Attributes - and mix and match these queries with rich search syntax including Boolean logic and regular expressions.

For example, if you'd like to find all Artifacts that are:

64 bit Windows executables (PEs)
AND were first seen within the last week
AND export a specified regular expression of function names
OR contain a specified C2 address

... then PolySwarm's Metadata Search is your tool!

This section will cover the basics of Metadata, syntax and finding the fields needed with some use case examples. Once the basics of Metadata have been understood, a Metadata command can be crafted and used across the UI,CLI and API.

As an example, scan.detections.malicious:>1 can be used in the UI, CLI and API tools as an argument.

PolySwarm's Metadata Search is backed by Elasticsearch and supports the full range of Elasticsearch search criteria to deliver flexible results quickly.

Searching for Metadata Attributes

Format: polyswarm search metadata <metadata values>

Description: Search for Artifact Metadata in the CLI, Add additional options like –fmt to allow for additional functionality see here.

Options

Option	Type	Required	Description
`-i`, `--include`	string	false	Field to be included in the result (* wildcards are accepted).
`-x`, `--exclude`	string	false	Field to be excluded in the result (* wildcards are accepted).

Request

$ polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1"

Response

{
    "artifact": {
        "created": "2023-06-20T11:29:11.322959+00:00",
        "id": "3414327927829341",
        "md5": "6bf2025e7aa7b09d7044718c2a3f190d",
        "sha1": "5323a695a165e13a04a11d24e603ae4444463b08",
        "sha256": "2d1bbc2837559f5224076a833ec6e9cc6fe053b76a11bf500654ce0431b8993c"
    },
    "exiftool": {
        "characterset": "Unicode",
        "codesize": 45056,
        ..............

Processing Attribute Results with JQ

jq is a command-line processor for json files, allowing the slicing of the json to filter out specific Attributes.

When defining --fmt as json in the polyswarm search metadata CLI command, jq can be used to filter the output of the Attributes.

Taking the command polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1" will produce a large json output that matches these criteria, to filter only sha256 values, you can use jq to achieve this.

Request

$ polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1" | jq .artifact.sha256

Response

"8ce0d5b701fb084f14990fe0d425628781130c9da0b0b95f98f3a9e5eef755bb"
"19cb4f641750555e4a40460e03a07217306077585a7290ef480712d373e3b755"
"f2015c1e82f92c7d8a728eeb47adb52e877a3ab9ee2d7168cc311fae7b5bbfae"
"b0a1cc605d485e5e73e73aa8a0377a9d12a53d4042d711bd4bf99cd7b6961afa"
"9cb02c934c2aa8938b30aa52924798a6d2a12ca4e7d75a2d01390c01067b0a8b"
"6d7607445c3b71d707576d6424581cb0a0c6c39f11a67601811568cf30eba9ab"
"f665fa1373a7bb1b8085ad95866066f2164e25f79e3bf0dc45abc2ba690144ab"
"bf1e0bd5265619d33c89795d340fe05bf7e3a80935396e83cd52d3baa77b4902"
"07707539577a320e56805cd9458a3ffd9ace7fb31aca106bd1aad89d60354906"
"d47f64147c5ad65a9841813df44fce49e435e472874853d02a192689dd1f5007"
"d767ded5ba7377356f48351f9f03ada9de9c6eb156f08de0a9cce2ebe3ad4369"

Including and Excluding Results

A more efficient method of selecting a subset of the fields in the results is to use the --include and --exclude options in the polyswarm search metadata command. These options can be used more than once in a single command to include or exclude parts of the resulting data object.

In the example below, the command will include only the artifact.sha256 field in the output.

Request

polyswarm search metadata --include artifact.sha256 --include scan.detections.malicious "scan.detections.malicious:>1"

Response

============================= Metadata =============================
Artifact id: 800261578717225
Created: None
SHA256: b59cc7c56a3513ea355660d8c6f9593ef0b28734575d528890f771d3184b001a

============================= Metadata =============================
Artifact id: 24752295304479291
Created: None
SHA256: 17b4c990736f5687081239758acbc5c67602c619bacd818ac8d0e08c313c2476

Common Metadata Search Pitfalls

When developing queries Users should be aware of several idiosyncrasies Metadata Search inherits from Elasticsearch.

Attribute fields are case-sensitive.
If a query refers to a field that doesn't exist, Metadata Search will ignore this portion of the query.

For example, the intention of the following query is likely to identify all Artifacts detected as malicious by at least 2 Engines, where 1 is ClamAV:

scan.latest_scan.ClamAV.assertion:malicious AND scan.detections.malicious:>1

As explained later, scan does not exist on all Artifacts (is optional), let alone scan.latest_scan.ClamAV.

On Artifacts for which scan.latest_scan.ClamAV does not exist, this portion of the query is ignored, effectively reducing this query to:

scan.detections.malicious:>1

Resulting in an incorrect result set that includes Artifacts found to be malicious by at least 2 Engines for which no ClamAV scan result exists.

Users must first verify the existence of the optional field before applying criteria to the contents of the optional field, this is covered in the Syntax Section

This query will return the intended result set:

_exists_:scan.latest_scan.ClamAV AND scan.latest_scan.ClamAV.assertion:malicious AND scan.detections.malicious:>1

Metadata Searchable Attributes

Metadata Attributes can be used to Search on as well as what Attributes to output, these Attributes belong to one of the following Scopes:

Artifact: Attributes that describe Artifacts in context and at surface level, e.g. the Artifact's unique id, the time it was first_seen and its various hashes (sha256,md5,sha1). These Attributes are available on all Artifacts.
Scan: Information concerning the Scan(s) that have been executed on the Artifact. Users can address the first and latest (most recent) Scan Result Sets for each scanned Artifact, accessing information such as: what each Engine said about the scanned Artifact, whether the Engine detected the Artifact as malicious or benign and what malware_family the Artifact was found to belong to, as applicable. There is a 1 to many relationship between Artifacts and Scan Result Sets: each Artifact has 0 to N associated Scan Result Sets, whereas every Scan result set will have exactly 1 associated Artifact. These Attributes are available on all Artifacts that have been scanned at least once.
Tool: Attributes that describe the content of Artifacts. A set of Metadata Extraction Tools ("Tools") are run on Artifacts under various criteria, e.g. the Artifact's file type. For example, strings (a Tool) is used to extract IP, domain & URL-like strings from all file Artifacts, whereas pefile (another Tool) exclusively extracts information from Artifacts that are Windows executables. Such Attributes are addressed via the name of the Tool itself. Tool-produced Attributes are available on Artifacts for which the given Tool is applicable.

Queries address Attributes hierarchically (based on their Scope). Results are similarly delivered hierarchically. For example, pefile produces an attribute named imphash. Users are able to access pefile's imphash via pefile.imphash. When constructing queries, it's important to understand this hierarchy and formulate queries accordingly.

The following sections expand on each class of Attribute along with CLI examples that leverage the Attributes.

This documentation does not cover every searchable attribute of an Artifact. We focus our examples and description on the most commonly used attributes to understand the principles.

To retrieve the full list of attributes that are searchable, you can use the CLI command polyswarm search mapping, more information is available here

If we're missing something you'd like to be able to search for, please get in touch!

Artifact Attributes

Attributes that provide contextual and surface-level information about Artifacts are available under the artifact Scope.

The following artifact Attributes are supported:

artifact
- id - a unique identifier for the Artifact within PolySwarm
- created - timestamp indicating when the Artifact became available on PolySwarm
- sha256 - the SHA256 hash of the Artifact
- md5 - the MD5 hash of the Artifact
- sha1 - the SHA1 hash of the Artifact

The Attribute required to query for an instance of EICAR sha256 hash via Metadata Search, would therefore be artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f". This would then be the argument for the polyswarm search metadata command.

Scan Attributes

Attributes that describe Scans executed against Artifacts are available under the scan Scope.

The following scan Attributes are supported:

scan
- filename - (DEPRECATED) observed filename(s) for the Artifact
- url - (DEPRECATED; Exists for URL Artifacts Only) observed URLs for the Artifact
- countries - (See Deprecation Note Below) countries from which a Scan was initiated on the Artifact
- mimetype - mime type information
  - extended - extended mime information, e.g., "PE32 executable (GUI) Intel 80386, for MS Windows"
  - mime - mime type, e.g. "application/x-dosexec", see File Types for more examples
- first_seen - (DEPRECATED) UTC date of when the Artifact was first scanned
- last_seen - (DEPRECATED) UTC date of when the Artifact was last scanned
- first_scan / latest_scan - the first / most recent Scan Results Set
  - artifact_instance_id - a unique identifier for the Scan Result Set
  - created - UTC date when the Artifact was first/last scanned
  - detections
    - benign - number of Engines that asserted that the Artifact is benign in this Scan Result Set
    - malicious - number of Engines that asserted that the Artifact is malicious in this Scan Result Set
    - unknown - number of Engines that did not finalize (reveal) their assertion
    - total - number of Engines that asserted in this Scan Result Set
  - filename - filename of Artifact, if artifact was a FILE Artifact
  - url - url of Artifact, if artifact was a URL Artifact
  - An array of objects, each describing an Engine (e.g. ClamAV)'s response in the Result Set. See Engine Result Objects for a breakdown.

Deprecations:

The scan.filename Attribute is deprecated. Please use scan.[first_scan|latest_scan].filename.

The scan.url Attribute is deprecated. Please use scan.[first_scan|latest_scan].url.

The scan.first_seen and scan.last_seen Attributes are deprecated. Please use scan.[first_scan|latest_scan].created.

The scan.countries Attribute will soon be replaced by artifact.countries.

PolySwarm maintains a record of all Scan Result Sets, but only the first Scan (scan.first_scan) and latest Scan (scan.latest_scan) are generally available via Metadata Search.

If you have a use case for querying against more/all Scan Result Sets, please get in touch and let's discuss!

Mime file Types

The following is a list of common mimetypes useful for querying via scan.mimetype.mime.

MIME Types	Kind of document	Extension
application/gzip	GZip Compressed Archive	.gz
application/octet-stream	Any kind of binary data	.bin
application/pdf	Adobe Portable Document Format	.pdf
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Microsoft Excel 2007+ (OpenXML)	.xlsx
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Microsoft Word 2007+ (OpenXML)	.docx
application/x-dosexec	PE32 executable	.exe
application/x-java-applet	Compiled Java class data	.class
application/x-rar	RAR archive data	.rar
application/xml	XML	.xml
application/zip	ZIP archive	.zip
text/html	HyperText Markup Language (HTML)	.htm .html
text/plain	Text, (generally ASCII or ISO 8859-n)	.txt

A list of all official MIME media types provided by IANA can be found here.

Scan Engine Result Objects

Attributes that describe a given Engine's assertion (malicious or benign), identified malware_family (as applicable) and additional optional data are available under the scan.<NAME OF SCAN>.<ENGINE NAME> (e.g. scan.latest_scan.ClamAV) Scope.

Remember: In PolySwarm, Engines are not required to provide responses to Scan requests. For this and other reasons (e.g. in the case of errors), any particular Engine may or may not appear within the scan.<NAME OF SCAN> scope. An Engine that appeared in scan.first_scan may or may not appear in scan.latest_scan and vice versa.

Things to keep in mind:

Although unlikely, 0 Engines may choose to respond to any given Scan Request, resulting in 0 Engine Result Objects for the given Scan Result Set. Do not assume there is at least 1 Engine Result Object on any given Scan Result Set.

Do not assume that any particular Engine produced an Engine Result Object for a given Scan Result Set.

Using the Attribute artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" in the CLI command polyswarm search metadata will produce part of the below output:

{
    ...
    "scan": {
        ...
        "first_scan": {
            ...
            "ClamAV": {
                "assertion": "malicious",
                "metadata": {
                    "malware_family": "Eicar-Test-Signature"
                }
            },

This Engine Result Object provides the following information:

scan.first_scan.ClamAV.assertion: malicious / benign determination
scan.first_scan.ClamAV.metadata.malware_family: the identified malware family name of the Artifact

Tool Attributes

Metadata Extraction Tools are applied on a per-Artifact basis according to some relevancy criteria.

Attributes produced by each Tool are addressed at the top level by the Tool's name. The following Tools are supported:

hash - computes various hash functions on Artifacts. Applies to all file Artifacts.
- authentihash - (string) a SHA256 hash used by Microsoft that "verifies that the software has not been tampered with since it was signed and published".
- ssdeep - (string) a fuzzy hash algorithm designed to collide on sufficiently similar files. Metadata searching an Artifact's fuzzy hash may return similar file results.
- ssdeep_chunk - (string) refer to ssdeep documentation
- ssdeep_chunk_size - (int) refer to ssdeep documentation
- ssdeep_double_chunk - (string) refer to ssdeep documentation
- tlsh - (string) Trend Micro Locality Sensitive Hash
- tlsh_quartiles_minimum_match - (int) refer to tlsh documentation
- tlsh_quartiles - (array of strings) refer to tlsh documentation
- md5 - (string) the MD5 hash of the Artifact
- sha1 - (string) the SHA-1 hash of the Artifact
- sha256 - (string) the SHA-256 hash of the Artifact
- sha512 - (string) the SHA-512 hash of the Artifact
- sha3_256 - (string) the SHA-3-256 hash of the Artifact
- sha3_512 - (string) the SHA-3-512 hash of the Artifact
strings - extracts string-like sequences from Artifacts. Applies to all file Artifacts.
- domains - (array of strings) strings that look like Domain names
- urls - (array of strings) strings that look like URLs (including things like emails)
- ipv4 - (array of strings) strings that look like IPv4 addresses
- ipv6 - (array of strings) strings that look like IPv6 addresses
lief - extracts information from executables. Applies to Linux (ELF), Windows (PE) and Java executable Artifacts.
- has_nx - (bool) indicates whether the executable was compiled with NX protections (referred to as DEP on Windows)
- is_pie - (bool) indicates whether the executable is compatible with a fully randomized address space (full ASLR)
- libraries - (array of strings) list of imported libraries
- entrypoint - (string) entrypoint in decimal notation
- virtual_size - (string) virtual size in decimal notation
- exported_functions - (array of strings) list of exported functions
- imported_functions - (array of strings) list of imported functions
- virtual_size - (int) size of the executable when mapped into a process space
pefile - extracts information from Windows executables. Refer to pefile documentation for a description of these fields. Applies to Windows (PE) executable Artifacts.
- app_container - (bool)
- compile_date - (string)
- compile_date_utc - (string)
- exports - (array of strings)
- force_integrity - (bool)
- force_no_isolation - (bool)
- has_debug_info - (bool)
- has_export_table - (bool)
- has_import_table - (bool)
- high_entropy_aslr - (bool)
- imphash - (string) "import hash". Use this to find other Windows executables that import the same functions. Examples provided later.
- imports - (object) dictionary of imports in format dllname: [list, of, functions]
- imported_functions - (array of strings)
- is_dll - (bool)
- is_driver - (bool)
- is_exe - (bool)
- is_probably_packed - (bool)
- is_suspicious - (bool, can be null)
- is_valid - (bool, can be null)
- libraries - (array of strings) array of imported libraries (DLLs)
- no_bind - (bool)
- pdb - (array of strings) PDB paths referenced in the Artifact. Useful for finding attacker OPSEC mistakes / false flags. Examples provided later.
- pdb_guids - (array of strings)
- terminal_server_aware - (bool)
- uses_aslr - (bool)
- uses_cfg - (bool)
- uses_dep - (bool)
- uses_seh - (bool)
- verify_checksum - (bool)
- warnings - (array of strings) warnings generated during pefile execution
- wdm_driver - (bool)
exiftool - pull assorted Attributes from a wide range of file types. Particularly useful for indicators in office documents. Applies to executables, documents, images, videos and fonts.
- Author - (string) author of the file, e.g. Theresia Ward
- build - (string) e.g. August 2018
- CharacterSet - (string) character set of file, e.g. Unicode
- codesize - (int) code size of PEs
- comments - (string) e.g. background challenge Licensed
- company - (string) e.g. Cremin LLC
- entrypoint - (string) entry point of PEs as a hexademicimal string, e.g. 0x13f0
- CreateDate - (string) creation time string from document
- filedescription - (string) e.g. GlowEffect MFC Application
- filename - (string) DO NOT USE
- filesize - (int) the size of the Artifact in bytes
- filetype - (string) e.g. Win64 DLL
- filetypeextension - (string) file type extension (e.g., 'exe', 'dll', 'pdf')
- initializeddatasize - (int) size of the initialized .data section in PEs
- InternalName - (string) internal name extracted from executable, e.g. GlowEffect
- Language - (string) language of file, e.g. 'en-GB'
- LanguageCode - (string) language used by executable, e.g. English (U.S.)
- lastmodifiedby - (string) e.g. Arturo Cole
- linkerversion - (int) linker version used to compile executables, e.g. 14.0
- manager - (string) e.g. Hayes
- mimetype - (string)
- machinetype - (string) a string describing the CPU type supported by the executable Artifact, e.g. ARM little endian or Intel 386 of later, and compatibles
- ModifyDate - (string) last modified time string from document
- OriginalFileName - (string) original name of the file
- osversion - (string) the version of the operating system supported by the executable Artifact, e.g. 5.0 (for Windows)
- petype - (string) type of (Windows) Portable Executable (PE), e.g. ROM Image, PE32 and PE32+
- sourcefile - (string) DO NOT USE
- Subject - (string) subject of the file, e.g. Plastic
- subsystem - (string) type of Windows subsystem supported by the executable Artifact, e.g. Windows GUI, XBOX, EFI application
- subsystemversion - (string) version string for the subsystem
- timestamp - (string) timestamp of the file, e.g. 2018:03:13 07:19:15+00:00
- Title - (string) title of the file, e.g. transmit
- zipcrc - (string) the CRC checksum of ZIP files as a hexadecimal string
- zipfilename - (string) e.g. [Content_Types].xml
- zipmodifydate - (string) e.g. 2008:04:16 07:40:25

Several exiftool fields are marked as DO NOT USE.

These fields are currently being "clobbered" via our partner feed ingestion process and therefore should not be relied on yet.

We'll remove these notices when these fields contain descriptive values.

Searching for Further Attribute Fields

Further Attribute Fields are available within PolySwarm outside of the values listed already. PolySwarm provides an easy CLI command that enables the functionality of searching through these fields to use in the metadata commands.

Request

$ polyswarm search mapping | grep cape | grep file

Response

 |  |  |  |  +-cape_sandbox_v2.behavior.enhanced.data.file
 |  |  |  +-cape_sandbox_v2.behavior.summary.delete_files
 |  |  |  +-cape_sandbox_v2.behavior.summary.files
 |  |  |  +-cape_sandbox_v2.behavior.summary.read_files
 |  |  |  +-cape_sandbox_v2.behavior.summary.write_files
 |  |  +-cape_sandbox_v2.cape_config.Copy file
 |  |  +-cape_sandbox_v2.cape_config.Delete file
 |  |  +-cape_sandbox_v2.cape_config.Hide file
 |  |  +-cape_sandbox_v2.cape_config.Hide keylog file

Metadata Syntax

Metadata Search supports Elasticsearch's query_string syntax, providing flexibility through:

Boolean logic, e.g. AND, OR & NOT
grouping Boolean terms
ranges, e.g. date:[2012-01-01 TO 2012-12-31]
comparison operators (>, <=, etc.)
wildcards
regular expressions

... and a lot more.

Always enclose literals in double-quotations ("), or, alternatively, escape all Elasticsearch control characters in your query.

For example, URLs contain Elasticsearch control characters. Failing to escape these control characters to enclose a queried URL in quotations will result in errors.

Doesn't work: strings.urls:https://polyswarm.network - due to the second exact value match operator (:)

Works: strings.urls:"https://polyswarm.network"

Also works: strings.urls:https\://polyswarm.network

Exact Value Match

Metadata query syntax supports exact value matching via the : operator.

The following will return all Artifacts for which the hash Tool reported an MD5 value of e90099d6f3078a9691ab8fe38f0f25e4.

hash.md5:"e90099d6f3078a9691ab8fe38f0f25e4"

This will either return 0 or 1 results, modulo MD5 colliding Artifacts.

Boolean Operators

Metadata query syntax supports Boolean operators that allow users to combine clauses into more powerful queries.

Supported operators:

AND
OR
NOT

... and a lot more.

You may combine multiple attributes matches in your query using boolean operators:

scan.first_scan.ClamAV.assertion:benign AND scan.latest_scan.ClamAV.assertion:malicious

This query will return all Artifacts that were first flagged by ClamAV as benign, but on their latest scan are now found to be malicious.

You may also use Boolean operators for attribute values:

scan.mimetype.mime:("application/x-dosexec" OR "application/x-java-applet")

Will search for all artifacts with MIME Type application/x-dosexec OR application/x-java-applet.

Comparison Operators

Metadata query syntax supports comparing values.

Supported comparisons:

>: greater than
<: less than
>=: greater than or equal to
<=: less than or equal to

The following will return all artifacts with at least one benign assertion.

scan.latest_scan.detections.benign:>0

Grouping

Metadata query syntax supports grouping Boolean operators and clauses using parentheses.

The following will return all Artifacts that, on their latest scan, were detected by 1, 2 or 3 engines as malicious OR were detected by ClamAV as malicious:

(scan.latest_scan.detections.malicious:>0 AND scan.latest_scan.detections.malicious:<=3) OR scan.latest_scan.ClamAV.assertion:malicious

Ranges

Metadata query syntax supports ranges using the TO operator.

This query:

scan.latest_scan.detections.benign:>=0 AND scan.latest_scan.detections.benign:<=10

... can be simplified to this:

scan.latest_scan.detections.benign:[0 TO 10]

Square brackets ([ & ]) match inclusively with respect to range boundaries, whereas curly brackets ({ & }) match exclusively. In the above query, 0 and 10 are included in the range of matching values.

If we replace the square bracket next to the 10 with a curly bracket:

scan.latest_scan.detections.benign:[0 TO 10}

... then 10 is not a matching value. The number of benign assertions on a scan is an integer value, so the matching range becomes 0 to 9, inclusive.

In addition to fields containing numbers, ranges can be applied to dates. The following will return all artifacts with an exiftool-identified createdate falling in the year 2019.

exiftool.createdate:[2019-01-01 TO 2019-12-31]

Wildcards

Metadata query syntax supports wildcard matching using the * character.

The following will return all Artifacts that, on their latest scan, were identified by ClamAV as belonging to a malware family that contains the string Trojan:

scan.latest_scan.ClamAV.metadata.malware_family:*Trojan*

This would match on Artifacts that belong to, e.g. Trojan-Ransom.Satan and Trojan.Packed2.39908 families.

Wildcards can be used for Attribute names as well, but must be escaped.

The following will return all Artifacts identified as belonging to a malware family that includes the string Trojan by any Engine:

scan.latest_scan.\*.metadata.malware_family:*Trojan*

Note: Do not escape * in values, only in Attribute names.

Regular Expressions

Metadata query syntax supports regular expression matching on Attribute values.

The following will return all Artifacts that are ELF executables AND export functions that match the regular expression /.*Shooter(Sound|Ping|Key|Image|File).*/, e.g. ShooterSound:

exiftool.FileType:"ELF executable" AND lief.exported_functions:/.*Shooter(Sound|Ping|Key|Image|File).*/

This includes EvilGnome samples.

Regular expressions containing ^ (beginning of line) or $ (end of line) matching are not supported.

Check if the Attribute Exists

Metadata query syntax supports existence checking for Attributes.

The following query will return all Artifacts on which the lief Tool has been executed and has reported which libraries the Artifact imports:

_exists_:lief.libraries

Reminder: always check for the existence of an optional Attribute before attempting to match on the value of the optional attribute.

Failure to do so is will almost certainly produce unexpected results.

Using the IP,Domain and URL Arguments

The Metadata Search API and CLI provide convenience arguments to use when searching for IPs, Domains, and URLs. Each argument takes one parameter, but you can use the arguments multiple times in a single query. However, you can only use one type of argument per query.

These convenience arguments are:

--ip - for IPv4 addresses
--domain - for domain names
--url - for URLs

The following are some examples:

polyswarm search metadata --ip 2.2.2.2 --ip 192.0.0.1
polyswarm search metadata --domain polyswarm.io
polyswarm search metadata --url https://polyswarm.network/marketplace-stats --url https://polyswarm.io/team

Metadata Example Library

PolySwarm's Metadata Search is a powerful tool for finding unique variants and even completely new versions of malware.

In this section, we'll run through several real-world example hunts where new malware, including brand new versions of malware that hadn't be previously published, were found using PolySwarm's Metadata Search. Other Use Case examples are also provided like using jq to extract relevant information from the metadata.

Hunting Syrian Nation State Android Malware

Lookout published a blog post on COVID-19 related Android malware released by the Syrian Electronic Army.

The post discloses:

Where the command and control (C2) addresses are stored within the malicious applications (within res/values/strings.xml)
A list of SHA1 hashes of applications known to belong to this family of malware

First, we look up Lookout's first SHA1 hash on PolySwarm:

via the CLI (hash search): polyswarm search hash 1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08
via the CLI (metadata search using the hash): polyswarm search metadata 'hash.sha1:"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08"'

We have a hit!

Next, we download the Artifact (using your choice of Web UI, CLI or Python) and use apktool with the d flag to extract res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    ...
    <string name="MT_Bin_dup_0x7f0c0020">Android Telegram</string>
    <string name="MT_Bin_dup_0x7f0c0021">10000</string>
    <string name="MT_Bin_dup_0x7f0c0022">82.137.218.185</string>
    ...
</resources>

It appears as though the C2 address is 82.137.218.185. This information was not published in Lookout's blog post.

We can use Metadata Search to "pivot" using this IP(v4) address:

via the CLI: polyswarm search metadata --ip 82.137.218.185

At the time of writing, we see:

50 results,
at least 23 of which were not identified by Lookout in their blog post, and
at least 5 of which cannot be found on platforms similar to PolySwarm.

Using PolySwarm, researchers can quickly identify additional variants of malware and produce something that immediately expands on the public knowledge of the threat.

Hunting Iranian Nation State Spyware

ZDNet published an article on Iran's official COVID-19 tracker application that sends the real time location of installees to the Iranian government.

The article provides only a single IOC - a SHA256 hash (0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b) we can find on PolySwarm:

via the CLI (hash search): polyswarm search hash 0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b
via the CLI (metadata search using the hash): polyswarm search metadata 'hash.sha256:"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b"'

Let's take a look some of the Metadata Attributes from this Artifact:

{
    "artifact": {
        "created": "2020-03-10T10:16:50.900548+00:00",
        "id": "71592690635387748",
        "md5": "766e5ecf6b1d86abf401ad9223de857d",
        "sha1": "f1271aa0ccf79d16b036bac5320ed4349af69b65",
        "sha256": "0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b"
    },
    ...
    "strings": {
        "domains": [
            "V.mr",
            "",
            "covid-19-e9057.appspot.com",
            "p.to",
            "II1046766097017-4va56jc12ajt308tpbuge0tc5iqla179.apps.googleusercontent.com",
            "b.mc",
            "YJ.cz",
            "6.om",
            "6.gm",
            "covid-19-e9057.firebaseio.com"
        ],
        ...
    }
}

There are several interesting domains extracted by the strings Tool:

covid-19-e9057.appspot.com
covid-19-e9057.firebaseio.com

It appears as though some portion of the Iranian government's backend for this app is Google's Appspot and Firebase services. This is mildly interesting because Google removed the application from their Play Store.

Next, we conduct a Metadata Search for the unique portion of these domains (covid-19-e9057) + a wildcard (*) to find additional Artifacts that contain these strings:

$ polyswarm --fmt sha256 search metadata 'strings.domains:covid-19-e9057*'

This search nets 4 Artifacts, all of which have been identified as malicious by Engines on PolySwarm. 3 of these Artifacts were, of course, not mentioned in the ZDNet article. Perhaps they have new functionality worth investigating!

Switching gears from Android to Windows malware, TrendMicro recently published a blog post on some malware exploiting the rise in Zoom popularity.

Among other tidbits mentioned in the article, this malware:

is a Powershell script,
that embeds a 7zip extractor, and
7zip-compressed Tor, coinminer (the actual malware) and (legitimate) Zoom installers

The malware will cause the victim machine to mine cryptocurrency if the infected computer is powerful enough (notably, has a discrete GPU) over Tor.

TrendMicro published a handful of IOCs, including a C2 URL: https://2no.co/1O5aW.

Again, we turn to Metadata search to find Artifacts that contain this URL:

via the CLI: polyswarm search metadata 'strings.urls:*2no.co*1O5aW'

We get 1 result, which was not part of the IOCs published by TrendMicro, but is clearly a PowerShell script exactly as described in their blog!

Hunt for Exploits

Often when identifying malware families, Engines on PolySwarm will name the malware family and the exploited vulnerability using its associated CVE number.

Users interested in vulnerability analysis and exploitation can use PolySwarm to find Artifacts that exploit known vulnerabilities!

via the CLI: polyswarm search metadata 'scan.latest_scan.\*.metadata.malware_family:*cve*'

At the time of writing, this query returns 12885 results!

Hunt WannaCry via its Killswitch Domain

WannaCry would not execute malicious logic if a particular, seemingly nonsense domain name could be resolved. Once this domain was registered, WannaCry propagation came to a halt. The domain registration was a bit of a "killswitch".

We can easily find samples of WannaCry by Metadata searching for its "killswitch" domain.

via the CLI: polyswarm search metadata "strings.domains:*iuqerfsodp9ifjaposdfjhgosurijfaewrwergwea.com"

Hunting EventBot

PolySwarm has been tracking the EventBot malware, a family of Android trojan applications that spread autonomously and seek to steal credentials.

For full details on the latest EventBot samples along with Metadata search tips for finding these samples on PolySwarm, please consult our Blog.

Processing Results with `jq`, Malicious Artifacts in the last 15 minutes

The following will find all Artifacts first seen in the first 15 minutes of April 14th, 2020 that were detected as malicious by more than 3 Engines, extract their SHA256s from JSON and write them to the file hash.txt:

polyswarm --fmt json search metadata 'scan.first_seen:[2020-04-14T00:00 TO 2020-04-14T00:15] AND scan.latest_scan.detections.malicious:>3' | jq -r '.artifact.sha256' > hash.txt

We see 879 results.

Next, we query these hashes for their PolySwarm and create a CSV value enumerating hash and PolyScore:

polyswarm --fmt json search hash -r hash.txt | jq -r '[.sha256, .polyscore|tostring] | join(", ")' > polyscore.txt

The resultant polyswarm.txt file contains:

$ head polyscore.txt
8105b93e3acb65b19d43febbb139f3184f9feff2ea78a3a615e6ae58ca6dfd5d, 0.9974553968361014
f1967ed3583fed9ca3b326b8df3cc362ac65420082d93dcbda91069a8c91d7c2, 0.9364975545636711
7c6a626eb58f8324689f8d63924adc6bc9131574b801917ce5514adce3cd8fcf, 0.5883349845592594
d1fb5cc4ffd5df4bfe967edc9203a79032fc58bb76bdc0e63c9f203fa43f1eef, 0.9175460331627756
ea8701c24a9c05ab81f314468ff802cfbbe501d6048392c6e0400f038ca34d21, 0.9684573626545542
c6b975b98330feb6f04dbf262632e4027e9c9d1a5f5cdb3ef0190f592eef64e3, 0.9446378922543466
21ad837771588fb0617431a2e4d77ea16c0b6b9b1e6263c8df21d51696aab79b, 0.9974553968361014
a8472100e89a3c5e7f38c3df86fd7ff2a0af657513672226afe2fcec873e24b0, 0.9175460331627756
3883d38baeae67939b893dcb97245af2c9592a75d53f06a328a6041a65d4379a, 0.9650102417745068
e8ab71339736c76fdeafc8eda8612a502cb723fe3137427bdfc5d6ee2720b90a, 0.9995237243129788

Processing Results with `jq`, Finding the Artifacts ssdeep fuzzy hash

Query for an instance of EICAr via Metadata Search: polyswarm --fmt pretty-json search metadata 'artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"'

Use the CLI &jq to determine the Artifact's ssdeep fuzzy hash

Request

$ polyswarm --fmt json search metadata 'artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"' | jq .hash.ssdeep

Processing Results with `jq`, Finding the ClamAV Engine Assertion

Using jq to output the scan.first_scan.ClamAV.assertion only for the artifact.sha256 metadata search

Request

$ polyswarm --fmt pretty-json search metadata "artifact.sha256:275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" | jq .scan.first_scan.ClamAV.assertion

Response

"malicious"

Processing Results with `jq`, Finding the md5 of a sha256

Using jq to output the artifact.md5 only for the artifact.sha256 metadata search

Request

$ polyswarm --fmt pretty-json search metadata "artifact.sha256:275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" | jq .artifact.md5

Response

"44d88612fea8a8f36de82e1278abb02f"

Processing Results with `jq`, Extract C2 IP's for a given hash

Find the C2 IP's that have been extracted by the triage sandbox based of a hash value.

Request

polyswarm --fmt json search hash e675677bb37b0f5d6a761c5ed4cf13fa53ef1fb579862f47944ce2715dda8f77 |jq -r '[.metadata[]|select(.tool == "triage_sandbox_v0")|.tool_metadata.extracted_c2_ips]'

Response

[
  [
    "95.171.16.42",
    "185.90.61.9",
    "5.1.81.68",
    "185.99.2.65",
    "134.119.191.11",
    "85.204.116.100",
    "78.108.216.47",
    "51.81.112.144",
    "194.5.250.121",
    "185.14.31.104",
    "185.99.2.66",
    "107.175.72.141",
    "192.3.247.123",
    "134.119.191.21",
....

Search for Artifact's based on a Cape Sandbox TTP

To find Artifact's that relate to a MITRE TTP, use the below cli command.

Request

polyswarm --fmt json search metadata 'cape_sandbox_v2.ttp:T1089'

Locate Hashes that are using the ddns.net C2 Domain

Find sha256 hashes that have been associated to the ddns.net C2 domain from either cape or triage sandboxes.

Request

polyswarm --fmt sha256 search metadata 'cape_sandbox_v2.network.dns.request:*.ddns.net OR triage_sandbox_v0.extracted.config.dns:*.ddns.net'

Response

c2e4997f1f88c1c6eef4e4f28af5f9da462e5510496cf3509ffbaf29d424ce35
0b2f244702c64a7e238175d8e33f6c8e7df3a2f20aaf362a56b716b130ccee23
067a9fabb4c4c4d3093a0ee6ff4d8c37426b14d4a7be8ca91424b8db4e51e675
d0b8ca9a2a2d4d431be17af9699f50bda16059fd29d0897d192cc0669d42f65c
c325629bbd6472571d868dae7ae47eab1b92012b7916d8e3b8118cd45fd4e581
....

Pivot on latent .pdb information in Windows Executables

FireEye published a blog post wherein they attribute threat actors using latent Windows debug information (.pdb paths) in malware executables.

We can use information extracted by the pefile Tool to search for Artifacts that include PDB paths.

via the CLI:

polyswarm search metadata 'pefile.pdb:*RControl*' - 10+ results
polyswarm search metadata 'pefile.pdb:*shellcode.pdb' - 142+ results
etc

IOC Searching

IOC Searching can be split into three groups of commands, these are:

Searching for Associated IOCs related to a Hash
Searching for Associated Hashes to an IP, URL, imphash or MITRE TTP
Check for known good domains and IPs

Searching for Associated IOCs

Format: polyswarm search ioc sha256 <hash>

Description: List associated IOCs to a Hash by referencing the hash value.

Request

$ polyswarm search ioc sha256 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40

Response

============================= IOCs =============================
ImpHash:
IPs: 1.2.3.4, 2.2.2.2
URLs: polyswarm.io
TTPs: T1060, T1053

Searching for Associated Hashes

Format: polyswarm search ioc ip <IP>

Replace ip above with domain, imphash, URL or MITRE TTP e.g. polyswarm search ioc domain <url>

Description: List associated Hashes to an IP, URL, imphash or MITRE TTP.

Request

$ polyswarm search ioc ip 1.2.3.4

Response

============================= IOCs =============================
SHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0a

Searching for Known Good Domains and IPs

Format: polyswarm search known -d <DOMAIN> -p <IP>

Description: Known good checking allows you to check for known good domains and IPs. If any of the list of domain or IP parameters you provide match a record, then you'll get a result.

Options

Option	Type	Required	Description
`-p`, `--ip`	string	true	IP to search on
`-d`, `--domain`	string	true	Domain to search on

Either -p or -d must be used in the command.

Request

$ polyswarm search known -d polyswarm.network

Response

============================= Known IOC =============================
ID: 67
type: domain
host: polyswarm.network
source: polyswarm
good: True

A word of caution with Known Good checking!

Our list of known good domains and IPs is not all-inclusive! Our goal for this feature is to provide an easy way to check the most common known good domains and IPs, so they can be excluded from analysis.

Tags/Lists/Families

PolySwarm researchers tag known malware samples with malware family names and attributes.

Below are some examples of using malware Families and Tags to identify Emotet - another malware family that PolySwarm has been tracking.

Emotet is a "downloader". By itself, it usually just offers the attackers the ability to install additional malware on target machines. TrickBot (an info stealer) and Ryuk (ransomware) are commonly installed via initial Emotet infection.

Using Tags

Format: polyswarm tag list

Description: PolySwarm tags are free-form attributes applied to known malware samples.

tags can describe attributes like malware family (e.g. EventBot), target operating system (e.g. Android), phishing campaign (e.g. COVID-19) and exploited vulnerabilities (e.g. CVE-2017-11882).

Request

$ polyswarm tag list

Response

Tag: Adware
Tag: AgentTesla
Tag: Android
Tag: Cerberus
Tag: COVID-19
Tag: CVE-2017-11882
Tag: Emotet
Tag: EventBot

Using Families

Format: polyswarm family list

Description: PolySwarm families are malware family names applied to known samples from a given family.

Families with an Emerging timestamp where listed on the PolySwarm homepage at the given time - these are particularly cutting edge or prominent in the news.

Request

$ polyswarm family list

Response

Family: Emotet
Emerging: 2020-06-06 08:23:35.997775

Family: EventBot
Emerging: 2020-06-10 17:15:54.789337

Family: NetWalker
Emerging: None

Using Links

Format: polyswarm link list --family <family>

Description: Artifacts are linked to tags and families.

Request

$ polyswarm link list --family Emotet

Response

SHA256: 8c8f9556b67c36cf23fea64e2f2086a5bbcddabd5c66b9847fac1c60c021eeba
First seen: 2023-04-29 22:17:41.507473
Tags: ['Banker', 'Unpacked', 'Trojan', 'PE32', 'Windows']
Families: ['Emotet']
Emerging: None

SHA256: dd168d5499cfd09ac35b70656983a2b5600bfea09319df5a4aa4260e20745111
First seen: 2023-04-29 14:24:31.835017
Tags: ['Banker', 'Unpacked', 'PE32', 'Windows', 'first_seen']
Families: ['Emotet']
Emerging: 2023-05-08 18:40:55.769796

Getting a list of SHA256 hashes for these artifacts is correspondingly as simple as: polyswarm link list --family Emotet | grep SHA256.

Sandboxing

Sandboxing in PolySwarm provides the ability to submit files directly to be sandboxed to either Cape or Triage, submit Artifacts already in PolySwarm to be sandboxed, and review what has been submitted to be sandboxed.

General Sandbox Questions & Answers

What is the difference between cape and triage. And when should they select one vs the other?

CAPE sandbox is specifically designed to extract malware payload and configuration files, hence the name CAPE (Config and Payload Extraction). It attempts to unpack malware so yara signatures can be used to identify a specific malware family and if it is supported by the different config and payload extractors the sandbox has then those data can be extracted. Triage on the other hand is designed to scale and process as many malware as possible in a given day. They also support other malware types such as android. The sandbox is well versed in tackling malware that have anti-sandbox evasion techniques.

If you want to gather more data from malware like a typical sandbox would and have a better chance of executing a malware regardless of whether it is using anti-analysis or anti-sandboxing techniques, Triage would be the best choice. If the you want to get malware payload or config data that includes IPs and domains that were not used during the sandboxing session and is kept in the malware's back pocket, then CAPE is the sandbox of choice.

URL Sandboxing is only supported using Triage as of today, we will update this section as further URL Sandboxing support is expanded.

List Sandbox Providers

Format: polyswarm sandbox providers

Description: List the supported sandbox providers, to include: sandbox name, sandbox VMs, and version information.

Note: For the sandbox vm parameter in the sandbox file and artifact commands, use the value of the slug field in the sandbox providers output.

Request

$ polyswarm sandbox providers

Response

============================= Provider =============================
slug: cape
name: cape
tool: cape_sandbox_v2
	============================= VM =============================
	architecture: x64
	id: 100
	language: English (United States)
	name: Microsoft Windows 10 Pro Build 19041
	os_name: Microsoft Windows 10 Pro
	os_version: 10.0.19041 Build 19041
	slug: win-10-build-19041
============================= Provider =============================
slug: triage
name: triage
tool: triage_sandbox_v0
	============================= VM =============================
	api_level: 30
	architecture: x64
	id: 201
	language: English (United States)
	name: android-11-x64
	os_name: Android 11 x64
	profile: droid
	slug: android-11-x64
	============================= VM =============================
	Architecture: x64
	id: 200
	language: English (United States)
	name: windows10-1703-x64
	os_name: Windows 10 1703 x64
	os_version: 10.0.15063 Build 15063
	profile: poly
	slug: win10-build-15063

Sandboxing a File

Want to know what files types are supported? See here

Format: polyswarm sandbox file <sandbox> <file path> --vm_slug <sandbox vm>

Description: Submit a new File stored locally to be sandboxed, define the sandbox name, file path or the optional sandbox vm. Sandbox Analysis will take around 2-5 minutes before the results can be accessed.

To find the sandbox name and sandbox vm see this section.

Options

Option	Type	Required	Description
`--vm_slug`	string	false	Define the Sandbox image to use.
`-z`, `--is-zip`	bool	false	Will handle the provided file as a zip and decompress server side.
`-p`, `--zip-password`	string	false	Used to provide a password to decompress the zip file with.
`--internet-disabled`	bool	false	Disable internet access in sandbox when processing the sample.

Request

$ polyswarm sandbox file triage ./tests/eicar.yara --vm_slug windows11-21h2-x64

Response

============================= Sandbox Task =============================
id: 30536618894625674
sha256: None
sandbox: triage
created: 2023-06-20T18:47:46.242045
community: pi
instance id: 95454528418762552
status: PENDING

Sandboxes have multiple returned statuses, these are listed below.

Status	What is it for?
`Success`	Finished processing correctly.
`Started`	Sandbox session has started.
`Collecting Data`	Sandbox session has been successful and data is being collected.
`Failed`	Sandbox session has failed, this can be due to many reasons.
`Pending`	Sandbox session is queued up and ready to start.
`Timed out`	Sandbox session has timed out and quota has not been reimbursed.
`Delayed`	Sandbox session has been delayed and will start soon.
`Failed with Quota Reimbursement`	Finished processing but failed, quota will be reimbursed.
`Timed out with Quota Reimbursement`	Delayed in the queue for too long, got timed out and then reimbursement.

Sandboxing a URL or QR Code

Format: polyswarm sandbox url <PROVIDER> [URL]

Description: Submit a URL to be sandboxed, define the sandbox PROVIDER name (e.g. triage or cape), the URL (unless --qrcode-file is used), and the optional sandbox vm and browser arguments.

To find the sandbox name and sandbox VMs see this section.

Options

Option	Type	Required	Description
`--vm_slug`	string	false	Define the Sandbox image to use.
`--browser`	string	false	Define a browser to detonate the url in, only `edge` supported.
`--qrcode-file`	string	false	Path of a QR Code image file that contains an URL as a payload.

Request

$ polyswarm sandbox url triage www.polyswarm.io --vm_slug windows11-21h2-x64

Response

============================= Sandbox Task =============================
id: 20806200704232355
sha256: None
sandbox: triage
created: 2024-02-22T10:51:48.722414
community: mainnet1
instance id: 7708689624900884
status: PENDING

Sandboxing an Existing Artifact

Format: polyswarm sandbox instance <PROVIDER> <atifact_id>

Description: Submit an already-scanned artifact for processing by the sandboxes. The required arguments are the Artifact id and the sandbox name.

To obtain the artifact_id required you can use the command polyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id' and for the sandbox and --vm_slug see here.

Options

Option	Type	Required	Description
`--vm_slug`	string	false	Define the Sandbox image to use.
`--internet-disabled`	bool	false	Disable internet access in sandbox when processing the sample.

Request

$ polyswarm sandbox instance triage 50667050680164455 --vm_slug windows11-21h2-x64

Response

============================= Sandbox Task =============================
id: 76509232912518724
sha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e
sandbox: triage
created: 2023-06-20T18:53:47.027083
community: pi
instance id: 5821643847114768
status: PENDING

Lookup Sandbox Task

Format: polyswarm sandbox lookup-id <task_id>

Description: Look up the status of a specific sandbox task with the ID.

The ID can be found once a file, or existing artifact has been submitted. CLI commands like sandbox search and sandbox my-tasks also provide the ID.

Request

$ polyswarm sandbox lookup-id 76509232912518724

Response

============================= Sandbox Task =============================
id: 76509232912518724
sha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e
sandbox: triage
created: 2023-06-20T18:53:47.027083
community: pi
instance id: 5821643847114768
status: STARTED

Lookup Latest Sandbox Task

Format: polyswarm sandbox lookup <PROVIDER> <hash>

Description: Look up the status of the latest sandbox task for a hash, including a list of files like pcap, jarm and report.

Feed the --fmt pretty-json option into the command to view the full metadata set of information.

Request

$ polyswarm sandbox lookup triage e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e

Response

============================= Sandbox Task =============================
id: 97818287069750641
sha256: 2345c426c584ec12f7a2106a52ce8ac4aeb144476d1a4e4b78c10addfddef920
sandbox: triage
created: 2023-06-26T15:21:30.054231
community: mainnet1
instance id: 29588752444918666
status: SUCCEEDED
sandbox artifacts:
	dropped_file: triage_dropped_file, PE32+ executable (GUI) x86-64, for MS Windows, instance id: 98765579577983166
	report: triage_report.json, application/json, instance id: 23250223674696404
	raw_report: triage_raw_report.json, application/json, instance id: 70519139222788003
	dropped_file: triage_dropped_file, PE32+ executable (DLL) (console) x86-64, for MS Windows, instance id: 76909336038197831
....

Note: Each file will have its own instance_id that will be required to download the artifact/file.

Download Sandbox Artifacts

Format: polyswarm download-id <instance id>

Description: Provides the ability to download Artifacts from the sandbox like the pcap, report and jarm files.

Each file will have its own instance_id, meaning each insatnce_id needs to be defined. To find the instance id of the file to download, use the polyswarm sandbox lookup cli command here. When you submit a file to be sandboxed, you get a SandboxTask ID. When the sandboxing is done, you can get the results for that sandboxtask. If you look at the json output, it will contain a SandboxArtifacts section. Each item in the SandboxArtifacts has an artifact ID.

Request

$ polyswarm download-id 76909336038197831

Response

Successfully downloaded artifact b1c52c16bd34314685b2147687d3d82d3032ad1066493538a9547a5b1cdf2254 to /Users/name/Desktop/b1c52c16bd34314685b2147687d3d82d3032ad1066493538a9547a5b1cdf2254

List my sandbox tasks

Format: polyswarm sandbox my-tasks

Description: List all the sandbox tasks submitted by you or anyone in your team with the status of these.

Options

Option	Type	Required	Description
`--provider`	string	false	Search on the sandbox name.
`--start-date`	string	false	Provide a start date for searching sandbox tasks.
`--end-date`	string	false	Provide a end date for searching sandbox tasks.
`--sha256`	string	false	Only list tasks with the SHA256 passed.

Request

$ polyswarm sandbox my-tasks

Response

============================= Sandbox Task =============================
id: 76509232912518724
sha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e
sandbox: triage
created: 2023-06-20T18:53:47.027083
community: pi
instance id: 5821643847114768
status: SUCCEEDED
account number: 582193978313
team account number: 582193978313

============================= Sandbox Task =============================
id: 30536618894625674
sha256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
sandbox: triage
created: 2023-06-20T18:47:46.242045
community: pi
instance id: 95454528418762552
status: PENDING
account number: 582193978313
team account number: 582193978313

Search Sandbox Tasks

Format: polyswarm sandbox search <HASH>

Description: Search sandbox tasks by sha256, sandbox provider, status, start date and/or end date in order to filter out the results.

Options

Option	Type	Required	Description
`--provider`	string	false	Search on the sandbox name.
`--status`	string	false	Filter by status i.e. pending.
`--start-date`	string	false	Provide a start date for searching sandbox tasks.
`--end-date`	string	false	Provide a end date for searching sandbox tasks.

Request

$ polyswarm sandbox search 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40

Response

============================= Sandbox Task =============================
id: 30536618894625674
sha256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
sandbox: triage
created: 2023-06-20T18:47:46.242045
community: pi
instance id: 95454528418762552
status: PENDING

Hunting with Yara

Managing Yara Rulesets

This section will walk through creating a Yara ruleset(s), viewing the ruleset contents, listing all rulesets, updating a ruleset and deleting a ruleset.

Creating a Ruleset

Format: polyswarm rules create eicar <file.yara>

Description: The first step to hunting with Yara rules is to create your Yara ruleset(s).

Options

Option	Type	Required	Description
`-d`, `--description`	string	false	Description of the ruleset.

Request

$ polyswarm rules create eicar eicar.yara

Response

Ruleset Id: 57611858371350090
Name: eicar
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:00:09.401395

View a Ruleset List

Format: polyswarm rules list

Description: It is also possible to list all the rulesets that exist in your account.

Request

$ polyswarm rules list

Response

Ruleset Id: 57611858371350090
Name: eicar
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:00:09.401395

Ruleset Id: 6094816616323164
Name: eicar
Description: None
Created at: 2022-05-26 18:42:41.806803
Modified at: 2022-05-26 18:45:04.864430

Inspect a Yara Ruleset Contents

Format: polyswarm rules view <Ruleset ID>

Description: You can use the Ruleset Id to inspect the contents of the Yara ruleset you created.

Find the Ruleset ID of the Ruleset with the command polyswarm rules list

Request

$ polyswarm rules view 57611858371350090

Response

Ruleset Id: 57611858371350090
Name: eicar
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:00:09.401395
Ruleset Contents:
rule eicar_av_test {
    /*
       Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
       The raw EICAR string to be matched is:
       X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    */

    meta:
        description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
        author = "Austin Byers | Airbnb CSIRT"
        reference = "http://www.eicar.org/86-0-Intended-use.html"

    strings:
        $eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/

    condition:
        all of them
}

rule eicar_substring_test {
    /*
       More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
    */

    meta:
        description = "Standard AV test, checking for an EICAR substring"
        author = "Austin Byers | Airbnb CSIRT"

    strings:
        $eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"

    condition:
        all of them
}

Update a Yara Ruleset

Format: polyswarm rules update <ruleset id> --name <NEW NAME> --file <file.yara>

Description: Update the ruleset using the update command or update the yara ruleset.

Options

Option	Type	Required	Description
`-n`, `--name`	string	false	Name of the ruleset.
`-f`, `--file`	string	false	File containing yara rules.
`-d`, `--description`	string	false	Description of the ruleset.

Request

$ polyswarm rules update 57611858371350090 --name EiCaR

Response

Ruleset Id: 57611858371350090
Name: EiCaR
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:03:09.500600

Deleting a YARA Ruleset

Format: polyswarm rules delete <Ruleset ID>

Description:Delete a ruleset if there is not a live hunt running associated with it.

Request

$ polyswarm rules delete 57611858371350090

Response

Ruleset Id: 57611858371350090
Name: EiCaR
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:03:45.551115

Live Hunting

Live Hunting offers users the valuable capability to employ a YARA ruleset for matching against artifacts submitted in real time to PolySwarm's extensive dataset.

Start a Live Hunt

Format: polyswarm live start <ruleset_id>

Description: Start a live hunt, Every live hunt that is active must be associated with a Yara ruleset. Because of this, you need to provide the rulset_id when starting a live hunt.

Request

$ polyswarm live start 57989886451857569

Response

Ruleset Id: 57989886451857569
Live Hunt Id: 86677820494666932
Live Hunt Created at: 2022-05-26T21:14:29.334580
Name: eicar
Description: None
Created at: 2022-05-26 18:48:38.048514
Modified at: 2022-05-26 21:14:29.207665

Stop a Live Hunt

Format: polyswarm live stop <ruleset_id>

Description: Similarly, you can stop a live hunt providing the ruleset_id it is associated with. When you start the live hunt for the same ruleset_id, a new live_hunt_id is generated. The Ruleset cannot be deleted or modified while it has an active live hunt associated with it.

Request

$ polyswarm live stop 57989886451857569

Response

Ruleset Id: 57989886451857569
Name: eicar
Description: None
Created at: 2022-05-26 18:48:38.048514
Modified at: 2022-05-26 21:17:29.079046

View Live Results of a Live Hunt

Format: polyswarm live feed

Description: You can see all the live results generated from all the live hunts in your feed. They are reverse chronologically ordered.

Options

Option	Type	Required	Description
`-r`, `--rule-name`	string	false	Filter results on the rule name
`-f`, `--family`	string	false	Filter hunt based on the family name
`-p`, `--private`	string	false	Filter results to only your Private Community, if not defined results are shown from your Private Community and the Public Community.
`-u`, `--polyscore-upper`	string	false	Polyscore upper bound for the hunt results

Request

$ polyswarm live feed

Response

Id: 32552275040389723
Instance Id: 33280875575725264
Created at: 2022-05-26 21:15:27.507020
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

Id: 34271764645034598
Instance Id: 33280875575725264
Created at: 2022-05-26 21:15:27.494428
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_av_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

View a Singular Result

Format: polyswarm live result <instance_id>

Description: You can inspect a particular result and get a download link using the result command.

Request>

$ polyswarm live result 32552275040389723

Response

Id: 32552275040389723
Instance Id: 33280875575725264
Created at: 2022-05-26 21:15:27.507020
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Download Url: http://minio:9000/cache-public/27/5a/02/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f3395856ce81f2b7382dee72602f798b642f1414044d88612fea8a8f36de82e1278abb02f?response-content-disposition=attachment%3Bfilename%3Dinfected&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T211923Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=52c1c289e0a9c86187224fbeeb6fa5122b8e9b0d196cc6440c00b665e168985c

Delete a Result

Format: polyswarm live results-delete <instance_id>

Description: You can also delete results from this list that are not interesting.

Request

$ polyswarm live results-delete 32552275040389723 # you can provide more ids here, separated by space

Response

Id: 32552275040389723
Instance Id: 33280875575725264
Created at: 2022-05-26 21:15:27.507020
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

Historical Hunting

Historical Hunting offers users the valuable capability to employ a YARA ruleset for matching against artifacts previously submitted in real time to PolySwarm's extensive dataset.

Start a Historical Hunt

Format: polyswarm historical start <file.yara>

polyswarm historical start -r <ruleset_id>

Provide the Yara ruleset directly or provide the ruleset id of the Yara Ruleset.

Description: Start a new historical hunt providing the ruleset directly.

Options

Option	Type	Required	Description
`-r`, `--rule-id`	integer	false	If provided, create this historical hunt from an existing ruleset.
`-n`, `--name`	string	false	Explicitly set the ruleset name for this hunt.

Request

$ polyswarm historical start tests/eicar.yara

Response

Hunt Id: 60834480310458457
Status: PENDING
Created at: 2022-05-26 21:24:20.712138
Ruleset Name: eicar.yara
Ruleset Contents:
rule eicar_av_test {
    /*
       Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
       The raw EICAR string to be matched is:
       X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    */

    meta:
        description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
        author = "Austin Byers | Airbnb CSIRT"
        reference = "http://www.eicar.org/86-0-Intended-use.html"

    strings:
        $eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/

    condition:
        all of them
}

rule eicar_substring_test {
    /*
       More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
    */

    meta:
        description = "Standard AV test, checking for an EICAR substring"
        author = "Austin Byers | Airbnb CSIRT"

    strings:
        $eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"

    condition:
        all of them
}

Historical hunt will activate upon creation. They are created in the PENDING state and are scheduled for execution during the next processing window.

View a Historical Hunt Status

Format: polyswarm historical list

Description: You can see the state of your historical hunts when you use the list command.

Options

Option	Type	Required	Description
`-s`, `--since`	integer	false	How far back in seconds to request results.

Request

$ polyswarm historical list

Response

Hunt Id: 86933257769414706
Status: PENDING
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar

Hunt Id: 60834480310458457
Status: PENDING
Created at: 2022-05-26 21:24:20.712138
Ruleset Name: eicar.yara

Hunt Id: 79157116618547376
Status: PENDING
Created at: 2022-05-26 19:07:25.339932
Ruleset Name: eicar.yara

Hunt Id: 48011760326110718
Status: LIMITED
Progress: 100.00%
Created at: 2022-05-26 17:53:07.832218
Total count: 6
	eicar_av_test: 3
	eicar_substring_test: 3
Ruleset Name: eicar.yara

Cancel a Historical Hunt

Format: polyswarm historical cancel <hunt_id>

Description: You can cancel a historical if you don't want it to finish by providing the hunt id. It will prevent further processing.

Request

$ polyswarm historical cancel 86933257769414706

Response

Hunt Id: 86933257769414706
Status: CANCELED
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar
Ruleset Contents:
rule eicar_av_test {
    /*
       Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
       The raw EICAR string to be matched is:
       X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    */

    meta:
        description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
        author = "Austin Byers | Airbnb CSIRT"
        reference = "http://www.eicar.org/86-0-Intended-use.html"

    strings:
        $eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/

    condition:
        all of them
}

rule eicar_substring_test {
    /*
       More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
    */

    meta:
        description = "Standard AV test, checking for an EICAR substring"
        author = "Austin Byers | Airbnb CSIRT"

    strings:
        $eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"

    condition:
        all of them
}

Delete a Historical Hunt

Format: polyswarm historical delete <hunt_id>

Description: You can also delete a historical hunt. The results associated with it will also be removed.

Since there can be a large number of results, this is an asynchronous task and might take a while to finish after it is requested.

Request

$ polyswarm historical delete 86933257769414706

Response

Successfully deleted Hunt:
Hunt Id: 86933257769414706
Status: DELETING
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar
Ruleset Contents:
rule eicar_av_test {
    /*
       Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
       The raw EICAR string to be matched is:
       X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    */

    meta:
        description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
        author = "Austin Byers | Airbnb CSIRT"
        reference = "http://www.eicar.org/86-0-Intended-use.html"

    strings:
        $eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/

    condition:
        all of them
}

rule eicar_substring_test {
    /*
       More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
    */

    meta:
        description = "Standard AV test, checking for an EICAR substring"
        author = "Austin Byers | Airbnb CSIRT"

    strings:
        $eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"

    condition:
        all of them
}

View or Download Historical Hunt Details

Format: polyswarm historical view <hunt_id>

Description: You can view details about the historical hunt and download a summary csv using the view command.

Request

$ polyswarm historical view 48011760326110718

Response

Hunt Id: 48011760326110718
Status: LIMITED
Progress: 100.00%
Created at: 2022-05-26 17:53:07.832218
Total count: 6
	eicar_av_test: 3
	eicar_substring_test: 3
Download Results CSV:
	http://minio:9000/historical/72/48/e9/7248e979625acf9f527e3ab7c8c0125e72e9b0a30b9a308b1617d475c8bcbf6bf27d52363bf2cd7b2359c70c6aac1de2ddad7daebc660cb805c99b51d4e4ff9648fe7eb1?response-content-disposition=attachment%3Bfilename%3D48011760326110718.csv&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213205Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=df334159d7a2a334f6fb0deffd6edc334f6f9188f4d29777b15a0575600114ff
Ruleset Name: eicar.yara
Ruleset Contents:
rule eicar_av_test {
    /*
       Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
       The raw EICAR string to be matched is:
       X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    */

    meta:
        description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
        author = "Austin Byers | Airbnb CSIRT"
        reference = "http://www.eicar.org/86-0-Intended-use.html"

    strings:
        $eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/

    condition:
        all of them
}

rule eicar_substring_test {
    /*
       More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
    */

    meta:
        description = "Standard AV test, checking for an EICAR substring"
        author = "Austin Byers | Airbnb CSIRT"

    strings:
        $eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"

    condition:
        all of them
}

View Results of a Historical Hunt

Format: polyswarm historical results <hunt_id>

Description: You can see the results of a particular hunt using its hunt_id.

Options

Option	Type	Required	Description
`-r`, `--rule-name`	string	false	Filter results on the rule name
`-f`, `--family`	string	false	Filter hunt based on the family name
`-p`, `--private`	string	false	Filter results to only your Private Community, if not defined results are shown from your Private Community and the Public Community.
`-l`, `--polyscore-lower`	string	false	Polyscore lower bound for the hunt results
`-u`, `--polyscore-upper`	string	false	Polyscore upper bound for the hunt results

Request

$ polyswarm historical results 48011760326110718

Response

Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

Id: 89734617019442134
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_av_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

Id: 55984849350345511
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

View or Download a Single Result of a Historical Hunt

Format: polyswarm historical result <id>

Description: You can inspect details and download the file for a result with the result command. You will need the ID which you can find with the polyswarm historical view <hunt_id> command.

Request

$ polyswarm historical result 34417123788028549

Response

Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Download Url: http://minio:9000/cache-public/27/5a/02/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f3395856ce81f2b7382dee72602f798b642f1414044d88612fea8a8f36de82e1278abb02f?response-content-disposition=attachment%3Bfilename%3Dinfected&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213355Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=bdd77765df45c068cd8f0d16580363003f9490ead7f4ff758aeada39bdcf9f96

Delete Historical Hunt Results

Format: polyswarm historical results-delete <id>

Description: You can delete an undesirable result by providing the ID or a list of ID's.

Request

$ polyswarm historical results-delete 34417123788028549 # you can provide a list of ids here, space separated

Response

Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}

Cat Artifacts

Format: polyswarm cat <hash> |hexdump -C

Description: Cat artifact to stdout. Perform feature extraction from artifact without downloading.

Request

$ # Get C&C from malware config
$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |hexdump -C

>Response

00000000  c3 3e 34 65 04 b3 00 00  00 00 00 00 00 00 00 00  |.>4e............|
00000010  6c f7 51 3a 6b 01 00 00  1e 00 02 00 e8 03 00 00  |l.Q:k...........|
00000020  10 27 00 00 c0 d4 01 00  c0 d4 01 00 e0 93 04 00  |.'..............|
00000030  c0 27 09 00 10 27 00 00                           |.'...'..|
00000038
$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |od -An -t u1 -N 4|sed 's/^ //;s/\s\{1,\}/./g'
195.62.52.101

Chain commands

Some commands in the CLI are composable using the sha256 format option and the unix pipe character |. For instance, if we wanted to download all the results matching a metadata query:

Request

$ polyswarm --fmt sha256 search metadata 'strings.domains:malicious.com' | polyswarm download malicious -r -

Response

Successfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/malicious/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267

Or we may want to download the last new samples matched in Live Hunting for the last 1 hour:

Request

$ polyswarm --fmt sha256 live feed -s 3600 | polyswarm download /tmp/download -r -

Response

Successfully downloaded artifact 513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831 to /tmp/download/513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831
Successfully downloaded artifact 7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724 to /tmp/download/7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724
Successfully downloaded artifact 2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9 to /tmp/download/2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9
Successfully downloaded artifact a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875 to /tmp/download/a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875
Successfully downloaded artifact b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce to /tmp/download/b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce
Successfully downloaded artifact bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142 to /tmp/download/bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142
Successfully downloaded artifact ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6 to /tmp/download/ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6
Successfully downloaded artifact a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4f to /tmp/download/a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4f

Lookup UUIDs

Format: polyswarm rules create eicar <file.yara>

Description: Scan results are referenced by their Submission UUID.

Request

$  polyswarm -vvv -o /tmp/test.json --fmt json lookup 50446025732260182

In this example, we demonstrate the --fmt json option, which saves the output in json format.

Response

info [polyswarm.base]: Running polyswarm-cli version 2.0.0 with polyswarm-api version 2.0.0
debug [polyswarm_api.api]: Creating PolyswarmAPI instance: api_key: cc2fdb7efa803cefcebd3c9750aab0ee, api_uri: https://api.polyswarm.network/v2, community: default
debug [polyswarm_api.http]: Creating PolyswarmHTTP instance
debug [polyswarm_api.endpoint]: Creating PolyswarmRequestGenerator instance
debug [polyswarm_api.endpoint]: Creating PolyswarmRequest instance.
debug [polyswarm_api.endpoint]: Request parameters: {'method': 'GET', 'url': 'https://api.polyswarm.network/v2/consumer/submission/default/50446025732260182'}
debug [polyswarm_api.endpoint]: Result parser: ArtifactInstance
debug [polyswarm_api.endpoint]: Executing request.
debug [urllib3.connectionpool]: Starting new HTTPS connection (1): api.polyswarm.network:443
debug [urllib3.connectionpool]: https://api.polyswarm.network:443 "GET /v2/consumer/submission/default/50446025732260182 HTTP/1.1" 200 None
debug [polyswarm_api.endpoint]: Request returned code 200 with content:
debug [polyswarm_api.endpoint]: b'{"result":{"artifact_id":"79510820469876527","assertions":[{"author":"0x45b94B4AFE4E4B5Bd7f70B84919fba20f1FAfB3f","author_name":"Qihoo 360","bid":"1000000000000000000","engine":{"description":null,"name":"Qihoo 360"},"mask":true,"metadata":{"malware_family":"qex.eicar.gen.gen","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}}},"verdict":true},{"author":"0xbec683492f5D509e119fB1B60543A1Ca595e0Df9","author_name":"Lionic","bid":"1000000000000000000","engine":{"description":null,"name":"Lionic"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}}},"verdict":false},{"author":"0x162675F361F6ff8D6F91e4833f4BA94587AF3655","author_name":"XVirus","bid":"812500000000000000","engine":{"description":null,"name":"XVirus"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"vendor_version":"3.0.2.0","version":"0.2.0"}},"verdict":false},{"author":"0x80Ed773972d8BA0A4FacF2401Aca5CEba52F76dc","author_name":"Nucleon","bid":"1000000000000000000","engine":{"description":"Nucleon, The only provider that guarantees 0% false positive. using Nucleon unique offering organizations can reduce thier TCO dramtically and enjoy cyber intelligence like governments have.","name":"Nucleon"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"","version":"0.1.0"}},"verdict":false},{"author":"0x8d80CEe474b9004949Cf7e4BfA28460AC8e370a1","author_name":"Virusdie","bid":"1000000000000000000","engine":{"description":null,"name":"Virusdie"},"mask":true,"metadata":{"malware_family":"EICAR.TEST","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"1.3.0","version":"0.3.0"}},"verdict":true},{"author":"0x7839aB10854505aBb712F10D1F66d45F359e6c89","author_name":"Ikarus","bid":"1000000000000000000","engine":{"description":null,"name":"Ikarus"},"mask":true,"metadata":{"malware_family":"EICAR-Test-File","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"signatures_version":"21.02.2020 13:15:46 (102417)","vendor_version":"5.2.9.0","version":"0.2.0"}},"verdict":true},{"author":"0x3750266F07E0590aA16e55c32e08e48878010f8f","author_name":"ClamAV","bid":"1000000000000000000","engine":{"description":null,"name":"ClamAV"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"ClamAV 0.101.4/25730/Fri Feb 21 12:08:06 2020"}},"verdict":false},{"author":"0x10A9eE8552f2c6b2787B240CeBeFc4A4BcB96f27","author_name":"Alibaba","bid":"1000000000000000000","engine":{"description":null,"name":"Alibaba"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}},"type":"eicar"},"verdict":false},{"author":"0xbE0B3ec289aaf9206659F8214c49D083Dc1a9E17","author_name":"K7","bid":"1000000000000000000","engine":{"description":null,"name":"K7"},"mask":true,"metadata":{"malware_family":"EICAR_Test_File","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"signatures_version":"11.95.33362, 21-Feb-2020","vendor_version":"15.2.0.42","version":"0.2.0"}},"verdict":true},{"author":"0x2b4C240B376E5406C5e2559C27789d776AE97EFD","author_name":"NanoAV","bid":"1000000000000000000","engine":{"description":null,"name":"NanoAV"},"mask":true,"metadata":{"malware_family":"Marker.Dos.EICAR-Test-File.dyb","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"signatures_version":"0.14.33.17090","vendor_version":"1.0.134.90567","version":"0.1.0"}},"verdict":true},{"author":"0xb9b1FA288F7b1867AEF6C044CDE12ab2De252113","author_name":"VenusEye","bid":"812500000000000000","engine":{"description":null,"name":"VenusEye"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"version":"0.1.0"}},"verdict":false},{"author":"0xBAFcaF4504FCB3608686b40eB1AEe09Ae1dd2bc3","author_name":"DrWeb","bid":"1000000000000000000","engine":{"description":null,"name":"DrWeb"},"mask":true,"metadata":{"malware_family":"EICAR Test File (NOT a Virus!)","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"signatures_version":"864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42","vendor_version":"7.00.44.12030","version":"0.3.0"}},"verdict":true}],"community":"lima","country":"US","created":"2020-02-21T19:21:59.196578","extended_type":"EICAR virus test files","failed":false,"filename":"malicious.txt","first_seen":"2020-01-24T21:56:21.456900","id":"50446025732260182","last_seen":"2020-02-21T19:21:59.196578","md5":"a6a57bf20416a4c712c4a1eabcaeb235","metadata":[{"created":"2020-02-20T22:29:45.801434","tool":"strings","tool_metadata":{"domains":[],"ipv4":[],"ipv6":[],"urls":[]}},{"created":"2020-02-20T22:29:45.675692","tool":"hash","tool_metadata":{"md5":"a6a57bf20416a4c712c4a1eabcaeb235","sha1":"a33fb79e9c71f1b446607d437a1984602ed47d5c","sha256":"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf","sha3_256":"ab1256000f634456fac4fe42bbc0bf39256e4bab954dc8c8f241433d07895fad","sha3_512":"737ec00fa15de1defdca9993c7d95058c2f30b658ef66c8b978287c1042d7ba7283d8d1130c356fbb8058bd739c5e349169ad93f4f428a830720ee107c6df288","sha512":"2f79598bc355b385be7c7b785ec74073bf4b59b8095c1b1f7291e0dd04e5e140f700bcc583809ec63d6d98991698273c1678bd3399ec0b1b8ba9f60be151ec3b","ssdeep":"3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX","tlsh":"ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8"}}],"mimetype":"text/plain","polyscore":0.07193209420451106,"result":null,"sha1":"a33fb79e9c71f1b446607d437a1984602ed47d5c","sha256":"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf","size":132,"type":"FILE","votes":[{"arbiter":"0xB63cD054D7E63D9Ce8AbB403a0dfa11b26A1fB89","vote":false},{"arbiter":"0xd8b48Da78188312c5fC079E532afd48De973767E","vote":true},{"arbiter":"0xdC6a0F9C3AF726Ba05AaC14605Ac9B3b958512d7","vote":false}],"window_closed":true},"status":"OK"}\n'
debug [polyswarm_api.endpoint]: Parsing request results.
debug [polyswarm_api.types.base]: Parsing resource ArtifactInstance

For information regarding the JSON format of a result object, please see polyswarm-api's API.md.

Changelog

Version 3.8.1

Release Date: 2024-09-24 Breaking Changes: N/A

Item	Topic	Description
1.0	Updated Validation URL	Less strict validation on URLs provided as an argument when scanning and sandboxing.
2.0	Error Reporting	Scans and Sandboxing now shows the Faliure Reason if applicable in the cli response.
3.0	Bug Fix Sandbox	Fixed exception when sandbox doesn't have the `config.artifact_type` field set.

Version 3.8.0

Release Date: 2024-08-07

Breaking Changes: Item 5.0

Item	Topic	Description
1.0	Submit URL from QR Code images	New arg `--qrcode-file` in `polyswarm scan url` and `polyswarm sandbox url`
2.0	Get basic account's information	New command `polyswarm account whois`.
3.0	Get account's features and quota available	New command `polyswarm account features`.
4.0	New options to create zip reports	`polyswarm report create [--sandbox_artifact_types --zip-report-ids]`
5.0	Rename command argument	`--sandbox` argument is renamed to `--provider`.

Version 3.7.0

Release Date: 2024-06-27

Breaking Changes: N/A

Item	Topic	Description
1.0	Wait and download reports	New `--nowait`, `--timeout` and `--destination` arguments in the `report` command.
2.0	Support zip file submissions	New `--is-zip` and `--zip-password` arguments in `scan` and `sandbox` commands.

Version 3.6.0

Release Date: 2024-05-20

Breaking Changes: Item 3.0

Item	Topic	Description
1.0	Reports Generation	Introduction of reports generation via the `report` CLI command.
2.0	Reports Templates	Introduction of reports templates management via the `report-template` CLI command.
3.0	Python versions supported	Minimal Python version supported is 3.7.

Version 3.5.2

Release Date: 2024-02-22

Breaking Changes: N/A

Item	Topic	Description
1.0	URL Sandboxing	Introduction of URL Sandboxing via the `sandbox url` cli command.

Version 3.5.1

Release Date: 2023-12-06

Breaking Changes: 1.0

Item	Topic	Description
1.0	IOC Search - Hash	Previously ioc search by hash returned a Generator, which was not correct. This fix has resolved this issue, to prevent the `has_more` flag being returned.

Version 3.4.1

Release Date: 2023-09-20

Breaking Changes: N/A

Item	Topic	Description
1.0	Added Private Parameter to Live Results	Added parameter `--private` to `polyswarm live feed` to allow you to see results from a private community.
2.0	Added Private Parameter to Historical Results	Added parameter `--private` to `polyswarm historical results` to allow you to see results from a private community.
3.0	New Permalink Structure	New Permalink Structure

Version 3.4.0

Release Date: 2023-07-12

Breaking Changes: N/A

Item	Topic	Description
1.0	`polyswarm sandbox providers`	New output with provider and slug information.
2.0	Update to `polyswarm sandbox file`	Added new config arguments `provider_slug` and `vm_slug`.
3.0	Update to `polyswarm sandbox instance`	Added new config arguments `provider_slug` and `vm_slug`.

Version 3.3.0

Release Date: 2023-06-20

Breaking Changes: Item 2.0

Item	Topic	Description
1.0	Dropping python 2.7 support	-
2.0	polyswarm sandbox submit changes	Change `polyswarm sandbox submit` to `polyswarm sandbox instance`.
3.0	polyswarm sandbox list changes	Change `polyswarm sandbox list` to `polyswarm sandbox providers`.
4.0	Additional Sub-Commands for Sandbox	lookup, lookup-id, search, file, my-tasks.

Version 3.2.1

Release Date: 2023-05-29

Breaking Changes: N/A

Item	Topic	Description
1.0	Bug fix for `search ioc`	Fix an issue with results not displaying with the `polyswarm search ioc` command.

PolySwarm Customer CLI v3

Getting Started

Installation

Upgrade

Configuration

Using the PolySwarm CLI

General Usage

Further Usage Details

Retrieve account information

Account details

Account features and quotas

Private Communities

Scanning an Artifact

Scan a File

Scan a URL

Rescanning an Artifact

Downloading & Reporting

Downloading Artifacts

Downloading Artifacts via id

Reporting

Downloading reports and zip files

Report templates

List templates

Create a template

Delete a template

Get template details

Update a template

Upload template logo

Delete template logo

Download template logo

Searching

Hash Searching

URL Searching

Metadata Searching

Getting Started with Metadata

Searching for Metadata Attributes

Processing Attribute Results with JQ

Including and Excluding Results

Common Metadata Search Pitfalls

Metadata Searchable Attributes

Artifact Attributes

Scan Attributes

Mime file Types

Scan Engine Result Objects

Tool Attributes

Searching for Further Attribute Fields

Metadata Syntax

Exact Value Match

Boolean Operators

Comparison Operators

Grouping

Ranges

Wildcards

Regular Expressions

Check if the Attribute Exists

Using the IP,Domain and URL Arguments

Metadata Example Library

Hunting Syrian Nation State Android Malware

Hunting Iranian Nation State Spyware

Hunting Zoom-Related Malware

Hunt for Exploits

Hunt WannaCry via its Killswitch Domain

Hunting EventBot

Processing Results with jq, Malicious Artifacts in the last 15 minutes

Processing Results with jq, Finding the Artifacts ssdeep fuzzy hash

Processing Results with jq, Finding the ClamAV Engine Assertion

Processing Results with jq, Finding the md5 of a sha256

Processing Results with jq, Extract C2 IP's for a given hash

Search for Artifact's based on a Cape Sandbox TTP

Locate Hashes that are using the ddns.net C2 Domain

Pivot on latent .pdb information in Windows Executables

IOC Searching

Searching for Associated IOCs

Searching for Associated Hashes

Searching for Known Good Domains and IPs

Tags/Lists/Families

Using Tags

Using Families

Using Links

Sandboxing

Processing Results with `jq`, Malicious Artifacts in the last 15 minutes

Processing Results with `jq`, Finding the Artifacts ssdeep fuzzy hash

Processing Results with `jq`, Finding the ClamAV Engine Assertion

Processing Results with `jq`, Finding the md5 of a sha256

Processing Results with `jq`, Extract C2 IP's for a given hash