Engines

General

The Engines page of PolySwarm UI allows you to view the list of Engines that have been created in a PolySwarm UI Account and have been Verified. For the users who have developed an Engine, this page allows them to add it to the PolySwarm Marketplace.

All Engines

The All Engines tab provides a listing of all verified Engines. For each Engine, it shows the Name and the Tags. The Tags are clickable to filter the content of the page. In the upper right corner, there is a button to edit the Tags filters.

Details

Clicking on the name of an Engine in the All Engines list will update the left area of the page to display the Engine's details. The Engine details view displays the name, description, date it was created, participant type, type(s) of artifacts it can process, and the author’s website.

My Engines

The My Engines tab is only available to logged in users. This is where a user can Create an Engine. Once a user has Created an Engine, their Engines will be listed on this page and can be edited or deleted. Clicking on an Engine's name will display the details in the left area, just like the All Engines page does, but this view also includes the Development Community details.

The Engine Status will be one of the following states:

Status	What does it mean?
`Disabled`	When your Engine is not in operation.
`Development`	When your Engine is in Development Mode.
`Verification`	When your Engine is being Verified by the PolySwarm Support team.
`Verified`	When PolySwarm has completed the Verification process for your Engine.
`Failed`	When an Engine was previously Verified and is no longer responding to bounties, it will be marked as “Failed”.

Creating an Engine

Creating an Engine is how the owner of a PolySwarm UI Account begins the process to connect their Engine to the PolySwarm Marketplace. Click the “Add engine” button to create your first engine. If you have one or more existing Engines, you can click the “+” button to create another one.

The Creation process allows the owner to define the operating parameters of their Engine. The PolySwarm Marketplace uses these parameters to determine which Engines can participate in each bounty.

Note: It is possible to create your engine in your User Account or in one of your Team Accounts. We recommend creating your Engines in a Team Account, because it is easier to manage when you have more than one person in your organization who needs to manage the Engine.

In the Add Engine window, complete the form and click the Save button to create the Engine. The Engine Configuration Options page provides guidance for all fields in the Engine creation/editing form.

Note: Most fields in the Add Engine window are disabled until a Webhook is selected.

Deleting an Engine

To delete an Engine, you must first move it to the Disabled state. When an Engine is Deleted, the PolySwarm Marketplace retains the Engine’s name associated with any bounty assertions or votes that the Engine provided while operating in a production community. Because of this, Engine Names can never be reused.

Development Community

Each Engine has its own Private Development Community to use for testing an Engine in the PolySwarm Marketplace. On the My Engines tab, when you click on the Name of an Engine, the left view will show your Development Community Details.

Name - The name of your Development Community is randomly generated and is unique to your engine.
API Key - The API Key used in the PolySwarm CLI when sending artifacts to your Development Community.
Accepting Bounties - When “Enabled”, your Development Community is active and will accept bounties for your Engine. When “Disabled”, it will not accept bounties. The Development Community will be “Disabled” when the Engine Status is “Disabled” or “Failed” or “Verified”. It will be “Enabled” when the Engine Status is “Development” or “Verification”.

Use the PolySwarm CLI to submit artifacts into your Development Community. You can also perform a hash search on your Development Community to see the full Scan result data for the bounties in your Development Community.

At the bottom of the Development Results table for each Engine are instructions for how to submit artifacts into your Development Community. The instructions are the same for each Engine, but the API key and Development Community Name will differ.

Development Mode

To move an Engine into the “Development” state, select “Enable Development Mode” from the Actions menu. Enabling Development Mode for an Engine allows you to test your Engine in the PolySwarm Marketplace using a Development Community only accessible by your Engine.

Development Results

When you submit bounties into your Development Community, those results are not accessible or searchable by other PolySwarm users. On the My Engines tab, when you click the “Down Arrow” icon in the Actions column for an Engine, it will expand the Development Results table for that Engine.

The Development Results table allows you to track each artifact you submit into your Development Community.

sha256 - The sha256 hash of the artifact you submitted.
Verdict - The Verdict returned by your Engine
Expected Verdict - For each artifact, you should set the value that you expected the verdict to be. This allows you to track which artifacts were evaluated incorrectly by your Engine during testing. In the Actions column, select “Set Expected Verdict” to set this value.
Status - The Status of the Bounty for your artifact. When you submit your artifact, this table will update automatically while the bounty is being processed.
Timestamp - The timestamp for when the Bounty was created.

Disabling

To Disable your Engine, select “Disable” from the Action menu of your Engine. You must Disable your Engine before you can Edit or Delete it.

Editing

To edit your Engine, you must first Disable it. Then select “Edit” from the Actions menu of your Engine. You can update any of the Engine’s configuration settings, except the Engine Name.

Failing

When an Engine is Verified and operating on the production PolySwarm Marketplace, and later stops responding to bounties, it will be marked as “Failed” status. To return the Engine to Production operation, the Engine owner must set the Engine to Disabled, re-test the webhook, and then progress through the Development and Verification process again.

Verification

When your Engine is ready for Production operation in the PolySwarm Marketplace, you must Request Verification. On the My Engines tab, select “Request Verification” in the Actions menu for that Engine. This will set your Engine to the “Verification” status and submit a request to the PolySwarm Support team to process your request.

Before you request Verification you must submit at least 2 bounties to your Engine’s Development Community, one should be for a malicious detection and the other for a benign detection. And you should have set an Expected Verdict that matches the Verdict for those bounties.

When Requesting Verification, make sure that your Engine is operating as if it is ready for production use, so the PolySwarm Support team can submit additional test bounties to verify your Engine’s operation.

Verified

When the PolySwarm Support team completes Verification, your Engine Status will be “Verified”. And your Engine will be joined to all Public Communities. You cannot edit or delete an Engine while it is operating in a production community, so if you need to edit or delete your Engine, you must first move it to the Disabled state. If your Engine stops operating or Fails to respond to a large number of bounties, it will be marked as Failed.