What's new?
\nDiscover the latest feature releases, improvements, and updates with PolySwarm in 2024.
\nSeptember 2024
\n- \n
- ZIP Password File Support - Upload a password protected zip file with a password for scanning or sandboxing via our UI, CLI and API. \n
- Windows 11 Sandbox support - Sandbox in a Windows 11 image via Triage. \n
- HTML Sandboxing improvements - Added additional HTML signatures into Cape for better analysis and detection. \n
- Sandboxing Improvements - Bug fixes around pdf sandboxing in cape for better analysis. \n
July 2024
\n- \n
- QR code Support - Ability to Sandbox and Scan QR Code images with a URL via UI/CLI and API, commonly used in phishing. \n
- Account Plan Information - Retrieve account plan quota and other details via API or CLI. \n
- UI Bug fixes and improvements. \n
June 2024
\n- \n
- Linux Sandboxing - Sandbox files on a Ubuntu image in Triage. \n
- PDF and HTML reports - Create PDF/HTML reports for Scanning and Sandboxing in UI, CLI and API. \n
- Engine fixes and maintenance. \n
April 2024
\n- \n
- HTM/HTML File support - Sandbox HTM/HTML files in Cape and Triage. \n
- URL Sandboxing Support - Cape now supports sandboxing URL's via the API and CLI. \n
- Introduction of new Sandboxing UI fields to improve functionality and clarity. \n
- Improvements of DOC/PDF file support in PolySwarm Sandboxing. \n
February 2024
\n- \n
- Triage Sandbox introduction of URL Sandboxing for the PythonSDK,RestAPI and CLI. \n
- Provided ability to download behavioral and Static json reports for a Sandbox detonation. \n
What's new?
\nDiscover the latest feature releases, improvements, and updates with PolySwarm in 2025.
\nSeptember 2025
\n- \n
- Additional PEID fields added to the UI for scanned artifacts. \n
- Extra fields introduced on the Scanning UI page for improved visibility. \n
August 2025
\n- \n
- Sandbox support expanded to include .eml and .msg file types in CAPE. \n
- \n
Enhanced error reporting for sandboxing:
\n- \n
config.errorsnow highlights unsupported file types. \nartifact.failed_reasonprovides direct sandbox error details (e.g., zero-byte file uploads). \n
\n
June 2025
\n- \n
- Teams can now configure a default value for Sandbox Internet Access in the Advanced tab under Settings. \n
- Sandboxing now includes file type validation. Sandbox sessions will fail if an unsupported file type is uploaded. See UI > Sandboxing for the full list of supported formats. \n
May 2025
\n- \n
- Sandboxing UI redesigned: “My Sandboxing” has been split into My Sandboxing and Team Sandboxing tabs. \n
- New Download Endpoint introduced, allowing users to download sandbox-specific artifacts. Artifacts can also be packaged into a ZIP file for easier handling. \n
- Added the ability to customize the password for downloaded ZIP files via the Settings page. \n
January 2025
\n- \n
- Notification System, This feature provides the ability to receive email notifications when Sandbox sessions are completed. It can be configured through the UI under Settings > Advanced for each user. With this functionality, users can leave the Sandboxing page and focus on other tasks while staying informed. Stay tuned for updates and additional enhancements to this feature in the coming months. \n
What's new?
\nDiscover the latest feature releases, improvements, and updates with PolySwarm in 2026.
\nJanuary 2026
\n- \n
- Notification Webhooks — You can now register notification webhooks to receive automatic push notifications when sandbox tasks complete. This enables automated workflows and real-time integrations with your security tools. Use the CLI command polyswarm notification webhook --help to get started. \n
- LLM-Powered Sample Reports — New downloadable reports providing AI-generated summaries of malware sample analysis. These reports synthesize scan results, sandbox findings, and threat intelligence into actionable summaries for faster analyst triage. \n
- Expire Files in Private Community - Applies to Private Communities only and affects new uploads via the Scan endpoint. After the configured number of days, the binary file is deleted, but the metadata remains available, so the hash can still be searched. \n
Communities
\nPublic Community
\nA Public Community is one that everyone can join and participate in.\nPolySwarm has a default public community that is used by PolySwarm UI and PolySwarm API when a user does not specify the name of a community.
\nPrivate Community
\nA Private Community is an invite-only Community to support specific use cases of our customers (e.g. mutual NDA among participants, GDPR compliance, etc).\nEach Private Community is owned by one Team Account.\nAnd only the Members of that Team Account can access the Private Community.
","rawMarkdownBody":"\n# Communities\n\n### Public Community\nA Public Community is one that everyone can join and participate in.\nPolySwarm has a default public community that is used by PolySwarm UI and PolySwarm API when a user does not specify the name of a community.\n\n### Private Community\nA Private Community is an invite-only Community to support specific use cases of our customers (e.g. mutual NDA among participants, GDPR compliance, etc).\nEach Private Community is owned by one Team Account.\nAnd only the Members of that Team Account can access the Private Community.\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/emerging-threats.md","frontmatter":{"title":"Emerging Threats","excerpt":"The Emerging Threats table provides customers with an actionable curated list of artifacts that PolySwarm has confirmed are emerging threats..."},"html":"Emerging Threats
\nThe Emerging Threats table provides customers with an actionable curated list of artifacts that PolySwarm has confirmed are emerging threats.\nThis single table provides a summary of several groupings of malware; grouped by malware family or world events.
\n- \n
- Clicking the \"View scan results\" button, will show the latest scan results in PolySwarm for that artifact. \n
- \"First Seen in PolySwarm\" indicates that the artifact was submitted into PolySwarm before other platforms. \n
- The PolyScore is PolySwarm's threat scoring algorithm that provides the probability a given file contains malware, in a single authoritative number.\nOn this table, that number is represented by a bar to indicate low, medium, and high. \n
- Each artifact has one or more tags to help the user quickly discern its function. \n
- Users can click the copy icon to grab a copy of the SHA256 hash of the artifact. \n
Why do we sometimes show a low PolyScore on an artifact that we say is malicious?
\nPolyScore weighs convictions from engines differently, based on factors such as malware family name and the engine's track record on similar files.\nFiles with high PolyScores are ready for automated action.\nBut sometimes, engines that detect important emerging threats do not increase the PolyScore very much, even though the file actually is malicious.\nThat is why the process behind PolyScore learns: so we can identify competent engines that see emerging malware first and give them a louder voice against future threats.\nIn the meantime, we still think it's important to show low PolyScores, because it means a file warrants review.\nAnd, if the file is included in the Emerging Threats table, yes, we believe it's malware.
","rawMarkdownBody":"\n# Emerging Threats\n\nThe Emerging Threats table provides customers with an actionable curated list of artifacts that PolySwarm has confirmed are emerging threats.\nThis single table provides a summary of several groupings of malware; grouped by malware family or world events.\n\n* Clicking the \"View scan results\" button, will show the latest scan results in PolySwarm for that artifact.\n* \"First Seen in PolySwarm\" indicates that the artifact was submitted into PolySwarm before other platforms.\n* The PolyScore is PolySwarm's threat scoring algorithm that provides the probability a given file contains malware, in a single authoritative number.\nOn this table, that number is represented by a bar to indicate low, medium, and high.\n* Each artifact has one or more tags to help the user quickly discern its function.\n* Users can click the copy icon to grab a copy of the SHA256 hash of the artifact.\n\n#### Why do we sometimes show a low PolyScore on an artifact that we say is malicious?\nPolyScore weighs convictions from engines differently, based on factors such as malware family name and the engine's track record on similar files.\nFiles with high PolyScores are ready for automated action.\nBut sometimes, engines that detect important emerging threats do not increase the PolyScore very much, even though the file actually is malicious.\nThat is why the process behind PolyScore learns: so we can identify competent engines that see emerging malware first and give them a louder voice against future threats.\nIn the meantime, we still think it's important to show low PolyScores, because it means a file warrants review.\nAnd, if the file is included in the Emerging Threats table, yes, we believe it's malware.\n\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/new/polyswarm-customer-new-23.md","frontmatter":{"title":"PolySwarm Customer New Features","excerpt":"List of new features in polyswarm..."},"html":"What's new?
\nDiscover the latest feature releases, improvements, and updates with PolySwarm in 2023.
\nNovember 2023
\n- \n
- Activity Page in Settings, allows teams to view who has uploaded files to Scan or Sandbox, see here. \n
- Scan History allows accounts to see previous Scans of the same Artifact, allowing you to understand how the sample has changed over time. \n
September 2023
\n- \n
- Private Communities UI introduction, the UI now supports all Private Community features like Scanning, Sandboxing and Hunting. \n
July 2023
\n- \n
- Direct Sandboxing support splits the Sandboxing from the Scan Summary Page, allowing for easy viewing of more metadata and downloading single files. Added ability to Sandbox directly and choose the desired detonation image. \n
May 2023
\n- \n
- Further Sandbox Files available to download, provides the ability to download PCAP & JARM Files from Sandboxing Samples directly. \n
April 2023
\n- \n
- Private Communities, Introduction of Private Communities functionality in the CLI and API, Private Communities allows accounts to upload files in a private space for scanning verdict and sandboxing, and keep the metadata in the teams repository for future reference. \n
March 2023
\n- \n
- Introduction of IOC Search in the UI/CLI and API, This feature provides the ability to search on a hash and review the IP, URL, imphash or MITRE TTP that are related in a single output. Search on a IP, URL, imphash or MITRE TTP to find related hashes. See here for more information. See here. \n
Engines
\n\nGeneral
\nThe 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.
\nAll Engines
\nThe 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.
\nDetails
\nClicking 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.
\nMy Engines
\nThe 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.
\nThe Engine Status will be one of the following states:
\n| Status | \nWhat does it mean? | \n
|---|---|
Disabled | \nWhen your Engine is not in operation. | \n
Development | \nWhen your Engine is in Development Mode. | \n
Verification | \nWhen your Engine is being Verified by the PolySwarm Support team. | \n
Verified | \nWhen PolySwarm has completed the Verification process for your Engine. | \n
Failed | \nWhen an Engine was previously Verified and is no longer responding to bounties, it will be marked as “Failed”. | \n
Creating an Engine
\nCreating 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.
\nThe 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.
\n\n\nNote: 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.
\n
In the Add Engine window, complete the form and click the Save button to create the Engine.\nThe Engine Configuration Options page provides guidance for all fields in the Engine creation/editing form.
\n\n\nNote: Most fields in the Add Engine window are disabled until an engine webhook is selected.
\n
Deleting an Engine
\nTo 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.
\nDevelopment Community
\nEach 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.
\n- \n
- Name - The name of your Development Community is randomly generated and is unique to your engine. \n
- API Key - The API Key used in the PolySwarm CLI when sending artifacts to your Development Community. \n
- 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”. \n
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.
\nAt 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.
\nDevelopment Mode
\nTo 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.
\nDevelopment Results
\nWhen 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.
\nThe Development Results table allows you to track each artifact you submit into your Development Community.
\n- \n
- sha256 - The sha256 hash of the artifact you submitted. \n
- Verdict - The Verdict returned by your Engine \n
- 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. \n
- 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. \n
- Timestamp - The timestamp for when the Bounty was created. \n
Disabling
\nTo Disable your Engine, select “Disable” from the Action menu of your Engine. You must Disable your Engine before you can Edit or Delete it.
\nEditing
\nTo 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.
\nFailing
\nWhen 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 engine webhook, and then progress through the Development and Verification process again.
\nVerification
\nWhen 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.
\nBefore 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.
\nWhen 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.
\nVerified
\nWhen 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.
","rawMarkdownBody":"\n# Engines\n\n\n\n## General {#general}\nThe [Engines](https://polyswarm.network/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.\n\n## All Engines {#all-engines}\nThe 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.\n\n### Details\nClicking 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.\n\n\n## My Engines {#my-engines}\nThe [My Engines](https://polyswarm.network/engines/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.\n\nThe Engine Status will be one of the following states:\n\n| Status| What does it mean?\n| --------| ---------------\n| `Disabled`| When your Engine is not in operation. |\n| `Development`| When your Engine is in Development Mode.|\n| `Verification`| When your Engine is being Verified by the PolySwarm Support team.|\n| `Verified`| When PolySwarm has completed the Verification process for your Engine. |\n| `Failed`| When an Engine was previously Verified and is no longer responding to bounties, it will be marked as “Failed”. |\n\n### Creating an Engine\nCreating 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.\n\nThe 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.\n\n> 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.\n\nIn the Add Engine window, complete the form and click the Save button to create the Engine.\nThe [Engine Configuration Options](/customers/engines-configuration) page provides guidance for all fields in the Engine creation/editing form.\n\n> Note: Most fields in the Add Engine window are disabled until an engine webhook is selected.\n\n### Deleting an Engine\nTo 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.\n\n### Development Community {#development-community}\nEach 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.\n\n* Name - The name of your Development Community is randomly generated and is unique to your engine.\n* API Key - The API Key used in the PolySwarm CLI when sending artifacts to your Development Community.\n* 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”.\n\nUse 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.\n\nAt 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.\n\n### Development Mode {#development-mode}\nTo 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.\n\n### Development Results {#development-results}\nWhen 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.\n\nThe Development Results table allows you to track each artifact you submit into your Development Community.\n\n* sha256 - The sha256 hash of the artifact you submitted.\n* Verdict - The Verdict returned by your Engine\n* 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.\n* 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.\n* Timestamp - The timestamp for when the Bounty was created.\n\n### Disabling\nTo Disable your Engine, select “Disable” from the Action menu of your Engine. You must Disable your Engine before you can Edit or Delete it.\n\n### Editing\nTo 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.\n\n### Failing\nWhen 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 engine webhook, and then progress through the Development and Verification process again.\n\n### Verification {#verification}\nWhen 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.\n\nBefore 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.\n\nWhen 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.\n\n### Verified\nWhen 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.\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/rewards.md","frontmatter":{"title":"Rewards","excerpt":"The Rewards tab in the Account Settings is used to view and manage Rewards"},"html":"NectarNet Rewards
\nGeneral
\nThe Rewards tab, available in a User Account, is where rewards are viewed and redeemed. Users must enable 2-factor authentication (2FA) to access the Rewards tab content.
\nJoin the NectarNet Rewards Program
\nSTEP 1: Get the NectarNet browser extension
\nChrome or Brave
\n- \n
- Navigate to PolySwarm NectarNet in the Chrome Web Store. \n
- Click Add to Chrome \n
![\"Screenshot](\"/images/chromestore.png\")
Firefox
\n- \n
- Navigate to PolySwarm NectarNet in the Firefox Add On store. \n
- Click Add to Firefox \n
![\"Screenshot](\"/images/firefoxstore.png\")
STEP 2: Setup NectarNet Rewards
\n- \n
- Go to https://polyswarm.network/ \n
- Log in or Sign up \n
- Navigate to Settings -> Rewards
\n![\"Screenshot](\"/images/usersettings.png\")
\n![\"Screenshot](\"/images/rewardstab.png\")
\n - Review and accept the Terms and Privacy Policy \n
- Click the \"Join\" button. \n
- Navigate to Settings -> API Keys
\n![\"Screenshot](\"/images/apikeys.png\")
\n - Copy your API key to the clipboard. \n
- Open the Extensions dropdown and click the PolySwarm NectarNet extension.
\n![\"Screenshot](\"/images/extensions.png\")
\n - Paste the API key into the field. \n
You’re all set! Reward amounts are updated daily!
\nNote: Your “community plan” will automatically reset every 30 days, there’s no action you need to take.
\nReward Distribution
\nThe following is an overview of how Rewards Distribution works:
\nWe are giving away $1,337 worth of NCT per day. So, each day PolySwarm builds a pot of NCT to give away. Then, we run an algorithm that analyzes two factors:
\n- \n
- the data provided by all Users during the previous day \n
- how the data provided by Users relates to threat intelligence that our customers want \n
Based on those factors, the algorithm determines which Users will get a portion of that days' Rewards. Finally, it distributes the portions of Rewards to those Users' Rewards Wallet.
\nCurrent Balance
\nThis is the total amount of NCT in the Rewards Wallet.
\nRedeeming
\nOnce a User has some NCT in their Rewards Wallet, they can Redeem those tokens.\nRedeeming is the action to withdraw tokens from your Rewards Wallet and transfer them to your personal ETH/NCT wallet.\nBefore you can Redeem tokens, you must Configure Withdrawals on your Rewards Wallet.\nAlso keep in mind that Redeeming tokens incurs a Transaction Fee, which is displayed when you are doing a redemption.
\nRewards Summary
\nA Rewards program has a collection of categories where Users can earn NCT.\nThe Rewards Summary lists the Categories in which a User has earned NCT and how much NCT a User has earned in each category.\nBy default, the date range is the past 30 days.\nUsers can select a different date range to view the Categories and NCT amounts during specific ranges of time.\nAt the bottom of the page, the Rewards Breakdown tab is a table that shows each Rewards that your account earned during the selected date range.
","rawMarkdownBody":"\n# NectarNet Rewards\n\n## General {#general}\n\nThe Rewards tab, available in a [User Account](https://polyswarm.network/account/wallets), is where rewards are viewed and redeemed. Users must [enable 2-factor authentication (2FA)](/customers/accounts#advanced) to access the Rewards tab content.\n\n## Join the NectarNet Rewards Program\n\n### STEP 1: Get the NectarNet browser extension\n\n#### Chrome or Brave\n\n1. Navigate to [PolySwarm NectarNet](https://chrome.google.com/webstore/detail/polyswarm-in-browser/kkpdgahlbagpciagghmefjdbgnjdahih) in the Chrome Web Store.\n2. Click Add to Chrome\n\n\n\n#### Firefox\n\n1. Navigate to [PolySwarm NectarNet](https://addons.mozilla.org/en-US/firefox/addon/polyswarm-nectarnet/) in the Firefox Add On store.\n2. Click Add to Firefox\n\n\n\n### STEP 2: Setup NectarNet Rewards\n\n1. Go to https://polyswarm.network/\n2. Log in or Sign up\n3. Navigate to Settings -> Rewards\n
\n \n4. Review and accept the Terms and Privacy Policy\n5. Click the \"Join\" button.\n6. Navigate to [Settings -> API Keys](https://docs.polyswarm.io/customers/accounts#api-keys)\n
\n7. Copy your API key to the clipboard.\n8. Open the Extensions dropdown and click the PolySwarm NectarNet extension. \n
\n9. Paste the API key into the field.\n\n## You’re all set! Reward amounts are updated daily! \n\nNote: Your “community plan” will automatically reset every 30 days, there’s no action you need to take.\n\n## Reward Distribution\n\nThe following is an overview of how Rewards Distribution works:\n\nWe are giving away $1,337 worth of NCT per day. So, each day PolySwarm builds a pot of NCT to give away. Then, we run an algorithm that analyzes two factors:\n\n1. the data provided by all Users during the previous day\n2. how the data provided by Users relates to threat intelligence that our customers want\n\nBased on those factors, the algorithm determines which Users will get a portion of that days' Rewards. Finally, it distributes the portions of Rewards to those Users' Rewards Wallet.\n\n## Current Balance\n\nThis is the total amount of NCT in the Rewards Wallet.\n\n## Redeeming\n\nOnce a User has some NCT in their Rewards Wallet, they can Redeem those tokens.\nRedeeming is the action to withdraw tokens from your Rewards Wallet and transfer them to your personal ETH/NCT wallet.\nBefore you can Redeem tokens, you must Configure Withdrawals on your [Rewards Wallet](/customers/wallets#engine-wallets).\nAlso keep in mind that Redeeming tokens incurs a Transaction Fee, which is displayed when you are doing a redemption.\n\n## Rewards Summary\n\nA Rewards program has a collection of categories where Users can earn NCT.\nThe Rewards Summary lists the Categories in which a User has earned NCT and how much NCT a User has earned in each category.\nBy default, the date range is the past 30 days.\nUsers can select a different date range to view the Categories and NCT amounts during specific ranges of time.\nAt the bottom of the page, the Rewards Breakdown tab is a table that shows each Rewards that your account earned during the selected date range.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/engines-configuration.md","frontmatter":{"title":"Engine Configuration Options","excerpt":"When adding or editing an engine, there are many configuration options..."},"html":"Engine Configuration Options
\nWhen adding or editing an engine, there are many configuration options and this page will review these.
\nName
\nGive your Engine a unique name.\nRemember that this name you choose will be visible on the Engines page.
\n\n\nNote: If you use the copyrighted name of a publicly available product, during the Verification process PolySwarm will require you to provide proof that you have rights to use that name.
\n
Engine Webhook
\nIf you haven’t already created an engine webhook in your Account Settings, you can create one here.\nHowever, it is best practice to create the engine webhook in your Account Settings first, so that you can test and verify it before associating it with an Engine.\nThe Rate Limit on the engine webhook determines the maximum number of artifacts your Engine will accept per day.
\nWebsite
\nProvide the URL of a website that has additional details about your Engine or your company.
\nDescription
\nPolySwarm recommends that you provide a description for your Engine.\nThink of it like a brief marketing description of your Engine and its capabilities.\n1-2 sentences using 200 words or less is usually sufficient.
\nMax file size
\nDefine the max size of artifacts that your engine can process.\nThe PolySwarm Marketplace has an internal max file size, but this allows you to define your upper limit below the Marketplace limit.
\nTags
\n- \n
- All Microengines have the “microengine” tag. \n
- All Arbiters have the \"arbiter\" tag. \n
- All Engines that support “file” artifacts will have the “file” tag, and for “url” artifacts will have the “url” tag. \n
Other than those required Tags, you are free to associate other Tags with your Engine.
\nMost Engine owners select tags that are related to the types of files the Engine processes or types of technologies implemented in the Engine.
\nClick the “Down Arrow” to see the list of available Tags.
\nSupported mimetypes
\nThis is where you can define which types of files your Engine can process.\nIf you leave this blank, the Marketplace will assume your Engine can process all files.\nClick the “Down Arrow” to see a list of available Mimetypes.
\nTable of Mimetypes by Category
\nThis table should help you select which Mimetypes are appropriate for your Engine.\nWe've grouped the available mimetypes into commonly referenced Categories.
\n| Category | \nMimetype | \n
|---|---|
| android | \napplication/vnd.android.package-archive application/java-archive application/zip application/octet-stream | \n
| archives | \napplication/java-archive application/x-tar application/zip application/x-compressed-zip application/gzip application/vnd.rar application/x-bzip2 application/x-xz application/octet-stream application/x-7z-compressed application/x-rar-compressed application/x-lha application/x-ace-compressed | \n
| disk image | \napplication/x-cd-image application/x-iso9660-image application/x-daa | \n
| elf | \napplication/x-executable application/x-elf | \n
| flash | \napplication/x-shockwave-flash | \n
| font | \napplication/vnd.ms-fontobject application/vnd.oasis.opendocument.text font/otf font/ttf font/woff font/woff2 font/collection font/sfnt | \n
| image/video | \nimage/tiff video/mp4 image/png image/bmp image/svg+xml image/jpeg image/webp image/gif | \n
| java | \napplication/x-java-applet | \n
| linux | \nelf + application/x-cpio application/x-rpm application/x-dpkg application/octet-stream application/x-sharedlib | \n
| mach-o | \napplication/x-mach-binary application/octet-stream | \n
| office (abiword) | \napplication/x-abiword | \n
| office (etc) | \ntext/calendar | \n
| office (ms) | \napplication/msword application/vnd.ms-excel application/vnd.ms-excel.addin.macroEnabled.12 application/vnd.ms-excel.sheet.binary.macroEnabled.12 application/vnd.ms-excel.sheet.macroEnabled.12 application/vnd.ms-excel.template.macroEnabled.12 application/vnd.ms-powerpoint application/vnd.ms-powerpoint.addin.macroEnabled.12 application/vnd.ms-powerpoint.presentation.macroEnabled.12 application/vnd.ms-powerpoint.slideshow.macroEnabled.12 application/vnd.ms-word.document.macroEnabled.12 application/vnd.ms-word.template.macroEnabled.12 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet application/vnd.openxmlformats-officedocument.spreadsheetml.template application/vnd.openxmlformats-officedocument.wordprocessingml.document application/vnd.openxmlformats-officedocument.wordprocessingml.template application/vnd.ms-office application/x-ms-shortcut application/vnd.ms-powerpoint.template.macroEnabled.12 application/x-mspublisher application/CDFV2-corrupt application/CDFV2-encrypted | \n
| office (open) | \napplication/vnd.oasis.opendocument.chart-template application/vnd.oasis.opendocument.chart application/vnd.oasis.opendocument.database application/vnd.oasis.opendocument.formula application/vnd.oasis.opendocument.graphics-template application/vnd.oasis.opendocument.graphics application/vnd.oasis.opendocument.image-template application/vnd.oasis.opendocument.image application/vnd.oasis.opendocument.presentation-template application/vnd.oasis.opendocument.presentation application/vnd.oasis.opendocument.spreadsheet-template application/vnd.oasis.opendocument.spreadsheet application/vnd.oasis.opendocument.text-master application/vnd.oasis.opendocument.text-template application/vnd.oasis.opendocument.text-web application/vnd.oasis.opendocument.text application/vnd.openofficeorg.extension application/vnd.openxmlformats-officedocument.presentationml.presentation application/vnd.openxmlformats-officedocument.presentationml.slideshow application/vnd.openxmlformats-officedocument.presentationml.template | \n
| osx | \nmach-o + application/octet-stream | \n
application/pdf text/plain application/octet-stream | \n|
| pe | \napplication/x-dosexec application/x-msdownload application/x-msi application/vnd.ms-msi application/vnd.microsoft.portable-executable application/vnd.ms-cab-compressed application/vnd.ms-access application/x-msinstaller | \n
| rtf | \napplication/rtf text/plain text/rtf | \n
| text & script | \napplication/x-httpd-php application/javascript application/json application/x-sh application/x-csh text/html text/plain text/x-python text/xml text/plain application/vnd.coffeescript application/x-vbe application/hta application/PowerShell application/xml text/javascript application/x-perl message/rfc822 text/scriptlet application/vnd.ms-htmlhelp text/vbscript | \n
| windows | \npe + application/octet-stream image/vnd.microsoft.icon text/plain | \n
\n\nNote: The mimetype
\napplication/octet-streamis a generic mimetype for a file that has binary content.\nSometimes the mimetype detection cannot correctly select the exact mimetype of a file and will default toapplication/octet-stream.\nSo, it is generally a good practice to select it if your Engine processes binary files.
Engine type
\nThe only option right now is “Engine”.\nFor Arbiters, PolySwarm will manually convert an Engine to an Arbiter during the on-boarding process.
\nSupported Artifact Types
\nSelect “file” if your Engine can process files. Select “url” if your Engine processes URLs, domains, and IP addresses.
","rawMarkdownBody":"\n# Engine Configuration Options\n\nWhen adding or editing an engine, there are many configuration options and this page will review these.\n\n## Name\nGive your Engine a unique name.\nRemember that this name you choose will be visible on the [Engines](https://polyswarm.network/engines) page.\n\n> **Note:** If you use the copyrighted name of a publicly available product, during the Verification process PolySwarm will require you to provide proof that you have rights to use that name.\n\n## Engine Webhook\nIf you haven’t already created an engine webhook in your Account Settings, you can create one here.\nHowever, it is best practice to create the engine webhook in your Account Settings first, so that you can test and verify it before associating it with an Engine.\nThe Rate Limit on the engine webhook determines the maximum number of artifacts your Engine will accept per day.\n\n## Website\nProvide the URL of a website that has additional details about your Engine or your company.\n\n\n## Description\nPolySwarm recommends that you provide a description for your Engine.\nThink of it like a brief marketing description of your Engine and its capabilities.\n1-2 sentences using 200 words or less is usually sufficient.\n\n\n## Max file size\nDefine the max size of artifacts that your engine can process.\nThe PolySwarm Marketplace has an internal max file size, but this allows you to define your upper limit below the Marketplace limit.\n\n## Tags\n\n* All Microengines have the “microengine” tag.\n* All Arbiters have the \"arbiter\" tag.\n* All Engines that support “file” artifacts will have the “file” tag, and for “url” artifacts will have the “url” tag.\n\nOther than those required Tags, you are free to associate other Tags with your Engine.\n\nMost Engine owners select tags that are related to the types of files the Engine processes or types of technologies implemented in the Engine.\n\nClick the “Down Arrow” to see the list of available Tags.\n\n## Supported mimetypes\nThis is where you can define which types of files your Engine can process.\nIf you leave this blank, the Marketplace will assume your Engine can process all files.\nClick the “Down Arrow” to see a list of available Mimetypes.\n\n### Table of Mimetypes by Category\nThis table should help you select which Mimetypes are appropriate for your Engine.\nWe've grouped the available mimetypes into commonly referenced Categories.\n\n| Category | Mimetype |\n|------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| android | `application/vnd.android.package-archive` `application/java-archive` `application/zip` `application/octet-stream` |\n| archives | `application/java-archive` `application/x-tar` `application/zip` `application/x-compressed-zip` `application/gzip` `application/vnd.rar` `application/x-bzip2` `application/x-xz` `application/octet-stream` `application/x-7z-compressed` `application/x-rar-compressed` `application/x-lha` `application/x-ace-compressed` |\n| disk image | `application/x-cd-image` `application/x-iso9660-image` `application/x-daa` |\n| elf | `application/x-executable` `application/x-elf` |\n| flash | `application/x-shockwave-flash` |\n| font | `application/vnd.ms-fontobject` `application/vnd.oasis.opendocument.text` `font/otf` `font/ttf` `font/woff` `font/woff2` `font/collection` `font/sfnt` |\n| image/video | `image/tiff` `video/mp4` `image/png` `image/bmp` `image/svg+xml` `image/jpeg` `image/webp` `image/gif` |\n| java | `application/x-java-applet` |\n| linux | elf + `application/x-cpio` `application/x-rpm` `application/x-dpkg` `application/octet-stream` `application/x-sharedlib` |\n| mach-o | `application/x-mach-binary` `application/octet-stream` |\n| office (abiword) | `application/x-abiword` |\n| office (etc) | `text/calendar` |\n| office (ms) | `application/msword` `application/vnd.ms-excel` `application/vnd.ms-excel.addin.macroEnabled.12` `application/vnd.ms-excel.sheet.binary.macroEnabled.12` `application/vnd.ms-excel.sheet.macroEnabled.12` `application/vnd.ms-excel.template.macroEnabled.12` `application/vnd.ms-powerpoint` `application/vnd.ms-powerpoint.addin.macroEnabled.12` `application/vnd.ms-powerpoint.presentation.macroEnabled.12` `application/vnd.ms-powerpoint.slideshow.macroEnabled.12` `application/vnd.ms-word.document.macroEnabled.12` `application/vnd.ms-word.template.macroEnabled.12` `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` `application/vnd.openxmlformats-officedocument.spreadsheetml.template` `application/vnd.openxmlformats-officedocument.wordprocessingml.document` `application/vnd.openxmlformats-officedocument.wordprocessingml.template` `application/vnd.ms-office` `application/x-ms-shortcut` `application/vnd.ms-powerpoint.template.macroEnabled.12` `application/x-mspublisher` `application/CDFV2-corrupt` `application/CDFV2-encrypted` |\n| office (open) | `application/vnd.oasis.opendocument.chart-template` `application/vnd.oasis.opendocument.chart` `application/vnd.oasis.opendocument.database` `application/vnd.oasis.opendocument.formula` `application/vnd.oasis.opendocument.graphics-template` `application/vnd.oasis.opendocument.graphics` `application/vnd.oasis.opendocument.image-template` `application/vnd.oasis.opendocument.image` `application/vnd.oasis.opendocument.presentation-template` `application/vnd.oasis.opendocument.presentation` `application/vnd.oasis.opendocument.spreadsheet-template` `application/vnd.oasis.opendocument.spreadsheet` `application/vnd.oasis.opendocument.text-master` `application/vnd.oasis.opendocument.text-template` `application/vnd.oasis.opendocument.text-web` `application/vnd.oasis.opendocument.text` `application/vnd.openofficeorg.extension` `application/vnd.openxmlformats-officedocument.presentationml.presentation` `application/vnd.openxmlformats-officedocument.presentationml.slideshow` `application/vnd.openxmlformats-officedocument.presentationml.template` |\n| osx | mach-o + `application/octet-stream` |\n| pdf | `application/pdf` `text/plain` `application/octet-stream` |\n| pe | `application/x-dosexec` `application/x-msdownload` `application/x-msi ` `application/vnd.ms-msi` `application/vnd.microsoft.portable-executable` `application/vnd.ms-cab-compressed` `application/vnd.ms-access` `application/x-msinstaller` |\n| rtf | `application/rtf` `text/plain` `text/rtf` |\n| text & script | `application/x-httpd-php` `application/javascript` `application/json` `application/x-sh` `application/x-csh` `text/html` `text/plain` `text/x-python` `text/xml` `text/plain` `application/vnd.coffeescript` `application/x-vbe` `application/hta` `application/PowerShell` `application/xml` `text/javascript` `application/x-perl` `message/rfc822` `text/scriptlet` `application/vnd.ms-htmlhelp` `text/vbscript` |\n| windows | pe + `application/octet-stream` `image/vnd.microsoft.icon` `text/plain` |\n\n> Note: The mimetype `application/octet-stream` is a generic mimetype for a file that has binary content.\n> Sometimes the mimetype detection cannot correctly select the exact mimetype of a file and will default to `application/octet-stream`.\n> So, it is generally a good practice to select it if your Engine processes binary files.\n\n\n## Engine type\nThe only option right now is “Engine”.\nFor Arbiters, PolySwarm will manually convert an Engine to an Arbiter during the on-boarding process.\n\n## Supported Artifact Types\nSelect “file” if your Engine can process files. Select “url” if your Engine processes URLs, domains, and IP addresses.\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/home.md","frontmatter":{"title":"PolySwarm UI","excerpt":"All actions in the PolySwarm UI operate in the Account Context of the active User Account or Team Account..."},"html":"PolySwarm UI
\nPolySwarm offers a User Interface (UI) to interact with PolySwarm features.
\nSome functionality of the PolySwarm UI is available without being logged in, but that functionality is limited.\nTo unlock additional functionality create a free account and sign in, then if you require additional quota upgrade your plan.
\n\nGetting Started
\nLogin/Sign Up
\n\n\nNote: If you have purchased a Premium plan, you will receive an email with a link to sign up.
\n
Sign Up
\n- \n
- Navigate to the PolySwarm UI via here \n
- Click on the “Log In/Sign up” button \n
- The authentication window will appear with two tabs, Click the “Sign Up” tab to Sign Up for a new User Account \n
- You will be provided three means of Signing Up: \n
\n\n\n
\n- Sign Up with GitHub - Use your GitHub account to log into PolySwarm UI.
\n- Sign Up with Google - Use your Google account to log into PolySwarm UI.
\n- Sign Up with Email address and password - Use an email address and password to log into PolySwarm UI. When using this method for sign up, you also need to provide your name.
\n
Once you complete the Sign Up, we will send you a verification email.\nYou need to click on the link in that verification email to complete your User Account creation.
\nLog In
\nClicking on the \"Login\" tab in the authentication Page provides a means of logging in.
\n- \n
- Navigate to the PolySwarm UI via here \n
- Click on the “Log In/Sign up” button \n
- The authentication window will appear with two tabs, Click the “Log In” tab to Log In using the same method used to create the accounts. \n
Accounts (Team/User)
\nPolySwarm offers two types of accounts:
\n- \n
- User Account - Individual User Accounts \n
- Team Account - User Accounts can be part of a Team Account \n
All new User Accounts will have the free \"Community\" subscription plan assigned, this allows access to the basic functionality of PolySwarm. Users will have the option of purchasing a Paid Premium Subscription, if a Paid Premium Subscription has already been purchased it will have been applied to the Team Account the User Account is part of.
\nOnce you have created a \"User Account\" (which all Users must do) you can be added to a \"Team Account\".
\n\"Team Accounts\" will allow individual \"User Accounts\" shared access to the Premium Subscription if purchased and shared Quotas of this Subscription. There are additional Settings options like Member Account Management and Integrations that standard \"User Accounts\" cannot access. We will cover how to access these in the \"Settings\" Pages here.
\nContext Menu
\nOnce logged in, the upper right corner changes from displaying a “Log In/Sign Up” button to displaying the username with an avatar icon, or if you have switched teams to the Name of the Team. Beside this is the Settings Icon.
\n![\"Sandbox](\"/images/ui/ui_started_context.gif\")
All actions in the PolySwarm UI operate in the Account Context of the active User Account or Team Account.
\nTo enable users to select which account should be used for their actions, users can Switch Accounts to change the active Context between their User Account and one or more Team Accounts. The Context that is currently being used is referred to as the Active Context.
\nThe Active Context determines several things:
\n- \n
- The features available in PolySwarm UI will vary depending on the Subscription Plan associated with the Active Context. \n
- All PolySwarm UI usage will subtract from the usage allotment in the Subscription Plan associated with the Active Context. \n
- The Account Settings page displays the Settings for the User Account or Team Account associated with the Active Context. \n
Clicking on the Avatar icon will open the Context Menu.\nIn the Context Menu are the following options:
\n| Menu Option | \nWhat is it for? | \n
|---|---|
| Switch Accounts | \nSwitch the currently active Context to that of the user’s User Account or one of the user’s Team Accounts. | \n
| Create Team | \nCreate a new Team Account. All users can create teams, but Premium plans are assigned to Teams by PolySwarm. | \n
| Logout | \nLog out of PolySwarm UI. | \n
Clicking on the Settings icon will open the Context Menu.\nIn the Context Menu are the following options:
\n| Menu Option | \nWhat is it for? | \n
|---|---|
| Settings | \nClick the Settings option to go to the Account Settings page for the account associated with the currently Active Context | \n
| Dark Theme Off/On | \nDisable or enable the dark theme. It is disabled by default. | \n
| Help | \nGo to the PolySwarm documentation website. | \n
\n\nThe Context Menu that shows the Team Name can be used to switch to a Private Community. If your organization is part of a Private Community, the Team name will be appended with a
\npublicandprivatename to highlight the two Communities.
\n\nWhen in Private mode for the Team a Black Hat Icon is shown in the Context Menu area to highlight the mode you are in, this is explained further in the Private Community section here.
\n
Emerging Threats
\nThe Emerging Threats table on the Home page provides customers with an actionable curated list of artifacts that PolySwarm has confirmed are emerging threats.\nThis single table provides a summary of several groupings of malware; grouped by malware family or world events.
\n![\"Emerging](\"/images/ui/ui_emerg.png\")
\n
\n\n\n\n
\n- Clicking the \"View scan results\" button, will show the latest scan results in PolySwarm for that artifact.
\n- \"First Seen in PolySwarm\" indicates that the artifact was submitted into PolySwarm before other platforms.
\n- \n
\nThe PolyScore is PolySwarm's threat scoring algorithm that provides the probability a given file contains malware, in a single authoritative number.
\n\n
\n- On this table, that number is represented by a bar to indicate low, medium, and high.
\n- Each artifact has one or more tags to help the user quickly discern its function.
\n- Users can click the copy icon to grab a copy of the SHA256 hash of the artifact.
\n
Why do we sometimes show a low PolyScore on an artifact that we say is malicious?
\nPolyScore weighs convictions from engines differently, based on factors such as malware family name and the engine's track record on similar files.\nFiles with high PolyScores are ready for automated action.\nBut sometimes, engines that detect important emerging threats do not increase the PolyScore very much, even though the file actually is malicious.\nThat is why the process behind PolyScore learns: so we can identify competent engines that see emerging malware first and give them a louder voice against future threats.\nIn the meantime, we still think it's important to show low PolyScores, because it means a file warrants review.\nAnd, if the file is included in the Emerging Threats table, yes, we believe it's malware.
\nPrivate Communities
\nPolySwarm offers an additional service called “Private Communities” that restricts artifacts submitted into a Private Community and any metadata from the artifact to be accessible only by members of the Private Community and not to the wider public PolySwarm Community.
\nPrivate Communities is a feature that covers all functionality in the UI, the context depends on what Team you are currently using. To access and move between the Public and Private Modes of a Team use the Context Menu, where you'll see your Team name with Public and Private appended, like this: Team Name - Private.
![\"Private](\"/images/ui/ui_private_team_name.png\")
Once using the Private mode of a Team it is clear that you are in this mode by a number of visual cues onscreen like:
\n- \n
- Background of the UI Changes to once of the Private Themes. \n
- Private Icon appears beside the Settings Icon to indicate you are in Private Mode. \n
![\"Private](\"/images/ui/ui_private_icon.png\"){kind=icon}
When in the Private Community the account features act in the following ways:
\n| Feature | \nFunctionality | \n
|---|---|
| File Upload Scan | \nFile uploaded will be kept private, scanned by chosen engines for that private community, metadata private. | \n
| URL Scan | \nURL will be kept private, scanned by chosen engines for that private community, metadata private. | \n
| Hash Search | \nSearch for a Hash in your Private Community only. | \n
| Metadata Search | \nSearch for a Metadata in your Private Community only. | \n
| IOC Search | \nSearch for a IOC's in your Private Community only. | \n
| Sandboxing | \nSubmit a file for Sandboxing in your Private Community, kept private with metadata. | \n
| Hunt - Rules | \nThe same Rulesets are visible in both Public and Private modes for a team. | \n
| Live Hunt | \nLive Hunt matches on samples in your Private and the Public community. | \n
| Historical Hunt | \nHistorical Hunt matches on samples in your Private and the Public community. | \n
\n","rawMarkdownBody":"\n# PolySwarm UI\n\nPolySwarm offers a User Interface (UI) to interact with PolySwarm features.\n\nSome functionality of the PolySwarm UI is available without being logged in, but that functionality is limited.\nTo unlock additional functionality create a free account and sign in, then if you require additional quota upgrade your plan.\n\n\n\n## Getting Started\n\n### Login/Sign Up {#log-in-sign-up}\n\n> **Note:** If you have purchased a Premium plan, you will receive an email with a link to sign up.\n\n##### Sign Up {#started-signup-account}\n\n1. Navigate to the PolySwarm UI via [here](https://polyswarm.network/)\n2. Click on the “_Log In/Sign up_” button\n3. The authentication window will appear with **two tabs**, Click the “_Sign Up_” tab to Sign Up for a new User Account\n4. You will be provided three means of Signing Up:\n\n> - **Sign Up with GitHub** - Use your GitHub account to log into PolySwarm UI.\n> - **Sign Up with Google** - Use your Google account to log into PolySwarm UI.\n> - **Sign Up with Email** address and password - Use an email address and password to log into PolySwarm UI. When using this method for sign up, you also need to provide your name.\n\nOnce you complete the Sign Up, we will send you a verification email.\nYou need to click on the link in that verification email to complete your User Account creation.\n\n##### Log In {#started-login}\n\nClicking on the \"Login\" tab in the authentication Page provides a means of logging in.\n\n1. Navigate to the PolySwarm UI via [here](https://polyswarm.network/)\n2. Click on the “_Log In/Sign up_” button\n3. The authentication window will appear with **two tabs**, Click the “_Log In_” tab to Log In using the same method used to create the accounts.\n\n### Accounts (Team/User) {#started-accounts}\n\nPolySwarm offers two types of accounts:\n\n- **User Account** - _Individual User Accounts_\n- **Team Account** - _User Accounts can be part of a Team Account_\n\nAll new User Accounts will have the free \"Community\" subscription plan assigned, this allows access to the basic functionality of PolySwarm. Users will have the option of purchasing a Paid Premium Subscription, if a Paid Premium Subscription has already been purchased it will have been applied to the Team Account the User Account is part of.\n\nOnce you have created a _\"User Account\"_ (which all Users must do) you can be added to a _\"Team Account\"_.\n\n_\"Team Accounts\"_ will allow individual _\"User Accounts\"_ shared access to the Premium Subscription if purchased and shared Quotas of this Subscription. There are additional Settings options like Member Account Management and Integrations that standard _\"User Accounts\"_ cannot access. We will cover how to access these in the \"Settings\" Pages [here](/customers/settings/).\n\n### Context Menu {#context-menu}\n\nOnce logged in, the upper right corner changes from displaying a “Log In/Sign Up” button to displaying the username with an avatar icon, or if you have switched teams to the Name of the Team. Beside this is the Settings Icon.\n\nWant to change your Private Community Theme? Navigate here to see how to do this.
\n
\n\nAll actions in the PolySwarm UI operate in the Account Context of the active User Account or Team Account.\n\nTo enable users to select which account should be used for their actions, users can Switch Accounts to change the active Context between their User Account and one or more Team Accounts. The Context that is currently being used is referred to as the Active Context.\n\nThe Active Context determines several things:\n\n- The features available in PolySwarm UI will vary depending on the Subscription Plan associated with the Active Context.\n- All PolySwarm UI usage will subtract from the usage allotment in the Subscription Plan associated with the Active Context.\n- The Account Settings page displays the Settings for the User Account or Team Account associated with the Active Context.\n\nClicking on the **Avatar icon** will open the Context Menu.\nIn the Context Menu are the following options:\n\n| Menu Option | What is it for? |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| Switch Accounts | Switch the currently active Context to that of the user’s User Account or one of the user’s Team Accounts. |\n| Create Team | Create a new Team Account. All users can create teams, but Premium plans are assigned to Teams by PolySwarm. |\n| Logout | Log out of PolySwarm UI. |\n\nClicking on the **Settings icon** will open the Context Menu.\nIn the Context Menu are the following options:\n\n| Menu Option | What is it for? |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| Settings | Click the Settings option to go to the Account Settings page for the account associated with the currently Active Context | |\n| Dark Theme Off/On | Disable or enable the dark theme. It is disabled by default. |\n| Help | Go to the PolySwarm documentation website. |\n\n> The Context Menu that shows the Team Name can be used to switch to a Private Community. If your organization is part of a Private Community, the Team name will be appended with a `public` and `private` name to highlight the two Communities.\n\n> When in Private mode for the Team a *Black Hat* Icon is shown in the Context Menu area to highlight the mode you are in, this is explained further in the Private Community section [here](#private-community).\n\n### Emerging Threats {#emerging-threats}\n\nThe Emerging Threats table on the **Home page** provides customers with an actionable curated list of artifacts that PolySwarm has confirmed are emerging threats.\nThis single table provides a summary of several groupings of malware; grouped by malware family or world events.\n\n\n\n\n\n> - Clicking the **\"View scan results\"** button, will show the latest scan results in PolySwarm for that artifact.\n> - **\"First Seen in PolySwarm\"** indicates that the artifact was submitted into PolySwarm before other platforms.\n> - The **PolyScore** is PolySwarm's threat scoring algorithm that provides the probability a given file contains malware, in a single authoritative number.\n> - On this table, that number is represented by a bar to indicate low, medium, and high.\n> - Each artifact has one or more **tags** to help the user quickly discern its function.\n> - Users can click the **copy** icon to grab a copy of the SHA256 hash of the artifact.\n\n
\n\n##### Why do we sometimes show a low PolyScore on an artifact that we say is malicious?\n\nPolyScore weighs convictions from engines differently, based on factors such as malware family name and the engine's track record on similar files.\nFiles with high PolyScores are ready for automated action.\nBut sometimes, engines that detect important emerging threats do not increase the PolyScore very much, even though the file actually is malicious.\nThat is why the process behind PolyScore learns: so we can identify competent engines that see emerging malware first and give them a louder voice against future threats.\nIn the meantime, we still think it's important to show low PolyScores, because it means a file warrants review.\nAnd, if the file is included in the Emerging Threats table, yes, we believe it's malware.\n\n### Private Communities {#private-community}\n\nPolySwarm offers an additional service called “Private Communities” that restricts artifacts submitted into a Private Community and any metadata from the artifact to be accessible only by members of the Private Community and not to the wider public PolySwarm Community.\n\nPrivate Communities is a feature that covers all functionality in the UI, the context depends on what Team you are currently using. To access and move between the Public and Private Modes of a Team use the Context Menu, where you'll see your Team name with `Public` and `Private` appended, like this: `Team Name - Private`.\n\n\n\nOnce using the Private mode of a Team it is clear that you are in this mode by a number of visual cues onscreen like:\n- Background of the UI Changes to once of the Private Themes.\n- Private Icon appears beside the Settings Icon to indicate you are in Private Mode.\n\n\n\nWhen in the Private Community the account features act in the following ways:\n\n| Feature | Functionality |\n| ----------------- | ----------- |\n| File Upload Scan | File uploaded will be kept private, scanned by chosen engines for that private community, metadata private. |\n| URL Scan | URL will be kept private, scanned by chosen engines for that private community, metadata private. |\n| Hash Search| Search for a Hash in your Private Community only. |\n| Metadata Search |Search for a Metadata in your Private Community only. |\n| IOC Search|Search for a IOC's in your Private Community only. |\n| Sandboxing| Submit a file for Sandboxing in your Private Community, kept private with metadata. |\n| Hunt - Rules | The same Rulesets are visible in both Public and Private modes for a team. |\n| Live Hunt | Live Hunt matches on samples in your Private and the Public community. |\n| Historical Hunt| Historical Hunt matches on samples in your Private and the Public community.|\n\n> Want to change your Private Community Theme? Navigate [here](/customers/settings#advanced-theme) to see how to do this.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/sandbox.md","frontmatter":{"title":"Sandbox","excerpt":"On the Sandbox page in the PolySwarm UI, we support submitting artifacts directly to our Sandboxes..."},"html":"Sandbox
\nOn the Sandbox page in the PolySwarm UI, we support Sandboxing Files directly, and managing current submissions.
\n\n\n\nTo use Sandboxing functionality, you must have this paid feature enabled on your Plan, you can check your Usage page to see if you have this.
\n
Submit to Sandbox
\nThe Submit to Sandbox button offers the ability to submit new Artifacts or Artifacts already in PolySwarm to be detonated on the Sandboxes by a chosen Sandbox provider. Sandbox Analysis will take around 2-5 minutes before the results can be accessed.
\n\n\nThis is a direct Sandbox submission, meaning the artifact will go directly to the sandbox and not for Scanning by the AV Engines, if you want to Scan a file then you need to upload the file via the Scanning upload. Alternatively, once the file has been Sandboxed you will have the ability to \"Rescan\" the artifact by the AV Engines.
\n
\n\nIf you are using the Public Community, the default is that Sandboxed Artifacts will be detonated on the Sandbox with Internet Outreach. If you are using the Private Community, the default is that Sandboxed Artifacts will be detonated on the Sandbox without Internet Outreach.
\n
![\"Sandbox](\"/images/ui/ui_sandbox_submit.gif\")
The Submit to Sandbox button presents a popup with the following options:
- \n
- File, Select a local artifact to be uploaded to PolySwarm for Sandboxing \n
- Hash, Search for a artifact already in PolySwarm by hash value \n
- \n
URL, Paste in the URL that you wish to Sandbox
\n- \n
- Choose which Sandbox Provider and detonation VM image to use, currently PolySwarm offers
CapeandTriageproviders with different detonation images for each. \n
\n - Choose which Sandbox Provider and detonation VM image to use, currently PolySwarm offers
- QR Code, Select a local qr code image to be uploaded to PolySwarm for Sandboxing \n
Provide the artifact or hash, select the Sandbox provider, and select the detonation VM, then click the Submit button to schedule the Sandboxing detonation task. Once submitted, you will return to the My Sandbox page where you can monitor the status of the task.
Sandboxes have multiple returned statuses, these are listed below.
\n| Status | \nWhat is it for? | \n
|---|---|
Success | \nFinished processing correctly | \n
Started | \nSandbox session has started. | \n
Collecting Data | \nSandbox session has been successful and data is being collected. | \n
Failed | \nSandbox session has failed, this can be due to many reasons. | \n
Pending | \nSandbox session is queued up and ready to start. | \n
Delayed | \nSandbox session has been delayed and will start soon. | \n
Failed with Quota Reimbursement | \nFinished processing but failed, quota will be reimbursed. | \n
Timed out with Quota Reimbursement | \nDelayed in the queue for too long, got timed out and then reimbursement. | \n
Supported File Types
\nThe PolySwarm Sandboxes support many file types, these are listed below.
\n| Type | \nExtensions | \nSandbox Provider | \n
|---|---|---|
| Executable | \n.dll | \nTriage, Cape | \n
| Executable | \n.upx | \nCape | \n
| Executable | \n.exe | \nTriage, Cape | \n
| Executable | \n.msi | \nTriage | \n
| Document | \n.chm | \nTriage, Cape | \n
| Document | \n.hta | \nTriage, Cape | \n
| Document | \n.iqy | \nTriage | \n
| Document | \n.doc | \nCape | \n
| Document | \n.docx | \nCape | \n
| Document | \n.xls | \nCape | \n
| Document | \n.xlsx | \nCape | \n
| Document | \n.ppt | \nCape | \n
| Document | \n.pptx | \nCape | \n
| Document | \n.pub | \nCape | \n
| Document | \n.pub2016 | \nCape | \n
| Document | \n.one | \nCape | \n
| Document | \n.mht | \nCape | \n
| Document | \n.hwp | \nCape | \n
| Document | \n.ich | \nCape | \n
| Document | \n.inp | \nCape | \n
| Document | \n.pdf | \nTriage | \n
| Document | \n.rtf | \nTriage | \n
| Document | \n.slk | \nTriage | \n
| Document | \n.swf | \nTriage | \n
| Document | \n.html | \nTriage, Cape | \n
| Scripting | \n.bat | \nTriage, Cape | \n
| Scripting | \n.ps1 | \nTriage, Cape | \n
| Scripting | \n.js | \nTriage, Cape | \n
| Scripting | \n.jse | \nTriage, Cape | \n
| Scripting | \n.vbe | \nTriage, Cape | \n
| Scripting | \n.pl | \nTriage | \n
| Scripting | \n.py | \nCape | \n
| Scripting | \n.vbs | \nTriage, Cape | \n
| Scripting | \n.wsf | \nTriage, Cape | \n
| Android | \n.apk | \nTriage | \n
| Android | \n.dex | \nTriage | \n
| Other | \n.jar | \nTriage | \n
| Other | \n.lnk | \nTriage, Cape | \n
| Other | \n.url | \nTriage | \n
| Other | \n.jnlp | \nTriage | \n
| Other | \n.reg | \nCape | \n
| Other | \n.xslt | \nCape | \n
| Other | \n.xps | \nCape | \n
32MB is the default \"max\" file submission size, this is a per-account setting, so it is possible for some users/teams to have a higher limit, if you wish to increase this limit please contact customersuccess@polyswarm.io
\nMy Sandboxing
\nThe My Sandbox tab shows you Artifacts that only you have Sandboxed, and the status of these submissions.
\n![\"My](\"/images/ui/ui_sandbox_my.png\")
The table of submissions displays the following information:
\n| Column | \nWhat is it for? | \n
|---|---|
| Sandboxed On | \nDate and Time that the Artifact was Sandboxed on. | \n
| Target | \nFile name of file uploaded, or hash of the file is resandboxed. | \n
| Type | \nType of item sandboxed, i.e. file, url. | \n
| SHA-256 | \nThe sha256 of the Artifact that has been Sandboxed. | \n
| Sandbox Provider | \nName of the sandbox provider used. | \n
| Mal Score | \nIndependent Score provided by the Sandbox, between 0-10. | \n
| Status | \nThe status of the Sandbox submission is color coded. The statuses can be: Success, Pending, Collecting Data, Started, Delayed, Failed Reimbursed, Timeout Reimbursed or Failed | \n
| Actions | \nSingle Action button will open the Sandbox Results Summary page for that Artifact once the Status has changed to Success. | \n
Filtering
\nThe Filter button at the top right of My Sandbox page provides the ability to Filter the results being seen. The following filter options are available:
![\"My](\"/images/ui/ui_my_sandbox_filter.gif\")
- \n
- Status - Status of the Sandbox submission and can be:
Success,Pending,Collecting Data,Started,Delayed,Failed Reimbursed,Timeout ReimbursedorFailed\n - Sandbox Provider - Name of the Sandbox provider. \n
- SHA256 - Specific sha256 value of the Sandboxing submission. \n
- Date Range - Start and End Date for the Sandboxing submission. \n
\n\nAt the bottom of the My Sandbox page you can navigate to the next page if further results exist.
\n
Team Sandboxing
\nThe Team Sandbox tab shows you Artifacts that you and your team members you have Sandboxed, and the status of these submissions.
\n![\"Team](\"/images/ui/ui_sandbox_team.png\")
The table of submissions displays the following information:
\n| Column | \nWhat is it for? | \n
|---|---|
| Sandboxed On | \nDate and Time that the Artifact was Sandboxed on. | \n
| Target | \nFile name of file uploaded, or hash of the file is resandboxed. | \n
| Type | \nType of item sandboxed, i.e. file, url. | \n
| SHA-256 | \nThe sha256 of the Artifact that has been Sandboxed. | \n
| Sandbox Provider | \nName of the sandbox provider used. | \n
| Mal Score | \nIndependent Score provided by the Sandbox, between 0-10. | \n
| Status | \nThe status of the Sandbox submission is color coded. The statuses can be: Success, Pending, Collecting Data, Started, Delayed, Failed Reimbursed, Timeout Reimbursed or Failed | \n
| Actions | \nSingle Action button will open the Sandbox Results Summary page for that Artifact once the Status has changed to Success. | \n
Filtering
\nThe Filter button at the top right of Team Sandbox page provides the ability to Filter the results being seen. The following filter options are available:
- \n
- Status - Status of the Sandbox submission and can be:
Success,Pending,Collecting Data,Started,Delayed,Failed Reimbursed,Timeout ReimbursedorFailed\n - Sandbox Provider - Name of the Sandbox provider. \n
- SHA256 - Specific sha256 value of the Sandboxing submission. \n
- Date Range - Start and End Date for the Sandboxing submission. \n
\n\nAt the bottom of the Team Sandbox page you can navigate to the next page if further results exist.
\n
Sandbox History
\nThe Sandbox History tab allows you to search by sha256 hash to get a list of every time that artifact was Sandboxed, by any user.
\n![\"All](\"/images/ui/ui_sandbox_all.png\")
Once you have searched for a Hash value, the table of submissions provides the following information:
\n| Column | \nWhat is it for? | \n
|---|---|
| Sandboxed On | \nDate and Time that the Artifact was Sandboxed on. | \n
| Target | \nFile name of file uploaded, or hash of the file is resandboxed. | \n
| Type | \nType of item sandboxed, i.e. file, url. | \n
| Sandbox Provider | \nName of the sandbox provider used. | \n
| Status | \nThe status of the Sandbox submission is color coded. The statuses can be: Success, Pending, Collecting Data, Started, Delayed, Failed Reimbursed, Timeout Reimbursed or Failed | \n
| Actions | \nSingle Action button will open the Sandbox Results Summary page for that Artifact once the Status has changed to Success. | \n
Filtering
\nThe Filter button at the top right of All Sandboxing page provides the ability to Filter the results being seen. The following filter options are available:
- \n
- Status - Status of the Sandbox submission and can be:
Success,Pending,Collecting Data,Started,Delayed,Failed Reimbursed,Timeout ReimbursedorFailed\n - Sandbox Provider - Name of the Sandbox provider. \n
- Date Range - Start and End Date for the Sandboxing submission. \n
\n\nAt the bottom of the My Sandbox page you can navigate to the next page if further results exist.
\n
Sandbox Results Summary
\nThis Sandbox Results Summary page provides the view of the latest Sandboxing Results for the Artifact for Cape and Triage.
\nThe page can be accessed from the Action button on the My Sandbox and All Sandboxing pages as well as the Latest Sandbox Results button on the Scan Summary Page for the Artifact.
To view the latest Scan results page for this Artifact you can use the Latest Scan Results button in the top right, then use the Latest Sandbox Results button to navigate back to the Sandboxing detonation results.
![\"Sandbox](\"/images/ui/ui_sandbox_summary_action.gif\")
Summary Pane
\nThe left Summary pane provides access to either the latest Cape or Triage Sandbox detonation, clicking on either will change the data in the main page body. This section lists the Sandbox ID, sha256, file or url, sandbox score and verdict and the Malware Family.
\n![\"Sandbox](\"/images/ui/ui_sandbox_summary_pane.png\")
Below the Summary Pane is the Action Pane with Several buttons:
\n![\"Sandbox](\"/images/ui/ui_sandbox_action_pane.png\")
| Button | \nWhat is it for? | \n
|---|---|
| Re-Sandbox | \nRe-Submit the Artifact to be Sandboxed. | \n
| Share | \nShare a link to these sandbox results page on social media. | \n
| Pivot | \nEnable/Disable the pivoting feature. | \n
| History | \nSee all Sandboxing history, brings you to the All Sandboxing page. | \n
| Generate Report | \nGenerates either a PDF or HTML report on demand, you will be able to choose sections to include. | \n
Sandbox Tabs
\nThe Sandbox Results Summary page has tabs that contain the information from the Sandboxing. This is only a small sample of the data available, to see the fill content download the Full (RAW) JSON for the Sandbox Detonation.
\n![\"Sandbox](\"/images/ui/ui_sandbox_tabs.png\")
Each Tab has shortcut boxes present, these will be greyed out if the metadata does not exist, click on these to quickly jump to the subsection in the relevant tab.
\n![\"Sandbox](\"/images/ui/ui_sandbox_shortcut_icon.png\"){kind=icon}
Extracted Config
\nThis tab contains fields relating to Malware config, Processes and Encryption Keys. Items like Campaign information, Install paths, Access Types and Encryption Key values may be present if the Sandbox has this information. This section can include details from parsers on the sandbox like the CobaltStrike parser.
![\"Sandbox](\"/images/ui/ui_sandbox_extracted_config.png\")
Dropped Files
\nThis tab contains information related to the Dropped Files from the Malware detonation. This tab will display information like File Name, Size, Type and multiple hash values of each dropped file.
\n![\"Settings](\"/images/ui/ui_sandbox_dropped.png\")
\n\nNote if you want the dropped file to be detonated in the Sandboxes, perform a Hash Search to lookup that file. On the Hash Search listing, view the Scan results for that file. On that page, you can select the \"Sandbox\" icon in the Actions Pane to submit it for Sandboxing.
\n
Network Tab
\nThis tab contains information on IPs, SMTP, Domains and JARM details relating to the Sandboxed Artifact. If no data is present then there is no network information available from the Sandbox for this detonation.
\n![\"Settings](\"/images/ui/ui_sandbox_network_tab.png\")
HTTP Transaction Tab
\nThis tab contains information HTTP Transactions, this view is only available for Triage Sandboxing sessions.
\n![\"Settings](\"/images/ui/ui_sandbox_http.png\")
Analysis Tab
\nThis tab contains information on MITRE TTPs used, OS Autorun, Signatures that have been triggered on the Sandbox and Processes. If no data is present then there is no information available for Analysis from the Sandbox for this detonation.
\n![\"Settings](\"/images/ui/ui_sandbox_analysis.png\")
JSON Tab
\nThis tab provides access to the JSON object in relation to the Sandbox detonation, the search field can be used to find specific values and keys. The JSON can be downloaded from this page to be stored locally.
\n\n\nThis JSON is the Summary JSON file for the Sandboxing, to download the Full JSON see the
\nrawreport in the download tab.
Download Results Tab
\nThis tab allows you to download the Sandbox artifacts. These files can be the JARM file, PCAP Files, full JSON Reports and all dropped artifacts. The dropped files will always be downloaded as an encrypted zip file to prevent trigger your local AV engine.
\nEach of these files can be downloaded as a single zip by using the zip tick box at the bottom of the page.
\n\nThe
\nrawjson is the full report created by the Sandbox, while the regular report is the summarized version used to populate the JSON tab.
![\"Settings](\"/images/ui/ui_sandbox_download.png\")
Video & Screenshot Tab
\nThis tab allows you to view the Triage Video OR Cape Screenshots that have been captured from the detonation.
","rawMarkdownBody":"\n# Sandbox\n\nOn the [Sandbox](https://polyswarm.network/sandbox) page in the PolySwarm UI, we support Sandboxing Files directly, and managing current submissions.\n\n\n\n> To use Sandboxing functionality, you must have this paid feature enabled on your Plan, you can check your Usage page to see if you have this.\n\n## Submit to Sandbox {#submit-sandbox}\n\nThe *Submit to Sandbox* button offers the ability to submit new Artifacts or Artifacts already in PolySwarm to be detonated on the Sandboxes by a chosen Sandbox provider. Sandbox Analysis will take around 2-5 minutes before the results can be accessed.\n\n> This is a direct Sandbox submission, meaning the artifact will go directly to the sandbox and **not** for Scanning by the AV Engines, if you want to Scan a file then you need to upload the file via the Scanning upload. Alternatively, once the file has been Sandboxed you will have the ability to \"Rescan\" the artifact by the AV Engines.\n\n> If you are using the **Public** Community, the default is that Sandboxed Artifacts will be detonated on the Sandbox *with* Internet Outreach. If you are using the **Private** Community, the default is that Sandboxed Artifacts will be detonated on the Sandbox *without* Internet Outreach.\n\n\n\nThe `Submit to Sandbox` button presents a popup with the following options:\n\n* File, Select a local artifact to be uploaded to PolySwarm for Sandboxing\n* Hash, Search for a artifact already in PolySwarm by hash value\n* URL, Paste in the URL that you wish to Sandbox\n * Choose which **Sandbox Provider and detonation VM image** to use, currently PolySwarm offers `Cape` and `Triage` providers with different detonation images for each.\n* QR Code, Select a local qr code image to be uploaded to PolySwarm for Sandboxing\n\nProvide the artifact or hash, select the Sandbox provider, and select the detonation VM, then click the `Submit` button to schedule the Sandboxing detonation task. Once submitted, you will return to the `My Sandbox` page where you can monitor the status of the task.\n\nSandboxes have multiple returned statuses, these are listed below.\n\n| Status | What is it for? |\n| ------------------- | -------------------------- |\n| `Success` | Finished processing correctly |\n| `Started` | Sandbox session has started. |\n| `Collecting Data` | Sandbox session has been successful and data is being collected. |\n| `Failed` | Sandbox session has failed, this can be due to many reasons. |\n| `Pending` | Sandbox session is queued up and ready to start. |\n| `Delayed` | Sandbox session has been delayed and will start soon. |\n| `Failed with Quota Reimbursement` | Finished processing but failed, quota will be reimbursed. |\n| `Timed out with Quota Reimbursement` | Delayed in the queue for too long, got timed out and then reimbursement. |\n\n### Supported File Types {#file-types}\n\nThe PolySwarm Sandboxes support many file types, these are listed below.\n\n| Type | Extensions | Sandbox Provider |\n| ---------------- | ------------------- | ------|\n| Executable | `.dll` | Triage, Cape |\n| Executable | `.upx` | Cape |\n| Executable | `.exe` | Triage, Cape |\n| Executable | `.msi` | Triage |\n| Document | `.chm` | Triage, Cape |\n| Document | `.hta` | Triage, Cape |\n| Document | `.iqy` | Triage |\n| Document | `.doc`| Cape |\n| Document | `.docx`| Cape |\n| Document | `.xls`| Cape |\n| Document | `.xlsx`| Cape |\n| Document | `.ppt`| Cape |\n| Document | `.pptx`| Cape |\n| Document | `.pub`| Cape |\n| Document | `.pub2016`| Cape |\n| Document | `.one`| Cape |\n| Document | `.mht`| Cape |\n| Document | `.hwp`| Cape |\n| Document | `.ich`| Cape |\n| Document | `.inp`| Cape |\n| Document | `.pdf` | Triage |\n| Document | `.rtf` | Triage |\n| Document | `.slk` | Triage |\n| Document | `.swf` | Triage |\n| Document | `.html` | Triage, Cape|\n| Scripting | `.bat` | Triage, Cape |\n| Scripting | `.ps1` | Triage, Cape |\n| Scripting | `.js` | Triage, Cape |\n| Scripting | `.jse` | Triage, Cape |\n| Scripting | `.vbe` | Triage, Cape |\n| Scripting | `.pl` | Triage |\n| Scripting | `.py` | Cape |\n| Scripting | `.vbs` | Triage, Cape |\n| Scripting | `.wsf` | Triage, Cape|\n| Android | `.apk` | Triage |\n| Android | `.dex` | Triage |\n| Other | `.jar` | Triage |\n| Other | `.lnk` | Triage, Cape |\n| Other | `.url` | Triage |\n| Other | `.jnlp` | Triage |\n| Other | `.reg` | Cape |\n| Other | `.xslt` | Cape |\n| Other | `.xps` | Cape |\n\n32MB is the default \"max\" file submission size, this is a per-account setting, so it is possible for some users/teams to have a higher limit, if you wish to increase this limit please contact *customersuccess@polyswarm.io*\n\n## My Sandboxing {#my-sandboxing}\n\nThe My Sandbox tab shows you Artifacts that only you have Sandboxed, and the status of these submissions.\n\n\n\nThe table of submissions displays the following information:\n\n| Column | What is it for? |\n| ------------------- | -------------------------- |\n| Sandboxed On | Date and Time that the Artifact was Sandboxed on. |\n| Target | File name of file uploaded, or hash of the file is resandboxed. |\n| Type | Type of item sandboxed, i.e. `file`, `url`. |\n| SHA-256 | The `sha256` of the Artifact that has been Sandboxed. |\n| Sandbox Provider | Name of the sandbox provider used. |\n| Mal Score | Independent Score provided by the Sandbox, between 0-10. |\n| Status | The status of the Sandbox submission is color coded. The statuses can be: `Success`, `Pending`, `Collecting Data`, `Started`, `Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed` |\n| Actions | Single Action button will open the [Sandbox Results Summary](#summary-sandbox) page for that Artifact once the Status has changed to `Success`. |\n\n### Filtering\n\nThe `Filter` button at the top right of My Sandbox page provides the ability to Filter the results being seen. The following filter options are available:\n\n\n\n* **Status** - Status of the Sandbox submission and can be: `Success`, `Pending`, `Collecting Data`, `Started`,`Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed`\n* **Sandbox Provider** - Name of the Sandbox provider.\n* **SHA256** - Specific sha256 value of the Sandboxing submission.\n* **Date Range** - Start and End Date for the Sandboxing submission.\n\n> At the bottom of the My Sandbox page you can navigate to the next page if further results exist.\n\n## Team Sandboxing {#team-sandboxing}\n\nThe Team Sandbox tab shows you Artifacts that you and your team members you have Sandboxed, and the status of these submissions.\n\n\n\nThe table of submissions displays the following information:\n\n| Column | What is it for? |\n| ------------------- | -------------------------- |\n| Sandboxed On | Date and Time that the Artifact was Sandboxed on. |\n| Target | File name of file uploaded, or hash of the file is resandboxed. |\n| Type | Type of item sandboxed, i.e. `file`, `url`. |\n| SHA-256 | The `sha256` of the Artifact that has been Sandboxed. |\n| Sandbox Provider | Name of the sandbox provider used. |\n| Mal Score | Independent Score provided by the Sandbox, between 0-10. |\n| Status | The status of the Sandbox submission is color coded. The statuses can be: `Success`, `Pending`, `Collecting Data`, `Started`, `Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed` |\n| Actions | Single Action button will open the [Sandbox Results Summary](#summary-sandbox) page for that Artifact once the Status has changed to `Success`. |\n\n### Filtering\n\nThe `Filter` button at the top right of Team Sandbox page provides the ability to Filter the results being seen. The following filter options are available:\n\n\n\n* **Status** - Status of the Sandbox submission and can be: `Success`, `Pending`, `Collecting Data`, `Started`,`Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed`\n* **Sandbox Provider** - Name of the Sandbox provider.\n* **SHA256** - Specific sha256 value of the Sandboxing submission.\n* **Date Range** - Start and End Date for the Sandboxing submission.\n\n> At the bottom of the Team Sandbox page you can navigate to the next page if further results exist.\n\n## Sandbox History {#sandbox-history}\n\nThe Sandbox History tab allows you to search by sha256 hash to get a list of every time that artifact was Sandboxed, by any user.\n\n\n\nOnce you have searched for a Hash value, the table of submissions provides the following information:\n\n| Column | What is it for? |\n| ------------------- | -------------------------- |\n| Sandboxed On | Date and Time that the Artifact was Sandboxed on. |\n| Target | File name of file uploaded, or hash of the file is resandboxed. |\n| Type | Type of item sandboxed, i.e. `file`, `url`. |\n| Sandbox Provider | Name of the sandbox provider used. |\n| Status | The status of the Sandbox submission is color coded. The statuses can be: `Success`, `Pending`, `Collecting Data`, `Started`, `Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed` |\n| Actions | Single Action button will open the [Sandbox Results Summary](#summary-sandbox) page for that Artifact once the Status has changed to `Success`. |\n\n### Filtering\n\nThe `Filter` button at the top right of All Sandboxing page provides the ability to Filter the results being seen. The following filter options are available:\n\n* **Status** - Status of the Sandbox submission and can be: `Success`, `Pending`, `Collecting Data`, `Started`, `Delayed`, `Failed Reimbursed`, `Timeout Reimbursed` or `Failed`\n* **Sandbox Provider** - Name of the Sandbox provider.\n* **Date Range** - Start and End Date for the Sandboxing submission.\n\n> At the bottom of the My Sandbox page you can navigate to the next page if further results exist.\n\n## Sandbox Results Summary {#summary-sandbox}\n\nThis Sandbox Results Summary page provides the view of the latest Sandboxing Results for the Artifact for Cape and Triage.\n\nThe page can be accessed from the Action button on the My Sandbox and All Sandboxing pages as well as the `Latest Sandbox Results` button on the Scan Summary Page for the Artifact.\n\nTo view the latest **Scan results** page for this Artifact you can use the `Latest Scan Results` button in the top right, then use the `Latest Sandbox Results` button to navigate back to the Sandboxing detonation results.\n\n\n\n### Summary Pane\n\nThe left **Summary pane** provides access to either the latest Cape or Triage Sandbox detonation, clicking on either will change the data in the main page body. This section lists the Sandbox ID, sha256, file or url, sandbox score and verdict and the Malware Family.\n\n\n\nBelow the Summary Pane is the **Action Pane** with Several buttons:\n\n\n\n| Button | What is it for? |\n| ------------------- | -------------------------- |\n| Re-Sandbox | Re-Submit the Artifact to be Sandboxed. |\n| Share | Share a link to these sandbox results page on social media. |\n| Pivot | Enable/Disable the pivoting feature. |\n| History | See all Sandboxing history, brings you to the `All Sandboxing` page. |\n| Generate Report | Generates either a PDF or HTML report on demand, you will be able to choose sections to include. |\n\n### Sandbox Tabs\n\nThe Sandbox Results Summary page has tabs that contain the information from the Sandboxing. This is only a small sample of the data available, to see the fill content download the Full (RAW) JSON for the Sandbox Detonation.\n\n\n\nEach Tab has shortcut boxes present, these will be greyed out if the metadata does not exist, click on these to quickly jump to the subsection in the relevant tab.\n\n\n\n##### Extracted Config\n\nThis tab contains fields relating to `Malware config`, `Processes` and `Encryption Keys`. Items like Campaign information, Install paths, Access Types and Encryption Key values may be present if the Sandbox has this information. This section can include details from parsers on the sandbox like the CobaltStrike parser.\n\n\n\n##### Dropped Files\n\nThis tab contains information related to the Dropped Files from the Malware detonation. This tab will display information like File Name, Size, Type and multiple hash values of each dropped file.\n\n\n\n> Note if you want the dropped file to be detonated in the Sandboxes, perform a Hash Search to lookup that file. On the Hash Search listing, view the Scan results for that file. On that page, you can select the \"Sandbox\" icon in the Actions Pane to submit it for Sandboxing.\n\n### Network Tab\n\nThis tab contains information on IPs, SMTP, Domains and JARM details relating to the Sandboxed Artifact. If no data is present then there is no network information available from the Sandbox for this detonation.\n\n\n\n### HTTP Transaction Tab\n\nThis tab contains information HTTP Transactions, this view is only available for Triage Sandboxing sessions.\n\n\n\n### Analysis Tab\n\nThis tab contains information on MITRE TTPs used, OS Autorun, Signatures that have been triggered on the Sandbox and Processes. If no data is present then there is no information available for Analysis from the Sandbox for this detonation.\n\n\n\n### JSON Tab\n\nThis tab provides access to the JSON object in relation to the Sandbox detonation, the search field can be used to find specific values and keys. The JSON can be downloaded from this page to be stored locally.\n\n> This JSON is the Summary JSON file for the Sandboxing, to download the Full JSON see the `raw` report in the download tab.\n\n### Download Results Tab\n\nThis tab allows you to download the Sandbox artifacts. These files can be the JARM file, PCAP Files, full JSON Reports and all dropped artifacts. The dropped files will always be downloaded as an encrypted zip file to prevent trigger your local AV engine.\n\nEach of these files can be downloaded as a single zip by using the `zip` tick box at the bottom of the page.\n\n> The `raw` json is the full report created by the Sandbox, while the regular report is the summarized version used to populate the JSON tab.\n\n\n\n### Video & Screenshot Tab\n\nThis tab allows you to view the Triage Video OR Cape Screenshots that have been captured from the detonation. \n\n\n\n\n\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/searching.md","frontmatter":{"title":"Searching","excerpt":"PolySwarm supports both Hash Searching and Metadata Searching..."},"html":"Searching with the UI
\nPolySwarm supports Hash Searching, Metadata Searching and IOC Searching. This section will cover how to use these functions in the UI.
\n\nHash Searching
\nSearching by Hash allows you to find Artifacts that match a given hash. We support searching by MD5, SHA1, and SHA256.
\nHashes can be entered into the multi-use text box below the “Select file” button on the Scan page.\nThey can also be entered into the text box on the Search page’s Hash Searching tab.
\nOn the Hash Searching tab, clicking the \"Search Multiple\" toggle above the search box will allow the user to enter a list of hashes to be searched.\nWhen multiple hashes are searched, the hash results will display in the same order as the list of hashes provided.
\nHash Search Results
\nHash search results are listed on the Search -> Hash Searching tab. The below covers what is displayed in the table once you search a hash.
\n![\"Searching](\"/images/ui/ui_search_hash.png\")
| Button | \nWhat is it for? | \n
|---|---|
| Hash | \nSHA256 hash of the Artifact with the file MIME type. | \n
| PolyScore | \nThreat scoring algorithm that provides the probability that a given file contains Malware. One being the highest number and will contain Malware, Zero being the least chance. | \n
| Scan Date | \nDate that the Artifact was last scanned by the Engines. | \n
| Detections | \nDetections column shows the engine detection results, which can be one of Four items:
| \n
| Network | \nIcons to highlight the available network data via the metadata, if the icon is colored, that type of network data is available:
| \n
| Actions | \nThe Actions column has an icon that allows you to get more information about the artifact:
| \n
Metadata Searching
\nSearching by Metadata allows you to find Artifacts that have a variety of attributes or content.\nWe support queries using the ElasticSearch Query String syntax.
\nMetadata searches can be entered into the search bubble on the landing page.\nThey can also be entered into the Search Metadata box on the Search -> Metadata Searching tab.\nTo understand how to build out a Metadata query see the How-To Guide.
\nThe Search Metadata box records your most recent queries and will suggest them as you type future queries.\nYou can remove queries from the list of recent queries by clicking the \"X\" icon at the far right side of the query entry.
\nMetadata Search Results
\nWhen a Metadata Search Query is run, the search results will be listed in a table below the Search Metadata box. The below covers what is displayed in the table once you search a hash.
\n![\"Searching](\"/images/ui/ui_search_meta.png\")
| Button | \nWhat is it for? | \n
|---|---|
| Hash | \nSHA256 hash of the Artifact with the file MIME type. | \n
| Malware Family | \nThe Malware Family shows the PolyUnite malware family. | \n
| First Seen | \nDate the Artifact was first seen in PolySwarm. | \n
| Last Seen | \nDate the Artifact was last seen in PolySwarm. | \n
| PolyScore | \nThreat scoring algorithm that provides the probability that a given file contains Malware. One being the highest number and will contain Malware, Zero being the least chance. | \n
| Detections | \nDetections column shows M/T (Malicious/Total) where Malicious is the number of engines that found the artifact to be malicious and Total is the total number of engines that analyzed the artifact. | \n
| File Size | \nSize of the Artifact File. | \n
| File Type | \nFile Extension Type of the Artifact. | \n
| Actions | \nThe Actions column has icon that allow you to get more information about the artifact:
| \n
At the top right of the table are buttons that allow you to change how the results are displayed as well as to save the results.
\n- \n
- Gear: Drop down that allows you to check/un-check column names to hide/unhide them. Plus, you can drag/drop column names in the drop down to re-order them. \n
- Floppy Disk: Allows you to save the currently displayed results as a CSV file. Only the data in the visible columns of the current page of results are saved. \n
\n\nNotes:
\n\n
\n- The results in the table are sorted with the most recently submitted file first.
\n- The results are paginated, defaulting to 25 per page.
\n- You can edit the page size using the dropdown menu in the lower left of the table.
\n- Next to that are buttons to go to first, previous, and next page of the results.
\n
\n
\n\n\nBe aware that each page of metadata search results that is viewed is counted as one use of your Metadata Search quota.\nChanging the \"Rows per page\" will reload the page, and also uses one use of your Metadata Search quota.
\n
IOC Searching
\nIOC Searching can be split into two types of Searches, these are:
\n- \n
- Searching for Associated IOCs related to a Hash: This returns IOCs that were observed by our sandbox during analysis. These IP's and Domains are classified as C2 or malicious. \n
- Searching for Associated Hashes related to an IP, URL, imphash or MITRE TTP: This returns file hashes that were seen communicating with the specified IPs or domains in our sandbox — regardless of whether the communication was malicious or not. \n
Access the IOC Search Functionality by Navigating to Search > IOC Searching.
\nSearching for Associated IOCs
\nThe Default option for this page is the Switch button will be on By Hash meaning searching on a Hash will provide a list of associated IOCs.
Once a hash has been searched, the results page will list the imphash, urls, ips and MITRE TTPs
![\"Searching](\"/images/ui/ui_search_ioc_hash.png\")
These associated items have been extracted from the Metadata for the Artifact and have been discovered by Static Tools and Sandboxing.
\nSearching for Associated Hashes
\nMoving the Switch to the By IOC option will provide the ability to search on a IOC (imphash, urls, ips and MITRE TTPs) and find related hashes.
This page provides the ability to select a start and end date criteria for the hash results to meet, and choose the IOC type.
Once an IOC has been searched on, the results table will show a list of sha256 hashes that are associated to the IOC along with the ability to Download the results as a csv and view each result in a new tab.
![\"Searching](\"/images/ui/ui_search_ioc_ip.png\")
\n\n| Button | What is it for? |\n| ------------------- | -------------------------- |\n| Hash | SHA256 hash of the Artifact with the file MIME type. |\n| PolyScore | Threat scoring algorithm that provides the probability that a given file contains Malware. One being the highest number and will contain Malware, Zero being the least chance. |\n| Scan Date | Date that the Artifact was last scanned by the Engines. |\n| Detections | Detections column shows the engine detection results, which can be one of Four items: - **M/T (Malicious/Total)** - Where Malicious is the number of engines that found the artifact to be malicious and Total is the total number of engines that analyzed the artifact.
- **Scan Now** - This means we have an artifact matching the hash, but it has not been scanned. Click on \"Scan Now\" to trigger a scan of that artifact.
- **Not Found** - No artifact matching the hash was found.
- **Invalid Hash** - The hash string was not a SHA256, SHA1, or MD5 hash.
- **Link Icon** - URL Network Data.
- **Globe Icon** - Domain Network Data.
- **Water Drop** - IP Network Data.
- **Down Arrow** - Show Artifact data and data extracted from Static Tools only.
- **Open in New Tab** - Opens the [Scan Results Page](customers/scanning#scan-results-page) for that artifact in a new tab, so you can view the metadata related to that artifact.
- **Download** - Download the artifact encapsulated in an encrypted .zip file, which is password protected.
\n\n\n| Button | What is it for? |\n| ------------------- | -------------------------- |\n| Hash | SHA256 hash of the Artifact with the file MIME type. |\n| Malware Family | The Malware Family shows the PolyUnite malware family. |\n| First Seen | Date the Artifact was first seen in PolySwarm. |\n| Last Seen | Date the Artifact was last seen in PolySwarm. |\n| PolyScore | Threat scoring algorithm that provides the probability that a given file contains Malware. One being the highest number and will contain Malware, Zero being the least chance. |\n| Detections | Detections column shows M/T (Malicious/Total) where Malicious is the number of engines that found the artifact to be malicious and Total is the total number of engines that analyzed the artifact.|\n| File Size| Size of the Artifact File. |\n| File Type | File Extension Type of the Artifact. |\n| Actions | The Actions column has icon that allow you to get more information about the artifact: - **Open in New Tab** - Opens the [Scan Results Page](customers/scanning#scan-results-page) for that artifact in a new tab, so you can view the metadata related that artifact.
- **Download** - Download the artifact encapsulated in an encrypted .zip file, which is password protected.
\n\n> Be aware that each page of metadata search results that is viewed is counted as **one use of your Metadata Search quota**.\n> Changing the \"Rows per page\" will reload the page, and also uses one use of your Metadata Search quota.\n\n
\n\n## IOC Searching {#ioc-searching}\n\nIOC Searching can be split into two types of Searches, these are:\n\n- Searching for Associated IOCs related to a Hash: This returns IOCs that were observed by our sandbox during analysis. These IP's and Domains are classified as C2 or malicious.\n- Searching for Associated Hashes related to an IP, URL, imphash or MITRE TTP: This returns file hashes that were seen communicating with the specified IPs or domains in our sandbox — regardless of whether the communication was malicious or not.\n\nAccess the IOC Search Functionality by Navigating to [Search > IOC Searching](https://polyswarm.network/search/ioc).\n\n### Searching for Associated IOCs\n\nThe Default option for this page is the `Switch` button will be on `By Hash` meaning searching on a Hash will provide a list of associated IOCs.\n\nOnce a hash has been searched, the results page will list the `imphash`, `urls`, `ips` and `MITRE TTPs`\n\n\n\nThese associated items have been extracted from the Metadata for the Artifact and have been discovered by Static Tools and Sandboxing.\n\n### Searching for Associated Hashes\n\nMoving the `Switch` to the `By IOC` option will provide the ability to search on a IOC (`imphash`, `urls`, `ips` and `MITRE TTPs`) and find related hashes.\n\nThis page provides the ability to select a `start` and `end` date criteria for the hash results to meet, and choose the IOC type.\n\nOnce an IOC has been searched on, the results table will show a list of sha256 hashes that are associated to the IOC along with the ability to Download the results as a `csv` and view each result in a new tab.\n\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/hunting.md","frontmatter":{"title":"Hunting","excerpt":"On the Hunt page in the PolySwarm UI, we support Live and Historical hunting using YARA Rulesets..."},"html":"Hunting
\nOn the Hunt page in the PolySwarm UI, we support Live and Historical Hunting using YARA Rulesets. A YARA Ruleset is a text file, traditionally having the .yar extension, that contains one or more YARA rules. Some people refer to the file as a YARA Rules file.
\n\nYara Rules
\nWhen performing Live or Historical Hunting, Artifacts are processed by the YARA tool according to the YARA rules contained in the active YARA Ruleset. Writing YARA rules is explained in-depth in the YARA documentation. And there are example YARA Rules in the Yara-Rules GitHub repository.
\nYara Rulesets are managed on the Hunt page’s Ruleset and Hunt Management tab.
\nAdding Rulesets
\nIf you have not added any Rulesets, there is a large “Add Rulesets” button on the Rulesets and Hunt Management tab to add your first Ruleset. If you’ve already added one or more rulesets, there is a “+” button in the upper right to add additional Rulesets.
\nAll Rulesets need a Name. The Description field is optional, but can be helpful to remember details about your rules. And finally there is the large text box to enter the YARA Rules.
\nYou have 2 options to enter the Rules:
\n- \n
- You can paste your Rules into the large text box. \n
- You can click the small “+” button in the lower right corner of the large text box to select a YARA Ruleset file from your computer to upload as your Ruleset. \n
Click the Save button to save the Ruleset.
\nValidating Rulesets
\nWhen one or more Rules have been entered into the large Rules text box, the button in the bottom right changes from a “+” button to a “Validate” button. Click the Validate button to validate the syntax of your Ruleset. If you click outside of the Rules area after entering rules, the validation will automatically run for you. Once you have a valid Ruleset, click the Save button to save it.
\nActions
\nActions exist for each Ruleset, the following highlight the functionality of these options.
\n![\"Hunting](\"/images/ui/ui_hunting_actions.png\")
Viewing / Editing Rulesets
\nYou can view and edit an existing Ruleset by clicking on the pencil icon in the Actions column.\nIf you have a Live Hunt running, the pencil icon is disabled.\nYou must stop the Live Hunt before you can edit the Ruleset.
\nDuplicating Rulesets
\nYou can copy and duplicate an existing Ruleset by clicking on the copy icon in the Actions column.\nClicking that icon will open the Create Ruleset window enabling you to create a new ruleset where the initial data is pre-filled using the data from this existing Ruleset.\nMake your changes, then click the Save button.
\nDeleting Rulesets
\nYou can delete an existing Ruleset by clicking on the trash can icon in the Actions column, if the trash icon is disabled there is a Live Hunt running.\nIf there is a running Live Hunt using this Ruleset, you must stop the Live Hunt before you can delete the Ruleset.
\nRunning a Hunt using a Ruleset
\nYou can start a Live Hunt using a Ruleset by simply clicking the toggle button to the \"on\" position.\nYou can start a Historical Hunt using a Ruleset by clicking on the running man icon in the Actions column.
\nIt is important to note that you cannot edit or delete a Ruleset while a Live Hunt is running.\nWe store the contents of the Ruleset used at the time the Live or Historical Hunt is started.\nSo when you view Hunt results, you are always able to reference the exact Ruleset that was used to run the Hunt.
\nLive Hunting
\nLive Hunting is a technique to use YARA Rules to examine new artifacts as they are submitted.\nWhen an artifact matches the Ruleset used in a Live Hunt, a new row is added to the Live Hunting Feed.
\nViewing Live Hunting Matches
\nThe Live Hunting Feed tab shows all Live Hunting matches as a continuous feed.\nThe Live Hunt matches for all your active Live Hunts are displayed in the feed as a single listing in reverse chronological ordering.
\nTable of Matches
\nEach row in the table is a match for a Live Hunt.\nThe row contains several key pieces of data and some Action buttons.
\n![\"Hunting](\"/images/ui/ui_live_hunt.png\")
| Column | \nWhat is it for? | \n
|---|---|
| Checkboxes | \nChecking one or more of these boxes activates 2 buttons in the upper right.
| \n
| Rule Name | \nColumn contains the name of the Rule that triggered the match. | \n
| SHA256 | \nColumn is the SHA256 of the matching artifact. There is a copy icon that will copy the hash to your clipboard. | \n
| Malware Family Name | \nColumn is the name of Malware Family associated with the artifact that matched the Rule. If the artifact was determined to be Benign, it is possible that the Malware Family name is blank. | \n
| PolyScore | \nColumn shows the PolyScore for each match. | \n
| Detections | \nColumn shows the number of malicious assertions / total assertions for the matched artifact. | \n
| Matched On | \nIs the date or relative time when the match happened. | \n
| Actions | \nAlong the right side is the Actions column with several buttons.
| \n
Filter
\nIn the upper right above the table is the Filter.\nYou can define a Filter to limit the set of matches displayed in the table of matches.\nThe Filter currently supports filtering by:
\n- \n
- Rule Name \n
- Malware Family Name \n
- PolyScore \n
Starting and Stopping a Live Hunt
\nYou can start a Live Hunt using a Ruleset by simply clicking the toggle button to the \"on\" position.\nAnd stop it by toggling to the \"off\" position.\nStopping a Live Hunt does NOT delete any of the matches from that Hunt.\nLive Hunt matches are always available in the Live Hunting Feed until you delete them.
\nHistorical Hunting
\nHistorical Hunting is a technique to use YARA Rules to examine artifacts that were submitted in the past.\nCurrently, Historical Hunts evaluate all artifacts submitted over the past 6 months.
\nViewing Historical Hunts
\nThe Historical Hunts tab allows you to view/manage Historical Hunts and their Matches.
\nEach row in the table is a Historical Hunt.\nThe row contains several key pieces of data about the Historical Hunt and some Action buttons.
\n![\"Hunting](\"/images/ui/ui_hist_hunt.png\")
| Column | \nWhat is it for? | \n
|---|---|
| Checkboxes | \nChecking one or more of these boxes activates the delete button in the upper right. This allows you to delete the Historical Hunt(s) that you have checked, along with all matches for the selected Historical Hunt(s). | \n
| Status | \nStatus column indicates the completion percentage and status of the Hunt:
| \n
| Historical Hunt Name | \nContains the name of the Historical Hunt. | \n
| Matches | \nColumn indicates the number of matches for this Hunt. This value is computed when the Hunt has finished. | \n
| Created | \nColumn indicates the date or relative time when the Hunt was started. | \n
| Actions | \nAlong the right side is the Actions column with several buttons.
| \n
Deleting a Historical Hunt
\nTo delete a Historical Hunt, click on the “trash can” button in the Action column on the right side of the row. This will delete the Hunt and all of the results in that hunt.\nYou can only delete a Hunt that is not running.
\nViewing Historical Hunting Matches
\nClicking on the row for a Hunt will display a new table that contains Historical Hunt matches.\nThese Results are paginated, so you can choose the quantity to view and move between pages of matches.
\nTable of Matches
\nEach row in the table is a match for the chosen Historical Hunt.\nThe row contains several key pieces of data and some Action buttons.
\n![\"Hunting](\"/images/ui/ui_hist_hunt_result.png\")
| Column | \nWhat is it for? | \n
|---|---|
| Checkboxes | \nChecking one or more of these boxes activates 2 buttons in the upper right.
| \n
| Rule Name | \nColumn contains the name of the Rule that triggered the match. | \n
| SHA256 | \nColumn is the SHA256 of the matching artifact. There is a copy icon that will copy the hash to your clipboard. | \n
| Malware Family Name | \nColumn is the name of Malware Family associated with the artifact that matched the Rule. If the artifact was determined to be Benign, it is possible that the Malware Family name is blank. | \n
| PolyScore | \nColumn shows the PolyScore for each match. | \n
| Detections | \nColumn shows the number of malicious assertions / total assertions for the matched artifact. | \n
| Matched On | \nIs the date or relative time when the match happened. | \n
| Actions | \nAlong the right side is the Actions column with several buttons.
| \n
Filter
\nIn the upper right above the table is the Filter.\nYou can define a Filter to limit the set of matches displayed in the table of matches.\nThe Filter currently supports filtering by:
\n- \n
- Rule Name \n
- Malware Family Name \n
- PolyScore \n
Deleting Historical Hunt Matches
\nUsing the Historical Hunt matches table, you can delete matches one at a time, or in bulk.\nTo delete one at a time, click on the delete icon in the Actions column on the right side of the row.\nTo delete in bulk, check one or more of the checkboxes in the first column and then click on the delete icon in the upper right.
","rawMarkdownBody":"\n# Hunting\n\nOn the [Hunt](https://polyswarm.network/hunt/rulesets) page in the PolySwarm UI, we support Live and Historical Hunting using YARA Rulesets. A YARA Ruleset is a text file, traditionally having the .yar extension, that contains one or more YARA rules. Some people refer to the file as a YARA Rules file.\n\n\n\n## Yara Rules {#yara-rules}\n\nWhen performing Live or Historical Hunting, Artifacts are processed by the [YARA tool](https://github.com/VirusTotal/yara) according to the YARA rules contained in the active YARA Ruleset. Writing YARA rules is explained in-depth in the [YARA documentation](https://yara.readthedocs.io/en/latest/). And there are example YARA Rules in the [Yara-Rules GitHub repository](https://github.com/Yara-Rules/rules).\n\nYara Rulesets are managed on the Hunt page’s Ruleset and Hunt Management tab.\n\n### Adding Rulesets\n\nIf you have not added any Rulesets, there is a large “Add Rulesets” button on the [Rulesets and Hunt Management](https://polyswarm.network/hunt/rulesets) tab to add your first Ruleset. If you’ve already added one or more rulesets, there is a “+” button in the upper right to add additional Rulesets.\n\nAll Rulesets need a Name. The Description field is optional, but can be helpful to remember details about your rules. And finally there is the large text box to enter the YARA Rules.\n\nYou have 2 options to enter the Rules:\n\n1. You can paste your Rules into the large text box.\n2. You can click the small “+” button in the lower right corner of the large text box to select a YARA Ruleset file from your computer to upload as your Ruleset.\n\nClick the Save button to save the Ruleset.\n\n### Validating Rulesets\n\nWhen one or more Rules have been entered into the large Rules text box, the button in the bottom right changes from a “+” button to a “Validate” button. Click the Validate button to validate the syntax of your Ruleset. If you click outside of the Rules area after entering rules, the validation will automatically run for you. Once you have a valid Ruleset, click the Save button to save it.\n\n### Actions\n\nActions exist for each Ruleset, the following highlight the functionality of these options.\n\n\n\n#### Viewing / Editing Rulesets\n\nYou can view and edit an existing Ruleset by clicking on the **pencil** icon in the Actions column.\nIf you have a Live Hunt running, the pencil icon is disabled.\nYou must stop the Live Hunt before you can edit the Ruleset.\n\n#### Duplicating Rulesets\n\nYou can copy and duplicate an existing Ruleset by clicking on the **copy** icon in the Actions column.\nClicking that icon will open the Create Ruleset window enabling you to create a new ruleset where the initial data is pre-filled using the data from this existing Ruleset.\nMake your changes, then click the Save button.\n\n#### Deleting Rulesets\n\nYou can delete an existing Ruleset by clicking on the **trash** can icon in the Actions column, if the trash icon is disabled there is a Live Hunt running.\nIf there is a running Live Hunt using this Ruleset, you must stop the Live Hunt before you can delete the Ruleset.\n\n#### Running a Hunt using a Ruleset\n\nYou can start a Live Hunt using a Ruleset by simply clicking the toggle button to the \"on\" position.\nYou can start a Historical Hunt using a Ruleset by clicking on the **running man** icon in the Actions column.\n\nIt is important to note that you cannot edit or delete a Ruleset while a Live Hunt is running.\nWe store the contents of the Ruleset used at the time the Live or Historical Hunt is started.\nSo when you view Hunt results, you are always able to reference the exact Ruleset that was used to run the Hunt.\n\n## Live Hunting {#live-hunting}\n\nLive Hunting is a technique to use YARA Rules to examine new artifacts as they are submitted.\nWhen an artifact matches the Ruleset used in a Live Hunt, a new row is added to the Live Hunting Feed.\n\n### Viewing Live Hunting Matches\n\nThe [Live Hunting Feed](https://polyswarm.network/hunt/live) tab shows all Live Hunting matches as a continuous feed.\nThe Live Hunt matches for all your active Live Hunts are displayed in the feed as a single listing in reverse chronological ordering.\n\n##### Table of Matches\n\nEach row in the table is a match for a Live Hunt.\nThe row contains several key pieces of data and some Action buttons.\n\n\n\n| Column | What is it for? |\n| ------------------- | -------------------------- |\n| Checkboxes | Checking one or more of these boxes activates 2 buttons in the upper right.- **Save:** It allows you to download a .CSV file containing the matches that you have checked.
- **Delete:** It allows you to delete the matches that you have checked.
- `Open in New Tab Icon` - Opens the [Scan Results Page](customers/scanning#scan-results-page) for that artifact in a new tab, so you can view the metadata related that artifact.
- `Download Icon` - Download the artifact encapsulated in an encrypted .zip file, which is password protected..
- `View Ruleset Icon` - View the Ruleset used by the associated Live Hunt.
- `Info Icon` - Show Live Hunt Info.
- `Delete Icon` - Delete the match.
\n\n| Column | What is it for? |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Checkboxes | Checking one or more of these boxes activates the delete button in the upper right. This allows you to delete the Historical Hunt(s) that you have checked, along with all matches for the selected Historical Hunt(s). |\n| Status | Status column indicates the completion percentage and status of the Hunt: - **Pending** - Historical Hunt is queued to run at the next launch interval. Percentage complete will be 0%.
- **Running** - Historical Hunt is currently running. Percentage complete will indicate the percentage of artifacts that have been processed.
- **Completed** - Historical Hunt completed successfully. Percentage complete will be 100%.
- **Cancelled** - Historical Hunt was cancelled by user clicking the hand icon. Percentage complete will indicate the percentage of artifacts that were processed before the Hunt was stopped.
- **Stopped** - Historical Hunt was stopped due to exceeding match limit (current limit is 10,000 matches) and is pending shutdown.
- **Limited** - Historical Hunt was stopped due to the match limit and has completed shutdown. The percentage displayed is the percentage of artifacts that were processed before the Hunt was stopped.
- **Failed** - Historical Hunt ended with a failure condition. This should be rare since we will retry the Hunt under most failure conditions.
- **Deleting** - Historical Hunt is in the process of being deleted. User clicked the Delete button on this Historical Hunt. Due to the fact that Historical Hunts might have a large number of results, deletions are done asynchronously.
- `Floppy Disk Icon` - Download the matches for this Hunt as a CSV file. This is available once the Hunt has finished.
- `Hand Icon` - Cancel a Hunt. If it has started it will stop. If it is pending it will not run.
- `List Icon` - View the Ruleset that is used by the Historical Hunt.
- `Info Icon` - Show Historical Hunt Info. Once the Hunt has finished, this will include a table showing the number of matches for each Rule Name in the Ruleset for the Hunt.
- `Delete Icon` - Delete the Historical Hunt and all matches. You can only delete a Hunt that is not running.
\n\n| Column | What is it for? |\n| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Checkboxes | Checking one or more of these boxes activates 2 buttons in the upper right.- **Save:**It allows you to download a .CSV file containing the matches that you have checked.
- **Delete:** It allows you to delete the matches that you have checked.
- `Open in New Window Icon` - Open Scan Results page for the matching artifact in New Tab/Window.
- `Download Icon` - Download the matching artifact binary
- `View Ruleset Icon ` - View the Ruleset used by the associated Live Hunt.
- `Info Icon` - Show Historical Hunt Info.
- `Delete Icon` - Delete the match.
PolySwarm Plans
\nIn PolySwarm UI, the Pricing page lists PolySwarm's plans.
\nAvailable Plans
\nPolySwarm provides multiple plans.
\n- \n
- Individual Plans - These are paid plans available for User Accounts. \n
- Enterprise Plans - These are paid plans available for User and Team Accounts. \n
The \"Community\" Plan is the default plan for both User and Team Accounts.\nThis plan is free, but the user must be logged into their User Account when using PolySwarm UI.\nUsage limits are higher than for anonymous usage, but less than all paid plans.
\nComponents of a Plan
\n- \n
- Quota Usage Period \n
- Billing Cycle \n
- Daily API usage limit \n
- One or more features \n
- Usage limit for each feature \n
Quota Usage Period
\nThe Quota Usage Period is the period of time until the Monthly Quota is reset.\nThe Monthly Quota used resets every 30 days, regardless of the Subscription Plan.\nA Quota Usage Period starts on the date and time the Plan Subscription is activated and ends on every subsequent 30th day at the same time.
\nBilling Cycle
\nPlan subscription durations can be either month-to-month or annual.\nMonth-to-Month has a 30-day cycle, while Annual has a 360-day cycle.
\nMonth-To-Month Subscription
\nTerm
\nThis subscription has a term of 30 consecutive days, which is one Usage Period.\nThe term starts on the date and time the subscription is activated and ends on the 30th day at the same time.
\nRenewal
\nAt the end of each term, the subscription automatically renews at the same rate for one more term.\nAnytime during the term, the user can cancel the automatic renewal of the subscription, such that at the end of that term it will not automatically renew.
\nInvoicing
\nThe cost of the subscription is charged at the start of each term.
\nAnnual Subscription
\nTerm
\nThis subscription has a term of 360 days, which is 12 Usage Periods.\nThe term starts on the date and time the subscription is activated and ends on the 360th day at the same time.
\nRenewal
\nAt the end of each term, the subscription automatically renews at the same rate for one more term.\nAnytime during the term, the user can cancel the automatic renewal of the subscription, such that at the end of that term it will not automatically renew.
\nInvoicing
\nThe cost of the subscription is charged at the start of each term.
\nDaily API Usage Limit
\nEach plan has a fixed Daily API usage limit.\nThis limit is the maximum number of total feature usages per 24-hour period.\nThis limit overrides all feature usage limits and is cumulative for all features.\nThe only method to increase the Daily API Usage limit is to purchase a plan with a higher limit.
\nQuota Usage Limits
\nEach Feature has a Quota Usage Limit that defines the quantity of usage available during each Quota Usage Period.\nEach subsequent Quota Usage Period will cause the Quota Usage to reset to the limits according to the active plan.\nThe quota usage limit of each feature is independent of the quota usage limit of all other features.
\nComparing
\nThe left column of the Compare Plans table lists each feature that PolySwarm offers.\nSelecting the small info icon will display the description of that feature.\nPolySwarm occasionally offers a free trial, contact us to ask for more information.
\nSelecting
\nAll new User Accounts and Team Accounts have the “Community” plan.\nThis allows all users to enjoy the base functionality of the platform for free.\nOnce the account is created, the plan can be upgraded to a paid plan.
\nIf you'd like to do a Free Trial, PolySwarm will work with you to set up a trial.
\nFree Trial
\nDuring the free trial, your account will have the Daily API Limit and all Quota Usage Limits based on the trial plan.\nWhen the trial is over, your account will revert to the free Community plan, so the Daily API Limit and all Quota Usage Limits will be replaced by those from the Community plan.\nAny features not included in the Community plan will become unavailable.\nIf you want access to other features or higher usage limits, you will need to purchase a paid plan.
\nUsing
\nIt is important to understand that each Account has a separate Subscription Plan with access based on your API Keys.\nSince PolySwarm UI allows a User Account to create one or more Team Accounts, this means that the User Account would have one subscription, while each Team Account would have separate subscriptions.\nThere is no usage sharing or inheritance between accounts.\nWe do this to allow larger organizations to purchase separate plans for separate teams.
\nThe User Account and Team Account documentation describes how to Switch Context to make use of each subscription.
","rawMarkdownBody":"\n# PolySwarm Plans\n\nIn PolySwarm UI, the [Pricing](https://polyswarm.network/pricing) page lists PolySwarm's plans.\n\n## Available Plans\n\nPolySwarm provides multiple plans.\n\n* Individual Plans - These are paid plans available for User Accounts.\n* Enterprise Plans - These are paid plans available for User and Team Accounts.\n\nThe \"Community\" Plan is the default plan for both User and Team Accounts.\nThis plan is free, but the user must be logged into their User Account when using PolySwarm UI.\nUsage limits are higher than for anonymous usage, but less than all paid plans.\n\n### Components of a Plan\n\n* Quota Usage Period\n* Billing Cycle\n* Daily API usage limit\n* One or more features\n* Usage limit for each feature\n\n#### Quota Usage Period\nThe Quota Usage Period is the period of time until the Monthly Quota is reset.\nThe Monthly Quota used resets every 30 days, regardless of the Subscription Plan.\nA Quota Usage Period starts on the date and time the Plan Subscription is activated and ends on every subsequent 30th day at the same time.\n\n#### Billing Cycle\nPlan subscription durations can be either month-to-month or annual.\nMonth-to-Month has a 30-day cycle, while Annual has a 360-day cycle.\n\n##### Month-To-Month Subscription\n*Term*\n\nThis subscription has a term of 30 consecutive days, which is one Usage Period.\nThe term starts on the date and time the subscription is activated and ends on the 30th day at the same time.\n\n*Renewal*\n\nAt the end of each term, the subscription automatically renews at the same rate for one more term.\nAnytime during the term, the user can cancel the automatic renewal of the subscription, such that at the end of that term it will not automatically renew.\n\n*Invoicing*\n\nThe cost of the subscription is charged at the start of each term.\n\n##### Annual Subscription\n*Term*\n\nThis subscription has a term of 360 days, which is 12 Usage Periods.\nThe term starts on the date and time the subscription is activated and ends on the 360th day at the same time.\n\n*Renewal*\n\nAt the end of each term, the subscription automatically renews at the same rate for one more term.\nAnytime during the term, the user can cancel the automatic renewal of the subscription, such that at the end of that term it will not automatically renew.\n\n*Invoicing*\n\nThe cost of the subscription is charged at the start of each term.\n\n#### Daily API Usage Limit\nEach plan has a fixed Daily API usage limit.\nThis limit is the maximum number of total feature usages per 24-hour period.\nThis limit overrides all feature usage limits and is cumulative for all features.\nThe only method to increase the Daily API Usage limit is to purchase a plan with a higher limit.\n\n#### Quota Usage Limits\nEach Feature has a Quota Usage Limit that defines the quantity of usage available during each Quota Usage Period.\nEach subsequent Quota Usage Period will cause the Quota Usage to reset to the limits according to the active plan.\nThe quota usage limit of each feature is independent of the quota usage limit of all other features.\n\n## Comparing\nThe left column of the Compare Plans table lists each feature that PolySwarm offers.\nSelecting the small info icon will display the description of that feature.\nPolySwarm occasionally offers a free trial, contact us to ask for more information.\n\n## Selecting\nAll new User Accounts and Team Accounts have the “Community” plan.\nThis allows all users to enjoy the base functionality of the platform for free.\nOnce the account is created, the plan can be upgraded to a paid plan.\n\nIf you'd like to do a Free Trial, PolySwarm will work with you to set up a trial.\n\n### Free Trial\nDuring the free trial, your account will have the Daily API Limit and all Quota Usage Limits based on the trial plan.\nWhen the trial is over, your account will revert to the free Community plan, so the Daily API Limit and all Quota Usage Limits will be replaced by those from the Community plan.\nAny features not included in the Community plan will become unavailable.\nIf you want access to other features or higher usage limits, you will need to purchase a paid plan.\n\n## Using\nIt is important to understand that each Account has a separate Subscription Plan with access based on your API Keys.\nSince PolySwarm UI allows a User Account to create one or more Team Accounts, this means that the User Account would have one subscription, while each Team Account would have separate subscriptions.\nThere is no usage sharing or inheritance between accounts.\nWe do this to allow larger organizations to purchase separate plans for separate teams.\n\nThe User Account and Team Account documentation describes how to Switch Context to make use of each subscription.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/webhooks.md","frontmatter":{"title":"Engine Webhooks","excerpt":"The Engine Webhooks tab in the Account Settings is used to manage engine webhooks"},"html":"Engine Webhooks
\nGeneral
\nThe Engine Webhooks tab in the User Account or Team Account Settings of a PolySwarm UI Account allows you to manage engine webhooks used by your Account. In a Team Account, a User must have the Team Admin or Microengine Admin role to view and use the Engine Webhooks tab.
\nHMAC Secret
\nThe engine webhook's HMAC Secret is used to allow the remote web service to verify that the engine webhook call was made by the PolySwarm Marketplace. All engine webhook calls are signed using the HMAC Secret, and can thus be verified by the recipient. In the Engine Webhooks tab, the HMAC Secret is hidden by default. You can click the \"Eye\" icon to view it or click the \"Copy\" icon to copy it to your clipboard.
\nRate Limit
\nThe rate limit is the number of engine webhook messages your engine webhook URL can process in one day (24hr period). This is the mechanism that you can use to control how many bounties your Engine receives in a day.
\nStatus
\nAn engine webhook's Status will be in one of the following states:
\n- \n
- Pending - The engine webhook has been created, but has not been tested. \n
- Verified - The engine webhook has been tested and the remote service responded correctly. \n
- Failed - The engine webhook was Verified, but the remote service is no longer responding. If an engine webhook is in the Failed state, it needs to be Tested again to become Verified. \n
URL
\nThe engine webhook URL must be the full URI that your web server is listening on to receive an engine webhook.\nIt must use HTTPS.\nOften it will be something like: \"https://example.com:1234/my/api/\"
\nCreating
\nTo create your first engine webhook, click the \"Create webhook\" button to open the engine webhook creation window. If you have one or more existing engine webhooks, you can click the \"+\" button to create another one.
\nIn the Create Engine Webhook window, enter the engine webhook URL and its Rate Limit. Then click Save.
\nDeleting
\nTo delete an engine webhook, click the \"Trash\" icon in the Actions column.
\nAn engine webhook cannot be deleted if it is associated with an Engine. You need to remove the engine webhook association from the Engine, and then you can delete the engine webhook.
\nTesting
\nIn the Actions column, you can click on the \"Gear\" icon to open the Engine Webhook Test window. Click the \"Test\" button to send a \"Ping\" action to the remote engine webhook server. Give it about one minute to send the engine webhook. If the engine webhook server responds to the Ping action, the Status will update to be \"verified\".
","rawMarkdownBody":"\n# Engine Webhooks\n\n## General {#general}\n\nThe Engine Webhooks tab in the [User Account](https://polyswarm.network/account/webhooks) or [Team Account](https://polyswarm.network/settings/team/webhooks) Settings of a PolySwarm UI Account allows you to manage engine webhooks used by your Account. In a Team Account, a User must have the Team Admin or Microengine Admin role to view and use the Engine Webhooks tab.\n\n### HMAC Secret\nThe engine webhook's HMAC Secret is used to allow the remote web service to verify that the engine webhook call was made by the PolySwarm Marketplace. All engine webhook calls are signed using the HMAC Secret, and can thus be verified by the recipient. In the Engine Webhooks tab, the HMAC Secret is hidden by default. You can click the \"Eye\" icon to view it or click the \"Copy\" icon to copy it to your clipboard.\n\n### Rate Limit\nThe rate limit is the number of engine webhook messages your engine webhook URL can process in one day (24hr period). This is the mechanism that you can use to control how many bounties your Engine receives in a day.\n\n### Status\nAn engine webhook's Status will be in one of the following states:\n\n* Pending - The engine webhook has been created, but has not been tested.\n* Verified - The engine webhook has been tested and the remote service responded correctly.\n* Failed - The engine webhook was Verified, but the remote service is no longer responding. If an engine webhook is in the Failed state, it needs to be Tested again to become Verified.\n\n### URL\nThe engine webhook URL must be the full URI that your web server is listening on to receive an engine webhook.\nIt must use HTTPS.\nOften it will be something like: \"https://example.com:1234/my/api/\"\n\n## Creating {#creating}\nTo create your first engine webhook, click the \"Create webhook\" button to open the engine webhook creation window. If you have one or more existing engine webhooks, you can click the \"+\" button to create another one.\n\nIn the Create Engine Webhook window, enter the engine webhook URL and its Rate Limit. Then click Save.\n\n## Deleting {#deleting}\nTo delete an engine webhook, click the \"Trash\" icon in the Actions column.\n\nAn engine webhook cannot be deleted if it is associated with an Engine. You need to remove the engine webhook association from the Engine, and then you can delete the engine webhook.\n\n## Testing {#testing}\nIn the Actions column, you can click on the \"Gear\" icon to open the Engine Webhook Test window. Click the \"Test\" button to send a \"Ping\" action to the remote engine webhook server. Give it about one minute to send the engine webhook. If the engine webhook server responds to the Ping action, the Status will update to be \"verified\".\n\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/getting-started/getting-started.md","frontmatter":{"title":"Overview","excerpt":"A simple end-to-end view of how to go from idea to a verified Engine in production."},"html":"PolySwarm Engine Overview
\nThank you for your interest in creating an Engine for PolySwarm!
\nPolySwarm Engines let you plug your detection capability into a live threat intelligence marketplace where real users submit suspicious artifacts (files, URLs, IPs, domains) and receive verdicts to support investigations and strengthen their cyber posture.
\nAs an Engine partner, you contribute verdict signals by analyzing artifacts and returning assertions, then you are incentivised through rewards when your results align with confirmed ground truth.
\nThis section is your starting point, it explains the Engine journey end to end, what you need to build, and how to participate safely and reliably in the marketplace.
\nHigh-level flow, proposal to verified Engine
\nThis is the end-to-end path for getting an Engine live on the PolySwarm Marketplace.
\n- \n
- Submit an Engine proposal \n
- PolySwarm review \n
- Onboarding \n
- Provisioning \n
- Integration and development testing \n
- Test in the Development Community \n
- Request verification \n
- Go live in production \n
- Operate and optimise \n
Scanning an Artifact
\nScanning is one of the primary functions of PolySwarm.\nWhen an Artifact is submitted, our network of engines will analyze that artifact for maliciousness and provide threat intelligence based on that analysis.
\nOn the Scan page on PolySwarm UI, we support scanning of multiple types of Artifacts, currently including: Files, URLs, domains, and IP addresses.
\n\nScan a File
\nTo scan a file, either drag and drop the file onto the Drag-and-Drop image, or click the \"Select File\" button to open a file chooser window that enables you to select a file from your local drive.
\n![\"Scan](\"/images/ui/ui_scan.png\")
Once the file is submitted, the Scan Results page will show the processing status, scan results, and metadata information.
\nScan a URL, Domain, QR Code, or IP Address
\nTo scan a URL, domain, or IP address, enter it into the text box below the “Select File” button. Press the “Enter” key to submit that Artifact.
\nTo scan a QR Code and have PolySwarm extract and scan the url from that image, use the 'qr code' button beside the magnify glass icon.\nPolySwarm supports any bitmap file type (not a vector image like SVG), complete list is below.
\n- \n
- \n
Supported Bitmap Image File Types:
\n- \n
- JPEG / JPG (.jpeg, .jpg) \n
- PNG (.png) \n
- BMP (.bmp) \n
- GIF (.gif) \n
- TIFF (.tif, .tiff) \n
- WEBP (.webp) \n
- \n
- \n
- PPM / PGM / PBM / PNM (.ppm, .pgm, .pbm, .pnm) – Netpbm formats \n
\n - TGA (.tga) – Truevision TGA \n
- ICO (.ico) – Icon files \n
- PCX (.pcx) \n
- DDS (.dds) – DirectDraw Surface \n
- IM – Format used by PIL \n
- SGI (.sgi, .rgb) – Silicon Graphics \n
\n - \n
Not Supported (Vector or Non-Bitmap):
\n- \n
- SVG (.svg) – vector-based, not supported by Pillow \n
- PDF (unless converted to bitmap) \n
- EPS (requires Ghostscript and not always reliable) \n
\n
Once the Artifact is submitted, the Scan Results page will show the processing status, scan results, and metadata information.
\n![\"Scan](\"/images/ui/ui_scan_url_domain_qr.png\")
Scan Results Page
\nThis Scan Results Summary page displays the latest scan result data for an artifact, along with the metadata from our static analysis tools.
\nThe page can be accessed from Searching and Scanning functions in the UI as well as the Latest Scan Results button on the Sandbox Summary Page for the Artifact.
To view the latest Sandbox results page for this Artifact you can use the Latest Sandbox Results button in the top right, and you can use the Latest Scan Results button to navigate back to the Scan result page.
Summary pane
\nThe summary pane on the left provides a quick overview of the analysis.
\n![\"Scan](\"/images/ui/ui_scan_summar.png\")
This sections provides access to some key information:
\n- \n
- PolyScore, which provides the probability that an artifact is malicious. Red is most likely malicious. Yellow is potentially malicious. Green is likely not malicious. \n
- Detections by all engines, which tells you how many engines chose to process the artifact and of those, how many found the artifact to be malicious. \n
- Detection summary is the name of the Artifact if the Artifact is a file. If the Artifact is a URL, domain, or IP address it will show that and in some cases the file name will be the SHA-256 hash. \n
- Below the Artifact name is the number of bytes in the Artifact. \n
- PolyUnite family name A common family name from all engines, Sandboxing and Analyst tags will be displayed. \n
- SHA-256 hash of the Artifact. In the case of a URL, domain, or IP address, the SHA-256 is a hash of the bytes of that string. \n
- Scan ID is the ID Number for the Specific scan being viewed. \n
Below the Summary Pane is the Action pane with several buttons:
\n![\"Scan](\"/images/ui/ui_scan_summary_buttons.png\")
| Button | \nWhat is it for? | \n
|---|---|
| Rescan | \nRe-submit the Artifact to the marketplace for analysis. This can be useful if the last time it was analyzed was a long time in the past. | \n
| Download | \nDownload the Artifact to your local host as an encrypted .zip file. In the case of a URL, domain, or IP address, this will download a text file with that string as the only content. | \n
| Share | \nShare a link to these scan results on social media. | \n
| Sandboxing | \nSubmit a task to process the artifact in the sandboxes. This can take up to 1 hour. You'll see the results in the Sandbox tab when it is finished. | \n
| Pivot | \nEnable/disable the Pivoting feature. | \n
| Generate Report | \nGenerates either a PDF or HTML report on demand, you will be able to choose sections to include. | \n
Detections tab
\nA list of all Engines in the PolySwarm marketplace and their detection results.\nThis list is sorted alphabetically in two groups.
\n![\"Scan](\"/images/ui/ui_scan_engines.png\")
The first set are the engines that chose to process the Artifact and their detection results.\nBelow the engine name is the Bid value.\nThis is the amount of NCT that they Bid with their assertion.\nTo the right of the name is either a Green icon with a check mark or a Red icon with an “!” exclamation mark.\nGreen indicates non-malicious and Red indicates malicious.
\nThe second set are the engines that chose NOT to process the Artifact.\nNext to those engines we display a grey “?” questionmark to indicate they did not provide any information on this Artifact.
\n![\"Scan](\"/images/ui/ui_scan_engines_not.png\")
Clicking on the name of an engine will display additional metadata about the engine to include things like: Engine Name, Engine ID, architecture, operating system, and version information.
\nFile Details tab
\nThis tab is only available when scanning a file.\nThis tab displays output from the collection of metadata analysis tools that PolySwarm uses to process each Artifact.\nThe page is separated into sections, one section per tool.\nSome tools only have results for specific file types, so different file types will have more or less tool sections displayed.
\nURL Details tab
\nThis tab is only available when scanning a URL, domain, or IP address.\nThis tab displays output from the collection of metadata analysis tools that PolySwarm uses to process each Artifact.\nCurrently, for URLs, domains, and IP addresses we only use the “Artifact Attributes” tool.
\nJSON Tab
\nThis tab gives you the entire scan result JSON object in a browsable and searchable display.\nYou can use the search fields at the top to find specific keys and values in the JSON object.\nOr, you can expand/collapse parts of the JSON object to do your own manual searching.
\nShortcut Boxes
\nOn the File Details, Network, and Sandbox tabs, at the top, you'll see several boxes with letters in them.\nThese are shortcut boxes, where the letter is the first letter of the name of a metadata tool.\nIf the box is highlighted, there is metadata available from that tool.\nClicking on the box will jump you to the results for that tool.
\nPivoting
\nPivoting is available on the Scan Results page.\nPivoting allows you use attributes of on Artifact to find other Artifacts with the same attributes.\nTo use Pivoting, first you click the Pivot button to enable Pivoting.\nWhen you enable Pivoting, several things on the page will change:
\n- \n
- A subset of the field names will become highlighted. The fields that are highlighted are the only ones that support pivoting. \n
- a Pivot Search box will appear at the top of the right side. \n
Pivot Search
\nTo create a Pivot Search, find the highlighted fields of interest. Hover your mouse over the value in a field and click the \"+\" sign to add that value to the Pivot Search.
\n![\"Scan](\"/images/ui/ui_scan_pivot_select.png\")
Once the value in a field has been added to the Pivot Search, hovering over the value will display a \"-\" sign.\nYou can click the \"-\" to remove that value from the Pivot Search.\nSome fields have a list of values, and each value will have a separate \"+\" or \"-\" sign.
\nOnce you've selected the values you want in your search, review and update the Start and End days for the Pivot Search.\nThe Start day has to be on or before the End day.\nThe values you select for the Start and End day are cached in your browser.
\n![\"Scan](\"/images/ui/ui_scan_pivot_search.png\")
Finally, click the Arrow icon to generate the Metadata Search query.\nThis will open a new tab and take you to the Metadata Search page with the query prepared for you.\nYou can manually tweak the query, or click the search button to run the Metadata Search query.
\nFor each artifact where you view the Scan Result page, you can do a Pivot Search.\nAnd from the results of each Search, you can view the Scan Result page of an artifact and continue to Pivot Search.
\n\n
","rawMarkdownBody":"\n# Scanning an Artifact\n\nScanning is one of the primary functions of PolySwarm.\nWhen an Artifact is submitted, our network of engines will analyze that artifact for maliciousness and provide threat intelligence based on that analysis.\n\nOn the [Scan](https://polyswarm.network/scan) page on PolySwarm UI, we support scanning of multiple types of Artifacts, currently including: Files, URLs, domains, and IP addresses.\n\n\n\n## Scan a File {#scan-a-file}\n\nTo scan a file, either drag and drop the file onto the Drag-and-Drop image, or click the \"Select File\" button to open a file chooser window that enables you to select a file from your local drive.\n\n\n\nIt is best to keep the Pivot Search to 5 terms or fewer.\nRunning a Metadata Search query with too many terms can cause it to timeout. If that happens, remove some terms and try again.
\n
\n\nOnce the file is submitted, the Scan Results page will show the processing status, scan results, and metadata information.\n\n## Scan a URL, Domain, QR Code, or IP Address {#scan-url-domain-or-ip}\n\nTo scan a URL, domain, or IP address, enter it into the text box below the “Select File” button. Press the “Enter” key to submit that Artifact.\n\nTo scan a QR Code and have PolySwarm extract and scan the url from that image, use the 'qr code' button beside the magnify glass icon. \nPolySwarm supports any bitmap file type (not a vector image like SVG), complete list is below. \n\n* Supported Bitmap Image File Types:\n * JPEG / JPG (.jpeg, .jpg)\n * PNG (.png)\n * BMP (.bmp)\n * GIF (.gif)\n * TIFF (.tif, .tiff)\n * WEBP (.webp)\n * * PPM / PGM / PBM / PNM (.ppm, .pgm, .pbm, .pnm) – Netpbm formats\n * TGA (.tga) – Truevision TGA\n * ICO (.ico) – Icon files\n * PCX (.pcx)\n * DDS (.dds) – DirectDraw Surface\n * IM – Format used by PIL\n * SGI (.sgi, .rgb) – Silicon Graphics\n* Not Supported (Vector or Non-Bitmap):\n * SVG (.svg) – vector-based, not supported by Pillow\n * PDF (unless converted to bitmap)\n * EPS (requires Ghostscript and not always reliable)\n\nOnce the Artifact is submitted, the Scan Results page will show the processing status, scan results, and metadata information.\n\n\n\n## Scan Results Page\n\nThis Scan Results Summary page displays the latest scan result data for an artifact, along with the metadata from our static analysis tools.\n\nThe page can be accessed from Searching and Scanning functions in the UI as well as the `Latest Scan Results` button on the Sandbox Summary Page for the Artifact.\n\nTo view the latest **Sandbox results** page for this Artifact you can use the `Latest Sandbox Results` button in the top right, and you can use the `Latest Scan Results` button to navigate back to the Scan result page.\n\n### Summary pane\n\nThe summary pane on the left provides a quick overview of the analysis.\n\n\n\nThis sections provides access to some key information:\n\n- **PolyScore**, which provides the probability that an artifact is malicious. Red is most likely malicious. Yellow is potentially malicious. Green is likely not malicious.\n- **Detections** by all engines, which tells you how many engines chose to process the artifact and of those, how many found the artifact to be malicious.\n- **Detection summary** is the name of the Artifact if the Artifact is a file. If the Artifact is a URL, domain, or IP address it will show that and in some cases the file name will be the SHA-256 hash.\n- Below the Artifact name is the number of bytes in the Artifact.\n- **PolyUnite family name** A common family name from all engines, Sandboxing and Analyst tags will be displayed.\n- **SHA-256 hash** of the Artifact. In the case of a URL, domain, or IP address, the SHA-256 is a hash of the bytes of that string.\n- **Scan ID** is the ID Number for the Specific scan being viewed.\n\nBelow the Summary Pane is the Action pane with several buttons:\n\n\n\n| Button | What is it for? |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Rescan | Re-submit the Artifact to the marketplace for analysis. This can be useful if the last time it was analyzed was a long time in the past. |\n| Download | Download the Artifact to your local host as an encrypted .zip file. In the case of a URL, domain, or IP address, this will download a text file with that string as the only content. |\n| Share | Share a link to these scan results on social media. |\n| Sandboxing | Submit a task to process the artifact in the sandboxes. This can take up to 1 hour. You'll see the results in the Sandbox tab when it is finished. |\n| Pivot | Enable/disable the Pivoting feature. |\n| Generate Report | Generates either a PDF or HTML report on demand, you will be able to choose sections to include. |\n\n### Detections tab\n\nA list of all Engines in the PolySwarm marketplace and their detection results.\nThis list is sorted alphabetically in two groups.\n\n\n\nThe first set are the engines that chose to process the Artifact and their detection results.\nBelow the engine name is the Bid value.\nThis is the amount of NCT that they Bid with their assertion.\nTo the right of the name is either a Green icon with a check mark or a Red icon with an “!” exclamation mark.\nGreen indicates non-malicious and Red indicates malicious.\n\nThe second set are the engines that chose NOT to process the Artifact.\nNext to those engines we display a grey “?” questionmark to indicate they did not provide any information on this Artifact.\n\n\n\nClicking on the name of an engine will display additional metadata about the engine to include things like: Engine Name, Engine ID, architecture, operating system, and version information.\n\n### File Details tab\n\nThis tab is only available when scanning a file.\nThis tab displays output from the collection of metadata analysis tools that PolySwarm uses to process each Artifact.\nThe page is separated into sections, one section per tool.\nSome tools only have results for specific file types, so different file types will have more or less tool sections displayed.\n\n### URL Details tab\n\nThis tab is only available when scanning a URL, domain, or IP address.\nThis tab displays output from the collection of metadata analysis tools that PolySwarm uses to process each Artifact.\nCurrently, for URLs, domains, and IP addresses we only use the “Artifact Attributes” tool.\n\n### JSON Tab\n\nThis tab gives you the entire scan result JSON object in a browsable and searchable display.\nYou can use the search fields at the top to find specific keys and values in the JSON object.\nOr, you can expand/collapse parts of the JSON object to do your own manual searching.\n\n### Shortcut Boxes\n\nOn the File Details, Network, and Sandbox tabs, at the top, you'll see several boxes with letters in them.\nThese are shortcut boxes, where the letter is the first letter of the name of a metadata tool.\nIf the box is highlighted, there is metadata available from that tool.\nClicking on the box will jump you to the results for that tool.\n\n### Pivoting\n\nPivoting is available on the Scan Results page.\nPivoting allows you use attributes of on Artifact to find other Artifacts with the same attributes.\nTo use Pivoting, first you click the Pivot button to enable Pivoting.\nWhen you enable Pivoting, several things on the page will change:\n\n- A subset of the field names will become highlighted. The fields that are highlighted are the only ones that support pivoting.\n- a Pivot Search box will appear at the top of the right side.\n\n#### Pivot Search\n\nTo create a Pivot Search, find the highlighted fields of interest. Hover your mouse over the value in a field and click the \"+\" sign to add that value to the Pivot Search.\n\n\n\nOnce the value in a field has been added to the Pivot Search, hovering over the value will display a \"-\" sign.\nYou can click the \"-\" to remove that value from the Pivot Search.\nSome fields have a list of values, and each value will have a separate \"+\" or \"-\" sign.\n\nOnce you've selected the values you want in your search, review and update the **Start and End days** for the Pivot Search.\nThe Start day has to be on or before the End day.\nThe values you select for the Start and End day are cached in your browser.\n\n\n\nFinally, click the **Arrow icon** to generate the Metadata Search query.\nThis will open a new tab and take you to the Metadata Search page with the query prepared for you.\nYou can manually tweak the query, or click the search button to run the Metadata Search query.\n\nFor each artifact where you view the Scan Result page, you can do a Pivot Search.\nAnd from the results of each Search, you can view the Scan Result page of an artifact and continue to Pivot Search.\n\n\n\n> It is best to keep the Pivot Search to 5 terms or fewer.\n> Running a Metadata Search query with too many terms can cause it to timeout. If that happens, remove some terms and try again.\n\n
\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/polyswarm-ui/settings.md","frontmatter":{"title":"Settings","excerpt":"PolySwarm offers access to Settings..."},"html":"Settings UI
\nThis section will review the Settings Page contents and what items are available for each type of account, each section is available for both types of accounts unless highlighted.
\nIn the Context Menu in the upper right corner, choose the Settings option to access the Account Settings for the active Account Context.
\nWhen viewing the Account Settings, the left area has your username, name, email address, and account number readily displayed in the first box.\nThe second box indicates your current subscription plan, and the number of days remaining in your monthly usage period.
\n\nProfile
\n\n
\n\n\nThis feature is only available for individual \"User Accounts\".
\n
The Profile tab allows you to change your username, name, company, and password.\nYou cannot change your email address.\nThe username is what gets displayed to other users as the owner of an engine, if you claim an engine.
\nMembers
\n\n
\n\n\nThis feature is only available for \"Team Accounts\".
\n
The Members tab allows Team Owners and Team Admins to manage the members of the team.\nWhen the Team Account is created, the only member is the User Account who created the team.\nThe User who created the team has the role of Team Owner by default.
\nClick the “+” plus sign icon to add User Accounts to the Team Account.\nWhen inviting a user, you must specify both a name and email address.\nAdding a User Account will send an invitation to that User Account to join the Team Account.
\n![\"Settings](\"/images/ui/ui_settings_members.png\")
Click the Edit icon (Pencil) to edit a User, including modifying their Team Roles.
\nMembers can be removed from the team, but there must always be at least one Team Owner.
\nMembers - Roles
\nRole-based access control defines a User's permissions to view or edit various tabs and content.\nThis includes the Team Account Settings tabs and content as well as other content outside of the settings.\nThe below highlights what access each kind of Role has access too and the functionality available.
\n\n \n\n
\n
\n\n Advanced Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
\n
\n \n\n
\n
\n\n API Keys Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \nX | \nX | \nX | \nX | \nX | \nX | \nX | \n
| Add | \nX | \nX | \nX | \nX | \nX | \nX | \nX | \n
| Delete | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Integrations Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Add | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Delete | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Invitations Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Add | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Delete | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Resend | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Members Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \nX | \nX | \nX | \nX | \nX | \nX | \nX | \n
| Add | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Edit | \n- | \n- | \n- | \n- | \n- | \nX | \nX | \n
| Delete | \nX | \nX | \nX | \nX | \nX | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Usage Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \nX | \nX | \nX | \nX | \nX | \nX | \nX | \n
| Edit | \n- | \nX | \n- | \n- | \n- | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Wallets Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \n- | \n- | \n- | \n- | \nX | \nX | \nX | \n
| Edit | \n- | \n- | \n- | \n- | \nX | \nX | \nX | \n
\n
\n \n\n
\n
\n\n Engine Webhooks Tab\n
\n| \n | Team Member | \nBilling Admin | \nCommunity Admin | \nMicroengine Admin | \nWallet Admin | \nTeam Admin | \nTeam Owner | \n
|---|---|---|---|---|---|---|---|
| View | \n- | \n- | \n- | \nX | \n- | \nX | \nX | \n
| Add | \n- | \n- | \n- | \nX | \n- | \nX | \nX | \n
| Delete | \n- | \n- | \n- | \nX | \n- | \nX | \nX | \n
Invitations
\n\n
\n\n\nThis feature is only available for \"Team Accounts\".
\n
The Invitations tab allows Team Owners and Team Admins to manage Team member invitations.\nIt will list all currently active team invitations and will allow the Team Owners and Team Admins to delete or resend invitations.\nAll invited Team Members are set with the Team Member role by default.\nAdding additional Team Roles is done via the Members tab after they have accepted the Team Invitation.
\nAPI Keys
\nThe API Keys tab allows User/Team Account members to manage their own API Keys.
\nAPI Keys allow PolySwarm to authenticate and associate your usage activity with the related account.\nAll API Keys in a Team account share the Subscription Plan for that Team account.
\nThe \"Personal Account\" section has your API Keys for your User Account.\nThe \"Team Account\" section has your API keys for all Team Accounts where your User Account is a member.\nIn a Team account, each Team Member has their own separate API Keys and each Team Member can view/delete their own API Keys.\nIf you are a member of one or more Team Accounts, you will see API Keys listed for each Team Account.\nAll of these API Keys are unique to you.\nThey are not visible or shared with other Users.
\nYou must have at least one API Key in each account at all times, so we automatically create the first API Key in each account.\nYou can create more API Keys, and you can delete any API Key, but we do not permit deletion of the API Key if it is the only one for that account.
\nWhen you create an API key, you can give it a Name and Expiration Date.\nA Name is now required and the Expiration Date defaults to never expires.\nWhen an API Key expires, it is not deleted, but it will no longer be accepted as valid.\nYou will get an email notification when one of your API keys is expiring.
\nIntegrations
\n\n
\n\n\nThis feature is only available for \"Team Accounts\".
\n
The Integrations tab allows Team Owners and Team Admins to manage their Integration API Keys.\nThese are special API keys that are shared by ALL Team Members with the Team Owner or Team Admin role.\nWhen creating an Integration, you can specify a Name and Expiration Date.
\nJust like regular API Keys, by default, the Name is blank, and Expiration Date is never expires.\nAnd when the key does expire, you will be notified by email and the key will no longer be valid to use.
\nEngine Webhooks
\nThe Engine Webhooks tab in the User Account or Team Account Settings of a PolySwarm UI Account allows you to manage engine webhooks used by your Account. In a Team Account, a User must have the Team Admin or Microengine Admin role to view and use the Engine Webhooks tab.
\nTo create your first engine webhook, click the “Create webhook” button to open the engine webhook creation window. If you have one or more existing engine webhooks, you can click the “+” button to create another one.
\nIn the Create Engine Webhook window, enter the engine webhook URL and its Rate Limit. Then click Save.
\nOnce the engine webhook has been created you can access a number of features listed below.
\n![\"Settings](\"/images/ui/ui_settings_webhook.png\")
- \n
- URL: The engine webhook URL must be the full URI that your web server is listening on to receive an engine webhook.\nIt must use HTTPS. Often it will be something like: “https://example.com:1234/my/api/” \n
- \n
Status: An engine webhook’s Status will be in one of the following states:
\n- \n
Pending- The engine webhook has been created, but has not been tested. \nVerified- The engine webhook has been tested and the remote service responded correctly. \nFailed- The engine webhook was Verified, but the remote service is no longer responding. If an engine webhook is in the Failed state, it needs to be Tested again to become Verified. \n
\n - Rate Limit: The rate limit is the number of engine webhook messages your engine webhook URL can process in one day (24hr period). This is the mechanism that you can use to control how many bounties your Engine receives in a day. \n
- Engine Webhook HMAC Secret: The engine webhook’s HMAC Secret is used to allow the remote web service to verify that the engine webhook call was made by the PolySwarm Marketplace. All engine webhook calls are signed using the HMAC Secret, and can thus be verified by the recipient. In the Engine Webhooks tab, the HMAC Secret is hidden by default. You can click the “Eye” icon to view it or click the “Copy” icon to copy it to your clipboard. \n
- Testing: In the Actions column, you can click on the “Gear” icon to open the Engine Webhook Test window. Click the “Test” button to send a “Ping” action to the remote engine webhook server. Give it about one minute to send the engine webhook. If the engine webhook server responds to the Ping action, the Status will update to be “verified”. \n
- Deleting: To delete an engine webhook, click the “Trash” icon in the Actions column. An engine webhook cannot be deleted if it is associated with an Engine. You need to remove the engine webhook association from the Engine, and then you can delete the engine webhook. \n
Rewards
\nThe Rewards tab allows you to manage your participation in the NectarNet Rewards program. This program allows users to share information automatically through browsing the internet and get paid in NCT coin.\nYou can view your rewards summary, and you can Redeem your Rewards.
\nWallet
\nThe Wallets tab allows team members with the Team Admin or Wallet Admin roles to manage your Wallets, you can also manage individual wallets if logged in as a \"User\".
\nIn a Team Account, a User must have the Team Admin or Wallet Admin role to view and use the Wallets tab.\nAll Users must enable 2-factor authentication (2FA) on their User Account before they can view the Wallets tab content.
\nRewards Wallets
\nThe section named \"Rewards Wallets\" is the Wallets used by PolySwarm Rewards programs.\nOnce a User has opted into a Rewards program, there will be one row in this table for their Rewards wallet.
\n- \n
- Wallet - The name of the Rewards program \n
- Balance (NCT) - The current NCT balance of the Wallet \n
- Deposit Address - Rewards wallets do not currently support deposits. \n
- Withdrawal Address - An external ETH/NCT address where NCT tokens are sent when withdrawn from this Wallet (Redeemed). \n
- Withdrawal Limit - Max amount of NCT that can be withdrawn per day from this Wallet. \n
In the Actions menu, there will be one or more options depending on the status of your wallet.
\n- \n
- Configure Withdrawals - This is where you define your
Withdrawal Addressand yourWithdrawal Limit. This is the first step you must do. \n - Withdrawals - Once you have defined a
Withdrawal Addressthis option will be active. Use this to withdraw NCT from your Rewards wallet and transfer the NCT to your personal ETH/NCT wallet. Withdrawals from a Rewards wallet can be initiated using the Action menu, or by clicking the Redeem button on the Rewards tab. \n
Below the name of the wallet is a Transactions table.\nClick the down arrow to view the set of Deposit and Withdrawal transactions for your Rewards wallet.\nNOTE: The Rewards payouts are not included in this table.
\nEngine Wallets
\nThe section named \"Engine Wallets\" are the Wallets used by Engines (Microengines and Arbiters).\nThere is a separate row in the table for each Engine owned by an Account.
\n- \n
- Wallet - The name of the Engine \n
- Balance (NCT) - The current NCT balance of the Engine's Wallet \n
- Deposit Address - The Address where you can deposit NCT to add to your Engine's Wallet. If your Engine has not been Verified before, this will say \"Pending Engine Verification\". \n
In the near future, we will be adding functionality to support making withdrawals from an Engine Wallet.
\nUsage
\nThe Usage tab displays the list of features available in the current Subscription Plan.
\nThe Daily API Request Limit is the maximum number of every total feature usage allowed per 24hrs.
\nNext to each feature is the remaining number of times out of the total number of times that feature can be used, per quota reset period.
\nExample: Hash Searches 6,692,085 of 7,000,000 /mo, means you have 6,692,085 times left to use Hash Searches in that Month and the feature has been used 307,915 times.
![\"Settings](\"/images/ui/ui_settings_usage.png\")
Activity
\nThe Activity tab provides access to functionality to report on events from members of your team.
\n\n\nNote: Team Admin and Team Owner accounts will be able to view events from all team members, non team admin accounts can only see events from their own account.
\n
This page will display the following items in the table:
\n| Item | \nFunctionality | \n
|---|---|
| Timestamp | \nA time stamp showing when the event took place. | \n
| Event Type | \nCurrently able to view Events for Sandbox Submissions (sandbox_submit, sandbox_create) and Scan Submissions (scan_submit, scan_create). | \n
| User | \nThe Name and Email for the account that triggered the Event. | \n
| Metadata | \nAccompanying Metadata to the Event Type. This will vary for each Event Type but can contain information like the filename, full user name and instance ids. Clicking on the metadata will provide a popup with the full content. | \n
The Activity Page can be filtered based on the below items.
\n- \n
- Event Type - Filter on Event Type i.e. Scan Create \n
- User - Filter on User Events \n
- Timestamp - Period to Filter on Events \n
- Metadata - Various Metadata to filter on, for example Filename, Hash, Instance ID \n
Advanced
\nThe Advanced tab provides access to functionality that is less often accessed.
\nSecure Authentication
\nEnabling Secure Authentication is highly recommended, especially when an email address and password are used to log in.
\nThis section will change depending on if the access is a User Account or a Team Account.
\nIn a user context: The button will say \"Enable Two-Factor Authentication (2FA) for Secure Login.\" This encourages individual users to activate 2FA to enhance the security of their login process.
\n![\"User](\"/images/ui/ui_auth_user.png\")
In a team context: The button will say \"Require 2FA for all Team Members.\" This emphasizes the importance of implementing 2FA for every member of the team, making it mandatory for enhanced security across the entire team.
\n![\"Team](\"/images/ui/ui_auth_team.png\")
For Users who have Engines or Wallets associated with their User Account, Enabled Secure Authentication is required.
\nRestrict Access To Members Tab
\nIf turned on, only Team Admins or Team Owners can see the Members tab.
\nSandbox Internet Access
\nThis section allows users the ability to define if the 'internet' is turned on or off by default when sandboxing in the specific communities.
\n![\"Sandbox](\"/images/ui/ui_sandbox_inter.png\")
Artifact Download Encryption
\nThe default password when downloading files via the UI is infected, this section allows this to be override with a password of you choice. This change will affect all downloads for all team members.
![\"Change](\"/images/ui/ui_password_team.png\")
Notifications
\nEnabling Notifications will provide email alerts for the individual user when a Sandbox Task has ended. Enabling or disabling this will effect the single user profile only, not the whole team.
\nFurther to this, Email Notifications will be sent out when each feature in your plan gets to 90% used in your quota window. The User must have the Team Owner or Billing Admin role assigned to them to receive these.
\n![\"Email](\"/images/ui/ui_notification.png\")
Delete Account
\n\n
\n\n\nThis feature is only available for individual \"User Accounts\".
\n
This feature will will permanently delete the user account.\nThere are some things to be aware of when deleting an account.
\n- \n
- If the user is the only Team Admin on a team, they cannot delete their account. The team has to first assign another user as a Team Admin. \n
- If the user has a claimed engine, they cannot delete their account. The user has to first delete their engine claim. \n
- If the user has an active Live Hunt, it will be automatically stopped and deleted. \n
- All Live and Historical Hunting instances, results, and rules will be deleted. \n
- All user account information will be deleted. \n
\n
\n\n\nWarning: There is no way to undo an account deletion once deleted!
\n
Configure Report Template
\nProvides the ability to change the template used for html and pdf reports. Accounts with the Team Owner or Team Admin role can change the template. The template they set will apply to the generation of all reports from all members of the team.
\n| Item | \nFunctionality | \n
|---|---|
| Logo | \nUpload a png or jpeg for the logo, the max file size is 40KB and dimensions are 960x960. | \n
| Primary Color | \nSelect the primary color from the color picker, or use the hex code. applies to thehtml and pdf report. | \n
| Footer Text | \nText displayed at the bottom of each page. | \n
| Disclaimer Text | \nText displayed on the last page. | \n
![\"Team](\"/images/ui/ui_settings_report_template.png\")
Private Mode Theme
\nIf you have a Private Community, only Accounts with the Team Owner or Team Admin role can change the Theme. The Theme they set will apply to all members of the team.
\n![\"Team](\"/images/ui/ui_settings_advance_theme.png\")
\n\n> This feature is only available for individual \"**User Accounts**\".\n\n
\n\nThe [Profile](https://polyswarm.network/account/profile) tab allows you to change your username, name, company, and password.\nYou cannot change your email address.\nThe username is what gets displayed to other users as the owner of an engine, if you claim an engine.\n\n## Members {#members}\n\n\n\n> This feature is only available for \"**Team Accounts**\".\n\n
\n\nThe Members tab allows Team Owners and Team Admins to manage the members of the team.\nWhen the Team Account is created, the only member is the User Account who created the team.\nThe User who created the team has the role of Team Owner by default.\n\nClick the **“+”** plus sign icon to add User Accounts to the Team Account.\nWhen inviting a user, you must specify both a name and email address.\nAdding a User Account will send an invitation to that User Account to join the Team Account.\n\n\n\nClick the Edit icon **(Pencil)** to edit a User, including modifying their Team Roles.\n\nMembers can be removed from the team, but there must always be at least one Team Owner.\n\n#### Members - Roles\n\n**Role-based** access control defines a User's permissions to view or edit various tabs and content.\nThis includes the Team Account Settings tabs and content as well as other content outside of the settings.\nThe below highlights what access each kind of Role has access too and the functionality available.\n\n\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n\n
\n\n\n Advanced Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Add | X | X | X | X | X | X | X |\n| Delete | - | - | - | - | - | X | X |\n\n
\n\n\n API Keys Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Add | X | X | X | X | X | X | X |\n| Delete | - | - | - | - | - | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n| Add | - | - | - | - | - | X | X |\n| Delete | - | - | - | - | - | X | X |\n\n
\n\n\n Integrations Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n| Add | - | - | - | - | - | X | X |\n| Delete | - | - | - | - | - | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n| Add | - | - | - | - | - | X | X |\n| Delete | - | - | - | - | - | X | X |\n| Resend | - | - | - | - | - | X | X |\n\n
\n\n\n Invitations Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | - | X | X |\n| Add | - | - | - | - | - | X | X |\n| Delete | - | - | - | - | - | X | X |\n| Resend | - | - | - | - | - | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Add | - | - | - | - | - | X | X |\n| Edit | - | - | - | - | - | X | X |\n| Delete | X | X | X | X | X | X | X |\n\n
\n\n\n Members Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Add | - | - | - | - | - | X | X |\n| Edit | - | - | - | - | - | X | X |\n| Delete | X | X | X | X | X | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Edit | - | X | - | - | - | X | X |\n\n
\n\n\n Usage Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | X | X | X | X | X | X | X |\n| Edit | - | X | - | - | - | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | X | X | X |\n| Edit | - | - | - | - | X | X | X |\n\n
\n\n\n Wallets Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ---- | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | - | X | X | X |\n| Edit | - | - | - | - | X | X | X |\n\n
\n\n
\n
Member | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | X | - | X | X |\n| Add | - | - | - | X | - | X | X |\n| Delete | - | - | - | X | - | X | X |\n\n
\n\n## Invitations {#invitations}\n\n\n Engine Webhooks Tab\n
\n\n| | TeamMember | Billing
Admin | Community
Admin | Microengine
Admin | Wallet
Admin | Team
Admin | Team
Owner |\n| ------ | -------------- | ---------------- | ------------------ | -------------------- | --------------- | ------------- | ------------- |\n| View | - | - | - | X | - | X | X |\n| Add | - | - | - | X | - | X | X |\n| Delete | - | - | - | X | - | X | X |\n\n
\n\n> This feature is only available for \"**Team Accounts**\".\n\n
\n\nThe Invitations tab allows Team Owners and Team Admins to manage Team member invitations.\nIt will list all currently active team invitations and will allow the Team Owners and Team Admins to delete or resend invitations.\nAll invited Team Members are set with the Team Member role by default.\nAdding additional Team Roles is done via the Members tab after they have accepted the Team Invitation.\n\n## API Keys {#api-key}\n\nThe API Keys tab allows User/Team Account members to manage their own API Keys.\n\nAPI Keys allow PolySwarm to authenticate and associate your usage activity with the related account.\nAll API Keys in a Team account share the Subscription Plan for that Team account.\n\nThe \"Personal Account\" section has your API Keys for your User Account.\nThe \"Team Account\" section has your API keys for all Team Accounts where your User Account is a member.\nIn a Team account, each Team Member has their own separate API Keys and each Team Member can view/delete their own API Keys.\nIf you are a member of one or more Team Accounts, you will see API Keys listed for each Team Account.\nAll of these API Keys are unique to you.\nThey are not visible or shared with other Users.\n\nYou must have at least one API Key in each account at all times, so we automatically create the first API Key in each account.\nYou can create more API Keys, and you can delete any API Key, but we do not permit deletion of the API Key if it is the only one for that account.\n\nWhen you create an API key, you can give it a Name and Expiration Date.\nA Name is now required and the Expiration Date defaults to never expires.\nWhen an API Key expires, it is not deleted, but it will no longer be accepted as valid.\nYou will get an email notification when one of your API keys is expiring.\n\n## Integrations {#integrations}\n\n\n\n> This feature is only available for \"**Team Accounts**\".\n\n
\n\nThe Integrations tab allows Team Owners and Team Admins to manage their Integration API Keys.\nThese are special API keys that are shared by ALL Team Members with the Team Owner or Team Admin role.\nWhen creating an Integration, you can specify a Name and Expiration Date.\n\nJust like regular API Keys, by default, the Name is blank, and Expiration Date is never expires.\nAnd when the key does expire, you will be notified by email and the key will no longer be valid to use.\n\n## Engine Webhooks {#webhooks}\n\nThe Engine Webhooks tab in the [User Account](https://polyswarm.network/account/webhooks) or Team Account Settings of a PolySwarm UI Account allows you to manage engine webhooks used by your Account. In a Team Account, a User must have the Team Admin or Microengine Admin role to view and use the Engine Webhooks tab.\n\nTo create your first engine webhook, click the “Create webhook” button to open the engine webhook creation window. If you have one or more existing engine webhooks, you can click the “+” button to create another one.\n\nIn the Create Engine Webhook window, enter the engine webhook URL and its Rate Limit. Then click Save.\n\nOnce the engine webhook has been created you can access a number of features listed below.\n\n\n\n- **URL:** The engine webhook URL must be the full URI that your web server is listening on to receive an engine webhook.\n It must use HTTPS. Often it will be something like: “https://example.com:1234/my/api/”\n- **Status:** An engine webhook’s Status will be in one of the following states:\n - `Pending` - The engine webhook has been created, but has not been tested.\n - `Verified` - The engine webhook has been tested and the remote service responded correctly.\n - `Failed` - The engine webhook was Verified, but the remote service is no longer responding. If an engine webhook is in the Failed state, it needs to be Tested again to become Verified.\n- **Rate Limit:** The rate limit is the number of engine webhook messages your engine webhook URL can process in one day (24hr period). This is the mechanism that you can use to control how many bounties your Engine receives in a day.\n- **Engine Webhook HMAC Secret:** The engine webhook’s HMAC Secret is used to allow the remote web service to verify that the engine webhook call was made by the PolySwarm Marketplace. All engine webhook calls are signed using the HMAC Secret, and can thus be verified by the recipient. In the Engine Webhooks tab, the HMAC Secret is hidden by default. You can click the “Eye” icon to view it or click the “Copy” icon to copy it to your clipboard.\n- **Testing:** In the Actions column, you can click on the “Gear” icon to open the Engine Webhook Test window. Click the “Test” button to send a “Ping” action to the remote engine webhook server. Give it about one minute to send the engine webhook. If the engine webhook server responds to the Ping action, the Status will update to be “verified”.\n- **Deleting:** To delete an engine webhook, click the “Trash” icon in the Actions column. An engine webhook cannot be deleted if it is associated with an Engine. You need to remove the engine webhook association from the Engine, and then you can delete the engine webhook.\n\n## Rewards {#rewards}\n\nThe [Rewards](https://polyswarm.network/account/rewards) tab allows you to manage your participation in the NectarNet Rewards program. This program allows users to share information automatically through browsing the internet and get paid in NCT coin.\nYou can view your rewards summary, and you can Redeem your Rewards.\n\n## Wallet {#wallet}\n\nThe Wallets tab allows team members with the Team Admin or Wallet Admin roles to manage your Wallets, you can also manage individual wallets if logged in as a \"User\".\n\nIn a Team Account, a User must have the Team Admin or Wallet Admin role to view and use the Wallets tab.\nAll Users must [enable 2-factor authentication (2FA)](/customers/accounts#advanced) on their User Account before they can view the Wallets tab content.\n\n### Rewards Wallets\n\nThe section named \"Rewards Wallets\" is the Wallets used by [PolySwarm Rewards](/customers/rewards) programs.\nOnce a User has opted into a Rewards program, there will be one row in this table for their Rewards wallet.\n\n- Wallet - The name of the Rewards program\n- Balance (NCT) - The current NCT balance of the Wallet\n- Deposit Address - Rewards wallets do not currently support deposits.\n- Withdrawal Address - An external ETH/NCT address where NCT tokens are sent when withdrawn from this Wallet (Redeemed).\n- Withdrawal Limit - Max amount of NCT that can be withdrawn per day from this Wallet.\n\nIn the Actions menu, there will be one or more options depending on the status of your wallet.\n\n- Configure Withdrawals - This is where you define your `Withdrawal Address` and your `Withdrawal Limit`. This is the first step you must do.\n- Withdrawals - Once you have defined a `Withdrawal Address` this option will be active. Use this to withdraw NCT from your Rewards wallet and transfer the NCT to your personal ETH/NCT wallet. Withdrawals from a Rewards wallet can be initiated using the Action menu, or by clicking the Redeem button on the Rewards tab.\n\nBelow the name of the wallet is a Transactions table.\nClick the down arrow to view the set of Deposit and Withdrawal transactions for your Rewards wallet.\nNOTE: The Rewards payouts are not included in this table.\n\n### Engine Wallets\n\nThe section named \"Engine Wallets\" are the Wallets used by Engines (Microengines and Arbiters).\nThere is a separate row in the table for each Engine owned by an Account.\n\n- Wallet - The name of the Engine\n- Balance (NCT) - The current NCT balance of the Engine's Wallet\n- Deposit Address - The Address where you can deposit NCT to add to your Engine's Wallet. If your Engine has not been Verified before, this will say \"Pending Engine Verification\".\n\nIn the near future, we will be adding functionality to support making withdrawals from an Engine Wallet.\n\n## Usage {#usage}\n\nThe Usage tab displays the list of features available in the current Subscription Plan.\n\nThe Daily API Request Limit is the maximum number of every total feature usage allowed per 24hrs.\n\nNext to each feature is the remaining number of times out of the total number of times that feature can be used, per quota reset period.\n\n**Example:** `Hash Searches 6,692,085 of 7,000,000 /mo`, means you have 6,692,085 times left to use Hash Searches in that Month and the feature has been used 307,915 times.\n\n\n\n## Activity {#activity}\n\nThe Activity tab provides access to functionality to report on events from members of your team.\n\n> **Note:** Team Admin and Team Owner accounts will be able to view events from all team members, non team admin accounts can only see events from their own account.\n\nThis page will display the following items in the table:\n\n| Item | Functionality |\n| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Timestamp | A time stamp showing when the event took place. |\n| Event Type | Currently able to view Events for Sandbox Submissions (`sandbox_submit`, `sandbox_create`) and Scan Submissions (`scan_submit`, `scan_create`). |\n| User | The Name and Email for the account that triggered the Event. |\n| Metadata | Accompanying Metadata to the Event Type. This will vary for each Event Type but can contain information like the filename, full user name and instance ids. Clicking on the metadata will provide a popup with the full content. |\n\nThe Activity Page can be filtered based on the below items.\n\n- **Event Type** - Filter on Event Type i.e. Scan Create\n- **User** - Filter on User Events\n- **Timestamp** - Period to Filter on Events\n- **Metadata** - Various Metadata to filter on, for example Filename, Hash, Instance ID\n\n## Advanced {#advanced}\n\nThe Advanced tab provides access to functionality that is less often accessed.\n\n### Secure Authentication\n\nEnabling Secure Authentication is highly recommended, especially when an email address and password are used to log in.\n\nThis section will change depending on if the access is a User Account or a Team Account.\n\n**In a user context:** The button will say \"Enable Two-Factor Authentication (2FA) for Secure Login.\" This encourages individual users to activate 2FA to enhance the security of their login process.\n\n\n\n**In a team context:** The button will say \"Require 2FA for all Team Members.\" This emphasizes the importance of implementing 2FA for every member of the team, making it mandatory for enhanced security across the entire team.\n\n\n\nFor Users who have Engines or Wallets associated with their User Account, Enabled Secure Authentication is required.\n\n### Restrict Access To Members Tab \n\nIf turned on, only Team Admins or Team Owners can see the Members tab. \n\n### Sandbox Internet Access\n\nThis section allows users the ability to define if the 'internet' is turned on or off by default when sandboxing in the specific communities.\n\n\n\n### Artifact Download Encryption\n\nThe default password when downloading files via the UI is `infected`, this section allows this to be override with a password of you choice. This change will affect all downloads for all team members. \n\n\n\n\n### Notifications\n\nEnabling Notifications will provide email alerts for the individual user when a Sandbox Task has ended. Enabling or disabling this will effect the single user profile only, not the whole team. \n\nFurther to this, Email Notifications will be sent out when each feature in your plan gets to 90% used in your quota window. The User must have the Team Owner or Billing Admin role assigned to them to receive these. \n\n\n\n### Delete Account\n\n\n\n> This feature is only available for individual \"**User Accounts**\".\n\n
\n\nThis feature will will permanently delete the user account.\nThere are some things to be aware of when deleting an account.\n\n1. If the user is the only Team Admin on a team, they cannot delete their account. The team has to first assign another user as a Team Admin.\n2. If the user has a claimed engine, they cannot delete their account. The user has to first delete their engine claim.\n3. If the user has an active Live Hunt, it will be automatically stopped and deleted.\n4. All Live and Historical Hunting instances, results, and rules will be deleted.\n5. All user account information will be deleted.\n\n\n\n> **Warning:** There is no way to undo an account deletion once deleted!\n\n
\n\n### Configure Report Template {#report}\n\nProvides the ability to change the template used for html and pdf reports. Accounts with the _Team Owner_ or _Team Admin_ role can change the template. The template they set will apply to the generation of all reports from all members of the team.\n\n| Item | Functionality |\n| --------------- | ----------------------------------------------------------------------------------------------------------- |\n| Logo | Upload a `png` or `jpeg` for the logo, the max file size is 40KB and dimensions are 960x960. |\n| Primary Color | Select the primary color from the color picker, or use the hex code. applies to the`html` and `pdf` report. |\n| Footer Text | Text displayed at the bottom of each page. |\n| Disclaimer Text | Text displayed on the last page. |\n\n\n\n### Private Mode Theme {#advanced-theme}\n\nIf you have a Private Community, only Accounts with the _Team Owner_ or _Team Admin_ role can change the Theme. The Theme they set will apply to all members of the team.\n\n\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/getting-started/marketplace-concepts.md","frontmatter":{"title":"Marketplace Concepts","excerpt":"The core marketplace terms, communities, and how verdicts and rewards are determined."},"html":"Marketplace Concepts
\nMarketplace flow
\nPolySwarm is a threat intelligence marketplace where Engines analyze artifacts and are incentivised for accurate results. The marketplace involves three roles:
\n- \n
- Ambassador: brokers access to intelligence for customers and returns a final verdict \n
- Engines: submit assertions (malicious or benign) and optionally stake NCT on confidence via bids \n
- Arbiters: provide ground truth after additional time and evidence \n
End-to-end flow
\n- \n
- An Ambassador submits a suspicious artifact (file, URL, IP, or domain) as a bounty. \n
- Engines receive the bounty and decide whether to participate. \n
- Participating Engines return an assertion (malicious or benign) and may place a bid in NCT. \n
- The Ambassador combines assertions and returns a verdict to the customer. \n
- Later, Arbiters publish ground truth for the artifact. \n
- Engines whose assertions match ground truth are rewarded, while engines that disagreed may lose staked NCT. \n
PolySwarm performs the role of Ambassador. As an Engine partner, you participate as an Engine.
\nCommunities
\nPolySwarm is organised into Communities, which define who can participate and where bounties run.
\n- \n
- Public Community: open access and the default place to get started and test. \n
- Private Communities: invite only environments used for specific customer needs (for example NDA or data handling requirements). \n
In most cases, Engines can participate in Private Communities without code changes. Access is controlled by configuration and customer selection.
\nBlockchain and NCT (what you need to know)
\nEngines may stake and earn Nectar (NCT) through marketplace bidding and rewards.
\nYou do not need to write blockchain code, all chain interactions are handled by PolySwarm as part of the marketplace.
Deposit NCT
\nEngines may stake and earn Nectar (NCT) through marketplace bidding and rewards. Engines do not need to manage blockchain interactions directly, wallet functionality is handled within the PolySwarm Marketplace and UI.
\nThis page explains how deposits work and how to estimate an initial funding amount.
\nViewing Engine Wallet
\nIn the PolySwarm UI, open your User or Team account settings and locate the Wallets area. There you can:
\n- \n
- View your Engine wallet balance \n
- Find the Engine wallet deposit address \n
- Track wallet activity as the Engine runs \n
How Deposits Work
\nFor production communities, NCT is added to an Engine by depositing to the Engine wallet deposit address.
\n- \n
- Deposits are initiated from your external wallet or custody solution \n
- Once confirmed, the Engine wallet balance updates in the UI \n
If your organisation cannot hold or use cryptocurrencies for legal or policy reasons, contact PolySwarm to discuss alternatives.
\nEstimating your Initial Deposit
\nA practical estimate for initial funding is:
\nEstimated Initial NCT = (Bounties per day asserted on) * (Average bid per assertion in NCT) * (Days in arbitration period)
Guidelines:
\n- \n
- Bounties per day asserted on: use your configured rate limit as an upper bound, or a smaller value if you only participate in a subset of artifact types. \n
- Average bid per assertion: use your expected average bid. If you want a conservative upper bound, use your maximum bid. \n
- Arbitration period: assume a multi-week delay (commonly around 14 days) unless PolySwarm confirms otherwise for your community. \n
If you prefer a simple starting point, fund an amount that supports at least two weeks of expected bids, then monitor and top up as needed.
\nMaintaining a Sufficient Balance
\nYour Engine wallet cannot go negative. If it drops too low, your Engine may be unable to place bids and may effectively stop participating.
\nKey balance movements:
\n- \n
- \n
Assertions with bids
\n- \n
- Bid amounts are deducted from your Engine wallet when assertions are made \n
- If the wallet cannot cover a bid, the bid may be treated as 0 and may not participate as expected \n
\n - \n
Arbitration and rewards
\n- \n
- Rewards arrive after arbitration, typically on a delay of 2 weeks \n
- Your wallet must be large enough to cover bids until rewards are paid out \n
\n - \n
Deposits
\n- \n
- Increase wallet balance after confirmation \n
\n - \n
Withdrawals
\n- \n
- Reduce wallet balance immediately when initiated \n
\n
When to Deposit?
\nMost Engine partners deposit NCT during the final stages of verification and activation:
\n- \n
- You request verification \n
- PolySwarm confirms the Engine wallet and deposit address \n
- You deposit enough NCT to support expected bidding during the arbitration window \n
- Once verified and funded, the Engine can be activated for production participation \n
Roles
\nPolySwarm is a threat intelligence marketplace where customers receive verdicts on suspicious artifacts, and Engine partners are incentivised for accurate analysis.
\nPolySwarm (Ambassador)
\nPolySwarm brokers access to the marketplace for customers. It submits bounties, collects Engine assertions, and returns a verdict.
\nEngine (you)
\nEngines analyse artifacts and submit an assertion (malicious or benign). Engines may also bid Nectar (NCT) to express confidence, and are rewarded when their results align with confirmed ground truth.
\nEngines are typically operated by individuals or organisations with malware detection capability, specialised tooling, or expertise in a specific family, file type, or technique.
\nArbiter
\nArbiters publish ground truth after additional time and evidence. That ground truth is used to settle rewards and penalties across participating Engines.
\nIn practice, the Arbiter capability is implemented using the same core Engine model, but applied later in the bounty lifecycle.
","rawMarkdownBody":"\n# Roles\n\nPolySwarm is a threat intelligence marketplace where customers receive verdicts on suspicious artifacts, and Engine partners are incentivised for accurate analysis.\n\n## PolySwarm (Ambassador)\nPolySwarm brokers access to the marketplace for customers. It submits bounties, collects Engine assertions, and returns a verdict.\n\n## Engine (you)\nEngines analyse artifacts and submit an assertion (malicious or benign). Engines may also bid **Nectar (NCT)** to express confidence, and are rewarded when their results align with confirmed ground truth.\n\nEngines are typically operated by individuals or organisations with malware detection capability, specialised tooling, or expertise in a specific family, file type, or technique.\n\n## Arbiter\nArbiters publish **ground truth** after additional time and evidence. That ground truth is used to settle rewards and penalties across participating Engines.\n\nIn practice, the Arbiter capability is implemented using the same core Engine model, but applied later in the bounty lifecycle. \n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/launch-to-production/production-hosting.md","frontmatter":{"title":"Production Hosting","excerpt":"Production readiness requirements for your endpoint, performance, and rate limits."},"html":"Production Hosting
\nThis page describes the hosting requirements for running your Engine webhook service in production. Your Engine must meet these requirements to pass verification and operate reliably in public production communities.
\nPolySwarm does not mandate specific vendors or tooling, you can choose the hosting approach that fits your organisation. The requirements below describe what must be true regardless of where you run it.
\nRequirements
\nPublicly Accessible over HTTPS
\nYour engine webhook endpoint must be reachable from the public internet using HTTPS.
\n- \n
- The engine webhook URL must use a fully qualified domain name (FQDN) \n
- The URL may include a path \n
- TLS certificates must be valid and kept up to date \n
Rate Limit
\nIn the PolySwarm UI, you can set a daily rate limit for an engine webhook. Your hosting must be able to sustain that rate limit.
\nIf your Engine cannot keep up, it may:
\n- \n
- Fail to accept engine webhooks \n
- Time out frequently \n
- Respond too late to participate in rewards \n
Engines that repeatedly fail to respond may be marked Failed and stop receiving bounties. Recovery usually requires fixes plus a new verification request.
\nSufficient Bandwidth (File Engines)
\nEngines that process file artifacts may download significant volumes of data, bounded by your configured rate limit. Insufficient bandwidth can cause:
\n- \n
- Delayed artifact downloads \n
- Late assertions (late assertions may not participate in rewards) \n
- Engine webhook request failures under load \n
Ensure your hosting provides enough bandwidth for your expected daily volume and concurrency.
\nConcurrency
\nYour engine webhook server must not block on scanning.
\nMinimum expectations:
\n- \n
- Validate signature and enqueue work \n
- Return
202 Acceptedquickly \n - Perform analysis in worker processes \n
- Enforce timeouts on any external tools \n
Monitoring and Logging
\nAt minimum, you should be able to observe:
\n- \n
- Engine webhook received and validated \n
- Bounty queued for processing \n
- Analysis completed (verdict and timing) \n
- Assertion posted successfully (or error details) \n
This reduces verification friction and improves time to recover when issues occur.
\nMigrating from a Development Endpoint
\nIf you used a temporary endpoint (for example ngrok) during development testing, switch to your production endpoint before requesting verification.
\nA safe migration approach:
\n- \n
- Create a new engine webhook in the PolySwarm UI pointing to the production endpoint. \n
- Attach the new engine webhook to your Engine. \n
- Test in the Development Community using the production endpoint. \n
- Remove or disable the old engine webhook once the new one is stable. \n
Engine webhooks may be treated as immutable configuration objects, so plan for creating a new engine webhook rather than editing an existing one.
","rawMarkdownBody":"\n# Production Hosting\n\nThis page describes the hosting requirements for running your Engine webhook service in production. Your Engine must meet these requirements to pass verification and operate reliably in public production communities.\n\nPolySwarm does not mandate specific vendors or tooling, you can choose the hosting approach that fits your organisation. The requirements below describe what must be true regardless of where you run it.\n\n## Requirements\n\n### Publicly Accessible over HTTPS\n\nYour engine webhook endpoint must be reachable from the public internet using HTTPS.\n\n- The engine webhook URL must use a fully qualified domain name (FQDN)\n- The URL may include a path\n- TLS certificates must be valid and kept up to date\n\n### Rate Limit\n\nIn the PolySwarm UI, you can set a daily rate limit for an engine webhook. Your hosting must be able to sustain that rate limit.\n\nIf your Engine cannot keep up, it may:\n- Fail to accept engine webhooks\n- Time out frequently\n- Respond too late to participate in rewards\n\nEngines that repeatedly fail to respond may be marked **Failed** and stop receiving bounties. Recovery usually requires fixes plus a new verification request.\n\n### Sufficient Bandwidth (File Engines)\n\nEngines that process file artifacts may download significant volumes of data, bounded by your configured rate limit. Insufficient bandwidth can cause:\n\n- Delayed artifact downloads\n- Late assertions (late assertions may not participate in rewards)\n- Engine webhook request failures under load\n\nEnsure your hosting provides enough bandwidth for your expected daily volume and concurrency.\n\n### Concurrency\n\nYour engine webhook server must not block on scanning.\n\nMinimum expectations:\n- Validate signature and enqueue work\n- Return `202 Accepted` quickly\n- Perform analysis in worker processes\n- Enforce timeouts on any external tools\n\n### Monitoring and Logging\n\nAt minimum, you should be able to observe:\n\n- Engine webhook received and validated\n- Bounty queued for processing\n- Analysis completed (verdict and timing)\n- Assertion posted successfully (or error details)\n\nThis reduces verification friction and improves time to recover when issues occur.\n\n## Migrating from a Development Endpoint\n\nIf you used a temporary endpoint (for example ngrok) during development testing, switch to your production endpoint before requesting verification.\n\nA safe migration approach:\n\n1. Create a new engine webhook in the PolySwarm UI pointing to the production endpoint.\n2. Attach the new engine webhook to your Engine.\n3. Test in the Development Community using the production endpoint.\n4. Remove or disable the old engine webhook once the new one is stable.\n\nEngine webhooks may be treated as immutable configuration objects, so plan for creating a new engine webhook rather than editing an existing one.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/launch-to-production/request-verification.md","frontmatter":{"title":"Request verification","excerpt":"The exact UI steps to request verification and what to prepare before you click it."},"html":"Request verification
\nOnce your Engine is stable in the Development Community, the next step is to request verification in the PolySwarm UI. Verification is required before an Engine can operate in public production communities.
\nWhen?
\nRequest verification only when your Engine is ready for production-style operation:
\n- \n
- Your engine webhook service is publicly reachable over HTTPS \n
- Your Engine processes bounties reliably and returns valid assertions \n
- Unsupported artifact types return UNKNOWN with bid 0 \n
- You can keep the Engine online during the verification window \n
If you are still iterating frequently, still using temporary endpoints (for example ngrok), or still seeing intermittent failures, keep testing in the Development Community and wait to request verification.
\nHow to Request Verification
\n- \n
- Open the PolySwarm UI and switch to the Team that owns the Engine, then Settings \n
- Go to My Engines. \n
- Select your Engine. \n
- Click Request verification. \n
During verification, keep your engine webhook endpoint online and do not rotate secrets or URLs unless you coordinate with PolySwarm.
\nVerification Process
\nWhat PolySwarm will use for verification
\nPolySwarm will validate both configuration and behavior, including:
\n- \n
- Engine configuration fields in the UI (artifact types, engine webhook configuration, metadata settings) \n
- Ability to receive engine webhook bounties and respond correctly \n
- Correct assertion format (verdict, bid, metadata) \n
- Basic accuracy across known benign and malicious samples \n
- Production readiness checks (HTTPS accessibility, stability under load) \n
If Verification Fails
\nVerification failures are common on the first attempt. Typical reasons include:
\n- \n
- Slow or inconsistent responses \n
- Incorrect verdict formatting or missing required fields \n
- Errors during artifact download or analysis \n
- Returning benign instead of UNKNOWN for unsupported artifact types \n
If verification fails:
\n- \n
- Fix the issues (see next section for help) \n
- Re-test in the Development Community. \n
- Request verification again from My Engines. \n
PolySwarm Engine Overview
\nThank you for your interest in creating an Engine for PolySwarm!
\nPolySwarm Engines let you plug your detection capability into a live threat intelligence marketplace where real users submit suspicious artifacts (files, URLs, IPs, domains) and receive verdicts to support investigations and strengthen their cyber posture.
\nAs an Engine partner, you contribute verdict signals by analyzing artifacts and returning assertions, then you are incentivised through rewards when your results align with confirmed ground truth.
\nThis section is your starting point, it explains the Engine journey end to end, what you need to build, and how to participate safely and reliably in the marketplace.
\nHigh-level flow, proposal to verified Engine
\nThis is the end-to-end path for getting an Engine live on the PolySwarm Marketplace.
\n- \n
- Submit an Engine proposal \n
- PolySwarm review \n
- Onboarding \n
- Provisioning \n
- Integration and development testing \n
- Test in the Development Community \n
- Request verification \n
- Go live in production \n
- Operate and optimise \n
Wallets
\nGeneral
\nThe Wallets tab in the User Account or Team Account Settings of a PolySwarm UI Account allows you to manage Wallets belonging to your Account.\nIn a Team Account, a User must have the Team Admin or Wallet Admin role to view and use the Wallets tab.\nAll Users must enable 2-factor authentication (2FA) on their User Account before they can view the Wallets tab content.
\nEngine Wallets
\nThe section named \"Engine Wallets\" are the Wallets used by Engines (Microengines and Arbiters).\nThere is a separate row in the table for each Engine owned by an Account.
\n- \n
- Wallet - The name of the Engine \n
- Balance (NCT) - The current NCT balance of the Engine's Wallet \n
- Deposit Address - The Address where you can deposit NCT to add to your Engine's Wallet. If your Engine has not been Verified before, this will say \"Pending Engine Verification\". \n
In the near future, we will be adding functionality to support making withdrawals from an Engine Wallet.
\nRewards Wallets
\nThe section named \"Rewards Wallets\" are the Wallets used by PolySwarm Rewards programs.\nOnce a User has opted into a Rewards program, there will be one row in this table for their Rewards wallet.
\n- \n
- Wallet - The name of the Rewards program \n
- Balance (NCT) - The current NCT balance of the Wallet \n
- Deposit Address - Rewards wallets do not currently support deposits. \n
- Withdrawal Address - An external ETH/NCT address where NCT tokens are sent when withdrawn from this Wallet (Redeemed). \n
- Withdrawal Limit - Max amount of NCT that can be withdrawn per day from this Wallet. \n
In the Actions menu, there will be one or more options depending on the status of your wallet.
\n- \n
- Configure Withdrawals - This is where you define your
Withdrawal Addressand yourWithdrawal Limit. This is the first step you must do. \n - Withdrawals - Once you have defined a
Withdrawal Addressthis option will be active. Use this to withdraw NCT from your Rewards wallet and transfer the NCT to your personal ETH/NCT wallet. Withdrawals from a Rewards wallet can be initiated using the Action menu, or by clicking the Redeem button on the Rewards tab. \n
Below the name of the wallet is a Transactions table.\nClick the down arrow to view the set of Deposit and Withdrawal transactions for your Rewards wallet.\nNOTE: The Rewards payouts are not included in this table.
","rawMarkdownBody":"\n# Wallets\n\n## General {#general}\n\nThe Wallets tab in the [User Account](https://polyswarm.network/account/wallets) or [Team Account](https://polyswarm.network/settings/team/wallets) Settings of a PolySwarm UI Account allows you to manage Wallets belonging to your Account.\nIn a Team Account, a User must have the Team Admin or Wallet Admin role to view and use the Wallets tab.\nAll Users must [enable 2-factor authentication (2FA)](/customers/accounts#advanced) on their User Account before they can view the Wallets tab content.\n\n## Engine Wallets\n\nThe section named \"Engine Wallets\" are the Wallets used by Engines (Microengines and Arbiters).\nThere is a separate row in the table for each Engine owned by an Account.\n\n* Wallet - The name of the Engine\n* Balance (NCT) - The current NCT balance of the Engine's Wallet\n* Deposit Address - The Address where you can deposit NCT to add to your Engine's Wallet. If your Engine has not been Verified before, this will say \"Pending Engine Verification\".\n\nIn the near future, we will be adding functionality to support making withdrawals from an Engine Wallet.\n\n## Rewards Wallets\n\nThe section named \"Rewards Wallets\" are the Wallets used by [PolySwarm Rewards](/customers/rewards) programs.\nOnce a User has opted into a Rewards program, there will be one row in this table for their Rewards wallet.\n\n* Wallet - The name of the Rewards program\n* Balance (NCT) - The current NCT balance of the Wallet\n* Deposit Address - Rewards wallets do not currently support deposits.\n* Withdrawal Address - An external ETH/NCT address where NCT tokens are sent when withdrawn from this Wallet (Redeemed).\n* Withdrawal Limit - Max amount of NCT that can be withdrawn per day from this Wallet.\n\nIn the Actions menu, there will be one or more options depending on the status of your wallet.\n* Configure Withdrawals - This is where you define your `Withdrawal Address` and your `Withdrawal Limit`. This is the first step you must do.\n* Withdrawals - Once you have defined a `Withdrawal Address` this option will be active. Use this to withdraw NCT from your Rewards wallet and transfer the NCT to your personal ETH/NCT wallet. Withdrawals from a Rewards wallet can be initiated using the Action menu, or by clicking the Redeem button on the Rewards tab.\n\nBelow the name of the wallet is a Transactions table.\nClick the down arrow to view the set of Deposit and Withdrawal transactions for your Rewards wallet.\nNOTE: The Rewards payouts are not included in this table.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/launch-to-production/production-verification.md","frontmatter":{"title":"Production verification","excerpt":"What PolySwarm tests during verification, pass criteria, and common failure reasons."},"html":"Production Verification
\nProduction verification is the quality gate that allows an Engine to operate in public production communities. The goal is to ensure users receive reliable results and that Engines behave safely and predictably under real traffic.
\nWhat Verification Checks
\nVerification typically includes four areas:
\nIdentity and agreement checks
\n- \n
- KYC completion (where required) \n
- Engine Provider Agreement completed (where required) \n
Engine configuration review
\n- \n
- Engine configuration fields are present and correct in the UI \n
- Artifact types and engine webhook selection are correct \n
- Any required metadata or capability fields are accurately set \n
Technical verification
\n- \n
- PolySwarm sends known benign and known malicious test artifacts to your Engine in a controlled environment \n
- \n
Your Engine must:
\n- \n
- accept engine webhook requests \n
- validate signatures \n
- return
202 Acceptedquickly \n - process the bounty asynchronously \n
- post a correctly formatted assertion back \n
\n - Unsupported artifact types must return UNKNOWN with bid 0 \n
Operational readiness
\n- \n
- Endpoint is stable and reachable over HTTPS \n
- Engine is reliable under expected traffic (rate limit and concurrency) \n
- Timeouts and error handling do not cause cascading failures \n
Passing Verification
\nYou will typically pass verification when:
\n- \n
- Your Engine consistently produces valid assertions \n
- Your engine webhook service stays online throughout the verification window \n
- Responses are timely, consistent, and do not exceed expected time limits \n
- Unsupported artifacts are handled safely (UNKNOWN, bid 0) \n
- Configuration in the UI matches real behavior \n
Common Verification Failure Reasons
\n- \n
- Engine webhook reachable but fails signature validation: Secret mismatch or signature implementation bug \n
- Engine webhook returns slow responses: Analysis happens in the HTTP request thread instead of a worker \n
- Malformed assertions: Missing verdict, invalid bid type, invalid metadata structure \n
- Artifact download failures: Network or firewall issues, incorrect handling of artifact_uri \n
- Incorrect handling of unsupported types: Returning benign instead of UNKNOWN \n
Verification Failure
\n- \n
- Review the feedback from the PolySwarm Engines team. \n
- Fix the issue and test the fix in the Development Community. \n
- Request verification again from My Engines. \n
Hunting Iranian Nation State Spyware
\nThis tutorial will focus on how to use PolySwarm to hunt for samples that potentially related to Iranian Nation State Spyware.
\nZDNet published an article on Iran's official COVID-19 tracker application that sends the real time location of installees to the Iranian government.
\nThe article provides only a single IOC - a SHA256 hash (0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b) we can find on PolySwarm:
- \n
- via the CLI (hash search):
polyswarm search hash 0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\n - via the CLI (metadata search using the hash):
polyswarm search metadata 'hash.sha256:\"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"'\n - via the Python library: \n
query = 'hash.sha256:\"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")Let's take a look some of the Metadata Attributes from this Artifact:
\n{\n \"artifact\": {\n \"created\": \"2020-03-10T10:16:50.900548+00:00\",\n \"id\": \"71592690635387748\",\n \"md5\": \"766e5ecf6b1d86abf401ad9223de857d\",\n \"sha1\": \"f1271aa0ccf79d16b036bac5320ed4349af69b65\",\n \"sha256\": \"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"\n },\n ...\n \"strings\": {\n \"domains\": [\n \"V.mr\",\n \"\",\n \"covid-19-e9057.appspot.com\",\n \"p.to\",\n \"II1046766097017-4va56jc12ajt308tpbuge0tc5iqla179.apps.googleusercontent.com\",\n \"b.mc\",\n \"YJ.cz\",\n \"6.om\",\n \"6.gm\",\n \"covid-19-e9057.firebaseio.com\"\n ],\n ...\n }\n}There are several interesting domains extracted by the strings Tool:
- \n
covid-19-e9057.appspot.com\ncovid-19-e9057.firebaseio.com\n
It appears as though some portion of the Iranian government's backend for this app is Google's Appspot and Firebase services.\nThis is mildly interesting because Google removed the application from their Play Store.
\nNext, we conduct a Metadata Search for the unique portion of these domains (covid-19-e9057) + a wildcard (*) to find additional Artifacts that contain these strings:
$ polyswarm --fmt sha256 search metadata 'strings.domains:covid-19-e9057*'This search nets 4 Artifacts, all of which have been identified as malicious by Engines on PolySwarm. 3 of these Artifacts were, of course, not mentioned in the ZDNet article.
\nPerhaps they have new functionality worth investigating!
","rawMarkdownBody":"\n# Hunting Iranian Nation State Spyware\n\nThis tutorial will focus on how to use PolySwarm to hunt for samples that potentially related to Iranian Nation State Spyware.\n\n\nZDNet [published an article](https://www.zdnet.com/article/spying-concerns-raised-over-irans-official-covid-19-detection-app/) on Iran's official COVID-19 tracker application that sends the real time location of installees to the Iranian government.\n\nThe article provides only a single IOC - a SHA256 hash (`0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b`) we can find on PolySwarm:\n* via the CLI (hash search): `polyswarm search hash 0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b`\n* via the CLI (metadata search using the hash): `polyswarm search metadata 'hash.sha256:\"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"'`\n* via the Python library:\n\n```python\nquery = 'hash.sha256:\"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")\n```\n\nLet's take a look some of the Metadata Attributes from this Artifact:\n\n```json\n{\n \"artifact\": {\n \"created\": \"2020-03-10T10:16:50.900548+00:00\",\n \"id\": \"71592690635387748\",\n \"md5\": \"766e5ecf6b1d86abf401ad9223de857d\",\n \"sha1\": \"f1271aa0ccf79d16b036bac5320ed4349af69b65\",\n \"sha256\": \"0f73ac8839f153cf0e830554d9b34af2ea90fd6514ed3992b66a96bc9c12bb4b\"\n },\n ...\n \"strings\": {\n \"domains\": [\n \"V.mr\",\n \"\",\n \"covid-19-e9057.appspot.com\",\n \"p.to\",\n \"II1046766097017-4va56jc12ajt308tpbuge0tc5iqla179.apps.googleusercontent.com\",\n \"b.mc\",\n \"YJ.cz\",\n \"6.om\",\n \"6.gm\",\n \"covid-19-e9057.firebaseio.com\"\n ],\n ...\n }\n}\n```\n\nThere are several interesting domains extracted by the `strings` Tool:\n* `covid-19-e9057.appspot.com`\n* `covid-19-e9057.firebaseio.com`\n\nIt appears as though some portion of the Iranian government's backend for this app is Google's Appspot and Firebase services.\nThis is mildly interesting because Google removed the application from their Play Store.\n\nNext, we conduct a Metadata Search for the unique portion of these domains (`covid-19-e9057`) + a wildcard (`*`) to find additional Artifacts that contain these strings:\n\n```bash\n$ polyswarm --fmt sha256 search metadata 'strings.domains:covid-19-e9057*'\n```\n\nThis search nets 4 Artifacts, all of which have been identified as malicious by Engines on PolySwarm. 3 of these Artifacts were, of course, not mentioned in the ZDNet article.\n\nPerhaps they have new functionality worth investigating!"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/operate-and-optimise/bidding-strategy.md","frontmatter":{"title":"Bidding Strategy","excerpt":"How to size bids based on confidence and constraints to balance risk and reward."},"html":"Bidding Strategy
\nBidding is how you stake NCT on your assertion. A good strategy aligns bid size with confidence so you can earn rewards without taking unnecessary risk.
\nWhat Bidding Controls?
\n- \n
- Higher bids can increase potential upside when you are correct \n
- Higher bids increase losses when you are wrong \n
- Bidding requires sufficient wallet balance to sustain the arbitration window \n
Core principles
\nBid 0 on unsupported or low-confidence cases
\nIf you return UNKNOWN, your bid should be 0.
\nIf your signal is weak, consider:
\n- \n
- return UNKNOWN, bid 0 \n
- or return a verdict with a conservative bid (only if your policy supports this) \n
Bid rules by verdict (required)
\nEach bounty includes a bid range in the engine webhook payload (min_allowed_bid and max_allowed_bid). Your bid must follow these rules:
- \n
- If you return MALICIOUS or BENIGN, you must place a bid within the allowed range (
min_allowed_bidtomax_allowed_bid).\nYou cannot bid0for these verdicts. \n - If you return UNKNOWN, your bid must be
0. \n
If you cannot justify a bid within the allowed range, return UNKNOWN instead.
\nStart conservative
\nWhen your Engine is new or recently changed:
\n- \n
- keep bids low until reliability and accuracy are stable \n
- increase only after you are confident in your signal quality \n
Map bid to confidence
\nA simple and safe mapping is:
\n- \n
- confidence low → small bid \n
- confidence medium → moderate bid \n
- confidence high → closer to max allowed bid \n
Keep the mapping consistent and explainable.
\nRespect bounty constraints
\nBounties may define minimum and maximum bid rules. Your strategy should:
\n- \n
- never exceed max allowed bid \n
- avoid bidding below minimum if you want to participate \n
- adapt when constraints change \n
A Simple Starter Strategy (example)
\n- \n
- If unsupported type: verdict UNKNOWN, bid 0 \n
- If scan failed or timed out: verdict UNKNOWN, bid 0 \n
- If strong malicious signal: verdict MALICIOUS, bid near max allowed \n
- If strong benign signal: verdict BENIGN, bid low to moderate \n
- If ambiguous: verdict UNKNOWN, bid 0 \n
This reduces risk while you build confidence in the Engine.
\nTuning over time
\nAs you learn:
\n- \n
- increase bids only in areas where you are consistently correct \n
- decrease bids in areas where you see mistakes or unstable behavior \n
- consider separate strategies per artifact type (file vs url) \n
Hunting Syrian Nation State Android Malware
\nThis tutorial will focus on how to use PolySwarm to hunt for Android samples that potentially related to the Syrian Nation State.
\nLookout published a blog post on COVID-19 related Android malware released by the Syrian Electronic Army.
\nThe post discloses:
\n- \n
- Where the command and control (C2) addresses are stored within the malicious applications (within
res/values/strings.xml) \n - A list of SHA1 hashes of applications known to belong to this family of malware \n
First, we look up Lookout's first SHA1 hash on PolySwarm:
\n- \n
- via the CLI (hash search):
polyswarm search hash 1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08\n - via the CLI (metadata search using the hash):
polyswarm search metadata 'hash.sha1:\"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08\"'\n - via the Python library: \n
query = 'hash.sha1:\"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08\"'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")Next, we download the Artifact (using your choice of Web UI, CLI or Python) and use apktool with the d flag to extract res/values/strings.xml:
<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<resources>\n ...\n <string name=\"MT_Bin_dup_0x7f0c0020\">Android Telegram</string>\n <string name=\"MT_Bin_dup_0x7f0c0021\">10000</string>\n <string name=\"MT_Bin_dup_0x7f0c0022\">82.137.218.185</string>\n ...\n</resources>It appears as though the C2 address is 82.137.218.185. This information was not published in Lookout's blog post.
We can use Metadata Search to \"pivot\" using this IP(v4) address:
\n- \n
- via the CLI:
polyswarm search metadata --ip 82.137.218.185\n - via the Python library: \n
results = api.search_by_metadata(\"*\", ip=\"82.137.218.185\")\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")At the time of writing, we see 50 results:
\n- \n
- at least 23 of which were not identified by Lookout in their blog post, and \n
- at least 5 of which cannot be found on platforms similar to PolySwarm. \n
Using PolySwarm, researchers can quickly identify additional variants of malware and produce something that immediately expands on the public knowledge of the threat.
","rawMarkdownBody":"\n# Hunting Syrian Nation State Android Malware\n\nThis tutorial will focus on how to use PolySwarm to hunt for Android samples that potentially related to the Syrian Nation State.\n\n[Lookout](https://blog.lookout.com/nation-state-mobile-malware-targets-syrians-with-covid-19-lures) published a blog post on COVID-19 related Android malware released by the Syrian Electronic Army.\n\nThe post discloses:\n* Where the command and control (C2) addresses are stored within the malicious applications (within `res/values/strings.xml`)\n* A list of SHA1 hashes of applications known to belong to this family of malware\n\n\nFirst, we look up Lookout's first SHA1 hash on PolySwarm:\n* via the CLI (hash search): `polyswarm search hash 1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08`\n* via the CLI (metadata search using the hash): `polyswarm search metadata 'hash.sha1:\"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08\"'`\n* via the Python library:\n\n```python\nquery = 'hash.sha1:\"1aefc2ebaf1a78f23473ce6275b0b514bbcdfb08\"'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")\n```\n\nNext, we download the Artifact (using your choice of Web UI, CLI or Python) and use [apktool](https://ibotpeaches.github.io/Apktool/) with the `d` flag to extract `res/values/strings.xml`:\n\n```xml\n\nAccuracy
\nAccuracy is the quality of your verdicts over time. Higher accuracy generally improves reputation and reward outcomes, and reduces the risk of losing NCT when you bid.
\nWhat to Optimize for?
\nYour Engine should aim to:
\n- \n
- Correctly identify malicious artifacts (true positives) \n
- Correctly identify benign artifacts (true negatives) \n
- Avoid false positives (benign marked malicious) \n
- Avoid false negatives (malicious marked benign) \n
- Return UNKNOWN when your signal is weak or unsupported \n
Practical Accuracy Levers
\n1. Improve coverage and typing
\n- \n
- Detect artifact type early and handle each type explicitly \n
- For unsupported types, return UNKNOWN rather than guessing \n
2. Reduce false positives first
\nFalse positives hurt trust and can cause operational noise for users.\nWays to reduce false positives:
\n- \n
- require stronger evidence before returning malicious \n
- use allowlists for common benign patterns when justified \n
- treat ambiguous cases as UNKNOWN \n
3. Use confidence honestly
\nOnly emit confidence if it maps to a real signal:
\n- \n
- “High confidence” should be rare and repeatable \n
- map tool outputs and heuristics into a stable confidence scale \n
- keep confidence consistent across runs \n
4. Keep malware_family meaningful
\nIf you provide malware_family metadata:
\n- \n
- avoid overly generic labels \n
- avoid dumping raw tool strings that are unstable \n
- prefer a small set of consistent family names \n
5. Regression testing
\nAs you ship changes:
\n- \n
- keep a small local test corpus (benign + malicious) \n
- ensure new changes do not break previous good detections \n
- add tests for any bug you fix \n
A simple decision policy that works well
\n- \n
- Return MALICIOUS only when you have a strong signal \n
- Return BENIGN when evidence is strong that the artifact is clean \n
- \n
Return UNKNOWN when:
\n- \n
- the type is unsupported \n
- the scan failed \n
- the signal is weak \n
- timeouts occur \n
\n
This usually produces better long-term outcomes than guessing benign.
","rawMarkdownBody":"\n# Accuracy\n\nAccuracy is the quality of your verdicts over time. Higher accuracy generally improves reputation and reward outcomes, and reduces the risk of losing NCT when you bid.\n\n## What to Optimize for?\n\nYour Engine should aim to:\n- Correctly identify malicious artifacts (true positives)\n- Correctly identify benign artifacts (true negatives)\n- Avoid false positives (benign marked malicious)\n- Avoid false negatives (malicious marked benign)\n- Return UNKNOWN when your signal is weak or unsupported\n\n## Practical Accuracy Levers\n\n### 1. Improve coverage and typing\n- Detect artifact type early and handle each type explicitly\n- For unsupported types, return UNKNOWN rather than guessing\n\n### 2. Reduce false positives first\nFalse positives hurt trust and can cause operational noise for users.\nWays to reduce false positives:\n- require stronger evidence before returning malicious\n- use allowlists for common benign patterns when justified\n- treat ambiguous cases as UNKNOWN\n\n### 3. Use confidence honestly\nOnly emit confidence if it maps to a real signal:\n- “High confidence” should be rare and repeatable\n- map tool outputs and heuristics into a stable confidence scale\n- keep confidence consistent across runs\n\n### 4. Keep malware_family meaningful\nIf you provide malware_family metadata:\n- avoid overly generic labels\n- avoid dumping raw tool strings that are unstable\n- prefer a small set of consistent family names\n\n### 5. Regression testing\nAs you ship changes:\n- keep a small local test corpus (benign + malicious)\n- ensure new changes do not break previous good detections\n- add tests for any bug you fix\n\n## A simple decision policy that works well\n\n- Return **MALICIOUS** only when you have a strong signal\n- Return **BENIGN** when evidence is strong that the artifact is clean\n- Return **UNKNOWN** when:\n - the type is unsupported\n - the scan failed\n - the signal is weak\n - timeouts occur\n\nThis usually produces better long-term outcomes than guessing benign.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/customers/stix-taxii/use-stix-taxii.md","frontmatter":{"title":"PolySwarm STIX / TAXII","excerpt":"Accessing PolySwarm using STIX/TAXII is very easy..."},"html":"\nPolySwarm STIX / TAXII
\nStructured Information Exchange (STIX) and Trusted Automated Exchange of Indicator Information (TAXII) are community-supported specifications analysts use to automate sharing of threat intelligence.
\nPolySwarm supports these emerging standards in our TAXII v2.1-compliant services serving STIX v2.1-formatted threat intelligence feeds. Users can augment their threat intelligence with the array of software tools supporting the most recent STIX & TAXII standards while still receiving PolySwarm-exclusive intelligence like canonicalized malware family and PolyScore.
\nPolySwarm supports two methods of setting up STIX/TAXII, using integrations (e.g. ThreatQuotient, Cyware, Sentinel) and the Python API.
\nGetting Started
\nThere are several initial steps that need to be taken before proceeding with the STIX/TAXII integration.
\nPre-Requirements
\n- \n
- If you haven't already you need to create a PolySwarm account. \n
- You will need a client that supports TAXII 2.1 (
taxii2clientif using the Python API) \n
API Roots & Collections
\nTAXII servers host a hierarchy of API Roots: distinct TAXII instances accessed via different URLs, each providing its collections of threat intelligence.\nPolySwarm's TAXII services are organized around Collections: logical threat intelligence repositories organized by type and purpose.
What is a collection?
\nPolySwarm's TAXII services are organized around collections: logical repositories of threat intelligence organized by type and purpose.
\nObjects in a collection may also appear in others, enabling pivots between faster feeds of compact objects and detailed representations in specialized collections.
\nPolySwarm's currently available collections are designed to allow new collections to be added without disrupting existing customers.\nCollections are assigned a unique identifier (UUID) which identifies that collection when performing queries against PolySwarm's TAXII server.
\nYou can work with your PolySwarm sales representative to enable access to each API Root and collection you want to access, to view these navigate to here.
\nCreate a Team API Key
\nA Team API Key will be needed for the integration setup and the Python API configuration for authentication.
\n- \n
- Log into the PolySwarm UI https://polyswarm.network/ \n
- Click on the account user name in the top right corner \n
- Click on
Switch Accountsand switch to your Team Account \n - Navigate to
Settingsin the top right corner \n - Navigate to the
API KeysPage \n - Add a new
Team Account API Key\n
Locate Team ID (for Username)
\nA Team ID (Username) will be needed going forward for the integrations setup and the Python API configuration for authentication.
\n- \n
- Log into the PolySwarm UI https://polyswarm.network/ \n
- Click on the account user name in the top right corner \n
- Click on
Switch Accountsand switch to your Team Account \n - Navigate to
Settingsin the top right corner \n - Locate your Team ID below your Team Name. i.e.
#123454212\n
Connecting via Integrations
\nIntegrations that support STIX/TAXII 2.1 will offer the ability to add a TAXII feed; you will require the following details:
\n- \n
- Username PolySwarm Team ID. \n
- Password PolySwarm Team API Key. \n
- API Root URL \n
- and Collection ID. \n
This section will review how to find the API Root URL, and Collection ID and configure the Integration.
\nConfiguration of TAXII Client
\nThe API Root URL and Collection ID can be obtained from the table below.
\n\n\nNote: Access to the collections will be based upon the Team account subscription plan, contact customer-success@polyswarm.io to find out further details. To find a up to date list of collections, navigate to the “Listing available collections” section in the Python API section. For integrations that require a discovery URL use: https://api.polyswarm.network/v3/stix/taxii2/
\n
| Title | \nDescription | \nAPI Root URL | \nCollection | \nCollection ID | \nDetails | \n
|---|---|---|---|---|---|
| Ransomware | \nEmerging Ransomware | \nhttps://api.polyswarm.network/v3/stix/ransomware/ | \nIdentified ransomware-family feed | \n7b6bbecc-95cf-5317-a900-5bb7008eae93 | \nPolyScore > 0.50, Artifacts in the last 14 days that match a list of malware families. | \n
| PolySwarm Trust Group | \nGuest researcher feeds | \nhttps://api.polyswarm.network/v3/stix/trustgroup/ | \n14-Day Feed | \n3f153afb-5bf5-5cca-bfe9-ee854d92658d | \nAny PolyScore, All Artifacts in the last 14 days | \n
\n\nYou can obtain the latest list of collections with the Python API.
\n
Add the details above to your integration configuration page, and once configured and saved, the collection will poll and ingest the intelligence into the integration.
\nConnecting via Python API
\nPolySwarm's TAXII services are accessed via standard HTTP API endpoints defined in the TAXII v2.1 standard, often using a TAXII client library such as taxii2client. This section will explain the Python Library that can be used to access the STIX/TAXII collections.
\nAuthentication
\nPolySwarm performs HTTP authentication using your PolySwarm account's Account Number as your user and API KEY as password:
import taxii2client.v21\n\nTAXII_SERVER = taxii2client.v21.Server(\n 'https://api.polyswarm.network/v3/stix/taxii2/',\n user='${YOUR ACCOUNT NUMBER}',\n password='${YOUR API KEY}'\n)Default API Root
\nUsers of taxii2client can access their default API root through the server's default attribute:
DEFAULT_API_ROOT = TAXII_SERVER.defaultListing available collections
\nCustomers with a PolySwarm account can programmatically obtain a up to date list of the titles, short descriptions, UUIDs and an indication of whether the current user is allowed to read and write from an API root & collection via the Python API:
\ndef print_all_collections(server):\n from textwrap import indent\n from functools import partial\n\n def build_printer(prefix='', sep=''):\n nsep = sep\n def driver(*args, **kwargs):\n nonlocal nsep\n print(indent(' '.join(args), prefix=prefix + nsep), **kwargs)\n nsep = ' ' * len(nsep)\n return driver\n\n p = build_printer()\n p(f'Title: \"{server.title}\"')\n p(f'Contact: \"{server.contact}\"')\n p(f'Description: \"{server.description}\"')\n p('Roots:')\n\n for root in server.api_roots:\n p = build_printer(' ', sep='- ')\n p(f'Title: \"{root.title}\"')\n p(f'Description: \"{root.description}\"')\n p(f'URL: \"{root.url}\"')\n p('Collections:')\n\n for collection in root.collections:\n p = build_printer(' ', sep='- ')\n p(f'Title: \"{collection.title}\"')\n p(f'Objects URL: \"{collection.objects_url}\"')\n if collection.description:\n p(f'Description: \"{collection.description}\"')\n p(f'Can Read: {collection.can_read}')\n p(f'Can Write: {collection.can_write}')\n\nprint_all_collections(TAXII_SERVER)\nTitle: \"Polyswarm TAXII Service\"\nContact: \"sales@polyswarm.io\"\nDescription: \"This TAXII Server contains a listing of Polyswarm's feed data\"\nRoots:\n - Title: \"PolySwarm Trust Group\"\n Description: \"Guest researcher feeds\"\n URL: \"https://api.polyswarm.network/v2/stix/trustgroup/\"\n Collections:\n - Title: \"14-Day Feed\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/trustgroup/collections/3f153afb-5bf5-5cca-bfe9-ee854d92658d/objects/\"\n Can Read: True\n Can Write: False\n - Title: \"Ransomware\"\n Description: \"Emerging Ransomware\"\n URL: \"https://api.polyswarm.network/v2/stix/ransomware/\"\n Collections:\n - Title: \"Identified ransomware-family feed\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/ransomware/collections/7b6bbecc-95cf-5317-a900-5bb7008eae93/objects/\"\n Can Read: True\n Can Write: False\n - Title: \"Freemium\"\n Description: \"Polyswarm Basic TAXII\"\n URL: \"https://api.polyswarm.network/v2/stix/freemium/\"\n Collections:\n - Title: \"Freemium collection\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/freemium/collections/019630e9-0cdb-5d7d-b8c1-120c793093ad/objects/\"\n Can Read: True\n Can Write: False\n\n
Pagination
\nTAXII supports pagination of very large result sets in collections.\nCollections return a \"feed\" of STIX-formatted data sorted in ascending order by the date they were added to the collection:
\ndef read_taxii_feed(collection, **kwargs):\n while True:\n page = collection.get_objects(**kwargs)\n\n if page:\n yield page['objects']\n\n if page['more'] is True:\n kwargs['next'] = page['next']\n continue\n\n break\n\niterator = read_taxii_feed(DEFAULT_API_ROOT.collections[0])\nprint(next(iterator))\n[{'id': 'bundle--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'objects': [{'aliases': ['Trojan.DownLoad3.28161',\n 'Trojan.Generic.dayyf',\n 'win/malicious',\n 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'Trojan.Win32.Crypt',\n 'Trojan.ADC939420BE48D7E'],\n 'created': '2021-09-01T19:22:45.157824Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d'}],\n 'first_seen': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-e689fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.157824Z',\n 'malware_types': ['trojan', 'downloader'],\n 'modified': '2021-09-15T19:22:44.625891Z',\n 'name': 'Trojan.Win32.Crypt',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:50.000000Z',\n 'ctime': '2021-09-01T19:22:50.000000Z',\n 'hashes': {'MD5': 'fef489eed1314bcd5d545e7f65889ed8',\n 'SHA-1': 'ddab1051e713b9ce191382cc34820a6a6117ae7f',\n 'SHA-256': '2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d',\n 'SHA-512': '760e9924f8b1c8f20420f2bde9abc09881b7e38062bb3275d4c50cd8856eb0a3b108746c1289d79c8cb751e0a6b01e979e43d2dc7c527e8f288b1d6864aa265b',\n 'SSDEEP': '768:/whRkKCCR3IAm9MOlq8bdA/bmerdkDwRGXn/+mmCfyrr7/YMy:s5Hm9dl4/tuDz/+mjfum',\n 'TLSH': '4413ae3c6ee95672d3bbdab6c6f655c6f931b42379029c0d40da03850c13f16eda1a2e'},\n 'id': 'file--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'mtime': '2021-09-01T19:22:50.000000Z',\n 'name': '2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Trojan.DownLoad3.28161',\n 'win/malicious',\n 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'Trojan.ADC939420BE48D7E',\n 'Trojan.Generic.dayyf',\n 'Trojan.Win32.Crypt'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.157824Z',\n 'first_seen': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.157824Z',\n 'modified': '2021-09-15T19:22:44.627754Z',\n 'name': 'Trojan.Win32.Crypt',\n 'sample_refs': ['file--dd45c61c-ddbf-4fbb-80db-cb89fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.627966Z',\n 'id': 'relationship--5870ee12-8276-4110-bf58-42df4297025c',\n 'modified': '2021-09-15T19:22:44.627966Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-e689fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45ca9a-beff-4fd6-8087-5689fd18a656',\n 'modified': '2021-09-15T19:22:44.628133Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Trojan.Generic.dayyf',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628265Z',\n 'id': 'relationship--376a66a3-9be9-4e55-be0f-d981e06bf156',\n 'modified': '2021-09-15T19:22:44.628265Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ca9a-beff-4fd6-8087-5689fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44f2e4-46e1-4fb2-80e5-7889fd18a656',\n 'modified': '2021-09-15T19:22:44.628403Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'Trojan.DownLoad3.28161',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628524Z',\n 'id': 'relationship--4ae93d16-fa30-41db-8e17-37713f6771d7',\n 'modified': '2021-09-15T19:22:44.628524Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f2e4-46e1-4fb2-80e5-7889fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45bf19-ce09-4fa7-801e-3f89fd18a656',\n 'modified': '2021-09-15T19:22:44.628658Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'malicious',\n 'result_name': 'win/malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628776Z',\n 'id': 'relationship--db9ee711-2a3a-451a-9fe3-70b6ae5322b9',\n 'modified': '2021-09-15T19:22:44.628776Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45bf19-ce09-4fa7-801e-3f89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc447f63-6ab3-4fc3-807f-7889fd18a656',\n 'modified': '2021-09-15T19:22:44.628910Z',\n 'product': 'filseclab',\n 'result': 'malicious',\n 'result_name': 'Trojan.ADC939420BE48D7E',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629048Z',\n 'id': 'relationship--aa86d817-54a7-479b-977e-85cdc653f0be',\n 'modified': '2021-09-15T19:22:44.629048Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc447f63-6ab3-4fc3-807f-7889fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45ee09-d9c1-4f3f-80c0-5e89fd18a656',\n 'modified': '2021-09-15T19:22:44.629191Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629314Z',\n 'id': 'relationship--827b5c4d-e12d-454d-8ced-e361041d2695',\n 'modified': '2021-09-15T19:22:44.629314Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ee09-d9c1-4f3f-80c0-5e89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44db30-d404-4fcb-80ce-6289fd18a656',\n 'modified': '2021-09-15T19:22:44.629455Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629575Z',\n 'id': 'relationship--fc2e7e5f-8e92-427f-a792-2bbc60cd5cfb',\n 'modified': '2021-09-15T19:22:44.629575Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44db30-d404-4fcb-80ce-6289fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44172e-d6a0-4f38-80ba-0189fd18a656',\n 'modified': '2021-09-15T19:22:44.629717Z',\n 'product': 'lionic',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629835Z',\n 'id': 'relationship--b64b2696-f536-4dc6-afeb-2461ec4749cd',\n 'modified': '2021-09-15T19:22:44.629835Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44172e-d6a0-4f38-80ba-0189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44609a-145c-4f5d-80a1-e189fd18a656',\n 'modified': '2021-09-15T19:22:44.629969Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Crypt',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630087Z',\n 'id': 'relationship--9e559a2e-d185-49fb-ab26-eb747e99de3c',\n 'modified': '2021-09-15T19:22:44.630087Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44609a-145c-4f5d-80a1-e189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '2019-10-02 10:25',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45b73b-fc99-4f74-8075-8789fd18a656',\n 'modified': '2021-09-15T19:22:44.630221Z',\n 'product': 'qihoo-360',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630336Z',\n 'id': 'relationship--95f18068-1342-4021-b3fd-49e3a021b9d0',\n 'modified': '2021-09-15T19:22:44.630336Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45b73b-fc99-4f74-8075-8789fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc458035-822d-4f07-80d4-0a89fd18a656',\n 'modified': '2021-09-15T19:22:44.630466Z',\n 'product': 'alibaba',\n 'result': 'malicious',\n 'result_name': 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630582Z',\n 'id': 'relationship--3a7abb12-86fe-4940-8800-e63b2e483c98',\n 'modified': '2021-09-15T19:22:44.630582Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc458035-822d-4f07-80d4-0a89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'},\n {'id': 'bundle--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'objects': [{'aliases': ['Trojan.Win64.CoinMiner',\n 'Trojan.BtcMine.3367',\n 'Trojan.MSIL.qzrf',\n 'Dropper.Agent!8.2F',\n 'Win.Coinminer.Generic-7151250-0',\n 'Trojan.Win32.Trick.fmmuks'],\n 'created': '2021-09-01T19:22:45.178976Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3'}],\n 'first_seen': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-f189fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.178976Z',\n 'malware_types': ['trojan', 'resource-exploitation', 'dropper'],\n 'modified': '2021-09-15T19:22:44.633865Z',\n 'name': 'Trojan.Win64.CoinMiner',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:47.000000Z',\n 'ctime': '2021-09-01T19:22:48.000000Z',\n 'hashes': {'MD5': '6e2757fa246b5bbdac38722930ec2794',\n 'SHA-1': '608604a72d867383a20c1f2f08ba1be61dc31b8b',\n 'SHA-256': '84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3',\n 'SHA-512': '3e70dc8d82c4cba93fe79e3ab10931a5dbb4a67243a9e9b1843135223c3680ef462aa3232b4fe855b85bc8f2cb65fbc0e4d75084abde914a70cf71a10496aca2',\n 'SSDEEP': '49152:FGUzr9GOWh50kC1/dVFdNaeUE3LqW1T/f5iBA9R86DHVVzP7ffQmSumSDr4k:FG6r9GOWPClFdNaeUE3LqW1T/f5iBA9H',\n 'TLSH': 'abb57cbd728502b1d1eec476ca178d0ff7b17a524334a1eb156443ae2e236d98639f32'},\n 'id': 'file--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'mtime': '2021-09-01T19:22:48.000000Z',\n 'name': '84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Trojan.Win64.CoinMiner',\n 'Dropper.Agent!8.2F',\n 'Trojan.Win32.Trick.fmmuks',\n 'Trojan.MSIL.qzrf',\n 'Trojan.BtcMine.3367',\n 'Win.Coinminer.Generic-7151250-0'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.178976Z',\n 'first_seen': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.178976Z',\n 'modified': '2021-09-15T19:22:44.635847Z',\n 'name': 'Trojan.Win64.CoinMiner',\n 'sample_refs': ['file--dd45aeee-3a07-4f09-80dd-de89fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.636028Z',\n 'id': 'relationship--2ddd2731-d977-4d21-9f42-456a390a9641',\n 'modified': '2021-09-15T19:22:44.636028Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-f189fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45ff41-2a95-4f62-8069-d189fd18a656',\n 'modified': '2021-09-15T19:22:44.636182Z',\n 'product': 'alibaba',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636307Z',\n 'id': 'relationship--dfc0f440-5c7f-4a29-92ff-1a6545dd6d48',\n 'modified': '2021-09-15T19:22:44.636307Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ff41-2a95-4f62-8069-d189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc445ec3-809e-4f9a-8052-1089fd18a656',\n 'modified': '2021-09-15T19:22:44.636443Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'Trojan.BtcMine.3367',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636561Z',\n 'id': 'relationship--e32c8ee3-1d9b-4eba-87f4-6bbb61741469',\n 'modified': '2021-09-15T19:22:44.636561Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc445ec3-809e-4f9a-8052-1089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44186b-960c-4f21-8012-5589fd18a656',\n 'modified': '2021-09-15T19:22:44.636694Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636812Z',\n 'id': 'relationship--308f92fb-ecdc-40a8-9245-b40c601ff795',\n 'modified': '2021-09-15T19:22:44.636812Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44186b-960c-4f21-8012-5589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44dd7a-4c15-4f86-8034-1b89fd18a656',\n 'modified': '2021-09-15T19:22:44.636948Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637101Z',\n 'id': 'relationship--9148f1a1-b66c-4bde-b0f6-819ad558607a',\n 'modified': '2021-09-15T19:22:44.637101Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44dd7a-4c15-4f86-8034-1b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': 'ClamAV 0.102.4/26281/Wed Sep 1 '\n '08:21:58 2021',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44f633-e3e2-4f0c-802b-9989fd18a656',\n 'modified': '2021-09-15T19:22:44.637241Z',\n 'product': 'clamav',\n 'result': 'malicious',\n 'result_name': 'Win.Coinminer.Generic-7151250-0',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637359Z',\n 'id': 'relationship--f48af396-db6d-44b8-9e71-57a713d6f47f',\n 'modified': '2021-09-15T19:22:44.637359Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f633-e3e2-4f0c-802b-9989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc445857-1da9-4f82-80f3-1989fd18a656',\n 'modified': '2021-09-15T19:22:44.637492Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637610Z',\n 'id': 'relationship--23dd6ac8-5b49-4353-b54e-392bc524126e',\n 'modified': '2021-09-15T19:22:44.637610Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc445857-1da9-4f82-80f3-1989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '0.14.35.19132',\n 'analysis_engine_version': '1.0.134.90676',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45a504-0f2e-4ff6-80d4-1989fd18a656',\n 'modified': '2021-09-15T19:22:44.637743Z',\n 'product': 'nanoav',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Trick.fmmuks',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637861Z',\n 'id': 'relationship--d12b3cab-fdf5-4bbe-b48b-9ce9ffa00e11',\n 'modified': '2021-09-15T19:22:44.637861Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45a504-0f2e-4ff6-80d4-1989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc440050-76f9-4f3c-8038-9e89fd18a656',\n 'modified': '2021-09-15T19:22:44.637995Z',\n 'product': 'rising',\n 'result': 'malicious',\n 'result_name': 'Dropper.Agent!8.2F',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638121Z',\n 'id': 'relationship--0a1c9971-36b9-482e-b117-39ecc03c5ed5',\n 'modified': '2021-09-15T19:22:44.638121Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc440050-76f9-4f3c-8038-9e89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45f7a9-3354-4f02-80ad-bc89fd18a656',\n 'modified': '2021-09-15T19:22:44.638263Z',\n 'product': 'filseclab',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638383Z',\n 'id': 'relationship--5f2cb4a5-94d2-49f0-abc5-dd2ea9795a07',\n 'modified': '2021-09-15T19:22:44.638383Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45f7a9-3354-4f02-80ad-bc89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc446861-42b0-4f55-804a-0389fd18a656',\n 'modified': '2021-09-15T19:22:44.638518Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win64.CoinMiner',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638636Z',\n 'id': 'relationship--c4056dc0-23e5-4b36-8d50-4cc1dafd9958',\n 'modified': '2021-09-15T19:22:44.638636Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc446861-42b0-4f55-804a-0389fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44bf82-a407-4fd6-800d-ab89fd18a656',\n 'modified': '2021-09-15T19:22:44.638769Z',\n 'product': 'lionic',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.639014Z',\n 'id': 'relationship--0c2bccc2-ff2c-4b56-9088-e2b93e8abf91',\n 'modified': '2021-09-15T19:22:44.639014Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44bf82-a407-4fd6-800d-ab89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44455e-f135-4f64-809d-8d89fd18a656',\n 'modified': '2021-09-15T19:22:44.639160Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Trojan.MSIL.qzrf',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.639281Z',\n 'id': 'relationship--855479ed-53f2-4368-95d3-92340d4a68fb',\n 'modified': '2021-09-15T19:22:44.639281Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44455e-f135-4f64-809d-8d89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'},\n {'id': 'bundle--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'objects': [{'aliases': ['Backdoor.6536F84D7F60AA9C',\n 'win/malicious',\n 'Malware:Win32/Dorpal.ali1000029',\n 'BackDoor.Golf.260',\n 'Backdoor.Generic.ztr',\n 'Trojan.Win32.Urelas',\n 'Backdoor.Plite!8.2D6',\n 'Win.Malware.Urelas-6840420-0'],\n 'created': '2021-09-01T19:22:45.194687Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3'}],\n 'first_seen': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-e089fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.194687Z',\n 'malware_types': ['backdoor', 'virus', 'trojan'],\n 'modified': '2021-09-15T19:22:44.642432Z',\n 'name': 'Urelas',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:50.000000Z',\n 'ctime': '2021-09-01T19:22:50.000000Z',\n 'hashes': {'MD5': 'f5b78e02928c276f22be13313d37bcb4',\n 'SHA-1': 'e024f5d831e101d4d7748fe3d0792e72f4762ff0',\n 'SHA-256': 'ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3',\n 'SHA-512': '66727aa1e7c24987b515ff42704b35a89d4ea5d3c62d32649f158218628344b30adfaa8a61967124592969f7301930588e472a618b5eed0b629c509d114e3b28',\n 'SSDEEP': '1536:s1baYkjUIKECOmxUNKwhB+GT/4I2fm3w9Rri+pXmf8t1dn4vcj0:sjIKn1xUswhsGTgI23RGUXmUDg',\n 'TLSH': '22d3cf4566010894f71c0b721a02fad0889dae7c65d6fa5ff1bc7d7ab932183a97309f'},\n 'id': 'file--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'mtime': '2021-09-01T19:22:50.000000Z',\n 'name': 'ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Backdoor.6536F84D7F60AA9C',\n 'win/malicious',\n 'Malware:Win32/Dorpal.ali1000029',\n 'BackDoor.Golf.260',\n 'Backdoor.Generic.ztr',\n 'Trojan.Win32.Urelas',\n 'Backdoor.Plite!8.2D6',\n 'Win.Malware.Urelas-6840420-0'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.194687Z',\n 'first_seen': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.194687Z',\n 'modified': '2021-09-15T19:22:44.644475Z',\n 'name': 'Urelas',\n 'sample_refs': ['file--dd44bb23-4668-4f3b-80c3-d589fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.644702Z',\n 'id': 'relationship--d1f3b112-02c4-4ea8-b36d-56c871f3da91',\n 'modified': '2021-09-15T19:22:44.644702Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-e089fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ef20-ce6a-4f5a-8060-d389fd18a656',\n 'modified': '2021-09-15T19:22:44.644858Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'malicious',\n 'result_name': 'win/malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.644982Z',\n 'id': 'relationship--d5a07ca3-fcbe-4722-92e8-16a6ac82da9e',\n 'modified': '2021-09-15T19:22:44.644982Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ef20-ce6a-4f5a-8060-d389fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ff03-52a3-4f74-8059-1289fd18a656',\n 'modified': '2021-09-15T19:22:44.645144Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Backdoor.Generic.ztr',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645264Z',\n 'id': 'relationship--4b08404d-64e3-44ae-99ab-8017944749ad',\n 'modified': '2021-09-15T19:22:44.645264Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ff03-52a3-4f74-8059-1289fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44f830-1712-4fcc-80e6-1089fd18a656',\n 'modified': '2021-09-15T19:22:44.645396Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645514Z',\n 'id': 'relationship--937a07aa-bc4f-4039-94b7-34c586f42703',\n 'modified': '2021-09-15T19:22:44.645514Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f830-1712-4fcc-80e6-1089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc443af4-a14c-4f37-8028-7b89fd18a656',\n 'modified': '2021-09-15T19:22:44.645648Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'BackDoor.Golf.260',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645765Z',\n 'id': 'relationship--09473b27-7c9e-4c41-bacb-b507e2a59900',\n 'modified': '2021-09-15T19:22:44.645765Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc443af4-a14c-4f37-8028-7b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44bea2-b17e-4fb6-80e1-2c89fd18a656',\n 'modified': '2021-09-15T19:22:44.645898Z',\n 'product': 'filseclab',\n 'result': 'malicious',\n 'result_name': 'Backdoor.6536F84D7F60AA9C',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646016Z',\n 'id': 'relationship--c9070ece-6c17-4af8-843b-8c9506acd11a',\n 'modified': '2021-09-15T19:22:44.646016Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44bea2-b17e-4fb6-80e1-2c89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44cd9a-0c37-4f5e-808c-4189fd18a656',\n 'modified': '2021-09-15T19:22:44.646147Z',\n 'product': 'alibaba',\n 'result': 'malicious',\n 'result_name': 'Malware:Win32/Dorpal.ali1000029',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646281Z',\n 'id': 'relationship--fdf11db2-f58b-4b3e-b5ac-eafd5aae5fff',\n 'modified': '2021-09-15T19:22:44.646281Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44cd9a-0c37-4f5e-808c-4189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ef5d-f3cf-4ff5-8048-6089fd18a656',\n 'modified': '2021-09-15T19:22:44.646417Z',\n 'product': 'lionic',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646531Z',\n 'id': 'relationship--4c9040a8-e18c-4e18-9719-bd1d0aea4b84',\n 'modified': '2021-09-15T19:22:44.646531Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ef5d-f3cf-4ff5-8048-6089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44f324-c769-4fb0-805e-4089fd18a656',\n 'modified': '2021-09-15T19:22:44.646661Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Urelas',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646777Z',\n 'id': 'relationship--6c4ae8f4-6834-463f-bd8a-7f48897802c6',\n 'modified': '2021-09-15T19:22:44.646777Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f324-c769-4fb0-805e-4089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '2019-10-02 10:25',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc4461c1-5f2a-4f35-80dd-e589fd18a656',\n 'modified': '2021-09-15T19:22:44.646906Z',\n 'product': 'qihoo-360',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647020Z',\n 'id': 'relationship--af73da52-3871-4627-89d9-dec1a1da70bb',\n 'modified': '2021-09-15T19:22:44.647020Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc4461c1-5f2a-4f35-80dd-e589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44b4fb-d3f9-4f32-80ef-6489fd18a656',\n 'modified': '2021-09-15T19:22:44.647162Z',\n 'product': 'rising',\n 'result': 'malicious',\n 'result_name': 'Backdoor.Plite!8.2D6',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647277Z',\n 'id': 'relationship--7d6c1a5b-b470-44cc-9518-deaedfe23236',\n 'modified': '2021-09-15T19:22:44.647277Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44b4fb-d3f9-4f32-80ef-6489fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44beb6-1678-4f7b-801f-2b89fd18a656',\n 'modified': '2021-09-15T19:22:44.647410Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647525Z',\n 'id': 'relationship--ee17c47a-9768-4f6f-8cf8-446a4a34d524',\n 'modified': '2021-09-15T19:22:44.647525Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44beb6-1678-4f7b-801f-2b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': 'ClamAV 0.102.4/26090/Wed Feb 24 '\n '12:09:42 2021',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc446b6b-1a0d-4f7c-806c-4c89fd18a656',\n 'modified': '2021-09-15T19:22:44.647653Z',\n 'product': 'clamav',\n 'result': 'malicious',\n 'result_name': 'Win.Malware.Urelas-6840420-0',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647769Z',\n 'id': 'relationship--56e75fba-6af7-4cec-9482-dabcb866ea6d',\n 'modified': '2021-09-15T19:22:44.647769Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc446b6b-1a0d-4f7c-806c-4c89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'}]\n\nFilter Parameters
\nA TAXII Client can request specific content from a TAXII Server by specifying a set of filters included in the URL query parameters of the request to the server.
\nUniversal filter parameters
\nAll of PolySwarm's collections support the following filter parameters:
\n| URL Query Parameters | \nDescription | \nExample | \n
|---|---|---|
added_after | \nA single \"T-Syntax\" RFC3339 time stamp that filters objects to only include those objects added after the specified time stamp. If no added_after URL query parameter is provided, the server will return the oldest objects matching the request first. For example, if a server has 100 objects (0-99), the server would start at record 0 looking for a match and work its way up from oldest to newest finding 50 (the default & maximum limit) of objects that matched the request. | \n2021-09-08T00:00:00Z | \n
limit | \nA single integer value that indicates the maximum number of objects that to receive in a single response. This must be a positive integer greater than 0 and less than 51. | \n25 | \n
next | \nA single opaque string value that indicates the next record or set of records in the data set that the client is requesting. This value never expires and may be used to resume pagination at a later date (if you attempt to resume pagination of objects older than that collection's defined maximum object age, you will resume pagination from that collection's initial page. | \ngAAAAAOSmbvF...oRY06o== | \n
You can use supply any these parameters as keyword arguments to read_taxii_feed:
read_taxii_feed(collection, added_after='2021-09-08T00:00:00Z'):Using the match[<field>] for Filtering
\nNon-freemium collections also provide a match[<field>] parameter to apply filtering on a specific <field>. The match parameter can be specified any number of times, where each match instance specifies an additional filter combined as logical \"AND\" predicates. Individual match query parameters may contain multiple values separated by a comma (,) which are treated as a logical \"OR\". For instance, ?match[type]=bundle,sighting specifies a filter for objects that are of type bundle OR sighting.
| Field | \nDescription | \nExample | \n
|---|---|---|
id | \nThe identifier of the object(s) that are being requested | \nbundle--dd45feca-cf0c-4f86-8026-f889 | \n
type | \nThe type of the object(s) that are being requested. Only the types listed in this parameter are permitted in the response. | \nbundle,sighting | \n
You can use supply any these parameters as keyword arguments to read_taxii_feed:
read_taxii_feed(collection, id='bundle--dd45feca-cf0c-4f86-8026-f889,bundle--dd445a57-7358-4ff4-8056-5d89'):STIX Field Mapping
\nThis sections will provide you with the field mapping of the STIX PolySwarm file.
\n| Field Name | \nDescription | \nSample Data | \n
|---|---|---|
| aliases | \nFamily names from engine results | \n[\"Backdoor.Padodor.c\",\"Backdoor.Win32.Padodor\",\"Backdoor.Berbew!8.115\", \"Trojan:Win32/Starter.ali1001008\", \"BackDoor.HangUp.5\",\"Win.Trojan.Crypted-29\",\"Proxy-Program ( 00557ea51 )\",\"win/malicious\"] | \n
| created/first_seen | \nWhen hash was first seen in the PolySwarm Marketplace | \n2021-01-20T23:30:10.665092Z | \n
| external_references | \nLink to PolySwarm portal with full details | \n\"url\": \"https://polyswarm.network/scan/results/file/017bcfbe29b805c010cf7c1790c17fb10a1069c7806ff65ae15fe12dd27e6645\" | \n
| malware_types | \nMalware functionality tags | \n[ \"backdoor\", \"greyware\", \"Trojan\" ] | \n
| imphash | \nValid only for Windows PE files | \n26babd76bbb7f9c516a338b0601b4c9f | \n
| optional_header | \nPE header information | \n\"address_of_entry_point\": 204800, \"major_linker_version\": 2, \"major_os_version\": 1, \"major_subsystem_version\": 4, \"minor_linker_version\": 5, \"minor_os_version\": 0, \"minor_subsystem_version\": 0, \"size_of_code\": 47104, \"size_of_initialized_data\": 18432 | \n
| pe_type | \nFile type | \nexe | \n
| timedatestamp | \nBinary compile date timestamp | \n2020-07-11T03:39:59Z | \n
| hashes | \nMD5, SHA-1, SHA-256, SHA-512, SSDEEP, TLSH hashes of the malware | \n{ \"MD5\": \"ab49bfba6e83c2211bcb5e25dfd428ae\", \"SHA-1\": \"0c09e4ecdedf46f5c801a1c2267d5166afd48a48\", \"SHA-256\": \"017bcfbe29b805c010cf7c1790c17fb10a1069c7806ff65ae15fe12dd27e6645\", \"SHA-512\": \"386f20b87848fc138b14931bdec5c348e26c7c270d952ba3487a020819ac07b1449b0715082e01aea898e69a1edb1aa77c5857c87ab1c8daa0d787f75c422def\", \"SSDEEP\": \"768:/abmyOy0JJk0Zvj12BhSPbefkcjnJuv+I1CV+zClaEZIGXOjWW3RuSyRZPAv8Q5:iDCJJko4hSPbelju91ZCla7IUW5SyRQ\", \"TLSH\": \"54637cc901172d79e8d9a5f25c238aa9a407cf390752f7dc0eda4db978fa4075f28c61\" } | \n
| mime_type | \nMime type of the file | \napplication/x-dosexec | \n
| size | \nFile size of the sample submitted | \n69632 | \n
| confidence | \nPolyScore * 100 | \n99 | \n
| last_seen | \nWhen it was last scanned by the malware engines | \n2021-01-20T23:30:10.584455Z | \n
| product | \nEngine name providing response (repeated for every engine asserting) | \nclamav | \n
| result | \nBenign or malicious (repeated for every engine asserting) | \nmalicious | \n
| result_name | \nFamily name provided by engine (not provided by every engine) (repeated for every engine asserting) | \nWin.Trojan.Crypted-29 | \n
\nTitle: \"Polyswarm TAXII Service\"\nContact: \"sales@polyswarm.io\"\nDescription: \"This TAXII Server contains a listing of Polyswarm's feed data\"\nRoots:\n - Title: \"PolySwarm Trust Group\"\n Description: \"Guest researcher feeds\"\n URL: \"https://api.polyswarm.network/v2/stix/trustgroup/\"\n Collections:\n - Title: \"14-Day Feed\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/trustgroup/collections/3f153afb-5bf5-5cca-bfe9-ee854d92658d/objects/\"\n Can Read: True\n Can Write: False\n - Title: \"Ransomware\"\n Description: \"Emerging Ransomware\"\n URL: \"https://api.polyswarm.network/v2/stix/ransomware/\"\n Collections:\n - Title: \"Identified ransomware-family feed\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/ransomware/collections/7b6bbecc-95cf-5317-a900-5bb7008eae93/objects/\"\n Can Read: True\n Can Write: False\n - Title: \"Freemium\"\n Description: \"Polyswarm Basic TAXII\"\n URL: \"https://api.polyswarm.network/v2/stix/freemium/\"\n Collections:\n - Title: \"Freemium collection\"\n Objects URL: \"https://api.polyswarm.network/v2/stix/freemium/collections/019630e9-0cdb-5d7d-b8c1-120c793093ad/objects/\"\n Can Read: True\n Can Write: False\n\n\n#### Pagination {#pagination}\n\nTAXII supports pagination of very large result sets in collections.\nCollections return a \"feed\" of STIX-formatted data sorted in ascending order by the date they were added to the collection:\n\n```python\ndef read_taxii_feed(collection, **kwargs):\n while True:\n page = collection.get_objects(**kwargs)\n\n if page:\n yield page['objects']\n\n if page['more'] is True:\n kwargs['next'] = page['next']\n continue\n\n break\n\niterator = read_taxii_feed(DEFAULT_API_ROOT.collections[0])\nprint(next(iterator))\n```\n\n
\n[{'id': 'bundle--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'objects': [{'aliases': ['Trojan.DownLoad3.28161',\n 'Trojan.Generic.dayyf',\n 'win/malicious',\n 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'Trojan.Win32.Crypt',\n 'Trojan.ADC939420BE48D7E'],\n 'created': '2021-09-01T19:22:45.157824Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d'}],\n 'first_seen': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-e689fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.157824Z',\n 'malware_types': ['trojan', 'downloader'],\n 'modified': '2021-09-15T19:22:44.625891Z',\n 'name': 'Trojan.Win32.Crypt',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:50.000000Z',\n 'ctime': '2021-09-01T19:22:50.000000Z',\n 'hashes': {'MD5': 'fef489eed1314bcd5d545e7f65889ed8',\n 'SHA-1': 'ddab1051e713b9ce191382cc34820a6a6117ae7f',\n 'SHA-256': '2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d',\n 'SHA-512': '760e9924f8b1c8f20420f2bde9abc09881b7e38062bb3275d4c50cd8856eb0a3b108746c1289d79c8cb751e0a6b01e979e43d2dc7c527e8f288b1d6864aa265b',\n 'SSDEEP': '768:/whRkKCCR3IAm9MOlq8bdA/bmerdkDwRGXn/+mmCfyrr7/YMy:s5Hm9dl4/tuDz/+mjfum',\n 'TLSH': '4413ae3c6ee95672d3bbdab6c6f655c6f931b42379029c0d40da03850c13f16eda1a2e'},\n 'id': 'file--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'mtime': '2021-09-01T19:22:50.000000Z',\n 'name': '2b898acee79ef91d036ceaf043953f234a36be79cfc92ec9f98f0c54a547144d',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Trojan.DownLoad3.28161',\n 'win/malicious',\n 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'Trojan.ADC939420BE48D7E',\n 'Trojan.Generic.dayyf',\n 'Trojan.Win32.Crypt'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.157824Z',\n 'first_seen': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.157824Z',\n 'modified': '2021-09-15T19:22:44.627754Z',\n 'name': 'Trojan.Win32.Crypt',\n 'sample_refs': ['file--dd45c61c-ddbf-4fbb-80db-cb89fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.627966Z',\n 'id': 'relationship--5870ee12-8276-4110-bf58-42df4297025c',\n 'modified': '2021-09-15T19:22:44.627966Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-e689fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45ca9a-beff-4fd6-8087-5689fd18a656',\n 'modified': '2021-09-15T19:22:44.628133Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Trojan.Generic.dayyf',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628265Z',\n 'id': 'relationship--376a66a3-9be9-4e55-be0f-d981e06bf156',\n 'modified': '2021-09-15T19:22:44.628265Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ca9a-beff-4fd6-8087-5689fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44f2e4-46e1-4fb2-80e5-7889fd18a656',\n 'modified': '2021-09-15T19:22:44.628403Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'Trojan.DownLoad3.28161',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628524Z',\n 'id': 'relationship--4ae93d16-fa30-41db-8e17-37713f6771d7',\n 'modified': '2021-09-15T19:22:44.628524Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f2e4-46e1-4fb2-80e5-7889fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45bf19-ce09-4fa7-801e-3f89fd18a656',\n 'modified': '2021-09-15T19:22:44.628658Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'malicious',\n 'result_name': 'win/malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.628776Z',\n 'id': 'relationship--db9ee711-2a3a-451a-9fe3-70b6ae5322b9',\n 'modified': '2021-09-15T19:22:44.628776Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45bf19-ce09-4fa7-801e-3f89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc447f63-6ab3-4fc3-807f-7889fd18a656',\n 'modified': '2021-09-15T19:22:44.628910Z',\n 'product': 'filseclab',\n 'result': 'malicious',\n 'result_name': 'Trojan.ADC939420BE48D7E',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629048Z',\n 'id': 'relationship--aa86d817-54a7-479b-977e-85cdc653f0be',\n 'modified': '2021-09-15T19:22:44.629048Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc447f63-6ab3-4fc3-807f-7889fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45ee09-d9c1-4f3f-80c0-5e89fd18a656',\n 'modified': '2021-09-15T19:22:44.629191Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629314Z',\n 'id': 'relationship--827b5c4d-e12d-454d-8ced-e361041d2695',\n 'modified': '2021-09-15T19:22:44.629314Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ee09-d9c1-4f3f-80c0-5e89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44db30-d404-4fcb-80ce-6289fd18a656',\n 'modified': '2021-09-15T19:22:44.629455Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629575Z',\n 'id': 'relationship--fc2e7e5f-8e92-427f-a792-2bbc60cd5cfb',\n 'modified': '2021-09-15T19:22:44.629575Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44db30-d404-4fcb-80ce-6289fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44172e-d6a0-4f38-80ba-0189fd18a656',\n 'modified': '2021-09-15T19:22:44.629717Z',\n 'product': 'lionic',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.629835Z',\n 'id': 'relationship--b64b2696-f536-4dc6-afeb-2461ec4749cd',\n 'modified': '2021-09-15T19:22:44.629835Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44172e-d6a0-4f38-80ba-0189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc44609a-145c-4f5d-80a1-e189fd18a656',\n 'modified': '2021-09-15T19:22:44.629969Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Crypt',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630087Z',\n 'id': 'relationship--9e559a2e-d185-49fb-ab26-eb747e99de3c',\n 'modified': '2021-09-15T19:22:44.630087Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44609a-145c-4f5d-80a1-e189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '2019-10-02 10:25',\n 'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc45b73b-fc99-4f74-8075-8789fd18a656',\n 'modified': '2021-09-15T19:22:44.630221Z',\n 'product': 'qihoo-360',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630336Z',\n 'id': 'relationship--95f18068-1342-4021-b3fd-49e3a021b9d0',\n 'modified': '2021-09-15T19:22:44.630336Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45b73b-fc99-4f74-8075-8789fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.157824Z',\n 'id': 'malware-analysis--dc458035-822d-4f07-80d4-0a89fd18a656',\n 'modified': '2021-09-15T19:22:44.630466Z',\n 'product': 'alibaba',\n 'result': 'malicious',\n 'result_name': 'TrojanDownloader:Win32/Waski.aaca15b4',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.630582Z',\n 'id': 'relationship--3a7abb12-86fe-4940-8800-e63b2e483c98',\n 'modified': '2021-09-15T19:22:44.630582Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc458035-822d-4f07-80d4-0a89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45c61c-ddbf-4fbb-80db-cb89fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'},\n {'id': 'bundle--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'objects': [{'aliases': ['Trojan.Win64.CoinMiner',\n 'Trojan.BtcMine.3367',\n 'Trojan.MSIL.qzrf',\n 'Dropper.Agent!8.2F',\n 'Win.Coinminer.Generic-7151250-0',\n 'Trojan.Win32.Trick.fmmuks'],\n 'created': '2021-09-01T19:22:45.178976Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3'}],\n 'first_seen': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-f189fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.178976Z',\n 'malware_types': ['trojan', 'resource-exploitation', 'dropper'],\n 'modified': '2021-09-15T19:22:44.633865Z',\n 'name': 'Trojan.Win64.CoinMiner',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:47.000000Z',\n 'ctime': '2021-09-01T19:22:48.000000Z',\n 'hashes': {'MD5': '6e2757fa246b5bbdac38722930ec2794',\n 'SHA-1': '608604a72d867383a20c1f2f08ba1be61dc31b8b',\n 'SHA-256': '84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3',\n 'SHA-512': '3e70dc8d82c4cba93fe79e3ab10931a5dbb4a67243a9e9b1843135223c3680ef462aa3232b4fe855b85bc8f2cb65fbc0e4d75084abde914a70cf71a10496aca2',\n 'SSDEEP': '49152:FGUzr9GOWh50kC1/dVFdNaeUE3LqW1T/f5iBA9R86DHVVzP7ffQmSumSDr4k:FG6r9GOWPClFdNaeUE3LqW1T/f5iBA9H',\n 'TLSH': 'abb57cbd728502b1d1eec476ca178d0ff7b17a524334a1eb156443ae2e236d98639f32'},\n 'id': 'file--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'mtime': '2021-09-01T19:22:48.000000Z',\n 'name': '84631ab11016280ca401d9775f0938ab31e451d228581944ee4eee3c2d538dc3',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Trojan.Win64.CoinMiner',\n 'Dropper.Agent!8.2F',\n 'Trojan.Win32.Trick.fmmuks',\n 'Trojan.MSIL.qzrf',\n 'Trojan.BtcMine.3367',\n 'Win.Coinminer.Generic-7151250-0'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.178976Z',\n 'first_seen': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.178976Z',\n 'modified': '2021-09-15T19:22:44.635847Z',\n 'name': 'Trojan.Win64.CoinMiner',\n 'sample_refs': ['file--dd45aeee-3a07-4f09-80dd-de89fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.636028Z',\n 'id': 'relationship--2ddd2731-d977-4d21-9f42-456a390a9641',\n 'modified': '2021-09-15T19:22:44.636028Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-f189fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45ff41-2a95-4f62-8069-d189fd18a656',\n 'modified': '2021-09-15T19:22:44.636182Z',\n 'product': 'alibaba',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636307Z',\n 'id': 'relationship--dfc0f440-5c7f-4a29-92ff-1a6545dd6d48',\n 'modified': '2021-09-15T19:22:44.636307Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45ff41-2a95-4f62-8069-d189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc445ec3-809e-4f9a-8052-1089fd18a656',\n 'modified': '2021-09-15T19:22:44.636443Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'Trojan.BtcMine.3367',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636561Z',\n 'id': 'relationship--e32c8ee3-1d9b-4eba-87f4-6bbb61741469',\n 'modified': '2021-09-15T19:22:44.636561Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc445ec3-809e-4f9a-8052-1089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44186b-960c-4f21-8012-5589fd18a656',\n 'modified': '2021-09-15T19:22:44.636694Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.636812Z',\n 'id': 'relationship--308f92fb-ecdc-40a8-9245-b40c601ff795',\n 'modified': '2021-09-15T19:22:44.636812Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44186b-960c-4f21-8012-5589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44dd7a-4c15-4f86-8034-1b89fd18a656',\n 'modified': '2021-09-15T19:22:44.636948Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637101Z',\n 'id': 'relationship--9148f1a1-b66c-4bde-b0f6-819ad558607a',\n 'modified': '2021-09-15T19:22:44.637101Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44dd7a-4c15-4f86-8034-1b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': 'ClamAV 0.102.4/26281/Wed Sep 1 '\n '08:21:58 2021',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44f633-e3e2-4f0c-802b-9989fd18a656',\n 'modified': '2021-09-15T19:22:44.637241Z',\n 'product': 'clamav',\n 'result': 'malicious',\n 'result_name': 'Win.Coinminer.Generic-7151250-0',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637359Z',\n 'id': 'relationship--f48af396-db6d-44b8-9e71-57a713d6f47f',\n 'modified': '2021-09-15T19:22:44.637359Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f633-e3e2-4f0c-802b-9989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc445857-1da9-4f82-80f3-1989fd18a656',\n 'modified': '2021-09-15T19:22:44.637492Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637610Z',\n 'id': 'relationship--23dd6ac8-5b49-4353-b54e-392bc524126e',\n 'modified': '2021-09-15T19:22:44.637610Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc445857-1da9-4f82-80f3-1989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '0.14.35.19132',\n 'analysis_engine_version': '1.0.134.90676',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45a504-0f2e-4ff6-80d4-1989fd18a656',\n 'modified': '2021-09-15T19:22:44.637743Z',\n 'product': 'nanoav',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Trick.fmmuks',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.637861Z',\n 'id': 'relationship--d12b3cab-fdf5-4bbe-b48b-9ce9ffa00e11',\n 'modified': '2021-09-15T19:22:44.637861Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45a504-0f2e-4ff6-80d4-1989fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc440050-76f9-4f3c-8038-9e89fd18a656',\n 'modified': '2021-09-15T19:22:44.637995Z',\n 'product': 'rising',\n 'result': 'malicious',\n 'result_name': 'Dropper.Agent!8.2F',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638121Z',\n 'id': 'relationship--0a1c9971-36b9-482e-b117-39ecc03c5ed5',\n 'modified': '2021-09-15T19:22:44.638121Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc440050-76f9-4f3c-8038-9e89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc45f7a9-3354-4f02-80ad-bc89fd18a656',\n 'modified': '2021-09-15T19:22:44.638263Z',\n 'product': 'filseclab',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638383Z',\n 'id': 'relationship--5f2cb4a5-94d2-49f0-abc5-dd2ea9795a07',\n 'modified': '2021-09-15T19:22:44.638383Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc45f7a9-3354-4f02-80ad-bc89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc446861-42b0-4f55-804a-0389fd18a656',\n 'modified': '2021-09-15T19:22:44.638518Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win64.CoinMiner',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.638636Z',\n 'id': 'relationship--c4056dc0-23e5-4b36-8d50-4cc1dafd9958',\n 'modified': '2021-09-15T19:22:44.638636Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc446861-42b0-4f55-804a-0389fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44bf82-a407-4fd6-800d-ab89fd18a656',\n 'modified': '2021-09-15T19:22:44.638769Z',\n 'product': 'lionic',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.639014Z',\n 'id': 'relationship--0c2bccc2-ff2c-4b56-9088-e2b93e8abf91',\n 'modified': '2021-09-15T19:22:44.639014Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44bf82-a407-4fd6-800d-ab89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.178976Z',\n 'id': 'malware-analysis--dc44455e-f135-4f64-809d-8d89fd18a656',\n 'modified': '2021-09-15T19:22:44.639160Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Trojan.MSIL.qzrf',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.639281Z',\n 'id': 'relationship--855479ed-53f2-4368-95d3-92340d4a68fb',\n 'modified': '2021-09-15T19:22:44.639281Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44455e-f135-4f64-809d-8d89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd45aeee-3a07-4f09-80dd-de89fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'},\n {'id': 'bundle--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'objects': [{'aliases': ['Backdoor.6536F84D7F60AA9C',\n 'win/malicious',\n 'Malware:Win32/Dorpal.ali1000029',\n 'BackDoor.Golf.260',\n 'Backdoor.Generic.ztr',\n 'Trojan.Win32.Urelas',\n 'Backdoor.Plite!8.2D6',\n 'Win.Malware.Urelas-6840420-0'],\n 'created': '2021-09-01T19:22:45.194687Z',\n 'external_references': [{'source_name': 'polyswarm-report',\n 'url': 'https://polyswarm.network/scan/results/file/ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3'}],\n 'first_seen': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware--de44e0eb-0e97-4fa4-80ab-e089fd18a656',\n 'is_family': True,\n 'last_seen': '2021-09-01T19:22:45.194687Z',\n 'malware_types': ['backdoor', 'virus', 'trojan'],\n 'modified': '2021-09-15T19:22:44.642432Z',\n 'name': 'Urelas',\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'atime': '2021-09-01T19:22:50.000000Z',\n 'ctime': '2021-09-01T19:22:50.000000Z',\n 'hashes': {'MD5': 'f5b78e02928c276f22be13313d37bcb4',\n 'SHA-1': 'e024f5d831e101d4d7748fe3d0792e72f4762ff0',\n 'SHA-256': 'ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3',\n 'SHA-512': '66727aa1e7c24987b515ff42704b35a89d4ea5d3c62d32649f158218628344b30adfaa8a61967124592969f7301930588e472a618b5eed0b629c509d114e3b28',\n 'SSDEEP': '1536:s1baYkjUIKECOmxUNKwhB+GT/4I2fm3w9Rri+pXmf8t1dn4vcj0:sjIKn1xUswhsGTgI23RGUXmUDg',\n 'TLSH': '22d3cf4566010894f71c0b721a02fad0889dae7c65d6fa5ff1bc7d7ab932183a97309f'},\n 'id': 'file--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'mtime': '2021-09-01T19:22:50.000000Z',\n 'name': 'ce50012446934e7ad42c209a12e377a9594930f788c659b32b5344bbc7ef5fb3',\n 'spec_version': '2.1',\n 'type': 'file'},\n {'aliases': ['Backdoor.6536F84D7F60AA9C',\n 'win/malicious',\n 'Malware:Win32/Dorpal.ali1000029',\n 'BackDoor.Golf.260',\n 'Backdoor.Generic.ztr',\n 'Trojan.Win32.Urelas',\n 'Backdoor.Plite!8.2D6',\n 'Win.Malware.Urelas-6840420-0'],\n 'confidence': 99,\n 'created': '2021-09-01T19:22:45.194687Z',\n 'first_seen': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'is_family': False,\n 'last_seen': '2021-09-01T19:22:45.194687Z',\n 'modified': '2021-09-15T19:22:44.644475Z',\n 'name': 'Urelas',\n 'sample_refs': ['file--dd44bb23-4668-4f3b-80c3-d589fd18a656'],\n 'spec_version': '2.1',\n 'type': 'malware'},\n {'created': '2021-09-15T19:22:44.644702Z',\n 'id': 'relationship--d1f3b112-02c4-4ea8-b36d-56c871f3da91',\n 'modified': '2021-09-15T19:22:44.644702Z',\n 'relationship_type': 'variant-of',\n 'source_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--de44e0eb-0e97-4fa4-80ab-e089fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': '2',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ef20-ce6a-4f5a-8060-d389fd18a656',\n 'modified': '2021-09-15T19:22:44.644858Z',\n 'product': 'crowdstrike-falcon-ml',\n 'result': 'malicious',\n 'result_name': 'win/malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.644982Z',\n 'id': 'relationship--d5a07ca3-fcbe-4722-92e8-16a6ac82da9e',\n 'modified': '2021-09-15T19:22:44.644982Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ef20-ce6a-4f5a-8060-d389fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ff03-52a3-4f74-8059-1289fd18a656',\n 'modified': '2021-09-15T19:22:44.645144Z',\n 'product': 'jiangmin',\n 'result': 'malicious',\n 'result_name': 'Backdoor.Generic.ztr',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645264Z',\n 'id': 'relationship--4b08404d-64e3-44ae-99ab-8017944749ad',\n 'modified': '2021-09-15T19:22:44.645264Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ff03-52a3-4f74-8059-1289fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '6.100',\n 'analysis_engine_version': '5.5.1',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44f830-1712-4fcc-80e6-1089fd18a656',\n 'modified': '2021-09-15T19:22:44.645396Z',\n 'product': 'secureage',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645514Z',\n 'id': 'relationship--937a07aa-bc4f-4039-94b7-34c586f42703',\n 'modified': '2021-09-15T19:22:44.645514Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f830-1712-4fcc-80e6-1089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '69971A0908A7EC9BE1CDAA21B8EFE918, '\n '2020-Nov-23 22:42:22',\n 'analysis_engine_version': '7.00.49.09080',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc443af4-a14c-4f37-8028-7b89fd18a656',\n 'modified': '2021-09-15T19:22:44.645648Z',\n 'product': 'drweb',\n 'result': 'malicious',\n 'result_name': 'BackDoor.Golf.260',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.645765Z',\n 'id': 'relationship--09473b27-7c9e-4c41-bacb-b507e2a59900',\n 'modified': '2021-09-15T19:22:44.645765Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc443af4-a14c-4f37-8028-7b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44bea2-b17e-4fb6-80e1-2c89fd18a656',\n 'modified': '2021-09-15T19:22:44.645898Z',\n 'product': 'filseclab',\n 'result': 'malicious',\n 'result_name': 'Backdoor.6536F84D7F60AA9C',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646016Z',\n 'id': 'relationship--c9070ece-6c17-4af8-843b-8c9506acd11a',\n 'modified': '2021-09-15T19:22:44.646016Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44bea2-b17e-4fb6-80e1-2c89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44cd9a-0c37-4f5e-808c-4189fd18a656',\n 'modified': '2021-09-15T19:22:44.646147Z',\n 'product': 'alibaba',\n 'result': 'malicious',\n 'result_name': 'Malware:Win32/Dorpal.ali1000029',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646281Z',\n 'id': 'relationship--fdf11db2-f58b-4b3e-b5ac-eafd5aae5fff',\n 'modified': '2021-09-15T19:22:44.646281Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44cd9a-0c37-4f5e-808c-4189fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44ef5d-f3cf-4ff5-8048-6089fd18a656',\n 'modified': '2021-09-15T19:22:44.646417Z',\n 'product': 'lionic',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646531Z',\n 'id': 'relationship--4c9040a8-e18c-4e18-9719-bd1d0aea4b84',\n 'modified': '2021-09-15T19:22:44.646531Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44ef5d-f3cf-4ff5-8048-6089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '01.09.2021 18:16:19 (104093)',\n 'analysis_engine_version': '5.6.2.0',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44f324-c769-4fb0-805e-4089fd18a656',\n 'modified': '2021-09-15T19:22:44.646661Z',\n 'product': 'ikarus',\n 'result': 'malicious',\n 'result_name': 'Trojan.Win32.Urelas',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.646777Z',\n 'id': 'relationship--6c4ae8f4-6834-463f-bd8a-7f48897802c6',\n 'modified': '2021-09-15T19:22:44.646777Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44f324-c769-4fb0-805e-4089fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '2019-10-02 10:25',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc4461c1-5f2a-4f35-80dd-e589fd18a656',\n 'modified': '2021-09-15T19:22:44.646906Z',\n 'product': 'qihoo-360',\n 'result': 'benign',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647020Z',\n 'id': 'relationship--af73da52-3871-4627-89d9-dec1a1da70bb',\n 'modified': '2021-09-15T19:22:44.647020Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc4461c1-5f2a-4f35-80dd-e589fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44b4fb-d3f9-4f32-80ef-6489fd18a656',\n 'modified': '2021-09-15T19:22:44.647162Z',\n 'product': 'rising',\n 'result': 'malicious',\n 'result_name': 'Backdoor.Plite!8.2D6',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647277Z',\n 'id': 'relationship--7d6c1a5b-b470-44cc-9518-deaedfe23236',\n 'modified': '2021-09-15T19:22:44.647277Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44b4fb-d3f9-4f32-80ef-6489fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_definition_version': '48872546c2e9031cb99dc29783b079288f18c6f8-Release.x64',\n 'analysis_engine_version': '4.7.0.10',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc44beb6-1678-4f7b-801f-2b89fd18a656',\n 'modified': '2021-09-15T19:22:44.647410Z',\n 'product': 'sentinelone-static-ml',\n 'result': 'malicious',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647525Z',\n 'id': 'relationship--ee17c47a-9768-4f6f-8cf8-446a4a34d524',\n 'modified': '2021-09-15T19:22:44.647525Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc44beb6-1678-4f7b-801f-2b89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'},\n {'analysis_engine_version': 'ClamAV 0.102.4/26090/Wed Feb 24 '\n '12:09:42 2021',\n 'created': '2021-09-01T19:22:45.194687Z',\n 'id': 'malware-analysis--dc446b6b-1a0d-4f7c-806c-4c89fd18a656',\n 'modified': '2021-09-15T19:22:44.647653Z',\n 'product': 'clamav',\n 'result': 'malicious',\n 'result_name': 'Win.Malware.Urelas-6840420-0',\n 'spec_version': '2.1',\n 'type': 'malware-analysis'},\n {'created': '2021-09-15T19:22:44.647769Z',\n 'id': 'relationship--56e75fba-6af7-4cec-9482-dabcb866ea6d',\n 'modified': '2021-09-15T19:22:44.647769Z',\n 'relationship_type': 'av-analysis-of',\n 'source_ref': 'malware-analysis--dc446b6b-1a0d-4f7c-806c-4c89fd18a656',\n 'spec_version': '2.1',\n 'target_ref': 'malware--dd44bb23-4668-4f3b-80c3-d589fd18a656',\n 'type': 'relationship'}],\n 'type': 'bundle'}]\n\n\n#### Filter Parameters {#filter-parameters}\n\nA TAXII Client can request specific content from a TAXII Server by specifying a set of filters included in the URL query parameters of the request to the server.\n\n##### Universal filter parameters\n\nAll of PolySwarm's collections support the following filter parameters:\n\n| URL Query Parameters | Description | Example |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |\n| `added_after` | A single \"T-Syntax\" RFC3339 time stamp that filters objects to only include those objects added after the specified time stamp. If no `added_after` URL query parameter is provided, the server will return the oldest objects matching the request first. For example, if a server has 100 objects (0-99), the server would start at record 0 looking for a match and work its way up from oldest to newest finding 50 (the default & maximum limit) of objects that matched the request. | `2021-09-08T00:00:00Z` |\n| `limit` | A single integer value that indicates the maximum number of objects that to receive in a single response. This must be a positive integer greater than 0 and less than 51. | `25` |\n| `next` | A single opaque string value that indicates the next record or set of records in the data set that the client is requesting. This value never expires and may be used to resume pagination at a later date (if you attempt to resume pagination of objects older than that collection's defined maximum object age, you will resume pagination from that collection's initial page. | `gAAAAAOSmbvF...oRY06o==` |\n\nYou can use supply any these parameters as keyword arguments to `read_taxii_feed`:\n\n```python\nread_taxii_feed(collection, added_after='2021-09-08T00:00:00Z'):\n```\n##### Using the `match[Operate and Optimise
\nOnce your Engine is verified and running in production, the goal shifts from “it works” to “it performs”. This section covers the operational areas that most directly impact:
\n- \n
- Whether you keep receiving bounties \n
- Whether your assertions participate in rewards \n
- How often you win rewards \n
- How much NCT you put at risk \n
Use these pages as an ongoing checklist as you iterate on your Engine.
\nWhat to focus on first
\n- \n
- Reliability
\nKeep your Engine online, fast, and predictable. Late or failed responses reduce earnings and can cause your Engine to be marked Failed. \n - Accuracy
\nImprove decision quality and reduce false positives and false negatives. \n - Bidding Strategy
\nAlign bids with confidence so you are not over-staking on weak signals. \n - NCT Management
\nMaintain enough balance to keep bidding during the arbitration window and avoid running out of funds mid-flight. \n
Reliability
\nReliability determines whether your Engine consistently receives bounties and whether your results arrive in time to participate in rewards. A reliable Engine is predictable, responsive, and safe under load.
\nReliability Criteria
\nYour Engine should:
\n- \n
- Accept engine webhooks consistently over HTTPS \n
- Validate signatures on every request \n
- Return
202 Acceptedquickly \n - Process bounties asynchronously in workers \n
- Post assertions back successfully and on time \n
- Degrade safely (UNKNOWN instead of crashing) \n
Common Failure Points
\n- \n
- Engine webhook endpoint is not reachable (DNS, TLS, firewall) \n
- Signature validation fails (secret mismatch) \n
- Web server blocks on scanning (no queue, no worker separation) \n
- Worker crashes on edge cases (empty bounty, unsupported type) \n
- Artifact downloads fail intermittently (network, timeouts) \n
- Concurrency is too low for configured rate limit \n
- External tools hang (no timeouts) \n
Minimum Operational Checklist
\nAvailability
\n- \n
- Endpoint is publicly reachable over HTTPS \n
- Certificates are valid and renewed automatically \n
- Health check endpoint exists (optional but recommended) \n
Performance
\n- \n
- Engine webhook request returns quickly (do not scan in the request thread) \n
- Worker concurrency supports your configured rate limit \n
- \n
Timeouts are enforced for:
\n- \n
- artifact download \n
- external tool execution \n
- response submission \n
\n
Correct behavior under stress
\n- \n
- Unsupported artifact types return UNKNOWN with bid 0 \n
- Empty or malformed bounties do not crash the service \n
- Retries do not create duplicate assertions (idempotency where possible) \n
Logging and Observability
\nAt minimum log:
\n- \n
- Bounty received (id, type) \n
- Signature validation result \n
- Job queued and started \n
- Analysis finished (verdict, duration) \n
- Assertion post result (success or error) \n
Protecting against “late results”
\nLate results often earn nothing. Reduce “late” outcomes by:
\n- \n
- Enforcing timeouts and returning UNKNOWN when needed \n
- Keeping artifact downloads fast (bandwidth, caching if appropriate) \n
- Avoiding slow startup paths and cold starts \n
- Not overloading workers beyond capacity \n
If your Engine is marked Failed
\nIf your Engine enters a Failed state:
\n- \n
- Fix the underlying reliability issue first \n
- Re-test in the Development Community if needed \n
- Follow your verification recovery process as required by your workflow \n
Protocols and APIs
\nEngines communicate with the PolySwarm Marketplace using:
\n- \n
- Inbound engine webhooks from PolySwarm to your Engine \n
- Outbound callbacks from your Engine to PolySwarm (artifact download and analysis submission) \n
You do not need to implement blockchain interactions.
\nInbound engine webhook, PolySwarm to Engine
\nPolySwarm sends HTTP POST requests to the engine webhook URL configured for your Engine.
HTTPS requirement
\nYour engine webhook endpoint must be publicly reachable over HTTPS using an FQDN.
\n- \n
- Use HTTPS only \n
- Use a fully qualified domain name (FQDN) \n
- You may include a path in the URL \n
Standard headers
\nPolySwarm includes headers on engine webhook calls. Common headers include:
\n- \n
X-POLYSWARM-DELIVERY(unique delivery id) \nX-POLYSWARM-EVENT(event type, for examplebountyorping) \nX-POLYSWARM-SIGNATURE(HMAC signature for sender validation) \n
Header names can vary by implementation, so treat the above as a reference and follow the Engine template you are using.
\nSignature validation
\nYour server should validate that PolySwarm sent the request by verifying the signature header against the raw request body using the shared secret configured for the engine webhook.
\nIf signature validation fails, reject the request (commonly 401 or 403) and do not process the bounty.
Event, ping
\nPing is a connectivity test.
\n- \n
- Method:
POST\n - Event header:
X-POLYSWARM-EVENT: ping\n
Recommended response:
\n- \n
- Status:
202\n - \n
Body:
\n\n{ \"status\": \"OK\" }\n
Event, bounty
\nBounty is the main event. It tells your Engine what to analyze.
\n- \n
- Method:
POST\n - Event header:
X-POLYSWARM-EVENT: bounty\n - Body: JSON bounty payload \n
Typical bounty payload
\nField names vary slightly by tooling, but the concepts are consistent.
\n{\n \"id\": 1234567890,\n \"artifact_type\": \"file\",\n \"artifact_uri\": \"https://api.polyswarm.network/path/to/download\",\n \"expiration\": \"1970-01-01T00:00:00+0000\",\n \"response_url\": \"https://api.polyswarm.network/path/to/respond\",\n \"phase\": \"assertion\",\n \"sha256\": \"optional-for-file\",\n \"mimetype\": \"optional-for-file\",\n \"rules\": {\n \"min_allowed_bid\": 625000000000,\n \"max_allowed_bid\": 1000000000000000000\n }\n}\n\nNote: The above
\nmin_allowed_bidandmax_allowed_bidvalues are in units of NCT-WEI.
Expected engine webhook server behaviour
\nYour engine webhook server should:
\n- \n
- validate signature \n
- enqueue work for a worker \n
- return quickly \n
Recommended success response:
\n- \n
- Status:
202\n - \n
Body:
\n\n{ \"status\": \"ACCEPTED\" }\n
If the payload is invalid (missing required fields), return a client error (commonly 400).
Outbound callbacks, Engine to PolySwarm
\n1) Artifact download (file artifacts)
\nTo fetch a file artifact, your Engine downloads from artifact_uri (or equivalent field).
- \n
- Method:
GET\n - URL:
artifact_uri\n
Expected success:
\n- \n
- Status:
200\n - Response body: binary file content \n
2) Submit analysis (assertion)
\nYour Engine posts the analysis result to response_url (or equivalent field).
- \n
- Method:
POST\n - URL:
response_url\n - Content-Type:
application/json\n
Payload:
\n{\n \"verdict\": \"malicious\",\n \"bid\": 1000000000000000000,\n \"metadata\": {\n \"malware_family\": \"EICAR-TEST-FILE\",\n \"confidence\": 1.0,\n \"scanner\": {\n \"version\": \"1.0.0\",\n \"environment\": {\n \"operating_system\": \"Linux\",\n \"architecture\": \"x86_64\"\n }\n }\n }\n}Rules:
\n- \n
bidmust be an integer in NCT-wei \n- bids must respect
min_allowed_bidandmax_allowed_bid\n unknownand unsupported cases should return bid 0 \n- metadata is optional but recommended, keep it stable and meaningful \n
Required behaviour summary
\n- \n
- validate signature on inbound engine webhooks \n
- return
202quickly and scan asynchronously \n - fetch artifacts from the provided URI and enforce timeouts \n
- post a correctly formatted analysis to the provided response URL before expiration \n
- return
UNKNOWNfor unsupported types, failures, and timeouts \n
End-to-end testing in the Development Community
\nThis page covers end-to-end testing against PolySwarm using the Development Community. It validates that your Engine can receive real bounties via engine webhook and send valid assertions back to the marketplace.
\nBefore you start
\nYou should have:
\n- \n
- Completed local tests on the Engine template (see Testing your Engine) \n
- \n
A running engine webhook service that:
\n- \n
- Validates signatures \n
- Returns 202 quickly \n
- Processes bounties asynchronously \n
- Posts assertions back to the provided response endpoint \n
\n
Process
\nStep 1 - Create an engine webhook in the PolySwarm UI
\nIn your Team account:
\n- \n
- Create a new engine webhook endpoint \n
- Set the shared secret (store it securely) \n
- Configure the URL to your engine webhook server (must be reachable from PolySwarm) \n
Step 2 - Attach the engine webhook to your Engine
\nIn your Team account:
\n- \n
- Open your Engine \n
- Attach the engine webhook you created \n
- Confirm the Engine is in a development state for testing \n
Step 3 - Send test bounties
\nRun test bounties appropriate to your Engine type:
\n- \n
- File engine: send an EICAR style test where appropriate \n
- URL engine: send WICAR style test \n
- Also test unsupported artifact types and confirm UNKNOWN is returned safely \n
Your goals:
\n- \n
- Confirm the engine webhook receives the bounty \n
- Confirm the worker processes it \n
- Confirm an assertion is sent back successfully \n
- Confirm the UI shows activity for the Engine \n
Step 4 - Validate expected behavior
\nRequired checks
\n- \n
- Signature validation is enforced (invalid signature requests are rejected) \n
- Response is posted within expected timing \n
- Verdict format is correct \n
- Unknown is used for unsupported artifacts \n
- Errors do not crash the service \n
Recommended checks
\n- \n
- Repeated bounties behave consistently \n
- Metadata is stable and meaningful \n
- Logging is sufficient to debug failures quickly \n
Common failure modes
\n- \n
- \n
Engine webhook never receives bounties
\n- \n
- URL not reachable from the internet \n
- wrong endpoint configured in UI \n
- TLS or firewall issues \n
\n - \n
Requests arrive but are rejected
\n- \n
- Incorrect shared secret \n
- Signature validation mismatch \n
\n - \n
Engine receives bounty but no assertion is posted
\n- \n
- Worker not running \n
- Broker misconfigured \n
- Crash during analysis \n
- Response endpoint call failing (network, auth, formatting) \n
\n - \n
Slow responses
\n- \n
- Analysis running in the web server process instead of the worker \n
- External tools lacking timeouts \n
- Insufficient concurrency \n
\n
Next Steps
\nYou are ready to request verification when:
\n- \n
- End to end dev community tests pass repeatedly \n
- Assertions are valid and timely \n
- Unsupported artifacts return UNKNOWN cleanly \n
- Logs are sufficient to diagnose issues \n
- Reliability is stable under repeated bounties \n
Quickstart
\nThis quickstart gets you from zero to a working Engine template that can analyze a test artifact locally. You will clone the reference repo, install dependencies, run a known-good check, then run the test suite.
\nAll instructions and examples assume that you are using a recent version of Linux and are building an Engine using Python with our reference implementation and associated artifact object library.
\n\n\nOur Python reference Engine implementation and Artifact object library should work in any current x86_64 Operating System.
\nPrerequisites
\n- \n
- Git \n
- Python (use the version supported by the template repo) \n
- A Python virtual environment (recommended) \n
Process
\nStep 1 - Cone
\ngit clone https://github.com/polyswarm/microengine-webhooks-py.gitStep 2 - Install dependencies
\nCreate and activate a virtual environment, then install the template in editable mode with the recommended extras.
\npython3 -m venv psvenv\nsource psvenv/bin/activate\npip install -U pip\npip install -e .[web,gunicorn,tests]Step 3 - Run a known-good local check
\nRun the built-in analyzer checks. You should see a structured result containing a verdict and bid.
\npython -m microenginewebhookspy.engine analyze --check-eicarStep 4 - Run tests
\npytest -vIf this passes, you have a working Engine skeleton and test harness.
\nWhat you have now
\nYou now have an Engine template that:
\n- \n
- Accepts a bounty object locally \n
- Runs an analyzer function \n
- Produces a valid assertion payload (verdict, bid, optional metadata) \n
- Has unit and integration tests you can build on \n
Build your Engine
\nThis page explains how to turn the Engine template into a real detection Engine.
\nAt a high level, your Engine will:
\n- \n
- receive a bounty (artifact + rules + deadlines) \n
- analyze the artifact using your tooling \n
- \n
return an analysis response:
\n- \n
verdict:malicious,benign, orunknown\nbid: how much NCT you stake (within the bounty bid rules) \nmetadata: optional context (for examplemalware_family,confidence) \n
\n
\n\nNote\nSetup and installation steps live in Quickstart. This page focuses on implementation patterns and the analyzer logic.
\n
\n
Core implementation point: analyze(bounty)
\nIn the template, the main implementation point is the analyzer function (commonly named analyze(bounty)).
Your analyzer should:
\n- \n
- branch early on artifact type (and other attributes if needed) \n
- retrieve the artifact (bytes, stream, or temp file path) \n
- run your detection logic (local tool, service, or remote API) \n
- map tool output into a stable
verdict,bid, andmetadata\n
\n
Architectures
\nDepending on the scanning technology you are using, you will typically implement one of these patterns:
\n- \n
- Command Line Scanner \n
- Remote API \n
- Local Service \n
Command Line Scanner
\nIf your tool runs via CLI, update analyze() to:
- \n
- get the artifact (often via a temp file) \n
- run your CLI tool with a timeout \n
- parse output to a stable verdict and metadata \n
- return an analysis dict \n
Tips:
\n- \n
- always enforce timeouts \n
- capture exit codes and stderr \n
- keep output parsing resilient and consistent \n
Remote API
\nIf your tool is a remote API that accepts files and/or URLs:
\n- \n
- get the bounty (and sometimes the artifact) \n
- submit an analysis request to the remote API \n
- poll (or async callback) until completion \n
- parse results \n
- return an analysis dict \n
A key decision is how to pass file artifacts:
\n- \n
- if the remote API can accept a URL to download the sample, prefer passing
artifact_uri\n - otherwise, your Engine will download then upload (slower, more bandwidth) \n
For URL artifacts, you can usually pass bounty.artifact_uri directly as the scan target.
Local Service
\nIf your tool runs locally as a daemon (for example ClamAV):
\n- \n
- download the artifact (bytes or temp file) \n
- connect to the local service (socket/HTTP) \n
- send the artifact or path \n
- parse results \n
- return an analysis dict \n
With local services, you also need surrounding machinery to ensure the service is running before the Engine starts handling bounties.
\n\n
Branching on bounty attributes
\nMany Engines need to take different actions based on the bounty contents, for example:
\n- \n
- Engines that process URLs, domains, and IPs differently \n
- Engines that process both file and URL artifact types \n
- Engines that only support a limited set of file mimetypes \n
The examples below assume polyswarm_engine is available as ps:
import polyswarm_engine as psFile vs URL artifact type
\nBranch early so you either handle the artifact type explicitly or return a safe UNKNOWN response.
\nif ps.is_file_artifact(bounty):\n do_file()\nelse:\n do_url()If you only support one type, reject the others:
\nif not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTEDDetecting IP vs domain vs URL
\nThe bounty does not always indicate whether a URL artifact is an IP, a domain, or a full URL.\nUse bounty.artifact_uri as input to your own parsing and branching:
if ps.is_url_artifact(bounty):\n target = bounty.artifact_uri\n if is_ip(target):\n do_ip_task()\n elif is_domain(target):\n do_domain_task()\n else:\n do_url_task()Detecting mimetypes
\nIf your Engine only supports specific mimetypes, check before scanning:
\nSUPPORTED_MIMETYPES = [\"mimetype1\", \"mimetype2\", \"mimetype3\"]\n\nif ps.is_file_artifact(bounty) and bounty.mimetype in SUPPORTED_MIMETYPES:\n do_file()\nelse:\n return ps.UNSUPPORTED\n
Minimal analyzer example
\nStart by branching on artifact type and returning UNKNOWN for anything you do not support.
\nimport polyswarm_engine as ps\n\n@engine.register_analyzer\ndef analyze(bounty: ps.Bounty) -> ps.Analysis:\n # Only handle file artifacts in this example\n if not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTED\n\n # Download the artifact to a temporary file for scanners that expect a file path\n with ps.ArtifactTempfile(bounty) as path:\n result = my_scanner(path) # Replace with your tooling\n\n # Map your scanner output into PolySwarm analysis fields\n if result.malicious:\n return {\n \"verdict\": ps.MALICIOUS,\n \"bid\": ps.bid_max(bounty),\n \"metadata\": {\n \"malware_family\": result.family,\n \"confidence\": float(result.confidence),\n },\n }\n\n return {\n \"verdict\": ps.BENIGN,\n \"bid\": ps.bid_min(bounty),\n \"metadata\": {\"confidence\": float(result.confidence)},\n }\n
Returning a valid analysis
\nYour return payload must validate against the Engine schema rules.
\nVerdict rules
\nUse verdicts consistently:
\n- \n
MALICIOUS: strong detection \nBENIGN: strong evidence it is clean \nUNKNOWN: unsupported type, failed processing, timeouts, or low confidence \n
Bid rules
\n- \n
- \n
If you return MALICIOUS or BENIGN, your
\nbidmust be within the bounty range:MIN_BID <= bid <= MAX_BID.- \n
MIN_BIDandMAX_BIDare provided in the bounty rules for each bounty. \n
\n - If you return UNKNOWN (including
UNSUPPORTED), yourbidmust be0. \n
Use helpers like ps.bid_min(bounty) and ps.bid_max(bounty) to stay inside the range.
Metadata discipline
\nKeep metadata consistent and meaningful:
\n- \n
- include
malware_familywhen you have a stable family label \n - only include
confidenceif you have a real signal behind it (float0.0to1.0) \n - avoid dumping raw tool output or unbounded strings \n
\n
Bidding
\nBidding expresses confidence with stake.
\n- \n
- start conservative while validating reliability and accuracy \n
- only increase bids where your signal is stable and repeatable \n
- always follow the bid rules for the verdict you return \n
See Bidding Strategy for bid sizing guidance.
","rawMarkdownBody":"\n# Build your Engine\n\nThis page explains how to turn the Engine template into a real detection Engine.\n\nAt a high level, your Engine will:\n1. receive a **bounty** (artifact + rules + deadlines)\n2. analyze the artifact using your tooling\n3. return an **analysis** response:\n - `verdict`: `malicious`, `benign`, or `unknown`\n - `bid`: how much NCT you stake (within the bounty bid rules)\n - `metadata`: optional context (for example `malware_family`, `confidence`)\n\n> **Note**\n> Setup and installation steps live in **Quickstart**. This page focuses on implementation patterns and the analyzer logic.\n\n---\n\n## Core implementation point: `analyze(bounty)`\n\nIn the template, the main implementation point is the analyzer function (commonly named `analyze(bounty)`).\n\nYour analyzer should:\n1. branch early on artifact type (and other attributes if needed)\n2. retrieve the artifact (bytes, stream, or temp file path)\n3. run your detection logic (local tool, service, or remote API)\n4. map tool output into a stable `verdict`, `bid`, and `metadata`\n\n---\n\n## Architectures\n\nDepending on the scanning technology you are using, you will typically implement one of these patterns:\n\n- **Command Line Scanner**\n- **Remote API**\n- **Local Service**\n\n### Command Line Scanner\n\nIf your tool runs via CLI, update `analyze()` to:\n1. get the artifact (often via a temp file)\n2. run your CLI tool with a timeout\n3. parse output to a stable verdict and metadata\n4. return an analysis dict\n\nTips:\n- always enforce timeouts\n- capture exit codes and stderr\n- keep output parsing resilient and consistent\n\n### Remote API\n\nIf your tool is a remote API that accepts files and/or URLs:\n1. get the bounty (and sometimes the artifact)\n2. submit an analysis request to the remote API\n3. poll (or async callback) until completion\n4. parse results\n5. return an analysis dict\n\nA key decision is how to pass file artifacts:\n- if the remote API can accept a URL to download the sample, prefer passing `artifact_uri`\n- otherwise, your Engine will download then upload (slower, more bandwidth)\n\nFor URL artifacts, you can usually pass `bounty.artifact_uri` directly as the scan target.\n\n### Local Service\n\nIf your tool runs locally as a daemon (for example ClamAV):\n1. download the artifact (bytes or temp file)\n2. connect to the local service (socket/HTTP)\n3. send the artifact or path\n4. parse results\n5. return an analysis dict\n\nWith local services, you also need surrounding machinery to ensure the service is running before the Engine starts handling bounties.\n\n---\n\n## Branching on bounty attributes\n\nMany Engines need to take different actions based on the bounty contents, for example:\n- Engines that process URLs, domains, and IPs differently\n- Engines that process both file and URL artifact types\n- Engines that only support a limited set of file mimetypes\n\nThe examples below assume `polyswarm_engine` is available as `ps`:\n\n```py\nimport polyswarm_engine as ps\n```\n\n### File vs URL artifact type\n\nBranch early so you either handle the artifact type explicitly or return a safe UNKNOWN response.\n\n```py\nif ps.is_file_artifact(bounty):\n do_file()\nelse:\n do_url()\n```\n\nIf you only support one type, reject the others:\n\n```py\nif not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTED\n```\n\n### Detecting IP vs domain vs URL\n\nThe bounty does not always indicate whether a URL artifact is an IP, a domain, or a full URL.\nUse `bounty.artifact_uri` as input to your own parsing and branching:\n\n```py\nif ps.is_url_artifact(bounty):\n target = bounty.artifact_uri\n if is_ip(target):\n do_ip_task()\n elif is_domain(target):\n do_domain_task()\n else:\n do_url_task()\n```\n\n### Detecting mimetypes\n\nIf your Engine only supports specific mimetypes, check before scanning:\n\n```py\nSUPPORTED_MIMETYPES = [\"mimetype1\", \"mimetype2\", \"mimetype3\"]\n\nif ps.is_file_artifact(bounty) and bounty.mimetype in SUPPORTED_MIMETYPES:\n do_file()\nelse:\n return ps.UNSUPPORTED\n```\n\n---\n\n## Minimal analyzer example\n\nStart by branching on artifact type and returning UNKNOWN for anything you do not support.\n\n```py\nimport polyswarm_engine as ps\n\n@engine.register_analyzer\ndef analyze(bounty: ps.Bounty) -> ps.Analysis:\n # Only handle file artifacts in this example\n if not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTED\n\n # Download the artifact to a temporary file for scanners that expect a file path\n with ps.ArtifactTempfile(bounty) as path:\n result = my_scanner(path) # Replace with your tooling\n\n # Map your scanner output into PolySwarm analysis fields\n if result.malicious:\n return {\n \"verdict\": ps.MALICIOUS,\n \"bid\": ps.bid_max(bounty),\n \"metadata\": {\n \"malware_family\": result.family,\n \"confidence\": float(result.confidence),\n },\n }\n\n return {\n \"verdict\": ps.BENIGN,\n \"bid\": ps.bid_min(bounty),\n \"metadata\": {\"confidence\": float(result.confidence)},\n }\n```\n\n---\n\n## Returning a valid analysis\n\nYour return payload must validate against the Engine schema rules.\n\n### Verdict rules\n\nUse verdicts consistently:\n- `MALICIOUS`: strong detection\n- `BENIGN`: strong evidence it is clean\n- `UNKNOWN`: unsupported type, failed processing, timeouts, or low confidence\n\n### Bid rules\n\n- If you return **MALICIOUS** or **BENIGN**, your `bid` must be within the bounty range: `MIN_BID <= bid <= MAX_BID`.\n - `MIN_BID` and `MAX_BID` are provided in the bounty rules for each bounty.\n- If you return **UNKNOWN** (including `UNSUPPORTED`), your `bid` must be `0`.\n\nUse helpers like `ps.bid_min(bounty)` and `ps.bid_max(bounty)` to stay inside the range.\n\n### Metadata discipline\n\nKeep metadata consistent and meaningful:\n- include `malware_family` when you have a stable family label\n- only include `confidence` if you have a real signal behind it (float `0.0` to `1.0`)\n- avoid dumping raw tool output or unbounded strings\n\n---\n\n## Bidding\n\nBidding expresses confidence with stake.\n- start conservative while validating reliability and accuracy\n- only increase bids where your signal is stable and repeatable\n- always follow the bid rules for the verdict you return\n\nSee **Bidding Strategy** for bid sizing guidance.\n"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/reference/polyswarm-engine-package-reference.md","frontmatter":{"title":"Polyswarm-engine package reference","excerpt":"A practical guide to the helpers, types, and utilities used in Engine code."},"html":"polyswarm_engine package reference
\npolyswarm_engine is a helper library for building PolySwarm Engines. It is designed to make it easy to:
- \n
- receive a bounty payload (artifact to analyze) \n
- fetch the artifact safely (bytes, stream, or temp file) \n
- return a correctly formatted analysis (verdict, bid, metadata) \n
- use common bidding helpers (min, max, rescale, NCT to wei) \n
This page is a practical overview of the parts most Engine partners use.
\nCore types
\nBounty
\nA Bounty represents an incoming request to analyze an artifact. It includes the artifact type, where to download it, where to send your response, the expiration deadline, and bid rules.
Typical fields you will use:
\n- \n
artifact_type(example:FILEorURL) \nartifact_uri(where to fetch the artifact) \nresponse_uriorresponse_url(where to send your analysis) \nexpiration(deadline) \nrules(includesmin_allowed_bid,max_allowed_bid) \nphase(example:assertionorarbitration) \nsha256,mimetype(commonly present for file artifacts) \n
Your analyzer function receives a Bounty as input.
Analysis
\nAn Analysis is what your Engine returns. The minimum expected shape is:
- \n
verdict:malicious,benign,suspicious, orunknown\nbid: integer in NCT-wei \nmetadata: optional object with extra context \n
Example:
\nreturn {\n \"verdict\": ps.MALICIOUS,\n \"bid\": ps.bid_max(bounty),\n \"metadata\": {\n \"malware_family\": \"ExampleFamily\",\n \"confidence\": 0.92\n }\n}Engine registration
\nEngineManager
\nYou typically register two functions:
\n- \n
@engine.register_head\nUse this to attach static metadata once, then re-use it on every analysis. \n@engine.register_analyzer\nThis is your main scanning function. It runs once per bounty. \n
Example:
\nimport polyswarm_engine as ps\n\nengine = ps.EngineManager(name=\"my-engine\", vendor=\"my-company\")\n\n@engine.register_head\ndef head() -> dict:\n return {\"scanner\": {\"version\": \"1.0.0\"}}\n\n@engine.register_analyzer\ndef analyze(bounty: ps.Bounty) -> ps.Analysis:\n ...Fetching artifacts
\nget_artifact_bytes(bounty)
\nDownloads the artifact and returns bytes. Best for small files or simple logic.
content = ps.get_artifact_bytes(bounty)get_artifact_stream(bounty)
\nReturns a stream-like object so you can forward the artifact to an external service without loading it all into memory.
\nstream = ps.get_artifact_stream(bounty)ArtifactTempfile(bounty)
\nRecommended for file-path tools, it downloads to a temp file and cleans up automatically.
\nwith ps.ArtifactTempfile(bounty) as filepath:\n run_my_scanner(filepath)Artifact type helpers
\nUse these to safely reject unsupported artifact types:
\nif not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTEDCommon helpers:
\n- \n
is_file_artifact(bounty)\nis_url_artifact(bounty)\n
Verdicts and bid rules
\nUse these verdict meanings consistently. Bid rules are enforced by the bounty bid range in the engine webhook payload (min_allowed_bid and max_allowed_bid).
- \n
MALICIOUS: strong detection, providemalware_familywhen possible\nBid must be withinmin_allowed_bidandmax_allowed_bid(bid cannot be0) \nBENIGN: strong evidence it is clean\nBid must be withinmin_allowed_bidandmax_allowed_bid(bid cannot be0) \nSUSPICIOUS: weak indicators, informational only\nBid must be 0 \nUNKNOWN: unsupported, failed processing, timeouts, or low confidence\nBid must be 0 \n
If you cannot justify a bid within the allowed range, return UNKNOWN instead.
Pre-built UNKNOWN responses
\npolyswarm_engine includes standard UNKNOWN responses for common cases:
- \n
ps.SKIPPED\nps.ENCRYPTED\nps.UNSAFE_DECOMPRESSION\nps.UNSUPPORTED\nps.CANNOT_FETCH\n
These are useful to avoid boilerplate and keep behaviour consistent.
\nBidding helpers
\nBids are integers in NCT-wei.
\nUseful helpers:
\n- \n
bid_min(bounty)\nbid_max(bounty)\nbid_range(bounty)\nbid_median(bounty)\nrescale_to_bid(bounty, value, min=0, max=100)\nto_wei(nct_amount)\n
Example, scale a confidence score into the bounty bid range:
\nscore = 85\nbid = ps.rescale_to_bid(bounty, score, min=0, max=100)Best practice summary
\n- \n
- return
202 Acceptedquickly at the engine webhook layer, scan in a worker \n - return
UNKNOWNfor unsupported types, failures, and timeouts \n - keep metadata stable and meaningful, avoid dumping raw tool strings \n
- keep bidding aligned with confidence, start conservative \n
Hunting Zoom-Related Malware
\nThis tutorial will focus on how to use PolySwarm to hunt for Windows samples that potentially related to Zoom.
\nTrendMicro recently published a blog post on some malware exploiting the rise in Zoom popularity.
\nAfter review the article, this malware:
\n- \n
- is a Powershell script, \n
- that embeds a 7zip extractor, and \n
- 7zip-compressed Tor, coinminer (the actual malware) and (legitimate) Zoom installers \n
The malware will cause the victim machine to mine cryptocurrency if the infected computer is powerful enough (notably, has a discrete GPU) over Tor.
\nTrendMicro published a handful of IOCs, including a C2 URL: https://2no.co/1O5aW.
Use Metadata search to find Artifacts that contain this URL:
\n- \n
- via the CLI:
polyswarm search metadata 'strings.urls:*2no.co*1O5aW'\n - via the Python library: \n
query = 'strings.urls:*2no.co*1O5aW'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")We get 1 result, which was not part of the IOCs published by TrendMicro, but is clearly a PowerShell script exactly as described in their blog!
","rawMarkdownBody":"\n# Hunting Zoom-Related Malware\n\nThis tutorial will focus on how to use PolySwarm to hunt for Windows samples that potentially related to Zoom.\n\nTrendMicro recently published [a blog post](https://blog.trendmicro.com/trendlabs-security-intelligence/zoomed-in-a-look-into-a-coinminer-bundled-with-zoom-installer/) on some malware exploiting the rise in Zoom popularity.\n\nAfter review the article, this malware:\n* is a Powershell script,\n* that embeds a [7zip](https://www.7-zip.org/) extractor, and\n* 7zip-compressed [Tor](https://www.torproject.org/), coinminer (the actual malware) and (legitimate) Zoom installers\n\nThe malware will cause the victim machine to mine cryptocurrency if the infected computer is powerful enough (notably, has a discrete GPU) over Tor.\n\nTrendMicro published a handful of IOCs, including a C2 URL: `https://2no.co/1O5aW`.\n\nUse Metadata search to find Artifacts that contain this URL:\n* via the CLI: `polyswarm search metadata 'strings.urls:*2no.co*1O5aW'`\n* via the Python library:\n\n```python\nquery = 'strings.urls:*2no.co*1O5aW'\n\nresults = api.search_by_metadata(query)\n\nfor result in results:\n print(f\"Artifact Attributes: {result.artifact}\")\n```\n\nWe get [1 result](https://polyswarm.network/scan/results/file/ef794ceaf0e181b2ed041374dcd09d9a64c3dd3087c2974c38dd387739646fce), which was not part of the IOCs published by TrendMicro, but is clearly a PowerShell script exactly as described in their blog!"}},{"node":{"fileAbsolutePath":"/opt/buildhome/repo/locale/en-US/engines/proposal-and-account-setup/propose-new-engine.md","frontmatter":{"title":"Propose a New Engine","excerpt":"How to submit an Engine proposal, what information we need, and what happens next."},"html":"Propose a New Engine
\nIf you would like to add a new Engine to the PolySwarm Marketplace, you can submit an Engine proposal from the PolySwarm UI below.
\n\nThis page explains what information we need, what happens after you submit, and how you move from proposal to a verified Engine.
\nSubmission Process
\nThis is the end-to-end path for submitting your proposal and onboarding your Engine.
\nSubmit an Engine proposal
\n- \n
- Provide a short overview of what your Engine detects, how it works, and where it adds value. \n
- Submit via the PolySwarm UI: Engines \n
PolySwarm review
\n- \n
- We review your submission against marketplace guidelines and expected value for users. \n
- \n
Outcome is one of:
\n- \n
- Approved: move to onboarding \n
- Not approved: we respond with the reason and next steps \n
\n
Onboarding
\n- \n
- Complete KYC to confirm who owns and operates the Engine. \n
- Sign the Engine Provider Agreement (required before provisioning). \n
- \n
Confirm the technical deployment model:
\n- \n
- PolySwarm-hosted (we host your Engine) \n
- Partner-hosted (you host your Engine and expose an engine webhook service) \n
\n
NCT Management
\nNCT management is keeping your Engine funded so it can bid consistently, and avoiding unexpected downtime from insufficient balance.
\nWhat Affects your Balance?
\nBids
\n- \n
- When you place a bid, that amount is deducted from your Engine wallet. \n
- If the wallet cannot cover the bid, your participation may be reduced or treated as bid 0. \n
Rewards and penalties
\n- \n
- Rewards arrive after arbitration, typically on a delay of weeks. \n
- That delay means your wallet must fund bids until rewards are paid out. \n
Deposits
\n- \n
- Add NCT to your Engine wallet via the deposit address shown in the PolySwarm UI. \n
Withdrawals
\n- \n
- Reduce wallet balance immediately when initiated. \n
Operating Checklist
\n1. Choose a target minimum balance
\nPick a minimum balance that covers at least the arbitration window for your expected bidding rate.
\nA practical estimate:
\n- \n
- Daily bounties you bid on \n
- Average bid size \n
- Arbitration window duration \n
2. Monitor balance and set a refill threshold
\nDecide a refill point such as:
\n- \n
- “top up when balance drops below X” \n
- “top up weekly if below X” \n
3. Match bidding to wallet reality
\nIf your balance is low:
\n- \n
- Reduce bids temporarily \n
- Bid only on your strongest signal areas \n
- Return UNKNOWN on anything uncertain \n
4. Avoid sudden bid spikes
\nBid spikes can drain your wallet quickly and create a stop-start Engine. Keep bids stable and increase gradually.
\nSigns you need to adjust
\n- \n
- Wallet drops rapidly day over day \n
- You stop participating due to insufficient bid funds \n
- You are overbidding relative to confidence \n
- Your configured rate limit is too high for your current funding level \n
Run your Engines as an Engine Webhook Service
\nThis page explains how to run your Engine as a real engine webhook service, meaning it can receive bounties over HTTP, process them asynchronously, then send assertions back to PolySwarm.
\nArchitecture (what runs where)
\nA typical engine webhook setup has three moving parts:
\nEngine Webhook HTTP Server
\n- \n
- Receives bounty events via HTTP POST \n
- Verifies the request signature \n
- Returns
202 Acceptedquickly \n - Enqueues work for processing \n
Queue and broker
\n- \n
- A message broker such as RabbitMQ \n
- Connects the web server to the worker \n
Worker
\n- \n
- Pulls jobs from the queue \n
- Executes your analyzer logic \n
- Posts the assertion back to the marketplace using the provided response endpoint \n
Prerequisites
\n- \n
- Docker and docker compose (recommended for local development) \n
- A broker URL configured for both the server and the worker \n
Required configuration
\nBoth the HTTP server and worker must share the broker configuration, commonly set via an environment variable such as:
\n- \n
- \n
\nPSENGINE_BROKER_URL(template default example uses AMQP)- \n
- example:
amqp://user:password@rabbitmq:5672\n
\n - example:
You will also configure an engine webhook shared secret (used to validate signatures).
\nRunning locally (recommended path)
\nUse the template repo docker compose example to run:
\n- \n
- Broker \n
- Engine webhook server \n
- Worker \n
- Optional integration helper service for local testing \n
This gives you the closest behavior to production without hand-installing RabbitMQ and process managers.
\n\n\nIf you support a non-docker path, document it as an alternative, but keep docker as the default for Engine partners.
\n
Engine Webhook Security Requirements
\nValidate request signatures
\nYour engine webhook server should verify that incoming requests are truly from PolySwarm.\nThis is typically done via an HMAC signature header using a shared secret configured in your Team account engine webhook.
\nRequirements:
\n- \n
- Reject unsigned requests \n
- Reject invalid signatures \n
- Do not run analysis for invalid requests \n
Return quickly
\nYour HTTP server should not block while scanning.
\n- \n
- Return
202 Acceptedimmediately after validation \n - Enqueue work for the worker to process \n
Replay protection
\nIf your engine webhook includes a delivery id or request id, log it and ensure duplicates do not trigger duplicate processing.
\nOperational expectations (development)
\n- \n
- Log at least: request received, request validated, job queued, analysis completed, assertion posted \n
- Enforce timeouts on any external tools \n
- Ensure crashes do not take down both the server and worker \n
- Prefer a small, stable set of environment variables over hardcoding values \n
Testing your Engine
\nBefore you run your Engine as an engine webhook service or request verification, your Engine should pass a minimum set of local tests. This prevents the most common failure modes during Development Community testing and verification.
\nMinimum Quality Gate (required)
\n1 - Structure validation
\nYour analyzer must always return a valid analysis object:
\n- \n
- verdict is always present \n
- bid is always an integer \n
- metadata is optional, but if confidence is provided it must be 0.0 to 1.0 \n
2 - Empty bounty handling
\nYour Engine should handle an empty or minimal bounty without crashing.
\nRun:
\npython -m microenginewebhookspy.engine analyze --check-emptyExpected:
\n- \n
- no exceptions \n
- returns UNKNOWN (or a safe default) with bid 0 \n
3 - Known-good checks
\nUse the built-in checks relevant to your Engine type.
\nFile Engines:
\npython -m microenginewebhookspy.engine analyze --check-eicarURL Engines:
\npython -m microenginewebhookspy.engine analyze --check-wicar4 - Unsupported artifact types
\nIf a bounty is outside your scope, return UNKNOWN with bid 0.
\nExample expectation:
\n- \n
- File engine receives URL bounty, returns UNKNOWN \n
- URL engine receives file bounty, returns UNKNOWN \n
Recommended additional tests
\n- \n
- Determinism: same input yields same verdict and stable metadata \n
- Timeout behavior: slow backends return UNKNOWN rather than hanging indefinitely \n
- Error mapping: backend errors become UNKNOWN, not 500 crashes \n
- Metadata sanity: malware_family present only when meaningful, confidence only when justified \n
PolySwarm Rest API v3
\nRest API Endpoints for interacting with version 3 of the PolySwarm Customer APIs.
\nGetting Started
\nUsing the API
\nPolySwarm's API provides a RESTful interface for various PolySwarm features.\nIf you'd like to report an issue or provide feedback for this page, please contact customersuccess@polyswarm.io
\nThe PolySwarm API is available at https://api.polyswarm.network/v3
\nFor 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.
\nCommunity (free) users have a limit of 60 calls per hour, Paying Enterprise Customers have a limit of 1000 calls per second.\nEach feature (i.e. Scanning) may have its own set monthly quota, and utilize a daily or monthly api limit too. See the team's usage page to better understand these numbers.
\nAuthentication
\nEvery API request must include an HTTP Authorization Header with an API key.
\nLocate the api_key for the User/Team from here
| HTTP Header | \nValue | \n
|---|---|
| Authorization | \nAPI Key | \n
Example:
\ncurl -X GET -H \"Authorization: $API_KEY\" 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default'Retrieve account information
\nAccount details
\n/v3/public/accounts/whois
Query Sample
\ncurl https://api.polyswarm.network/v3/public/accounts/whois -H \"Authorization: $POLYSWARM_API_KEY\"Account features and quotas
\n/v3/public/accounts
Query Sample
\ncurl https://api.polyswarm.network/v3/public/accounts -H \"Authorization: $POLYSWARM_API_KEY\"Pagination and Offset Handling
\nWhen interacting with paginated endpoints, each page of results consumes one quota unit.
\nKey Points on Pagination:
\n- \n
- The
has_moreflag indicates whether additional pages of results are available. \n - If
has_more=true, the response will include an encrypted offset value. \n - For the first request, specify a
limitparameter (e.g.,limit=50). The server will return anoffsetvalue for the next page in the response. \n - For subsequent requests, include the
offsetvalue returned by the server in the previous response. The server will always provide the nextoffset, which must be sent back unmodified in subsequent calls. \n
Example Initial Request
\ncurl -H 'Authorization: <API_KEY>' 'https://api.polyswarm.network/v3/hunt/live/list?limit=50&timeout=30'The response will include an offset value for the next page.
Example Subsequent Request
\ncurl -H 'Authorization: <API_KEY>' 'https://api.polyswarm.network/v3/hunt/live/list?limit=50&timeout=30&offset=<OFFSET>'\n\nNote: The offset is an encrypted token generated by the server. Clients must use it as-is and not attempt to modify it.
\n
Hash Search and Collision Handling
\nFor the Hash Search endpoint, the has_more flag will typically return false. However, consider the following:
- \n
- A sha256 collision is highly unlikely, but not impossible. \n
- Collisions are more probable with weaker hash algorithms like md5 or sha1. \n
To address potential risks:
\n- \n
- Use the
has_moreflag to manage collisions, particularly when working with md5 or sha1. \n - Decide whether to rely on this flag based on your specific use case and risk tolerance. \n
Artifact Lookup
\nTo 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.
\nGET /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.\nIf the value failed is true then the scan has failed.
Scanning Artifacts
\nThe following are the 3 sequential steps in a Scanning operation:
\n- \n
- POST Inform PolySwarm to start a scan, returns an
artifact_idand pre signed AWS URL that the artifact can be uploaded to \n - PUT Upload the artifact to the AWS URL location \n
- PUT Inform PolySwarm that the artifact is uploaded and to start the scan \n
Lastly, lookup the artifact for the verdict, follow this process here.
\nURL Scanning
\nPOST /v3/instance
\n\nInform PolySwarm to start a scan, returns an
\nartifact_idand pre signed AWS URL that the file/url can be uploaded to
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
artifact_name | \nstring | \ntrue | \nURL value to be scanned. | \n
artifact_type | \nstring | \ntrue | \nDefines the type, should be URL. | \n
scan_config | \nstring | \nfalse | \nAllows additional time for the scan, default if not provided, default, more-time, most-time. | \n
url-file | \nstring | \nfalse | \nPath of the file containing a single line of the URL to be scanned. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
preprocessing | \nobject | \nfalse | \nSet to {\"type\": \"qrcode\"} if the URL is inside a QR Code image. | \n
Query Sample
\ncurl -X POST -d '{\n \"artifact_name\": \"https://www.google.com\",\n \"artifact_type\": \"URL\",\n \"scan_config\": \"most-time\",\n \"community\": \"default\"\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/instanceHere is a sample of how to scan a URL that is inside a QR Code image:
\ncurl -X POST -d '{\n \"artifact_name\": \"qrcode.png\",\n \"artifact_type\": \"URL\",\n \"community\": \"default\",\n \"preprocessing\": {\"type\": \"qrcode\"}\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/instance\n
PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}
\n\nProvide the artifact to upload to the AWS URL.
\n
Query Sample
\ncurl -X PUT '<PRE_SIGNED_AWS_URL>' -d 'content=www.google.com'\n
PUT /v3/instance
\n\nInform PolySwarm the upload is complete and to start the scan.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \nstring | \ntrue | \nartifact_id that has been returned by the first POST command. | \n
Query Sample
\ncurl -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.
\nFile Scanning
\nPOST /v3/instance
\n\nInform PolySwarm to start a scan, returns an
\nartifact_idand pre signed AWS url that the file needs to be placed into.
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
artifact_name | \nstring | \ntrue | \nPath of the File to be scanned. | \n
artifact_type | \nstring | \ntrue | \nDefines the type, should be FILE. | \n
preprocessing | \nobject | \nfalse | \nPreprocessing settings to be applied to the artifact. See schema table bellow. | \n
expiration_window | \nint | \nfalse | \nApplies to Private Communities only and affects new uploads. After the configured number of days, the binary file is deleted, but the metadata remains available, so the hash can still be searched. Must be 30 or 180. | \n
scan_config | \nstring | \nfalse | \nAllows additional time for the scan, default if not provided, default, more-time, most-time. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Body / Preprocessing Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
type | \nstring | \ntrue | \nEither zip, 7zip, base64, orqrcode, the first two 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\"). | \n
password | \nstring | \nfalse | \nUse this password to decompress the zip file. | \n
|
\nQuery Sample
\nScan a file install.exe example:
curl -X POST -d '{\n \"artifact_name\": \"install.exe\",\n \"artifact_type\": \"FILE\",\n \"community\": \"default\"\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/instanceThe file to scan is inside an encrypted zip:
\ncurl -X POST -d '{\n \"artifact_name\": \"install.exe\",\n \"artifact_type\": \"FILE\",\n \"community\": \"default\",\n \"preprocessing\": {\"type\": \"zip\", \"password\": \"password\"}\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/instance\n
PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}
\n\nProvide the artifact to upload to the AWS URL.
\n
Query Sample
\ncurl --upload-file ./tests/eicar.yara \"<PRE_SIGNED_AWS_URL>\"\n
PUT /v3/instance
\n\nInform PolySwarm the upload is complete and to start the scan.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \nstring | \ntrue | \nartifact_id that has been returned by the first POST command. | \n
Query Sample
\ncurl -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.
\nRescanning Artifacts
\nPOST /v3/consumer/submission/default/rescan/sha256/{sha256}
\n\nOther Endpoints include:
\n/v3/consumer/submission/default/rescan/md5/{md5}and/v3/consumer/submission/default/rescan/sha1/{sha1}
\n\nThis endpoint can only be used to rescan files, for urls see rescan by id below.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
hash-type | \nstring | \nfalse | \nHash type to be searched on, default is autodetect. | \n
scan-config | \nstring | \nfalse | \nConfiguration template to use, provides more time for the results to be returned, default, more-time, most-time. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -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.
\nRescanning Artifacts by ID
\nPOST /v3/consumer/submission/{community}/rescan/{id}
\n\nRescan an existing artifact by its
\nartifact_id(also referred to asinstance_id) rather than by hash. The community (defaultorprivate) is specified as part of the URL path, include this.
Path Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community in the URL path. Use default for the public community, or private for your Private Community. | \n
id | \ninteger | \ntrue | \nartifact_id of the artifact to rescan. | \n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
scan-config | \nstring | \nfalse | \nConfiguration template to use, provides more time for the results to be returned, default, more-time, most-time. | \n
Query Sample
\ncurl -X POST 'https://api.polyswarm.network/v3/consumer/submission/private/rescan/3147283219576984' -H \"Authorization: $API_KEY\"Query Sample with scan-config in private
\ncurl -X POST 'https://api.polyswarm.network/v3/consumer/submission/private/rescan/3147283219576984?scan_config=more-time' -H \"Authorization: $API_KEY\"Lastly, lookup the artifact for the verdict, follow this process here.
\nDownloading
\nDownload an Artifact
\nGET /v3/consumer/download/sha256/{sha256}
\n\nOther Endpoints include:
\n/v3/consumer/download/sha256/{md5}and/v3/consumer/download/sha256/{sha1}
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
hash-type | \nstring | \nfalse | \nHash type to be searched on, default is autodetect. | \n
destination | \nstring | \nfalse | \nLocal Path where to store the downloaded files. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/consumer/download/sha256/5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default' -H \"Authorization: $API_KEY\"Download via id
\nGET /v3/instance/download
\n\nTip: Can be used to download reports and files from a sandbox detonation, see sandboxing sections to retrieve the
\ninstance_id.
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
instance_id | \ninteger | \ntrue | \ninstance_id of the item to download, often provided in the output of a previous query. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/instance/download?instance_id=84432173138232095' -H \"Authorization: $API_KEY\"Download Bundle
\nCreate the Bundle
\nPOST /v3/bundle
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
instance-ids | \nstring array | \ntrue | \nThe ID's of an instance to include in the bundle archive. | \n
preserve_filenames | \nboolean | \nfalse | \nPreserve the names of the files in the bundle. | \n
filename | \nstring | \nfalse | \nName of the archive that will be created. | \n
community | \nstring | \ntrue | \nDefine the community either private or public. | \n
Query Sample
\ncurl -X POST \"https://api.polyswarm.network/v3/bundle\" \\\n -H \"Authorization: $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"instance_ids\": [\"51375268900310741\", \"58964500531258633\"], \"preserve_filenames\": true, \"filename\": \"output-archive.zip\"}' \\\n
Check Status of Bundle
\nGET /v3/bundle
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \nstring | \ntrue | \nThe Bundle Task ID Returned in step 1. | \n
community | \nstring | \ntrue | \nDefine the community either private or public. | \n
Query Sample
\ncurl -X GET \"https://api.polyswarm.network/v3/bundle?id=41476135624684596&community=private\" -H \"Authorization: $POLYSWARM_API_KEY\"\n
Download the Bundle
\nGET https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}
\n\nNote: The previous GET command returns the
\nPRE_SIGNED_AWS_URLonce the report generation has been completed.
Query Sample
\ncurl -o output-archive.zip -X GET 'https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}'Reporting
\nDownloading Reports
\nPolySwarm provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing, these are separate reports.
\nThe following are the 3 sequential steps in a report generation operation:
\n- \n
- POST Inform PolySwarm to start generating the report. \n
- GET Poll PolySwarm to understand when the report has finished generating. \n
- GET Download the report locally once generation is successful. \n
\n
POST /v3/reports
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
format | \nstring | \ntrue | \npdf, html or zip. | \n
type | \nstring | \ntrue | \nscan, sandbox, or sandbox_zip. | \n
community | \nstring | \ntrue | \nDefine the community either private or public. | \n
template_metadata | \nobject | \nfalse | \nChoose 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. | \n
instance_id | \ninteger | \ntrue | \nRequired if generating a scanning report, this is the artifact_id. | \n
sandbox_task_id | \ninteger | \ntrue | \nRequired if generating a sandboxing report or sandbox zip, this is the sandbox_id. | \n
Query Sample Scan Report
\ncurl -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/reportsQuery Sample Sandbox ZIP File
\nThe below example downloads the report json and the pcap files in a single zip file.
\ncurl -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\n
GET /v3/reports
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid returned from the previous POST command. | \n
community | \nstring | \ntrue | \nDefine the community either private or public. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/reports?id=59403308938961820' -H \"Authorization: $API_KEY\"\n
GET https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}
\n\nNote: The previous GET command returns the
\nPRE_SIGNED_AWS_URLonce the report generation has been completed.
Query Sample
\ncurl -o scan-97903321852386706.pdf -X GET 'https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}'Report Templates
\nList templates
\nGET /v3/reports/templates/list
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/reports/templates/list' -H \"Authorization: $API_KEY\"Create a template
\nPOST /v3/reports/templates
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
template_name | \nstring | \ntrue | \nName for the template. | \n
is_default | \nboolean | \nfalse | \nIf true this template will be the default template for the team. | \n
primary_color | \nstring | \nfalse | \nSix-character hex color code. | \n
footer_text | \nstring | \nfalse | \nText to be displayed in the footer of each page. Up to 100 characters are allowed. | \n
last_page_text | \nstring | \nfalse | \nText to be displayed on the last page. Up to 1000 characters are allowed. | \n
includes | \nstring | \nfalse | \nArray list of sections to include in the report. Can be one or more of: \"analysis\", \"detections\", \"droppedFiles\", \"extractedConfig\", \"fileMetadata\", \"network\", \"summary\". | \n
Query Sample
\ncurl -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/templatesDelete a templates
\nDELETE /v3/reports/templates
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template. | \n
Query Sample
\ncurl -X DELETE 'https://api.polyswarm.network/v3/reports/templates?id=10512439389909571' -H \"Authorization: $API_KEY\"Get template details
\nGET /v3/reports/templates
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/reports/templates?id=89035259732911602' -H \"Authorization: $API_KEY\"Update a template
\nPUT /v3/reports/templates
NOTE: despite being a PUT endpoint, only fields passed in the JSON body are updated, the remaining fields retain their values.\nQuery Parameters
| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template. | \n
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
template_name | \nstring | \ntrue | \nName for the template. | \n
is_default | \nboolean | \nfalse | \nIf true this template will be the default template for the team. | \n
primary_color | \nstring | \nfalse | \nSix-character hex color code. | \n
footer_text | \nstring | \nfalse | \nText to be displayed in the footer of each page. Up to 100 characters are allowed. | \n
last_page_text | \nstring | \nfalse | \nText to be displayed on the last page. Up to 1000 characters are allowed. | \n
includes | \nstring | \nfalse | \nArray list of sections to include in the report. Can be one or more of: \"summary\", \"detections\", \"fileMetadata\", \"network\", \"droppedFiles\", \"extractedConfig\", \"analysis\". | \n
Query Sample
\ncurl -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
\nPUT /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.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template | \n
Body Parameters
\nThe body has to be the binary data of the image. Max length allowed is 40 Kb.
\nHeader Parameters
\n| Parameter | \nRequired | \nDescription | \n
|---|---|---|
Content-Type | \ntrue | \nEither image/png or image/jpeg | \n
Query Sample
\nHaving 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
\nDELETE v3/reports/templates/logo
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template. | \n
Query Sample
\ncurl -X DELETE 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H \"Authorization: $API_KEY\"Download template logo
\nGET v3/reports/templates/logo
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid value of the template. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H \"Authorization: $API_KEY\" --output /Users/John/Documents/logo.jpgLLM Reports
\nLLM reports provide AI-generated analysis summaries for both scans and sandbox detonations using language models.
\nFor this to work, the team plan must include access to downloads. This feature consumes one unit from the PolySwarm Intelligence quota per report generated, which covers both the create and download steps.
Create LLM Report
\nPOST /v3/reports/llm
\n\nCreates an LLM report task that will generate an AI-powered analysis summary. The system automatically detects duplicate pending reports and returns the existing one instead of creating a duplicate.
\n
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
instance_id | \ninteger | \nfalse | \nThe artifact_id from a scan submission. Include to add scan results to the LLM report. | \n
cape_sandbox_task_id | \ninteger | \nfalse | \nThe task ID of a Cape sandbox detonation. Include to add Cape sandbox results to the LLM report. | \n
triage_sandbox_task_id | \ninteger | \nfalse | \nThe task ID of a Triage sandbox detonation. Include to add Triage sandbox results to the LLM report. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
\n\nAt least one of
\ninstance_id,cape_sandbox_task_id, ortriage_sandbox_task_idis required. You may combinecape_sandbox_task_idandtriage_sandbox_task_idtogether, optionally alongsideinstance_id, to generate a single unified report from multiple sources.
Query Sample for Scan Report
\ncurl -X POST -d '{\"instance_id\": \"97903321852386706\", \"community\": \"default\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/reports/llmQuery Sample for Cape Sandbox Report
\ncurl -X POST -d '{\"cape_sandbox_task_id\": \"97903321852386706\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/reports/llmQuery Sample for Triage Sandbox Report
\ncurl -X POST -d '{\"triage_sandbox_task_id\": \"97903321852386706\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/reports/llmQuery Sample for Combined Cape + Triage Report
\ncurl -X POST -d '{\"cape_sandbox_task_id\": \"97903321852386706\", \"triage_sandbox_task_id\": \"12345678901234567\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/reports/llm\n
Get LLM Report
\nGET /v3/reports/llm
\n\nRetrieve the status and details of an LLM report task. Use the
\nidreturned from the POST request.
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid returned from the LLM report POST. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/reports/llm?id=12345678901234567&community=default' -H \"Authorization: $API_KEY\"Searching
\nHash Searching
\nGET /v3/search/hash/sha256
\n\nOther Endpoints include:
\n/v3/search/hash/md5and/v3/search/hash/sha1
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
hash | \nstring | \ntrue | \nHash (sha256,md5 or sha1) value to be searched. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
hash-type | \nstring | \nfalse | \nHash type to be searched on, default is autodetect. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/search/hash/sha256?hash=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a&community=default' -H \"Authorization: $API_KEY\"View Scan History
\nGET /v3/search/instances
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
hash | \nstring | \ntrue | \nHash (sha256,md5 or sha1) value to be searched. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/search/instances?hash=95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5&community=default' -H \"Authorization: $API_KEY\"URL Searching
\nGET /v3/search/url
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
url | \nstring | \ntrue | \nURL value to be searched. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default' -H \"Authorization: $API_KEY\"Metadata Searching
\nGET /v3/search/metadata/query
\n\nTo understand how to build out a Metadata query see the How-To Guide.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
query | \nstring | \ntrue | \nMetadata query to search on. | \n
include | \nstring | \nfalse | \nMetadata field to include in results. | \n
exclude | \nstring | \nfalse | \nMetadata field to exclude in results. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/search/metadata/query?query=artifact.sha256:5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H \"Authorization: $API_KEY\"Query Sample
\nThe below query searches for artifacts related to emotet and only return the Triage TTP values, making use of the include option.
curl -X GET 'https://api.polyswarm.network/v3/search/metadata/query?include=triage_sandbox_v0.ttp&query=polyunite.malware_family%3AEmotet&community=default' -H \"Authorization: $API_KEY\"IOC Searching
\n- \n
- Searching for Associated IOCs related to a Hash: This returns IOCs that were observed by our sandbox during analysis. These IP's and Domains are classified as C2 or malicious. \n
- Searching for Associated Hashes related to an IP, URL, imphash or MITRE TTP: This returns file hashes that were seen communicating with the specified IPs or domains in our sandbox — regardless of whether the communication was malicious or not. \n
Search for Associated IOCs
\nGET /v3/ioc/sha256/{sha256}
\n\nOther Endpoints include:
\n/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
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/ioc/sha256/2a85d68c1c503d9b6efcf124ac7d7afc0f3a8a0543f5d6790ebd978f4e8468bd?community=default' -H \"Authorization: $API_KEY\"Search for Associated Hashes
\nGET /v3/ioc/search
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
imphash | \nstring | \nfalse | \nimphash to see related hashes. | \n
domain | \nstring | \nfalse | \ndomain to see related hashes. | \n
ttp | \nstring | \nfalse | \nMITRE ttp to see related hashes. | \n
ip | \nstring | \nfalse | \nIP to see related hashes. | \n
\n\nRequires at least one of the values imphash, domain, ttp or ip in the query.
\n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/ioc/search?ip=193.138.218.74&community=default' -H \"Authorization: $API_KEY\"Sandboxing
\nList Sandboxes
\nGET /v3/sandbox/provider/list
\n\nList the
\nprovider_slugandvm_slugvalues for sandboxing a file and/or artifact.
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/sandbox/provider/list' -H \"Authorization: $API_KEY\"Sandboxing a File/URL
\n\n\nWant to know what files types are supported? See here
\n
POST /v3/sandbox/sandboxtask/instance
\n\nInform PolySwarm to start a sandbox, returns an
\nidvalue in the json 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\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
artifact_name | \nstring | \ntrue | \nPath to File of the artifact to be sandboxed or URL string. | \n
artifact_type | \nstring | \ntrue | \nDefines the type, FILE to Sandbox a file, URL to Sandbox a URL. | \n
preprocessing | \nobject | \nfalse | \nPreprocessing settings to be applied to the artifact. See schema table bellow. | \n
provider_slug | \nstring | \ntrue | \nName of the sandbox to detonate on. For URL Sandboxing only Triage is Supported. | \n
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
vm_slug | \nstring | \ntrue | \nSlug name for the sandbox vm to use, for URL Sandboxing only Windows 10 on Triage is Supported. | \n
browser | \nstring | \nfalse | \nOptional value to choose the browser for URL detonation, only edge supported. | \n
Body / Preprocessing Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
type | \nstring | \ntrue | \nEither 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\"). | \n
password | \nstring | \nfalse | \nUse this password to decompress the zip file. | \n
Query Sample
\nHere is a simple sandboxing POST request:
\ncurl -X POST -d '{\n \"artifact_name\": \"eicar.txt\",\n \"artifact_type\": \"FILE\",\n \"community\": \"default\",\n \"sandbox\": \"cape\"\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/sandbox/sandboxtask/instanceHere is an example using the \"preprocessing\" argument to send an encrypted zip file:
\ncurl -X POST -d '{\n \"artifact_name\": \"target.zip\",\n \"artifact_type\": \"FILE\",\n \"community\": \"default\",\n \"sandbox\": \"cape\",\n \"preprocessing\": {\"type\": \"zip\", \"password\": \"password\"}\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance\n
PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}
\n\nProvide the file to upload to the AWS URL.
\n
Query Sample
\ncurl --upload-file ./tests/eicar.txt \"<PRE_SIGNED_AWS_URL>\"\n
PUT /v3/sandbox/sandboxtask/instance
\n\nInform PolySwarm the upload is complete and to start the sandbox.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \nstring | \ntrue | \nid that has been returned by the first POST command. | \n
community | \nstring | \nfalse | \nprivate or public values for the community` | \n
Query Sample
\ncurl -X PUT 'https://api.polyswarm.network/v3/sandbox/sandboxtask/instance?id=49722305458696948' -H \"Authorization: $API_KEY\"Query Sample
\ncurl -X PUT 'https://api.polyswarm.network/v3/sandbox/sandboxtask/instance?id=49722305458696948&community=private' -H \"Authorization: $API_KEY\"Sandboxes have multiple returned statuses, these are listed below.
\n| Status Name | \nAPI Status Name | \nWhat is it for? | \n
|---|---|---|
Success | \nSUCCEEDED | \nFinished processing correctly. | \n
Started | \nSTARTED | \nSandbox session has started. | \n
Collecting Data | \nCOLLECTING_DATA | \nSandbox session has been successful and data is being collected. | \n
Failed | \nFAILED | \nSandbox session has failed, this can be due to many reasons. | \n
Pending | \nPENDING | \nSandbox session is queued up and ready to start. | \n
Timed out | \nTIMEDOUT | \nSandbox session has timed out and quota has not been reimbursed. | \n
Delayed | \nDELAYED | \nSandbox session has been delayed and will start soon. | \n
Failed with Quota Reimbursement | \nFAILED_REIMBURSED | \nFinished processing but failed, quota will be reimbursed. | \n
Timed out with Quota Reimbursement | \nTIMEDOUT_REIMBURSED | \nDelayed in the queue for too long, got timed out and then reimbursement. | \n
Query every 30 seconds to understand if the Sandbox session has been successful, see the Lookup Sandbox Task section below.
\nSandboxing an Existing Artifact
\nPOST /v3/sandbox/sandboxtask
Send an existing artifact to be sandboxed by providing its artifact id, and the chosen Sandbox provider.
\nBody Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
artifact_id | \ninteger | \ntrue | \nartifact_id value for the artifact. | \n
provider_slug | \nstring | \ntrue | \nSandbox provider name. | \n
community | \nstring | \nfalse | \nprivate or public values for the community` | \n
network_enabled | \nboolean | \nfalse | \ntrue or false defines if you want Internet on Sandbox Detonation. Default true for public communities and false for private ones. | \n
vm_slug | \nstring | \nfalse | \nSlug name for the sandbox vm to use. | \n
Query Sample
\ncurl -X POST -d '{\"artifact_id\": \"66885603025097785\", \"provider_slug\": \"cape\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/sandbox/sandboxtaskLookup Sandbox Task
\nGET /v3/sandbox/sandboxtask
Lookup the results from the specified sandbox task.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
sandbox_task_id | \ninteger | \ntrue | \nsandbox task id value. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask?community=default&sandbox_task_id=29603365297891589' -H \"Authorization: $API_KEY\"Lookup Latest Sandbox Task
\nGET /v3/sandbox/sandboxtask/latest
Lookup the results from the most recent sandbox task that was run on the provided sha256 in the provided sandbox.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
sha256 | \nstring | \ntrue | \nHash value to lookup. | \n
sandbox | \nstring | \ntrue | \nName of the Sandbox, e.g. cape, triage. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/latest?community=default&sandbox=cape&sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H \"Authorization: $API_KEY\"Download Sandbox Artifact
\nTo download Sandbox Artifacts like pcap, jarm or report files follow this section to download via instance_id.
\n\nEach file (pcap,report etc) will have its own
\ninstance_id, these can be found by using the \"Lookup Sandbox Task\" (/v3/sandbox/sandboxtask) command, and each file name will have aninstance_idlisted beside it.
List my Sandbox Tasks
\nGET /v3/sandbox/sandboxtask/my-tasks
Find all sandbox tasks that you or your team members have run in the chosen date range.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
community | \nstring | \ntrue | \nName of the Community. Simplest to use default for the public community, or private for your Private Community. | \n
sandbox | \nstring | \nfalse | \nName of the sandbox to search on. | \n
start-date | \nstring | \nfalse | \nStart date to search. | \n
end-date | \nstring | \nfalse | \nEnd date to search. | \n
user_account_id | \ninteger | \nfalse | \nUser account that created the sandbox task. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/my-tasks?community=default' -H \"Authorization: $API_KEY\"Search Sandbox Tasks
\nGET /v3/sandbox/sandboxtask/list
Find all sandbox tasks associated with a sha256 (i.e. each time that artifact was sandboxed).
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
sha256 | \nstring | \ntrue | \nHash value to find related tasks. | \n
sandbox | \nstring | \nfalse | \nSandbox name to search. | \n
start_date | \nstring | \nfalse | \nStart date for the search, i.e. 2024-09-27 (ISO format). | \n
end_date | \nstring | \nfalse | \nEnd date for the search, i.e. 2024-09-27 (ISO format). | \n
status | \nstring | \nfalse | \nStatus of the sandbox task i.e. PENDING. | \n
account_id | \ninteger | \nfalse | \nAccount that created the sandbox task. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/list?sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H \"Authorization: $API_KEY\"Notification Webhooks
\nNotification webhooks allow you to receive real-time notifications for events in PolySwarm, such as when sandbox analysis completes.
\nCreate a Notification Webhook
\nPOST /v3/notification/webhook
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
webhook_uri | \nstring | \ntrue | \nThe URI where notification webhook events should be sent. | \n
secret | \nstring | \ntrue | \nThe secret key used for HMAC signature verification. | \n
status | \nstring | \nfalse | \nNotification webhook status: enabled or disabled (default: enabled) | \n
events | \narray | \nfalse | \nEvent types to subscribe to (e.g., ['sandbox_done']) | \n
Query Sample
\ncurl -X POST -d '{\n \"webhook_uri\": \"https://example.com/webhook\",\n \"secret\": \"your-secret-key\",\n \"status\": \"enabled\",\n \"events\": [\"sandbox_done\"]\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/notification/webhookGet a Notification Webhook
\nGET /v3/notification/webhook
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nThe ID of the notification webhook. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/notification/webhook?id=12345' -H \"Authorization: $API_KEY\"Update a Notification Webhook
\nPUT /v3/notification/webhook
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nThe ID of the notification webhook. | \n
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
webhook_uri | \nstring | \nfalse | \nThe new notification webhook URI. | \n
secret | \nstring | \nfalse | \nThe new secret for HMAC signing. | \n
status | \nstring | \nfalse | \nThe new status: enabled or disabled. | \n
events | \narray | \nfalse | \nEvent types to subscribe to. | \n
Query Sample
\ncurl -X PUT -d '{\n \"webhook_uri\": \"https://newexample.com/webhook\",\n \"status\": \"disabled\"\n}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/notification/webhook?id=12345Delete a Notification Webhook
\nDELETE /v3/notification/webhook
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nThe ID of the notification webhook. | \n
Query Sample
\ncurl -X DELETE 'https://api.polyswarm.network/v3/notification/webhook?id=12345' -H \"Authorization: $API_KEY\"List All Notification Webhooks
\nGET /v3/notification/webhook/list
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
limit | \ninteger | \nfalse | \nNumber of results per page (default: 50). | \n
offset | \nstring | \nfalse | \nPagination offset token returned by the server for the next page of results. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/notification/webhook/list?limit=50' -H \"Authorization: $API_KEY\"Test a Notification Webhook
\nPOST /v3/notification/webhook/test
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nThe ID of the notification webhook. | \n
Query Sample
\ncurl -X POST 'https://api.polyswarm.network/v3/notification/webhook/test?id=12345' -H \"Authorization: $API_KEY\"\n\nNote: When this endpoint is called, a success response is returned, this is a success for the request, it does not mean the webhook url worked.
\n
Hunting with Yara
\nManaging Yara Rulesets
\nCreate Ruleset
\nPOST /v3/hunt/rule
Create a new ruleset.
\nBody Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
yara | \nstring | \ntrue | \nYara values, escape the items. | \n
name | \nstring | \ntrue | \nName of the ruleset. | \n
description | \nstring | \nfalse | \nDescription for the ruleset. | \n
Query Sample
\ncurl -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/ruleView Ruleset
\nGET /v3/hunt/rule
View the contents of the specified ruleset.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nruleset id value to view the contents. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H \"Authorization: $API_KEY\"List Rulesets
\nGET /v3/hunt/rule/list
List all rulesets in your account
\nQuery Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/rule/list' -H \"Authorization: $API_KEY\"Update Ruleset
\nPUT /v3/hunt/rule
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nruleset_id that needs to be updated. | \n
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
name | \nstring | \nfalse | \nNew updated name for the ruleset. | \n
file | \nstring | \nfalse | \nNew updated yara values, escaped. | \n
description | \nstring | \nfalse | \nNew updated description. | \n
Query Sample
\ncurl -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=15862162112430616Delete Ruleset
\nDELETE /v3/hunt/rule
Delete the given ruleset.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nruleset_id value to delete. | \n
Query Sample
\ncurl -X DELETE 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H \"Authorization: $API_KEY\"Live Hunts
\nStart Live Hunt
\nPOST /v3/hunt/rule/live
Start a Live Hunt using the given ruleset.
\nBody Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
rule_id | \ninteger | \ntrue | \nrule_id of the ruleset to start a live hunt. | \n
Query Sample
\ncurl -X POST -d '{\"rule_id\":\"6992666340481223\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/hunt/rule/liveStop Live Hunt
\nDELETE /v3/hunt/rule/live
Stop the Live Hunt on a given ruleset.
\nBody Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
rule_id | \ninteger | \ntrue | \nrule_id of the ruleset to stop a live hunt/ | \n
Query Sample
\ncurl -X DELETE -d '{\"rule_id\":\"6992666340481223\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/hunt/rule/liveView Live Results of a Live Hunt
\nGET /v3/hunt/live/list
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
since | \ninteger | \nfalse | \nTime value (in seconds) for how far back to request results (default 1440). | \n
rule-name | \ninteger | \nfalse | \nName of the ruleset being used in the hunt. | \n
family | \nstring | \nfalse | \nFilter results based on the family name. | \n
community | \nstring | \nfalse | \nFilter results based community. | \n
polyscore-lower | \nstring | \nfalse | \nPolyscore lower bound for the hunt results. | \n
polyscore-upper | \nstring | \nfalse | \nPolyscore upper bound for the hunt results. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/live/list?polyscore-upper=0.99' -H \"Authorization: $API_KEY\"View a Singular Result
\nGET /v3/hunt/live
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nProvide the result id value. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/live?id=75570120079919313' -H \"Authorization: $API_KEY\"Delete Live Result
\nDELETE /v3/hunt/live/list
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
result_ids | \ninteger | \ntrue | \nList of ruleset_ids for the live hunt results to be deleted. | \n
Query Sample
\ncurl -X DELETE -d '{\"result_ids\":[\"66625018770158663\"]}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/hunt/live/listHistorical Hunts
\nStart a Historical Hunt
\nPOST /v3/hunt/historical
start a new Historical Hunt using the provided yara rules or existing ruleset file.
\nBody Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
rule_id | \ninteger | \ntrue | \nrule_id of the ruleset to start a historical hunt. | \n
yara | \nstring | \ntrue | \nPath of the yara file to start a historical hunt. | \n
\n\nEither
\nrule_idoryarais required in the call.
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
name | \nstring | \nfalse | \nName of the ruleset to start an historical hunt. | \n
Query Sample
\ncurl -X POST -d '{\"rule_id\":\"24285974317896172\"}' -H \"Content-Type: application/json\" -H \"Authorization: $API_KEY\" https://api.polyswarm.network/v3/hunt/historicalCancel an Historical Hunt
\nPUT /v3/hunt/historical
Stop a Historical Hunt. If it's already running, it will stop at the next batch interval.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nid of the historical hunt to stop. | \n
Query Sample
\ncurl -X PUT 'https://api.polyswarm.network/v3/hunt/historical?' -H \"Authorization: $API_KEY\"List Historical Hunts
\nGET /v3/hunt/historical/list
List the Historical Hunts in your account.
\nQuery Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
since | \ninteger | \nfalse | \nValue in seconds to look for Historical Hunts. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/historical/list' -H \"Authorization: $API_KEY\"View Historical Hunt Details for a Hunt
\nGET /v3/hunt/historical
\n\nProvides ability to download results as a csv file and see the ruleset contents.
\n
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nhistorical hunt id to view details. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/historical?id=75570120079919313' -H \"Authorization: $API_KEY\"View Historical Hunt Results
\nGET /v3/hunt/historical/results/list
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nHistorical hunt id. | \n
rule-name | \ninteger | \nfalse | \nRuleset name to filter results. | \n
family | \ninteger | \nfalse | \nFamily name to filter results. | \n
community | \nstring | \nfalse | \nFilter results based community. | \n
polyscore-lower | \ninteger | \nfalse | \nPolyscore lower bound for the results. | \n
polyscore-upper | \ninteger | \nfalse | \nPolyscore upper bound for the results. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results/list?id=75570120079919313' -H \"Authorization: $API_KEY\"View a Singular Historical Hunt Result
\nGET /v3/hunt/historical/results
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nresult_id value to view single result. | \n
Query Sample
\ncurl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results?id=75570120079919313' -H \"Authorization: $API_KEY\"Delete a Historical Hunt
\nDELETE /v3/hunt/historical
Query Parameters
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
id | \ninteger | \ntrue | \nhunt id of the historical hunt to delete it. | \n
Query Sample
\ncurl -X DELETE 'https://api.polyswarm.network/v3/hunt/historical?id=1371741361996923' -H \"Authorization: $API_KEY\"Delete Historical Hunt Results
\nDELETE /v3/hunt/historical/results/live
Body Schema\n(application/json)
\n| Parameter | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
result_ids | \ninteger | \ntrue | \nruleset_id of the historical hunt to delete results from it. | \n
Query Sample
\ncurl -X DELETE -d '{\"result_ids\":[\"66625018770158663\"]}' -H \"Content-Type: application/json\" https://api.polyswarm.network/v3/hunt/historical/results/list -H \"Authorization: $API_KEY\"PolySwarm Customer CLI v3
\nA Command Line Interface tool for interacting with version 3 of the PolySwarm Customer APIs.
\nSupports Python 3.7 and later.
\nGetting Started
\nInstallation
\nFrom PyPI:
\n$ pip install polyswarm\n\nIf you get an error about a missing package named
\nwheel, that means your version of pip is too old.\nYou need pip version 19 or newer.\nTo update pip, runpip install -U pip.
From source:
\n$ python setup.py install\n\nIf you get an error about a missing package named
\nwheel, that means your version of setuptools is too old.\nYou need setuptools version 40.8.0 or newer.\nTo update setuptools, runpip install -U setuptools.
Upgrade
\n- \n
- \n
Check the current version installed
\n\n$ pip3 list | grep polyswarmResponse Example:\n
\npolyswarm 3.1.0andpolyswarm_api 3.1.1\n - \n
Upgrade the PolySwarm Package
\n\n$ pip3 install -U polyswarm polyswarm_api\n - \n
Confirm the upgraded version
\n\n$ pip3 list | grep polyswarmResponse Example:\n
\npolyswarm 3.9.0andpolyswarm_api 3.11.0\n
Configuration
\nSeveral parameters can be set up Globally in your environment instead of defining these with each command.
\nSet your API key
\n$ export POLYSWARM_API_KEY=<Your API key from polyswarm.network>\n\nYou will need to get your own API key from
\npolyswarm.network/account/api-keys
Set the community name: \"default\" is the default public community.
\n$ export POLYSWARM_COMMUNITY=default\n\nYou can define your own private community name replacing the default community above if you have this feature on your plan.
\n
Enable tab completion
\n$ eval \"$(_POLYSWARM_COMPLETE=source polyswarm)\"Using the PolySwarm CLI
\nGeneral Usage
\nThe polyswarm command has several sub-commands.\nYou can run the command or a sub-command by itself or use the -h option to get help output.
Request
\n$ polyswarm -hResponse
\nUsage: polyswarm [OPTIONS] COMMAND [ARGS]...\n\n This is a PolySwarm CLI client, which allows you to interact directly with\n the PolySwarm network to scan files, search hashes, and more.\n\nOptions:\n -a, --api-key TEXT Your API key for polyswarm.network\n (required). [env var: POLYSWARM_API_KEY]\n\n -u, --api-uri TEXT The API endpoint (ADVANCED). [env var:\n POLYSWARM_API_URI]\n\n -o, --output-file FILENAME Path to output file.\n --output-format, --fmt [text|json|pretty-json|sha256|sha1|md5]\n Output format. Human-readable text or JSON.\n --color / --no-color Use colored output in text mode.\n -v, --verbose\n -c, --community TEXT Community to use. [env var:\n POLYSWARM_COMMUNITY]\n\n --parallel INTEGER Number of threads to be used in parallel\n http requests.\n\n --verify / --no-verify Verify TLS connections.\n --version Show the version and exit.\n --api-version Show the version and exit.\n -h, --help Show this message and exit.\n\nCommands:\n account Interact with Accounts in Polyswarm.\n activity Interact with Yara Rules stored in Polyswarm.\n cat Output artifact contents to stdout.\n download Download file(s).\n download-id Download file(s).\n engine Interact with engines.\n family Interact with Malware Families in Polyswarm.\n historical Interact with historical hunts.\n known Interact with known ioc api.\n link Interact with Tag links in Polyswarm.\n live Interact with live hunts.\n lookup Lookup a scan id(s).\n metadata Interact with Metadata in Polyswarm.\n providers List the names of available sandbox providers and VMs.\n report Interact with the Polyswarm reporting system.\n report-template Interact with the Polyswarm reporting templates system.\n rescan Rescan files(s) by hash.\n rescan-id Rescan by scan id.\n rules Interact with Yara Rules stored in Polyswarm.\n sandbox Interact with the Polyswarm sandbox system.\n scan Interact with Scans sent to Polyswarm.\n search Interact search api.\n stream Access the polyswarm file stream.\n tag Interact with Tags in Polyswarm.\n wait Wait for a scan to finish.Further Usage Details
\nThe command line structure is split into several sections; further details for the most used options and arguments are listed below. '[OPTIONS]' can be used in combination with a number of [COMMANDS].
\npolyswarm [OPTIONS] COMMAND [ARGS]...
[OPTIONS]
- \n
-aapi key, overrides the global setting of the api key, useful for moving between the default public community and the private community. \n–fmtDefine an output format of the returned results; available outputs includejson,pretty-jsonandsha256values. This –fmt is optional; if not defined, it defaults to the engine verdict and artifact details. \n-ooutput the returned results of the command to a file path of choice \n-vVerbose allows for debugging and viewing the API/HTTP request \n
[COMMANDS]
These will be listed in the following chapters but are hierarchical in structure. Each main command will have a sub-command most of the time; these sub-command options can be found with the command polyswarm <command> -h.
For example, polyswarm search -h will list the available sub-commands for the command search
[ARGS]
Most commands require one or more Parameters; these could be IPs, URLs, Artifact ID, or a Hunt ID.
\nStill, the possibilities are significant with commands like metadata, allowing the ability to search through many fields. The Searching Metadata section will review these in further detail.
\nRetrieve account information
\nAccount details
\nFormat: polyswarm account whois
Description: Command to show information for your account, this includes what teams you are part of and account numbers.
\nRequest
\n$ polyswarm account whoisResponse
\nAccount Number: 123456789\nUser Account Number: 987654321\nAccount Name: PolySwarm Demo\nAccount Type: team\nTenant: polyswarm\nCommunities: pcdemoAccount features and quotas
\nFormat: polyswarm account features
Description: Command to show the features enabled and disabled for your account and team, quota usage and other details.
\nRequest
\n$ polyswarm account featuresResponse
\n========================= Account Plan =========================\nAccount Number: 123456789\nUser Account Number: 987654321\nTenant: polyswarm\nAccount Plan Name: Enterprise\nPlan Period Start: 2024-01-02T10:54:51.631182+00:00\nPlan Period End: 2026-01-15T00:00:00+00:00\nWindow Start: 2024-07-30T10:54:51.631182+00:00\nWindow End: 2024-08-29T10:54:51.631182+00:00\nDaily API Limit: 12,500\nDaily API Remaining: 11,000\nHas Stream Access?: No\nIs Trial?: No\n\n================== Account Features and Quota ==================\nName: Daily Api Limit\nTag: daily_api_limit\nValue: True\n---\n.......Private Communities
\nPolySwarm offers a service called “Private Communities” that restricts artifacts submitted into a Private Community and any metadata from the artifact to be accessible only by members of the private community and not to the wider public PolySwarm community.
\nCurrently, once Private Communities has been enabled for your Team Account, it can be used via the API and CLI.
\nWhile setting up the environment as highlighted in the section \"Configuration\", you can set the API Key and Community to relate to the Team and Private Community Name going forward.
Alternatively, all cli commands discussed in this section support Private Communities, and to use this function, two options need to be fed into the [OPTIONS].
- \n
-a- Define the Team API Key that has access to the Private Community, to get the key see here \n--community- Input the name of the Private Community, this will have been provided by the PolySwarm Team. If you omit the--communityoption from a CLI command, it will first look for thePOLYSWARM_COMMUNITYvariable in your environment, and if that is not defined, it will use the default public community. \n
Request Example
\npolyswarm -a 1234123412341234123412341234 --community mypc --fmt sha256 search metadata 'artifact.created:>now-1000d 'Scanning an Artifact
\nScan a File
\nFormat: polyswarm scan file <file>
Description: Command to scan a local file with PolySwarm to retrieve engine verdict details.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --recursive | \n- | \nfalse | \nScan directories recursively | \n
-t, --timeout | \ninteger | \nfalse | \nHow long to wait for results (default:900) | \n
-z, --is-zip | \nbool | \nfalse | \nWill handle the provided file as a zip and decompress server side. | \n
-p, --zip-password | \nstring | \nfalse | \nUsed to provide a password to decompress the zip file with. | \n
-e, --expiration-window | \nINTEGER | \nfalse | \nApplies to Private Communities only and affects new uploads. After the configured number of days, the binary file is deleted, but the metadata remains available, so the hash can still be searched. Must be 30 or 180. | \n
-n, --nowait | \n- | \nfalse | \nDoes not wait for the scan window to close | \n
-b, --is-base64 | \n- | \nfalse | \nWill handle the provided file as containingbase64-encoded content to decode server-side. | \n
--is-7zip | \n- | \nfalse | \nWill handle the provided file as a 7zip archive and decompress server-side. | \n
--sevenzip-password | \nstring | \nfalse | \nWill use this password to decompress the 7zip file. If provided, will handle the file as a 7zip. | \n
-s, --scan-config | \nstring | \nfalse | \nTemplate to be used in the scan i.e. default, more-time, most-time | \n
Request
\n$ polyswarm scan file /tmp/eicarResponse
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nDetections: 6/12 engines reported malicious\n\tQihoo 360: Malicious, metadata: {\"malware_family\": \"qex.eicar.gen.gen\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}}}\n\tLionic: Clean\n\tXVirus: Clean\n\tNucleon: Clean\n\tVirusdie: Malicious, metadata: {\"malware_family\": \"EICAR.TEST\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"vendor_version\": \"1.3.0\", \"version\": \"0.3.0\"}}\n\tIkarus: Malicious, metadata: {\"malware_family\": \"EICAR-Test-File\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"21.02.2020 13:15:46 (102417)\", \"vendor_version\": \"5.2.9.0\", \"version\": \"0.2.0\"}}\n\tClamAV: Clean\n\tAlibaba: Clean\n\tK7: Malicious, metadata: {\"malware_family\": \"EICAR_Test_File\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}, \"signatures_version\": \"11.95.33362, 21-Feb-2020\", \"vendor_version\": \"15.2.0.42\", \"version\": \"0.2.0\"}}\n\tNanoAV: Malicious, metadata: {\"malware_family\": \"Marker.Dos.EICAR-Test-File.dyb\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}, \"signatures_version\": \"0.14.33.17090\", \"vendor_version\": \"1.0.134.90567\", \"version\": \"0.1.0\"}}\n\tVenusEye: Clean\n\tDrWeb: Malicious, metadata: {\"malware_family\": \"EICAR Test File (NOT a Virus!)\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42\", \"vendor_version\": \"7.00.44.12030\", \"version\": \"0.3.0\"}}\nScan id: 50446025732260182\nSHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nSHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c\nMD5: a6a57bf20416a4c712c4a1eabcaeb235\nFile type: mimetype: text/plain, extended_info: EICAR virus test files\nSSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX\nTLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8\nFirst seen: 2020-01-24 21:56:21.456900\nLast seen: 2020-02-21 19:21:59.196578\nStatus: Assertion window closed\nFilename: malicious.txt\nCommunity: lima\nCountry: US\nPolyScore: 0.07193209420451106284Scan a URL
\nFormat: polyswarm scan url <URL>
\n\nWhen scanning a URL, you should always include the protocol (
\nhttp://orhttps://).
Description: Command to scan a url with PolySwarm to retrieve engine verdict details. The command can be used to scan a qr code and extract the url from the code.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r ,--url-file | \nstring | \nfalse | \nPath of file that contains multiple URLs, one per line. | \n
--qrcode-file | \nstring | \nfalse | \nPath of a QR Code image file that contains an URL as a payload. | \n
-e, --expiration-window | \nINTEGER | \nfalse | \nApplies to Private Communities only and affects new uploads. After the configured number of days, the binary file is deleted, but the metadata remains available, so the hash can still be searched. Must be 30 or 180. | \n
-t, --timeout | \ninteger | \nfalse | \nHow long to wait for results (default:900). | \n
-n, --nowait | \n- | \nfalse | \nDoes not wait for the scan window to close. | \n
-s, --scan-config | \nstring | \nfalse | \nTemplate to be used in the scan i.e. default, more-time, most-time. | \n
Request
\n$ polyswarm scan url --scan-config most-time https://google.comResponse
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d\nDetections: 0/4 engines reported malicious\n\tCyRadar: Clean\n\tPhishtank: Clean\n\tNucleon: Clean\n\tVirusdie: Clean\nScan id: 47022542941158297\nSHA256: 05046f26c83e8c88b3ddab2eab63d0d16224ac1e564535fc75cdceee47a0938d\nSHA1: 72fe95c5576ec634e214814a32ab785568eda76a\nMD5: 99999ebcfdb78df077ad2727fd00969f\nFile type: mimetype: text/plain, extended_info: ASCII text, with no line terminators\nSSDEEP: 3:N8r3uK:2LuK\nTLSH:\nFirst seen: 2019-06-25 01:53:43.954091\nLast seen: 2020-02-21 19:40:12.136225\nStatus: Assertion window closed\nFilename: https://google.com\nCommunity: lima\nCountry: US\nPolyScore: 0.00000000000000000000Rescanning an Artifact
\nFormat: polyswarm rescan <hash>
Description: Rescans also triggered by referencing the SHA256/SHA1/MD5 hash of the artifact. Rescan will submit the sample through the engines to retrieve an updated verdict.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --hash-file | \nstring | \nfalse | \nFile path and name for file that contains hashes, one per line | \n
-t, --timeout | \ninteger | \nfalse | \nHow long to wait for results (default:900) | \n
-n, --nowait | \n- | \nfalse | \nDoes not wait for the scan window to close | \n
-s, --scan-config | \nstring | \nfalse | \nTemplate to be used in the scan i.e. default, more-time, most-time | \n
--hash-type | \nstring | \nfalse | \nHash type to search [default:autodetect, sha256, sha1, md5] | \n
Request
\n$ polyswarm rescan 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bfResponse
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nDetections: 5/11 engines reported malicious\n\tQihoo 360: Malicious, metadata: {\"malware_family\": \"qex.eicar.gen.gen\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}}}\n\tClamAV: Clean\n\tIkarus: Malicious, metadata: {\"malware_family\": \"EICAR-Test-File\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"21.02.2020 13:15:46 (102417)\", \"vendor_version\": \"5.2.9.0\", \"version\": \"0.2.0\"}}\n\tNucleon: Clean\n\tVenusEye: Clean\n\tK7: Malicious, metadata: {\"malware_family\": \"EICAR_Test_File\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}, \"signatures_version\": \"11.95.33362, 21-Feb-2020\", \"vendor_version\": \"15.2.0.42\", \"version\": \"0.2.0\"}}\n\tLionic: Clean\n\tVirusdie: Malicious, metadata: {\"malware_family\": \"EICAR.TEST\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"vendor_version\": \"1.3.0\", \"version\": \"0.3.0\"}}\n\tAlibaba: Clean\n\tDrWeb: Malicious, metadata: {\"malware_family\": \"EICAR Test File (NOT a Virus!)\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"0599371BD3AE76D460E15A9719E64059, 2020-Feb-21 18:06:10\", \"vendor_version\": \"7.00.44.12030\", \"version\": \"0.3.0\"}}\n\tXVirus: Clean\nScan id: 87555975730729927\nSHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nSHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c\nMD5: a6a57bf20416a4c712c4a1eabcaeb235\nFile type: mimetype: text/plain, extended_info: EICAR virus test files\nSSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX\nTLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8\nFirst seen: 2020-01-24 21:56:21.456900\nLast seen: 2020-02-21 20:03:30.398950\nStatus: Assertion window closed\nFilename: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nCommunity: lima\nCountry: US\nPolyScore: 0.08376258884586366971Downloading & Reporting
\nDownloading Artifacts
\nFormat: polyswarm download <hash>
Description: Artifacts are downloaded by referencing their SHA256/SHA1/MD5 hash and stored locally.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --hash-file | \nstring | \nfalse | \nFile of hashes to download, one per line | \n
-d, --destination | \nstring | \nfalse | \nPath where to store the downloaded files | \n
--hash-type | \nstring | \nfalse | \nHash type to search [default:autodetect, sha256, sha1, md5] | \n
Request
\n$ polyswarm download 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 test/Response
\nSuccessfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/test/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267Downloading Artifacts via id
\nCommonly used to download sandbox artifacts, this command can be used to download artifacts directly via their instance_id see this section for command.
Downloading Bundles
\nThis provides the ability to 'bundle' selected items together into a single zip file for easy collection. This is a three step process.
\n- \n
- Create the bundle \n
- Get the bundle status, wait for it to be built \n
- Download the bundle \n
Format: polyswarm bundle create -i <instance_id>
Description: Define the items that will be included in the bundle and create it.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-i, --instance-id | \nstring | \ntrue | \nThe ID of an instance to include in the bundle archive. | \n
-n, --archive-name | \nstring | \ntrue | \nName of the archive that will be created. | \n
-p, --preserve-filenames | \nstring | \nfalse | \nPreserve the names of the files in the bundle. | \n
Request
\n$ polyswarm bundle create -i 71486732419112569 -i 55884507474463461 --archive-name reports.zipResponse
\n============================= Sample Bundle =============================\nID: 25716002001657474\nCommunity: _public\nCreated: 2025-05-27T11:08:54.819102+00:00\nInstance IDs: [71486732419112569, 55884507474463461]\nState: PENDING\n
Format: polyswarm bundle get <bundle_task_id>
Description: Poll the status of the bundle creation get the id from step 1.
\nRequest
\n$ polyswarm bundle get 25716002001657474Response
\n============================= Sample Bundle =============================\nID: 25716002001657474\nCommunity: _public\nCreated: 2025-05-27T11:08:54.819102+00:00\nInstance IDs: [71486732419112569, 55884507474463461]\nState: SUCCEEDED\nURL: https:<presigned-aws-link>\n
Format: polyswarm bundle download <bundle_task_id>
Description: Download the bundle.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-d, --destination | \nstring | \nfalse | \nPath where to store the downloaded file. | \n
Request
\n$ polyswarm bundle download 25716002001657474Response
\nSuccessfully downloaded artifact reports.zip to /Users/name/Documents/reports.zipReporting
\nDownloading reports and zip files
\nPolySwarm provides the reporting cli command, this provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing sessions, and download a ZIP file of which can contain the PDF report alongside other Sandbox artifacts like pcaps, reports and jarm files.
\nThe following are the 3 sequential steps in a report generation operation, that can be performed via the CLI one step at a time:
\n- \n
- Inform PolySwarm to start creating the report, or create and download the zip file. If only wanting the zip file there is no need to proceed with the next two steps. \n
- Poll PolySwarm to understand when the report has finished being created. \n
- Download the report locally once generation is successful. \n
\n
Format: polyswarm report create [OPTIONS] <html|pdf|zip> <scan|sandbox> <OBJECT_ID>
Description: Start to generate the PolySwarm report, choose a PDF or HTML report for Sandbox or a Scanning instance. Or create a zip file with Sandbox Artifacts to download directly.
\n\n\nNOTE: If generating a Scanning report the
\nOBJECT_IDwill be theartifact_id, find this with the command:polyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id'.\nIf generating a Sandboxing report theOBJECT_IDwill be thesandbox_id, find this with the command:polyswarm sandbox search <hash>then choose from the desired sandbox sessions.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--includes | \nstring | \nfalse | \nComma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis | \n
--sandbox_artifact_types | \nstring | \nfalse | \nComma-separated list of sandbox artifact types to include in the downloaded zip. Can be one or more of: report, raw_report, screenshot, recording, dropped_file, memory_dump, pcap, jarm. Only applicable to zip type. | \n
--zip-report-ids | \nstring | \nfalse | \nComma-separated list of report task ids to include in the zip. This only needs to be used if you require the PDF report to be included in the ZIP. Note that the PDF report must be generated first. | \n
--template-id | \ninteger | \nfalse | \nProvide the id for the template used | \n
Example 1 Request: Create a PDF Report
\n$ polyswarm report create pdf scan 97903321852386706Example 1 Response
\nSuccessfully downloaded artifact scan-97903321852386706.pdf to /Users/John/Documents/scan-97903321852386706.pdf\n============================= Report =============================\nID: 59403308938961820\nCommunity: _public\nCreated: 2024-06-11T10:19:48.211143\nType: scan\nFormat: pdf\nTemplate ID: 95389624286242180\nScan ID: 97903321852386706\nState: PENDINGExample 2 Request: Download a ZIP file
\n$ polyswarm report create --sandbox_artifact_types report,raw_report,pcap zip sandbox 97903321852386706Example 2 Response
\nSuccessfully downloaded artifact sandbox_zip-97903321852386706.zip to /Users/John/Documents/sandbox_zip-97903321852386706.zip\n
Format: polyswarm report get <REPORT_ID>
Description: Retrieve the report's details to understand if the report generation has been successful and then retrieve the download link. REPORT_ID provided from the previous command.
Request
\n$ polyswarm report get 59403308938961820Response
\n============================= Report =============================\nID: 59403308938961820\nCommunity: _public\nCreated: 2024-06-11T10:19:48.211143\nType: scan\nFormat: pdf\nTemplate ID: 95389624286242180\nScan ID: 97903321852386706\nState: SUCCEEDED\nURL: https://s3.us-east-2.amazonaws.com/ps-storage-prod-reports/{AWS_LINK}...\n
Format: polyswarm report download <REPORT_ID>
Description: Download the generated report locally.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--destination | \nstring | \nfalse | \nLocal path to store the downloaded file. | \n
Request
\n$ polyswarm report download 59403308938961820Response
\nSuccessfully downloaded artifact scan-97903321852386706.pdf to /Users/John/Documents/scan-97903321852386706.pdfLLM Reports
\nPolySwarm provides the ability to generate LLM-powered analysis reports for Scanning and Sandboxing sessions. These reports provide AI-generated summaries and insights for your submitted artifacts.
\nThe following are the 3 sequential steps in an LLM report generation operation:
\n- \n
- Inform PolySwarm to start creating the LLM report. \n
- Poll PolySwarm to understand when the report has finished being created. \n
- Download the report locally once generation is successful. \n
\n
Format: polyswarm report llm-create [OPTIONS]
Description: Start to generate an LLM-powered analysis report for a Scanning or Sandboxing instance.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-i, --instance-id | \nstring | \nfalse | \nInstance ID (from a scan) to include in the report. | \n
--cape-sandbox-task-id | \nstring | \nfalse | \nCape Sandbox Task ID to include in the report. | \n
--triage-sandbox-task-id | \nstring | \nfalse | \nTriage Sandbox Task ID to include in the report. | \n
\n\nAt least one of
\n--instance-id,--cape-sandbox-task-id, or--triage-sandbox-task-idmust be provided. You may combine--cape-sandbox-task-idand--triage-sandbox-task-idtogether, optionally alongside--instance-id, to generate a single unified report from multiple sources.
Example 1 Request: Create an LLM Report for a Scan
\n$ polyswarm report llm-create --instance-id 97903321852386706Example 1 Response
\n============================= LLM Report Task =============================\nID: 45678901234567890\nInstance ID: 97903321852386706\nCreated: 2024-12-15T14:32:10.123456\nState: PENDINGExample 2 Request: Create an LLM Report for a Cape Sandbox Task
\n$ polyswarm report llm-create --cape-sandbox-task-id 76509232912518724Example 2 Response
\n============================= LLM Report Task =============================\nID: 45678901234567891\nCape Sandbox Task ID: 76509232912518724\nCreated: 2024-12-15T14:33:22.654321\nState: PENDINGExample 3 Request: Create an LLM Report for a Triage Sandbox Task
\n$ polyswarm report llm-create --triage-sandbox-task-id 76509232912518724Example 3 Response
\n============================= LLM Report Task =============================\nID: 45678901234567892\nTriage Sandbox Task ID: 76509232912518724\nCreated: 2024-12-15T14:34:10.789012\nState: PENDINGExample 4 Request: Create an LLM Report combining Cape and Triage results
\n$ polyswarm report llm-create --cape-sandbox-task-id 76509232912518724 --triage-sandbox-task-id 12345678901234567Example 4 Response
\n============================= LLM Report Task =============================\nID: 45678901234567893\nCape Sandbox Task ID: 76509232912518724\nTriage Sandbox Task ID: 12345678901234567\nCreated: 2024-12-15T14:35:00.111222\nState: PENDING\n
Format: polyswarm report llm-get <REPORT_ID>
Description: Retrieve the LLM report task details to understand if the report generation has been successful. Use the REPORT_ID from the llm-create command.
Request
\n$ polyswarm report llm-get 45678901234567890Response
\n============================= LLM Report Task =============================\nID: 45678901234567890\nInstance ID: 97903321852386706\nCreated: 2024-12-15T14:32:10.123456\nState: SUCCEEDED\n
Format: polyswarm report llm-download <REPORT_ID>
Description: Download the generated LLM report locally.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-d, --destination | \nstring | \nfalse | \nLocal path to store the downloaded file. | \n
Request
\n$ polyswarm report llm-download 45678901234567890Response
\nSuccessfully downloaded artifact llm_report-97903321852386706.txt to /Users/John/Documents/llm_report-97903321852386706.txtLLM Prompt Configurations
\nPolySwarm provides the ability to manage LLM prompt configurations for customizing AI-generated analysis reports.
\nCreate a prompt configuration
\nFormat: polyswarm report prompt-config-create <NAME> --system-prompt <PROMPT>
Description: Create a new LLM prompt configuration with customizable prompts for different analysis types.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--system-prompt | \nstring | \ntrue | \nThe system prompt text for the AI analysis. | \n
--is-active | \nflag | \nfalse | \nWhether this should be the active prompt configuration. | \n
--cape-only-prompt | \nstring | \nfalse | \nOptional Cape sandbox-specific prompt text. | \n
--triage-only-prompt | \nstring | \nfalse | \nOptional Triage sandbox-specific prompt text. | \n
--scan-only-prompt | \nstring | \nfalse | \nOptional scan-specific prompt text. | \n
Request
\n$ polyswarm report prompt-config-create detailed_analysis \\\n --system-prompt \"You are a cybersecurity expert analyzing malware samples.\" \\\n --is-active \\\n --cape-only-prompt \"Focus on payload extraction.\" \\\n --scan-only-prompt \"Focus on detection results.\"Response
\n============================= LLM Prompt Config =============================\nID: 12345678901234567\nName: detailed_analysis\nSystem Prompt: You are a cybersecurity expert analyzing malware samples.\nIs Active: True\nCreated: 2024-12-15T14:32:10.123456+00:00Report templates
\nPolySwarm provides the ability to manage the report templates, this can include uploading a new template, deleting a current template and managing the logo for each one.
\nList templates
\nFormat: polyswarm report-template list
Description: List the available templates available to the team.
\nRequest
\n$ polyswarm report-template listResponse
\n============================= Report Template =============================\nID: 95389624286242180\nTemplate Name: default\nCreated: 2024-06-05T19:33:03.232395\nPrimary Color: 6D3AEC\nIs Default: TrueCreate a template
\nFormat: polyswarm report-template create <TEMPLATE_NAME>
Description: Create a new template with a number of option below.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--is-default | \n- | \nfalse | \nIf declared this template will be the default template for the team. | \n
--primary-color | \nstring | \nfalse | \nSix-character hex color code. | \n
--last-page-text | \nstring | \nfalse | \nText to be displayed on the last page of the template (cannot be used with --last-page-text-file). | \n
--last-page-text-file | \nstring | \nfalse | \nFile path to the document that contains the text for the last page text (cannot be used with --last-page-text). | \n
--includes | \nstring | \nfalse | \nComma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis. | \n
Request
\n$ polyswarm report-template create --primary-color ec6560 --footer-text 'Company A INC 2024' --includes network,droppedFiles,extractedConfig snd_box_testResponse
\n============================= Report Template =============================\nID: 60430384589833968\nTemplate Name: sndboxtest\nCreated: 2024-06-11T12:42:45.950422\nPrimary Color: ec6560\nIncludes: network, droppedFiles, extractedConfig\nFooter Text: Company A INC 2024Delete a template
\nFormat: polyswarm report-template delete <REPORT_ID>
Description: Delete the template.
\nRequest
\n$ polyswarm report-template delete 60430384589833968Response
\nTemplate DeletedGet template details
\nFormat: polyswarm report-template get <REPORT_ID>
Description: Get the details for s specific template.
\nRequest
\npolyswarm report-template get 60430384589833968Response
\n============================= Report Template =============================\nID: 60430384589833968\nTemplate Name: sndboxtest\nCreated: 2024-06-11T12:42:45.950422\nPrimary Color: ec6560\nIncludes: network, droppedFiles, extractedConfig\nFooter Text: Company A INC 2024Update a template
\nFormat: polyswarm report-template update <TEMPLATE_ID>
Description: Update the template with new values and configuration.
\nOptions
\nOnly the passed options are updated, leaving the rest of the values untouched.\n| Option | Type | Required | Description |\n|------|------|----------|-------------|\n|--is-default| - | false | If declared this template will be the default template for the team. |\n|--primary-color| string | false | Six-character hex color code. |\n|--last-page-text| string | false | Text to be displayed on the last page of the template. |\n|--last-page-text-file| string | false | File path to the document that contains the text for the last page text. |\n|--includes| string | false | Comma-separated list of sections to include in the report. Can be one or more of: summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis. |
Request
\n$ polyswarm report-template update --primary-color 6D3AEC 98453877554394669Response
\n============================= Report Template =============================\nID: 98453877554394669\nTemplate Name: test\nCreated: 2024-06-11T12:36:17.511289\nPrimary Color: 6D3AECUpload template logo
\nFormat: polyswarm report-template logo-upload <TEMPLATE_ID> <PATH>
Description: Upload a new logo for the template.
\nRequest
\npolyswarm report-template logo-upload 98453877554394669 /Users/John/Downloads/Logo_Purple.pngResponse
\n============================= Report Template =============================\nID: 98453877554394669\nTemplate Name: test\nCreated: 2024-06-11T12:36:17.511289\nPrimary Color: 6D3AEC\nLogo Content Length: 6284\nLogo Content Type: image/png\nLogo URL: https://api.polyswarm.network/v3/reports/templates/logo?id=98453877554394669\nLogo Height: 42\nLogo Width: 250Delete template logo
\nFormat: polyswarm report-template logo-delete <TEMPLATE_ID>
Description: Delete the current logo for the template.
\nRequest
\npolyswarm report-template logo-delete 98453877554394669Response
\nTemplate logo deletedDownload template logo
\nFormat: polyswarm report-template logo-download <TEMPLATE_ID>
Description: Download the template logo locally.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--destination | \nstring | \nfalse | \nLocal path to store the downloaded file. | \n
Request
\n$ polyswarm report-template logo-download 98453877554394669Response
\nSuccessfully downloaded artifact logo to /Users/ruebenburrows/Documents/python/logoSearching
\nHash Searching
\nFormat: polyswarm search <hash>
Description: Artifacts are searched by referencing their SHA256/SHA1/MD5.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --hash-file | \nstring | \nfalse | \nFile of hashes to search, one per line | \n
--hash-type | \nstring | \nfalse | \nHash type to search [default:autodetect, sha256, sha1, md5] | \n
Request
\n$ polyswarm search hash 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bfResponse
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nDetections: 6/12 engines reported malicious\n\tQihoo 360: Malicious, metadata: {\"malware_family\": \"qex.eicar.gen.gen\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}}}\n\tLionic: Clean\n\tXVirus: Clean\n\tNucleon: Clean\n\tVirusdie: Malicious, metadata: {\"malware_family\": \"EICAR.TEST\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"vendor_version\": \"1.3.0\", \"version\": \"0.3.0\"}}\n\tIkarus: Malicious, metadata: {\"malware_family\": \"EICAR-Test-File\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"21.02.2020 13:15:46 (102417)\", \"vendor_version\": \"5.2.9.0\", \"version\": \"0.2.0\"}}\n\tClamAV: Clean\n\tAlibaba: Clean\n\tK7: Malicious, metadata: {\"malware_family\": \"EICAR_Test_File\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}, \"signatures_version\": \"11.95.33362, 21-Feb-2020\", \"vendor_version\": \"15.2.0.42\", \"version\": \"0.2.0\"}}\n\tNanoAV: Malicious, metadata: {\"malware_family\": \"Marker.Dos.EICAR-Test-File.dyb\", \"scanner\": {\"environment\": {\"architecture\": \"AMD64\", \"operating_system\": \"Windows\"}, \"signatures_version\": \"0.14.33.17090\", \"vendor_version\": \"1.0.134.90567\", \"version\": \"0.1.0\"}}\n\tVenusEye: Clean\n\tDrWeb: Malicious, metadata: {\"malware_family\": \"EICAR Test File (NOT a Virus!)\", \"scanner\": {\"environment\": {\"architecture\": \"x86_64\", \"operating_system\": \"Linux\"}, \"signatures_version\": \"864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42\", \"vendor_version\": \"7.00.44.12030\", \"version\": \"0.3.0\"}}\nScan id: 50446025732260182\nSHA256: 89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\nSHA1: a33fb79e9c71f1b446607d437a1984602ed47d5c\nMD5: a6a57bf20416a4c712c4a1eabcaeb235\nFile type: mimetype: text/plain, extended_info: EICAR virus test files\nSSDEEP: 3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX\nTLSH: ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8\nFirst seen: 2020-01-24 21:56:21.456900\nLast seen: 2020-02-21 19:21:59.196578\nStatus: Assertion window closed\nFilename: malicious.txt\nCommunity: lima\nCountry: US\nPolyScore: 0.07193209420451106284View Scan History
\nFormat: polyswarm search scans <hash>
Description: Search a hash to view previosu Scans that have been performed.
\nRequest
\n$ polyswarm search scans 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5Response
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5/30327221925404900\nDetections: No engines responded to this scan. You can trigger a rescan now.\nScan id: 30327221925404900\nSHA256: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5\nSHA1: 8169175b424034b0f93b433e6d7068c08e526199\nMD5: e6c0964ef7105869ef21379eebaefe12\nFile type: mimetype: application/x-dosexec, extended_info: PE32 executable (DLL) (GUI) Intel 80386, for MS Windows\nFirst seen: 2024-09-13 22:48:48 UTC\nLast scanned: 2024-11-19 06:14:47 UTC\nLast seen: 2024-11-19 06:14:47 UTC\nStatus: Assertion window closed\nFilename: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5\nCommunity: mainnet1\nCountry: US\nPolyScore: 0.99922532264464414276\n\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5/79082986982481921\nDetections: No engines responded to this scan. You can trigger a rescan now.\nScan id: 79082986982481921\nSHA256: 95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5\nSHA1: 8169175b424034b0f93b433e6d7068c08e526199\nMD5: e6c0964ef7105869ef21379eebaefe12\nFile type: mimetype: application/x-dosexec, extended_info: PE32 executable (DLL) (GUI) Intel 80386, for MS Windows\nFirst seen: 2024-09-13 22:48:48 UTC\nLast scanned: 2024-10-31 01:10:49 UTC\nLast seen: 2024-10-31 01:10:49 UTC\nStatus: Assertion window closed\n..\n..URL Searching
\nFormat: polyswarm search url <URL>
Description: Artifacts are searched by referencing their URL.
\nRequest
\n$ polyswarm search url https://polyswarm.ioResponse
\n============================= Artifact Instance =============================\nScan permalink: https://polyswarm.network/scan/results/file/078e6c2d6ba818466fb9944a8717e249b3820c13addc9b7ebf59e3ca79166541\nDetections: 0/6 engines reported malicious\n\tZeroCERT: Clean\n\tCyRadar: Clean\n\tQuttera: Clean\n\tNotmining: Clean\n\tVirusdie: Clean\n\tNucleon: Clean\nScan id: 61118021570495545\nSHA256: 078e6c2d6ba818466fb9944a8717e249b3820c13addc9b7ebf59e3ca79166541\nSHA1: 3a26c7a00fbeb54b49361457e99bb6cd59dcfe24\nMD5: e82f49f9ef02b6b517748be47ba0005a\nFile type: mimetype: text/plain, extended_info: ASCII text, with no line terminators\nSSDEEP: 3:N8OI+ILL:2OGLL\nTLSH:\nFirst seen: 2019-06-25 18:04:48.248039\nLast seen: 2020-04-01 03:59:53.555767\nStatus: Assertion window closed\nURL: https://polyswarm.io\nCommunity: lima\nCountry: AU\nPolyScore: 0.00000000000000000000Metadata Searching
\nPolySwarm's Metadata Search provides you with the functionality to search through PolySwarm’s dataset to find samples that relate to information you are interested in.
\nTo understand how to build out a Metadata query see the How-To Guide.
\nSearching for Metadata Attributes
\nFormat: polyswarm search metadata <metadata values>
Description: Search for Artifact Metadata in the CLI, Add additional options like –fmt to allow for additional functionality see here.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-i, --include | \nstring | \nfalse | \nField to be included in the result (* wildcards are accepted). | \n
-x, --exclude | \nstring | \nfalse | \nField to be excluded in the result (* wildcards are accepted). | \n
-p , --ip | \nstring | \nfalse | \nIP address IOC to search. | \n
-d ,--domain | \nstring | \nfalse | \nDomain name IOC to search. | \n
-u , --url | \nstring | \nfalse | \nURL IOC to search. | \n
Request
\n$ polyswarm --fmt pretty-json search metadata \"scan.detections.malicious:>1\"Response
\n{\n \"artifact\": {\n \"created\": \"2023-06-20T11:29:11.322959+00:00\",\n \"id\": \"3414327927829341\",\n \"md5\": \"6bf2025e7aa7b09d7044718c2a3f190d\",\n \"sha1\": \"5323a695a165e13a04a11d24e603ae4444463b08\",\n \"sha256\": \"2d1bbc2837559f5224076a833ec6e9cc6fe053b76a11bf500654ce0431b8993c\"\n },\n \"exiftool\": {\n \"characterset\": \"Unicode\",\n \"codesize\": 45056,\n ..............Request
\n$ polyswarm search metadata -i triage_sandbox_v0.ttp 'scan.detections.malicious:>1 AND polyunite.malware_family:Emotet'Response
\n============================= Metadata =============================\nArtifact id: 1368439839946634\nCreated: 2025-02-14 09:41:05.568721+00:00\nSHA256: 687e603817c1c9de994763bcae0c531544a62b6f993071b8721004fd6e780841\nSHA1: 2377b6e51ddb690b2ca732a1045dec3e3c934601\nMD5: 3d10895e2f8bd8e2ab6735e3a4ebb70d\n\n============================= Metadata =============================\nArtifact id: 51608922017858789\nCreated: 2025-02-14 09:40:48.910620+00:00\nSHA256: ca7cfdc3fdca5c5d05fb85fcd1ff3c1190968f1cdc2bf159f232d08bb1f8e66d\nSHA1: 9feff541dec075bc5893745ecef9a16a016996b3\nMD5: fb59934c3c6305e9a5a08dcd082724f7\n....\n.Processing Attribute Results with JQ
\njq is a command-line processor for json files, allowing the slicing of the json to filter out specific Attributes.
When defining --fmt as json in the polyswarm search metadata CLI command, jq can be used to filter the output of the Attributes.
Taking the command polyswarm --fmt pretty-json search metadata -i artifact.sha256 \"scan.detections.malicious:>1\" will produce a large json output that matches these criteria, to filter only md5 values, you can use jq to achieve this.
Request
\n$ polyswarm --fmt pretty-json search metadata -i artifact.sha256 \"scan.detections.malicious:>1\" | jq .artifact.md5Response
\n\"8ce0d5b701fb084f14990fe0d425628781130c9da0b0b95f98f3a9e5eef755bb\"\n\"19cb4f641750555e4a40460e03a07217306077585a7290ef480712d373e3b755\"\n\"f2015c1e82f92c7d8a728eeb47adb52e877a3ab9ee2d7168cc311fae7b5bbfae\"\n\"b0a1cc605d485e5e73e73aa8a0377a9d12a53d4042d711bd4bf99cd7b6961afa\"\n\"9cb02c934c2aa8938b30aa52924798a6d2a12ca4e7d75a2d01390c01067b0a8b\"\n\"6d7607445c3b71d707576d6424581cb0a0c6c39f11a67601811568cf30eba9ab\"\n\"f665fa1373a7bb1b8085ad95866066f2164e25f79e3bf0dc45abc2ba690144ab\"\n\"bf1e0bd5265619d33c89795d340fe05bf7e3a80935396e83cd52d3baa77b4902\"\n\"07707539577a320e56805cd9458a3ffd9ace7fb31aca106bd1aad89d60354906\"\n\"d47f64147c5ad65a9841813df44fce49e435e472874853d02a192689dd1f5007\"\n\"d767ded5ba7377356f48351f9f03ada9de9c6eb156f08de0a9cce2ebe3ad4369\"Searching for Metadata Fields
\nFormat: polyswarm search mapping | grep <value>
Description: Search for fields that can be used in PolySwarm Metadata searching.
\nRequest
\n$ polyswarm search mapping | grep c2 | grep ipIOC Searching
\nIOC Searching can be split into three groups of commands, these are:
\n- \n
- Searching for Associated IOCs related to a Hash: This returns IOCs that were observed by our sandbox during analysis. These IP's and Domains are classified as C2 or malicious. \n
- Searching for Associated Hashes related to an IP, URL, imphash or MITRE TTP: This returns file hashes that were seen communicating with the specified IPs or domains in our sandbox — regardless of whether the communication was malicious or not. \n
- Check for known good domains and IPs \n
Searching for Associated IOCs
\nFormat: polyswarm search ioc sha256 <hash>
Description: List associated IOCs to a Hash by referencing the hash value.
\nRequest
\n$ polyswarm search ioc sha256 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40Response
\n============================= IOCs =============================\nImpHash:\nIPs: 1.2.3.4, 2.2.2.2\nURLs: polyswarm.io\nTTPs: T1060, T1053Searching for Associated Hashes
\nFormat: polyswarm search ioc ip <IP>
\n\nReplace
\nipabove withdomain,imphash,URLorMITRE TTPe.g.polyswarm search ioc domain <url>
Description: List associated Hashes to an IP, URL, imphash or MITRE TTP.
\nRequest
\n$ polyswarm search ioc ip 1.2.3.4Response
\n============================= IOCs =============================\nSHA256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0aSearching for Known Good Domains and IPs
\nFormat: polyswarm search known -d <DOMAIN> -p <IP>
Description: Known good checking allows you to check for known good domains and IPs. If any of the list of domain or IP parameters you provide match a record, then you'll get a result.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-p, --ip | \nstring | \ntrue | \nIP to search on | \n
-d, --domain | \nstring | \ntrue | \nDomain to search on | \n
\n\nEither
\n-por-dmust be used in the command.
Request
\n$ polyswarm search known -d polyswarm.networkResponse
\n============================= Known IOC =============================\nID: 67\ntype: domain\nhost: polyswarm.network\nsource: polyswarm\ngood: True\n
\n\n\nA word of caution with Known Good checking!
\nOur list of known good domains and IPs is not all-inclusive!\nOur goal for this feature is to provide an easy way to check the most common known good domains and IPs, so they can be excluded from analysis.
\n
Tags/Lists/Families
\nPolySwarm researchers tag known malware samples with malware family names and attributes.
\nBelow are some examples of using malware Families and Tags to identify Emotet - another malware family that PolySwarm has been tracking.
\n\n\nEmotet is a \"downloader\".\nBy itself, it usually just offers the attackers the ability to install additional malware on target machines.\nTrickBot (an info stealer) and Ryuk (ransomware) are commonly installed via initial Emotet infection.
\n
Using Tags
\nFormat: polyswarm tag list
Description: PolySwarm tags are free-form attributes applied to known malware samples.
\n\n\n\n
tagscan describe attributes like malware family (e.g.EventBot), target operating system (e.g.Android), phishing campaign (e.g.COVID-19) and exploited vulnerabilities (e.g.CVE-2017-11882).
Request
\n$ polyswarm tag listResponse
\nTag: Adware\nTag: AgentTesla\nTag: Android\nTag: Cerberus\nTag: COVID-19\nTag: CVE-2017-11882\nTag: Emotet\nTag: EventBotUsing Families
\nFormat: polyswarm family list
Description: PolySwarm families are malware family names applied to known samples from a given family.
\n\nFamilies with an Emerging timestamp where listed on the PolySwarm homepage at the given time - these are particularly cutting edge or prominent in the news.
\n
Request
\n$ polyswarm family listResponse
\nFamily: Emotet\nEmerging: 2020-06-06 08:23:35.997775\n\nFamily: EventBot\nEmerging: 2020-06-10 17:15:54.789337\n\nFamily: NetWalker\nEmerging: NoneUsing Links
\nFormat: polyswarm link list --family <family>
Description: Artifacts are linked to tags and families.
\nRequest
\n$ polyswarm link list --family EmotetResponse
\nSHA256: 8c8f9556b67c36cf23fea64e2f2086a5bbcddabd5c66b9847fac1c60c021eeba\nFirst seen: 2023-04-29 22:17:41.507473\nTags: ['Banker', 'Unpacked', 'Trojan', 'PE32', 'Windows']\nFamilies: ['Emotet']\nEmerging: None\n\nSHA256: dd168d5499cfd09ac35b70656983a2b5600bfea09319df5a4aa4260e20745111\nFirst seen: 2023-04-29 14:24:31.835017\nTags: ['Banker', 'Unpacked', 'PE32', 'Windows', 'first_seen']\nFamilies: ['Emotet']\nEmerging: 2023-05-08 18:40:55.769796\n\nGetting a list of SHA256 hashes for these artifacts is correspondingly as simple as:
\npolyswarm link list --family Emotet | grep SHA256.
Sandboxing
\nSandboxing in PolySwarm provides the ability to submit files directly to be sandboxed to either Cape or Triage, submit Artifacts already in PolySwarm to be sandboxed, and review what has been submitted to be sandboxed.
\nGeneral Sandbox Questions & Answers
\nWhat is the difference between cape and triage. And when should they select one vs the other?
\nCAPE sandbox is specifically designed to extract malware payload and configuration files, hence the name CAPE (Config and Payload Extraction). It attempts to unpack malware so yara signatures can be used to identify a specific malware family and if it is supported by the different config and payload extractors the sandbox has then those data can be extracted.\nTriage on the other hand is designed to scale and process as many malware as possible in a given day. They also support other malware types such as android. The sandbox is well versed in tackling malware that have anti-sandbox evasion techniques.
\nIf you want to gather more data from malware like a typical sandbox would and have a better chance of executing a malware regardless of whether it is using anti-analysis or anti-sandboxing techniques, Triage would be the best choice.\nIf the you want to get malware payload or config data that includes IPs and domains that were not used during the sandboxing session and is kept in the malware's back pocket, then CAPE is the sandbox of choice.
\nURL Sandboxing is only supported using Triage as of today, we will update this section as further URL Sandboxing support is expanded.
\nList Sandbox Providers
\nFormat: polyswarm sandbox providers
Description: List the supported sandbox providers, to include: sandbox name, sandbox VMs, and version information.
\n\n\nNote: For the
\nsandbox vmparameter in the sandbox file and artifact commands, use the value of theslugfield in the sandbox providers output.
Request
\n$ polyswarm sandbox providersResponse
\n============================= Provider =============================\nslug: cape\nname: cape\ntool: cape_sandbox_v2\n\t============================= VM =============================\n\tarchitecture: x64\n\tid: 100\n\tlanguage: English (United States)\n\tname: Microsoft Windows 10 Pro Build 19041\n\tos_name: Microsoft Windows 10 Pro\n\tos_version: 10.0.19041 Build 19041\n\tslug: win-10-build-19041\n============================= Provider =============================\nslug: triage\nname: triage\ntool: triage_sandbox_v0\n\t============================= VM =============================\n\tapi_level: 30\n\tarchitecture: x64\n\tid: 201\n\tlanguage: English (United States)\n\tname: android-11-x64\n\tos_name: Android 11 x64\n\tprofile: droid\n\tslug: android-11-x64\n\t============================= VM =============================\n\tArchitecture: x64\n\tid: 200\n\tlanguage: English (United States)\n\tname: windows10-1703-x64\n\tos_name: Windows 10 1703 x64\n\tos_version: 10.0.15063 Build 15063\n\tprofile: poly\n\tslug: win10-build-15063Sandboxing a File
\n\n\nWant to know what files types are supported? See here
\n
Format: polyswarm sandbox file <sandbox> <file path> --vm_slug <sandbox vm>
Description: Submit a new File stored locally to be sandboxed, define the sandbox name, file path or the optional sandbox vm. Sandbox Analysis will take around 2-5 minutes before the results can be accessed.
\n\n\nTo find the
\nsandboxname andsandbox vmsee this section.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--vm_slug | \nstring | \nfalse | \nDefine the Sandbox image to use. | \n
-z, --is-zip | \nbool | \nfalse | \nWill handle the provided file as a zip and decompress server side. | \n
-p, --zip-password | \nstring | \nfalse | \nUsed to provide a password to decompress the zip file with. | \n
--internet-disabled | \nbool | \nfalse | \nDisable internet access in sandbox when processing the sample. | \n
Request
\n$ polyswarm sandbox file triage ./tests/eicar.yara --vm_slug windows11-21h2-x64Response
\n============================= Sandbox Task =============================\nid: 30536618894625674\nsha256: None\nsandbox: triage\ncreated: 2023-06-20T18:47:46.242045\ncommunity: pi\ninstance id: 95454528418762552\nstatus: PENDINGSandboxes have multiple returned statuses, these are listed below.
\n| Status | \nWhat is it for? | \n
|---|---|
Success | \nFinished processing correctly. | \n
Started | \nSandbox session has started. | \n
Collecting Data | \nSandbox session has been successful and data is being collected. | \n
Failed | \nSandbox session has failed, this can be due to many reasons. | \n
Pending | \nSandbox session is queued up and ready to start. | \n
Timed out | \nSandbox session has timed out and quota has not been reimbursed. | \n
Delayed | \nSandbox session has been delayed and will start soon. | \n
Failed with Quota Reimbursement | \nFinished processing but failed, quota will be reimbursed. | \n
Timed out with Quota Reimbursement | \nDelayed in the queue for too long, got timed out and then reimbursement. | \n
Sandboxing a URL or QR Code
\nFormat: polyswarm sandbox url <PROVIDER> [URL]
Description: Submit a URL to be sandboxed, define the sandbox PROVIDER name (e.g. triage or cape), the URL (unless --qrcode-file is used), and the optional sandbox vm and browser arguments.
\n\nTo find the
\nsandboxname and sandbox VMs see this section.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--vm_slug | \nstring | \nfalse | \nDefine the Sandbox image to use. | \n
--browser | \nstring | \nfalse | \nDefine a browser to detonate the url in, only edge supported. | \n
--qrcode-file | \nstring | \nfalse | \nPath of a QR Code image file that contains an URL as a payload. | \n
Request
\n$ polyswarm sandbox url triage www.polyswarm.io --vm_slug windows11-21h2-x64Response
\n============================= Sandbox Task =============================\nid: 20806200704232355\nsha256: None\nsandbox: triage\ncreated: 2024-02-22T10:51:48.722414\ncommunity: mainnet1\ninstance id: 7708689624900884\nstatus: PENDINGSandboxing an Existing Artifact
\nFormat: polyswarm sandbox instance <PROVIDER> <atifact_id>
Description: Submit an already-scanned artifact for processing by the sandboxes. The required arguments are the Artifact id and the sandbox name.
\n\nTo obtain the
\nartifact_idrequired you can use the commandpolyswarm --fmt pretty-json search hash <hash> | jq '.artifact_id'and for thesandboxand--vm_slugsee here.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--vm_slug | \nstring | \nfalse | \nDefine the Sandbox image to use. | \n
--internet-disabled | \nbool | \nfalse | \nDisable internet access in sandbox when processing the sample. | \n
Request
\n$ polyswarm sandbox instance triage 50667050680164455 --vm_slug windows11-21h2-x64Response
\n============================= Sandbox Task =============================\nid: 76509232912518724\nsha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e\nsandbox: triage\ncreated: 2023-06-20T18:53:47.027083\ncommunity: pi\ninstance id: 5821643847114768\nstatus: PENDINGLookup Sandbox Task
\nFormat: polyswarm sandbox lookup-id <task_id>
Description: Look up the status of a specific sandbox task with the ID.
\n\n\nThe ID can be found once a file, or existing artifact has been submitted. CLI commands like
\nsandbox searchandsandbox my-tasksalso provide the ID.
Request
\n$ polyswarm sandbox lookup-id 76509232912518724Response
\n============================= Sandbox Task =============================\nid: 76509232912518724\nsha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e\nsandbox: triage\ncreated: 2023-06-20T18:53:47.027083\ncommunity: pi\ninstance id: 5821643847114768\nstatus: STARTEDLookup Latest Sandbox Task
\nFormat: polyswarm sandbox lookup <PROVIDER> <hash>
Description: Look up the status of the latest sandbox task for a hash, including a list of files like pcap, jarm and report.
\n\n\nFeed the
\n--fmt pretty-jsonoption into the command to view the full metadata set of information.
Request
\n$ polyswarm sandbox lookup triage e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876eResponse
\n============================= Sandbox Task =============================\nid: 97818287069750641\nsha256: 2345c426c584ec12f7a2106a52ce8ac4aeb144476d1a4e4b78c10addfddef920\nsandbox: triage\ncreated: 2023-06-26T15:21:30.054231\ncommunity: mainnet1\ninstance id: 29588752444918666\nstatus: SUCCEEDED\nsandbox artifacts:\n\tdropped_file: triage_dropped_file, PE32+ executable (GUI) x86-64, for MS Windows, instance id: 98765579577983166\n\treport: triage_report.json, application/json, instance id: 23250223674696404\n\traw_report: triage_raw_report.json, application/json, instance id: 70519139222788003\n\tdropped_file: triage_dropped_file, PE32+ executable (DLL) (console) x86-64, for MS Windows, instance id: 76909336038197831\n....\n\nNote: Each file will have its own
\ninstance_idthat will be required to download the artifact/file.
Download Sandbox Artifacts
\nFormat: polyswarm download-id <instance id>
Description: Provides the ability to download Artifacts from the sandbox like the pcap, report and jarm files.
\n\n\nEach file will have its own
\ninstance_id, meaning eachinsatnce_idneeds to be defined. To find theinstance idof the file to download, use thepolyswarm sandbox lookupcli command here. When you submit a file to be sandboxed, you get a SandboxTask ID. When the sandboxing is done, you can get the results for that sandboxtask. If you look at the json output, it will contain a SandboxArtifacts section. Each item in the SandboxArtifacts has an artifact ID.
Request
\n$ polyswarm download-id 76909336038197831Response
\nSuccessfully downloaded artifact b1c52c16bd34314685b2147687d3d82d3032ad1066493538a9547a5b1cdf2254 to /Users/name/Desktop/b1c52c16bd34314685b2147687d3d82d3032ad1066493538a9547a5b1cdf2254List my sandbox tasks
\nFormat: polyswarm sandbox my-tasks
Description: List all the sandbox tasks submitted by you or anyone in your team with the status of these.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--provider | \nstring | \nfalse | \nSearch on the sandbox name. | \n
--start-date | \nstring | \nfalse | \nProvide a start date for searching sandbox tasks. | \n
--end-date | \nstring | \nfalse | \nProvide a end date for searching sandbox tasks. | \n
--sha256 | \nstring | \nfalse | \nOnly list tasks with the SHA256 passed. | \n
--user-account-id | \ninteger | \nfalse | \nUser account that created the sandbox task. | \n
Request
\n$ polyswarm sandbox my-tasksResponse
\n============================= Sandbox Task =============================\nid: 76509232912518724\nsha256: e7dcfa7e44cfea923e8d1bde56a480ff3d18e2b7221c8d5e50bf753b1a5e876e\nsandbox: triage\ncreated: 2023-06-20T18:53:47.027083\ncommunity: pi\ninstance id: 5821643847114768\nstatus: SUCCEEDED\naccount number: 582193978313\nteam account number: 582193978313\n\n============================= Sandbox Task =============================\nid: 30536618894625674\nsha256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40\nsandbox: triage\ncreated: 2023-06-20T18:47:46.242045\ncommunity: pi\ninstance id: 95454528418762552\nstatus: PENDING\naccount number: 582193978313\nteam account number: 582193978313Search Sandbox Tasks
\nFormat: polyswarm sandbox search <HASH>
Description: Search sandbox tasks by sha256, sandbox provider, status, start date and/or end date in order to filter out the results.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--provider | \nstring | \nfalse | \nSearch on the sandbox name. | \n
--status | \nstring | \nfalse | \nFilter by status i.e. pending. | \n
--start-date | \nstring | \nfalse | \nProvide a start date for searching sandbox tasks. | \n
--end-date | \nstring | \nfalse | \nProvide a end date for searching sandbox tasks. | \n
--account-id | \ninteger | \nfalse | \nAccount that created the sandbox task. | \n
Request
\n$ polyswarm sandbox search 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40Response
\n============================= Sandbox Task =============================\nid: 30536618894625674\nsha256: 18e5b8fe65e8f73c3a4a637c258c02aeec8a6ab702b15b7ee73f5631a9879e40\nsandbox: triage\ncreated: 2023-06-20T18:47:46.242045\ncommunity: pi\ninstance id: 95454528418762552\nstatus: PENDINGHunting with Yara
\nManaging Yara Rulesets
\nThis section will walk through creating a Yara ruleset(s), viewing the ruleset contents, listing all rulesets, updating a ruleset and deleting a ruleset.
\nCreating a Ruleset
\nFormat: polyswarm rules create eicar <file.yara>
Description: The first step to hunting with Yara rules is to create your Yara ruleset(s).
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-d, --description | \nstring | \nfalse | \nDescription of the ruleset. | \n
Request
\n$ polyswarm rules create eicar eicar.yaraResponse
\nRuleset Id: 57611858371350090\nName: eicar\nDescription: None\nCreated at: 2022-05-26 21:00:09.401395\nModified at: 2022-05-26 21:00:09.401395View a Ruleset List
\nFormat: polyswarm rules list
Description: It is also possible to list all the rulesets that exist in your account.
\nRequest
\n$ polyswarm rules listResponse
\nRuleset Id: 57611858371350090\nName: eicar\nDescription: None\nCreated at: 2022-05-26 21:00:09.401395\nModified at: 2022-05-26 21:00:09.401395\n\nRuleset Id: 6094816616323164\nName: eicar\nDescription: None\nCreated at: 2022-05-26 18:42:41.806803\nModified at: 2022-05-26 18:45:04.864430Inspect a Yara Ruleset Contents
\nFormat: polyswarm rules view <Ruleset ID>
Description: You can use the Ruleset Id to inspect the contents of the Yara ruleset you created.
\n\nFind the Ruleset ID of the Ruleset with the command
\npolyswarm rules list
Request
\n$ polyswarm rules view 57611858371350090Response
\nRuleset Id: 57611858371350090\nName: eicar\nDescription: None\nCreated at: 2022-05-26 21:00:09.401395\nModified at: 2022-05-26 21:00:09.401395\nRuleset Contents:\nrule eicar_av_test {\n /*\n Per standard, match only if entire file is EICAR string plus optional trailing whitespace.\n The raw EICAR string to be matched is:\n X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*\n */\n\n meta:\n description = \"This is a standard AV test, intended to verify that BinaryAlert is working correctly.\"\n author = \"Austin Byers | Airbnb CSIRT\"\n reference = \"http://www.eicar.org/86-0-Intended-use.html\"\n\n strings:\n $eicar_regex = /^X5O!P%@AP\\[4\\\\PZX54\\(P\\^\\)7CC\\)7\\}\\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\\$H\\+H\\*\\s*$/\n\n condition:\n all of them\n}\n\nrule eicar_substring_test {\n /*\n More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)\n */\n\n meta:\n description = \"Standard AV test, checking for an EICAR substring\"\n author = \"Austin Byers | Airbnb CSIRT\"\n\n strings:\n $eicar_substring = \"$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\"\n\n condition:\n all of them\n}Update a Yara Ruleset
\nFormat: polyswarm rules update <ruleset id> --name <NEW NAME> --file <file.yara>
Description: Update the ruleset using the update command or update the yara ruleset.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-n, --name | \nstring | \nfalse | \nName of the ruleset. | \n
-f, --file | \nstring | \nfalse | \nFile containing yara rules. | \n
-d, --description | \nstring | \nfalse | \nDescription of the ruleset. | \n
Request
\n$ polyswarm rules update 57611858371350090 --name EiCaRResponse
\nRuleset Id: 57611858371350090\nName: EiCaR\nDescription: None\nCreated at: 2022-05-26 21:00:09.401395\nModified at: 2022-05-26 21:03:09.500600Deleting a YARA Ruleset
\nFormat: polyswarm rules delete <Ruleset ID>
Description:Delete a ruleset if there is not a live hunt running associated with it.
\nRequest
\n$ polyswarm rules delete 57611858371350090Response
\nRuleset Id: 57611858371350090\nName: EiCaR\nDescription: None\nCreated at: 2022-05-26 21:00:09.401395\nModified at: 2022-05-26 21:03:45.551115Live Hunting
\nLive Hunting offers users the valuable capability to employ a YARA ruleset for matching against artifacts submitted in real time to PolySwarm's extensive dataset.
\nStart a Live Hunt
\nFormat: polyswarm live start <ruleset_id>
Description: Start a live hunt, Every live hunt that is active must be associated with a Yara ruleset. Because of this, you need to provide the rulset_id when starting a live hunt.
Request
\n$ polyswarm live start 57989886451857569Response
\nRuleset Id: 57989886451857569\nLive Hunt Id: 86677820494666932\nLive Hunt Created at: 2022-05-26T21:14:29.334580\nName: eicar\nDescription: None\nCreated at: 2022-05-26 18:48:38.048514\nModified at: 2022-05-26 21:14:29.207665Stop a Live Hunt
\nFormat: polyswarm live stop <ruleset_id>
Description: Similarly, you can stop a live hunt providing the ruleset_id it is associated with.\nWhen you start the live hunt for the same ruleset_id, a new live_hunt_id is generated.\nThe Ruleset cannot be deleted or modified while it has an active live hunt associated with it.
Request
\n$ polyswarm live stop 57989886451857569Response
\nRuleset Id: 57989886451857569\nName: eicar\nDescription: None\nCreated at: 2022-05-26 18:48:38.048514\nModified at: 2022-05-26 21:17:29.079046View Live Results of a Live Hunt
\nFormat: polyswarm live feed
Description: You can see all the live results generated from all the live hunts in your feed.\nThey are reverse chronologically ordered.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --rule-name | \nstring | \nfalse | \nFilter results on the rule name | \n
-f, --family | \nstring | \nfalse | \nFilter hunt based on the family name | \n
-p, --private | \nstring | \nfalse | \nFilter results to only your Private Community, if not defined results are shown from your Private Community and the Public Community. | \n
-u, --polyscore-upper | \nstring | \nfalse | \nPolyscore upper bound for the hunt results | \n
Request
\n$ polyswarm live feedResponse
\nId: 32552275040389723\nInstance Id: 33280875575725264\nCreated at: 2022-05-26 21:15:27.507020\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}\n\nId: 34271764645034598\nInstance Id: 33280875575725264\nCreated at: 2022-05-26 21:15:27.494428\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_av_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}View a Singular Result
\nFormat: polyswarm live result <instance_id>
Description: You can inspect a particular result and get a download link using the result command.
Request>
\n$ polyswarm live result 32552275040389723Response
\nId: 32552275040389723\nInstance Id: 33280875575725264\nCreated at: 2022-05-26 21:15:27.507020\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}\nDownload Url: http://minio:9000/cache-public/27/5a/02/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f3395856ce81f2b7382dee72602f798b642f1414044d88612fea8a8f36de82e1278abb02f?response-content-disposition=attachment%3Bfilename%3Dinfected&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T211923Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=52c1c289e0a9c86187224fbeeb6fa5122b8e9b0d196cc6440c00b665e168985cDelete a Result
\nFormat: polyswarm live results-delete <instance_id>
Description: You can also delete results from this list that are not interesting.
\nRequest
\n$ polyswarm live results-delete 32552275040389723 # you can provide more ids here, separated by spaceResponse
\nId: 32552275040389723\nInstance Id: 33280875575725264\nCreated at: 2022-05-26 21:15:27.507020\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}Historical Hunting
\nHistorical Hunting offers users the valuable capability to employ a YARA ruleset for matching against artifacts previously submitted in real time to PolySwarm's extensive dataset.
\nStart a Historical Hunt
\nFormat:\npolyswarm historical start <file.yara>
OR
\npolyswarm historical start -r <ruleset_id>
\n\nProvide the Yara ruleset directly or provide the ruleset id of the Yara Ruleset.
\n
Description: Start a new historical hunt providing the ruleset directly.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --rule-id | \ninteger | \nfalse | \nIf provided, create this historical hunt from an existing ruleset. | \n
-n, --name | \nstring | \nfalse | \nExplicitly set the ruleset name for this hunt. | \n
Request
\n$ polyswarm historical start tests/eicar.yaraResponse
\nHunt Id: 60834480310458457\nStatus: PENDING\nCreated at: 2022-05-26 21:24:20.712138\nRuleset Name: eicar.yara\nRuleset Contents:\nrule eicar_av_test {\n /*\n Per standard, match only if entire file is EICAR string plus optional trailing whitespace.\n The raw EICAR string to be matched is:\n X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*\n */\n\n meta:\n description = \"This is a standard AV test, intended to verify that BinaryAlert is working correctly.\"\n author = \"Austin Byers | Airbnb CSIRT\"\n reference = \"http://www.eicar.org/86-0-Intended-use.html\"\n\n strings:\n $eicar_regex = /^X5O!P%@AP\\[4\\\\PZX54\\(P\\^\\)7CC\\)7\\}\\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\\$H\\+H\\*\\s*$/\n\n condition:\n all of them\n}\n\nrule eicar_substring_test {\n /*\n More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)\n */\n\n meta:\n description = \"Standard AV test, checking for an EICAR substring\"\n author = \"Austin Byers | Airbnb CSIRT\"\n\n strings:\n $eicar_substring = \"$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\"\n\n condition:\n all of them\n}\n\nHistorical hunt will activate upon creation. They are created in the
\nPENDINGstate and\nare scheduled for execution during the next processing window.
View a Historical Hunt Status
\nFormat: polyswarm historical list
Description: You can see the state of your historical hunts when you use the list command.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-s, --since | \ninteger | \nfalse | \nHow far back in seconds to request results. | \n
Request
\n$ polyswarm historical listResponse
\nHunt Id: 86933257769414706\nStatus: PENDING\nCreated at: 2022-05-26 21:25:35.467834\nRuleset Name: eicar\n\nHunt Id: 60834480310458457\nStatus: PENDING\nCreated at: 2022-05-26 21:24:20.712138\nRuleset Name: eicar.yara\n\nHunt Id: 79157116618547376\nStatus: PENDING\nCreated at: 2022-05-26 19:07:25.339932\nRuleset Name: eicar.yara\n\nHunt Id: 48011760326110718\nStatus: LIMITED\nProgress: 100.00%\nCreated at: 2022-05-26 17:53:07.832218\nTotal count: 6\n\teicar_av_test: 3\n\teicar_substring_test: 3\nRuleset Name: eicar.yaraCancel a Historical Hunt
\nFormat: polyswarm historical cancel <hunt_id>
Description: You can cancel a historical if you don't want it to finish by providing the hunt id. It will prevent further processing.
\nRequest
\n$ polyswarm historical cancel 86933257769414706Response
\nHunt Id: 86933257769414706\nStatus: CANCELED\nCreated at: 2022-05-26 21:25:35.467834\nRuleset Name: eicar\nRuleset Contents:\nrule eicar_av_test {\n /*\n Per standard, match only if entire file is EICAR string plus optional trailing whitespace.\n The raw EICAR string to be matched is:\n X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*\n */\n\n meta:\n description = \"This is a standard AV test, intended to verify that BinaryAlert is working correctly.\"\n author = \"Austin Byers | Airbnb CSIRT\"\n reference = \"http://www.eicar.org/86-0-Intended-use.html\"\n\n strings:\n $eicar_regex = /^X5O!P%@AP\\[4\\\\PZX54\\(P\\^\\)7CC\\)7\\}\\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\\$H\\+H\\*\\s*$/\n\n condition:\n all of them\n}\n\nrule eicar_substring_test {\n /*\n More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)\n */\n\n meta:\n description = \"Standard AV test, checking for an EICAR substring\"\n author = \"Austin Byers | Airbnb CSIRT\"\n\n strings:\n $eicar_substring = \"$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\"\n\n condition:\n all of them\n}Delete a Historical Hunt
\nFormat: polyswarm historical delete <hunt_id>
Description: You can also delete a historical hunt. The results associated with it will also be removed.
\n\n\nSince there can be a large number of results, this is an asynchronous task and might take a while to finish after it is requested.
\n
Request
\n$ polyswarm historical delete 86933257769414706Response
\nSuccessfully deleted Hunt:\nHunt Id: 86933257769414706\nStatus: DELETING\nCreated at: 2022-05-26 21:25:35.467834\nRuleset Name: eicar\nRuleset Contents:\nrule eicar_av_test {\n /*\n Per standard, match only if entire file is EICAR string plus optional trailing whitespace.\n The raw EICAR string to be matched is:\n X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*\n */\n\n meta:\n description = \"This is a standard AV test, intended to verify that BinaryAlert is working correctly.\"\n author = \"Austin Byers | Airbnb CSIRT\"\n reference = \"http://www.eicar.org/86-0-Intended-use.html\"\n\n strings:\n $eicar_regex = /^X5O!P%@AP\\[4\\\\PZX54\\(P\\^\\)7CC\\)7\\}\\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\\$H\\+H\\*\\s*$/\n\n condition:\n all of them\n}\n\nrule eicar_substring_test {\n /*\n More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)\n */\n\n meta:\n description = \"Standard AV test, checking for an EICAR substring\"\n author = \"Austin Byers | Airbnb CSIRT\"\n\n strings:\n $eicar_substring = \"$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\"\n\n condition:\n all of them\n}View or Download Historical Hunt Details
\nFormat: polyswarm historical view <hunt_id>
Description: You can view details about the historical hunt and download a summary csv using the view command.
Request
\n$ polyswarm historical view 48011760326110718Response
\nHunt Id: 48011760326110718\nStatus: LIMITED\nProgress: 100.00%\nCreated at: 2022-05-26 17:53:07.832218\nTotal count: 6\n\teicar_av_test: 3\n\teicar_substring_test: 3\nDownload Results CSV:\n\thttp://minio:9000/historical/72/48/e9/7248e979625acf9f527e3ab7c8c0125e72e9b0a30b9a308b1617d475c8bcbf6bf27d52363bf2cd7b2359c70c6aac1de2ddad7daebc660cb805c99b51d4e4ff9648fe7eb1?response-content-disposition=attachment%3Bfilename%3D48011760326110718.csv&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213205Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=df334159d7a2a334f6fb0deffd6edc334f6f9188f4d29777b15a0575600114ff\nRuleset Name: eicar.yara\nRuleset Contents:\nrule eicar_av_test {\n /*\n Per standard, match only if entire file is EICAR string plus optional trailing whitespace.\n The raw EICAR string to be matched is:\n X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*\n */\n\n meta:\n description = \"This is a standard AV test, intended to verify that BinaryAlert is working correctly.\"\n author = \"Austin Byers | Airbnb CSIRT\"\n reference = \"http://www.eicar.org/86-0-Intended-use.html\"\n\n strings:\n $eicar_regex = /^X5O!P%@AP\\[4\\\\PZX54\\(P\\^\\)7CC\\)7\\}\\$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\\$H\\+H\\*\\s*$/\n\n condition:\n all of them\n}\n\nrule eicar_substring_test {\n /*\n More generic - match just the embedded EICAR string (e.g. in packed executables, PDFs, etc)\n */\n\n meta:\n description = \"Standard AV test, checking for an EICAR substring\"\n author = \"Austin Byers | Airbnb CSIRT\"\n\n strings:\n $eicar_substring = \"$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!\"\n\n condition:\n all of them\n}View Results of a Historical Hunt
\nFormat: polyswarm historical results <hunt_id>
Description: You can see the results of a particular hunt using its hunt_id.
Options
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
-r, --rule-name | \nstring | \nfalse | \nFilter results on the rule name | \n
-f, --family | \nstring | \nfalse | \nFilter hunt based on the family name | \n
-p, --private | \nstring | \nfalse | \nFilter results to only your Private Community, if not defined results are shown from your Private Community and the Public Community. | \n
-l, --polyscore-lower | \nstring | \nfalse | \nPolyscore lower bound for the hunt results | \n
-u, --polyscore-upper | \nstring | \nfalse | \nPolyscore upper bound for the hunt results | \n
Request
\n$ polyswarm historical results 48011760326110718Response
\nId: 34417123788028549\nInstance Id: 72401552809848506\nCreated at: 2022-05-26 17:54:56.489448\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}\n\nId: 89734617019442134\nInstance Id: 72401552809848506\nCreated at: 2022-05-26 17:54:56.489448\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_av_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}\n\nId: 55984849350345511\nInstance Id: 72401552809848506\nCreated at: 2022-05-26 17:54:56.489448\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}View or Download a Single Result of a Historical Hunt
\nFormat: polyswarm historical result <id>
Description: You can inspect details and download the file for a result with the result command. You will need the ID which you can find with the polyswarm historical view <hunt_id> command.
Request
\n$ polyswarm historical result 34417123788028549Response
\nId: 34417123788028549\nInstance Id: 72401552809848506\nCreated at: 2022-05-26 17:54:56.489448\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}\nDownload Url: http://minio:9000/cache-public/27/5a/02/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f3395856ce81f2b7382dee72602f798b642f1414044d88612fea8a8f36de82e1278abb02f?response-content-disposition=attachment%3Bfilename%3Dinfected&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220526T213355Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=bdd77765df45c068cd8f0d16580363003f9490ead7f4ff758aeada39bdcf9f96Delete Historical Hunt Results
\nFormat: polyswarm historical results-delete <id>
Description: You can delete an undesirable result by providing the ID or a list of ID's.
\nRequest
\n$ polyswarm historical results-delete 34417123788028549 # you can provide a list of ids here, space separatedResponse
\nId: 34417123788028549\nInstance Id: 72401552809848506\nCreated at: 2022-05-26 17:54:56.489448\nSHA256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f\nRule: eicar_substring_test\nPolyScore: 0.23213458159978606066\nDetections: 1/1 engines reported malicious\nTags: {}Cat Artifacts
\nFormat: polyswarm cat <hash> |hexdump -C
Description: Cat artifact to stdout. Perform feature extraction from artifact without downloading.
\nRequest
\n$ # Get C&C from malware config\n$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |hexdump -C>Response
\n00000000 c3 3e 34 65 04 b3 00 00 00 00 00 00 00 00 00 00 |.>4e............|\n00000010 6c f7 51 3a 6b 01 00 00 1e 00 02 00 e8 03 00 00 |l.Q:k...........|\n00000020 10 27 00 00 c0 d4 01 00 c0 d4 01 00 e0 93 04 00 |.'..............|\n00000030 c0 27 09 00 10 27 00 00 |.'...'..|\n00000038\n$ polyswarm cat 3b08ce97c512c695c0258c2d0fce86648a28cceb1ce98e0456413e339c7908e8 |od -An -t u1 -N 4|sed 's/^ //;s/\\s\\{1,\\}/./g'\n195.62.52.101Chain commands
\nSome commands in the CLI are composable using the sha256 format option and the unix pipe character |.\nFor instance, if we wanted to download all the results matching a metadata query:
Request
\n$ polyswarm --fmt sha256 search metadata 'strings.domains:malicious.com' | polyswarm download malicious -r -Response
\nSuccessfully downloaded artifact 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267 to /home/user/malicious/131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267Or we may want to download the last new samples matched in Live Hunting for the last 1 hour:
\nRequest
\n$ polyswarm --fmt sha256 live feed -s 3600 | polyswarm download /tmp/download -r -Response
\nSuccessfully downloaded artifact 513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831 to /tmp/download/513c197e7a88299b217dccc8fa16489c83d0abb06367eb2b14ef3a74102d7831\nSuccessfully downloaded artifact 7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724 to /tmp/download/7aba0a7ff6e263591e33c5c5c644e0fa6a70d299beced8705983189ded448724\nSuccessfully downloaded artifact 2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9 to /tmp/download/2f4a9ef2071ee896674e3da1a870d4efab4bb16e2e26ea3d7543d98b614ceab9\nSuccessfully downloaded artifact a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875 to /tmp/download/a82dd93585094aeba4363c5aeedd1a85ef72c60a03738b25d452a5d895313875\nSuccessfully downloaded artifact b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce to /tmp/download/b2d29bb9350a0df93d0918c0208af081f917129ee46544508f2e1cf30aa4f4ce\nSuccessfully downloaded artifact bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142 to /tmp/download/bf2cdd1dc2e20c42d2451c83b8280490879b3515aa6c15ab297419990e017142\nSuccessfully downloaded artifact ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6 to /tmp/download/ba04eacaa80bb5da6b02e1e7fdf3775cf5a44a6179b2c142605e089d78a2f5b6\nSuccessfully downloaded artifact a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4f to /tmp/download/a7656ccba0946d25a4efd96f4f4576494d5f1e23e6ad2acc16d2e684656a2d4fLookup UUIDs
\nFormat: polyswarm rules create eicar <file.yara>
Description: Scan results are referenced by their Submission UUID.
\nRequest
\n$ polyswarm -vvv -o /tmp/test.json --fmt json lookup 50446025732260182\n\nIn this example, we demonstrate the
\n--fmt jsonoption, which saves the output in json format.
Response
\ninfo [polyswarm.base]: Running polyswarm-cli version 2.0.0 with polyswarm_api version 2.0.0\ndebug [polyswarm_api.api]: Creating PolyswarmAPI instance: api_key: cc2fdb7efa803cefcebd3c9750aab0ee, api_uri: https://api.polyswarm.network/v2, community: default\ndebug [polyswarm_api.http]: Creating PolyswarmHTTP instance\ndebug [polyswarm_api.endpoint]: Creating PolyswarmRequestGenerator instance\ndebug [polyswarm_api.endpoint]: Creating PolyswarmRequest instance.\ndebug [polyswarm_api.endpoint]: Request parameters: {'method': 'GET', 'url': 'https://api.polyswarm.network/v2/consumer/submission/default/50446025732260182'}\ndebug [polyswarm_api.endpoint]: Result parser: ArtifactInstance\ndebug [polyswarm_api.endpoint]: Executing request.\ndebug [urllib3.connectionpool]: Starting new HTTPS connection (1): api.polyswarm.network:443\ndebug [urllib3.connectionpool]: https://api.polyswarm.network:443 \"GET /v2/consumer/submission/default/50446025732260182 HTTP/1.1\" 200 None\ndebug [polyswarm_api.endpoint]: Request returned code 200 with content:\ndebug [polyswarm_api.endpoint]: b'{\"result\":{\"artifact_id\":\"79510820469876527\",\"assertions\":[{\"author\":\"0x45b94B4AFE4E4B5Bd7f70B84919fba20f1FAfB3f\",\"author_name\":\"Qihoo 360\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"Qihoo 360\"},\"mask\":true,\"metadata\":{\"malware_family\":\"qex.eicar.gen.gen\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"}}},\"verdict\":true},{\"author\":\"0xbec683492f5D509e119fB1B60543A1Ca595e0Df9\",\"author_name\":\"Lionic\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"Lionic\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"}}},\"verdict\":false},{\"author\":\"0x162675F361F6ff8D6F91e4833f4BA94587AF3655\",\"author_name\":\"XVirus\",\"bid\":\"812500000000000000\",\"engine\":{\"description\":null,\"name\":\"XVirus\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"},\"vendor_version\":\"3.0.2.0\",\"version\":\"0.2.0\"}},\"verdict\":false},{\"author\":\"0x80Ed773972d8BA0A4FacF2401Aca5CEba52F76dc\",\"author_name\":\"Nucleon\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":\"Nucleon, The only provider that guarantees 0% false positive. using Nucleon unique offering organizations can reduce thier TCO dramtically and enjoy cyber intelligence like governments have.\",\"name\":\"Nucleon\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"vendor_version\":\"\",\"version\":\"0.1.0\"}},\"verdict\":false},{\"author\":\"0x8d80CEe474b9004949Cf7e4BfA28460AC8e370a1\",\"author_name\":\"Virusdie\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"Virusdie\"},\"mask\":true,\"metadata\":{\"malware_family\":\"EICAR.TEST\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"vendor_version\":\"1.3.0\",\"version\":\"0.3.0\"}},\"verdict\":true},{\"author\":\"0x7839aB10854505aBb712F10D1F66d45F359e6c89\",\"author_name\":\"Ikarus\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"Ikarus\"},\"mask\":true,\"metadata\":{\"malware_family\":\"EICAR-Test-File\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"signatures_version\":\"21.02.2020 13:15:46 (102417)\",\"vendor_version\":\"5.2.9.0\",\"version\":\"0.2.0\"}},\"verdict\":true},{\"author\":\"0x3750266F07E0590aA16e55c32e08e48878010f8f\",\"author_name\":\"ClamAV\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"ClamAV\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"vendor_version\":\"ClamAV 0.101.4/25730/Fri Feb 21 12:08:06 2020\"}},\"verdict\":false},{\"author\":\"0x10A9eE8552f2c6b2787B240CeBeFc4A4BcB96f27\",\"author_name\":\"Alibaba\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"Alibaba\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"}},\"type\":\"eicar\"},\"verdict\":false},{\"author\":\"0xbE0B3ec289aaf9206659F8214c49D083Dc1a9E17\",\"author_name\":\"K7\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"K7\"},\"mask\":true,\"metadata\":{\"malware_family\":\"EICAR_Test_File\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"},\"signatures_version\":\"11.95.33362, 21-Feb-2020\",\"vendor_version\":\"15.2.0.42\",\"version\":\"0.2.0\"}},\"verdict\":true},{\"author\":\"0x2b4C240B376E5406C5e2559C27789d776AE97EFD\",\"author_name\":\"NanoAV\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"NanoAV\"},\"mask\":true,\"metadata\":{\"malware_family\":\"Marker.Dos.EICAR-Test-File.dyb\",\"scanner\":{\"environment\":{\"architecture\":\"AMD64\",\"operating_system\":\"Windows\"},\"signatures_version\":\"0.14.33.17090\",\"vendor_version\":\"1.0.134.90567\",\"version\":\"0.1.0\"}},\"verdict\":true},{\"author\":\"0xb9b1FA288F7b1867AEF6C044CDE12ab2De252113\",\"author_name\":\"VenusEye\",\"bid\":\"812500000000000000\",\"engine\":{\"description\":null,\"name\":\"VenusEye\"},\"mask\":true,\"metadata\":{\"malware_family\":\"\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"version\":\"0.1.0\"}},\"verdict\":false},{\"author\":\"0xBAFcaF4504FCB3608686b40eB1AEe09Ae1dd2bc3\",\"author_name\":\"DrWeb\",\"bid\":\"1000000000000000000\",\"engine\":{\"description\":null,\"name\":\"DrWeb\"},\"mask\":true,\"metadata\":{\"malware_family\":\"EICAR Test File (NOT a Virus!)\",\"scanner\":{\"environment\":{\"architecture\":\"x86_64\",\"operating_system\":\"Linux\"},\"signatures_version\":\"864BFD34E93FFC1BEFC260DAE804EFAF, 2020-Feb-21 16:59:42\",\"vendor_version\":\"7.00.44.12030\",\"version\":\"0.3.0\"}},\"verdict\":true}],\"community\":\"lima\",\"country\":\"US\",\"created\":\"2020-02-21T19:21:59.196578\",\"extended_type\":\"EICAR virus test files\",\"failed\":false,\"filename\":\"malicious.txt\",\"first_seen\":\"2020-01-24T21:56:21.456900\",\"id\":\"50446025732260182\",\"last_seen\":\"2020-02-21T19:21:59.196578\",\"md5\":\"a6a57bf20416a4c712c4a1eabcaeb235\",\"metadata\":[{\"created\":\"2020-02-20T22:29:45.801434\",\"tool\":\"strings\",\"tool_metadata\":{\"domains\":[],\"ipv4\":[],\"ipv6\":[],\"urls\":[]}},{\"created\":\"2020-02-20T22:29:45.675692\",\"tool\":\"hash\",\"tool_metadata\":{\"md5\":\"a6a57bf20416a4c712c4a1eabcaeb235\",\"sha1\":\"a33fb79e9c71f1b446607d437a1984602ed47d5c\",\"sha256\":\"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\",\"sha3_256\":\"ab1256000f634456fac4fe42bbc0bf39256e4bab954dc8c8f241433d07895fad\",\"sha3_512\":\"737ec00fa15de1defdca9993c7d95058c2f30b658ef66c8b978287c1042d7ba7283d8d1130c356fbb8058bd739c5e349169ad93f4f428a830720ee107c6df288\",\"sha512\":\"2f79598bc355b385be7c7b785ec74073bf4b59b8095c1b1f7291e0dd04e5e140f700bcc583809ec63d6d98991698273c1678bd3399ec0b1b8ba9f60be151ec3b\",\"ssdeep\":\"3:a+JraNvsgzsVqSwHqajaBFSdYSDQ1SBWfQdRXn:tJuOgzskCStDmidRX\",\"tlsh\":\"ccc09b867e1dfda6530b44510171b5771829575d1de4053421d1f0f4dd677dc43741f8\"}}],\"mimetype\":\"text/plain\",\"polyscore\":0.07193209420451106,\"result\":null,\"sha1\":\"a33fb79e9c71f1b446607d437a1984602ed47d5c\",\"sha256\":\"89b7a034846a917f7f31a22778ffe04caa3c22136d0e12d1676cfd41a889b6bf\",\"size\":132,\"type\":\"FILE\",\"votes\":[{\"arbiter\":\"0xB63cD054D7E63D9Ce8AbB403a0dfa11b26A1fB89\",\"vote\":false},{\"arbiter\":\"0xd8b48Da78188312c5fC079E532afd48De973767E\",\"vote\":true},{\"arbiter\":\"0xdC6a0F9C3AF726Ba05AaC14605Ac9B3b958512d7\",\"vote\":false}],\"window_closed\":true},\"status\":\"OK\"}\\n'\ndebug [polyswarm_api.endpoint]: Parsing request results.\ndebug [polyswarm_api.types.base]: Parsing resource ArtifactInstanceFor information regarding the JSON format of a result object, please see polyswarm_api's API.md.
\nNotification Webhooks
\nNotification webhooks allow you to receive real-time notifications for events in PolySwarm, such as when sandbox analysis completes.
\nCreate a Notification Webhook
\nFormat: polyswarm webhook create <WEBHOOK_URI> <SECRET>
Description: Create a new notification webhook to receive notifications from PolySwarm events.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--status | \nstring | \nfalse | \nNotification webhook status: 'enabled' or 'disabled' (default: enabled) | \n
--events | \nstring | \nfalse | \nEvent types to subscribe to (can be specified multiple times) | \n
Request
\n$ polyswarm webhook create https://example.com/webhook your-secret-key --status enabled --events sandbox_doneResponse
\n============================= Notification Webhook =============================\nID: 12345\nWebhook URI: https://example.com/webhook\nStatus: enabled\nEvents: sandbox_done\nCreated: 2024-01-15T10:30:00+00:00Get a Notification Webhook
\nFormat: polyswarm webhook get <WEBHOOK_ID>
Description: Retrieve details about a specific notification webhook by its ID.
\nRequest
\n$ polyswarm webhook get 12345Response
\n============================= Notification Webhook =============================\nID: 12345\nWebhook URI: https://example.com/webhook\nStatus: enabled\nEvents: sandbox_done\nCreated: 2024-01-15T10:30:00+00:00Update a Notification Webhook
\nFormat: polyswarm webhook update <WEBHOOK_ID> [OPTIONS]
Description: Update an existing notification webhook’s configuration.
\nOptions
\n| Option | \nType | \nRequired | \nDescription | \n
|---|---|---|---|
--webhook-uri | \nstring | \nfalse | \nThe new notification webhook URI | \n
--secret | \nstring | \nfalse | \nThe new secret for HMAC signing | \n
--status | \nstring | \nfalse | \nThe new status: 'enabled' or 'disabled' | \n
--events | \nstring | \nfalse | \nEvent types to subscribe to (can be specified multiple times) | \n
Request
\n$ polyswarm webhook update 12345 --webhook-uri https://newexample.com/webhook --status disabledResponse
\n============================= Notification Webhook =============================\nID: 12345\nWebhook URI: https://newexample.com/webhook\nStatus: disabled\nEvents: sandbox_done\nCreated: 2024-01-15T10:30:00+00:00Delete a Notification Webhook
\nFormat: polyswarm webhook delete <WEBHOOK_ID>
Description: Delete a notification webhook permanently.
\nRequest
\n$ polyswarm webhook delete 12345Response
\nWebhook 12345 deleted successfullyList All Notification Webhooks
\nFormat: polyswarm webhook list
Description: List all notification webhooks configured for the current account.
\nRequest
\n$ polyswarm webhook listResponse
\n============================= Notification Webhook =============================\nID: 12345\nWebhook URI: https://example.com/webhook\nStatus: enabled\nEvents: sandbox_done\nCreated: 2024-01-15T10:30:00+00:00\n\n============================= Notification Webhook =============================\nID: 67890\nWebhook URI: https://another-example.com/webhook\nStatus: enabled\nEvents: sandbox_done\nCreated: 2024-01-16T14:22:00+00:00Test a Notification Webhook
\nFormat: polyswarm webhook test <WEBHOOK_ID>
Description: Test a notification webhook by sending a test payload to verify it's working correctly.
\nRequest
\n$ polyswarm webhook test 12345Response
\nTest payload sent to webhook 12345Changelog
\nVersion 3.15.0
\nRelease Date: 2026-01-28\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nNotification Webhooks | \nNew endpoint notification webhook for creating a notification webhook. | \n
| 2.0 | \nllm reports | \nNew endpoints for creating llm reports: llm-create, llm-download and llm-get | \n
| 3.0 | \nPrivate Community Expire | \nNew Options for Scan, to Expire files in a Private Community on Upload, --expiration-window. | \n
Version 3.11.0
\nRelease Date: 2025-06-02\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nNew Param for Sandbox File | \nNew --arguments for sandbox file | \n
Version 3.10.0
\nRelease Date: 2025-05-20\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nNew Argument for Sandbox my-tasks | \nsandbox my-tasks supports --user-account-id argument | \n
| 2.0 | \nNew Feature, Download Sample Bundle Zips | \nAbility to bundle files into a single zip to download, via bundle create | \n
| 3.0 | \nNew Feature, Download artifacts created by a Sandbox Task | \nAbility to download files like Sandbox Tasks report files, via download-sandbox-artifact SANDBOX_TASK_ID [INSTANCE_ID]... | \n
Version 3.9.0
\nRelease Date: 2024-12-09\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \n\"Backing Feature\" field | \nShow in the features details the new field if it's set when executing polyswarm account features. | \n
| 2.0 | \nBug Fix errors | \nFix errors when serializing some API responses. | \n
Version 3.8.1
\nRelease Date: 2024-09-24\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nUpdated Validation URL | \nLess strict validation on URLs provided as an argument when scanning and sandboxing. | \n
| 2.0 | \nError Reporting | \nScans and Sandboxing now shows the Faliure Reason if applicable in the cli response. | \n
| 3.0 | \nBug Fix Sandbox | \nFixed exception when sandbox doesn't have the config.artifact_type field set. | \n
Version 3.8.0
\nRelease Date: 2024-08-07
\nBreaking Changes: Item 5.0
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nSubmit URL from QR Code images | \nNew arg --qrcode-file in polyswarm scan url and polyswarm sandbox url | \n
| 2.0 | \nGet basic account's information | \nNew command polyswarm account whois. | \n
| 3.0 | \nGet account's features and quota available | \nNew command polyswarm account features. | \n
| 4.0 | \nNew options to create zip reports | \npolyswarm report create [--sandbox_artifact_types --zip-report-ids] | \n
| 5.0 | \nRename command argument | \n--sandbox argument is renamed to --provider. | \n
Version 3.7.0
\nRelease Date: 2024-06-27
\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nWait and download reports | \nNew --nowait, --timeout and --destination arguments in the report command. | \n
| 2.0 | \nSupport zip file submissions | \nNew --is-zip and --zip-password arguments in scan and sandbox commands. | \n
Version 3.6.0
\nRelease Date: 2024-05-20
\nBreaking Changes: Item 3.0
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nReports Generation | \nIntroduction of reports generation via the report CLI command. | \n
| 2.0 | \nReports Templates | \nIntroduction of reports templates management via the report-template CLI command. | \n
| 3.0 | \nPython versions supported | \nMinimal Python version supported is 3.7. | \n
Version 3.5.2
\nRelease Date: 2024-02-22
\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nURL Sandboxing | \nIntroduction of URL Sandboxing via the sandbox url cli command. | \n
Version 3.5.1
\nRelease Date: 2023-12-06
\nBreaking Changes: 1.0
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nIOC Search - Hash | \nPreviously ioc search by hash returned a Generator, which was not correct. This fix has resolved this issue, to prevent the has_more flag being returned. | \n
Version 3.4.1
\nRelease Date: 2023-09-20
\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nAdded Private Parameter to Live Results | \nAdded parameter --private to polyswarm live feed to allow you to see results from a private community. | \n
| 2.0 | \nAdded Private Parameter to Historical Results | \nAdded parameter --private to polyswarm historical results to allow you to see results from a private community. | \n
| 3.0 | \nNew Permalink Structure | \nNew Permalink Structure | \n
Version 3.4.0
\nRelease Date: 2023-07-12
\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \npolyswarm sandbox providers | \nNew output with provider and slug information. | \n
| 2.0 | \nUpdate to polyswarm sandbox file | \nAdded new config arguments provider_slug and vm_slug. | \n
| 3.0 | \nUpdate to polyswarm sandbox instance | \nAdded new config arguments provider_slug and vm_slug. | \n
Version 3.3.0
\nRelease Date: 2023-06-20
\nBreaking Changes: Item 2.0
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nDropping python 2.7 support | \n- | \n
| 2.0 | \npolyswarm sandbox submit changes | \nChange polyswarm sandbox submit to polyswarm sandbox instance. | \n
| 3.0 | \npolyswarm sandbox list changes | \nChange polyswarm sandbox list to polyswarm sandbox providers. | \n
| 4.0 | \nAdditional Sub-Commands for Sandbox | \nlookup, lookup-id, search, file, my-tasks. | \n
Version 3.2.1
\nRelease Date: 2023-05-29
\nBreaking Changes: N/A
\n| Item | \nTopic | \nDescription | \n
|---|---|---|
| 1.0 | \nBug fix for search ioc | \nFix an issue with results not displaying with the polyswarm search ioc command. | \n
\n\n> **A word of caution with Known Good checking!**\n>\n> Our list of known good domains and IPs is not all-inclusive!\n> Our goal for this feature is to provide an easy way to check the most common known good domains and IPs, so they can be excluded from analysis.\n\n
\n\n## Tags/Lists/Families {#tags-lists}\n\nPolySwarm researchers tag known malware samples with malware family names and attributes.\n\nBelow are some examples of using malware Families and Tags to identify Emotet - another malware family that PolySwarm has been tracking.\n\n>Emotet is a \"downloader\".\n>By itself, it usually just offers the attackers the ability to install additional malware on target machines.\n>TrickBot (an info stealer) and Ryuk (ransomware) are commonly installed via initial Emotet infection.\n\n#### Using Tags {#using-tags}\n\n**Format:** ```polyswarm tag list```\n\n**Description:** PolySwarm tags are free-form attributes applied to known malware samples.\n>`tags` can describe attributes like malware family (e.g. `EventBot`), target operating system (e.g. `Android`), phishing campaign (e.g. `COVID-19`) and exploited vulnerabilities (e.g. `CVE-2017-11882`).\n\n**Request**\n```bash\n$ polyswarm tag list\n```\n\n**Response**\n```bash\nTag: Adware\nTag: AgentTesla\nTag: Android\nTag: Cerberus\nTag: COVID-19\nTag: CVE-2017-11882\nTag: Emotet\nTag: EventBot\n```\n\n#### Using Families\n\n**Format:** ```polyswarm family list```\n\n**Description:** PolySwarm `families` are malware family names applied to known samples from a given family.\n>Families with an Emerging timestamp where listed on the PolySwarm homepage at the given time - these are particularly cutting edge or prominent in the news.\n\n**Request**\n```bash\n$ polyswarm family list\n```\n\n**Response**\n```bash\nFamily: Emotet\nEmerging: 2020-06-06 08:23:35.997775\n\nFamily: EventBot\nEmerging: 2020-06-10 17:15:54.789337\n\nFamily: NetWalker\nEmerging: None\n```\n\n#### Using Links\n\n**Format:** ```polyswarm link list --family Examples
\nThese examples show how an Engine works end to end, from receiving a bounty to returning an analysis. Use them as references, then replace the analyzer logic with your own detection tooling.
\nRecommended learning path
\nIf you are new to building a PolySwarm Engine, follow this order. Each page builds on the previous one:
\n- \n
- Quickstart: run the reference EICAR Engine locally and confirm you can return valid results \n
- Build your Engine: replace the template analyzer with your own detection logic \n
- Testing your Engine: run unit and local integration tests before marketplace testing \n
- Run your Engine as an engine webhook service: run the web server and worker so PolySwarm can deliver bounties \n
- End-to-end testing in the Development Community: validate real bounty flow in a safe environment \n
Once you complete the path above, use the examples below as patterns you can copy and adapt.
\nExample 1 - EICAR Engine (template)
\nBest for learning the basics and validating protocols.
\nThe microengine-webhooks-py repository is the recommended starting point. It is a working Engine that detects EICAR and includes a web server, worker, and tests.
What it demonstrates:
\n- \n
- registering an analyzer (
@engine.register_analyzer) \n - fetching an artifact safely \n
- returning an Analysis (verdict, bid, metadata) \n
- handling unsupported artifact types safely (UNKNOWN) \n
Typical analyzer shape:
\n@engine.register_analyzer\ndef analyze(bounty: ps.Bounty) -> ps.Analysis:\n if not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTED\n\n content = ps.get_artifact_bytes(bounty)\n\n if EICAR_STRING in content:\n return {\n \"verdict\": ps.MALICIOUS,\n \"bid\": ps.bid_max(bounty),\n \"metadata\": {\"malware_family\": \"EICAR\", \"confidence\": 1.0},\n }\n\n return {\"verdict\": ps.BENIGN, \"bid\": ps.bid_max(bounty), \"metadata\": {}}Quick local checks:
\n- \n
- empty bounties \n
- EICAR for file engines \n
- WICAR for URL engines \n
- unsupported types return UNKNOWN \n
Example 2 - External Scanner Integration Pattern (ClamAV style)
\nBest for integrating an existing scanner that expects file paths or runs as a service.
\nThis pattern:
\n- \n
- downloads the artifact to a temp file \n
- runs a scanner tool \n
- maps tool output into verdict and metadata \n
Key ideas:
\n- \n
- enforce timeouts, treat timeouts as UNKNOWN \n
- keep malware family output stable and meaningful \n
- run scanning in a worker, not in the engine webhook request thread \n
Example pattern:
\n@engine.register_analyzer\ndef analyze(bounty: ps.Bounty) -> ps.Analysis:\n if not ps.is_file_artifact(bounty):\n return ps.UNSUPPORTED\n\n with ps.ArtifactTempfile(bounty) as path:\n result = scan_with_tool(path)\n\n if result.malicious:\n return {\n \"verdict\": ps.MALICIOUS,\n \"bid\": ps.bid_max(bounty),\n \"metadata\": {\"malware_family\": result.family},\n }\n\n return {\"verdict\": ps.BENIGN, \"bid\": ps.bid_max(bounty)}Which example to start with
\nUse the EICAR template if you want:
\n- \n
- the fastest path to a working Engine \n
- a stable reference for protocols and expected behaviour \n
- a clear place to replace scanning logic (
analyze) \n
Use the external scanner pattern if you want:
\n- \n
- a model for integrating external tools safely \n
- a clean file-based workflow for CLI scanners \n
- a repeatable mapping from tool output to a stable verdict \n
Onboarding
\nWhen approved, PolySwarm will require a Know Your Customer (KYC) check so we understand who owns and operates the Engine.
\nYou will be asked to submit:
\n- \n
- Personal identification information \n
- A government-issued ID (passport preferred) \n
You will also receive an Engine Provider Agreement for signature. We must have a signed agreement in place before we can proceed to provisioning.
\nOnboarding checklist
\n- \n
- KYC completed \n
- Engine Provider Agreement signed \n
- Deployment model confirmed (PolySwarm-hosted or Partner-hosted) \n
- Technical details provided (see below) \n
Technical information
\nPolySwarm-hosted Engines
\nIf you have chosen to deploy your Engine through PolySwarm, and allow us to host it we will need additional technical information:
\n- \n
- Is the Engine containerized, what is the image size, and how can we access the image? \n
- What is the update mechanism, and how often does it update? \n
- Does it require internet access? \n
- What resources are required (memory, CPU, disk)? \n
- If it is Windows-based, can it run under Wine? \n
Partner-hosted Engines
\nIf you choose to host the Engine yourself, then the process is:
\n- \n
- PolySwarm creates the Engine in a development state until verification is complete \n
- You create engine webhooks in your team account, connect an engine webhook to the Engine to begin testing. \n
- Test in the Development Community: Send test bounties to confirm the Engine processes artifacts and responds correctly \n
- Request verification: When ready, request verification from the My Engines tab in your Team. \n
Verification Failure Reasons
\nDuring verification testing, common issues include:
\n- \n
- Slow or inconsistent responses \n
- Incorrect verdict formatting or missing required fields \n
- Accuracy problems across benign and malicious samples \n
- Unexpected errors during bounty processing \n
- If verification fails, fix the issues, re-test in the Development Community, then request verification again. \n