PolySwarmPolySwarmPolySwarmPolySwarm
Go to PolySwarm
Home

PolySwarm Customer CLI v3

A CLI tool for interacting with version 3 PolySwarm Customer APIs.

Supports Python 2.7, 3.5 and greater.

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.

Configuration

Set your API key

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

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

$ export POLYSWARM_COMMUNITY=default

Enable tab completion

$ eval "$(_POLYSWARM_COMPLETE=source polyswarm)"

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

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.

$ polyswarm
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).
  -u, --api-uri TEXT              The API endpoint (ADVANCED).
  -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.
  --advanced-disable-version-check / --advanced-enable-version-check
                                  Enable/disable GitHub release version check.
  --validate                      Validate incoming schemas (note: slow).
  --parallel INTEGER              Number of threads to be used in parallel
                                  http requests.
  --version                       Show the version and exit.
  --api-version                   Show the version and exit.
  -h, --help                      Show this message and exit.

Commands:
  cat         Output artifact contents to stdout.
  download    Download file(s).
  family      Interact with Malware Families in Polyswarm.
  historical  Interact with historical hunts.
  link        Interact with Tag links in Polyswarm.
  live        Interact with live hunts.
  lookup      Lookup a scan id(s).
  rescan      Rescan files(s) by hash.
  rescan-id   Rescan by scan id.
  rules       Interact with Yara Rules stored in Polyswarm.
  sandbox     Interact with Sandboxes.
  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.

Scanning an Artifact

Scan a File

$ polyswarm scan file /tmp/eicar
============================= 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

$ polyswarm scan url https://google.com
============================= 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

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

Searching

Hash Searching

$ polyswarm -o /tmp/test.txt search hash 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
$ cat /tmp/test.txt
============================= 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

$ polyswarm search url https://polyswarm.io
============================= 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

Metadata Search documentation is moving!

Please refer to API -> Metadata Search, the temporary home for the latest information, including Web UI, CLI and API usage examples.

IOC Searching

There are three groups of commands for IOC searching. All of them deduct usage from a new IOC Search feature.

The first allows you to get the IOCs associated with a Hash.

$ polyswarm search ioc sha256 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
============================= IOCs =============================
ImpHash:
IPs: 1.2.3.4, 2.2.2.2
URLs: polyswarm.io
TTPs: T1060, T1053

The second allows you to provide an IOC and get a list of hashes for all artifacts that match that IOC.

The following IOCs can be used as search terms:

$ polyswarm search ioc ip 1.2.3.4
============================= IOCs =============================
SHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0a

$ polyswarm search ioc domain polyswarm.io
============================= IOCs =============================
SHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40

$ polyswarm search ioc ttp T1060
============================= IOCs =============================
SHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40

$ polyswarm search ioc imphash b085c7a99e6177e72564c5a6c7d849c8
============================= IOCs =============================
SHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40

Lastly, we have known good checking. 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.

$ polyswarm search known -d www.polyswarm.io -p 1.1.1.1
============================= Known IOC =============================
ID: 1
type: ip
host: 1.1.1.1
source: xyz list
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.

Hunting with Yara

Managing Yara Rulesets

The first step to hunting with Yara rules is to create your Yara ruleset(s). Once you have a Yara ruleset, you can use that to trigger Live and Historical Hunts.

$ polyswarm rules create eicar eicar.yara
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

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

$ polyswarm rules view 57611858371350090
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
}

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

$ polyswarm rules list
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: 57989886451857569
Name: eicar
Description: None
Created at: 2022-05-26 18:48:38.048514
Modified at: 2022-05-26 18:49:18.990421

Ruleset Id: 33832689671369163
Name: eicar
Description: None
Created at: 2022-05-26 18:45:11.980424
Modified at: 2022-05-26 18:48:29.335121

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

You can update the ruleset using the update command.

$ polyswarm rules update 57611858371350090 --name EiCaR
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

Or you can also update the yara ruleset.

$ polyswarm rules update 57611858371350090 --file another.yara
Ruleset Id: 57611858371350090
Name: EiCaR
Description: None
Created at: 2022-05-26 21:00:09.401395
Modified at: 2022-05-26 21:05:11.037574

And delete it if there is not a live hunt running associated with it.

$ polyswarm rules delete 57611858371350090
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

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.

$ polyswarm live start 57989886451857569
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

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 can not be deleted or modified while it has an active live hunt associated with it.

$ polyswarm live stop 57989886451857569
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

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

$ polyswarm live feed
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: {}

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

$ polyswarm live result 32552275040389723
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

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

$ polyswarm live results-delete 32552275040389723 # you can provide more ids here, separated by space
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

Start a new historical hunt providing the ruleset directly.

$ polyswarm historical start tests/eicar.yara
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
}

Or you can provide an existing rulset_id.

polyswarm historical start -r 57989886451857569
Hunt Id: 86933257769414706
Status: PENDING
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
}

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

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

$ polyswarm historical list
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

You can cancel a historical if you don't want it to finish. It will prevent further processing.

$ polyswarm historical cancel 86933257769414706
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
}

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.

$ polyswarm historical delete 86933257769414706
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
}

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

$ polyswarm historical view 48011760326110718
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
}

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

$ polyswarm historical results 48011760326110718
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: {}

You can inspect details and download the file for a result with the result command.

$ polyswarm historical result 34417123788028549
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

And you can delete an undesirable result.

$ polyswarm historical results-delete 34417123788028549 # you can provide a list of ids here, space separated
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: {}

Downloading Artifacts

Artifacts are downloaded by referencing their SHA256/SHA1/MD5 hash.

$ polyswarm download 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 test/
Successfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/test/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267

Cat Artifacts

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

$ # Get C&C from malware config
$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |hexdump -C
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:

$ polyswarm --fmt sha256 search metadata 'strings.domains:malicious.com' | polyswarm download malicious -r -
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:

$ polyswarm --fmt sha256 live results -s 3600 | polyswarm download /tmp/download -r -
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

Scan results are referenced by their Submission UUID

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

$  polyswarm -vvv -o /tmp/test.json --fmt json lookup 50446025732260182
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.

Rescanning an Artifact

Rescans also triggered by referencing the SHA256/SHA1/MD5 hash of the artifact.

$ polyswarm rescan 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
============================= 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

Sandboxing

Submit an already-scanned artifact for processing by the sandboxes. The only required argument is the id of the artifact.

polyswarm sandbox submit 42445563653708569
============================= Sandbox result =============================
result: OK

List Sandboxes

List the available sandbox names.

polyswarm sandbox list
============================= Sandboxes =============================
result: ['cape', 'triage']

2023 © PolySwarm Pte. Ltd.