Skip to content

Control 4.13: Copilot Extensibility and Agent Operations Governance — PowerShell Setup

Automation scripts for managing Copilot plugins, connectors, and related extensibility governance.

Tenant verification required: Microsoft 365 agent, tool, and audit APIs continue to evolve. Treat the scripts below as supplemental evidence collection; current portal evidence from Agents > Overview, All agents > Registry, Settings, Tools, and Settings > Integrated apps remains required.

Prerequisites

  • Modules: Microsoft.Graph, ExchangeOnlineManagement
  • Permissions: Application Administrator, Entra Global Admin
  • PowerShell: Version 7.x recommended

Connect to Required Services

Import-Module Microsoft.Graph
Connect-MgGraph -Scopes "Application.Read.All", "AppCatalog.ReadWrite.All", "AuditLog.Read.All"

Scripts

Script 1: Copilot Plugin and App Inventory

# Generate an inventory of all apps and plugins available to Copilot
$apps = Get-MgServicePrincipal -All | Where-Object {
    $_.Tags -contains "CopilotExtension" -or
    $_.Tags -contains "TeamsApp" -or
    $_.AppDisplayName -like "*Copilot*"
}

$inventory = $apps | ForEach-Object {
    [PSCustomObject]@{
        AppName        = $_.AppDisplayName
        AppId          = $_.AppId
        Publisher      = $_.PublisherName
        CreatedDate    = $_.CreatedDateTime
        Permissions    = ($_.Oauth2PermissionScopes | Select-Object -First 3 -ExpandProperty Value) -join ", "
        ConsentType    = if ($_.AppOwnerOrganizationId -eq $null) { "Microsoft" } else { "Third-Party" }
    }
}

Write-Host "Copilot Plugin and App Inventory:" -ForegroundColor Cyan
$inventory | Format-Table AppName, Publisher, ConsentType -AutoSize
$inventory | Export-Csv "CopilotPluginInventory_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation
Write-Host "Total plugins: $($inventory.Count)" -ForegroundColor Green

Script 2: Graph Connector Inventory and Risk Assessment

# Inventory Graph connectors and assess data sensitivity
$connectors = Invoke-MgGraphRequest -Method GET `
    -Uri "https://graph.microsoft.com/v1.0/external/connections" `
    -OutputType PSObject

if ($connectors.value) {
    $connectorReport = $connectors.value | ForEach-Object {
        [PSCustomObject]@{
            ConnectorName  = $_.name
            ConnectorId    = $_.id
            State          = $_.state
            Description    = $_.description
        }
    }

    Write-Host "Graph Connector Inventory:" -ForegroundColor Cyan
    $connectorReport | Format-Table -AutoSize
    $connectorReport | Export-Csv "GraphConnectors_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation
} else {
    Write-Host "No Graph connectors configured" -ForegroundColor Yellow
}
# Audit app consent and permissions for Copilot-related applications
$appConsents = Get-MgOauth2PermissionGrant -All | Where-Object {
    $_.ConsentType -eq "AllPrincipals"
}

$consentReport = foreach ($consent in $appConsents) {
    $sp = Get-MgServicePrincipal -ServicePrincipalId $consent.ClientId -ErrorAction SilentlyContinue
    if ($sp) {
        [PSCustomObject]@{
            AppName       = $sp.AppDisplayName
            ConsentType   = $consent.ConsentType
            Scope         = $consent.Scope
            ResourceId    = $consent.ResourceId
            GrantedDate   = $consent.StartDateTime
        }
    }
}

Write-Host "Organization-Wide App Consent Audit:" -ForegroundColor Cyan
$consentReport | Where-Object { $_.Scope -like "*ReadWrite*" -or $_.Scope -like "*FullControl*" } |
    Format-Table AppName, Scope, GrantedDate -AutoSize

