次の方法で共有

Microsoft Security Copilot の API プラグイン

既存の OpenAI 仕様ファイルから API プラグインを作成する

このクイックスタート チュートリアルでは、Security Copilot で既存の OpenAI プラグインを使用する方法を示します。

この演習では、このマニフェスト ファイル: https://hacktrack.routum.io/.well-known/ai-plugin.json が使用されます。

プラグイン マニフェストのアップロード

  1. Microsoft Security Copilotにサインインします。

  2. プロンプト バーから [プラグイン] ボタンを選択して、[プラグイン の管理] にアクセスします。

    [プラグイン] ボタンを示すスクリーンショット。

  3. [カスタム] まで下にスクロールし、[プラグインの追加] を選択します。

    [プラグインの追加] ボタンを示すスクリーンショット。

  4. アップロード形式として [OpenAI プラグイン] を選択し、リンクとして https://hacktrack.routum.io/.well-known/ai-plugin.json を入力して [追加] を選択します。

    OpenAI プラグインの追加を示すスクリーンショット。

既存の API からの API プラグイン

このクイックスタート チュートリアルでは、既存の API を Security Copilot API プラグインに変える方法を示します。

OpenAPI 仕様ファイルを作成する

API に既に OpenAPI 仕様ファイルがある場合は、それを使用できます。 アクセス可能なリポジトリまたは GitHub gist で OpenAPI 仕様 https://[domain]/template.yaml をホストします。

次の内容で新しいプラグイン マニフェスト ファイルを作成します (OpenaApiSpecUrl 値を、前のセクションで作成した OpenAPI 仕様ファイルへの URL に置き換えます):

Descriptor:
  Name: 
  DisplayName: 
  Description: 

SkillGroups:
  - Format: API
    Settings:
      OpenApiSpecUrl: https://[domain]/template.yaml

API 認証

サポートされているスキーム

Security Copilot は、プラグインを認証するためのいくつかのスキームをサポートしています。

配色 説明 Copilot マニフェストのサポート OpenAI のサポート +
なし 認証はありません。 はい はい
Basic 基本認証。 はい いいえ
ApiKey ApiKey ベースの認証。開発者が提供した ApiKey がカスタム ヘッダーまたはクエリ パラメーターで渡されます。 はい はい*
ServiceHttp 指定されたトークンに基づく認証。 はい はい
OAuthAuthorizationCodeFlow OAuth 2.0 認証コード フローは、ユーザー資格情報を共有せずに Microsoft 以外のアプリケーションへのアクセスを許可するために使用される、より安全で複雑な認証方法です。 はい はい
OAuthClientCredentialsFlow 基本認証と似ていますが、代わりにサーバー間の通信、またはユーザー固有のアクセス許可を必要としないパブリック データにアクセスする場合に使用されます。 はい いいえ
Microsoft Entra ID アプリケーションのみのアクセス。 はい はい*
AADDelegated ユーザー + アプリケーションのみのアクセス。 はい はい*

+ このフィールドは、Security Copilot でサポートされている 2 種類のアップロードを示すために使用されます。

* これらは、openAI によって当初サポートされていたものを超えて拡張された認証方法を表します。

次の表は、各認証の種類でサポートされている設定を示しています。

