閱讀英文

共用方式為


Microsoft Copilot for Security 中的 API 外掛程式

來自現有 OpenAI 外掛程式的 API 外掛程式

本快速入門教學課程顯示如何在 Security Copilot 中使用現有的 OpenAI 外掛程式。

在此練習中,會使用 此資訊清單檔案

上傳外掛程式資訊清單

  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。

使用下列內容建立新的外掛程式資訊清單檔案 (使用上一章節中建立之 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 最初支援的驗證方法。

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

驗證類型 設定 描述
AADAADDelegated EntraScopes 要要求之 Microsoft Entra 範圍的逗號分隔清單。
Basic Username 要用於基本身份驗證的用戶名稱。
Basic Password 用於基本身份驗證的密碼。
ApiKeyServiceHttp Key 標頭/查詢參數的名稱。
ApiKeyServiceHttp AuthScheme 在標頭中使用時,前面加上 Value 的驗證配置名稱。
ApiKeyServiceHttp Location API 金鑰的位置,可以 Header 是 或 QueryParams
ApiKeyServiceHttp Value 要使用的金鑰/令牌。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow TokenEndpoint 要向其要求令牌的端點。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow Scopes 要要求的範圍逗號分隔清單。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow ClientId 要求令牌時要使用的用戶端標識碼。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow ClientSecret 要求令牌時要使用的客戶端密碼。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow 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. 

建立外掛程式資訊清單

在此範例中,我們將設定外掛程式,以便使用 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 技能群組下新增設定,告知 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.yaml ,並取代 Webapp 中的 OpenApiSpecUrlEndpointUrl 值。

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. 您將會看到已成功連結帳戶的通知。

    網頁瀏覽器的影像。

  5. 設定已完成。

    狀態的影像。

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

如果您在選取 [ 連線] 時看到錯誤訊息,請使用下列步驟來解決此錯誤: 錯誤訊息的影像。

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

驗證頁面的影像。

限制

  1. 通常允許狀態變更和寫入作業的 HTTP 動詞 (例如,POST) 只能用於數據擷取用途。 目前不支援寫入作業。

  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"
        ]
    }