PolySwarmPolySwarmPolySwarmPolySwarm
Help

Developing a Production Microengine

マイクロエンジンの開発者としては、マイクロエンジンのパフォーマンスを監視し、NCT 投資戦略を磨いて、PolySwarm マーケットプレイスにおけるアーティファクトに関する自信度を反映させることが重要です。 マイクロエンジンでアサーションを提示するアーティファクトをフィルターに掛け、投資金額とマイクロエンジンのアサーションの自信度の間に強い相関が保たれるようにすることは、効果的で利益を生み出すマイクロエンジンを維持するために必要不可欠です。

All microengine developers should routinely:

  1. マイクロエンジンのマーケットプレイスでのパフォーマンスを監視する。
  2. 対象とするアーティファクトを迅速に特定する初回「トリアージ」フィルターを作成する。
  3. マイクロエンジンのアサーションの自信度と投資金額 (NCT) の間に密接な相関が保たれるようにする。
  4. Ensure their microengine is capable of scaling in response to demand.

Monitoring Your Microengine's Marketplace Performance

Any PolySwarm user can track any microengine's profit / loss from PolySwarm Web's Microengines page. マイクロエンジンの開発者は、以下を行うことができます。

  1. Create an account on PolySwarm Web
  2. Track your microengines' performance in comparison to other microengines' performance and
  3. Claim ownership in your microengine(s) so you can more easily track your microengines' performance

マイクロエンジンの所有権の要求

When you claim (and prove) ownership of your Microengines, you're able to:

  1. (Optionally) name your microengine
  2. (Coming Soon) assign ownership to a Team
  3. View your microengines' performance in a single view without searching for each microengine in the unfiltered Microengines listing

We encourage every microengine developer to claim all of their Microengines.

We're continually rolling out new features that extend the management capabilities of owned Microengines.

Taking ownership of your microengine is a necessary first step for admission to PolySwarm's various Private Communities, unlocking private and often higher-value bounties.

パフォーマンスの追跡

With your Microengines claimed, quickly view profit / loss information across your microengine footprint using My Microengines. When deploying new detections to your microengines, use My Microengines to get a sense for their economic impact. そこにあるグラフを頻繁に確認することで、マイクロエンジンで発生した問題 (利益の急激な落ち込みなど) を速やかに特定できます。

改善のサイクル

パフォーマンスの低いマイクロエンジンを把握することで、マイクロエンジンの開発者は、損失を食い止めるために、パフォーマンスの低いマイクロエンジンをオフラインにすることができます。 ただし、追加のコンテキストがなければ、そのマイクロエンジンをオンラインに戻す前にどのように改善すればよいのかを判断するのが困難になる可能性があります。 そのため、すべてのマイクロエンジンで、評価したアーティファクトを、そのアーティファクトに対するアサーションと投資金額 (NCT) とともにアーカイブすることを強くお勧めします

マイクロエンジンの開発者がマイクロエンジンを改善する上でさらに迅速に対応できるように、これをプロアクティブなプロセスにする帳簿機能を設計中です。 As they become available, these features will be accessible on the My Microengines page.


Triaging Artifacts

マイクロエンジンの開発者には、以下の 2 つのステージから成るプロセスでマイクロエンジンを設計することをお勧めします。

  1. アーティファクトを詳細に調べる価値があるかどうかを判別する、非常に高速な軽量トリアージ・プロセス
  2. アサーション期間内に悪意性を判別して報奨金に応答する、アーティファクトの詳細な調査プロセス

マイクロエンジンの開発者は、初回トリアージを実装すれば、実行の負担を低減し、対象外のアーティファクトを速やかに無視することで、時間と費用を節約できます。 マイクロエンジンのプロバイダーと会話した結果、人気のあるトリアージ戦略は、ファイル・タイプに基づいたアーティファクトの絞り込みです。

Below is a simple example of a triage pass in a Microengine's scan() function:

