Прочитать на английском

Поделиться через


Подключаемые модули API в Microsoft Security Copilot

Подключаемый модуль API из существующего подключаемого модуля OpenAI

В этом кратком руководстве показано, как использовать существующий подключаемый модуль OpenAI в Security Copilot.

В этом упражнении используется этот файл манифеста.

Отправка манифеста подключаемого модуля

  1. Войдите в Microsoft Security Copilot.

  2. Перейдите в раздел Управление подключаемыми модулями, нажав кнопку Подключаемый модуль на панели запросов.

    Снимок экрана: кнопка

  3. Прокрутите вниз до пункта Пользовательский и выберите Добавить подключаемый модуль.

    Снимок экрана: кнопка

  4. Выберите Подключаемый модуль OpenAI в качестве формата отправки, введите https://hacktrack.routum.io/.well-known/ai-plugin.json в качестве ссылки и нажмите кнопку Добавить.

    Снимок экрана: добавление подключаемого модуля OpenAI.

Подключаемый модуль API из существующего API

В этом кратком руководстве показано, как превратить существующий API в подключаемый модуль API Security Copilot.

Создание спецификации OpenAPI

Если у API уже есть спецификация OpenAPI, ее можно просто использовать. Разместите спецификацию OpenAPI https://[domain]/template.yaml.

Создайте файл манифеста подключаемого модуля со следующим содержимым (заменив OpenaApiSpecUrl значение URL-адресом файла спецификации OpenAPI, созданного в предыдущем разделе):

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

Проверка подлинности API

Поддерживаемые схемы

Security Copilot поддерживает несколько схем проверки подлинности подключаемых модулей:

Схема Описание Поддержка манифеста Copilot Поддержка OpenAI +
Нет Проверка подлинности не выполняется. Да Да
Обычный Обычная проверка подлинности. Да Нет
ApiKey Проверка подлинности на основе ApiKey, при которой разработчик предоставил ApiKey в пользовательском заголовке или параметре запроса. Да Да*
ServiceHttp Проверка подлинности на основе предоставленного маркера. Да Да
OAuthAuthorizationCodeFlow Поток кода авторизации OAuth 2.0 — это более безопасный и сложный метод проверки подлинности, используемый для предоставления доступа к приложениям сторонних корпораций без предоставления доступа к учетным данным пользователя. Да Да
OAuthClientCredentialsFlow Как и обычная проверка подлинности, но используется для обмена данными между серверами или при доступе к общедоступным данным, для которых не требуются разрешения пользователя. Да Нет
Microsoft Entra ID Доступ только к приложению. Да Да*
AADDelegated Доступ только для пользователей и приложений. Да Да*

+ Это поле используется для указания двух разных типов отправки, поддерживаемых в Security Copilot.

* Они представляют собой методы проверки подлинности, которые выходят за рамки первоначально поддерживаемых openAI.

В следующей таблице показаны поддерживаемые параметры для каждого типа проверки подлинности.

Тип проверки подлинности Setting Описание
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 Идентификатор клиента, используемый при запросе маркера.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow ClientSecret Секрет клиента, используемый при запросе маркера.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow AuthorizationContentType Тип контента, используемый при отправке запроса маркера.
OAuthAuthorizationCodeFlow AuthorizationEndpoint Конечная точка для запроса кода авторизации.

Предварительная настройка параметров проверки подлинности

Примечание

В настоящее время можно предварительно настроить параметры только для одного типа проверки подлинности.

Можно предварительно настроить параметры проверки подлинности для подключаемого модуля в тех случаях, когда одинаковые значения будут использоваться для каждого экземпляра подключаемого модуля (например, для набора областей Microsoft Entra). Предварительная настройка параметров обрабатывается путем заполнения поля Authorization в дескрипторе коллекцией пар "ключ-значение" и типом проверки подлинности.

В следующем примере показано, как указать набор областей Microsoft Entra по умолчанию для типа проверки подлинности AAD.

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

Подключаемый модуль API с обычной проверкой подлинности

В этом кратком руководстве показано, как создать подключаемый модуль, использующий обычную проверку подлинности HTTP.

Примечание

Настоятельно рекомендуется использовать обычную проверку подлинности только с конечными точками API, которые используют HTTPS.

Создание спецификации 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 для проверки подлинности. Вы можете завершить это сейчас или выбрать Сделать это позже, чтобы настроить его позже.

Снимок экрана: установка ключа API

Если вы выбрали параметр Сделать это позже, вы можете настроить имя пользователя и пароль позже, нажав кнопку Настроить на странице управление подключаемыми модулями.

Снимок экрана: параметр

Если вы хотите обновить параметры после настройки, это можно сделать, щелкнув значок параметров на странице подключаемых модулей управления.

Снимок экрана с настройками

Подключаемый модуль API с настраиваемым URL-адресом конечной точки

В этом примере добавляется настраиваемое имя параметров InstanceURL, которое пользователь может настроить с помощью Security Copilot. Затем в группе навыков 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

Подключаемый модуль API с OAuthAuthorizationCodeFlow

В этом кратком руководстве показано, как создать навык, который использует поток OAuthAuthorizationCodeFlow для проверки подлинности.

Создание манифеста подключаемого модуля

Создайте файл plugin.yaml манифеста подключаемого модуля со следующим содержимым и замените 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. Вы увидите уведомление о том, что учетная запись успешно связана.

    Изображение веб-браузера.

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