ユーザーリスクエクスチェンジカスタムプラグイン開発者ガイド

このガイドでは、新しいユーザーリスク交換プラグインを作成する方法と、ユーザーリスク交換モジュール内で提供される機能を活用してリスクエコシステムから最大限の価値を引き出す方法について説明します。このガイドに従えば、開発者は技術的な問題なく、独自に新しいプラグインを作成できるようになるはずです。

前提条件

• Python 3.xのプログラミング経験（中級レベル）。
• Netskope Cloud Exchangeプラットフォームへのアクセス。
• プラグインを作成する必要のある製品またはソリューションへのAPIまたはPython SDKへのアクセス。
• 製品に対する最低限の権限を持つアカウント。

ユーザーリスク交換モジュール

Cloud Exchangeプラットフォームとその User Risk Exchange モジュールには、高度なカスタマイズを可能にする豊富な機能セットが付属しているため、以下に示すプラットフォームのさまざまな側面についてよく理解しておくことをお勧めします。 このモジュールは、Netskopeからサードパーティ製ツールへのデータ共有、およびその逆方向のデータ共有をサポートします。

Netskopeの概念と用語

• コア：Cloud Exchangeのコアエンジンは、サードパーティ製プラグインとそのライフサイクルメソッドを管理します。プラットフォームと対話してさまざまなタスクを実行するための API エンドポイントがあります。
• モジュール：さまざまなワークフローを実行するために、モジュール固有のプラグインを呼び出す機能的なコード領域。ユーザーリスク交換は、 Cloud Exchangeで動作するモジュールの1つです。
• プラグイン：プラグインは、サードパーティの脅威インテリジェンスシステムからユーザーとリスクスコアを取得するロジックを備えたPythonパッケージであり、取得したデータはUser Risk Exchangeに保存されます。また、動作を実行することもできます。
• プラグイン構成：プラグイン構成とは、必要なパラメータで構成され、ユーザーとスコアを取得するためにCloud Exchangeコアエンジンによってスケジュールされるプラグインクラスオブジェクトのことです。
• ユーザー (UBA アラート): (ユーザーの) レコードは、電子メールとそのリスク スコアがさまざまなプラットフォームから収集され、 Cloud Exchangeデータベースに保存されているオブジェクトです。

開発ガイドライン