import magic
...
class Scanner(AbstractScanner):

  ...

  async def scan(self, guid, artifact_type, content, chain):

    # Reject artifacts that aren't files
    if not artifact_type == ArtifactType.FILE:
      return ScanResult()

    # Reject files that libmagic does not identify as an ELF or PE by returning an empty ScanResult object
    if not ((magic.from_buffer(content)[0:3] == "ELF") or (magic.from_buffer(content)[0:2] == "PE")):
      return ScanResult()
...

Developing an Effective Staking Strategy

Example Lifecycle

Let's run through a simplified example of a bounty lifecycle, noting the impact of staking strategy design.

報奨金の作成

Suppose the fictitious ACME Enterprises discovers something suspicious on their network and wants to enrich their telemetry with intelligence produced by the PolySwarm marketplace. ACME submits an artifact to the PolySwarm marketplace via PolySwarm Web, PolySwarm API or a third party Ambassador.

An Ambassador creates a bounty for ACME's submission. This bounty contains: (1) the artifact, and (2) a configurable amount of NCT into the initial reward bucket for the bounty. 説明のために、報酬バケットに 5 NCT を入れたとします。

この新しい報奨金とアーティファクトに対して用意された金額 (NCT) が、アクティブな PolySwarm マイクロエンジンに通知されます。

Let's assume 8 microengines* find the initial NCT reward placed by the Ambassador to be sufficient for triaging of the artifact to determine whether the artifact falls within the the microengine's area of expertise.

*The number of active PolySwarm microengines is far beyond 8 and is growing by the day, but we'll keep this example simple for illustrative purposes.

マイクロエンジンによる初回トリアージの実行

マイクロエンジンは、初回トリアージを実行して、以下のように判別しました。

  • マイクロエンジン A、B、C、D、E: アーティファクトは自分の専門知識の対象である
  • マイクロエンジン F、G、H: アーティファクトは自分の専門知識の対象外である

マイクロエンジン F、G、H は報奨金を無視し、応答しないことを選択しました。一方、マイクロエンジン A から E はさらに詳細に調べることにしました。

マイクロエンジンによる詳細な分析の実行

各マイクロエンジンは分析中に鍵となる特性 (高信頼度の指標) や汎用パターン (低信頼度の指標) を特定し、結論に到達しました。 各マイクロエンジンは、投資金額 (NCT) で自信度を示します。以下のようになりました。

  • マイクロエンジン A: 1 NCT / 悪意がある
  • マイクロエンジン B: 1 NCT / 無害
  • マイクロエンジン C: 2 NCT / 悪意がある
  • マイクロエンジン D: 1 NCT / 悪意がある
  • マイクロエンジン E: 2 NCT / 無害

大まかに言うと、マイクロエンジン C と E は、同じ意見の他のマイクロエンジンよりもアサーションに対して 2 倍自信があるということになります。

These assertions and their NCT stakes are sent to the Ambassador immediately after the assertion window closes. アンバサダーはアサーションを分析し、必要に応じてアサーションを組み合わせて、最終的な単一のインテリジェンスを生成して ACME に送信します。

Total NCT is Computed by PolySwarm's BountyRegistry Contract

初期報酬と投資された金額が、PolySwarm の BountyRegistry コントラクトに預託されます。 以下のようにすべての資金が合計されます。

  • 初期報酬: 5 NCT +
  • マイクロエンジン A: 1 NCT +
  • マイクロエンジン B: 1 NCT +
  • マイクロエンジン C: 2 NCT +
  • マイクロエンジン D: 1 NCT +
  • マイクロエンジン E: 2 NCT =
  • 報酬合計: 12 NCT

評価者による確認・評価

後から、評価者が、対象アーティファクトに関する確認・評価を行います。 評価者は、アーティファクトが実際に悪意のあるものであったと判断しました。

次に、アサーションが正しかったマイクロエンジンが報酬を要求するために報奨金がオープンになります。 マイクロエンジンは、以下のように、投資金額に比例して報酬を受け取ります。

  • マイクロエンジン A: 3 NCT (2 NCT の利益)
  • マイクロエンジン B: 0 NCT (アサーションが正しくなかった)
  • マイクロエンジン C: 6 NCT (4 NCT の利益)
  • マイクロエンジン D: 3 NCT (2 NCT の利益)
  • マイクロエンジン E: 0 NCT (アサーションが正しくなかった)