$highRisk = $consentReport | Where-Object { $_.Scope -like "*ReadWrite*" -or $_.Scope -like "*FullControl*" }
if ($highRisk) {
    Write-Warning "$($highRisk.Count) apps have broad read-write or full control permissions"
}

$consentReport | Export-Csv "AppConsentAudit_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation

Script 4: Microsoft 365 Copilot Plugin and Agent Interaction Evidence

# Monitor Microsoft 365 Copilot interaction records and summarize plugin evidence.
# CopilotInteraction spans multiple Microsoft Copilot products, so use an
# AppIdentity allow-list and exclude Security Copilot from the evidence set.
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName admin@contoso.com -ShowBanner:$false

# Populate exact values from the approved agent and plugin inventory.
# Microsoft documents values such as Copilot.MicrosoftCopilot.BizChat and
# Copilot.Studio.<app-id>; do not add Copilot.Security.SecurityCopilot.
$approvedAppIdentities = @(
    # "Copilot.MicrosoftCopilot.BizChat"
    # "Copilot.Studio.<approved-app-id>"
)
$approvedPluginIds = @(
    # "<approved-plugin-id>"
)

if ($approvedAppIdentities.Count -eq 0 -or $approvedPluginIds.Count -eq 0) {
    throw "Populate the approved AppIdentity and plugin ID allow-lists before collecting evidence."
}

function Get-PagedCopilotAuditRecord {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [datetime]$StartDate,

        [Parameter(Mandatory)]
        [datetime]$EndDate,

        [timespan]$SegmentDuration = [timespan]::FromHours(1)
    )

    if ($EndDate -le $StartDate) {
        throw "EndDate must be later than StartDate."
    }
    if ($SegmentDuration -le [timespan]::Zero) {
        throw "SegmentDuration must be greater than zero."
    }

    $records = [System.Collections.Generic.List[object]]::new()
    $seenRecordIds = [System.Collections.Generic.HashSet[string]]::new(
        [System.StringComparer]::OrdinalIgnoreCase
    )

    for ($segmentStart = $StartDate; $segmentStart -lt $EndDate; $segmentStart = $segmentEnd) {
        $segmentEnd = $segmentStart.Add($SegmentDuration)
        if ($segmentEnd -gt $EndDate) {
            $segmentEnd = $EndDate
        }

        $sessionId = "CopilotPluginEvidence_$([guid]::NewGuid())"
        $pageNumber = 0
        $previousResultIndex = -1L
        $segmentResultCount = 0
        $segmentExhausted = $false

        do {
            $pageNumber++
            if ($pageNumber -gt 100) {
                throw "Paging safety limit reached for $segmentStart to $segmentEnd."
            }

            try {
                $page = @(
                    Search-UnifiedAuditLog `
                        -StartDate $segmentStart `
                        -EndDate $segmentEnd `
                        -RecordType CopilotInteraction `
                        -Operations "CopilotInteraction" `
                        -SessionId $sessionId `
                        -SessionCommand ReturnLargeSet `
                        -ResultSize 5000 `
                        -ErrorAction Stop
                )
            }
            catch {
                throw (
                    "Search-UnifiedAuditLog failed for segment $segmentStart to " +
                    "$segmentEnd on page $pageNumber (SessionId $sessionId). " +
                    "No evidence from this run should be treated as complete. " +
                    "Underlying error: $($_.Exception.Message)"
                )
            }

            if ($page.Count -eq 0) {
                $segmentExhausted = $true
                break
            }

            $segmentResultCount += $page.Count
            $newRecordCount = 0

            foreach ($record in $page) {
                $auditData = $record.AuditData | ConvertFrom-Json
                $recordId = [string]$auditData.Id
                if ([string]::IsNullOrWhiteSpace($recordId)) {
                    throw "An audit record is missing AuditData.Id; safe deduplication is not possible."
                }

                if ($seenRecordIds.Add($recordId)) {
                    $records.Add(
                        [PSCustomObject]@{
                            Record    = $record
                            AuditData = $auditData
                        }
                    )
                    $newRecordCount++
                }
            }

            $lastResult = $page[-1]
            $hasResultIndex = $null -ne $lastResult.ResultIndex -and
                -not [string]::IsNullOrWhiteSpace([string]$lastResult.ResultIndex)
            $hasResultCount = $null -ne $lastResult.ResultCount -and
                -not [string]::IsNullOrWhiteSpace([string]$lastResult.ResultCount)

            if ($hasResultIndex) {
                $resultIndex = [long]$lastResult.ResultIndex
                if ($resultIndex -le $previousResultIndex -and $newRecordCount -eq 0) {
                    throw "Audit paging made no progress for $segmentStart to $segmentEnd."
                }
                $previousResultIndex = $resultIndex
            }

            $moreRecordsProperty = $lastResult.AuditSearchRequestMetadata.PSObject.Properties[
                "moreRecordsAvailable"
            ]
            if ($null -ne $moreRecordsProperty) {
                $segmentExhausted = -not [System.Convert]::ToBoolean(
                    $moreRecordsProperty.Value
                )
            }
            elseif ($hasResultIndex -and $hasResultCount) {
                $segmentExhausted = (
                    [long]$lastResult.ResultIndex -eq [long]$lastResult.ResultCount
                )
            }

            if (
                $segmentResultCount -ge 50000 -or
                ($hasResultCount -and [long]$lastResult.ResultCount -ge 50000)
            ) {
                throw (
                    "The $segmentStart to $segmentEnd segment reached the Exchange Online " +
                    "50,000-record session limit. Reduce SegmentDuration and rerun; this " +
                    "result cannot be represented as complete."
                )
            }

            if (-not $segmentExhausted -and $newRecordCount -eq 0) {
                throw "Audit paging returned only duplicate records before reporting exhaustion."
            }
        }
        while (-not $segmentExhausted)
    }

    return $records
}