• すべての Python コードのプラグイン ディレクトリ構造を使用します。
• プラグインパッケージに同梱されているすべてのサードパーティライブラリについて、既知の脆弱性がないか確認してください。
• 標準的なPythonのコーディング規約を必ず守ってください。(https://peps.python.org/pep-0008/)
• flake8 Lint チェックを実行し、docstring チェックを有効にした状態で合格することを確認してください。1 行の最大長は 80 文字である必要があります。
• タイムスタンプ値を人間が読みやすい形式に変換します（エポックからDateTimeオブジェクトへ）。UIに表示される時刻が、現地のタイムゾーンであることを確認してください。
• 可能であれば、プラグインで設定パラメータを追加する際に、デフォルト値を追加してください。
• Pythonで記述されたスクリプトや統合機能については、必ず単体テストを作成してください。単体テストを参照してください。
• プラグインアーキテクチャでは状態の保存は可能ですが、状態管理のために巨大なオブジェクトを保存することは避けてください。
• Pythonコードに脆弱性がないか確認してください。
• プラグインのアイコンは10KB未満でなければなりません。必ず会社のロゴ（製品のロゴではなく）を透明なバックグランドで使用してください。 ロゴの推奨サイズは300×50ピクセル、またはそれに近いアスペクト比です。
• 独自のチェックポイントを実装するのではなく、 Cloud Exchangeコアが提供するチェックポイントを使用します。
• ロガーメッセージとトーストメッセージには、APIトークンとパスワードタイプのフィールド値を含めてはいけません。
• プラグインの機能開発においては、ページネーションを常に考慮に入れるべきです。
• ステータスコード429に対する再試行メカニズムを必ず追加してください。
• 障害や重大な状況（レート制限、ペイロードサイズの超過など）が発生した場合に通知を発生させ、プラグインの状態をユーザーに通知するための通知オブジェクト。
• Cloud Exchangeプラットフォームによって渡されるロガー オブジェクトを使用して、適切なログ メカニズムを実装してください。 運用チームがトラブルシューティングを行う際に役立つよう、十分なログ記録が行われるようにしてください。通知に機密データが記録されたり、漏洩したりしないようにしてください。
• すべてのパラメータに対して適切なヘルプテキスト（ツールチップ）を提供してください。可能であれば、ツールチップでそのパラメータの重要性を説明するようにしてください。
• プラグイン設定パラメータには必ず意味のある名前とデスクリプションを指定してください。
• パラメータには、適切な設定タイプ（テキスト、数値、パスワード、選択式、複数選択式）を指定してください。
• アウトバウンドリクエスト (API/SDK) を行う際に、 Cloud Exchangeプラットフォームによって渡されるプロキシ構成辞書と SSL 証明書検証フラグを必ず使用してください。
• 必須ではないパラメーターの値を取得するようにしてください .get() メソッドを作成し、 .get() を使用するときにデフォルト値を提供します 方法。
• API トークンとパスワード フィールドでは、strip() を使用しないでください。
• The log messages should start with “<module> <app name> Plugin [configuration_name]: “. Example: “URE Crowdstrike Plugin [CrowdStrike Configuration Name]: <log_message>“. [This is a suggestion, we can avoid configuration name]. (logger.info(“<module> <plugin_name> Plugin: <message>”))
• エラーログを記録する際には、可能であれば例外のトレースバックも追加すべきです。使う: self.logger.error(error, details=traceback.format_exc())
• The Toast message should not contain the <app_name> <module> Plugin: in the message.
• API呼び出し中および呼び出し後に、適切な例外とステータスコードを捕捉するようにしてください。可能であれば、開発者はリクエストを行うためのヘルパーメソッドを作成し、必要に応じて適切なパラメータを指定してこのメソッドを呼び出すことができます。
• CHANGELOG.md ファイルには、追加、変更、修正などの適切なタグと、ユーザーにとって分かりやすいメッセージを追加して更新する必要があります。ファイル名がCHANGELOG.mdと完全に一致していることを確認してください。
• プラグインディレクトリ構造のガイドラインに従ってください。
• デスクトップリプションにリンクが含まれている場合は、プレーンテキストではなくハイパーリンクにする必要があります。
• システムのメリットを最大限に活用するために、API呼び出しで取得した様々なフィールドをユーザーおよびスコアのデータモデルに正しくマッピングしてください。レコード内のスコアのようなフィールドは、SOCユーザーがデータを分析する際に、より理解しやすいものとなる。SOCアナリストにとってより詳細な情報が得られるよう、スコアフィールドを必ずマッピングしてください。スコア欄は整数である必要があります。
• validateメソッドに渡されるパラメータを適切に検証し、すべてのパラメータに対して適切なヘルプテキストを提供します。
• 障害や重大な状況（レート制限、ペイロードサイズ超過など）が発生した場合に通知を発生させ、プラグインの状態をユーザーに通知するための通知オブジェクト。
• Cloud Exchangeプラットフォームによって渡されるロガー オブジェクトを使用して、適切なログ メカニズムを実装してください。 運用チームがトラブルシューティングを行う際に役立つよう、十分なログ記録が行われるようにしてください。通知に機密データが記録されたり、漏洩したりしないようにしてください。
• プラグインディレクトリ名（sample_plugin）がmanifest.jsonと一致していることを確認してください。IDフィールド。
• User Agent should be added to the headers while making any API call. Format for the User Agent: netskope-ce-<ce_version>-<module>–<plugin_name>–<plugin_version>.
• ロガーステートメントは次の形式に従う必要があります。
  • logger.info(“<module> <plugin_name> Plugin: <message>”)

プラグインの作成

このセクションでは、プラグインをゼロから作成するプロセスについて説明します。

サンプルプラグインは NetskopeOSSの公開Githubリポジトリ またはCloud Exchangeナレッジベース(こちら)からダウンロードできます: https://support.netskope.com/hc/en-us/articles/360052128734-Cloud-Threat-Exchange。

開発環境のセットアップ

Python

当システムはPython3（バージョン3.7以降）を使用しています。開発環境にPython3がインストールされていることを確認してください。Pytest は単体テストを実行するために使います。

含まれるPythonライブラリ

Netskope Cloud Exchangeプラットフォームには、次の Python ライブラリが含まれています。

図書館名	バージョン
aiofiles	22.1.0
amqp	5.1.1
anyio	3.6.2
asgiref	3.6.0
attrs	22.2.0
azure-core	1.26.2
azure-storage-blob	12.14.1
bcrypt	4.0.1
boto3	1.26.51
botocore	1.29.51
billiard	3.6.4.0
celery	5.2.7
cabby	0.1.23
cachetools	5.2.1
celerybeat-mongo	0.2.0
certifi	2022.12.7
cffi	1.15.1
chardet	5.1.0
charset-normalizer	3.0.1
click	8.1.3
click-didyoumean	0.3.0
click-plugins	1.1.1
click-repl	0.2.0
colorama	0.4.6
colorlog	6.7.0
cryptography	39.0.0
cybox	2.1.0.21
defusedxml	0.7.1
dnspython	2.3.0
docker	6.0.1
fastapi	0.89.1
furl	2.1.3
google-api-core	2.11.0
google-auth	2.16.0
google-cloud-core	2.3.2
google-cloud-pubsub	2.13.12
google-cloud-pubsublite	1.6.0
google-cloud-storage	2.7.0
google-crc32c	1.5.0
google-resumable-media	2.4.0
googleapis-common-protos	1.58.0
grpc-google-iam-v1	0.12.6
grpcio	1.51.1
grpcio-status	1.51.1
gunicorn	20.1.0
h11	0.14.0
idna	3.4
importlib-metadata	6.0.0
isodate	0.6.1
jmespath	1.0.1
jsonpath	0.82
jsonschema	4.17.3
kombu	5.2.4
libcst	0.3.21
libtaxii	1.1.119
lxml	4.9.2
mongoengine	0.25.0
more-itertools	9.0.0
MarkupSafe	2.1.2
memory-profiler	0.61.0
mixbox	1.0.5
mongoquery	1.4.2
msrest	0.7.1
multidict	6.0.4
mypy-extensions	0.4.3
netskopesdk	0.0.25
numpy	1.23.5
oauthlib	3.2.2
onelogin	3.1.0
ordered-set	4.1.0
orderedmultidict	1.0.1
overrides	6.5.0
pandas	1.5.0
packaging	23.0
passlib	1.7.4
pycparser	2.21
prompt-toolkit	3.0.36
proto-plus	1.22.2
protobuf	4.21.12
psutil	5.9.4
pydantic	1.10.4
pyasn1	0.4.8
pyasn1-modules	0.2.8
PyJWT	2.6.0
pymongo	4.3.3
pyparsing	3.0.9
python-dateutil	2.8.2
pyrsistent	0.19.3
python-multipart	0.0.5
python3-saml	1.15.0
pytz	2022.7.1
PyYAML	6.0
requests	2.28.2
requests-oauthlib	1.3.1
rsa	4.9
six	1.16.0
starlette	0.22.0
sniffio	1.3.0
s3transfer	0.6.0
stix	1.2.0.11
taxii2-client	2.3.0
typing-inspect	0.8.0
typing-utils	0.1.0
typing_extensions	4.4.0
urllib3	1.26.14
uvicorn	0.20.0
vine	5.0.0
wcwidth	0.2.6
weakrefmethod	1.0.3
websocket-client	1.4.2
Werkzeug	2.2.2
xmlsec	1.3.11
zipp	3.11.0
requests-mock	1.7.0

カスタムプラグインライブラリを含む

Netskopeは、プラグインが必要とするサードパーティ製のPythonライブラリをすべてプラグインパッケージ自体にバンドルすることを推奨しています。このバンドル化を実現するには、pipインストーラーを使用します。ディレクトリを入力として受け取るスイッチが用意されています。 ディレクトリが指定されている場合、pipはそのディレクトリにパッケージをインストールします。

例えば、以下のコマンドを実行すると、「cowsay」パッケージが「lib」ディレクトリにインストールされます。

> pip install cowsay --target ./lib

これに関する公式ドキュメントについては、 https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-tを参照してください。

上記のlibフォルダからモジュールをインポートする際は、 絶対インポートではなく相対インポートを使用する必要があります。

IDE

推奨されるIDEはPyCharmまたはVisual Studio Codeです。

プラグインディレクトリ構造

このセクションでは、ユーザーリスク交換プラグインの典型的なディレクトリ構造について説明します。

/sample_plugin/
  ├── __init__.py
  ├── Changelog.md
  ├── icon.png
  ├── main.py
  └── manifest.json

• __init__.py:ユーザーリスクエクスチェンジのコードでは、すべてのプラグインパッケージはPythonモジュールとみなされます。すべてのプラグインパッケージに空の「__init__.py」が含まれていることを確認してください。ファイル。
• CHANGELOG.md:このファイルにはプラグインの更新に関する詳細が含まれており、追加、変更、修正などの適切なタグと、ユーザーにとって分かりやすいメッセージを追加して更新する必要があります。
• icon.png: プラグインのアイコンロゴ。これは、UI 上のプラグインのチクレットと設定カードに表示されます。ロゴには、推奨サイズ 300*50 ピクセルまたは同様のアスペクト比の透明なバックグランドが必要です。
• main.py:このPythonファイルには、ユーザーとスコアの取得、アクションの実行、検証、およびアクションの検証メソッドの具体的な実装を含むPluginクラスが含まれています。
• manifest.json:プラグインパッケージのマニフェストファイル。設定可能なすべてのパラメータとそのデータ型に関する情報が含まれています。このファイルには、プラグインの統合に関する詳細情報も記載されています。

ここに記載されているファイルは、プラグインの統合に必須ですが、開発者は特定の統合要件に基づいて他のファイルを追加することもできます。

Changelog.md

これはプラグインの更新に関する詳細情報を含むファイルであり、追加、変更、修正などの適切なタグと、ユーザーにとって分かりやすい適切なメッセージで更新する必要があります。

• 追加: 新しい機能が追加されたときに使用します。
• 修正済み: バグやエラーが修正されたときに使用します。
• 変更: プラグインの既存の実装に変更があった場合に更新します。

変更履歴のサンプル.md

# 1.0.1
## Fixed
- Fixed pagination while fetching records.

# 1.0.0
## Added
- Initial release.

Manifest.json

これは、プラグインに関連するメタ情報を格納する JSON ファイルです。このファイルは、URE モジュールによって読み込まれ、UI にプラグインを表示するとともに、必要な構成パラメータ、プラグイン ID、プラグイン名など、プラグインに関する詳細情報を URE モジュールが把握できるようにします。

• すべてのプラグインには、User Risk Exchangeがプラグインオブジェクトを適切にインスタンス化できるように、必要な情報を含むこのファイルが含まれている必要があります。
• マニフェスト.json の一般的なパラメーターには次のものがあります。
  • name: (文字列) プラグインの名前。（必須）
  • Netskope :(ブール値) です プラグインがNetskopeプラグインかどうかを確認します（例： Netskopeプラグインの場合はTrue、それ以外の場合はFalse）
  • デスクリプション: (文字列) プラグインのデスクリプション。 プラグインの機能と使用手順について説明した詳細なデスクリプションを提供します。 ユーザーとユーザー スコアを取得し、グループ/グループのメンバーに対してアクションを実行します) このデスクトップ リプションは、プラグイン構成カードに表示されます。 （必須）
  • ID: (文字列) プラグインパッケージのID。Cloud Exchangeにインストールされているすべてのプラグインで、一意であることを確認してください。IDはプラグインパッケージのディレクトリ名と一致する必要があります。（必須）
  • タイプ: ( [String] ): データが取得するユーザーのタイプ。ホスト、ユーザー、またはその両方を指定できます。
  • version: (文字列) プラグインのバージョン。MAJOR.MINOR.PATCH の使用 (例:1.0.1)バージョン管理方式を推奨しますが、特に制限はありません。（必須）
  • 設定: (配列) プラグインに必要なすべてのパラメーターに関する情報 (名前、タイプ、ID など) を含む JSON オブジェクトの配列。ネストされた JSON オブジェクトによくあるパラメーターについては、以下で説明します。
    • ラベル：パラメータの名前。これはプラグインの設定ページに表示されます。（必須）
    • key: プラグイン設定が使用される Python dict オブジェクト内のキーとして使用される一意のパラメーター キー。 （必須）
    • type: パラメータの値の型。使用可能な値は、「text」、「password」、「number」、「choice」、「multichoice」です。（必須）詳細については、下記のプラグイン設定パラメータの種類を参照してください。
    • default: このパラメータのデフォルト値。この値は、URE UI のプラグイン設定ページに表示されます。サポートされているデータ型は、「テキスト」、「数値」、「リスト」（複数選択型の場合）です。（必須）
    • mandatory: このパラメータが必須かどうかを示すブール値。パラメータが必須の場合、ユーザーリスク交換UIでは、そのパラメータに空の値を指定することはできません。許容される値は「true」と「false」です。（必須）
    • デスクリプション: パラメータと期待値に関する詳細を提供する、パラメータのヘルプ テキスト レベルのデスクリプション。 この文字列は、プラグインの設定ページにヘルプテキストとして表示されます。（必須）
    • 選択肢：キーと値をJSONキーとして含むJSONオブジェクトのリスト。このパラメータは「type」:「choice」および「multichoice」でのみサポートされています。

