PolySwarmPolySwarmPolySwarmPolySwarm
Go to PolySwarm
Home

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"
    }
  }
}

2021 © PolySwarm Pte. Ltd.