$endDate = (Get-Date).ToUniversalTime()
$startDate = $endDate.AddDays(-30)
$recordEnvelopes = @(
    Get-PagedCopilotAuditRecord -StartDate $startDate -EndDate $endDate
)

$pluginEvidence = foreach ($envelope in $recordEnvelopes) {
    $record = $envelope.Record
    $auditData = $envelope.AuditData
    $copilotEventData = $auditData.CopilotEventData

    foreach ($plugin in @($copilotEventData.AISystemPlugin)) {
        if ($null -eq $plugin) {
            continue
        }

        $rejectionReasons = @()
        if ($auditData.Workload -ne "Copilot") {
            $rejectionReasons += "Unexpected workload"
        }
        if (([string]$auditData.AppIdentity) -like "Copilot.Security.*") {
            $rejectionReasons += "Security Copilot is out of scope"
        }
        elseif ($approvedAppIdentities -notcontains [string]$auditData.AppIdentity) {
            $rejectionReasons += "AppIdentity is not approved"
        }
        if ($approvedPluginIds -notcontains [string]$plugin.ID) {
            $rejectionReasons += "Plugin ID is not approved"
        }

        [PSCustomObject]@{
            EvidenceStatus  = if ($rejectionReasons.Count -eq 0) { "Accepted" } else { "Rejected" }
            RejectionReason = $rejectionReasons -join "; "
            CreationDate    = $record.CreationDate
            UserId          = $record.UserIds -join "; "
            Workload        = $auditData.Workload
            AppIdentity     = $auditData.AppIdentity
            AppHost         = $copilotEventData.AppHost
            AgentId         = $auditData.AgentId
            AgentName       = $auditData.AgentName
            PluginName      = $plugin.Name
            PluginId        = $plugin.ID
            PluginVersion   = $plugin.Version
        }
    }
}