認証の種類 設定 説明
AAD または AADDelegated EntraScopes 要求する Microsoft Entra スコープのコンマ区切りリスト。
Basic Username 基本認証に使用するユーザー名。
Basic Password 基本認証に使用するパスワード。
ApiKey または ServiceHttp Key ヘッダー/クエリ パラメーターの名前。
ApiKey または ServiceHttp AuthScheme 認証スキームの名前。ヘッダーで使用される場合、Value の先頭に追加されます。
ApiKey または ServiceHttp Location API キーの場所。Header または QueryParams。
ApiKey または ServiceHttp Value 使用するキー/トークン。
OAuthAuthorizationCodeFlow または OAuthClientCredentialsFlow TokenEndpoint トークンを要求するエンドポイント。
OAuthAuthorizationCodeFlow または OAuthClientCredentialsFlow Scopes 要求するスコープのカンマ区切りのリスト。
OAuthAuthorizationCodeFlow または OAuthClientCredentialsFlow ClientId トークンを要求するときに使用するクライアント ID。
OAuthAuthorizationCodeFlow または OAuthClientCredentialsFlow ClientSecret トークンを要求するときに使用するクライアント シークレット。
OAuthAuthorizationCodeFlow または OAuthClientCredentialsFlow AuthorizationContentType トークン要求の送信時に使用されるコンテンツ タイプ。
OAuthAuthorizationCodeFlow AuthorizationEndpoint 承認コードを要求するエンドポイント。

認証設定の事前構成

注:

現在、1 つの認証の種類の設定を事前に構成することのみ可能です。

プラグインのすべてのインスタンス (たとえば、Microsoft Entra スコープのセット) に同じ値が使用される場合は、プラグインの認証設定を事前構成できます。 設定の事前構成は、認証の種類とともにキーと値のペアのコレクションを記述子の Authorization フィールドに設定することによって処理されます。

次の例は、AAD 認証の種類の Microsoft Entra スコープの既定のセットを指定する方法を示しています。

Descriptor:
  Name: SampleAPI
  Description: Sample API
  SupportedAuthTypes:
    - AAD
  Authorization:
    Type: AAD
    EntraScopes: https://graph.microsoft.com/.default

基本認証を使用した API プラグイン

このクイック スタート チュートリアルでは、HTTP Basic 認証を使用するプラグインを作成する方法について説明します。

注:

基本認証は、HTTPS を使用する API エンドポイントでのみ使用することを強くお勧めします。

OpenAPI 仕様を作成する

この例では、httpbin.org サービスを使用して基本認証を検証します。 Httpbin.org は既に OpenAPI 仕様を公開していますが、たとえば、操作の 1 つだけを使用する目的で説明します。

次の内容を含む新しいファイルを作成し、公的にアクセスできる場所にアップロードします。 このチュートリアルでは、GitHub Gist を使用して、https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml のコンテンツを含む新しい gist を作成しました

openapi: 3.0.0

info:
    title: httpbin.org
    description: A simple HTTP Request & Response Service.
    version: "0.9.2"

servers:
    - url: https://httpbin.org/

paths:
    /basic-auth/{user}/{passwd}:
        get: 
            operationId: TestBasicAuth
            description: |
              This is a plugin to test basic authentication 
              #ExamplePrompts Test Basic Auth using HTTPbin plugin
              #ExamplePrompts Use HTTPbin to test basic authorization 
            summary: Prompts the user for authorization using HTTP Basic 
            parameters:
                - in: path 
                  name: user
                  schema:
                    type: string
                  required: true
                - in: path
                  name: passwd 
                  schema:
                    type: string
                  required: true
            responses:
                200:
                    description: Successful authentication. 
                401:
                    description: Unsuccessful authentication.

プラグイン マニフェストを作成する

この例では、httpbin.org サービスを使用して基本認証を検証します。 Httpbin.org は既に OpenAPI 仕様を公開しています。

次の内容で新しいプラグイン マニフェスト ファイル plugin.yaml を作成します:

Descriptor:
  Name: SampleAPIForBasicAuth
  DisplayName: httpbin.org
  Description: Plugin for making example http requests
  SupportedAuthTypes:
    - Basic

SkillGroups:
  - Format: API
    Settings:
      OpenApiSpecUrl: https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml

プラグイン マニフェストをアップロードする

「プラグインの管理」の手順に従って、プラグイン マニフェストを Security Copilot にアップロードします。

認証を構成する

警告

この例を設定するときは、既存のユーザー名またはパスワードを入力しないでください。 資格情報は検証されないため、任意の値が受け入れられます。