Plugin Configuration Parameter types

プラグインのmanifest.jsonファイルのconfigurationセクションに、必要なプラグイン設定パラメータがすべて記載されていることを確認してください。

Password Parameter

このパラメータは、API エンドポイントでの認証のためのシークレット/パスワードを保存するために使用されます。 パスワードを型とするパラメータは、プラグイン設定ページにパスワード入力欄が表示され、プラットフォームによって難読化および暗号化されます。
サンプルJSON

      "configuration": [
           {
               "label": "API Token",
               "key": "api_token",
               "type": "password"
           },
       ]

プラグイン設定ビュー

Text Parameter

このパラメータは、ベースURL、ユーザー名などの文字列情報を格納します。 このパラメータは、プラグイン設定ページに通常のテキスト入力欄として表示されます。
サンプルJSON

       "configuration": [
           {
               "label": "Tenant Name",
               "key": "tenant_name",
               "type": "text"
           },
       ]

プラグイン設定ビュー

Number Parameter

このパラメータは数値/浮動小数点値を保存するために使用されます。 このパラメータは、プラグイン設定ページに数値入力ボックスとして表示されます。（ハッシュリストは脅威情報交換モジュールにあります。）

       "configuration": [
           {
               "label": "Maximum File hash list size in MB.",
               "key": "max_size",
               "type": "number"
           },
       ]