Write-Host "Microsoft 365 Copilot Plugin Evidence (Last 30 Days):" -ForegroundColor Cyan
Write-Host "Total CopilotInteraction envelopes collected: $($recordEnvelopes.Count)"
Write-Host "Plugin rows before scoping filters: $($pluginEvidence.Count)"

$m365PluginEvidence = @($pluginEvidence | Where-Object EvidenceStatus -eq "Accepted")
$rejectedPluginEvidence = @($pluginEvidence | Where-Object EvidenceStatus -eq "Rejected")

Write-Host "In-scope M365 Copilot plugin rows: $($m365PluginEvidence.Count)"
Write-Host "Rejected rows: $($rejectedPluginEvidence.Count)"

if ($m365PluginEvidence.Count -gt 0) {
    $pluginSummary = $m365PluginEvidence | Group-Object PluginName |
        Select-Object @{N='Plugin'; E={$_.Name}}, @{N='ExecutionCount'; E={$_.Count}} |
        Sort-Object ExecutionCount -Descending

    $pluginSummary | Format-Table -AutoSize
    $m365PluginEvidence |
        Export-Csv "M365CopilotPluginUsage_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation
}
else {
    Write-Warning "No in-scope Microsoft 365 Copilot plugin evidence matched the approved AppIdentity and plugin ID allow-lists."
}

if ($rejectedPluginEvidence.Count -gt 0) {
    $rejectedPluginEvidence |
        Export-Csv "RejectedCopilotPluginUsage_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation
    Write-Warning "$($rejectedPluginEvidence.Count) plugin row(s) were excluded from the M365 Copilot evidence set; review the rejected export."
}

The Microsoft audit schema places AISystemPlugin and AppHost under AuditData.CopilotEventData, while fields such as Workload, AppIdentity, AgentId, and AgentName remain at the root of AuditData. Microsoft also documents CopilotInteraction as a cross-product record type that includes Microsoft 365 Copilot, Cowork, and Security Copilot, so Workload = Copilot is not a sufficient product boundary by itself. Filter by an approved AppIdentity allow-list and keep Copilot.Security.SecurityCopilot out of the Microsoft 365 Copilot evidence set.

Search-UnifiedAuditLog returns at most 5,000 records per call. Script 4 therefore reuses a stable SessionId with SessionCommand ReturnLargeSet until each one-hour segment is exhausted, deduplicates the immutable audit record ID across page and segment boundaries, and stops if any segment reaches the 50,000-record Exchange Online session limit. If that limit is hit, reduce SegmentDuration and rerun; do not treat the export as complete evidence.

If you also need administrative change evidence for plugin or agent governance, search the documented admin operations separately, for example: CreatePlugin, UpdatePlugin, EnablePlugin, DisableCopilotPlugin, DeployedAgent, UpdatedAgent, RemovedAgent, BlockedAgent, UnblockedAgent, DeletedAgent, and UpdatedTenantSettings. Microsoft documents EnablePlugin in more than one Copilot product context, and UpdatedTenantSettings (Agent settings) is a different operation from UpdateTenantSettings (Copilot setting changes), so scope exported records before treating them as Microsoft 365 Copilot evidence.

Script 5: Agent tools / MCP request evidence checklist

Write-Host "Collect this evidence from Microsoft 365 admin center > Agents > Tools:" -ForegroundColor Cyan
Write-Host "  - Available and Blocked tools / MCP servers"
Write-Host "  - Requests tab with approve/reject decision and requester"
Write-Host "  - Declared tools exposed by each BYO MCP server"
Write-Host "  - Microsoft Entra permission consent state"
Write-Host "  - Work IQ read/write setting, usage-based billing plan, and spending policy where Work IQ is enabled"

Scheduled Tasks

Task Frequency Script
Plugin inventory Monthly Script 1
Graph connector review Quarterly Script 2
Permission audit Monthly Script 3
M365 Copilot plugin evidence review Weekly Script 4
Agent tools / MCP request review Monthly and after approvals Script 5 evidence checklist

Next Steps