Lavoro da anni con script PS1 che scrivo, modifico e richiamo all’occorrenza ogni volta che ne ho bisogno. Trovo altresì comodo poter avere però dei comandi rapidi da lanciare che è solitamente prerogativa dei moduli che PowerShell carica al suo avvio (o in un secondo momento, manualmente). Ho quindi voluto dare una sbirciata alla documentazione ufficiale di Microsoft (i link diretti si trovano nei crediti dell’articolo, in fondo) e imbastire un piccolo modulo “scatola dei giocattoli” che potesse tornarmi utile nelle operazioni quotidiane con PowerShell, di quelle che magari richiedono un paio di comandi anziché uno, un output più pulito, maggiori filtri, ecc.
Il “ToyBox” vuole essere un modulo fatto in casa e in continuo aggiornamento, qualcosa da tenere a portata di mano e possibilmente aggiornato anche su GitHub. Lascia che te ne parli.

ps.toybox

Il modulo è composto da un file psm1 che contiene il cuore pulsante (funzioni, comandi, ecc.) e un file manifest psd1 non obbligatorio, ma che porta in dote una serie di informazioni relative al modulo, alla sua compatibilità con PowerShell, la versione e molto altro ancora.

Il modulo andrà caricato in una delle posizioni già tenute d’occhio da PowerShell, puoi ottenerle facilmente lanciando un $env:PSModulePath in finestra PowerShell, più precisamente in una cartella che porti il medesimo nome del file del modulo. Nel mio caso la directory sarà C:\Users\giovanni.solone\Documents\PowerShell\Modules, è qui che ho creato la cartella con all’interno i due file, chiamata alla stessa maniera del modulo:

Caricare un modulo è semplice, basterà lanciare da PowerShell il comando Import-Module ps.toybox e il gioco è fatto. Un rapido check (Get-Module) ti dovrebbe mostrare cosa c’è ora a bordo di PowerShell 7 (insieme al resto dei moduli precedentemente già presenti):

Il modulo (almeno attualmente)

Ho scelto di iniziare il modulo con alcune delle istruzioni di più comune utilizzo. Si va dalla connessione ai servizi Microsoft Online (PowerShell: Connect-MsolService con PowerShell 7) al rilascio delle email in quarantena, passando per un più banale check delle ACL applicate alla casella di posta elettronica o l’aggiunta / rimozione di permessi multipli sulla stessa.
L’ho già detto e lo sottolineo: è un modulo nato da poco, arriveranno aggiornamenti in base alle necessità o alle richieste, d’altronde gli script PowerShell scritti e pubblicati svolgono già queste funzioni nella maggior parte dei casi, si tratta giusto di snellire il “non necessario” e portarlo a bordo del modulo.

# M365: connessioni ======================================================================================================================================================================

function ConnectMSOnline {
  Import-Module MSOnline -UseWindowsPowershell
  Connect-MsolService
}

# Check ACL caselle di posta =============================================================================================================================================================

function MboxPermission {
  param( [string] $sourceMailbox )
  Get-MailboxPermission -Identity $sourceMailbox | where {$_.user.tostring() -ne "NT AUTHORITY\SELF" -and $_.user.tostring() -NotLike "S-1-5*" -and $_.IsInherited -eq $false} | Select Identity,User,AccessRights
  Get-RecipientPermission $sourceMailbox -AccessRights SendAs | where {$_.Trustee.tostring() -ne "NT AUTHORITY\SELF" -and $_.Trustee.tostring() -NotLike "S-1-5*"} | Select Identity,Trustee,AccessRights | Out-String
  Get-Mailbox $sourceMailbox | Select -Expand GrantSendOnBehalfTo
}

# Modifica ACL caselle di posta ==========================================================================================================================================================

function AddMboxPermission {
  param( [string] $sourceMailbox )
  Write-Host "Add $($_) on $($sourceMailbox) ..."
  Add-MailboxPermission -Identity $sourceMailbox -User $_ -AccessRights FullAccess -Confirm:$false
  Add-RecipientPermission $sourceMailbox -Trustee $_ -AccessRights SendAs -Confirm:$false
}

function RemoveMboxPermission {
  param( [string] $sourceMailbox )
  Write-Host "Remove $($_) from $($sourceMailbox) ..."
  Remove-MailboxPermission -Identity $sourceMailbox -User $_ -AccessRights FullAccess -Confirm:$false
  Remove-RecipientPermission $sourceMailbox -Trustee $_ -AccessRights SendAs -Confirm:$false
}

# M365: Protection =======================================================================================================================================================================

function QuarantineRelease {
  param(
    [string] $senderAddress,
    [switch] $release
  )
  if ($release) {
    Write-Host "Release quarantine from known senders: release email(s) from $($senderAddress) ..."
    Get-QuarantineMessage -QuarantineTypes TransportRule -SenderAddress $senderAddress | ForEach {Get-QuarantineMessage -Identity $_.Identity} | ? {$_.QuarantinedUser -ne $null} | Release-QuarantineMessage -ReleaseToAll
    Write-Host "Release quarantine from known senders: verifying email(s) from $($senderAddress) just released ..."
    Get-QuarantineMessage -QuarantineTypes TransportRule -SenderAddress $senderAddress | ForEach {Get-QuarantineMessage -Identity $_.Identity} | ft -AutoSize Subject,SenderAddress,ReceivedTime,Released,ReleasedUser
  } else {
    Write-Host "Find email(s) from known senders quarantined: email(s) from $($senderAddress) not yet released ..."
    Get-QuarantineMessage -QuarantineTypes TransportRule -SenderAddress $senderAddress | ForEach {Get-QuarantineMessage -Identity $_.Identity} | ft -AutoSize Subject,SenderAddress,ReceivedTime,Released,ReleasedUser
  }
}

Export-ModuleMember -Function AddMboxPermission
Export-ModuleMember -Function ConnectMSOnline
Export-ModuleMember -Function MboxPermission
Export-ModuleMember -Function QuarantineRelease
Export-ModuleMember -Function RemoveMboxPermission

Il progetto è come sempre aperto e collaborativo se lo desideri, si trova all’indirizzo github.com/gioxx/ps.toybox. Modificare ciò che vuoi per renderlo migliore, più completo, sarà mio piacere mandare in merge eventuali richieste sensate. Diversamente porta pazienza, seguiranno certamente degli aggiornamenti lato mio e – necessariamente – la stesura del file Readme per spiegare come usare al meglio il modulo, anche se per qualcuno sarà già più che comprensibile il codice inserito all’interno del modulo (e i comandi per richiamare le singole funzioni).

In caso di dubbi, lo sai già, l’area commenti è a tua totale disposizione :-)

#StaySafe

Credits:
docs.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-script-module?view=powershell-7.2
docs.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest?view=powershell-7.2