Engine Protocols and API's
Microengines and Arbiters communicate with the PolySwarm marketplace using Webhooks and callbacks to URLs provided in the webhook body content. The following sections detail the structure of those protocols and APIs.
Webhook Request to Engine
PolySwarm will make an HTTP request to the URI registered in the Engine's profile in the PolySwarm UI. The URI must use HTTPs.
Webhook Headers
All webhooks receive the same set of headers.
| X-POLYSWARM-DELIVERY | Unique Delivery ID for a Webhook |
| X-POLYSWARM-EVENT | Event name |
| X-POLYSWARM-SIGNATURE | Signed HMAC for sender validation |
Bounty
Called by PolySwarm to send a Bounty to the engine.
| Method | POST |
| X-POLYSWARM-EVENT | bounty |
Data constraints
| id | Bounty Identifier |
| artifact_type | Identifies the type of artifact: FILE or URL |
| artifact_uri | FILE: Where to download. URL: website to scan |
| expiration | ISO timestamp when the response is due |
| response_url | Where to send the bounty response |
| rules | Specific behaviors engines must follow for this bounty. For example, every bounty has min_allowed_bid and max_allowed_bid that set limits on the bidding. |
| phase | Is the bounty in Assertion or Arbitration phase |
| sha256 | Sha256 if FILE artifact |
| mimetype | Mimetype if FILE artifact |
| metadata | Addition information about an artifact |
{
"id": "[Big integer]",
"artifact_type": "[string either 'file', or 'url']",
"artifact_uri": "[string minimum length 1/ uri]",
"expiration": "[string minimum length 1/ iso format date]",
"response_url": "[string minimum length 1/ url]",
"rules": "[object]",
"phase": "[string either 'assertion', or 'arbitration']",
"sha256": "[nullable string length 64]",
"mimetype": "[nullable string minimum length 1]",
"metadata": "[nullable object with extra details about the artifact]"
}Data example - All fields will be sent.
{
"id": 1234567890,
"artifact_type": "file",
"artifact_uri": "https://api.polyswarm.network/path/to/download",
"expiration": "1970-01-01T00:00:00+0000",
"response_url": "https://api.polyswarm.network/path/to/respond",
"rules": { "min_allowed_bid": 625000000000, "max_allowed_bid": 1000000000000000000 },
"phase": "assertion",
"sha256": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
"mimetype": "text/plain",
"metadata": { "filesize": 68, "filename": "eicar.com" }
}Success response
| Condition | If the engine has accepted the bounty and started processing/scanning it asynchronously |
| Status | 202 |
Ping
Called by PolySwarm to send a connectivity test the engine's webserver. Ping has no body content.
| Method | POST |
| X-POLYSWARM-EVENT | ping |
Requests from Engine to PolySwarm
Artifact Download
| URL | Bounty's artifact_uri |
| Method | GET |
Success response
| Condition | File is found, and will be downloaded |
| Status | 200 |
Assertion
| URL | Bounty's response_url |
| Method | POST |
| Content-Type | application/json |
Data constraints
| verdict | One of four states: unknown, suspicious, malicious, benign |
| bid | Amount to bid |
| metadata | Key-Value pairs of metadata values |
{
"verdict": "[string one of 'unknown', 'suspicious', 'benign', or 'malicious']",
"bid": "[integer between min and max bid, per the bounty]",
"metadata": "[object, following the polyswarmartifact metadata schema]"
}Data example - All fields must be sent.
{
"verdict": "malicious",
"bid": 1000000000000000000,
"metadata": {
"malware_family": "EICAR-TEST-FILE",
"scanner": {
"version": "1.0.0",
"environment": {
"platform": "x86 64",
"operating_system": "Linux"
}
}
}
}Vote
| URL | Bounty's response_url |
| Method | POST |
| Content-Type | application/json |
Data constraints
| verdict | One of four states: unknown, suspicious, malicious, benign |
| metadata | Key-Value pairs of metadata values |
{
"verdict": "[string one of 'unknown', 'suspicious', 'benign', or 'malicious']",
"metadata": "[object, following the polyswarmartifact metadata schema]"
}Data example - All fields must be sent.
{
"verdict": "malicious",
"metadata": {
"malware_family": "EICAR-TEST-FILE",
"scanner": {
"version": "1.0.0",
"environment": {
"platform": "x86 64",
"operating_system": "Linux"
}
}
}
}Metadata
This metadata object is included in both assertions and votes.
All of these fields are optional, except malware_family.
malware_family should be an empty string if the artifact is not malicious.
Engines built with Python can use the Verdict class in polyswarm-artifact. The Verdict class uses the builder pattern.
Data constraints
Metadata object
| malware_family | Requred string to identiy the malware |
| domains | List of domains associated with the malware |
| ip_addresses | List of ip_addresses associated with the malware |
| stix | List of stix signatures to identify the malware |
| heuristic | Was the assertion/vote generated from a hueristic |
| scanner | Details about the engine itself |
Scanner object
| version | Engine version |
| vendor_version | The version of some existing malware scanner this wraps |
| signatures_version | The version of the signatures used to scan |
| environment | Object of details about the environment, such as os, and platform |
{
"malware_family": "[string minimum length 0]",
"domains": "[list of strings minimum length 0]",
"ip_addresses": "[list of strings minimum length 0]",
"stix": "[list of stix signatures, minimum length 0]",
"heuristic": "[boolean]",
"scanner": "[scanner object]"
}Data example
{
"malware_family": "EICAR-TEST-FILE",
"scanner": {
"version": "1.0.0",
"vendor_version": "2021.2",
"signatures_version": "2021.2.5",
"environment": {
"platform": "x86 64",
"operating_system": "Linux"
}
}
}