Terza prova ITS

•

Sommario documento terza prova ITS TTF #

  1. Introduzione
  2. Obbiettivo
  3. Cenni-Teorici
  4. Realizzazione

INTRODUZIONE #

Questo documento nasce come documentazione di un piccolo progetto realizzato durante i 2 mesi e mezzo di stage del corso ITS Tech Talent Factory “Cloud Administrator & Security Engineer”. Ho scelto di parlare di questo progetto in particolare perché è uno dei progetti che ho personalmente iniziato e concluso all’interno di questo percorso ed è uno script di automazione che servirà ad evitare perdite di tempo in futuro, e sarà quindi utilizzato (si spera) per lungo tempo all’interno dell’azienda del cliente per il quale il progetto è stato pensato, oltre a poter essere replicato e riutilizzato anche per altre aziende in futuro, semplicemente cambiando alcuni parametri e gli indirizzi mail a cui inviare le mail autogenerate.

OBBIETTIVO #

L’obbiettivo di questo progetto è quello di creare due script in grado di inviare in modo automatico della mail. Queste mail devono contenere all’interno dei dati che vengono forniti da Microsoft, tramite API, riguardanti il Message Center e il Service Health. Si è deciso di automatizzare questo processo poiché veniva inizialmente svolto a mano, andando nella console di admin di Microsoft e copiando e incollando tutte le informazioni riguardanti determinati problemi e messaggi del tenant Microsoft e inviando poi manualmente le mail tramite un template preimpostato di una mail. L’obbiettivo diventa quindi quello di automatizzare la creazione e l’invio delle mail al competence che si occuperà poi di inviare le mail ai reparti di competenza in un primo momento e poi sarà invece lo script di occuparsi anche di questo passaggio, lasciando al competence center in questione la sola presa visione dei problemi e dei messaggi relativi al tenant.

BEFORE SCRIPT Before Script

AFTER SCRIPT Post Script

CENNI-TEORICI #

Message-Center #

Il Message Center di Microsoft serve a tenere traccia di modifiche dei software, funzionalità e manutenzioni su servizi e/o siti. È utile per un amministratore di sistema, o anche di solo una piccola parte di servizi, sapere in tempo utile quali saranno gli aggiornamenti, le manutenzioni e i nuovi aggiornamenti e servizi che Microsoft lancia sul mercato, in modo da poter adattare al meglio le esigenze dell’azienda alle modifiche. È possibile filtrare le notizie per Update, per servizi impattati e anche per tag, in modo da prendere, ad esempio, solo i Major Update.

Service-Health #

Il Service Health di Microsoft offre un dashboard personalizzabile che registra l’integrità dei servizi di Azure ed è possibile utilizzare la dashboard del Service Health per creare e gestire degli alert immediati in caso di problemi sul tenant controllato. L’integrità dei servizi tiene traccia di quattro tipi di eventi di integrità che possono influito sulle risorse:

  • Problemi dei servizi: problemi dei servizi di Azure che influiscono in questo momento.
  • Manutenzione pianificata: manutenzione imminente che può influire sulla disponibilità dei servizi in futuro.
  • Avvisi sull’integrità: modifiche apportate ai servizi di Azure che richiedono attenzione, Gli esempi includono la deprecazione delle funzionalità di Azure o i requisiti di aggiornamento
  • Avvisi di sicurezza : notifiche o violazioni correlate alla sicurezza che potrebbero influire sulla disponibilità dei servizi di Azure.

Powershell #

Powershell è uno strumento essenziale per qualsiasi sistemista informatico, essendo una shell con un proprio linguaggio di programmazione e una riga di comando (CLI). È ora un software libero, disponibile non solo per Windows, ma anche per Linux e MacOS, e questo è un vantaggio enorme data la possibilità di creare script cross-platform, utilizzando anche alias di alcuni comandi che appartengono inizialmente a Linux e sistemi UNIX. Powershell risulta adatta ad automatizzare processi, principalmente grazie alla versatilità data dai vari moduli installabili e all’utilizzo di API e web requests come ad esempio in questo specifico caso.

HTML #

