Copilot Agents Scanner

Scanner multi-ambiente per analizzare e monitorare Copilot Studio Agents in Microsoft Dataverse.

Funzionalità

• Autenticazione Service Principal per scansioni automatizzate
• Scansione multi-ambiente con singolo comando
• Report CSV consolidato con tutti gli agent di tutti gli ambienti
• Analisi condivisione tramite PrincipalObjectAccess
• Rilevamento utenti e team con accesso
• Identificazione connettori utilizzati
• Statistiche per ambiente

Avvio Rapido

1. Setup e Deploy Application User

.\1-Setup.ps1

Lo script:

• Autentica interattivamente via browser (richiesto per operazioni PAC admin)
• Salva credenziali Service Principal in file criptato
• Lista tutti gli ambienti Power Platform
• Deploya application user con ruolo System Administrator in ogni ambiente

2. Scansione Multi-Ambiente

.\2-Scan-AllEnvironments.ps1

Lo script:

• Carica credenziali Service Principal
• Connette ad ogni ambiente automaticamente
• Scansiona tutti gli agent Copilot Studio
• Genera report consolidati in cartella con timestamp

File di Output

Tutti i report sono salvati in: ConsolidatedReport_YYYYMMDD_HHMMSS/

Report Principale: AllEnvironments_Agents.csv

CSV compatibile Excel con inventario completo agent.

Colonne:

• Environment - Nome ambiente
• EnvironmentId - GUID ambiente
• EnvironmentURL - URL organization Dataverse
• AgentName - Nome agent
• AgentId - GUID bot
• State - Stato agent (Active/Inactive)
• ComponentState - Stato componente (Published/Unpublished/Deleted)
• Language - Codice lingua agent
• AccessControlPolicy - Policy accesso (Any/Copilot readers/Group membership)
• CreatedOn - Data creazione
• ModifiedOn - Data ultima modifica
• PublishedOn - Data ultima pubblicazione
• SecurityGroupCount - Numero security group assegnati
• SharedWithSecurityGroups - Nomi security group (separati da punto e virgola)
• TotalUsers - Totale utenti con accesso
• TotalTeams - Totale team con accesso
• UsersList - Nomi utenti (separati da punto e virgola)
• TeamsList - Nomi team (separati da punto e virgola)
• ConnectorsCount - Numero connettori utilizzati
• ConnectorsList - Nomi connettori (separati da punto e virgola)
• LastUsed - Data ultimo utilizzo
• DaysSinceLastUse - Giorni dall'ultimo utilizzo
• IsShared - "Yes" se condiviso
• IsOrphaned - "Yes" se non condiviso con nessuno

Report Aggiuntivi

• EnvironmentSummary.csv - Statistiche per ambiente (conteggio agent, condivisi/orfani)
• DetailedReport.txt - Report testuale leggibile
• CompleteData.json - Dati completi in formato JSON

Prerequisiti

• PowerShell 5.1 (Windows PowerShell Desktop edition)
• Power Platform CLI (pac) - Guida installazione
• Azure AD Service Principal con:
  • Application (client) ID
  • Client secret
  • Tenant ID

Setup Service Principal

1. Creare App Registration in Azure AD

1. Vai su Azure Portal → Azure Active Directory → App registrations
2. Click New registration
3. Inserisci nome (es. "Copilot Agent Scanner")
4. Click Register
5. Annota Application (client) ID e Tenant ID
6. Vai su Certificates & secrets → New client secret
7. Annota il client secret value (copialo immediatamente, non sarà più mostrato)

2. Configurare Credenziali

Imposta variabili ambiente con credenziali Service Principal:

# Imposta variabili ambiente (PowerShell)
$env:PP_APP_ID = "your-application-id-here"
$env:PP_CLIENT_SECRET = "your-client-secret-here"
$env:PP_TENANT_ID = "your-tenant-id-here"

Nota: Queste sono variabili di sessione temporanee. Per renderle permanenti:

• Windows: Usa System Properties → Environment Variables
• PowerShell Profile: Aggiungi i comandi al tuo script $PROFILE

3. Eseguire Setup

.\1-Setup.ps1

Lo script deploierà application user in tutti gli ambienti automaticamente.

Workflow

┌─────────────────────────┐
│   1-Setup.ps1           │
│   - Auth interattiva    │
│   - Salva credenziali SP│
│   - Deploy app users    │
└───────────┬─────────────┘
            │ Crea sp-credentials.xml
            ↓