報酬が最も多かったのは、マイクロエンジン C です。 C は、A や D の 2 倍の金額を投資することで、報酬の分け前も 2 倍になっています。

ここで示した例は、PolySwarm マーケットで実際に行われる内容を単純化したものです。

実際のマーケットプレイスでは、はるかに多くのマイクロエンジンが応答します。また、投資金額は整数である必要はありません。さらに、マーケットプレイスによって評価者への報酬の費用も決定されます。

自信度と NCT 投資金額間の密接な相関の維持

マイクロエンジンが NCT 投資金額でアサーションの自信度を示すと、すべての関係者が恩恵を受けることになります。 アンバサダーにとっては、マイクロエンジンの NCT 投資金額から、アーティファクトの悪意性に関する 1 つの指標が得られます。 マーケットのマイクロエンジン側では、自信度に基づいて NCT 投資金額を調整して、利益を増大させることができます。

The best microengines will have a good sense of their confidence in each scan and will deliver a "confidence interval" between 0.0 and 1.0 while returning scan results via the ScanResult object. These confidences are used in AbstractMicroengine's bid() method according to a BidStrategy.

polyswarm-client provides a default bid strategy via the class BidStrategyBase. Variants of this default strategy (with different weights applied) can be found in polyswarm-client.

You may use the default bid strategy, some variant thereof, or develop a fully custom bid strategy by subclassing BidStrategyBase. participant-template will produce a BidStrategy class for Microengine participants. Refer to the comments surrounding this subclass for more information.

During testing, it may be convenient to quickly swap bid strategies. You can choose which strategy to use when you launch your microengine by providing the --bid-strategy command line option or setting the BID_STRATEGY variable in your environment.

Let's take a look at the default bid strategy in BidStrategyBase's bid() method:

async def bid(self, guid, mask, verdicts, confidences, metadatas, chain):
  """カスタム投入額計算ロジックを実装するには、これをオーバーライド
  引数:
      guid (str): 分析対象の報奨金の GUID。これを使用して、同じ報奨金に含まれているアーティファクトと相関付ける
      masks (list[bool]): 報奨金ファイルをスキャンした結果のマスク
      verdicts (list[bool]): 報奨金ファイルをスキャンした結果のスキャン判定
      confidences (list[float]): アーティファクトごとの判定の自信度を示す尺度 (0.0 から 1.0)
      metadatas (list[str]): 報奨金ファイルをスキャンした結果のメタデータ文言
      chain (str): 動作するチェーン
  戻り:
      int: 基本 NCT 単位 (10 ^ -18) での NCT 投入金額
  """
  min_allowed_bid = await self.client.bounties.parameters[chain].get('assertion_bid_minimum')
  min_bid = max(self.min_bid, min_allowed_bid)
  max_bid = max(self.max_bid, min_allowed_bid)

  asserted_confidences = [c for b, c in zip(mask, confidences) if b]
  avg_confidence = sum(asserted_confidences) / len(asserted_confidences)
  bid = int(min_bid + ((max_bid - min_bid) * avg_confidence))

  # 投入額を min_bid から max_bid までに設定
  return max(min_bid, min(bid, max_bid))

Currently, only one NCT stake may be placed per bounty. This presents a problem for multi-artifact bounties: How can a single NCT stake accurately convey potentially variable confidence across multiple bounties?

We're working to remove this limitation. Future releases will support N stakes for N artifacts in a single bounty.

Currently, staking strategies take an average confidence over all artifacts in a given bounty to arrive at a single NCT stake amount for that bounty.

自信度の決定