L’HTML (HyperText Markup Language) un linguaggio di formattazione e impaginazione (markup), nato all’inizio del Web, ed è un linguaggio molto semplice e intuitivo che, grazie a dei tag, permette l’impaginazione e la formattazione personalizzata di elementi all’interno di una pagina web. È divenuto sempre più utilizzato grazie anche all’utilizzo di linguaggi come il CSS e il JavaScript che consentono varie impostazioni grafiche e di movimento e di compatibilità con diversi browser e dispositivi. In questo specifico progetto, l’HTML, è utilizzato per la formattazione della mail, in modo da rendere completa e leggibile, nel miglior modo possibile, ogni informazione che arriva direttamente dalle API di Microsoft.

Azure-App #

Sul portale di Azure è possibile registrare delle applicazioni interne, oltre alla gestione di utenti, gruppi e VM. Queste applicazioni interne servono da certificato per determinati utilizzi, tra cui l’utilizzo delle API di Microsoft. Creando una applicazione si ha a disposizione un codice univoco e una chiave che serve per richiedere un token di autenticazione tramite web request, in modo da poter operare in tutta tranquillità tramite script Powershell, senza dover accedere manualmente al portale o tramite file .xml. Le applicazioni possono avere diversi tipi di accessi e di permessi, che possono essere garantiti solamente dal Global Admin del tenant, ed è possibile modificare i permessi senza dover ricreare completamente l’applicazione.

Microsoft-API #

Con API, si intendono delle Application Programming Interface, ovvero un insieme di processi e procedure raggruppate per specifici compiti che vengono distribuite in modo da rendere più veloce e semplice la configurazione di determinati script o programmi, poiché buona parte del codice viene gestista appunto internamente dalle API ed il lavoro del programmatore si limita a dover gestire correttamente i parametri richiesti dalla API. Come per ogni libreria e/o programma, ogni API ha una sua documentazione, ed è lì che possiamo trovare ogni informazione possibile riguardo alle configurazioni e parametri delle API.Nel mio caso ho utilizzato direttamente le API Microsoft, di tipo Web RESTful, che consentono di accedere a risorse e informazioni del cloud Microsoft grazie all’utilizzo di app Azure, secret key e token di autenticazione tramite richieste web di tipo REST.

REALIZZAZIONE #

Di seguito la realizzazione suddivisa in capitoli del progetto di automazione per l’invio delle mail. Questo documento è utile anche come guida in caso si voglia replicare lo script per questa o altre automazioni che abbiano alla base l’utilizzo delle Microsoft Graph API per la gestione di dati Microsoft.

Creazione-Applicazione-Azure #