┌─────────────────────────┐
│ 2-Scan-AllEnvironments  │
│ .ps1                    │
│   - Carica credenziali  │
│   - Scansiona ambienti  │
│   - Genera report       │
└───────────┬─────────────┘
            │
            ↓
┌─────────────────────────┐
│ ConsolidatedReport_*/   │
│   - AllEnvironments_    │
│     Agents.csv          │
│   - EnvironmentSummary  │
│     .csv                │
│   - JSON & TXT reports  │
└─────────────────────────┘

Meccanismo di Condivisione

Gli agent Copilot Studio NON usano:

• appmoduleroles (come le Model-Driven Apps)
• Security roles Bot/Copilot (sempre a 0 assignments)

La condivisione avviene tramite:

• PrincipalObjectAccess: tabella generica per condivisione oggetti
• Team auto-generati: pattern nome {botid}_1
• teammembership: link team → utenti

AccessControlPolicy

• 0 = Any
• 1 = Copilot readers
• 2 = Group membership (usa authorizedsecuritygroupids)
• 3 = Any multi-tenant

Rilevamento Connettori

I connettori sono identificati tramite:

• Analisi botcomponent.data (componenti dell'agent)
• Match con connectionreference (tabella riferimenti connettori)
• Estrazione tipo da logical name per connettori inline

Formato output:

• Dataverse (connectionreference standard)
• github (inline) (connettore inline non pubblicato)

Troubleshooting

HttpRequestException - Browser non si apre

Se il browser non si apre durante pac auth create, usa device code flow:

pac auth create --deviceCode

Questo mostra un codice da inserire manualmente in un browser (anche su altro dispositivo).

Vedi TROUBLESHOOTING.md per soluzioni dettagliate.

"Connection Failed" per un ambiente

• L'application user deve esistere nell'ambiente
• L'application user deve avere ruolo System Administrator
• Assicurati che l'ambiente abbia un database Dataverse provisionato

"Credential file not found"

Esegui .\1-Setup.ps1 prima per creare il file credenziali.

"pac command not found"

Installa Power Platform CLI:

# Usando dotnet tool
dotnet tool install --global Microsoft.PowerApps.CLI.Tool

# Oppure scarica installer da:
# https://aka.ms/PowerAppsCLI

Errore: "Microsoft.Xrm.Data.PowerShell module is not compatible with PowerShell Core"

Usa PowerShell 5.1 Desktop, non PowerShell 7/Core.

Nessun agent trovato ma esistono nell'ambiente

Verifica che il Service Principal abbia ruolo System Administrator.

Note Sicurezza

• Credenziali in sp-credentials.xml sono criptate usando Windows DPAPI
• Credenziali criptate sono specifiche per macchina e utente
• Mai committare sp-credentials.xml in version control (già in .gitignore)
• Service Principal ha accesso solo agli ambienti dove application user è deployato

Dettagli Tecnici

Flusso Autenticazione

1. Setup (1-Setup.ps1):

   • Usa autenticazione interattiva per operazioni PAC admin
   • Salva credenziali Service Principal per scanner

2. Scansione (2-Scan-AllEnvironments.ps1):

   • Usa autenticazione Service Principal per connettersi a Dataverse
   • Nessuna interazione utente richiesta

Estrazione Dati

• Usa FetchXML queries via modulo Microsoft.Xrm.Data.PowerShell
• Query su entità bot (Copilot Studio Agents)
• Estrae condivisione da PrincipalObjectAccess
• Mappa principalid a team e utenti
• Estrae metadata: date creazione, modifica, pubblicazione, lingua, stato componente

Accesso Risultati FetchXML

Pattern corretto:

$result = Get-CrmRecordsByFetch -conn $conn -Fetch $fetchXml
$records = $result.CrmRecords  # Array di record

NON iterare su $result.Keys (errore comune).

Performance

• Scansioni sequenziali per ambiente
• Tempo tipico: 5-15 secondi per ambiente
• Generazione output: < 1 secondo
• Cache connectionreference per ambiente per ridurre query

Casi d'Uso

Questo tool è utile per governance e auditing di ambienti Power Platform su scala, permettendo di:

• Inventariare tutti gli agent Copilot Studio in tutti gli ambienti
• Identificare agent orfani (non condivisi con nessuno)
• Analizzare gruppi di sicurezza e accesso utenti per ogni agent
• Ottenere statistiche aggregate per ambiente
• Monitorare utilizzo agent nel tempo
• Identificare agent inattivi o inutilizzati
• Tracciare ciclo vita agent (date creazione, modifica, pubblicazione)
• Verificare conformità assicurando assegnazioni corrette

Autore

Marco Zamana

Licenza

Uso interno