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

2024-12-12

Создание подключаемого модуля API из существующего файла спецификации OpenAI

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

В этом упражнении используется этот файл https://hacktrack.routum.io/.well-known/ai-plugin.json манифеста: .

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

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

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

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

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

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

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

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

Настроить аутентификацию

Предупреждение

НЕ вводите существующий ключ 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.

Настройка проверки подлинности

Войдите в Microsoft Security Copilot.
Прокрутите вниз до пункта Пользовательский и выберите Настройка.
Введите секрет клиента и нажмите кнопку Подключить.
Вы увидите уведомление о том, что учетная запись успешно связана.
Настройка завершена.

Теперь подключаемый модуль должен быть включен.

Если при нажатии кнопки Подключиться отображается сообщение об ошибке, выполните следующие действия для устранения ошибки: Изображение сообщения об ошибке.

Добавьте следующий URI обратного вызова (https://securitycopilot.microsoft.com/auth/v1/callback), как показано на следующем рисунке, и попробуйте повторно подключиться.

Изображение страницы проверки подлинности.

Ограничения

Команды HTTP, которые обычно разрешают изменения состояния и операции записи (например, POST), можно использовать только для получения данных. Операции записи в настоящее время не поддерживаются.
Схема текста запроса должна быть ограничена глубиной до 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"
    ]
}
```

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

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

Создание подключаемого модуля API из существующего файла спецификации OpenAI

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

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

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

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

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

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

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

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

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

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

Настройка проверки подлинности

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

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

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

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

Настроить аутентификацию

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

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

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

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

Настройка проверки подлинности

Ограничения

Дополнительные ресурсы