Scopri come Microsoft Graph può essere usato come Copilot per la Sicurezza, sfruttando le API REST per migliorare la protezione dei dati con accesso delegato.
Microsoft Graph è uno strumento potente e flessibile che permette di recuperare dati da diversi prodotti Microsoft. Utilizzando le API REST ben documentate, è possibile estrarre informazioni da varie fonti come incidenti di sicurezza, documenti di SharePoint, email, chat di Teams e molte altre. Tutte le chiamate alle API di Graph supportano la specifica OData e restituiscono i dati in formato JSON. La specifica URL di OData consente di includere clausole di selezione, filtro e altro nelle chiamate REST, dando così il controllo sulla quantità di dati da includere nella risposta dell’API.
Microsoft Copilot per la Sicurezza è un sistema di Intelligenza Artificiale basato su modelli di linguaggio di grandi dimensioni, progettato per casi d’uso legati alla cybersecurity. Non è un sistema monolitico, ma un ecosistema che esegue richieste di dati da più fonti tramite un meccanismo di plugin unico. Questo meccanismo permette a Copilot di estrarre dati da qualsiasi fonte esterna che supporti le API REST, consentendogli così di effettuare chiamate alle API di Graph.
Questo articolo presuppone una conoscenza di base di Microsoft Graph, Copilot e l’uso delle API REST, e fornisce un esempio generico di come effettuare chiamate API di Graph da Copilot.
Introduzione a Microsoft Graph
Microsoft Graph offre un unico endpoint (https://graph.microsoft.com) per accedere a una vasta gamma di dati e informazioni provenienti dal cloud Microsoft, inclusi Microsoft 365, Windows ed Enterprise Mobility + Security. Se non hai mai lavorato con Microsoft Graph API prima, il punto di partenza migliore è la pagina principale della documentazione disponibile qui.
Come per qualsiasi altra API REST, è utile utilizzare un client API REST (Boomerang, Postman, ecc.) per sperimentare e testare l’API. Con Microsoft Graph c’è un’altra opzione chiamata Graph Explorer, che permette di valutare tutte le API. Usare Graph Explorer è molto più veloce e conveniente rispetto ad altri client REST, poiché gestisce l’ottenimento dei token di autenticazione ed è direttamente collegato alla documentazione di Graph. Puoi accedere a Graph Explorer da questo link.
Una volta all’interno di Graph Explorer, sarà necessario autenticarsi con le credenziali del tuo tenant Microsoft. Anche se questo non è necessario per effettuare le chiamate API, è fortemente raccomandato poiché, dopo l’autenticazione, Graph Explorer recupererà il JSON Web Token (JWT) per il tuo account, necessario come token Bearer nell’intestazione di ogni chiamata API di Graph. Il JWT consente inoltre a Graph Explorer di recuperare dati dal tuo tenant, al contrario dei dati generici mostrati quando non si è autenticati.
Permessi
Ogni chiamata API di Graph richiede che il tuo account (e il JWT) disponga dei permessi necessari per visualizzare i dati. Maggiori dettagli sui permessi di Graph sono disponibili qui. Poiché Graph Explorer agisce per conto dell’utente autenticato, questo è definito come autenticazione “per conto di” con accesso delegato. I permessi delegati sono anche chiamati scope e sono contenuti all’interno del JWT. Se non si dispone dei permessi necessari, la chiamata REST restituirà un errore “Non autorizzato” (HTTP 401). Per ogni chiamata di Graph, sotto la scheda “Modifica permessi” Graph Explorer mostra uno o più dei permessi necessari per la chiamata.
In base al tuo ruolo e all’assegnazione dei permessi in Entra, puoi dare il consenso a uno dei permessi richiesti per effettuare la chiamata. Lo scope del JWT dovrebbe contenere i permessi che permettono a Graph Explorer o a qualsiasi altra applicazione che agisce per conto dell’utente, di recuperare correttamente i dati richiesti dalla chiamata. Puoi vedere il contenuto di un JWT e lo scope che contiene dal sito jwt.ms.
Utilizzo di Microsoft Graph per Copilot della Sicurezza
Definiamo ora un caso d’uso in base al quale decideremo le API di Graph da chiamare e quindi costruiremo un plugin API per Copilot su di esse. Prima di costruire un plugin per Copilot che utilizza le API di Graph, assicurati di aver esaminato tutte le capacità presenti nei vari plugin Microsoft disponibili di default in Copilot. Nuovi plugin Microsoft e abilità aggiuntive per i plugin esistenti vengono costantemente aggiunti, e questo assicura che tu non stia costruendo un plugin per una funzionalità che già esiste. Nel nostro caso d’uso costruiremo un plugin per estrarre tutti gli ID degli avvisi da un incidente e poi, in base all’ID dell’avviso, consentirci di recuperare le prove associate a quell’avviso.
Accedi alla console di Graph Explorer, autentica e vai al gruppo “Sicurezza” nella barra di navigazione a sinistra. Selezionando l’opzione ‘alerts’ aggiornerà l’URL nel riquadro di destra. Se l’URL non punta alla nuova API unificata di Microsoft 365 Alerts e Incident (termina in ‘alert’ e non ‘alert_v2’), cambia l’URL per terminare in ‘alert_v2’.
Poiché si basa sulla specifica OData, l’API di Graph supporta diversi criteri di selezione e opzioni di filtro che restringono l’ambito dei dati restituiti. Per un plugin Copilot per la Sicurezza, questo è molto importante poiché l’uso di criteri di selezione e filtro riduce la dimensione dei dati restituiti dall’API, permettendo a Copilot di processarli in modo più efficiente. Queste opzioni vengono passate come parametri di query nell’URL e la descrizione dettagliata delle opzioni supportate è disponibile nella documentazione di Microsoft Graph qui. Se il campo dati necessario non è disponibile nel JSON restituito dalla chiamata API di Graph, si tratta di un caso d’uso avanzato che non è coperto da questo articolo. In questi casi, sarà necessario modificare/manipolare i dati utilizzando Logic Apps, Azure Functions o Webservice e quindi integrarli con Copilot.
Nella nostra prima chiamata API, utilizzeremo l’opzione $count che inserirà un campo di conteggio nel JSON di output. L’opzione $count viene aggiunta come parametro di query come mostrato nella schermata di cattura. Una volta premuto il pulsante ‘Run Query’, Graph Explorer effettuerà la chiamata API REST, il cui output/risposta JSON viene mostrato nel riquadro ‘Response preview’. Nota il campo ‘@odata.count’ aggiunto dal parametro di query $count che mostra il numero di avvisi restituiti.
Il nostro caso d’uso prevede di visualizzare solo gli avvisi in un incidente specifico. Sebbene il JSON restituito abbia un campo ‘incidentId’ che mostra l’ID dell’incidente a cui appartiene ciascun avviso, ci sono troppi avvisi che non sono utili. Il nostro obiettivo è restituire il minor numero possibile di dati a Copilot, perciò utilizzeremo un filtro OData per restringere l’incidente e ottenere solo gli avvisi assegnati a esso.
Creazione del Plugin API per Copilot
Siamo ora pronti a definire i file YAML necessari affinché Copilot effettui la chiamata API di Graph. Il file YAML principale è riportato di seguito, per maggiori dettagli su questi file YAML e i loro campi, fare riferimento a questo articolo.
Autenticazione
Nota il valore per ‘SupportedAuthTypes’ e ‘Authorization’ definito come ‘AADDelegated’ (Azure Active Directory Delegated). Quando l’autorizzazione è impostata su ‘AADDelegated’, si indica a Copilot di utilizzare l’accesso delegato (o ‘operare per conto di’) dell’utente che è connesso a Copilot durante la chiamata API di Graph. In questo modo, Copilot rende molto facile effettuare chiamate API di Graph, senza dover andare al Centro di amministrazione di Microsoft Entra e registrare l’applicazione come descritto qui. Per questo, dobbiamo usare OAuth2 e ottenere un ID applicazione registrando una applicazione, di cui parleremo in un articolo seguente. Insieme a ‘AADDelegated’, Copilot supporta l’autenticazione OAuth2 insieme a diverse altre opzioni elencate qui.
Con l’importante questione dell’autenticazione risolta, vediamo il secondo file YAML, ovvero per la specifica OpenAPI del nostro Plugin.
Una volta che il file YAML della definizione OpenAPI è accessibile su Internet, andiamo alla console di Copilot e seguiamo i passaggi per importare il plugin personalizzato. Una volta importato, mostrerà nell’area dei plugin personalizzati, assicurati che sia abilitato.
Ottenere le Prove in Basi agli IDs degli Avvisi
Ora che abbiamo gli IDs degli avvisi, estendiamo la capacità del nostro plugin per ottenere i dettagli delle prove su un avviso specifico. Il seguente URL dell’API di Graph recupera informazioni specifiche per l’ID dell’avviso passato a esso: https://graph.microsoft.com/v1.0/security/alerts_v2/{alertid}.
Modificando la specifica OpenAPI per supportare un’altra chiamata API REST, ottenendo le informazioni specifiche per l’ID dell’avviso, possiamo quindi estrarre solo i dati relativi alle prove.
In questo articolo, abbiamo dimostrato quanto sia semplice costruire un plug-in Copilot per la Sicurezza che effettua chiamate API di Graph. Abbiamo utilizzato il tipo di autenticazione ‘AADDelegated’ di Copilot che ci consente di effettuare chiamate API di Graph con accesso delegato. In un articolo successivo, esploreremo come effettuare chiamate API di Graph da Copilot con l’autenticazione OAuth2.