From 6a4e1d8d6fc29b29342e2e6235b0447877b4f058 Mon Sep 17 00:00:00 2001 From: Innocent Wafula Date: Sat, 7 Mar 2026 17:13:52 -0500 Subject: [PATCH] Add Entra Service Principal GUID Resolver plugin Adds a new community plugin that resolves GUIDs from security alerts to Microsoft Entra service principal (Enterprise Application) display names via Microsoft Graph API. Supports lookup by Object ID and Application (Client) ID / appId. Can also be used as a tool when building a Security Copilot Custom Agent. --- .../GUID Resolution/Readme.md | 29 +++++++ .../sp guid resolver-plugin-spec.yaml | 84 +++++++++++++++++++ .../sp guid resolver-plugin.yaml | 13 +++ 3 files changed, 126 insertions(+) create mode 100644 Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/Readme.md create mode 100644 Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin-spec.yaml create mode 100644 Plugins/Community Based Plugins/Microsoft Graph API plugins/GUID Resolution/sp guid resolver-plugin.yaml 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