プラグイン設定ビュー

Choice Parameter

このパラメータは、列挙パラメータの値を格納するために使用されます。 このパラメータは、プラグイン設定ページにドロップダウンボックスとして表示されます。
サンプルJSON

	"configuration": [
        {
            "label": "Base URL",
            "key": "base_url",
            "type": "choice",
            "choices": [
                {
                    "key": "Commercial cloud (api.crowdstrike.com)",
                    "value": "https://api.crowdstrike.com"
                },
                {
                    "key": "US 2 (api.us-2.crowdstrike.com)",
                    "value": "https://api.us-2.crowdstrike.com"
                },
                {
                    "key": "Falcon on GovCloud (api.laggar.gcw.crowdstrike.com)",
                    "value": "https://api.laggar.gcw.crowdstrike.com"
                },
                {
                    "key": "EU cloud (api.eu-1.crowdstrike.com)",
                    "value": "https://api.eu-1.crowdstrike.com"
                }
            ],
            "default": "https://api.crowdstrike.com",
            "mandatory": true,
            "description": "API Base URL."
        },

プラグイン設定ビュー

入力を選択した後:

Multichoice Parameter

このパラメータは、複数の選択肢の値を保存するために使用します。 このパラメータは、プラグイン設定ページにドロップダウンボックスとして表示され、複数の値を選択できるようになります。（深刻度は脅威情報交換モジュールに記載されています。）

サンプルJSON

    "configuration": [
        {
            "label": "Severity",
            "key": "severity",
            "type": "multichoice",
            "choices": [
                {
                    "key": "Unknown",
                    "value": "unknown"
                },
                {
                    "key": "Low",
                    "value": "low"
                },
                {
                    "key": "Medium",
                    "value": "medium"
                },
                {
                    "key": "High",
                    "value": "high"
                },
                {
                    "key": "Critical",
                    "value": "critical"
                }
            ],
            "default": [
                "critical",
                "high",
                "medium",
                "low",
                "unknown"
            ],
            "mandatory": false,
            "description": "Only indicators with matching severity will be saved."
        }
    ]

プラグイン設定ビュー

Toggle Parameter

このパラメータはブール値を格納します。トグル有効はTrue、トグル無効はFalseです。
システムプロキシ(「プロキシ」)を使う: Use system proxy configured in Settings.(Default: False)
プラグイン設定ビュー

Main.py

このPythonファイルには、プラグインのコア実装が含まれています。
Netskope .integrations.cre.plugin_base からの標準インポート import PluginBase, ValidationResult, PushResult
from Netskope .integrations.cre.models.business_rule import Action, ActionWithoutParams, ActionWithoutParams, Action.
PluginBase 変数
PluginBase は、プラグインのライフサイクル中に使用できる変数へのアクセスを提供します。 メソッド。 以下は変数の一覧です。

変数名	Usage	デスクリプション
self.logger	self.logger.error(“メッセージ”) self.logger.warn(“メッセージ”) self.logger.info(“メッセージ”)	コアによって提供されるロガーハンドル。このオブジェクトを使用して重要なイベントを記録します。 ログはCloud Exchange監査ログに表示されます。 ロガーオブジェクトのドキュメントを参照してください。
self.configuration	self.configuration.get()<attribute-key-name>	プラグインインスタンスの設定オブジェクトのJSON表現。これを使用して、認証クレデンシャル、サーバーの詳細などの構成属性にアクセスします。manifest.json に記載されている属性のキー名を使用します。
self.last_run_at	self.last_run_at: の場合self.last_run_at.timestamp() この形式は、最後の実行時間をエポック形式に変換するためのものです。	プラグインのプルメソッドが最後に正常に実行された時刻のタイムスタンプを提供します。Cloud Exchange コアは、pull() の実行が成功するたびにチェックポイント時刻を保持します。初回実行時の値はNoneになります。オブジェクトのデータ型はdatetimeです。
self.storage		Cloud Exchangeは、プラグインが状態を維持するためのメカニズムを提供します。このオブジェクトは、後続の呼び出しで必要となるあらゆる状態を保持します。 このオブジェクトのデータ型はPythonの辞書型です。
self.notifier	self.notifier.info(“message”) self.notifier.warn(“message”) self.notifier.error(“message”)	このオブジェクトは、User Risk Exchangeコアの通知機能へのハンドルを提供します。このオブジェクトを使用して、プラットフォームに通知をプッシュします。 通知はユーザーリスク交換UIに表示されます。ユーザーが読んで必要な行動を取れるよう、メッセージ は要約された情報が含まれていることを確認してください。Netskopeプラグインの通知機能。push()メソッドが製品の8MB制限を超えた場合に通知します。
self.proxy	requests.get(url=url,プロキシ=self.proxy)	システムのプロキシ設定が設定されている場合はそのハンドル、設定されていない場合は {}。
self.ssl_validation	requests.get(url=url,verify=self.ssl_validation)	REST API呼び出しに対してSSL検証が強制されるかどうかを示すブール値。

プラグインクラス

• プラグインクラスはPluginBaseクラスを継承する必要があります。PluginBase クラスはNetskope .integrations.cre.plugin_baseで定義されています。
• Plugin クラスが fetch_records、fetch_scores、validate、get_actions、get_action_fields、validate_actions、および execute_actions の実装を提供していることを確認してください。
• プラグインクラスには、サードパーティAPIとの接続と認証を確立するために必要なすべてのパラメータが含まれます。
• プラグインの機能開発においては、ページネーションを常に考慮に入れるべきです。

"""Sample plugin implementation.

This is a sample implementation of the base PluginBase class. Which explains the concrete implementation
of the base class.
"""

from netskope.integrations.cre.plugin_base import PluginBase, ValidationResult, PushResult
from netskope.integrations.cre.models import Indicator, IndicatorType
from typing import List
from datetime import datetime
import requests

PLUGIN_NAME = "<module> <plugin_name> Plugin"

class SamplePlugin(PluginBase):
   """SamplePlugin class having concrete implementation for fetching information and performing actions.

   This class is responsible for implementing pull, perform actions and validate methods with proper return types,
   so that it's lifecycle execution can be scheduled by the URE core engine.
   """

def fetch_records()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、サードパーティ API エンドポイントからユーザー (インジケーター) を取得するロジックを実装します。 このメソッドは定期的に呼び出されます。
• 単体テストが可能であることを確認してください。
• self.proxyを呼び出して、 Cloud Exchangeプラットフォームによって渡されたプロキシ構成を使用します。 これは、Pythonの辞書オブジェクトを返します。 requestsモジュールで直接使用できます。
• API認証のすべての設定パラメータは、 self.configurationを呼び出すことでPython辞書が受け取る形で渡されます。
• すべてのログは、適切なログレベル（info、warn、error）を指定して、 self.loggerオブジェクトによって記録できます。このオブジェクトはログをMongoDBに記録し、API呼び出しを介してアクセスできます。
• self.ssl_validationを使用するSSLサーバー証明書の検証を有効/無効にするためのブール値。
• APIエンドポイントから受信したデータを含むレコードのリストを返します。 注：このリストにはレコードオブジェクトが含まれます。
• 失敗した場合は、適切なメッセージとともに、適切な種類のエラーまたは例外を発生させてください。
• APIエンドポイントがサポートする最大ペイロードサイズを超えた場合は必ず対処してください。 このケースに対処する方法は複数考えられます。
  • API エンドポイントがペイロード サイズが固定された複数のリクエストをサポートしている場合は、データをチャンクで送信します。 この概念はページネーションとも呼ばれます。
  • API が複数のリクエストをサポートしていない場合（1回のAPI呼び出しでのみプッシュできます）、プラグインは残りのインジケーターをスキップして、共有フィルターを調整するようユーザーに通知するか、ペイロードサイズ超過のエラーで失敗する可能性があります。

def fetch_records(self):
"""Fetches users from a 3rd party API.

       Implement the logic of fetching users from 3rd party apis and 
return the list of objects netskope.integrations.cre.models.Records on 
successful fetch otherwise raises an exception.

       Returns:
           List[netskope.integrations.cre.models.Records]: List of 
Record objects received from the 3rd party platform.
       """
       # Load all the configured plugin parameters as python dict objects.
       # Use the key name provided in the manifest.json file for the configuration parameters to
       # get the value of that particular parameter.
       config = self.configuration
       # get proxy settings dict, just the way requests module requires.
       proxy_dict = self.proxy
       # get the ssl_validation bool for enabling/disabling validation of SSL server certificates.
       ssl_validation = self.ssl_validation
       # How to use proxy dict and ssl_validation flag.
       resp = requests.get("www.example.com", proxies=proxy_dict, verify=ssl_validation) 
       # Get the logger object for logging purpose. This logger object logs all the logs to mongodb
       # under the cre database logs collection. Log timestamp is automatically recorded by the logger library.
       # Supported logging levels are info, warn and error.
       logger = self.logger
       logger.info(f"{PLUGIN_NAME}: Finished fetching records")
       return records

def fetch_scores()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、サードパーティ API エンドポイントからスコア (インジケーター) を取得するロジックを実装します。 このメソッドは定期的に呼び出されます。
• 単体テストが可能であることを確認してください。
• self.proxyを呼び出して、CE プラットフォームから渡されたプロキシ構成を使用します。 これは、Pythonの辞書オブジェクトを返します。 requestsモジュールで直接使用できます。
• API認証のすべての設定パラメータは、 self.configurationを呼び出すことでPython辞書が受け取る形で渡されます。
• すべてのログは、適切なログレベル（info、warn、error）を指定して、 self.loggerオブジェクトによって記録できます。このオブジェクトはログをMongoDBに記録し、API呼び出しを介してアクセスできます。
• self.ssl_validationを使用するSSLサーバー証明書の検証を有効/無効にするためのブール値。
• API エンドポイントから受信したデータを含むスコアのリストを返します。このデータは Record オブジェクトに保存されます。 注：このリストにはレコードオブジェクトが含まれます。
• 失敗した場合は、適切なメッセージとともに、適切な種類のエラーまたは例外を発生させる。
• APIエンドポイントがサポートする最大ペイロードサイズを超えた場合は必ず対処してください。 このケースに対処する方法は複数考えられます。
  • API エンドポイントがペイロード サイズが固定された複数のリクエストをサポートしている場合は、データをチャンクで送信します。 この概念はページネーションとも呼ばれます。
  • API エンドポイントが複数のリクエストをサポートしていない場合 (つまり、 （1回のAPI呼び出しでのみプッシュできます）プラグインは残りのインジケーターをスキップして、共有フィルターを調整するようにユーザーに通知するか、ペイロードサイズ超過のエラーで失敗することができます。
• スコアは必ず0～1000の整数にマッピングしてください。

def fetch_scores(self):
       """Fetches users from a 3rd party API.
       
Implement the logic of fetching risk scores from 3rd party apis and return the list of objects netskope.integrations.cre.models. Records a successful fetch otherwise raises an exception.

       Returns:
           List[netskope.integrations.cre.models.Records]: List of Record objects received from the 3rd party platform.
       """
       # Load all the configured plugin parameters as python dict objects.
       # Use the key name provided in the manifest.json file for the configuration parameters to
       # get the value of that particular parameter.
       config = self.configuration
       # get proxy settings dict, just the way requests module requires.
       proxy_dict = self.proxy
       # get the ssl_validation bool for enabling/disabling validation of SSL server certificates.
       ssl_validation = self.ssl_validation
       # How to use proxy dict and ssl_validation flag.
       resp = requests.get("www.example.com", proxies=proxy_dict, verify=ssl_validation) 
       # Get the logger object for logging purpose. This logger object logs all the logs to mongodb
       # under the cre database logs collection. Log timestamp is automatically recorded by the logger library.
       # Supported logging levels are info, warn and error.
       logger = self.logger
       logger.info(f"{PLUGIN_NAME}: Finished fetching records")
       return scores

def validate()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、プラグイン構成を作成する際に渡されたプラグイン構成および認証パラメータを検証します。
• このメソッドは、新しい設定が作成または更新された場合にのみ呼び出されます。
• 必須パラメータがすべて適切なデータ型で渡されていることを検証します。
• 認証パラメータと API エンドポイントを検証して、プラグインのライフサイクルがスムーズに実行されるようにします。
• 検証の成功または失敗を示す成功フラグと、検証失敗の理由を含む検証メッセージを含むValidationResultオブジェクト（ValidationResultデータモデルを参照）を返します。

def validate(self, data):      
       """Validate the Plugin configuration parameters.

       Validation for all the parameters mentioned in the manifest.json for the existence and
       data type. Method returns the netskope.integrations.cre.plugin_base.ValidationResult object with success = True in the case of successful validation and success = False and an error message in the case of failure.
       Args:
           data (dict): Dict object having all the Plugin configuration parameters.
       Returns:
           netskope.integrations.cre.plugin_base.ValidateResult: ValidateResult object with success flag and message.
       """
       self.logger.info(f"{PLUGIN_NAME}: Executing validate method for Sample plugin")
       if (
           "secret_field_id1" not in data
           or not data["secret_field_id1"]
           or type(data["secret_field_id1"]) != str
       ):
           self.logger.error(
               "f{PLUGIN_NAME}: Validation error occurred Error: Secret Field1 is required with type string."
           )
           return ValidationResult(
               success=False, message="Invalid Secret Field 1 provided.",

def get_actions()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、サポートされているすべてのアクションのリストを返す必要があります。
• ActionWithoutParams クラスにサポートされているすべてのアクションを追加し、ActionWithoutParams クラスのオブジェクトのリストを返します。

def get_actions(self): 
      """Get available actions.
      Returns:
	        List[ActionWithoutParams]: List of ActionWithoutParams objects 
               that are supported by the plugin.
       """
	return [
		ActionWithoutParams(label=”Add to group”, value=”add”)
		ActionWithoutParams(label=”Remove from Group”, value=”remove”)
		ActionWithoutParams(label=”No actions”, value=”generate”)
	]

def get_action_fields()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、ドロップダウンリストからターゲットが選択されたときにUIに表示されるフィールドのリストを返す必要があります。
• このメソッドは、ユーザーがいずれかのアクションを選択した後に呼び出す必要があります。
• 選択されたアクションにパラメータが必要な場合は、辞書のリスト（各辞書は設定可能な入力）を返し、そうでない場合は空のリストを返します。
• フィールドの定義方法については、Manifest.json を参照してください。

def get_action_fields(self, action: Action):
       """Get fields required for an action.
       Args: 
	      action (Action): Action object which is selected as Target.
       Return:
	      List[Dict]: List of configurable fields based on selected action.
       """
	if action.value == “add”:
      		return [
			{
				“label”: “Group Name”,
				“key”: “group_name”,
				“type”: “choice”, 
				“choice”: [{key: “name”, value: “id”}, ...]
				“default”: “”,
				“mandatory”: True,
				“description”: “Name of group.”
			}
 	]
else:
	return []

def validate_action()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、プラグイン構成を作成する際に渡されたプラグイン構成および認証パラメータを検証します。
• このメソッドは、新しい設定が作成または更新された場合にのみ呼び出されます。
• プラグイン設定の検証メソッドでは、空欄の検証と型チェックの検証を別々に行う必要があります。
• 必須パラメータがすべて適切なデータ型で渡されていることを検証します。
• 認証パラメータと API エンドポイントを検証して、プラグインのライフサイクルがスムーズに実行されるようにします。
• 検証中に、API トークンとパスワード フィールドを除く、ベース URL、電子メール、ユーザー名などの構成パラメータに対して、strip() を使用します。
• 検証の成功または失敗を示す成功フラグと、検証失敗の理由を含む検証メッセージを含むValidationResultオブジェクト（ValidationResultデータモデルを参照）を返します。
• プラグインにアクションがない場合は、成功フラグ付きのValidationResultオブジェクトを返し、そうでない場合は検証をチェックします。

def validate_action(self, action: Action):
"""Validate Action Parameters.
 
Args:
    action (Action): Action object having all the configurable parameters.
Return:
    netskope.integrations.cre.plugin_base.ValidateResult: ValidateResult object with success flag and message.
"""
    if action.value not in [“add”, “remove”]:
        return ValidationResult(
        success=False, message=”Unsupported action provided.”
    )
    if action.value == “add”:
        if action.parameters.get(“group_name”) is None:
            return ValidationResult(
                success=False, message=”Group Name should not be empty.”
            )
    return ValidationResult(
        success=True, message=”Validation successful.”
    )

def execute_action()

これはPluginBaseクラスの抽象メソッドです。

• このメソッドは、実行されたアクションを検証します。
• メソッドがグループへの追加やグループからの削除といったアクションを実行することを確認してください。
• サードパーティAPI呼び出しを実行するには、ヘルパーメソッドを使用するのが望ましい。

 def execute_action(self, record: Record, action: Action):
       """Execute action on the user.
       Calls _add_to_group or _remove_to_group helper methods in the case
           of add or remove action
       Passes when action is generate

if action.value == "generate":
       return
       
if action.value == "add":
 	group_id = action.parameters.get("group")
 	self._add_to_group(user, group_id)
 	self.logger.info(f"Added {user} to group to group ")
 )

データモデル

このセクションでは、データモデルとその特性を一覧表示します。

レコードタイプモデル

• RecordTypeモデルには、レコードのタイプ（ユーザーまたはホスト）が含まれます。
• レコードモデルには、USERとHOSTという2つのフィールドがあり、HOSTはレコード型です。
• レコードのリストを返す際に、fetch_records メソッドと fetch_scores メソッド内でモデルとやり取りすることになります。

データモデルの特性

名前	タイプ	デスクリプション
USER	string	ユーザーになることができます。
HOST	string	ホストになることができます。

from netskope.integrations.cre.models import RecordType, Record
for user in users:
    res.append(
            Record(uid=user["email"], type=RecordType.USER, score=None)
        )

レコードモデル

• レコードモデルには、ユーザー（指標）レコードが含まれます。
• レコード モデルには、uid、type、score の 3 つのフィールドがあり、それぞれ電子メール、ユーザーのタイプ、整数のスコア値です。
• レコードのリストを返す際に、fetch_users メソッドと fetch_scores メソッド内でモデルとやり取りすることになります。

データモデルの特性

名前	タイプ	デスクリプション
uid	string	ユーザーの電子メール。
タイプ	list[string]	ユーザー、ホスト、またはその両方である可能性があります。
score	int	ユーザーのスコア。0～1000の範囲の整数にマッピングする必要があります。

from netskope.integrations.cre.models import Record

          Record(uid=each_user.get("userPrincipalName"),
                type=RecordType.USER,
                score=None
         )

アクションクラス

• このクラスは、実行したいアクションを表します。
• 通常、生成、追加、削除、またはそれ以上のアクションを実行する必要があります。
• それは スコアの取得、ユーザーの取得、validate_action、execute_actions、およびget_action_fieldsで行われます。

データモデルの特性

名前	タイプ	デスクリプション
label	string	UIに表示されるアクションのラベルを表示します。
value	string	それにアクセスするための鍵。
parameters	Dict	それぞれのプラグインに必要なアクションフィールドがすべて含まれます。
generateAlerts	Bool	条件が真の場合にCTO宛てにアラートを生成します。
syncAction	Bool	条件が真の場合にアクションを同期する。

from netskope.integrations.cre.models import Action

       if action.value == "generate":
             return

ActionWithoutParamsクラス

• このクラスは、パラメータなしで実行したいアクションを表します。 パラメータなし。
• それは get_actions メソッド内にあります。
• これは サポートされているアクションをユーザーに表示します。

データモデルの特性

名前	タイプ	デスクリプション
label	string	UIに表示されるアクションのラベルを表示します。
value	string	それにアクセスするための鍵。

from netskope.integrations.cre.models import ActionWithoutParams

       return [
            ActionWithoutParams(label="Add to group", value="add"),
            ActionWithoutParams(label="Remove from group", value="remove"),
            ActionWithoutParams(label="No actions", value="generate"),
        ]

ValidationResultクラス

• このクラスには、プラグインの新しい設定を作成する際にPluginオブジェクトに渡されるプラグイン設定パラメータに対する検証プロセスの結果が含まれています。
• validate メソッドに渡されるすべてのパラメータが、データ型と値に対して検証されていることを確認してください。
• validate メソッドは、検証操作の結果を示す成功フラグと、検証が失敗した場合に適切なエラーメッセージを含むメッセージフィールドを持つ、このクラスのオブジェクトを返します。 （成功した場合は、成功フラグがTrueの単純な成功メッセージを返す必要があります。）
• Validate Action もこのクラスのオブジェクトを返すことに注意してください。

データモデルの特性

名前	タイプ	デスクリプション
success	bool	成功フラグは、検証操作が成功したか失敗したかの結果を示します。
message	string	メッセージフィールドは失敗の場合のエラーを示します。 成功のケースでは、シンプルな成功メッセージで十分な場合もある。

from netskope.integrations.cre.plugin_base import ValidationResult

       ValidationResult(
           success=True,
           message="Validation Successful for Sample plugin"
       )

ログ記録

UREは、ログ記録のためのロガーオブジェクトへのハンドルを提供します。

• コード内でprint文を使用することは避けてください。
• このオブジェクトは、タイムスタンプフィールドを使用して中央のCloud Exchangeデータベースにログを記録します。 サポートされているログレベルは、情報、警告、エラーです。
• API認証情報やその他の機密情報がログメッセージに漏洩しないようにしてください。
• Cloud Exchangeプラットフォームによって渡されるロガー オブジェクトを使用して、適切なログ メカニズムを実装してください。
• 運用チームがトラブルシューティングを行う際に役立つよう、十分なログ記録が行われるようにしてください。
• 通知やログに機密データが記録されたり、漏洩したりしないようにしてください。

self.logger.error(
               f"{PLUGIN_NAME}: Error log-message goes here."
 )

 self.logger.warn(
               f"{PLUGIN_NAME}: Warning log-message goes here."
 )

 self.logger.info(
               f"{PLUGIN_NAME}: Info log-message goes here."
 )

通知

UREは通知オブジェクトのハンドルを提供します。このハンドルは URE UI上で通知を生成するために使用できます。

• このオブジェクトは、 Cloud Exchangeプラットフォームから Plugin オブジェクトに渡されます。 すべてのプラグイン統合は ユーザーに即座に通知する必要のある障害が発生した場合はいつでもこのオブジェクトを使用できます。 通知のタイムスタンプは、 Cloud Exchangeプラットフォームによって管理されます。
• このオブジェクトは、障害の深刻度に応じて色分けされた通知をUI上に表示します。サポートされている通知の重要度は、情報、警告、エラーです。
• 通知メッセージに、API認証情報やその他の機密情報が含まれていないことを確認してください。
• 障害や重大な状況（レート制限、ペイロードサイズの超過など）が発生した場合に通知を発生させ、プラグインの状態をユーザーに通知するための通知オブジェクト。

 self.notifier.info(
               f"{PLUGIN_NAME}: Info notification-message goes here."
 )

 self.notifier.error(
               f"{PLUGIN_NAME}: Error notification-message goes here."
 )

 self.notifier.warn(
               f"{PLUGIN_NAME}: Warning notification-message goes here."
 )

Testing

Linting

ビルドプロセスの一環として、いくつかのリンターを実行して、 プログラミングエラー、スタイルエラー、および潜在的なセキュリティ問題を検出します。

Flake8

これは基本的なリンターです。必要な依存関係がすべて揃っていなくても実行でき、不要なエラーを検出します。 また このリンターを使用して、標準的な Python PEP8 フォーマットスタイルを強制します。 まれに、このリンターから返されるエラーや警告を無効にする必要が生じる場合があります。エラーを無効にしたい行に、次のようなインラインコメントを追加することで、この操作を実行できます。

# noqa: <error-id>

例えば、

example = lambda: 'example' # noqa: E731

インラインコメントを追加する際は、必ず無効化するエラーコードも併せて記載してください。そうすれば、同じ行に他のエラーがあった場合、それらが報告されます。
詳細については、 https ://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors を参照してください
Flake8リンターでは、PEP8スタイルのドキュメント文字列チェックも有効になっています。したがって、すべての関数/モジュールに適切なドキュメンテーション文字列が追加されていることを確認してください。

単体テスト

単体テストを実施し、コードの小さな単位を隔離された状態で、かつ決定論的にテストするようにしてください。単体テストでは、外部 API との通信や モックの使用を避けるようにしてください。 単体テストによってコードカバレッジが70%以上であることを確認してください。

環境設定

単体テストを行うには、統合スクリプトまたは自動化スクリプトをプラグインディレクトリ構造内で開発する必要があります。セットアップを実行するために必要なすべてのPythonモジュール依存関係をPIPでインストールします。 テストを実行する前に、l coreリポジトリのrequirements.txtに記載されている必要な依存関係をすべてインストールしてください。

ユニットテストを作成する

ユニットテストは、 <your_plugin_name> _test.py という名前の別の Python ファイルに記述してください。単体テストファイル内では、各単体テスト関数は test_<your test case> という名前を付ける必要があります。単体テストの書き方やフォーマットに関する詳細は、 PyTest ドキュメントをご覧ください。

Mocking

モックにはpytest-mockを使います。 pytest-mockはデフォルトで有効になっており、上記の基本環境にインストールされています。モックオブジェクトを使用するには、それをテスト関数のパラメータとして渡すだけです。 モッカーは プラグインクラスオブジェクトと外部APIの両方をモックできます。
例：

def test_netskope_fetch_users(mocker):
   mocker.patch("cre.plugins.sample.main.Sample.fetch_users")
   fetch_users_return_result = [
       Record(uid="a@def.com", type=Record.user, score=400),
       Record(uid="b@pqr.com", type=Record.user, score=300),
       Record(uid="c@xyz.com", type=Record.user, score=750),
   ]

   samplePlugin.fetch_users.return_value = fetch_users_return_result 
   sp = samplePlugin(None, None, None, logger)
   actual_fetch = sp.fetch_users()
   assert fetch_return_result == actual_fetch

API呼び出しのリクエストモジュールのレスポンスをモックするため（requests_mock Pytestプラグインはすべての依存関係とともにインストールされています）。

def test_fetch_users(requests_mock):
   endpoint_url = "https://example-api.com"
   mock_response_json = {
       {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value": [
        {
            "@odata.type": "#microsoft.graph.user",
            "id": "48a97c4b-65af-4cb7-90f9-c7835d5ecd8b",
            "userPrincipalName": "adaml@xyz.com"
        }
    ]
}

   requests_mock.get(endpoint_url, json=mock_response_json)
   config_dict = {
       "tenant_name": "ecre-ccec-jpvasq",
       "client_id": "ue4y-3id8-mnx87q",
       "client_secret": "d9oe-ple7-nfi34w",
       "api_token": "token",
   }
   sp = SamplePlugin(config_dict, None, None, logger)
   actual_users_lists = sp.fetch_users(
       endpoint_url,
       config_dict['api_token']
   )
   users_mock = [
  	Record(uid="a@def.com", type=Record.user, score=400),
       Record(uid="b@pqr.com", type=Record.user, score=300),
       Record(uid="c@xyz.com", type=Record.user, score=750),
   ]
   assert len(actual_users_lists) == len(users_mock)
   for i in range(len(actual_users_lists)):
       assert actual_ind_lists[i].value == users_mock[i].value

ユニットテストを実行する

$ PYTHONPATH=. pytest

CE上でのプラグインの展開

プラグインをパッケージ化する

Cloud Exchangeでは、開発されたプラグインはzipまたはtar.gz形式で提供されることを想定しています。
パッケージを圧縮するには、次のコマンドを実行してください。

zip -r sample_plugin.zip sample_plugin

tar.gzパッケージを生成するには、以下のコマンドを実行してください。

tar -zcvf sample_plugin.tar.gz sample_plugin

プラグインをアップロードする

この zip または tar.gz をCloud Exchangeプラットフォームにデプロイするには:

1. Cloud Exchangeプラットフォームにログインします。
2. Settings > Plugin .
   へ移動
3. Add New Plugin .
   をクリックしてください
4. Browseをクリックしてください。
5. zipファイルまたはtar.gzファイルをSelect 。
   
6. Uploadをクリックしてください。

Add a Repo

Cloud Exchangeプラットフォームにプラグインをデプロイするには、次の手順に従ってCloud Exchangeプラットフォームにリポジトリを追加します。

1. Cloud Exchangeプラットフォームにログインします。
2. Settings > Plugin Repository .
   へ移動してください。
3. Configure New Repository .
   をクリックしてください
4. リポジトリ名、リポジトリURL、ユーザー名、および個人アクセストークンを入力してください。
5. Saveをクリックしてください。
6. Settings > Pluginsへ移動してください。
7. リポジトリのドロップダウンリストからリポジトリ名Select 。

Deliverables

Plugin Guide

• プラグインガイドは、リリースごとに必ず更新してください。
• プラグインガイドには以下の内容が含まれている必要があります。
  • Compatibility
  • リリースノート
  • デスクリプション
  • 前提条件
  • 権限
  • 製品の承認
  • Netskope User Risk Exchangeプラグインの設定
  • 当社が開発したサードパーティ製ユーザーリスク交換プラグインの設定。
  • ビジネスルールの設定
  • アクションの設定
  • Validation.

デモビデオ

ユーザーリスク交換プラグインの開発が成功したら、デモビデオを作成し、プラグインのエンドツーエンドのワークフローを示してください。