Main

Plugins/Community Based Plugins/Microsoft Graph API plugins/Devices Onboarded into MDE/MDEOnboardedDevices-OpenAPISpec.yaml

@@ -0,0 +1,101 @@
+openapi: 3.0.0
+
+# This section provides metadata about the plugin, including its title, description, and version.
+info:
+  title: Retrieve devices onboarded into Microsoft Defender for Endpoint (MDE)
+  description: Plugin to retrieve a list of devices onboarded into Microsoft Defender for Endpoint (MDE) using Microsoft Graph API.
+  version: 1.0.0
+
+# Defines the base URL for the Microsoft Graph API, which is used to make requests.
+servers:
+  - url: https://graph.microsoft.com/v1.0
+    description: Microsoft Graph API url
+
+# Specifies the available API endpoints and their operations, in this case, retrieving a list of devices.
+paths:
+  /devices:
+    get:
+      summary: Get devices
+      description: Retrieve a list of devices onboarded into Microsoft Defender for Endpoint 
+      responses:
+        '200':
+          description: List of devices
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  value:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          description: Device ID.
+                        deviceName:
+                          type: string
+                          description: Name of the device.
+                        osPlatform:
+                          type: string
+                          description: Operating system of the device.
+                        complianceState:
+                          type: string
+                          description: Compliance state of the device.
+                        lastSeenDateTime:
+                          type: string
+                          format: date-time
+                          description: Last seen date and time.
+                        onboardedDate:
+                          type: string
+                          format: date
+                          description: Date the device was onboarded.
+                        manufacturer:
+                          type: string
+                          description: Manufacturer of the device.
+                        model:
+                          type: string
+                          description: Model of the device.
+                        serialNumber:
+                          type: string
+                          description: Serial number of the device.
+                        macAddress:
+                          type: string
+                          description: MAC address of the device.
+                        ipAddress:
+                          type: string
+                          description: IP address of the device.
+                        isAzureAdJoined:
+                          type: boolean
+                          description: Indicates if the device is Azure AD joined.
+                        isCompliant:
+                          type: boolean
+                          description: Indicates if the device is compliant.
+                        riskLevel:
+                          type: string
+                          description: Risk level assigned to the device.
+        '401':
+          description: Unauthorized error.
+        '403':
+          description: Forbidden access.
+        '500':
+          description: Internal server error.
+
+# Defines security mechanisms, such as authentication methods, that the API uses.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+
+security:
+  - bearerAuth: []
+
+# Provides example natural language queries that users can use to interact with the API via Security Copilot and retrieve specific device information.
+x-example-prompts:
+  - Retrieve devices onboarded to MDE that have a compliance state of 'Non-compliant'
+  - Get the list of non-compliant devices from devices onboarded to MDE
+  - retrieve a list of devices onboarded onto MDE that have a Risk Level of "High"
+  - Retrieve devices from MDE that registered less than 14 days ago from today
+  - Retrieve a list of MDE endpoints that were last seen less than 1 day ago
+  - Get devices from MDE that have the IoS operating system

Plugins/Community Based Plugins/Microsoft Graph API plugins/Devices Onboarded into MDE/MDEOnboardedDevicesPlugin.yaml

@@ -0,0 +1,12 @@
+Descriptor:   
+  Name: RetriveMDEOnboardedDevices   
+  DisplayName: Retrive details for devices onboarded onto Microsoft Defender for Endpoint (MDE)   
+  Description: Retrive details for devices onboarded onto Microsoft Defender for Endpoint (MDE)
+  DescriptionForModel: Retrive details about devices or endpoints onboarded onto Microsoft Defender for Endpoint (MDE) including details such as DeviceID, DeviceName, OSPlatform, ComplianceState, LastSeenDateTime, OnboardedDate, Manufacturer, Model, SerialNumber. 
+  Authorization:   
+    Type: AADDelegated   
+    EntraScopes: https://graph.microsoft.com/.default   
+SkillGroups:   
+  - Format: API   
+    Settings:   
+      OpenApiSpecUrl: https://raw.githubusercontent.com/inwafula/inwafula/refs/heads/main/MDE%20OnboardedDevices.yaml

Plugins/Community Based Plugins/Microsoft Graph API plugins/Devices Onboarded into MDE/Readme.md

@@ -0,0 +1,36 @@
+# Plugin to retrieve Devices Onboarded into Microsoft Defender for Endpoint (MDE) Plugin
+
+## Overview
+This plugin enables users to retrieve a list of devices onboarded into **Microsoft Defender for Endpoint (MDE)** using the **Microsoft Graph API**. It provides valuable insights into device details, compliance status, risk levels, and more, facilitating security monitoring and incident response.
+
+## Features
+- Retrieves device details including **device name, OS, manufacturer, model, serial number, and MAC address**.
+- Identifies **compliance state** and **risk level** of onboarded devices.
+- Fetches devices based on **last seen date** 
+- Supports filtering for devices based on **Azure AD join status, compliance status, and OS platform**.
+
+## API Endpoint
+**Base URL:** `https://graph.microsoft.com/v1.0`
+
+
+### Setup instructions
+#### Upload the Plugin manifest
+
+1. Obtain the manifest  [MDEOnboardedDevicesPlugin.yaml](https://github.com/Azure/Copilot-For-Security/blob/main/Plugins/Community%20Based%20Plugins/Microsoft%20Graph%20API%20/Devices%20Onboarded%20into%20MDE/MDEOnboardedDevicesPlugin.yaml) and the OpenAPI Specification [MDEOnboardedDevices-OpenAPISpec.yaml](https://github.com/Azure/Copilot-For-Security/blob/main/Plugins/Community%20Based%20Plugins/Microsoft%20Graph%20API%20/Devices%20Onboarded%20into%20MDE/MDEOnboardedDevices-OpenAPISpec.yaml) files from this directory.
+2. Download the Git Hub gist file and move it to your prefered location, ensuring it is reachable by Securty  Copilot 
+
+
+3. [Upload the custom plugin](https://learn.microsoft.com/en-us/security-copilot/manage-plugins?tabs=securitycopilotplugin#add-custom-plugins) and enter your Tenant ID, Subscription ID, Workspace name, Resource group that hosts your Sentinel worksapce in the resulting dialog box.  Verify that the plugin is activated.
+
+## Example Natural Language Queries
+Use these sample prompts to retrieve relevant data via **Security Copilot**:
+- "Retrieve devices onboarded to MDE that have a compliance state of 'Non-compliant'"
+- "Get the list of non-compliant devices from devices onboarded to MDE"
+- "Retrieve a list of devices onboarded onto MDE that have a Risk Level of 'High'"
+- "Retrieve devices from MDE that registered less than 14 days ago from today"
+- "Retrieve a list of MDE endpoints that were last seen less than 1 day ago"
+- "Get devices from MDE that have the iOS operating system"
+
+
+---
+For more details, visit the **[Microsoft Graph API documentation](https://learn.microsoft.com/en-us/graph/)**.