DOCSEARCHbyAlgolia
Submit Docs

PolySwarm Documentation

website·Indexed 35 days ago

https://docs.polyswarm.io

Documentation for PolySwarm, a threat intelligence marketplace. Includes guides for customers on scanning artifacts, using the PolySwarm Python SDK, Customer CLI v3, and STIX/TAXII protocols, as well as comprehensive resources for Engine developers on building, testing, hosting, and verifying engines to provide verdicts.

Tokens
46K
Snippets
141
Records
337
Agent score
62%

What's inside PolySwarm

  1. Overview of the polyswarm_engine package

    polyswarm_engine is a helper library designed to simplify the development of PolySwarm Engines. It provides standardized ways to receive bounty payloads, fetch artifacts (as bytes, streams, or temporary files), return formatted analysis results (verdicts, bids, and metadata), and calculate bids using NCT-wei helpers.

  2. Understand the PolySwarm Marketplace Roles

    PolySwarm operates as a threat intelligence marketplace where suspicious artifacts are analyzed to provide verdicts. The ecosystem consists of three primary roles:

    1. PolySwarm (Ambassador): Acts as the broker for customers. It submits bounties, collects assertions from Engines, and returns the final verdict to the customer.
    2. Engine: Analyzes artifacts and submits an assertion of 'malicious' or 'benign'. Engines can bid Nectar (NCT) to express confidence in their analysis and are rewarded when their assertions align with the eventual ground truth.
    3. Arbiter: Responsible for publishing the 'ground truth' after further evidence is gathered. This ground truth is used to determine the rewards and penalties for the participating Engines. The Arbiter uses the same core model as an Engine but operates later in the bounty lifecycle.

  3. Interpret the PolySwarm Results page

    The Results page is a centralized view of all intelligence gathered for a specific artifact, including engine verdicts, sandbox detonations, LLM reports, and static analysis.

    Key navigation elements include:

    • Search Bar: Located at the top; allows searching for other hashes, URLs, or metadata queries without leaving the page.
    • Tabs: Dynamic navigation links that jump to specific sections. Tabs only appear if data is available for that specific artifact type.

  4. Perform Historical Hunting with YARA Rules

    Historical Hunting allows you to use YARA Rules to examine artifacts submitted in the past. Currently, Historical Hunts evaluate all artifacts submitted within the last 6 months. You can manage these hunts and view their matches via the Historical Hunts tab.

  5. Understand PolySwarm subscription plan types

    PolySwarm offers three primary plan categories:

    • Community Plan: The default free plan for all User and Team accounts. Requires the user to be logged in to the PolySwarm UI. It provides higher limits than anonymous usage but lower limits than paid plans.
    • Individual Plans: Paid plans available specifically for User Accounts.
    • Enterprise Plans: Paid plans available for both User and Team Accounts.

  6. Understand the PolySwarm Engine partner role

    PolySwarm Engines allow developers to integrate detection capabilities into a threat intelligence marketplace. Engine partners analyze suspicious artifacts—such as files, URLs, IPs, and domains—and return assertions (verdicts). Partners are incentivized with rewards when their analysis aligns with confirmed ground truth.

  7. Understand the PolySwarm Engine production verification process

    Production verification is a quality gate required for an Engine to operate in public production communities. It ensures that Engines provide reliable results and behave predictably under real traffic. Verification covers four primary areas:

    1. Identity and Agreement: Completion of KYC and the Engine Provider Agreement (where required).
    2. Configuration Review: Validation of UI configuration fields, artifact types, engine webhook selection, and metadata/capability fields.
    3. Technical Verification: Testing with benign and malicious artifacts to ensure the Engine accepts webhook requests, validates signatures, returns 202 Accepted quickly, processes bounties asynchronously, and posts correctly formatted assertions.
    4. Operational Readiness: Ensuring the HTTPS endpoint is stable, handles expected traffic (rate limits/concurrency), and manages timeouts without cascading failures.

  8. Implement a Command Line Scanner architecture

    When using a CLI-based tool, the analyze() function should:

    1. Retrieve the artifact, typically using a temporary file.
    2. Execute the CLI tool with a strict timeout.
    3. Capture exit codes and stderr.
    4. Parse the output into a stable verdict and metadata dictionary.

  9. Implement a Local Service architecture

    When using a local daemon (e.g., ClamAV):

    1. Download the artifact as bytes or a temporary file.
    2. Connect to the local service via socket or HTTP.
    3. Send the artifact or its file path.
    4. Parse the results into an analysis dictionary.

    Note: Ensure the local service is running before the Engine starts handling bounties.

  10. Manage NCT wallet balance for PolySwarm Engines

    NCT management ensures an Engine remains funded to bid consistently and avoids unexpected downtime. The wallet balance is affected by four primary factors:

    1. Bids: Amounts are deducted from the Engine wallet when a bid is placed. If the wallet cannot cover the bid, participation may be reduced or treated as a bid of 0.
    2. Rewards and Penalties: Rewards are paid after arbitration, which typically involves a delay of several weeks. The wallet must be sufficiently funded to cover bids during this gap.
    3. Deposits: NCT is added to the Engine wallet using the deposit address provided in the PolySwarm UI.
    4. Withdrawals: These reduce the wallet balance immediately upon initiation.

  11. Implement a PolySwarm Engine Webhook Service architecture

    To process bounties asynchronously and send assertions back to PolySwarm, implement a three-part architecture:

    1. Engine Webhook HTTP Server: Receives bounty events via HTTP POST, verifies request signatures, returns a 202 Accepted response immediately, and enqueues the work.
    2. Queue and Broker: A message broker (e.g., RabbitMQ) that connects the HTTP server to the worker.
    3. Worker: Pulls jobs from the queue, executes the analyzer logic, and posts the resulting assertion back to the marketplace via the provided response endpoint.

  12. Interpret Live Hunting match results

    The Live Hunting matches table provides detailed information about artifacts that triggered YARA rules. Key columns include:

    • Rule Name: The specific rule that triggered the match.
    • SHA256: The hash of the matching artifact (includes a copy-to-clipboard icon).
    • Malware Family Name: The associated malware family; may be blank if the artifact is benign.
    • PolyScore: The PolyScore assigned to the match.
    • Detections: The ratio of malicious assertions to total assertions.
    • Matched On: The timestamp or relative time of the match.

    Available Actions per match:

    • Open in New Tab: Navigates to the Results Page for the artifact's metadata.
    • Download: Downloads the artifact in a password-protected, encrypted .zip file.
    • View Ruleset: Displays the Ruleset used by the associated Live Hunt.
    • Info: Shows Live Hunt information.
    • Delete: Removes the match.

    Bulk Actions: Using the checkboxes, you can select multiple matches to either Save (download as a .CSV file) or Delete.