PolySwarmPolySwarmPolySwarmPolySwarm
Go to PolySwarm
Home

PolySwarm Rest API v3

Rest API Endpoints for interacting with version 3 of the PolySwarm Customer APIs.

Getting Started

Using the API

PolySwarm's API provides a RESTful interface for various PolySwarm features. If you'd like to report an issue or provide feedback for this page, please contact [email protected]

The PolySwarm API is available at https://api.polyswarm.network/v3

For the rest of this document, the base API URL will not be included in any endpoints (e.g., the branch for search will be described as /v3/search rather than https://api.polyswarm.network/v3/search). You will be responsible for adding the correct base API URL.

The overview of the API Endpoints will include required and optional parameters, with a curl example.

Authentication

Every API request must include an HTTP Authorization Header with an API key.

Locate the api_key for the User/Team from here

HTTP Header Value
Authorization API Key

Example:

curl -X GET -H "Authorization: $API_KEY" 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default'

Retrieve account information

Account details

/v3/public/accounts/whois

Query Sample

curl https://api.polyswarm.network/v3/public/accounts/whois -H "Authorization: $POLYSWARM_API_KEY"

Account features and quotas

/v3/public/accounts

Query Sample

curl https://api.polyswarm.network/v3/public/accounts -H "Authorization: $POLYSWARM_API_KEY"

Artifact Lookup

To retrieve the results of a scan or sandbox, you can do an artifact lookup. In the scanning/sandboxing sections we will remind you of this.

GET /v3/consumer/submission/default/{artifact_id}

Once the scan has completed the returned window_closed value will be true, if this value is false then the scan is still processing, so you will need to poll periodically. If the value failed is true then the scan has failed.

Scanning Artifacts

The following are the 3 sequential steps in a Scanning operation:

  • POST Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS URL that the artifact can be uploaded to
  • PUT Upload the artifact to the AWS URL location
  • PUT Inform PolySwarm that the artifact is uploaded and to start the scan

Lastly, lookup the artifact for the verdict, follow this process here.

URL Scanning

POST /v3/instance

Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS URL that the file/url can be uploaded to

Body Schema (application/json)

Parameter Type Required Description
artifact_name string true URL value to be scanned.
artifact_type string true Defines the type, should be URL.
scan_config string false Allows additional time for the scan, default if not provided, default, more-time, most-time.
url-file string false Path of the file containing a single line of the URL to be scanned.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
preprocessing object false Set to {"type": "qrcode"} if the URL is inside a QR Code image.

Query Sample

curl -X POST -d '{
  "artifact_name": "https://www.google.com",
  "artifact_type": "URL",
  "community": "default"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/instance

Here is a sample of how to scan a URL that is inside a QR Code image:

curl -X POST -d '{
  "artifact_name": "qrcode.png",
  "artifact_type": "URL",
  "community": "default",
  "preprocessing": {"type": "qrcode"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the artifact to upload to the AWS URL.

Query Sample

curl -X PUT '<PRE_SIGNED_AWS_URL>' -d 'content=www.google.com'

PUT /v3/instance

Inform PolySwarm the upload is complete and to start the scan.

Query Parameters

Parameter Type Required Description
id string true artifact_id that has been returned by the first POST command.

Query Sample

curl -X PUT -H "Content-Type: application/json" https://api.polyswarm.network/v3/instance?id=49722305458696948 -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

File Scanning

POST /v3/instance

Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS url that the file needs to be placed into.

Body Schema (application/json)

Parameter Type Required Description
artifact_name string true Path of the File to be scanned.
artifact_type string true Defines the type, should be FILE.
preprocessing object false Preprocessing settings to be applied to the artifact. See schema table bellow.
scan_config string false Allows additional time for the scan, default if not provided, default, more-time, most-time.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Body / Preprocessing Schema (application/json)

Parameter Type Required Description
type string true Either zip or qrcode, the first mean the file is a zip that the server has to decompress to then scan the content (only one file inside allowed). "qrcode" means the file is a QR Code image with a URL as payload, and you want to scan the URL, not the actual file (artifact_type has to be "URL").
password string false Use this password to decompress the zip file.

Query Sample

Scan a file install.exe example:

curl -X POST -d '{
  "artifact_name": "install.exe",
  "artifact_type": "FILE",
  "community": "default"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/instance

The file to scan is inside an encrypted zip:

curl -X POST -d '{
  "artifact_name": "install.exe",
  "artifact_type": "FILE",
  "community": "default",
  "preprocessing": {"type": "zip", "password": "password"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the artifact to upload to the AWS URL.

Query Sample

curl --upload-file ./tests/eicar.yara "<PRE_SIGNED_AWS_URL>"

PUT /v3/instance

Inform PolySwarm the upload is complete and to start the scan.

Query Parameters

Parameter Type Required Description
id string true artifact_id that has been returned by the first POST command.

Query Sample

curl -X PUT https://api.polyswarm.network/v3/instance?id=49722305458696948 -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

Rescanning Artifacts

POST /v3/consumer/submission/default/rescan/sha256/{sha256}

Other Endpoints include: /v3/consumer/submission/default/rescan/md5/{md5} and /v3/consumer/submission/default/rescan/sha1/{sha1}

Query Parameters

Parameter Type Required Description
hash-type string false Hash type to be searched on, default is autodetect.
scan-config string false Configuration template to use, provides more time for the results to be returned, default, more-time, most-time.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Query Sample

curl -X POST 'https://api.polyswarm.network/v3/consumer/submission/default/rescan/sha256/5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default&scan_config=more-time' -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

Downloading

Download an Artifact

GET /v3/consumer/download/sha256/{sha256}

Other Endpoints include: /v3/consumer/download/sha256/{md5} and /v3/consumer/download/sha256/{sha1}

Query Parameters

Parameter Type Required Description
hash-type string false Hash type to be searched on, default is autodetect.
destination string false Local Path where to store the downloaded files.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/consumer/download/sha256/5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default' -H "Authorization: $API_KEY"

Download via id

GET /v3/instance/download

Tip: Can be used to download reports and files from a sandbox detonation, see sandboxing sections to retrieve the instance_id.

Query Parameters

Parameter Type Required Description
instance_id integer true instance_id of the item to download, often provided in the output of a previous query.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/instance/download?instance_id=84432173138232095' -H "Authorization: $API_KEY"

Reporting

Downloading Reports

PolySwarm provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing, these are separate reports.

The following are the 3 sequential steps in a report generation operation:

  • POST Inform PolySwarm to start generating the report.
  • GET Poll PolySwarm to understand when the report has finished generating.
  • GET Download the report locally once generation is successful.

POST /v3/reports

Body Schema (application/json)

Parameter Type Required Description
format string true pdf, html or zip.
type string true scan, sandbox, or sandbox_zip.
template_metadata object false Choose what to include in the report or zip file, separated by commas. When choosing a PDF or HTML report the options are: analysis, detections, droppedFiles, extractedConfig, fileMetadata, network, summary. If not included in body, the default is all items. EXAMPLE: {"includes":["summary"]}. When choosing a Sandbox ZIP file there are two optional values in the template_metadata, zip_report_ids and sandbox_artifact_type. The zip_report_ids are the ID's of the other reports already created to include in the zip file. The sandbox_artifact_type are a list of sandbox artifacts to include from: report,raw_report,screenshot,recording,dropped_file,memory_dump,pcap and jarm.
instance_id integer true Required if generating a scanning report, this is the artifact_id.
sandbox_task_id integer true Required if generating a sandboxing report or sandbox zip, this is the sandbox_id.

Query Sample Scan Report

curl -X POST -d '{"type": "scan", "format": "pdf", "template_metadata": {"includes": ["summary", "detections"]}, "instance_id": "97903321852386706"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports

Query Sample Sandbox ZIP File

The below example downloads the report json and the pcap files in a single zip file.

curl -X POST -d '{"type": "sandbox_zip", "format": "zip", "template_metadata": {"sandbox_artifact_types": ["report", "pcap"]}, "sandbox_task_id": "97903321852386706"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports

GET /v3/reports

Query Parameters

Parameter Type Required Description
id integer true id returned from the previous POST command.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports?id=59403308938961820' -H "Authorization: $API_KEY"

GET https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Note: The previous GET command returns the PRESIGNEDAWS_URL once the report generation has been completed.

Query Sample

curl -o scan-97903321852386706.pdf -X GET 'https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}'

Report Templates

List templates

GET /v3/reports/templates/list

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates/list' -H "Authorization: $API_KEY"
Create a template

POST /v3/reports/templates

Body Schema (application/json)

Parameter Type Required Description
template_name string true Name for the template.
is_default boolean false If true this template will be the default template for the team.
primary_color string false Six-character hex color code.
footer_text string false Text to be displayed in the footer of each page. Up to 100 characters are allowed.
last_page_text string false Text to be displayed on the last page. Up to 1000 characters are allowed.
includes string false Array list of sections to include in the report. Can be one or more of: "analysis", "detections", "droppedFiles", "extractedConfig", "fileMetadata", "network", "summary".

Query Sample

curl -X POST -d '{"template_name": "temptest", "primary_color": "ff0000", "includes": ["summary", "detections", "fileMetadata"]}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports/templates
Delete a templates

DELETE /v3/reports/templates

Query Parameters

Parameter Type Required Description
id integer true id value of the template.

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/reports/templates?id=10512439389909571' -H "Authorization: $API_KEY"
Get template details

GET /v3/reports/templates

Query Parameters

Parameter Type Required Description
id integer true id value of the template.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates?id=89035259732911602' -H "Authorization: $API_KEY"
Update a template

PUT /v3/reports/templates

NOTE: despite being a PUT endpoint, only fields passed in the JSON body are updated, the remaining fields retain their values. Query Parameters

Parameter Type Required Description
id integer true id value of the template.

Body Schema (application/json)

Parameter Type Required Description
template_name string true Name for the template.
is_default boolean false If true this template will be the default template for the team.
primary_color string false Six-character hex color code.
footer_text string false Text to be displayed in the footer of each page. Up to 100 characters are allowed.
last_page_text string false Text to be displayed on the last page. Up to 1000 characters are allowed.
includes string false Array list of sections to include in the report. Can be one or more of: "summary", "detections", "fileMetadata", "network", "droppedFiles", "extractedConfig", "analysis".

Query Sample

curl -X PUT -d '{"primary_color": "7bfa7f", "includes": ["summary", "detections", "fileMetadata"]}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" "https://api.polyswarm.network/v3/reports/templates?id=89035259732911602"

PUT /v3/reports/templates/logo

A logo can be provided for an already created template. The image is only used in the first page of the PDF reports. Can be either a PNG or JPEG file, the max size allowed is 40 Kb, and the max resolution 960px x 960px.

Query Parameters

Parameter Type Required Description
id integer true id value of the template

Body Parameters

The body has to be the binary data of the image. Max length allowed is 40 Kb.

Header Parameters

Parameter Required Description
Content-Type true Either image/png or image/jpeg

Query Sample

Having a file logo.jpg in the same folder were curl is executed:

curl -X PUT 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' --data-binary @logo.jpg -H "Content-Type: image/jpeg" -H "Authorization: $API_KEY"

DELETE v3/reports/templates/logo

Query Parameters

Parameter Type Required Description
id integer true id value of the template.

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H "Authorization: $API_KEY"

GET v3/reports/templates/logo

Query Parameters

Parameter Type Required Description
id integer true id value of the template.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H "Authorization: $API_KEY" --output /Users/John/Documents/logo.jpg

Searching

GET /v3/search/url

Query Parameters

Parameter Type Required Description
url string true URL value to be searched.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default' -H "Authorization: $API_KEY"

GET /v3/search/hash/sha256

Other Endpoints include: /v3/search/hash/md5 and /v3/search/hash/sha1

Query Parameters

Parameter Type Required Description
hash string true Hash (sha256,md5 or sha1) value to be searched.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
hash-type string false Hash type to be searched on, default is autodetect.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/hash/sha256?hash=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default' -H "Authorization: $API_KEY"

GET /v3/search/metadata/query

To build out the metadata query, see this page.

Query Parameters

Parameter Type Required Description
query string true Metadata query to search on.
include string false Metadata field to include in results.
exclude string false Metadata field to exclude in results.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/metadata/query?query=artifact.sha256:5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"
Search for Associated IOCs

GET /v3/ioc/sha256/{sha256}

Other Endpoints include: /v3/ioc/md5/{md5} and /v3/ioc/sha1/{sha1}. Include the desired hash value in the endpoint to retrieve associated ip,domain, ttp and imphash results.

Query Parameters

Parameter Type Required Description
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/ioc/sha256/2a85d68c1c503d9b6efcf124ac7d7afc0f3a8a0543f5d6790ebd978f4e8468bd?community=default' -H "Authorization: $API_KEY"
Search for Associated Hashes

GET /v3/ioc/search

Query Parameters

Parameter Type Required Description
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
imphash string false imphash to see related hashes.
domain string false domain to see related hashes.
ttp string false MITRE ttp to see related hashes.
ip string false IP to see related hashes.

Requires at least one of the values imphash, domain, ttp or ip in the query.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/ioc/search?ip=193.138.218.74&community=default' -H "Authorization: $API_KEY"

Sandboxing

List Sandboxes

GET /v3/sandbox/provider/list

List the provider_slug and vm_slug values for sandboxing a file and/or artifact.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/provider/list' -H "Authorization: $API_KEY"

Sandboxing a File/URL

Want to know what files types are supported? See here

POST /v3/sandbox/sandboxtask/instance

Inform PolySwarm to start a sandbox, returns an artifact_id and pre signed AWS url that the file needs to be placed into. This is the same process for Sandboxing a File and Sandboxing a URL, as the process for URL will be to upload a file with the URL inside it.

Body Schema (application/json)

Parameter Type Required Description
artifact_name string true Path to File of the artifact to be sandboxed or URL string.
artifact_type string true Defines the type, FILE to Sandbox a file, URL to Sandbox a URL.
preprocessing object false Preprocessing settings to be applied to the artifact. See schema table bellow.
provider_slug string true Name of the sandbox to detonate on. For URL Sandboxing only Triage is Supported.
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
vm_slug string true Slug name for the sandbox vm to use, for URL Sandboxing only Windows 10 on Triage is Supported.
browser string false Optional value to choose the browser for URL detonation, only edge supported.

Body / Preprocessing Schema (application/json)

Parameter Type Required Description
type string true Either zip or qrcode, the first mean the file is a zip that the server has to decompress to then sandbox the content (only one file inside allowed). "qrcode" means the file is a QR Code image with a URL as payload, and you want to sandbox the URL, not the actual file (artifact_type has to be "URL").
password string false Use this password to decompress the zip file.

Query Sample

Here is a simple sandboxing POST request:

curl -X POST -d '{
  "artifact_name": "eicar.txt",
  "artifact_type": "FILE",
  "community": "default",
  "sandbox": "cape"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance

Here is an example using the "preprocessing" argument to send an encrypted zip file:

curl -X POST -d '{
  "artifact_name": "target.zip",
  "artifact_type": "FILE",
  "community": "default",
  "sandbox": "cape",
  "preprocessing": {"type": "zip", "password": "password"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the file to upload to the AWS URL.

Query Sample

curl --upload-file ./tests/eicar.txt "<PRE_SIGNED_AWS_URL>"

PUT /v3/instance

Inform PolySwarm the upload is complete and to start the sandbox.

Query Parameters

Parameter Type Required Description
id string true artifact_id that has been returned by the first POST command.

Query Sample

curl -X PUT https://api.polyswarm.network/v3/sandbox/sandboxtask/instance?id=49722305458696948 -H "Authorization: $API_KEY"

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 an Existing Artifact

POST /v3/sandbox/sandboxtask

Send an existing artifact to be sandboxed by providing its artifact id, and the chosen Sandbox provider.

Body Schema (application/json)

Parameter Type Required Description
artifact_id integer true artifact_id value for the artifact.
provider_slug string true Sandbox provider name.
vm_slug string false Slug name for the sandbox vm to use.

Query Sample

curl -X POST -d '{"artifact_id": "66885603025097785", "provider_slug": "cape"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask

Lookup Sandbox Task

GET /v3/sandbox/sandboxtask

Lookup the results from the specified sandbox task.

Query Parameters

Parameter Type Required Description
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
sandbox_task_id integer true sandbox task id value.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask?community=default&sandbox_task_id=29603365297891589' -H "Authorization: $API_KEY"

Lookup Latest Sandbox Task

GET /v3/sandbox/sandboxtask/latest

Lookup the results from the most recent sandbox task that was run on the provided sha256 in the provided sandbox.

Query Parameters

Parameter Type Required Description
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
sha256 string true Hash value to lookup.
sandbox string true Name of the Sandbox, e.g. cape, triage.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/latest?community=default&sandbox=cape&sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"

Download Sandbox Artifact

To download Sandbox Artifacts like pcap, jarm or report files follow this section to download via instance_id.

Each file (pcap,report etc) will have its own instance_id, these can be found by using the "Lookup Sandbox Task" (/v3/sandbox/sandboxtask) command, and each file name will have an instance_id listed beside it.

List my Sandbox Tasks

GET /v3/sandbox/sandboxtask/my-tasks

Find all sandbox tasks that you or your team members have run in the chosen date range.

Query Parameters

Parameter Type Required Description
community string true Name of the Community. Simplest to use default for the public community, or private for your Private Community.
sandbox string false Name of the sandbox to search on.
start-date string false Start date to search.
end-date string false End date to search.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/my-tasks?community=default' -H "Authorization: $API_KEY"

Search Sandbox Tasks

GET /v3/sandbox/sandboxtask/list

Find all sandbox tasks associated with a sha256 (i.e. each time that artifact was sandboxed).

Query Parameters

Parameter Type Required Description
sha256 string true Hash value to find related tasks.
sandbox string false Sandbox name to search.
start-date string false Start date for the search.
end-date string false End date for the search.
status string false Status of the sandbox task i.e. PENDING.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/list?sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"

Hunting with Yara

Managing Yara Rulesets

Create Ruleset

POST /v3/hunt/rule

Create a new ruleset.

Body Schema (application/json)

Parameter Type Required Description
yara string true Yara values, escape the items.
name string true Name of the ruleset.
description string false Description for the ruleset.

Query Sample

curl -X POST -d '{"yara": "\/*\r\n This Yara ruleset is under the GNU-GPLv2 license (http:\/\/www.gnu.org\/licenses\/gpl-2.0.html) and open to any user or organization, as long as you use it under this license.\r\n\r\n*\/\r\n\r\nimport \"pe\"\r\n\r\nrule MirageStrings\r\n{\r\n meta:\r\n description = \"Mirage Identifying Strings\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n strings:\r\n $ = \"Neo,welcome to the desert of real.\" wide ascii\r\n $ = \"\/result?hl=en&id=%s\"\r\n \r\n condition:\r\n  any of them\r\n}\r\n\r\nrule Mirage\r\n{\r\n meta:\r\n description = \"Mirage\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n condition:\r\n MirageStrings\r\n}\r\n\r\nrule Mirage_APT\r\n{\r\n meta:\r\n Author = \"Silas Cutler\"\r\n Date = \"yyyy\/mm\/dd\"\r\n Description = \"Malware related to APT campaign\"\r\n Reference  = \"Useful link\"\r\n \r\n strings:\r\n $a1 = \"welcome to the desert of the real\"\r\n $a2 = \"Mirage\"\r\n $b = \"Encoding: gzip\"\r\n $c = \/\\\/[A-Za-z]*\\?hl=en\/\r\n\r\n condition: \r\n (($a1 or $a2) or $b) and $c\r\n}", "name": "test_rule"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule
View Ruleset

GET /v3/hunt/rule

View the contents of the specified ruleset.

Query Parameters

Parameter Type Required Description
id integer true ruleset id value to view the contents.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H "Authorization: $API_KEY"
List Rulesets

GET /v3/hunt/rule/list

List all rulesets in your account

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/rule/list' -H "Authorization: $API_KEY"
Update Ruleset

PUT /v3/hunt/rule

Query Parameters

Parameter Type Required Description
id integer true ruleset_id that needs to be updated.

Body Schema (application/json)

Parameter Type Required Description
name string false New updated name for the ruleset.
file string false New updated yara values, escaped.
description string false New updated description.

Query Sample

curl -X PUT -d '{"yara": "\/*\r\n This Yara ruleset is under the GNU-GPLv2 license (http:\/\/www.gnu.org\/licenses\/gpl-2.0.html) and open to any user or organization, as long as you use it under this license.\r\n\r\n*\/\r\n\r\nimport \"pe\"\r\n\r\nrule MirageStrings\r\n{\r\n meta:\r\n description = \"Mirage Identifying Strings\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n strings:\r\n $ = \"Neo,welcome to the desert of real.\" wide ascii\r\n $ = \"\/result?hl=en&id=%s\"\r\n \r\n condition:\r\n  any of them\r\n}\r\n\r\nrule Mirage\r\n{\r\n meta:\r\n description = \"Mirage\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n condition:\r\n MirageStrings\r\n}\r\n\r\nrule Mirage_APT\r\n{\r\n meta:\r\n Author = \"Silas Cutler\"\r\n Date = \"yyyy\/mm\/dd\"\r\n Description = \"Malware related to APT campaign\"\r\n Reference  = \"Useful link\"\r\n \r\n strings:\r\n $a1 = \"welcome to the desert of the real\"\r\n $a2 = \"Mirage\"\r\n $b = \"Encoding: gzip\"\r\n $c = \/\\\/[A-Za-z]*\\?hl=en\/\r\n\r\n condition: \r\n (($a1 or $a2) or $b) and $c\r\n}", "name": "yytest_rule4444"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616
Delete Ruleset

DELETE /v3/hunt/rule

Delete the given ruleset.

Query Parameters

Parameter Type Required Description
id integer true ruleset_id value to delete.

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H "Authorization: $API_KEY"

Live Hunts

Start Live Hunt

POST /v3/hunt/rule/live

Start a Live Hunt using the given ruleset.

Body Schema (application/json)

Parameter Type Required Description
rule_id integer true rule_id of the ruleset to start a live hunt.

Query Sample

curl -X POST -d '{"rule_id":"6992666340481223"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule/live
Stop Live Hunt

DELETE /v3/hunt/rule/live

Stop the Live Hunt on a given ruleset.

Body Schema (application/json)

Parameter Type Required Description
rule_id integer true rule_id of the ruleset to stop a live hunt/

Query Sample

curl -X DELETE -d '{"rule_id":"6992666340481223"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule/live
View Live Results of a Live Hunt

GET /v3/hunt/live/list

Query Parameters

Parameter Type Required Description
since integer false Time value (in seconds) for how far back to request results (default 1440).
rule-name integer false Name of the ruleset being used in the hunt.
family string false Filter results based on the family name.
community string false Filter results based community.
polyscore-lower string false Polyscore lower bound for the hunt results.
polyscore-upper string false Polyscore upper bound for the hunt results.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/live/list?polyscore-upper=0.99' -H "Authorization: $API_KEY"
View a Singular Result

GET /v3/hunt/live

Query Parameters

Parameter Type Required Description
id integer true Provide the result id value.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/live?id=75570120079919313' -H "Authorization: $API_KEY"
Delete Live Result

DELETE /v3/hunt/live/list

Body Schema (application/json)

Parameter Type Required Description
result_ids integer true List of ruleset_ids for the live hunt results to be deleted.

Query Sample

curl -X DELETE -d '{"result_ids":["66625018770158663"]}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/live/list

Historical Hunts

Start a Historical Hunt

POST /v3/hunt/historical

start a new Historical Hunt using the provided yara rules or existing ruleset file.

Body Schema (application/json)

Parameter Type Required Description
rule_id integer true rule_id of the ruleset to start a historical hunt.
yara string true Path of the yara file to start a historical hunt.

Either rule_id or yara is required in the call.

Query Parameters

Parameter Type Required Description
name string false Name of the ruleset to start an historical hunt.

Query Sample

curl -X POST -d '{"rule_id":"24285974317896172"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/historical
Cancel an Historical Hunt

PUT /v3/hunt/historical

Stop a Historical Hunt. If it's already running, it will stop at the next batch interval.

Query Parameters

Parameter Type Required Description
id integer true id of the historical hunt to stop.

Query Sample

curl -X PUT 'https://api.polyswarm.network/v3/hunt/historical?' -H "Authorization: $API_KEY"
List Historical Hunts

GET /v3/hunt/historical/list

List the Historical Hunts in your account.

Query Parameters

Parameter Type Required Description
since integer false Value in seconds to look for Historical Hunts.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/list' -H "Authorization: $API_KEY"
View Historical Hunt Details for a Hunt

GET /v3/hunt/historical

Provides ability to download results as a csv file and see the ruleset contents.

Query Parameters

Parameter Type Required Description
id integer true historical hunt id to view details.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical?id=75570120079919313' -H "Authorization: $API_KEY"
View Historical Hunt Results

GET /v3/hunt/historical/results/list

Query Parameters

Parameter Type Required Description
id integer true Historical hunt id.
rule-name integer false Ruleset name to filter results.
family integer false Family name to filter results.
community string false Filter results based community.
polyscore-lower integer false Polyscore lower bound for the results.
polyscore-upper integer false Polyscore upper bound for the results.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results/list?id=75570120079919313' -H "Authorization: $API_KEY"
View a Singular Historical Hunt Result

GET /v3/hunt/historical/results

Query Parameters

Parameter Type Required Description
id integer true result_id value to view single result.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results?id=75570120079919313' -H "Authorization: $API_KEY"
Delete a Historical Hunt

DELETE /v3/hunt/historical

Query Parameters

Parameter Type Required Description
id integer true hunt id of the historical hunt to delete it.

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/hunt/historical?id=1371741361996923' -H "Authorization: $API_KEY"
Delete Historical Hunt Results

DELETE /v3/hunt/historical/results/live

Body Schema (application/json)

Parameter Type Required Description
result_ids integer true ruleset_id of the historical hunt to delete results from it.

Query Sample

curl -X DELETE -d '{"result_ids":["66625018770158663"]}'  -H "Content-Type: application/json" https://api.polyswarm.network/v3/hunt/historical/results/list -H "Authorization: $API_KEY"

2024 © PolySwarm Pte. Ltd.