Microsoft
Building Graph API Custom Plugins for Copilot for Security
July 25, 2024 | 7 min read
Jaime Guimera Coll
Security Architect
![Jaime coll headshot 2 2x](/assets/imager/imagess3/Headshots/333486/jaime-coll-headshot-2@2x_d2448492f1f17e3bf43a2e2b9f1c45e4.png 100w, /assets/imager/imagess3/Headshots/333486/jaime-coll-headshot-2@2x_fc4267e5cc2c64c601bf2ad9abb5c180.png 200w)
As we explored the capabilities of Copilot for Security, we discovered that while the native plugins offer access to a vast array of data, they didn't cover everything we needed for some of our specific use cases and promptbooks. For instance, we wanted detailed insights into Conditional Access policies from Entra ID, Intune policies, Secure Score, and more. Although Microsoft continues to enhance the native plugins by adding new skills, we opted to develop our own custom plugins. By leveraging the integration with the Microsoft Graph API, we can immediately provide our customers with additional value and tailored solutions.
Microsoft Graph API and Microsoft Copilot for Security
Microsoft Graph API is a powerful tool that allows developers and system administrators to access a wide range of Microsoft 365 services and data. It provides a unified API endpoint to interact with various resources such as users, groups, mail, calendar events, and more. The API enables seamless integration and automation across Microsoft services, making it an essential tool for people looking to build robust applications.
Microsoft Copilot for Security is an advanced security management platform that leverages AI to enhance security operations. It integrates with various Microsoft security products and services to provide a comprehensive view of an organization's security posture and accelerate Security Operations. Some of the plugins included in Copilot for security use the Graph API with delegated access allowing the user to query data from multiple platforms within the Microsoft ecosystem. The available plugins include integration with Entra, Defender, Sentinel, Purview and Intune, for example. One of the platform's key features is its ability to support custom plugins, which allows organizations to extend copilot capabilities by integrating additional functionalities, such as those provided by Microsoft Graph API.
You can find more about Copilot for Security in our blog series and our best practices report. If you really want to understand all the pieces and components take a look at our Copilot for Security Design blog post.
Creating Custom Plugins in Microsoft Copilot for Security
Creating custom plugins in Microsoft Copilot for Security involves several steps:
Define Plugin Descriptor:
- The descriptor outlines the plugin's name, display name, description, and authorization type.
- Required scopes: Graph API, Azure Management
Define the Skill Group:
- In the descriptor you must add a link to the OpenAPI specification file.
- This OpenAPI specification must include all the Skills with its corresponding endpoint and endpoint parameters.
Deploy and Test the Plugin:
- Deploy the plugin to the Copilot for Security platform.
- Test the plugin to ensure it works as expected and can interact with the required Graph API endpoints.
For more details about developing and deploying plugins you can go the official Microsoft documentation and community posts:
Creating Graph API Plugins for Microsoft Copilot for Security
There are some things that need explanation before the development of the plugin.
Azure Access Model
In Azure, access management can be handled through delegated access and application access using Service Principal Names (SPNs), each serving distinct purposes. Delegated access allows an application to act on behalf of a user, inheriting the user's permissions and performing actions within the user's context. It's ideal for scenarios where user-specific data or actions are required, such as a web application retrieving a user's email from Microsoft Graph API.
On the other hand, application access using SPNs enables an application to access resources independently of any user, with permissions assigned directly to the application's service principal. It's suited for background services, automated processes, or any application that needs to perform tasks without user intervention, like a background service syncing data between systems.
Understanding these differences is crucial for implementing secure and efficient access management in Azure, ensuring that applications have the right level of access based on their operational context.
Scope Limitations
For this type of plugins we will use Delegated access model (AADDelegated authorization), so we first need to understand how it works and its current limitations.
In the descriptor of a Graph API plugin we need to specify the Authorization type as AADDelegated and the Entra ID Scope(s) that the plugin will request access for. We can limit the scope to specific permissions (i.e. User.Read.All, Group.Read.All or Policy.Read.All) or we can use the GraphAPI Default Scope. You can find additional information in the official learn page.
Sample Descriptor Authorization Section:
Authorization:
Type: AADDelegated
EntraScopes: https://graph.microsoft.com/.default
However, there are limitations in the Scopes you can use in the plugins. This limitation comes from how the Graph API access token is generated. Under the hood, Copilot for Security is using its own Entra ID Enterprise Application (Medeina Service, Client ID: bb3d68c2-d09e-4455-94a0-e323996dbaa3) to make the call to the GraphAPI on behalf of the user. This application lives in every tenant where Copilot for Security has been enabled and it is owned by Microsoft.
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/Asset-2.png)
The permissions this application has currently authorized to use on behalf of the user are listed below:
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/accessreview3.png)
So, these are the permissions we can use in our custom Graph API plugins. To get this list of permissions you can review the Scopes field in your MicrosoftGraphActivityLogs table in Sentinel/LogAnalytics using the following query:
MicrosoftGraphActivityLogs
| where UserAgent == "MicrosoftCopilotforSecurity.DirectorySkillDispatcher`1/0.1.0.0"
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/activity-logs-2.png)
We could potentially try to use an Entra Scope outside this list, for example Mail.Read to be able to fetch email content (interesting for Phishing analysis) inside Copilot for Security. To do that we can change the EntraScopes property of our plugin to request this permission like this:
Authorization:
Type: AADDelegated
EntraScopes: https://graph.microsoft.com/Mail.Read
However, using this EntraScopes will make the plugin fail when triggering any skill. Looking at the API logs we can see this error message (it is not shown in the UI):
AADSTS65002: Consent between first party application 'bb3d68c2-d09e-4455-94a0-e323996dbaa3' and first party resource '00000003-0000-0000-c000-000000000000' must be configured via preauthorization - applications owned and operated by Microsoft must get approval from the API owner before requesting tokens for that API
This indicates that the Copilot Application is managed by Microsoft, and additional permissions need to be preauthorized by Microsoft. Unfortunately, this means that you cannot modify the permissions for the Copilot Application yourself and that Microsoft would need to add other permissions to Medeina (CfS) application to allow additional access from the plugins.
Define the Plugin Descriptor
So now that we understand the limitations of the platform and the available permissions, we can decide what kind of things our GraphAPI plugin is going to do.
The plugin descriptor should be simple. Below you can find an example:
The OpenAPI specification must be publicly accessible and can reference any GraphAPI endpoint that is allowed by the permissions specified above. You can see all the available endpoints here.
To test the endpoints you can use Microsoft Graph Explorer.
One tip to speed up the creation of these specs is to use Copilot for Security to create it. You can leverage the Fetch Public Web plugin to feed the official endpoint website and ask Copilot to create the OpenAPI spec for you.
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/openai-2.png)
Below you can find a simplified sample spec based on the Copilot answer above for Conditional Access Policies endpoint. This spec will allow us to retrieve the available conditional access policies and ask questions about them:
You can see the whole code of this example in our public GitHub repo.
Deploy and Test the Plugin
Once the OpenAPI spec is uploaded to a public site you can import the plugin into Copilot for Security. Learn more about the upload process for custom plugins.
After the plugin is uploaded you can start using it by using the right prompts. You can see some examples in the screenshots below:
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/1.png)
![](https://s3.us-east-2.amazonaws.com/bluevoyant.com/prod/images/Blogs/2.png)
Conclusion
Creating custom plugins for Microsoft Copilot for Security using the Microsoft Graph API can significantly enhance the platform's capabilities. However, it's essential to be aware of the scope limitations. By following the outlined steps and understanding the constraints, you can successfully develop and deploy Graph API plugins that meet your organization's security needs.
Related Reading
Company News
BlueVoyant Awarded Microsoft Worldwide Security Partner of the Year, Recognizing Leading-Edge Cyber Defense
June 27, 2024 | 2 min read
Microsoft
Microsoft Copilot for Security – Use Cases for Cloud Security and DevSecOps Teams
April 15, 2024 | 5 min read