API-Plug-Ins in Microsoft Security Copilot
In diesem Schnellstarttutorial erfahren Sie, wie Sie ein vorhandenes OpenAI-Plug-In in Security Copilot verwenden.
In dieser Übung wird diese Manifestdatei verwendet.
Melden Sie sich bei Microsoft Security Copilot an.
Greifen Sie auf "Plug-Ins verwalten" zu, indem Sie in der Eingabeaufforderungsleiste auf die Schaltfläche Plug-Ins klicken.
Scrollen Sie nach unten zu Benutzerdefiniert, und wählen Sie Plug-In hinzufügen aus.
Wählen Sie OpenAI-Plug-In als Uploadformat aus, geben Sie
https://hacktrack.routum.io/.well-known/ai-plugin.json
als Link ein, und wählen Sie Hinzufügen aus.
In diesem Schnellstarttutorial erfahren Sie, wie Sie eine vorhandene API in ein Security Copilot-API-Plug-In umwandeln.
Wenn die API bereits über eine OpenAPI-Spezifikation verfügt, können Sie diese einfach verwenden. Hosten Sie die OpenAPI-Spezifikation https://[Domäne]/template.yaml.
Erstellen Sie eine neue Plug-In-Manifestdatei mit folgendem Inhalt (ersetzen Sie den OpenaApiSpecUrl
-Wert durch die URL zur OpenAPI-Spezifikationsdatei, die sie im vorherigen Abschnitt erstellt hat):
Descriptor:
Name:
DisplayName:
Description:
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://[domain]/template.yaml
Security Copilot unterstützt mehrere Schemata für die Authentifizierung von Plug-Ins:
Schema | Beschreibung | Copilot-Manifestunterstützung | OpenAI-Unterstützung + |
---|---|---|---|
Keine | Keine Authentifizierung. | Ja | Ja |
Standard | Standardauthentifizierung. | Ja | Nein |
ApiKey | ApiKey-basierte Authentifizierung, bei der von einem Entwickler bereitgestellter ApiKey in einem benutzerdefinierten Header oder Abfrageparameter übergeben wird. | Ja | Ja* |
ServiceHttp | Authentifizierung basierend auf dem bereitgestellten Token. | Ja | Ja |
OAuthAuthorizationCodeFlow | Der OAuth 2.0-Autorisierungscodeflow ist eine sicherere und komplexere Authentifizierungsmethode, die verwendet wird, um Zugriff auf Nicht-Microsoft-Anwendungen zu gewähren, ohne Benutzeranmeldeinformationen freizugeben. | Ja | Ja |
OAuthClientCredentialsFlow | Wie die Standardauthentifizierung, wird aber stattdessen für die Server-zu-Server-Kommunikation oder beim Zugriff auf öffentliche Daten verwendet, für die keine benutzerspezifischen Berechtigungen erforderlich sind. | Ja | Nein |
Microsoft Entra-ID | Nur Anwendungszugriff. | Ja | Ja* |
AADDelegated | Nur Benutzer- und Anwendungszugriff. | Ja | Ja* |
+ Dieses Feld wird verwendet, um die beiden verschiedenen Uploadtypen anzugeben, die in Security Copilot unterstützt werden.
* Diese stellen Authentifizierungsmethoden dar, die über das hinaus erweitert werden, was ursprünglich von openAI unterstützt wurde.
Die folgende Tabelle zeigt die unterstützten Einstellungen für jeden Authentifizierungstyp.
Authentifizierungstyp | Einstellung | Beschreibung |
---|---|---|
AAD oder AADDelegated |
EntraScopes |
Eine durch Trennzeichen getrennte Liste von Microsoft Entra bereichen, die anzufordern sind. |
Basic |
Username |
Der Benutzername, der für die Standardauthentifizierung verwendet werden soll. |
Basic |
Password |
Das Kennwort, das für die Standardauthentifizierung verwendet werden soll. |
ApiKey oder ServiceHttp |
Key |
Der Name des Header-/Abfrageparameters. |
ApiKey oder ServiceHttp |
AuthScheme |
Der Name des Authentifizierungsschemas, das dem Value vorangestellt wird, wenn es in einem Header verwendet wird. |
ApiKey oder ServiceHttp |
Location |
Der Speicherort des API-Schlüssels, entweder Header oder QueryParams . |
ApiKey oder ServiceHttp |
Value |
Der zu verwendende Schlüssel/Token. |
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow |
TokenEndpoint |
Der Endpunkt, von dem das Token angefordert werden soll. |
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow |
Scopes |
Eine durch Trennzeichen getrennte Liste von Bereichen, die anzufordern sind. |
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow |
ClientId |
Die Client-ID, die beim Anfordern des Tokens verwendet werden soll. |
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow |
ClientSecret |
Der geheime Clientschlüssel, der beim Anfordern des Tokens verwendet werden soll. |
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow |
AuthorizationContentType |
Der Inhaltstyp, der beim Senden der Tokenanforderung verwendet wird. |
OAuthAuthorizationCodeFlow |
AuthorizationEndpoint |
Der Endpunkt, von dem der Autorisierungscode anzufordern ist. |
Hinweis
Es ist derzeit nur möglich, Einstellungen für einen Authentifizierungstyp vorzukonfigurieren.
Es ist möglich, Authentifizierungseinstellungen für Ihr Plug-In vorkonfigurieren, wenn die gleichen Werte für jede Instanz Ihres Plug-Ins verwendet werden (z. B. für den Satz von Microsoft Entra-Bereichen). Die Vorkonfiguration der Einstellungen erfolgt durch Auffüllen des Authorization
-Felds im Deskriptor mit einer Auflistung von Schlüssel-Wert-Paaren zusammen mit dem Authentifizierungstyp.
Das folgende Beispiel zeigt, wie Sie einen Standardsatz von Microsoft Entra-Bereichen für den AAD
-Authentifizierungstyp angeben.
Descriptor:
Name: SampleAPI
Description: Sample API
SupportedAuthTypes:
- AAD
Authorization:
Type: AAD
EntraScopes: https://graph.microsoft.com/.default
In diesem Schnellstarttutorial erfahren Sie, wie Sie ein Plug-In erstellen, das die HTTP-Standardauthentifizierung verwendet.
Hinweis
Es wird dringend empfohlen, die Standardauthentifizierung nur mit APIs-Endpunkten zu verwenden, die HTTPS verwenden.
In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die Standardauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation, aber beispielsweise verwenden wir nur einen der Vorgänge.
Erstellen Sie eine neue Datei mit den folgenden Inhalten, und laden Sie sie an einem öffentlich zugänglichen Ort hoch. In diesem Tutorial wurde GitHub Gist verwendet, um einen neuen Gist mit dem Inhalt auf https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml zu erstellen
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.
In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die Standardauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation.
Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml
mit folgendem Inhalt:
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
Befolgen Sie die Anweisungen in Verwalten von Plug-Ins, um das Plug-In-Manifest in Security Copilot hochzuladen.
Warnung
Geben Sie bei der Einrichtung dieses Beispiels KEINEN bestehenden Benutzernamen und kein bestehendes Passwort ein. Die Anmeldeinformationen werden nicht überprüft, sodass alle Werte akzeptiert werden.
Geben Sie nach dem Hochladen des Plug-Ins den Benutzernamen und das Kennwort für die Standardauthentifizierung ein. Sie können den Schritt entweder jetzt abschließen oder Später tun auswählen, um ihn später zu konfigurieren.
Wenn Sie die Option Später tun ausgewählt haben, können Sie den Benutzernamen und das Kennwort später konfigurieren, indem Sie auf der Seite "Plug-Ins verwalten" die Schaltfläche Einrichten auswählen.
Wenn Sie die Einstellungen nach der Konfiguration aktualisieren möchten, können Sie dies tun, indem Sie auf der Seite mit den Verwaltungs-Plug-Ins auf das Einstellungssymbol klicken.
In diesem Schnellstarttutorial erfahren Sie, wie Sie ein Plug-In erstellen, das einen API-Schlüssel für die Authentifizierung verwendet. Bei der API-Schlüsselauthentifizierung wird ein geheimer(s) Schlüssel/Token verwendet, der als Teil der Anforderung entweder als Abfragezeichenfolgenparameter oder als Header übergeben wird. Der API-Schlüssel wird zum Authentifizieren der Anforderung verwendet und ist nicht an einen bestimmten Benutzer gebunden.
In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die API-Schlüsselauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation, aber beispielsweise verwenden wir nur einen der Vorgänge.
Erstellen Sie eine neue Datei mit den folgenden Inhalten, und laden Sie sie an einem öffentlich zugänglichen Ort hoch. In diesem Tutorial wurde GitHub Gist verwendet, um einen neuen Gist mit dem Inhalt auf https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml zu erstellen
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.
In diesem Beispiel konfigurieren wir das Plug-In so, dass der API-Schlüssel mithilfe eines x-test-api-key
Headers gesendet wird. Wir konfigurieren den Speicherort des Schlüssels vor, erfordern jedoch, dass der Benutzer bei der Installation des Plug-Ins den Schlüsselwert eingibt.
Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml
mit folgendem Inhalt:
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
Befolgen Sie die Anweisungen in Verwalten von Plug-Ins, um das Plug-In-Manifest in Security Copilot hochzuladen.
Warnung
Geben Sie bei der Einrichtung dieses Beispiels KEINEN bestehenden API-Schlüssel ein. Der API-Schlüssel wird nicht überprüft, sodass alle Werte akzeptiert werden.
Nach dem Hochladen des Plug-Ins werden Sie aufgefordert, den API-Schlüssel für die Authentifizierung einzugeben. Sie können den Schritt entweder jetzt abschließen oder Später tun auswählen, um ihn später zu konfigurieren.
Wenn Sie die Option Später tun ausgewählt haben, können Sie den Benutzernamen und das Kennwort später konfigurieren, indem Sie auf der Seite "Plug-Ins verwalten" die Schaltfläche Einrichten auswählen.
Wenn Sie die Einstellungen nach der Konfiguration aktualisieren möchten, können Sie dies tun, indem Sie auf der Seite mit den Verwaltungs-Plug-Ins auf das Einstellungssymbol klicken.
In diesem Beispiel wird der konfigurierbare Einstellungsname "InstanceURL" hinzugefügt, den der Benutzer über Security Copilot konfigurieren kann. Anschließend wird unter der API-Qualifikationsgruppe eine Einstellung hinzugefügt, die Security Copilot anweist, den Wert der Einstellung "InstanceURL" als Endpunkt für die API-Anforderungen zu verwenden:
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
Das folgende Beispiel zeigt die Verwendung einer anpassbaren Endpunkt-URL mit einem API-Schlüssel:
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
In diesem Schnellstarttutorial erfahren Sie, wie Sie eine Fähigkeit erstellen, die den OAuthAuthorizationCodeFlow-Fluss für die Authentifizierung verwendet.
Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml
mit dem folgenden Inhalt, und ersetzen Sie die OpenApiSpecUrl
Werte und EndpointUrl
aus Ihrer Web-App.
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
Befolgen Sie die Anweisungen hier, um das Plug-In-Manifest in Security Copilot hochzuladen.
Melden Sie sich bei Microsoft Security Copilot an.
Scrollen Sie nach unten zu Benutzerdefiniert, und wählen Sie Setup aus.
Geben Sie den geheimen Clientschlüssel ein, und wählen Sie Verbinden aus.
Es wird eine Benachrichtigung angezeigt, dass das Konto erfolgreich verknüpft wurde.
Das Setup ist abgeschlossen.
Das Plug-In sollte jetzt aktiviert sein.
Wenn beim Auswählen von Verbinden eine Fehlermeldung angezeigt wird, führen Sie die folgenden Schritte aus, um den Fehler zu beheben:
Fügen Sie den folgenden Rückruf-URI (https://securitycopilot.microsoft.com/auth/v1/callback) hinzu, wie in der folgenden Abbildung dargestellt, und versuchen Sie, die Verbindung wiederherzustellen.
HTTP-Verben, die in der Regel Zustandsänderungen und Schreibvorgänge zulassen (z. B. POST), können nur für Datenabrufzwecke verwendet werden. Schreibvorgänge werden derzeit nicht unterstützt.
Anforderungstextschemas müssen auf eine Tiefe von 1 beschränkt sein. Dies bedeutet, dass das übergeordnete Objekt keine geschachtelten Objekte in sich selbst enthalten kann. Ein Verstoß gegen diese Tiefeneinschränkung führt zu einem Fehler mit Code 2006.
2.1 Im Folgenden finden Sie ein Beispiel für den Anforderungstext mit der Tiefe = 1:
{ "id": "UserID", "name": "Alex Wilber", "email": "AlexW@contoso.com", "isActive": true }
2.2 Der folgende Beispielanforderungstext wird nicht akzeptiert, da die Tiefe größer als 1 ist:
{ "productId": 123456, "name": "Widget", "price": 9.99, "manufacturer": { "name" :"Tailspin Toys", "address": { "street" : "123 Anystreet", "city" : "Redmond", "zipcode": "98005" } }, "tags": [ "Holiday2024", "Popular" ] }