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"
Upload template logo
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 template logo
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"
Download template logo
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
URL 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"
Hash Searching
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"
Metadata Searching
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"
IOC Searching
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
andvm_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 aninstance_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
oryara
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"