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, runpip 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, runpip install -U setuptools
.
Upgrade
-
Check the current version installed
$ pip3 list | grep polyswarm
Response Example:
polyswarm 3.1.0
andpolyswarm-api 3.1.1
-
Upgrade the PolySwarm Package
$ pip3 install -U polyswarm polyswarm-api
-
Confirm the upgraded version
$ pip3 list | grep polyswarm
Response Example:
polyswarm 3.8.0
andpolyswarm-api 3.9.0
Configuration
Several parameters can be set up Globally in your environment instead of defining these with each command.
Set your API key
$ export POLYSWARM_API_KEY=<Your API key from polyswarm.network>
You will need to get your own API key from
polyswarm.network/account/api-keys
Set the community name: "default" is the default public community.
$ export POLYSWARM_COMMUNITY=default
You can define your own private community name replacing the default community above if you have this feature on your plan.
Enable tab completion
$ eval "$(_POLYSWARM_COMPLETE=source polyswarm)"
Using the PolySwarm CLI
General Usage
The polyswarm
command has several sub-commands.
You can run the command or a sub-command by itself or use the -h
option to get help output.
Request
$ polyswarm -h
Response
Usage: polyswarm [OPTIONS] COMMAND [ARGS]...
This is a PolySwarm CLI client, which allows you to interact directly with
the PolySwarm network to scan files, search hashes, and more.
Options:
-a, --api-key TEXT Your API key for polyswarm.network
(required). [env var: POLYSWARM_API_KEY]
-u, --api-uri TEXT The API endpoint (ADVANCED). [env var:
POLYSWARM_API_URI]
-o, --output-file FILENAME Path to output file.
--output-format, --fmt [text|json|pretty-json|sha256|sha1|md5]
Output format. Human-readable text or JSON.
--color / --no-color Use colored output in text mode.
-v, --verbose
-c, --community TEXT Community to use. [env var:
POLYSWARM_COMMUNITY]
--parallel INTEGER Number of threads to be used in parallel
http requests.
--verify / --no-verify Verify TLS connections.
--version Show the version and exit.
--api-version Show the version and exit.
-h, --help Show this message and exit.
Commands:
account Interact with Accounts in Polyswarm.
activity Interact with Yara Rules stored in Polyswarm.
cat Output artifact contents to stdout.
download Download file(s).
download-id Download file(s).
engine Interact with engines.
family Interact with Malware Families in Polyswarm.
historical Interact with historical hunts.
known Interact with known ioc api.
link Interact with Tag links in Polyswarm.
live Interact with live hunts.
lookup Lookup a scan id(s).
metadata Interact with Metadata in Polyswarm.
providers List the names of available sandbox providers and VMs.
report Interact with the Polyswarm reporting system.
report-template Interact with the Polyswarm reporting templates system.
rescan Rescan files(s) by hash.
rescan-id Rescan by scan id.
rules Interact with Yara Rules stored in Polyswarm.
sandbox Interact with the Polyswarm sandbox system.
scan Interact with Scans sent to Polyswarm.
search Interact search api.
stream Access the polyswarm file stream.
tag Interact with Tags in Polyswarm.
wait Wait for a scan to finish.
Further Usage Details
The command line structure is split into several sections; further details for the most used options and arguments are listed below. '[OPTIONS]' can be used in combination with a number of [COMMANDS].
polyswarm [OPTIONS] COMMAND [ARGS]...
[OPTIONS]
-a
api key, overrides the global setting of the api key, useful for moving between the default public community and the private community.–fmt
Define an output format of the returned results; available outputs includejson
,pretty-json
andsha256
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 thePOLYSWARM_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://
orhttps://
).
Description: Command to scan a url with PolySwarm to retrieve engine verdict details. The command can be used to scan a qr code and extract the url from the code.
Options
Option | Type | Required | Description |
---|---|---|---|
-r ,--url-file |
string | false | Path of file that contains multiple URLs, one per line. |
--qrcode-file |
string | false | Path of a QR Code image file that contains an URL as a payload. |
-t , --timeout |
integer | false | How long to wait for results (default:900). |
-n , --nowait |
- | false | Does not wait for the scan window to close. |
-s , --scan-config |
string | false | Template to be used in the scan i.e. default, more-time, most-time. |
Request
$ polyswarm scan url https://google.com
Response
============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d
Detections: 0/4 engines reported malicious
CyRadar: Clean
Phishtank: Clean
Nucleon: Clean
Virusdie: Clean
Scan id: 47022542941158297
SHA256: 05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d
SHA1: 72fe95c5576ec634e214814a32ab785568eda76a
MD5: 99999ebcfdb78df077ad2727fd00969f
File type: mimetype: text/plain, extended_info: ASCII text, with no line terminators
SSDEEP: 3:N8r3uK:2LuK
TLSH:
First seen: 2019-06-25 01:53:43.954091
Last seen: 2020-02-21 19:40:12.136225
Status: Assertion window closed
Filename: https://google.com
Community: lima
Country: US
PolyScore: 0.00000000000000000000
Rescanning an Artifact
Format: polyswarm rescan <hash>
Description: Rescans also triggered by referencing the SHA256/SHA1/MD5
hash of the artifact. Rescan will submit the sample through the engines to retrieve an updated verdict.
Options
Option | Type | Required | Description |
---|---|---|---|
-r , --hash-file |
string | false | File path and name for file that contains hashes, one per line |
-t , --timeout |
integer | false | How long to wait for results (default:900) |
-n , --nowait |
- | false | Does not wait for the scan window to close |
-s , --scan-config |
string | false | Template to be used in the scan i.e. default, more-time, most-time |
--hash-type |
string | false | Hash type to search [default:autodetect, sha256, sha1, md5] |
Request
$ polyswarm rescan 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Response
============================= Artifact Instance =============================
Scan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Detections: 5/11 engines reported malicious
Qihoo 360: Malicious, metadata: {"malware_family": "qex.eicar.gen.gen", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}}}
ClamAV: Clean
Ikarus: Malicious, metadata: {"malware_family": "EICAR-Test-File", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "21.02.2020 13:15:46 (102417)", "vendor_version": "5.2.9.0", "version": "0.2.0"}}
Nucleon: Clean
VenusEye: Clean
K7: Malicious, metadata: {"malware_family": "EICAR_Test_File", "scanner": {"environment": {"architecture": "AMD64", "operating_system": "Windows"}, "signatures_version": "11.95.33362, 21-Feb-2020", "vendor_version": "15.2.0.42", "version": "0.2.0"}}
Lionic: Clean
Virusdie: Malicious, metadata: {"malware_family": "EICAR.TEST", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "vendor_version": "1.3.0", "version": "0.3.0"}}
Alibaba: Clean
DrWeb: Malicious, metadata: {"malware_family": "EICAR Test File (NOT a Virus!)", "scanner": {"environment": {"architecture": "x86_64", "operating_system": "Linux"}, "signatures_version": "0599371BD3AE76D460E15A9719E64059, 2020-Feb-21 18:06:10", "vendor_version": "7.00.44.12030", "version": "0.3.0"}}
XVirus: Clean
Scan id: 87555975730729927
SHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
SHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c
MD5: a6a57bf20416a4c712c4a1eabcaeb235
File type: mimetype: text/plain, extended_info: EICAR virus test files
SSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX
TLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8
First seen: 2020-01-24 21:56:21.456900
Last seen: 2020-02-21 20:03:30.398950
Status: Assertion window closed
Filename: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf
Community: lima
Country: US
PolyScore: 0.08376258884586366971
Downloading & Reporting
Downloading Artifacts
Format: polyswarm download <hash>
Description: Artifacts are downloaded by referencing their SHA256/SHA1/MD5
hash and stored locally.
Options
Option | Type | Required | Description |
---|---|---|---|
-r , --hash-file |
string | false | File of hashes to download, one per line |
-d , --destination |
string | false | Path where to store the downloaded files |
--hash-type |
string | false | Hash type to search [default:autodetect, sha256, sha1, md5] |
Request
$ polyswarm download 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 test/
Response
Successfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/test/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
Downloading Artifacts via id
Commonly used to download sandbox artifacts, this command can be used to download artifacts directly via their instance_id
see this section for command.
Reporting
Downloading reports and zip files
PolySwarm provides the reporting cli command, this provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing sessions, and download a ZIP file of which can contain the PDF report alongside other Sandbox artifacts like pcaps, reports and jarm files.
The following are the 3 sequential steps in a report generation operation, that can be performed via the CLI one step at a time:
- Inform PolySwarm to start creating the report, or create and download the zip file. If only wanting the zip file there is no need to proceed with the next two steps.
- Poll PolySwarm to understand when the report has finished being created.
- Download the report locally once generation is successful.
Format: polyswarm report create [OPTIONS] <html|pdf|zip> <scan|sandbox> <OBJECT_ID>
Description: Start to generate the PolySwarm report, choose a PDF or HTML report for Sandbox or a Scanning instance. Or create a zip file with Sandbox Artifacts to download directly.
NOTE: If generating a Scanning report the
OBJECT_ID
will be theartifact_id
, find this with the command:polyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id'
. If generating a Sandboxing report theOBJECT_ID
will be thesandbox_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 is a powerful and flexible means to discover previously unknown malware. Metadata information covered in the section will be the building blocks in any Metadata query, and will apply to Metadata usage throughout PolySwarm (CLI,API,UI).
This section is broken down into the below high level sections
- Getting started with Metadata
- Metadata Searchable Attributes
- Metadata Syntax
- Metadata Example Library
Getting Started with Metadata
As PolySwarm ingests Artifacts (Files, URLs, etc.), various "Metadata Extractors" are run against the Artifacts, producing a rich set of Attributes that describe the Artifacts, the Scans conducted against the Artifacts and contextual information such as the timestamp of ingestion.
All of the Attributes produced by the Metadata extraction process are "pivotable" (searchable), empowering users to hunt for Artifacts that exhibit (or don't exhibit) various Attributes - and mix and match these queries with rich search syntax including Boolean logic and regular expressions.
For example, if you'd like to find all Artifacts that are:
- 64 bit Windows executables (PEs)
AND
were first seen within the last weekAND
export a specified regular expression of function namesOR
contain a specified C2 address
... then PolySwarm's Metadata Search is your tool!
This section will cover the basics of Metadata, syntax and finding the fields needed with some use case examples. Once the basics of Metadata have been understood, a Metadata command can be crafted and used across the UI,CLI and API.
As an example, scan.detections.malicious:>1
can be used in the UI, CLI and API tools as an argument.
PolySwarm's Metadata Search is backed by Elasticsearch and supports the full range of Elasticsearch search criteria to deliver flexible results quickly.
Searching for Metadata Attributes
Format: polyswarm search metadata <metadata values>
Description: Search for Artifact Metadata in the CLI, Add additional options like –fmt
to allow for additional functionality see here.
Options
Option | Type | Required | Description |
---|---|---|---|
-i , --include |
string | false | Field to be included in the result (* wildcards are accepted). |
-x , --exclude |
string | false | Field to be excluded in the result (* wildcards are accepted). |
Request
$ polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1"
Response
{
"artifact": {
"created": "2023-06-20T11:29:11.322959+00:00",
"id": "3414327927829341",
"md5": "6bf2025e7aa7b09d7044718c2a3f190d",
"sha1": "5323a695a165e13a04a11d24e603ae4444463b08",
"sha256": "2d1bbc2837559f5224076a833ec6e9cc6fe053b76a11bf500654ce0431b8993c"
},
"exiftool": {
"characterset": "Unicode",
"codesize": 45056,
..............
Processing Attribute Results with JQ
jq
is a command-line processor for json files, allowing the slicing of the json to filter out specific Attributes.
When defining --fmt
as json
in the polyswarm search metadata
CLI command, jq
can be used to filter the output of the Attributes.
Taking the command polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1"
will produce a large json output that matches these criteria, to filter only sha256 values, you can use jq
to achieve this.
Request
$ polyswarm --fmt pretty-json search metadata "scan.detections.malicious:>1" | jq .artifact.sha256
Response
"8ce0d5b701fb084f14990fe0d425628781130c9da0b0b95f98f3a9e5eef755bb"
"19cb4f641750555e4a40460e03a07217306077585a7290ef480712d373e3b755"
"f2015c1e82f92c7d8a728eeb47adb52e877a3ab9ee2d7168cc311fae7b5bbfae"
"b0a1cc605d485e5e73e73aa8a0377a9d12a53d4042d711bd4bf99cd7b6961afa"
"9cb02c934c2aa8938b30aa52924798a6d2a12ca4e7d75a2d01390c01067b0a8b"
"6d7607445c3b71d707576d6424581cb0a0c6c39f11a67601811568cf30eba9ab"
"f665fa1373a7bb1b8085ad95866066f2164e25f79e3bf0dc45abc2ba690144ab"
"bf1e0bd5265619d33c89795d340fe05bf7e3a80935396e83cd52d3baa77b4902"
"07707539577a320e56805cd9458a3ffd9ace7fb31aca106bd1aad89d60354906"
"d47f64147c5ad65a9841813df44fce49e435e472874853d02a192689dd1f5007"
"d767ded5ba7377356f48351f9f03ada9de9c6eb156f08de0a9cce2ebe3ad4369"
Including and Excluding Results
A more efficient method of selecting a subset of the fields in the results is to use the --include
and --exclude
options in the polyswarm search metadata
command. These options can be used more than once in a single command to include or exclude parts of the resulting data object.
In the example below, the command will include only the artifact.sha256
field in the output.
Request
polyswarm search metadata --include artifact.sha256 --include scan.detections.malicious "scan.detections.malicious:>1"
Response
============================= Metadata =============================
Artifact id: 800261578717225
Created: None
SHA256: b59cc7c56a3513ea355660d8c6f9593ef0b28734575d528890f771d3184b001a
============================= Metadata =============================
Artifact id: 24752295304479291
Created: None
SHA256: 17b4c990736f5687081239758acbc5c67602c619bacd818ac8d0e08c313c2476
Common Metadata Search Pitfalls
When developing queries Users should be aware of several idiosyncrasies Metadata Search inherits from Elasticsearch.
- Attribute fields are case-sensitive.
- If a query refers to a field that doesn't exist, Metadata Search will ignore this portion of the query.
For example, the intention of the following query is likely to identify all Artifacts detected as malicious
by at least 2 Engines, where 1 is ClamAV:
scan.latest_scan.ClamAV.assertion:malicious AND scan.detections.malicious:>1
As explained later, scan
does not exist on all Artifacts (is optional), let alone scan.latest_scan.ClamAV
.
On Artifacts for which scan.latest_scan.ClamAV
does not exist, this portion of the query is ignored, effectively reducing this query to:
scan.detections.malicious:>1
Resulting in an incorrect result set that includes Artifacts found to be malicious
by at least 2 Engines for which no ClamAV scan result exists.
Users must first verify the existence of the optional field before applying criteria to the contents of the optional field, this is covered in the Syntax Section
This query will return the intended result set:
_exists_:scan.latest_scan.ClamAV AND scan.latest_scan.ClamAV.assertion:malicious AND scan.detections.malicious:>1
Metadata Searchable Attributes
Metadata Attributes can be used to Search on as well as what Attributes to output, these Attributes belong to one of the following Scopes:
- Artifact: Attributes that describe Artifacts in context and at surface level, e.g. the Artifact's unique
id
, the time it wasfirst_seen
and its various hashes (sha256
,md5
,sha1
). These Attributes are available on all Artifacts. - Scan: Information concerning the Scan(s) that have been executed on the Artifact.
Users can address the first and latest (most recent) Scan Result Sets for each scanned Artifact, accessing information such as: what each Engine said about the scanned Artifact, whether the Engine
detected
the Artifact asmalicious
orbenign
and whatmalware_family
the Artifact was found to belong to, as applicable. There is a 1 to many relationship between Artifacts and Scan Result Sets: each Artifact has 0 to N associated Scan Result Sets, whereas every Scan result set will have exactly 1 associated Artifact. These Attributes are available on all Artifacts that have been scanned at least once. - Tool: Attributes that describe the content of Artifacts.
A set of Metadata Extraction Tools ("Tools") are run on Artifacts under various criteria, e.g. the Artifact's file type.
For example,
strings
(a Tool) is used to extract IP, domain & URL-like strings from all file Artifacts, whereaspefile
(another Tool) exclusively extracts information from Artifacts that are Windows executables. Such Attributes are addressed via the name of the Tool itself. Tool-produced Attributes are available on Artifacts for which the given Tool is applicable.
Queries address Attributes hierarchically (based on their Scope).
Results are similarly delivered hierarchically.
For example, pefile
produces an attribute named imphash
.
Users are able to access pefile
's imphash
via pefile.imphash
.
When constructing queries, it's important to understand this hierarchy and formulate queries accordingly.
The following sections expand on each class of Attribute along with CLI examples that leverage the Attributes.
This documentation does not cover every searchable attribute of an Artifact. We focus our examples and description on the most commonly used attributes to understand the principles.
To retrieve the full list of attributes that are searchable, you can use the CLI command
polyswarm search mapping
, more information is available hereIf we're missing something you'd like to be able to search for, please get in touch!
Artifact Attributes
Attributes that provide contextual and surface-level information about Artifacts are available under the artifact
Scope.
The following artifact
Attributes are supported:
-
artifact
id
- a unique identifier for the Artifact within PolySwarmcreated
- timestamp indicating when the Artifact became available on PolySwarmsha256
- the SHA256 hash of the Artifactmd5
- the MD5 hash of the Artifactsha1
- the SHA1 hash of the Artifact
The Attribute required to query for an instance of EICAR sha256 hash via Metadata Search, would therefore be artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
. This would then be the argument for the polyswarm search metadata
command.
Scan Attributes
Attributes that describe Scans executed against Artifacts are available under the scan
Scope.
The following scan
Attributes are supported:
-
scan
filename
- (DEPRECATED) observed filename(s) for the Artifacturl
- (DEPRECATED; Exists for URL Artifacts Only) observed URLs for the Artifactcountries
- (See Deprecation Note Below) countries from which a Scan was initiated on the Artifact-
mimetype
- mime type informationextended
- extended mime information, e.g., "PE32 executable (GUI) Intel 80386, for MS Windows"mime
- mime type, e.g. "application/x-dosexec", see File Types for more examples
first_seen
- (DEPRECATED) UTC date of when the Artifact was first scannedlast_seen
- (DEPRECATED) UTC date of when the Artifact was last scanned-
first_scan
/latest_scan
- the first / most recent Scan Results Setartifact_instance_id
- a unique identifier for the Scan Result Setcreated
- UTC date when the Artifact was first/last scanned-
detections
benign
- number of Engines that asserted that the Artifact isbenign
in this Scan Result Setmalicious
- number of Engines that asserted that the Artifact ismalicious
in this Scan Result Setunknown
- number of Engines that did not finalize (reveal) their assertiontotal
- number of Engines that asserted in this Scan Result Set
filename
- filename of Artifact, if artifact was a FILE Artifacturl
- url of Artifact, if artifact was a URL Artifact- An array of objects, each describing an Engine (e.g.
ClamAV
)'s response in the Result Set. See Engine Result Objects for a breakdown.
Deprecations:
The
scan.filename
Attribute is deprecated. Please usescan.[first_scan|latest_scan].filename
.The
scan.url
Attribute is deprecated. Please usescan.[first_scan|latest_scan].url
.The
scan.first_seen
andscan.last_seen
Attributes are deprecated. Please usescan.[first_scan|latest_scan].created
.The
scan.countries
Attribute will soon be replaced byartifact.countries
.
PolySwarm maintains a record of all Scan Result Sets, but only the first Scan (
scan.first_scan
) and latest Scan (scan.latest_scan
) are generally available via Metadata Search.If you have a use case for querying against more/all Scan Result Sets, please get in touch and let's discuss!
Mime file Types
The following is a list of common mimetypes useful for querying via scan.mimetype.mime
.
MIME Types | Kind of document | Extension |
---|---|---|
application/gzip | GZip Compressed Archive | .gz |
application/octet-stream | Any kind of binary data | .bin |
application/pdf | Adobe Portable Document Format | |
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | Microsoft Excel 2007+ (OpenXML) | .xlsx |
application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word 2007+ (OpenXML) | .docx |
application/x-dosexec | PE32 executable | .exe |
application/x-java-applet | Compiled Java class data | .class |
application/x-rar | RAR archive data | .rar |
application/xml | XML | .xml |
application/zip | ZIP archive | .zip |
text/html | HyperText Markup Language (HTML) | .htm .html |
text/plain | Text, (generally ASCII or ISO 8859-n) | .txt |
A list of all official MIME media types provided by IANA can be found here.
Scan Engine Result Objects
Attributes that describe a given Engine's assertion (malicious
or benign
), identified malware_family
(as applicable) and additional optional data are available under the scan.<NAME OF SCAN>.<ENGINE NAME>
(e.g. scan.latest_scan.ClamAV
) Scope.
Remember: In PolySwarm, Engines are not required to provide responses to Scan requests. For this and other reasons (e.g. in the case of errors), any particular Engine may or may not appear within the
scan.<NAME OF SCAN>
scope. An Engine that appeared inscan.first_scan
may or may not appear inscan.latest_scan
and vice versa.Things to keep in mind:
- Although unlikely, 0 Engines may choose to respond to any given Scan Request, resulting in 0 Engine Result Objects for the given Scan Result Set. Do not assume there is at least 1 Engine Result Object on any given Scan Result Set.
- Do not assume that any particular Engine produced an Engine Result Object for a given Scan Result Set.
Using the Attribute artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
in the CLI command polyswarm search metadata
will produce part of the below output:
{
...
"scan": {
...
"first_scan": {
...
"ClamAV": {
"assertion": "malicious",
"metadata": {
"malware_family": "Eicar-Test-Signature"
}
},
This Engine Result Object provides the following information:
scan.first_scan.ClamAV.assertion
:malicious
/benign
determinationscan.first_scan.ClamAV.metadata.malware_family
: the identified malware family name of the Artifact
Tool Attributes
Metadata Extraction Tools are applied on a per-Artifact basis according to some relevancy criteria.
Attributes produced by each Tool are addressed at the top level by the Tool's name. The following Tools are supported:
-
hash
- computes various hash functions on Artifacts. Applies to all file Artifacts.authentihash
- (string) a SHA256 hash used by Microsoft that "verifies that the software has not been tampered with since it was signed and published".ssdeep
- (string) a fuzzy hash algorithm designed to collide on sufficiently similar files. Metadata searching an Artifact's fuzzy hash may return similar file results.ssdeep_chunk
- (string) refer to ssdeep documentationssdeep_chunk_size
- (int) refer to ssdeep documentationssdeep_double_chunk
- (string) refer to ssdeep documentationtlsh
- (string) Trend Micro Locality Sensitive Hashtlsh_quartiles_minimum_match
- (int) refer to tlsh documentationtlsh_quartiles
- (array of strings) refer to tlsh documentationmd5
- (string) the MD5 hash of the Artifactsha1
- (string) the SHA-1 hash of the Artifactsha256
- (string) the SHA-256 hash of the Artifactsha512
- (string) the SHA-512 hash of the Artifactsha3_256
- (string) the SHA-3-256 hash of the Artifactsha3_512
- (string) the SHA-3-512 hash of the Artifact
-
strings
- extracts string-like sequences from Artifacts. Applies to all file Artifacts.domains
- (array of strings) strings that look like Domain namesurls
- (array of strings) strings that look like URLs (including things like emails)ipv4
- (array of strings) strings that look like IPv4 addressesipv6
- (array of strings) strings that look like IPv6 addresses
-
lief
- extracts information from executables. Applies to Linux (ELF), Windows (PE) and Java executable Artifacts.has_nx
- (bool) indicates whether the executable was compiled with NX protections (referred to as DEP on Windows)is_pie
- (bool) indicates whether the executable is compatible with a fully randomized address space (full ASLR)libraries
- (array of strings) list of imported librariesentrypoint
- (string) entrypoint in decimal notationvirtual_size
- (string) virtual size in decimal notationexported_functions
- (array of strings) list of exported functionsimported_functions
- (array of strings) list of imported functionsvirtual_size
- (int) size of the executable when mapped into a process space
-
pefile
- extracts information from Windows executables. Refer topefile
documentation for a description of these fields. Applies to Windows (PE) executable Artifacts.app_container
- (bool)compile_date
- (string)compile_date_utc
- (string)exports
- (array of strings)force_integrity
- (bool)force_no_isolation
- (bool)has_debug_info
- (bool)has_export_table
- (bool)has_import_table
- (bool)high_entropy_aslr
- (bool)imphash
- (string) "import hash". Use this to find other Windows executables that import the same functions. Examples provided later.imports
- (object) dictionary of imports in formatdllname: [list, of, functions]
imported_functions
- (array of strings)is_dll
- (bool)is_driver
- (bool)is_exe
- (bool)is_probably_packed
- (bool)is_suspicious
- (bool, can be null)is_valid
- (bool, can be null)libraries
- (array of strings) array of imported libraries (DLLs)no_bind
- (bool)pdb
- (array of strings) PDB paths referenced in the Artifact. Useful for finding attacker OPSEC mistakes / false flags. Examples provided later.pdb_guids
- (array of strings)terminal_server_aware
- (bool)uses_aslr
- (bool)uses_cfg
- (bool)uses_dep
- (bool)uses_seh
- (bool)verify_checksum
- (bool)warnings
- (array of strings) warnings generated duringpefile
executionwdm_driver
- (bool)
-
exiftool
- pull assorted Attributes from a wide range of file types. Particularly useful for indicators in office documents. Applies to executables, documents, images, videos and fonts.Author
- (string) author of the file, e.g.Theresia Ward
build
- (string) e.g.August 2018
CharacterSet
- (string) character set of file, e.g.Unicode
codesize
- (int) code size of PEscomments
- (string) e.g.background challenge Licensed
company
- (string) e.g.Cremin LLC
entrypoint
- (string) entry point of PEs as a hexademicimal string, e.g.0x13f0
CreateDate
- (string) creation time string from documentfiledescription
- (string) e.g.GlowEffect MFC Application
filename
- (string) DO NOT USEfilesize
- (int) the size of the Artifact in bytesfiletype
- (string) e.g.Win64 DLL
filetypeextension
- (string) file type extension (e.g., 'exe', 'dll', 'pdf')initializeddatasize
- (int) size of the initialized.data
section in PEsInternalName
- (string) internal name extracted from executable, e.g.GlowEffect
Language
- (string) language of file, e.g. 'en-GB'LanguageCode
- (string) language used by executable, e.g.English (U.S.)
lastmodifiedby
- (string) e.g.Arturo Cole
linkerversion
- (int) linker version used to compile executables, e.g.14.0
manager
- (string) e.g.Hayes
mimetype
- (string)machinetype
- (string) a string describing the CPU type supported by the executable Artifact, e.g.ARM little endian
orIntel 386 of later, and compatibles
ModifyDate
- (string) last modified time string from documentOriginalFileName
- (string) original name of the fileosversion
- (string) the version of the operating system supported by the executable Artifact, e.g.5.0
(for Windows)petype
- (string) type of (Windows) Portable Executable (PE), e.g.ROM Image
,PE32
andPE32+
sourcefile
- (string) DO NOT USESubject
- (string) subject of the file, e.g.Plastic
subsystem
- (string) type of Windows subsystem supported by the executable Artifact, e.g.Windows GUI
,XBOX
,EFI application
subsystemversion
- (string) version string for thesubsystem
timestamp
- (string) timestamp of the file, e.g.2018:03:13 07:19:15+00:00
Title
- (string) title of the file, e.g.transmit
zipcrc
- (string) the CRC checksum of ZIP files as a hexadecimal stringzipfilename
- (string) e.g.[Content_Types].xml
zipmodifydate
- (string) e.g.2008:04:16 07:40:25
Several
exiftool
fields are marked as DO NOT USE.These fields are currently being "clobbered" via our partner feed ingestion process and therefore should not be relied on yet.
We'll remove these notices when these fields contain descriptive values.
Searching for Further Attribute Fields
Further Attribute Fields are available within PolySwarm outside of the values listed already. PolySwarm provides an easy CLI command that enables the functionality of searching through these fields to use in the metadata commands.
Request
$ polyswarm search mapping | grep cape | grep file
Response
| | | | +-cape_sandbox_v2.behavior.enhanced.data.file
| | | +-cape_sandbox_v2.behavior.summary.delete_files
| | | +-cape_sandbox_v2.behavior.summary.files
| | | +-cape_sandbox_v2.behavior.summary.read_files
| | | +-cape_sandbox_v2.behavior.summary.write_files
| | +-cape_sandbox_v2.cape_config.Copy file
| | +-cape_sandbox_v2.cape_config.Delete file
| | +-cape_sandbox_v2.cape_config.Hide file
| | +-cape_sandbox_v2.cape_config.Hide keylog file
Metadata Syntax
Metadata Search supports Elasticsearch's query_string
syntax, providing flexibility through:
- Boolean logic, e.g.
AND
,OR
&NOT
- grouping Boolean terms
- ranges, e.g.
date:[2012-01-01 TO 2012-12-31]
- comparison operators (
>
,<=
, etc.) - wildcards
- regular expressions
... and a lot more.
Always enclose literals in double-quotations (
"
), or, alternatively, escape all Elasticsearch control characters in your query.For example, URLs contain Elasticsearch control characters. Failing to escape these control characters to enclose a queried URL in quotations will result in errors.
Doesn't work:
strings.urls:https://polyswarm.network
- due to the second exact value match operator (:
)Works:
strings.urls:"https://polyswarm.network"
Also works:
strings.urls:https\://polyswarm.network
Exact Value Match
Metadata query syntax supports exact value matching via the :
operator.
The following will return all Artifacts for which the hash
Tool reported an MD5 value of e90099d6f3078a9691ab8fe38f0f25e4
.
hash.md5:"e90099d6f3078a9691ab8fe38f0f25e4"
This will either return 0 or 1 results, modulo MD5 colliding Artifacts.
Boolean Operators
Metadata query syntax supports Boolean operators that allow users to combine clauses into more powerful queries.
Supported operators:
AND
OR
NOT
... and a lot more.
You may combine multiple attributes matches in your query using boolean operators:
scan.first_scan.ClamAV.assertion:benign AND scan.latest_scan.ClamAV.assertion:malicious
This query will return all Artifacts that were first flagged by ClamAV as benign, but on their latest scan are now found to be malicious.
You may also use Boolean operators for attribute values:
scan.mimetype.mime:("application/x-dosexec" OR "application/x-java-applet")
Will search for all artifacts with MIME Type application/x-dosexec
OR application/x-java-applet
.
Comparison Operators
Metadata query syntax supports comparing values.
Supported comparisons:
>
: greater than<
: less than>=
: greater than or equal to<=
: less than or equal to
The following will return all artifacts with at least one benign assertion.
scan.latest_scan.detections.benign:>0
Grouping
Metadata query syntax supports grouping Boolean operators and clauses using parentheses.
The following will return all Artifacts that, on their latest scan, were detected by 1, 2 or 3 engines as malicious OR were detected by ClamAV as malicious:
(scan.latest_scan.detections.malicious:>0 AND scan.latest_scan.detections.malicious:<=3) OR scan.latest_scan.ClamAV.assertion:malicious
Ranges
Metadata query syntax supports ranges using the TO
operator.
This query:
scan.latest_scan.detections.benign:>=0 AND scan.latest_scan.detections.benign:<=10
... can be simplified to this:
scan.latest_scan.detections.benign:[0 TO 10]
Square brackets ([
& ]
) match inclusively with respect to range boundaries, whereas curly brackets ({
& }
) match exclusively.
In the above query, 0
and 10
are included in the range of matching values.
If we replace the square bracket next to the 10
with a curly bracket:
scan.latest_scan.detections.benign:[0 TO 10}
... then 10
is not a matching value.
The number of benign assertions on a scan is an integer value, so the matching range becomes 0
to 9
, inclusive.
In addition to fields containing numbers, ranges can be applied to dates.
The following will return all artifacts with an exiftool
-identified createdate
falling in the year 2019
.
exiftool.createdate:[2019-01-01 TO 2019-12-31]
Wildcards
Metadata query syntax supports wildcard matching using the *
character.
The following will return all Artifacts that, on their latest scan, were identified by ClamAV as belonging to a malware family that contains the string Trojan
:
scan.latest_scan.ClamAV.metadata.malware_family:*Trojan*
This would match on Artifacts that belong to, e.g. Trojan-Ransom.Satan
and Trojan.Packed2.39908
families.
Wildcards can be used for Attribute names as well, but must be escaped.
The following will return all Artifacts identified as belonging to a malware family that includes the string Trojan
by any Engine:
scan.latest_scan.\*.metadata.malware_family:*Trojan*
Note: Do not escape
*
in values, only in Attribute names.
Regular Expressions
Metadata query syntax supports regular expression matching on Attribute values.
The following will return all Artifacts that are ELF executables AND
export functions that match the regular expression /.*Shooter(Sound|Ping|Key|Image|File).*/
, e.g. ShooterSound
:
exiftool.FileType:"ELF executable" AND lief.exported_functions:/.*Shooter(Sound|Ping|Key|Image|File).*/
This includes EvilGnome samples.
Regular expressions containing
^
(beginning of line) or$
(end of line) matching are not supported.
Check if the Attribute Exists
Metadata query syntax supports existence checking for Attributes.
The following query will return all Artifacts on which the lief
Tool has been executed and has reported which libraries
the Artifact imports:
_exists_:lief.libraries
Reminder: always check for the existence of an optional Attribute before attempting to match on the value of the optional attribute.
Failure to do so is will almost certainly produce unexpected results.
Using the IP,Domain and URL Arguments
The Metadata Search API and CLI provide convenience arguments to use when searching for IPs, Domains, and URLs. Each argument takes one parameter, but you can use the arguments multiple times in a single query. However, you can only use one type of argument per query.
These convenience arguments are:
--ip
- for IPv4 addresses--domain
- for domain names--url
- for URLs
The following are some examples:
polyswarm search metadata --ip 2.2.2.2 --ip 192.0.0.1
polyswarm search metadata --domain polyswarm.io
polyswarm search metadata --url https://polyswarm.network/marketplace-stats --url https://polyswarm.io/team
Metadata Example Library
PolySwarm's Metadata Search is a powerful tool for finding unique variants and even completely new versions of malware.
In this section, we'll run through several real-world example hunts where new malware, including brand new versions of malware that hadn't be previously published, were found using PolySwarm's Metadata Search.
Other Use Case examples are also provided like using jq
to extract relevant information from the metadata.
Hunting Syrian Nation State Android Malware
Lookout published a blog post on COVID-19 related Android malware released by the Syrian Electronic Army.
The post discloses:
- Where the command and control (C2) addresses are stored within the malicious applications (within
res/values/strings.xml
) - A list of SHA1 hashes of applications known to belong to this family of malware
First, we look up Lookout's first SHA1 hash on PolySwarm:
- via the CLI (hash search):
polyswarm search hash 1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08
- via the CLI (metadata search using the hash):
polyswarm search metadata 'hash.sha1:"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08"'
We have a hit!
Next, we download the Artifact (using your choice of Web UI, CLI or Python) and use apktool with the d
flag to extract res/values/strings.xml
:
<?xml version="1.0" encoding="utf-8"?>
<resources>
...
<string name="MT_Bin_dup_0x7f0c0020">Android Telegram</string>
<string name="MT_Bin_dup_0x7f0c0021">10000</string>
<string name="MT_Bin_dup_0x7f0c0022">82.137.218.185</string>
...
</resources>
It appears as though the C2 address is 82.137.218.185
.
This information was not published in Lookout's blog post.
We can use Metadata Search to "pivot" using this IP(v4) address:
- via the CLI:
polyswarm search metadata --ip 82.137.218.185
At the time of writing, we see:
- 50 results,
- at least 23 of which were not identified by Lookout in their blog post, and
- at least 5 of which cannot be found on platforms similar to PolySwarm.
Using PolySwarm, researchers can quickly identify additional variants of malware and produce something that immediately expands on the public knowledge of the threat.
Hunting Iranian Nation State Spyware
ZDNet published an article on Iran's official COVID-19 tracker application that sends the real time location of installees to the Iranian government.
The article provides only a single IOC - a SHA256 hash (0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b
) we can find on PolySwarm:
- via the CLI (hash search):
polyswarm search hash 0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b
- via the CLI (metadata search using the hash):
polyswarm search metadata 'hash.sha256:"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b"'
Let's take a look some of the Metadata Attributes from this Artifact:
{
"artifact": {
"created": "2020-03-10T10:16:50.900548+00:00",
"id": "71592690635387748",
"md5": "766e5ecf6b1d86abf401ad9223de857d",
"sha1": "f1271aa0ccf79d16b036bac5320ed4349af69b65",
"sha256": "0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b"
},
...
"strings": {
"domains": [
"V.mr",
"",
"covid-19-e9057.appspot.com",
"p.to",
"II1046766097017-4va56jc12ajt308tpbuge0tc5iqla179.apps.googleusercontent.com",
"b.mc",
"YJ.cz",
"6.om",
"6.gm",
"covid-19-e9057.firebaseio.com"
],
...
}
}
There are several interesting domains extracted by the strings
Tool:
covid-19-e9057.appspot.com
covid-19-e9057.firebaseio.com
It appears as though some portion of the Iranian government's backend for this app is Google's Appspot and Firebase services. This is mildly interesting because Google removed the application from their Play Store.
Next, we conduct a Metadata Search for the unique portion of these domains (covid-19-e9057
) + a wildcard (*
) to find additional Artifacts that contain these strings:
$ polyswarm --fmt sha256 search metadata 'strings.domains:covid-19-e9057*'
This search nets 4 Artifacts, all of which have been identified as malicious by Engines on PolySwarm. 3 of these Artifacts were, of course, not mentioned in the ZDNet article. Perhaps they have new functionality worth investigating!
Hunting Zoom-Related Malware
Switching gears from Android to Windows malware, TrendMicro recently published a blog post on some malware exploiting the rise in Zoom popularity.
Among other tidbits mentioned in the article, this malware:
- is a Powershell script,
- that embeds a 7zip extractor, and
- 7zip-compressed Tor, coinminer (the actual malware) and (legitimate) Zoom installers
The malware will cause the victim machine to mine cryptocurrency if the infected computer is powerful enough (notably, has a discrete GPU) over Tor.
TrendMicro published a handful of IOCs, including a C2 URL: https://2no.co/1O5aW
.
Again, we turn to Metadata search to find Artifacts that contain this URL:
- via the CLI:
polyswarm search metadata 'strings.urls:*2no.co*1O5aW'
We get 1 result, which was not part of the IOCs published by TrendMicro, but is clearly a PowerShell script exactly as described in their blog!
Hunt for Exploits
Often when identifying malware families, Engines on PolySwarm will name the malware family and the exploited vulnerability using its associated CVE number.
Users interested in vulnerability analysis and exploitation can use PolySwarm to find Artifacts that exploit known vulnerabilities!
- via the CLI:
polyswarm search metadata 'scan.latest_scan.\*.metadata.malware_family:*cve*'
At the time of writing, this query returns 12885
results!
Hunt WannaCry via its Killswitch Domain
WannaCry would not execute malicious logic if a particular, seemingly nonsense domain name could be resolved. Once this domain was registered, WannaCry propagation came to a halt. The domain registration was a bit of a "killswitch".
We can easily find samples of WannaCry by Metadata searching for its "killswitch" domain.
- via the CLI:
polyswarm search metadata "strings.domains:*iuqerfsodp9ifjaposdfjhgosurijfaewrwergwea.com"
Hunting EventBot
PolySwarm has been tracking the EventBot malware, a family of Android trojan applications that spread autonomously and seek to steal credentials.
For full details on the latest EventBot samples along with Metadata search tips for finding these samples on PolySwarm, please consult our Blog.
Processing Results with jq
, Malicious Artifacts in the last 15 minutes
The following will find all Artifacts first seen in the first 15 minutes of April 14th, 2020 that were detected as malicious by more than 3
Engines, extract their SHA256s from JSON and write them to the file hash.txt
:
polyswarm --fmt json search metadata 'scan.first_seen:[2020-04-14T00:00 TO 2020-04-14T00:15] AND scan.latest_scan.detections.malicious:>3' | jq -r '.artifact.sha256' > hash.txt
We see 879
results.
Next, we query these hashes for their PolySwarm and create a CSV value enumerating hash and PolyScore:
polyswarm --fmt json search hash -r hash.txt | jq -r '[.sha256, .polyscore|tostring] | join(", ")' > polyscore.txt
The resultant polyswarm.txt
file contains:
$ head polyscore.txt
8105b93e3acb65b19d43febbb139f3184f9feff2ea78a3a615e6ae58ca6dfd5d, 0.9974553968361014
f1967ed3583fed9ca3b326b8df3cc362ac65420082d93dcbda91069a8c91d7c2, 0.9364975545636711
7c6a626eb58f8324689f8d63924adc6bc9131574b801917ce5514adce3cd8fcf, 0.5883349845592594
d1fb5cc4ffd5df4bfe967edc9203a79032fc58bb76bdc0e63c9f203fa43f1eef, 0.9175460331627756
ea8701c24a9c05ab81f314468ff802cfbbe501d6048392c6e0400f038ca34d21, 0.9684573626545542
c6b975b98330feb6f04dbf262632e4027e9c9d1a5f5cdb3ef0190f592eef64e3, 0.9446378922543466
21ad837771588fb0617431a2e4d77ea16c0b6b9b1e6263c8df21d51696aab79b, 0.9974553968361014
a8472100e89a3c5e7f38c3df86fd7ff2a0af657513672226afe2fcec873e24b0, 0.9175460331627756
3883d38baeae67939b893dcb97245af2c9592a75d53f06a328a6041a65d4379a, 0.9650102417745068
e8ab71339736c76fdeafc8eda8612a502cb723fe3137427bdfc5d6ee2720b90a, 0.9995237243129788
Processing Results with jq
, Finding the Artifacts ssdeep fuzzy hash
Query for an instance of EICAr via Metadata Search: polyswarm --fmt pretty-json search metadata 'artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"'
Use the CLI &jq
to determine the Artifact's ssdeep
fuzzy hash
Request
$ polyswarm --fmt json search metadata 'artifact.sha256:"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"' | jq .hash.ssdeep
Processing Results with jq
, Finding the ClamAV Engine Assertion
Using jq
to output the scan.first_scan.ClamAV.assertion
only for the artifact.sha256
metadata search
Request
$ polyswarm --fmt pretty-json search metadata "artifact.sha256:275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" | jq .scan.first_scan.ClamAV.assertion
Response
"malicious"
Processing Results with jq
, Finding the md5 of a sha256
Using jq
to output the artifact.md5
only for the artifact.sha256
metadata search
Request
$ polyswarm --fmt pretty-json search metadata "artifact.sha256:275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" | jq .artifact.md5
Response
"44d88612fea8a8f36de82e1278abb02f"
Processing Results with jq
, Extract C2 IP's for a given hash
Find the C2 IP's that have been extracted by the triage sandbox based of a hash value.
Request
polyswarm --fmt json search hash e675677bb37b0f5d6a761c5ed4cf13fa53ef1fb579862f47944ce2715dda8f77 |jq -r '[.metadata[]|select(.tool == "triage_sandbox_v0")|.tool_metadata.extracted_c2_ips]'
Response
[
[
"95.171.16.42",
"185.90.61.9",
"5.1.81.68",
"185.99.2.65",
"134.119.191.11",
"85.204.116.100",
"78.108.216.47",
"51.81.112.144",
"194.5.250.121",
"185.14.31.104",
"185.99.2.66",
"107.175.72.141",
"192.3.247.123",
"134.119.191.21",
....
Search for Artifact's based on a Cape Sandbox TTP
To find Artifact's that relate to a MITRE TTP, use the below cli command.
Request
polyswarm --fmt json search metadata 'cape_sandbox_v2.ttp:T1089'
Locate Hashes that are using the ddns.net C2 Domain
Find sha256 hashes that have been associated to the ddns.net C2 domain from either cape or triage sandboxes.
Request
polyswarm --fmt sha256 search metadata 'cape_sandbox_v2.network.dns.request:*.ddns.net OR triage_sandbox_v0.extracted.config.dns:*.ddns.net'
Response
c2e4997f1f88c1c6eef4e4f28af5f9da462e5510496cf3509ffbaf29d424ce35
0b2f244702c64a7e238175d8e33f6c8e7df3a2f20aaf362a56b716b130ccee23
067a9fabb4c4c4d3093a0ee6ff4d8c37426b14d4a7be8ca91424b8db4e51e675
d0b8ca9a2a2d4d431be17af9699f50bda16059fd29d0897d192cc0669d42f65c
c325629bbd6472571d868dae7ae47eab1b92012b7916d8e3b8118cd45fd4e581
....
Pivot on latent .pdb information in Windows Executables
FireEye published a blog post wherein they attribute threat actors using latent Windows debug information (.pdb
paths) in malware executables.
We can use information extracted by the pefile
Tool to search for Artifacts that include PDB paths.
via the CLI:
polyswarm search metadata 'pefile.pdb:*RControl*'
-10
+ resultspolyswarm search metadata 'pefile.pdb:*shellcode.pdb'
-142
+ results- etc
IOC Searching
IOC Searching can be split into three groups of commands, these are:
- Searching for Associated IOCs related to a Hash
- Searching for Associated Hashes to an IP, URL, imphash or MITRE TTP
- Check for known good domains and IPs
Searching for Associated IOCs
Format: polyswarm search ioc sha256 <hash>
Description: List associated IOCs to a Hash by referencing the hash value.
Request
$ polyswarm search ioc sha256 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40
Response
============================= IOCs =============================
ImpHash:
IPs: 1.2.3.4, 2.2.2.2
URLs: polyswarm.io
TTPs: T1060, T1053
Searching for Associated Hashes
Format: polyswarm search ioc ip <IP>
Replace
ip
above withdomain
,imphash
,URL
orMITRE 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 theslug
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 andsandbox 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 commandpolyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id'
and for thesandbox
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
andsandbox 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 eachinsatnce_id
needs to be defined. To find theinstance id
of the file to download, use thepolyswarm 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>
OR
polyswarm historical start -r <ruleset_id>
Provide the Yara ruleset directly or provide the ruleset id of the Yara Ruleset.
Description: Start a new historical hunt providing the ruleset directly.
Options
Option | Type | Required | Description |
---|---|---|---|
-r , --rule-id |
integer | false | If provided, create this historical hunt from an existing ruleset. |
-n , --name |
string | false | Explicitly set the ruleset name for this hunt. |
Request
$ polyswarm historical start tests/eicar.yara
Response
Hunt Id: 60834480310458457
Status: PENDING
Created at: 2022-05-26 21:24:20.712138
Ruleset Name: eicar.yara
Ruleset Contents:
rule eicar_av_test {
/*
Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
The raw EICAR string to be matched is:
X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
*/
meta:
description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
author = "Austin Byers | Airbnb CSIRT"
reference = "http://www.eicar.org/86-0-Intended-use.html"
strings:
$eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/
condition:
all of them
}
rule eicar_substring_test {
/*
More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
*/
meta:
description = "Standard AV test, checking for an EICAR substring"
author = "Austin Byers | Airbnb CSIRT"
strings:
$eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"
condition:
all of them
}
Historical hunt will activate upon creation. They are created in the
PENDING
state and are scheduled for execution during the next processing window.
View a Historical Hunt Status
Format: polyswarm historical list
Description: You can see the state of your historical hunts when you use the list
command.
Options
Option | Type | Required | Description |
---|---|---|---|
-s , --since |
integer | false | How far back in seconds to request results. |
Request
$ polyswarm historical list
Response
Hunt Id: 86933257769414706
Status: PENDING
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar
Hunt Id: 60834480310458457
Status: PENDING
Created at: 2022-05-26 21:24:20.712138
Ruleset Name: eicar.yara
Hunt Id: 79157116618547376
Status: PENDING
Created at: 2022-05-26 19:07:25.339932
Ruleset Name: eicar.yara
Hunt Id: 48011760326110718
Status: LIMITED
Progress: 100.00%
Created at: 2022-05-26 17:53:07.832218
Total count: 6
eicar_av_test: 3
eicar_substring_test: 3
Ruleset Name: eicar.yara
Cancel a Historical Hunt
Format: polyswarm historical cancel <hunt_id>
Description: You can cancel a historical if you don't want it to finish by providing the hunt id. It will prevent further processing.
Request
$ polyswarm historical cancel 86933257769414706
Response
Hunt Id: 86933257769414706
Status: CANCELED
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar
Ruleset Contents:
rule eicar_av_test {
/*
Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
The raw EICAR string to be matched is:
X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
*/
meta:
description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
author = "Austin Byers | Airbnb CSIRT"
reference = "http://www.eicar.org/86-0-Intended-use.html"
strings:
$eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/
condition:
all of them
}
rule eicar_substring_test {
/*
More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
*/
meta:
description = "Standard AV test, checking for an EICAR substring"
author = "Austin Byers | Airbnb CSIRT"
strings:
$eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"
condition:
all of them
}
Delete a Historical Hunt
Format: polyswarm historical delete <hunt_id>
Description: You can also delete a historical hunt. The results associated with it will also be removed.
Since there can be a large number of results, this is an asynchronous task and might take a while to finish after it is requested.
Request
$ polyswarm historical delete 86933257769414706
Response
Successfully deleted Hunt:
Hunt Id: 86933257769414706
Status: DELETING
Created at: 2022-05-26 21:25:35.467834
Ruleset Name: eicar
Ruleset Contents:
rule eicar_av_test {
/*
Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
The raw EICAR string to be matched is:
X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
*/
meta:
description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
author = "Austin Byers | Airbnb CSIRT"
reference = "http://www.eicar.org/86-0-Intended-use.html"
strings:
$eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/
condition:
all of them
}
rule eicar_substring_test {
/*
More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
*/
meta:
description = "Standard AV test, checking for an EICAR substring"
author = "Austin Byers | Airbnb CSIRT"
strings:
$eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"
condition:
all of them
}
View or Download Historical Hunt Details
Format: polyswarm historical view <hunt_id>
Description: You can view details about the historical hunt and download a summary csv using the view
command.
Request
$ polyswarm historical view 48011760326110718
Response
Hunt Id: 48011760326110718
Status: LIMITED
Progress: 100.00%
Created at: 2022-05-26 17:53:07.832218
Total count: 6
eicar_av_test: 3
eicar_substring_test: 3
Download Results CSV:
http://minio:9000/historical/72/48/e9/7248e979625acf9f527e3ab7c8c0125e72e9b0a30b9a308b1617d475c8bcbf6bf27d52363bf2cd7b2359c70c6aac1de2ddad7daebc660cb805c99b51d4e4ff9648fe7eb1?response-content-disposition=attachment%3Bfilename%3D48011760326110718.csv&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213205Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=df334159d7a2a334f6fb0deffd6edc334f6f9188f4d29777b15a0575600114ff
Ruleset Name: eicar.yara
Ruleset Contents:
rule eicar_av_test {
/*
Per standard, match only if entire file is EICAR string plus optional trailing whitespace.
The raw EICAR string to be matched is:
X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
*/
meta:
description = "This is a standard AV test, intended to verify that BinaryAlert is working correctly."
author = "Austin Byers | Airbnb CSIRT"
reference = "http://www.eicar.org/86-0-Intended-use.html"
strings:
$eicar_regex = /^X5O!P%@AP\[4\\PZX54\(P\^\)7CC\)7\}\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\$H\+H\*\s*$/
condition:
all of them
}
rule eicar_substring_test {
/*
More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)
*/
meta:
description = "Standard AV test, checking for an EICAR substring"
author = "Austin Byers | Airbnb CSIRT"
strings:
$eicar_substring = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"
condition:
all of them
}
View Results of a Historical Hunt
Format: polyswarm historical results <hunt_id>
Description: You can see the results of a particular hunt using its hunt_id
.
Options
Option | Type | Required | Description |
---|---|---|---|
-r , --rule-name |
string | false | Filter results on the rule name |
-f , --family |
string | false | Filter hunt based on the family name |
-p , --private |
string | false | Filter results to only your Private Community, if not defined results are shown from your Private Community and the Public Community. |
-l , --polyscore-lower |
string | false | Polyscore lower bound for the hunt results |
-u , --polyscore-upper |
string | false | Polyscore upper bound for the hunt results |
Request
$ polyswarm historical results 48011760326110718
Response
Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Id: 89734617019442134
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_av_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Id: 55984849350345511
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
View or Download a Single Result of a Historical Hunt
Format: polyswarm historical result <id>
Description: You can inspect details and download the file for a result with the result
command. You will need the ID which you can find with the polyswarm historical view <hunt_id>
command.
Request
$ polyswarm historical result 34417123788028549
Response
Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Download Url: http://minio:9000/cache-public/27/5a/02/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f3395856ce81f2b7382dee72602f798b642f1414044d88612fea8a8f36de82e1278abb02f?response-content-disposition=attachment%3Bfilename%3Dinfected&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213355Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=bdd77765df45c068cd8f0d16580363003f9490ead7f4ff758aeada39bdcf9f96
Delete Historical Hunt Results
Format: polyswarm historical results-delete <id>
Description: You can delete an undesirable result by providing the ID or a list of ID's.
Request
$ polyswarm historical results-delete 34417123788028549 # you can provide a list of ids here, space separated
Response
Id: 34417123788028549
Instance Id: 72401552809848506
Created at: 2022-05-26 17:54:56.489448
SHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Rule: eicar_substring_test
PolyScore: 0.23213458159978606066
Detections: 1/1 engines reported malicious
Tags: {}
Cat Artifacts
Format: polyswarm cat <hash> |hexdump -C
Description: Cat artifact to stdout. Perform feature extraction from artifact without downloading.
Request
$ # Get C&C from malware config
$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |hexdump -C
>Response
00000000 c3 3e 34 65 04 b3 00 00 00 00 00 00 00 00 00 00 |.>4e............|
00000010 6c f7 51 3a 6b 01 00 00 1e 00 02 00 e8 03 00 00 |l.Q:k...........|
00000020 10 27 00 00 c0 d4 01 00 c0 d4 01 00 e0 93 04 00 |.'..............|
00000030 c0 27 09 00 10 27 00 00 |.'...'..|
00000038
$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |od -An -t u1 -N 4|sed 's/^ //;s/\s\{1,\}/./g'
195.62.52.101
Chain commands
Some commands in the CLI are composable using the sha256
format option and the unix pipe character |
.
For instance, if we wanted to download all the results matching a metadata query:
Request
$ polyswarm --fmt sha256 search metadata 'strings.domains:malicious.com' | polyswarm download malicious -r -
Response
Successfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/malicious/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
Or we may want to download the last new samples matched in Live Hunting for the last 1 hour:
Request
$ polyswarm --fmt sha256 live feed -s 3600 | polyswarm download /tmp/download -r -
Response
Successfully downloaded artifact 513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831 to /tmp/download/513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831
Successfully downloaded artifact 7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724 to /tmp/download/7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724
Successfully downloaded artifact 2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9 to /tmp/download/2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9
Successfully downloaded artifact a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875 to /tmp/download/a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875
Successfully downloaded artifact b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce to /tmp/download/b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce
Successfully downloaded artifact bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142 to /tmp/download/bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142
Successfully downloaded artifact ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6 to /tmp/download/ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6
Successfully downloaded artifact a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4f to /tmp/download/a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4f
Lookup UUIDs
Format: polyswarm rules create eicar <file.yara>
Description: Scan results are referenced by their Submission UUID.
Request
$ polyswarm -vvv -o /tmp/test.json --fmt json lookup 50446025732260182
In this example, we demonstrate the
--fmt json
option, which saves the output in json format.
Response
info [polyswarm.base]: Running polyswarm-cli version 2.0.0 with polyswarm-api version 2.0.0
debug [polyswarm_api.api]: Creating PolyswarmAPI instance: api_key: cc2fdb7efa803cefcebd3c9750aab0ee, api_uri: https://api.polyswarm.network/v2, community: default
debug [polyswarm_api.http]: Creating PolyswarmHTTP instance
debug [polyswarm_api.endpoint]: Creating PolyswarmRequestGenerator instance
debug [polyswarm_api.endpoint]: Creating PolyswarmRequest instance.
debug [polyswarm_api.endpoint]: Request parameters: {'method': 'GET', 'url': 'https://api.polyswarm.network/v2/consumer/submission/default/50446025732260182'}
debug [polyswarm_api.endpoint]: Result parser: ArtifactInstance
debug [polyswarm_api.endpoint]: Executing request.
debug [urllib3.connectionpool]: Starting new HTTPS connection (1): api.polyswarm.network:443
debug [urllib3.connectionpool]: https://api.polyswarm.network:443 "GET /v2/consumer/submission/default/50446025732260182 HTTP/1.1" 200 None
debug [polyswarm_api.endpoint]: Request returned code 200 with content:
debug [polyswarm_api.endpoint]: b'{"result":{"artifact_id":"79510820469876527","assertions":[{"author":"0x45b94B4AFE4E4B5Bd7f70B84919fba20f1FAfB3f","author_name":"Qihoo 360","bid":"1000000000000000000","engine":{"description":null,"name":"Qihoo 360"},"mask":true,"metadata":{"malware_family":"qex.eicar.gen.gen","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}}},"verdict":true},{"author":"0xbec683492f5D509e119fB1B60543A1Ca595e0Df9","author_name":"Lionic","bid":"1000000000000000000","engine":{"description":null,"name":"Lionic"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}}},"verdict":false},{"author":"0x162675F361F6ff8D6F91e4833f4BA94587AF3655","author_name":"XVirus","bid":"812500000000000000","engine":{"description":null,"name":"XVirus"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"vendor_version":"3.0.2.0","version":"0.2.0"}},"verdict":false},{"author":"0x80Ed773972d8BA0A4FacF2401Aca5CEba52F76dc","author_name":"Nucleon","bid":"1000000000000000000","engine":{"description":"Nucleon, The only provider that guarantees 0% false positive. using Nucleon unique offering organizations can reduce thier TCO dramtically and enjoy cyber intelligence like governments have.","name":"Nucleon"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"","version":"0.1.0"}},"verdict":false},{"author":"0x8d80CEe474b9004949Cf7e4BfA28460AC8e370a1","author_name":"Virusdie","bid":"1000000000000000000","engine":{"description":null,"name":"Virusdie"},"mask":true,"metadata":{"malware_family":"EICAR.TEST","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"1.3.0","version":"0.3.0"}},"verdict":true},{"author":"0x7839aB10854505aBb712F10D1F66d45F359e6c89","author_name":"Ikarus","bid":"1000000000000000000","engine":{"description":null,"name":"Ikarus"},"mask":true,"metadata":{"malware_family":"EICAR-Test-File","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"signatures_version":"21.02.2020 13:15:46 (102417)","vendor_version":"5.2.9.0","version":"0.2.0"}},"verdict":true},{"author":"0x3750266F07E0590aA16e55c32e08e48878010f8f","author_name":"ClamAV","bid":"1000000000000000000","engine":{"description":null,"name":"ClamAV"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"vendor_version":"ClamAV 0.101.4/25730/Fri Feb 21 12:08:06 2020"}},"verdict":false},{"author":"0x10A9eE8552f2c6b2787B240CeBeFc4A4BcB96f27","author_name":"Alibaba","bid":"1000000000000000000","engine":{"description":null,"name":"Alibaba"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"}},"type":"eicar"},"verdict":false},{"author":"0xbE0B3ec289aaf9206659F8214c49D083Dc1a9E17","author_name":"K7","bid":"1000000000000000000","engine":{"description":null,"name":"K7"},"mask":true,"metadata":{"malware_family":"EICAR_Test_File","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"signatures_version":"11.95.33362, 21-Feb-2020","vendor_version":"15.2.0.42","version":"0.2.0"}},"verdict":true},{"author":"0x2b4C240B376E5406C5e2559C27789d776AE97EFD","author_name":"NanoAV","bid":"1000000000000000000","engine":{"description":null,"name":"NanoAV"},"mask":true,"metadata":{"malware_family":"Marker.Dos.EICAR-Test-File.dyb","scanner":{"environment":{"architecture":"AMD64","operating_system":"Windows"},"signatures_version":"0.14.33.17090","vendor_version":"1.0.134.90567","version":"0.1.0"}},"verdict":true},{"author":"0xb9b1FA288F7b1867AEF6C044CDE12ab2De252113","author_name":"VenusEye","bid":"812500000000000000","engine":{"description":null,"name":"VenusEye"},"mask":true,"metadata":{"malware_family":"","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"version":"0.1.0"}},"verdict":false},{"author":"0xBAFcaF4504FCB3608686b40eB1AEe09Ae1dd2bc3","author_name":"DrWeb","bid":"1000000000000000000","engine":{"description":null,"name":"DrWeb"},"mask":true,"metadata":{"malware_family":"EICAR Test File (NOT a Virus!)","scanner":{"environment":{"architecture":"x86_64","operating_system":"Linux"},"signatures_version":"864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42","vendor_version":"7.00.44.12030","version":"0.3.0"}},"verdict":true}],"community":"lima","country":"US","created":"2020-02-21T19:21:59.196578","extended_type":"EICAR virus test files","failed":false,"filename":"malicious.txt","first_seen":"2020-01-24T21:56:21.456900","id":"50446025732260182","last_seen":"2020-02-21T19:21:59.196578","md5":"a6a57bf20416a4c712c4a1eabcaeb235","metadata":[{"created":"2020-02-20T22:29:45.801434","tool":"strings","tool_metadata":{"domains":[],"ipv4":[],"ipv6":[],"urls":[]}},{"created":"2020-02-20T22:29:45.675692","tool":"hash","tool_metadata":{"md5":"a6a57bf20416a4c712c4a1eabcaeb235","sha1":"a33fb79e9c71f1b446607d437a1984602ed47d5c","sha256":"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf","sha3_256":"ab1256000f634456fac4fe42bbc0bf39256e4bab954dc8c8f241433d07895fad","sha3_512":"737ec00fa15de1defdca9993c7d95058c2f30b658ef66c8b978287c1042d7ba7283d8d1130c356fbb8058bd739c5e349169ad93f4f428a830720ee107c6df288","sha512":"2f79598bc355b385be7c7b785ec74073bf4b59b8095c1b1f7291e0dd04e5e140f700bcc583809ec63d6d98991698273c1678bd3399ec0b1b8ba9f60be151ec3b","ssdeep":"3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX","tlsh":"ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8"}}],"mimetype":"text/plain","polyscore":0.07193209420451106,"result":null,"sha1":"a33fb79e9c71f1b446607d437a1984602ed47d5c","sha256":"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf","size":132,"type":"FILE","votes":[{"arbiter":"0xB63cD054D7E63D9Ce8AbB403a0dfa11b26A1fB89","vote":false},{"arbiter":"0xd8b48Da78188312c5fC079E532afd48De973767E","vote":true},{"arbiter":"0xdC6a0F9C3AF726Ba05AaC14605Ac9B3b958512d7","vote":false}],"window_closed":true},"status":"OK"}\n'
debug [polyswarm_api.endpoint]: Parsing request results.
debug [polyswarm_api.types.base]: Parsing resource ArtifactInstance
For information regarding the JSON format of a result object, please see polyswarm-api's API.md.
Changelog
Version 3.8.1
Release Date: 2024-09-24 Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | Updated Validation URL | Less strict validation on URLs provided as an argument when scanning and sandboxing. |
2.0 | Error Reporting | Scans and Sandboxing now shows the Faliure Reason if applicable in the cli response. |
3.0 | Bug Fix Sandbox | Fixed exception when sandbox doesn't have the config.artifact_type field set. |
Version 3.8.0
Release Date: 2024-08-07
Breaking Changes: Item 5.0
Item | Topic | Description |
---|---|---|
1.0 | Submit URL from QR Code images | New arg --qrcode-file in polyswarm scan url and polyswarm sandbox url |
2.0 | Get basic account's information | New command polyswarm account whois . |
3.0 | Get account's features and quota available | New command polyswarm account features . |
4.0 | New options to create zip reports | polyswarm report create [--sandbox_artifact_types --zip-report-ids] |
5.0 | Rename command argument | --sandbox argument is renamed to --provider . |
Version 3.7.0
Release Date: 2024-06-27
Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | Wait and download reports | New --nowait , --timeout and --destination arguments in the report command. |
2.0 | Support zip file submissions | New --is-zip and --zip-password arguments in scan and sandbox commands. |
Version 3.6.0
Release Date: 2024-05-20
Breaking Changes: Item 3.0
Item | Topic | Description |
---|---|---|
1.0 | Reports Generation | Introduction of reports generation via the report CLI command. |
2.0 | Reports Templates | Introduction of reports templates management via the report-template CLI command. |
3.0 | Python versions supported | Minimal Python version supported is 3.7. |
Version 3.5.2
Release Date: 2024-02-22
Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | URL Sandboxing | Introduction of URL Sandboxing via the sandbox url cli command. |
Version 3.5.1
Release Date: 2023-12-06
Breaking Changes: 1.0
Item | Topic | Description |
---|---|---|
1.0 | IOC Search - Hash | Previously ioc search by hash returned a Generator, which was not correct. This fix has resolved this issue, to prevent the has_more flag being returned. |
Version 3.4.1
Release Date: 2023-09-20
Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | Added Private Parameter to Live Results | Added parameter --private to polyswarm live feed to allow you to see results from a private community. |
2.0 | Added Private Parameter to Historical Results | Added parameter --private to polyswarm historical results to allow you to see results from a private community. |
3.0 | New Permalink Structure | New Permalink Structure |
Version 3.4.0
Release Date: 2023-07-12
Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | polyswarm sandbox providers |
New output with provider and slug information. |
2.0 | Update to polyswarm sandbox file |
Added new config arguments provider_slug and vm_slug . |
3.0 | Update to polyswarm sandbox instance |
Added new config arguments provider_slug and vm_slug . |
Version 3.3.0
Release Date: 2023-06-20
Breaking Changes: Item 2.0
Item | Topic | Description |
---|---|---|
1.0 | Dropping python 2.7 support | - |
2.0 | polyswarm sandbox submit changes | Change polyswarm sandbox submit to polyswarm sandbox instance . |
3.0 | polyswarm sandbox list changes | Change polyswarm sandbox list to polyswarm sandbox providers . |
4.0 | Additional Sub-Commands for Sandbox | lookup, lookup-id, search, file, my-tasks. |
Version 3.2.1
Release Date: 2023-05-29
Breaking Changes: N/A
Item | Topic | Description |
---|---|---|
1.0 | Bug fix for search ioc |
Fix an issue with results not displaying with the polyswarm search ioc command. |