プラグインをアップロードした後、基本認証のユーザー名とパスワードを入力します。 この手順を今すぐ完了することも、[後で実行する] を選択して後で構成することもできます。

[ユーザー名とパスワードの設定] ダイアログを示すスクリーンショット

[後で実行する] オプションを選択した場合は、プラグインの管理ページで [設定] ボタンを選択することで、後でユーザー名とパスワードを構成できます。

設定のオプションを示すスクリーンショット

構成後に設定を更新したい場合は、管理プラグイン ページの設定アイコンをクリックして更新できます。

[設定] イメージを示すスクリーンショット。

API キー認証を使用した API プラグイン

このクイックスタート チュートリアルでは、API キーを使用して認証するプラグインを作成する方法を示します。 API キー認証では、要求の一部としてクエリ文字列パラメーターまたはヘッダーとして渡される秘密鍵/トークンを使用します。 API キーは要求の認証に使用され、特定のユーザーに関連付けられません。

OpenAPI 仕様を作成する

この例では、httpbin.org サービスを使用して API キー認証を検証します。 Httpbin.org は既に OpenAPI 仕様を公開していますが、たとえば、操作の 1 つだけを使用する目的で説明します。

次の内容を含む新しいファイルを作成し、公的にアクセスできる場所にアップロードします。 このチュートリアルでは、GitHub Gist を使用して、https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml のコンテンツを含む新しい gist を作成しました

openapi: 3.0.0

info:
    title: httpbin.org
    description: A simple HTTP Request & Response Service.
    version: "0.9.2"

servers:
    - url: https://httpbin.org/

paths:
    /headers:
        get: 
            operationId: TestApiKeyAuth
            summary: Returns the provided headers
            responses:
                200:
                    description: Successful request.

プラグイン マニフェストを作成する

この例では、x-test-api-key ヘッダーを使用して API キーを送信するようにプラグインを設定します。 キーの場所は事前に設定しますが、プラグインのインストール時にユーザーがキーの値を入力する必要があります。

次の内容で新しいプラグイン マニフェスト ファイル plugin.yaml を作成します:

Descriptor:
  Name: SampleAPIForApiKeyAuth
  DisplayName: httpbin.org - API Key Authentication
  Description: Plugin for making example http requests
  SupportedAuthTypes:
    - ApiKey
  Authorization:
    Type: APIKey
    Key: x-test-api-key
    Location: Header
    AuthScheme: ''

SkillGroups:
  - Format: API
    Settings:
      OpenApiSpecUrl: https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml

プラグイン マニフェストをアップロードする

「プラグインの管理」の手順に従って、プラグイン マニフェストを Security Copilot にアップロードします。

認証を構成する

警告

この例を設定するときは、既存の API キーを入力しないでください。 API キーは検証されていないため、任意の値が受け入れられます。

プラグインをアップロードした後、認証用の API キーの入力を求められます。 これを今すぐ完了することも、[後で実行する] を選択して後で構成することもできます。

API キーの設定を示すスクリーンショット

[後で実行する] オプションを選択した場合は、プラグインの管理ページで [設定] ボタンを選択することで、後でユーザー名とパスワードを構成できます。

設定オプションを示すスクリーンショット

構成後に設定を更新したい場合は、管理プラグイン ページの設定アイコンをクリックして更新できます。

設定のスクリーンショット

カスタマイズ可能なエンドポイント URL を含む API プラグイン

この例では、ユーザーが Security Copilot を使用して構成できる構成可能な設定名 "InstanceURL" を追加します。 次に、API 要求を行うためのエンドポイントとして "InstanceURL" 設定の値を使用するように Security Copilot に指示する設定が API スキル グループの下に追加されます。

Descriptor:
  Name: Example
  Settings:
    - Name: InstanceURL
      Label: Instance URL
      Description: The URL of the instance to connect to
      HintText: "e.g. https://example.com"
      SettingType: String
      Required: true

