diff --git a/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/Readme.md b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/Readme.md new file mode 100644 index 00000000..b8d43afb --- /dev/null +++ b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/Readme.md @@ -0,0 +1,29 @@ +# Plugin to Resolve GUIDs to Microsoft Entra Service Principals (Enterprise Applications) + +## Overview +This plugin enables users to resolve GUIDs found in security alerts to their corresponding **Microsoft Entra service principal (Enterprise Application)** display names and identifiers using the **Microsoft Graph API**. When investigating alerts, the "Caller" or source fields often contain opaque GUIDs — this plugin translates them into human-readable application names, accelerating triage and incident response. It can also be used as a tool when building a **Security Copilot Custom Agent**. + +## Features +- Resolves a service principal by **Object ID** (the GUID commonly found in alert "Caller" fields). +- Resolves a service principal by **Application (Client) ID / appId** when the GUID represents the app registration rather than the service principal object. +- Returns key details including **display name, Object ID, appId, service principal type, account enabled status, and publisher name**. + +## API Endpoint +**Base URL:** `https://graph.microsoft.com/v1.0` + +### Setup Instructions +#### Upload the Plugin Manifest + +1. Obtain the manifest [sp guid resolver-plugin.yaml](https://github.com/Azure/Copilot-For-Security/blob/main/Plugins/Community%20Based%20Plugins/Microsoft%20Graph%20API%20plugins/GUID%20Resolution/sp%20guid%20resolver-plugin.yaml) and the OpenAPI Specification [sp guid resolver-plugin-spec.yaml](https://github.com/Azure/Copilot-For-Security/blob/main/Plugins/Community%20Based%20Plugins/Microsoft%20Graph%20API%20plugins/GUID%20Resolution/sp%20guid%20resolver-plugin-spec.yaml) files from this directory. +2. Download the Spec file and move it to your preferred location, ensuring it is reachable by Security Copilot. +3. [Upload the custom plugin](https://learn.microsoft.com/en-us/security-copilot/manage-plugins?tabs=securitycopilotplugin#add-custom-plugins) + +## Example Natural Language Queries +Use these sample prompts to retrieve relevant data via **Security Copilot**: +- "Resolve this caller GUID to the enterprise application name: 9cb7b82d-55cd-4265-b8a7-8899a7376e5c" +- "Get the service principal name for ObjectId 9cb7b82d-55cd-4265-b8a7-8899a7376e5c" +- "Resolve this appId GUID to the enterprise application name: a12e8ccb-0fcd-46f8-b6a1-000000000000" +- "Get the service principal name for appId a12e8ccb-0fcd-46f8-b6a1-000000000000" + +--- +For more details, visit the **[Microsoft Graph API documentation](https://learn.microsoft.com/en-us/graph/)**. diff --git a/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin-spec.yaml b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin-spec.yaml new file mode 100644 index 00000000..fd807730 --- /dev/null +++ b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin-spec.yaml @@ -0,0 +1,84 @@ +openapi: 3.0.0 +info: + title: Entra Service Principal GUID Resolver + version: 1.0.0 + description: > + Resolve a GUID from security alerts to the Microsoft Entra service principal (Enterprise Application) + display name and identifiers using Microsoft Graph. + +servers: + - url: https://graph.microsoft.com/v1.0 + +paths: + /servicePrincipals/{id}: + get: + operationId: GetServicePrincipalByObjectId + summary: Resolve a service principal by Object ID (Caller GUID) + description: > + Retrieves Microsoft Entra service principal (Enterprise Application) details using the service principal + Object ID. Use when an alert "Caller" field contains a GUID that is the enterprise application's Object ID. + #ExamplePrompts Resolve this caller GUID to the enterprise application name: 9cb7b82d-55cd-4265-b8a7-8899a7376e5c + #ExamplePrompts Get the service principal name for ObjectId 9cb7b82d-55cd-4265-b8a7-8899a7376e5c + parameters: + - name: id + in: path + required: true + description: Service principal Object ID (GUID) + schema: + type: string + responses: + "200": + description: Service principal found + content: + application/json: + schema: + $ref: "#/components/schemas/ServicePrincipal" + "404": + description: Not found + + "/servicePrincipals(appId='{appId}')": + get: + operationId: GetServicePrincipalByAppId + summary: Resolve a service principal by Application (Client) ID / appId + description: > + Retrieves Microsoft Entra service principal (Enterprise Application) details using the Application (Client) ID (appId). + Use when the GUID you have is the AppId rather than the service principal Object ID. + #ExamplePrompts Resolve this appId GUID to the enterprise application name: a12e8ccb-0fcd-46f8-b6a1-000000000000 + #ExamplePrompts Get the service principal name for appId a12e8ccb-0fcd-46f8-b6a1-000000000000 + parameters: + - name: appId + in: path + required: true + description: Application (Client) ID / appId (GUID) + schema: + type: string + responses: + "200": + description: Service principal found + content: + application/json: + schema: + $ref: "#/components/schemas/ServicePrincipal" + "404": + description: Not found + +components: + schemas: + ServicePrincipal: + type: object + properties: + id: + type: string + description: Service principal Object ID + appId: + type: string + description: Application (Client) ID + displayName: + type: string + description: Enterprise Application (service principal) display name + servicePrincipalType: + type: string + accountEnabled: + type: boolean + publisherName: + type: string \ No newline at end of file diff --git a/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin.yaml b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin.yaml new file mode 100644 index 00000000..48542832 --- /dev/null +++ b/Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin.yaml @@ -0,0 +1,13 @@ +Descriptor: + Name: EntraSpnGuidResolver + DisplayName: Entra SPN-App Resolver + Description: Resolves a GUID from alerts service principal ObjectId or appId) to Enterprise Application or service principal display name via Microsoft Graph. + SupportedAuthTypes: + - AADDelegated + Authorization: + Type: AADDelegated + EntraScopes: https://graph.microsoft.com/.default +SkillGroups: + - Format: API + Settings: + OpenApiSpecUrl: < url to your spec file> \ No newline at end of file