共用方式為

Microsoft Copilot for Security 中的 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 規格檔，那你就可以直接用那個。 將 OpenAPI 規格 https://[domain]/template.yaml 托管在可存取的倉庫或 GitHub gist。

使用下列內容建立新的外掛程式資訊清單檔案 (使用上一章節中建立之 OpenAPI 規格檔案的 URL 取代 OpenaApiSpecUrl 值):

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 中支援的兩種不同上傳類型。

* 這些代表擴充超過 openAI 最初支援的驗證方法。

下表顯示每個驗證類型的支援設定。

驗證類型 設定 描述
AAD 或 AADDelegated EntraScopes 一份逗號分隔的 Microsoft Entra 請求範圍清單。
Basic Username 這是基本驗證用的用戶名稱。
Basic Password 用於基本認證的密碼。
ApiKey 或 ServiceHttp Key 標頭/查詢參數的名稱。
ApiKey 或 ServiceHttp AuthScheme 在標頭中使用時，驗證方案名稱會加在 前面 Value 。
ApiKey 或 ServiceHttp Location API 金鑰的位置，要麼HeaderQueryParams是 。
ApiKey 或 ServiceHttp Value 要用的金鑰/代幣。
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow TokenEndpoint 請求權杖的端點。
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow Scopes 請用逗號分隔的範圍清單。
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow ClientId 請求令牌時要使用的客戶端 ID。
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow ClientSecret 請求權杖時使用的客戶端秘密。
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow AuthorizationContentType 發送令牌請求時所使用的內容類型。
OAuthAuthorizationCodeFlow AuthorizationEndpoint 請求授權碼的端點。

預先設定驗證設定

注意事項

目前只能預先設定一種認證類型的設定。

如果外掛程式的每個執行個體 (例如 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 基本驗證的外掛程式。

注意事項

強烈建議您只搭配使用 HTTPS 的 API 端點使用基本驗證。

建立 OpenAPI 規格

在此範例中，我們將使用 httpbin.org 服務來驗證基本身份驗證。 Httpbin.org 已發佈和 OpenAPI 規格，但例如，我們只會使用其中一個作業。

建立具有下列內容的新檔案，並將之上傳至可公開存取的位置。 本教學課程使用 GitHub Gist 來建立新的 gist，其中內容位於 https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml

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 規格，但例如，我們只會使用其中一個作業。

建立具有下列內容的新檔案，並將之上傳至可公開存取的位置。 本教學課程使用 GitHub Gist 來建立新的 gist，其中內容位於 https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml

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.

建立外掛程式資訊清單

在這個範例中，我們將設定外掛，讓它用標頭傳送 API 金鑰 x-test-api-key 。 我們會預先設定金鑰的位置，但需要使用者在安裝外掛程式時輸入金鑰值。

使用下列內容建立新的外掛程式資訊清單檔案 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 金鑰以進行驗證。 您可以立即完成，或選取 [稍後再執行此動作] 以稍後再進行設定。

顯示 Set API Key 的截圖

如果您選擇 [稍後再執行此動作] 選項，則您稍後可以選取 [管理外掛程式] 頁面上的 [設定] 按鈕，來設定使用者名稱和密碼。

顯示設定選項的截圖。

如果你想在設定後更新設定，可以在管理插件頁面點擊設定圖示來操作。

設定的螢幕擷取畫面

具有可自訂端點 URL 的 API 外掛程式

本範例會新增使用者可透過 Security Copilot 設定的可設定設定名稱 「InstanceURL」。 接著系統會在 API 技能群組下新增設定，告知 Security Copilot 使用「InstanceURL」設定的值作為提出 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

下列範例顯示如何使用可自訂的端點 URL 搭配 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
  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 清單檔案 plugin.yaml ，內容如下，並替換 OpenApiSpecUrl Web App 中的 和 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. 輸入用戶端密碼，然後選取 [連線]。

    截圖顯示 Step 輸入客戶端秘密

  4. 您將會看到已成功連結帳戶的通知。

    網頁瀏覽器圖片。

  5. 設定已完成。

    地位的形象。

系統現在應該會啟用外掛程式。

如果你在選擇 Connect（連線）時看到錯誤訊息，請依照以下步驟處理錯誤訊息 ：錯誤訊息圖片。

新增下列回呼 URI (https://securitycopilot.microsoft.com/auth/v1/callback)，如下圖所示，然後嘗試重新連線。

認證頁面圖片。

限制

  1. 通常允許狀態變更和寫入操作的 HTTP 動詞 (例如 POST) ，只能用於資料檢索。 目前不支援寫入操作。
  • Last updated on