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.9.0 and polyswarm-api 3.11.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 --scan-config most-time 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

View Scan History

Format: polyswarm search scans <hash>

Description: Search a hash to view previosu Scans that have been performed.

Request

$ polyswarm search scans 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5

Response

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5/30327221925404900
Detections: No engines responded to this scan. You can trigger a rescan now.
Scan id: 30327221925404900
SHA256: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5
SHA1: 8169175b424034b0f93b433e6d7068c08e526199
MD5: e6c0964ef7105869ef21379eebaefe12
File type: mimetype: application/x-dosexec, extended_info: PE32 executable (DLL) (GUI) Intel 80386, for MS Windows
First seen: 2024-09-13 22:48:48 UTC
Last scanned: 2024-11-19 06:14:47 UTC
Last seen: 2024-11-19 06:14:47 UTC
Status: Assertion window closed
Filename: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5
Community: mainnet1
Country: US
PolyScore: 0.99922532264464414276

============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5/79082986982481921
Detections: No engines responded to this scan. You can trigger a rescan now.
Scan id: 79082986982481921
SHA256: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5
SHA1: 8169175b424034b0f93b433e6d7068c08e526199
MD5: e6c0964ef7105869ef21379eebaefe12
File type: mimetype: application/x-dosexec, extended_info: PE32 executable (DLL) (GUI) Intel 80386, for MS Windows
First seen: 2024-09-13 22:48:48 UTC
Last scanned: 2024-10-31 01:10:49 UTC
Last seen: 2024-10-31 01:10:49 UTC
Status: Assertion window closed
..
..

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 provides you with the functionality to search through PolySwarm’s dataset to find samples that relate to information you are interested in.

To understand how to build out a Metadata query see the How-To Guide.

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).
`-p` , `--ip`	string	false	IP address IOC to search.
`-d` ,`--domain`	string	false	Domain name IOC to search.
`-u` , `--url`	string	false	URL IOC to search.

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

Request

$ polyswarm search metadata -i triage_sandbox_v0.ttp 'scan.detections.malicious:>1 AND polyunite.malware_family:Emotet'

Response

============================= Metadata =============================
Artifact id: 1368439839946634
Created: 2025-02-14 09:41:05.568721+00:00
SHA256: 687e603817c1c9de994763bcae0c531544a62b6f993071b8721004fd6e780841
SHA1: 2377b6e51ddb690b2ca732a1045dec3e3c934601
MD5: 3d10895e2f8bd8e2ab6735e3a4ebb70d

============================= Metadata =============================
Artifact id: 51608922017858789
Created: 2025-02-14 09:40:48.910620+00:00
SHA256: ca7cfdc3fdca5c5d05fb85fcd1ff3c1190968f1cdc2bf159f232d08bb1f8e66d
SHA1: 9feff541dec075bc5893745ecef9a16a016996b3
MD5: fb59934c3c6305e9a5a08dcd082724f7
....
.

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 -i artifact.sha256 "scan.detections.malicious:>1" will produce a large json output that matches these criteria, to filter only md5 values, you can use jq to achieve this.

Request

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

Response

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

Searching for Metadata Fields

Format: polyswarm search mapping | grep <value>

Description: Search for fields that can be used in PolySwarm Metadata searching.

Request

$ polyswarm search mapping | grep c2 | grep ip

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

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

Item	Topic	Description
1.0	"Backing Feature" field	Show in the features details the new field if it's set when executing `polyswarm account features`.
2.0	Bug Fix errors	Fix errors when serializing some API responses.

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.