Dal portale di azure (https://www.portal.azure.com), cliccare su Azure Active Directory e poi su ‘App Registration’ e poi su ‘New Registration’

Per creare una applicazione serve semplicemente scegliere un nome, che può comunque essere cambiato in ogni momento, e scegliere la tipologia di permessi, come ad esempio se si vuole dare i permessi solo agli utenti che si autenticano allo stesso tenant o OU dell’utente che ha creato l’App e che ne ha dato i permess

Una volta creata l’applicazione avremo bisogno di seguire due ulteriori passaggi:

  • Dare i giusti permessi all’app per poter funzionare
  • Creare delle chiavi segrete per la richiesta di token di autenticazione durante l’esecuzione dello script

Dalla pagina principale dell’applicazione, clicchiamo su ‘API Permissions’. In una situazione standard, avremo già come API Permission, le Microsoft Graph API User.Read.

Tramite il tasto ‘Add a permission’ dobbiamo aggiungere anche un’altra permission che possiamo trovare sotto ‘Office 365 Management APIs’ -> ‘Application permissions’ -> ‘ServiceHealth.Read’

Adesso la nostra App ha accesso a tutte le API necessarie per la realizzazione del progetto. Come ultimo passaggio sulla applicazione però, dobbiamo creare una Client Secrets, ovvero una chiave che servirà a dimostrare di essere i possessori di quella applicazione all’interno dello script powershell, in modo da ricevere un corretto auth token durante la connessione al sito di Microsoft per il download delle informazioni necessarie dalla console di Admin Microsoft. Per farlo, basterà andare su ‘Certificates & Secrets’ e cliccare su ‘New Client Secret’, aggiungiamo una descrizione della chiave per ricordare in futuro a cosa è collegata quella chiave segreta ed infine scegliamo una data di scadenza, scegliendo dal menù a tendina o personalizzando come vogliamo noi la durata della chiave.

Una volta creata la client secret, è necessario salvare su un blocco note, o ovunque ci sia più comodo, tutti i dati della chiave, in particolar modo la ‘Value’ della client secret, perché una volta ricaricata la pagina non sarà più visibile e sarà quindi necessario creare una nuova client secrets in caso si perdesse il valore della chiave

Creazione-Script-Service-Health #

Prima di tutto, all’interno dello script vanno definite alcune variabili, come da prassi, e in questo caso le variabili che dichiariamo sono quasi tutti dei percorsi all’interno del server per il salvataggio di log, e per il controllo delle credenziali di autenticazione per l’invio delle mail e gli ID del tenant, dell’applicazione che abbiamo precedentemente creato e della sua client secret key, tramite le quali richiederemo poi un authentication token con una web request. Altre variabili che dichiareremo sono gli indirizzi a cui manderemo le mail e l’indirizzo da cui la mail partirà, il file xml con le credenziali di quell’indirizzo mail e il server SMTP che gestirà la richiesta di quell’indirizzo mail.

#Directory ID from Azure
$TenantID = ‘XXXXXXXXXXXXXXXXXXXXXXXXXXX’
#Created Application's ID
$ClientID = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX’
#Secret Key created inside the Azure's application
$ClientSecret = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX'
$logpath = 'C:\GetServiceHealth\Logs'
$credpath = 'C:\GetServiceHealth\Credenziali.xml'
$log = 'C:\Script\GetServiceHealth\Logs\' + (Get-Date -UFormat "%Y-%m-%d") + '.log'
#Define variable for mail sender, one line for every receiver domain
$to = "destinatario@its.it" #you can add multiple address of the same domain or use a DL for multiple domains
$from = new-object System.Net.Mail.MailAddress("mittente@its.it", "Mittente O365 
Message Center - Service News") #you can change the displayed name on mailbox 
$subject = ''
$smtp = 'its-it.mail.protection.outlook.com'

Le mail potranno essere inviate in ogni caso, ma è sempre meglio autenticarsi con la mail, in modo da non rischiare che le mail finiscano nella cartella di spam o che peggio ancora non vengano neanche consegnate in base a regole dell’azienda sulle mail considerate come mail potenzialmente dannose. Per l’autenticazione usiamo un file xml con le credenziali giuste che viene precedentemente creato grazie ai comandi ‘$cred = Get-Credential’ -> ‘$cred = Export-Clixml C:\percorsodelfile.xml’

$cred = Import-Clixml -Path $credpath

Utilizzando le variabili definite finora, possiamo fare una richiesta di token di autenticazione con il quale verrà poi effettuata la richiesta web per avere come ritorno il risultato delle API di Microsoft gestite come vogliamo noi, in questo caso infatti vogliamo avere informazioni solamente per quanto riguarda gli oggetti di tipo ‘MessageCenter’, ovvero tutte le informazioni e i dati presenti nella pagina del Message Center della Admin Console di Microsoft,

#request of authentication token
$body = @{grant_type="client_credentials";
 resource="https://manage.office.com";
 client_id=$ClientID;
 client_secret=$ClientSecret
 }
$oauth = Invoke-RestMethod -Method Post -Uri
"https://login.microsoftonline.com/$($tenantID)/oauth2/token?api-version=1.0" -Body
$body
$token = @{'Authorization' = "$($oauth.token_type) $($oauth.access_token)" }
#---------------------------------------------------------------------------------
#GET request to microsoft API
$Invoke = Invoke-RestMethod -Uri
"https://manage.office.com/api/v1.0/$($TenantID)/ServiceComms/Messages" -Headers
$token -Method Get -Verbose
#select all information where message type is -ne to 'MessageCenter' and where $_.ID 
exist
$status = $Invoke.Value | Where-Object {($_.MessageType -ne 'MessageCenter') -and
($_.ID -ne '{}')}

All’interno dello script totale, c’è una piccola parte di script che si occupa solamente di convertire e confrontare delle date, trasformando degli oggetti di tipo ‘DATE’ a oggetti di tipo stringa da poter manipolare e gestire e ritrasformando gli oggetti in tipo ‘DATE’, in modo poter effettivamente fare il controllo delle date e di poter inviare solamente gli aggiornamenti delle ultime 24 ore, o comunque la frequenza con cui si sceglierà di far girare lo script.

#string that i want to convert
$start = $i.LastUpdatedTime 
#select only first 10 char 
$day = $start.Substring(0,10)
#convert that char in the date format
$day = [datetime]::parseexact($day, 'yyyy-MM-dd', $null)
$hour = $start.Substring(11,8)
#convert that char in the date format
$hour = [datetime]::parseexact($hour, 'HH:mm:ss', $null)
#create variable that contain all hours,minutes and seconds information
$timespan = New-TimeSpan -Hours $hour.Hour -Minutes $hour.Minute -Seconds
$hour.Second
#create variable that include the day and hour of the $i object in the format I want
$lst = $day + $timespan
#get today's date
$today = Get-date
#calcolate the difference between the date of object $i and the today's date, and 
then i write that in hours difference format with $hours variable
$timedifference = New-TimeSpan -Start $lst -End $today
$hours = $timedifference.TotalHours

Se la differenza di orario è effettivamente minore di 24, o di qualsiasi altro numero venga scelto per far girare lo script con task scheduler, allora ci si occuperà effettivamente di recuperare tutti i dati necessari per comporre la mail che verrà poi inviata. La mail viene inviata come HTML, in modo che sia il più leggibile e possibile, senza fraintendimenti o impostazioni grafiche non chiare.


if($hours -lt 24){
 
 $message = Out-String -InputObject $i.Messages.MessageText
 $type = Out-String -InputObject $i.MessageType
 $time = ([datetime]$i.StartTime).AddHours(0).ToString('dd/MM/yyyy - HH:mm:ss')
 $lastupdate = ([datetime]$i.LastUpdatedTime).AddHours(0).ToString('dd/MM/yyyy -
HH:mm:ss')
 #write in $services variable all the service to print that in the mail in htlm 
format
 foreach ($w in $($i.WorkloadDisplayName)){
 $services = $services + $w + " <br>"
 }
 foreach ($f in $i.Messages){
 $appoggio = $f.MessageText | Out-String
 $update = $update + $appoggio + "<br><style>hr.solid { border-top: 3px solid 
#bbb;}</style><body><hr class='solid'><br>"
 }

$standardbody = $i.ImpactDescription + "</h2></strong>" + "<h3><a 
href='https://admin.microsoft.com/#/servicehealth/:/alerts/" + $i.Id + "'>"+ $i.Id +
"</a></h3>" + '<style>table { width:100%;}table, th, td { border: 1px solid black; 
border-collapse: collapse;}th, td { padding: 15px; text-align: center;}#t01 tr:nthchild(odd) { background-color: #aaa;}#t01 th { background-color: #aaa; }</style> 
<table id="t01"> <tr> <th><h3>Published on</h3></th> <th><h3>Last Update on</h3></th> 
<th><h3>Status</h3></th> <th><h3>Services Impacted </h3></th> <th><h3>Issue 
type</h3></th> </tr> <tr> <td> <center>'+ $time+ '</td> </center> <td> 
<center>'+$lastupdate+'</td> </center> <td> <center>'+$($i.Status)+'</td> 
</center><td> <center>'+ $services +'</td> </center> <td> <center>'+$type+'</td> 
</center> </tr></table>'+ "<br>" + "<strong><h3>All Update: </h3></strong>" + "<pre>"
+ $update +"</pre>" + "<h3 style='color:#7f6000'>Il problema e' stato aperto a 
livello World Wide e potrebbe non avere impatto sul Servizio O365 di ITS Tech Talent 
Factory</h3> "

La mail viene composta da due parti principali, la variabile $standardbody qui sopra, che imposta in tutto e per tutto la mail, ogni singolo componente dal titolo in poi, e la parte $body, che è visibile qua sotto all’interno del controllo if, che serve semplicemente a cambiare il colore del titolo in base allo stato del servizio, seguendo la tabella in fondo al capitolo. Una volta composta la mail, viene inviata utilizzando un determinato encoding, l’SSL e l’utilizzo delle credenziali per l’invio di mail autenticate.

if($i.Status -like "Service restored"){
 $subject = "[Service Restored] Problema O365 - " + $I.id + ' - '
+ $i.ImpactDescription
 $body = "<h2 style='color:#228B22'>" + $standardbody
 }
 #send mail using all variables defined before
 Send-MailMessage -From $from -to $to -Subject $subject -BodyAsHtml $body -
Encoding utf32 -SmtpServer $smtp -UseSsl -Credential $cred -Port 25
 }

Creazione-Script-Message-Center #

Schedulazione-Script #

Risultato #

Implementazioni-Future #