The specifics of determining confidence cannot easily be generalized; each microengine will have an optimal strategy. Generally, we've found that microengine developers are choosing one of several strategies (in order of increasing efficacy):

  1. 自信度なし: マイクロエンジンにおいて、すべての応答の自信度が同じになります。 これは最低水準の戦略であり、多くの場合、すべてのアーティファクトに固定の NCT 金額を投資します。 Discord でマイクロエンジンの開発者と連携して、優れた投資戦略を開発しています。また、お困りのことがありましたら、喜んでお手伝いいたします。
  2. タイプに基づいた自信度: ファイル・タイプ情報を 2 回使用するマイクロエンジンもあります。その場合は、トリアージ・プロセス時にアーティファクトを除外するために 1 回使用し、トリアージ・プロセスを通過したファイルに重みを付与するためにもう 1 回使用します。 これは非常にシンプルにすることができ、Scanner クラスから渡された confidence スコアを調整する静的な重みをサポート対象ファイル・タイプごとに割り当てるだけです。 このタイプの戦略は、自信度なしよりは優れていますが、まだ最適な戦略とは言えません。
  3. 特定の指標に基づいた自信度: パフォーマンスが高いマイクロエンジンを作成するには、常にこれを目標にする必要があります。 現在、これを実現しているマイクロエンジンが PolySwarm マーケットプレイスに複数存在しています。例えば、Microsoft Word 文書を詳細に分析して、悪意があると知られている自動実行マクロ・スクリプトを検出しているものがあります。 このようなアーティファクトの調査は最適な処理であり、非常に高いレベルの自信度指標が得られます。これにより、マイクロエンジンの開発者は、最適な投資戦略を作成できるようになります。
import magic
...
class Scanner(AbstractScanner):

  ...

  async def scan(self, guid, artifact_type, content, chain):

    confidence_delta = 0

    # Increase confidence score for ELF and PE files
    if not ((magic.from_buffer(content)[0:3] == "ELF") or (magic.from_buffer(content)[0:2] == "PE")):
      confidence_delta += 0.2

    ...

    # 詳細な分析を実行して、ベース自信度スコアを計算
    confidence_base = do_analysis()

    ...

    # 結果を返す際に、ファイル・ベースの自信度を考慮
    return ScanResult(bit=True, verdict=True, confidence=confidence_base+confidence_delta)
...

Operating at Scale

As more enterprises rely on PolySwarm for scanning suspect artifacts, microengines need to scale in order to meet demand.

Microengines built using participant-template use a producer / consumer model* for horizontal scaling:

  1. 1 frontend (producer): responsible for communicating with the PolySwarm marketplace: ingesting bounties, triaging artifacts, producing pub/sub scan events for backends, implementing a staking strategy and posting assertions. The frontend translates marketplace bounties into events on a pub/sub queue for backends to consume and distills responses from backends into marketplace actions.
  2. N backends (consumers): the actual scanners that process artifacts and produce assertions (malicious / benign) coupled with confidence ratings. These backends are tasked by the frontend.

Microengines created with participant-template prior to June 18th 2019 will need to be upgraded to the producer / consumer model.

The producer / consumer model makes it simple to horizontally scale your microengine. As demand increases, launch additional consumer instances. As demand decreases, it's safe to retire some consumer instances. In other words, microengine's resource footprint should scale elastically in response to demand.

Relative to a traditional monolithic model, producer / consumer provides additional benefits:

  1. The producer houses bid / staking logic, disjoint from consumer-held scanning logic. This separation provides a more maintainable and secure architecture: consumers, responsible for complex scanning functions, need not (and should not) have access to the microengine's wallet. All wallet-related functions can be handled by the comparatively simple producer component.
  2. The pub/sub interface permits parallel scans by design without complex (or even explicit) client synchronization.
  3. Makes it easier to build disjoint, multi-backend microengines. It becomes possible to mix and match lighter weight (e.g. static analysis) and heavier weight (e.g. sandbox) backends, with the single producer frontend mediating scan results, allowing the microengine to respond as best it can within the assertion timeframe.
  4. Reduces computational cost via elastic resource consumption.

Next Steps

With a staking strategy in place, it's time to connect your microengine to the PolySwarm marketplace!

Connect to the PolySwarm marketplace →