SkillGroups:
 - Format: API
   Settings:
     OpenApiSpecURL: https://example.com/openapi.json
     EndpointUrlSettingName: InstanceURL

次の例は、API キーを使用したカスタマイズ可能なエンドポイント URL の使用を示しています:

Descriptor:
  Name: Example
  Settings:
    - Name: InstanceURL
      Label: Instance URL
      Description: The URL of the instance to connect to
      HintText: "e.g. https://example.com"
      SettingType: String
      Required: true
  SupportedAuthTypes:
    - ApiKey
  Authorization:
    Type: APIKey
    Key: session
    Location: Header
    AuthScheme: ''

SkillGroups:
 - Format: API
   Settings:
     OpenApiSpecURL: https://example.com/openapi.json
     EndpointUrlSettingName: InstanceURL

OAuthAuthorizationCodeFlow を使用した API プラグイン

このクイックスタート チュートリアルでは、認証に OAuthAuthorizationCodeFlow フローを使用するスキルを作成する方法を示します。

プラグイン マニフェストを作成する

次の内容で新しいプラグイン マニフェスト ファイル plugin.yaml を作成し、Web アプリの OpenApiSpecUrl 値と EndpointUrl 値を置き換えます。

Descriptor:
  Name: SamplePluginManifestOAuth
  Description: Gets info via OAuth
  DescriptionDisplay: Current DateTime, report status
  DescriptionForModel: Shows an OAUTH Sample
  DisplayName: WeatherNew
  Authorization:
    Type: OAuthAuthorizationCodeFlow
    ClientId: <id of client that wants to auth>
    AuthorizationEndpoint: https://sample.com/oauth2/v2.0/authorize
    TokenEndpoint: https://sample.com/oauth2/v2.0/token
    Scopes: <Scopes>
    AuthorizationContentType: application/x-www-form-urlencoded
SkillGroups:
- Format: API
  Settings:
    OpenApiSpecUrl: https://sample.com
    EndpointUrl: https://sample.com

プラグイン マニフェストをアップロードする

こちらの手順に従って、プラグイン マニフェストを Security Copilot にアップロードします。

認証を構成する

  1. Microsoft Security Copilotにサインインします。

  2. [カスタム] まで下にスクロールし、[セットアップ] を選択します。

    組織の接続を示すスクリーンショット

  3. クライアント シークレットを入力し、[接続] を選択します。

    クライアント シークレットを入力するステップを示すスクリーンショット

  4. アカウントが正常にリンクされたことを示す通知が表示されます。

    Web ブラウザーの画像。

  5. セットアップが完了しました。

    状態の画像。

これでプラグインが有効になるはずです。

[接続] を選択したときにエラー メッセージが表示された場合は、次の手順に従ってエラーに対処します: エラー メッセージの画像

次の画像に示すように、次のコールバック URI (https://securitycopilot.microsoft.com/auth/v1/callback) を追加し、再接続してみます。

認証ページの画像。

制限事項

  1. 通常、状態の変更や書き込み操作 (POST など) を許可する HTTP 動詞は、データ取得の目的でのみ使用できます。 書き込み操作は現在サポートされていません。

  2. 要求本文スキーマは、深さを 1 に制限する必要があります。 つまり、親オブジェクト自体に入れ子になったオブジェクトを含めることはできません。 この深度制限に違反すると、コード 2006 でエラーが発生します。

    2.1 要求本文の深さ = 1 の例を次に示します。

    {
    "id": "UserID",
    "name": "Alex Wilber",
    "email": "AlexW@contoso.com",
    "isActive": true
}

    2.2 次の要求本文の例は、深さが 1 を超えるので受け入れられません:

    {
    "productId": 123456,
    "name": "Widget",
    "price": 9.99,
    "manufacturer": {
       "name" :"Tailspin Toys",
       "address": {
          "street" : "123 Anystreet",
          "city" : "Redmond",
          "zipcode": "98005"
        }
    },
    "tags": [
       "Holiday2024", "Popular"
    ]
}