MailHeaderAnalyzer: analizzare le intestazioni e-mail in PowerShell senza accesso alla rete

MailHeaderAnalyzer è un modulo PowerShell con due cmdlet. Get-MailHeaderAnalysis analizza l’intestazione di un’e-mail: catena di consegna con ritardi e informazioni TLS, risultati SPF, DKIM, DMARC e ARC inclusa la verifica che tali risultati provengano dal server ricevente, allineamento DMARC, classificazione ibrida di Exchange Online, valutazioni di Microsoft Defender, SpamAssassin e Rspamd, nonché anomalie quali righe From duplicate o caratteri di controllo Unicode. ConvertTo-MailHeaderReport genera da questi dati un rapporto per i ticket. Il modulo opera interamente offline: nessuna query DNS, nessuna connessione HTTP. È la versione da riga di comando dell’Header Analyzer su questo sito e utilizza la stessa logica di analisi.

Panoramica dei parametri

Entrambi i cmdlet supportano i Common Parameters -Verbose, -ErrorAction, -ErrorVariable, -OutVariable e gli altri descritti in about_CommonParameters.

Installazione

Install-Module -Name MailHeaderAnalyzer -Scope CurrentUser

Su un sistema senza accesso a Internet, scaricare il modulo su un altro computer con Save-Module -Name MailHeaderAnalyzer -Path C:\Temp e copiare la cartella MailHeaderAnalyzer in una directory di $env:PSModulePath, ad esempio %USERPROFILE%\Documents\WindowsPowerShell\Modules (Windows PowerShell 5.1) o %USERPROFILE%\Documents\PowerShell\Modules (PowerShell 7). Gli aggiornamenti vengono ottenuti con Update-Module -Name MailHeaderAnalyzer, mentre Get-Module -Name MailHeaderAnalyzer -ListAvailable mostra la versione installata.

Get-MailHeaderAnalysis

Analizza l’intestazione di un’e-mail e restituisce un oggetto di analisi.

Sintassi

Text (predefinito)

Get-MailHeaderAnalysis
    [-Header] <String[]>
    [<CommonParameters>]

Path

Get-MailHeaderAnalysis
    -Path <String[]>
    [<CommonParameters>]

Clipboard

Get-MailHeaderAnalysis
    -FromClipboard
    [<CommonParameters>]

Descrizione

Il cmdlet suddivide l’intestazione grezza in campi, espande le piegature RFC 5322 e decodifica i valori RFC 2047 nell’oggetto e negli indirizzi. Dalle righe Received costruisce la catena di consegna in ordine cronologico, calcola il ritardo per ogni stazione e legge versione TLS, cipher e classe di protocollo secondo RFC 3848. Da Authentication-Results, Received-SPF, DKIM-Signature e dalla catena ARC determina i risultati di autenticazione e verifica se la riga di verifica provenga effettivamente da una stazione della catena di consegna (RFC 8601, sezione 5). Si aggiungono l’allineamento DMARC, la classificazione ibrida di Exchange Online, le valutazioni dei filtri antispam e un elenco di anomalie.

Il cmdlet non esegue query DNS e non apre connessioni di rete. Spf, Dkim e Dmarc sono quindi sempre il giudizio del server ricevente, integrato dalla verifica che tale giudizio provenga da esso. Le firme DKIM non vengono ricalcolate crittograficamente.

Gli input vengono letti in modo tollerante: una riga vuota termina l’intestazione e il testo del messaggio successivo viene ignorato. Le righe senza nome di campo e senza spazio iniziale, come possono risultare dalla copia da finestre di dialogo dei client, appartengono al campo precedente. Una riga separatrice mbox From ... prima del primo campo viene ignorata e una Byte Order Mark viene rimossa. Vengono analizzate al massimo 200 righe Received, conteggiate dalla consegna.

Esempi

Esempio 1

Get-MailHeaderAnalysis -FromClipboard

Analizza l’intestazione presente negli appunti. In Outlook per Windows, l’intestazione si trova in File, Proprietà, Intestazioni Internet; in Outlook sul Web nelle opzioni del messaggio, in «Visualizza dettagli messaggio».

Subject     : Service-Report für März
From        : Beispiel Newsletter <[email protected]>
Date        : 2026-08-03 09:14:27Z
SPF         : pass
DKIM        : pass
DMARC       : pass
ARC         : -
CompAuth    : pass (reason 100)
AuthTrust   : Absent (no authserv-id, Microsoft 365 style)
Hops        : 3 (total 00:00:42)
DeliveredBy : zr0p278mb0570.chep278.prod.outlook.com
Findings    : none

Esempio 2

Get-MailHeaderAnalysis -Path .\nachricht.eml

Analizza un messaggio salvato. Il file può contenere solo l’intestazione o il messaggio completo; il corpo del messaggio viene ignorato.

Esempio 3

(Get-MailHeaderAnalysis -Path .\nachricht.eml).Hops

Mostra la catena di consegna come tabella, con il primo hop per primo.

#   From                 IP              By                                     Protocol   TLS      Time (UTC)           Delay
-   ----                 --              --                                     --------   ---      ----------           -----
1   client.example.net   198.51.100.34   mail.example.org                       ESMTPSA    -        2026-08-03 09:14:28  -
2   mail.example.org     203.0.113.25    mx.eur02.prod.protection.outlook.com   Microsoft… TLS 1.3  2026-08-03 09:15:09  41 s
3   AM0EUR02FT056.eop…   -               ZR0P278MB0570.CHEP278.PROD.OUTLOOK.COM Microsoft… TLS 1.2  2026-08-03 09:15:10  1 s

Esempio 4

Get-Content -Path .\header.txt | Get-MailHeaderAnalysis | Select-Object -ExpandProperty Findings

Legge l’intestazione riga per riga da un file di testo e mostra solo le anomalie. -Raw con Get-Content non è necessario, poiché il cmdlet compone autonomamente le righe.

Esempio 5

Get-ChildItem -Path .\export\*.eml |
    Get-MailHeaderAnalysis |
    Select-Object Source, Subject, Spf, Dkim, Dmarc, AuthTrust, HopCount,
        @{ Name = 'Findings'; Expression = { ($_.Findings.Code | Sort-Object -Unique) -join ',' } } |
    Export-Csv -Path .\auswertung.csv -NoTypeInformation -Encoding UTF8

Analizza tutti i messaggi di una cartella e scrive un file CSV con una riga per messaggio. La colonna calcolata riassume i codici Finding.

Esempio 6

Get-ChildItem .\export\*.eml |
    Get-MailHeaderAnalysis |
    Where-Object AuthTrust -eq 'Unmatched' |
    Select-Object Source, AuthServId, DeliveredBy

Elenca i messaggi la cui riga Authentication-Results non proviene dal sistema che effettua la consegna. Nelle analisi di phishing, è un rapido primo filtro.

Esempio 7

$a = Get-MailHeaderAnalysis -Path .\nachricht.eml
$a.Hops[$a.SlowestHopIndex - 1] | Format-List Index, FromHost, ByHost, Delay

Mostra la stazione con il ritardo maggiore. SlowestHopIndex è basato su 1, l’array Hops su 0.

Esempio 8

Get-MailHeaderAnalysis -Path .\nachricht.eml | ConvertTo-Json -Depth 6 | Set-Content .\analyse.json

Scrive l’analisi completa come JSON. -Depth 6 è necessario perché Hops, DkimSignatures e Exchange sono oggetti annidati; il valore predefinito 2 li emetterebbe solo come nomi di tipo.

Parametri

-Header

L’intestazione come testo. Il parametro accetta una singola stringa contenente l’intera intestazione o più stringhe; gli input della pipeline vengono raccolti e alla fine composti in un’intestazione, quindi Get-Content datei | Get-MailHeaderAnalysis funziona senza -Raw. Per analizzare più intestazioni separatamente, usare -Path con più file.

Alias: Text, Raw, InputObject

-Path

Percorso a un file contenente l’intestazione o un messaggio .eml completo. I percorsi relativi vengono risolti rispetto alla directory corrente. Il file viene letto con [System.IO.File]::ReadAllText: viene considerata una Byte Order Mark, senza BOM si usa UTF-8. Per ogni file viene creato un oggetto risultato separato; i file mancanti generano un errore non terminante.

Alias: FullName, PSPath, LiteralPath

-FromClipboard

Legge l’intestazione dagli appunti con Get-Clipboard -Raw. Il parametro è disponibile solo in Windows; in Linux e macOS il cmdlet termina con un messaggio di errore, così come quando gli appunti sono vuoti.

Input

System.String: righe di intestazione o l’intera intestazione, per -Header.

System.IO.FileInfo: oggetti file di Get-ChildItem, la cui FullName viene associata a -Path.

Output

MailHeaderAnalyzer.Analysis: un oggetto per ogni intestazione analizzata. Le proprietà sono descritte nella sezione Oggetto di output.

Note

Il testo dell’analisi (spiegazioni in Findings, CompAuthReasonMeaning e nei campi di significato) è in inglese, affinché possa essere inserito senza modifiche nei ticket internazionali. L’output della visualizzazione predefinita può essere mostrato per intero con Format-List *.

ConvertTo-MailHeaderReport

Genera un rapporto in Markdown o testo da un oggetto di analisi.

Sintassi

ConvertTo-MailHeaderReport
    [-Analysis] <Object>
    [-Format <String>]
    [<CommonParameters>]

Descrizione

Il rapporto comprende oggetto, mittente, data e Message-ID, risultati di autenticazione con indicazione della provenienza e allineamento, tutti i finding, la catena di consegna, la classificazione di Exchange e i valori dei filtri antispam. I caratteri di controllo Unicode per la direzione di scrittura restano visibili nel rapporto come <U+...>, così da non poter essere trasferiti tramite il rapporto in un sistema di ticket. L’ultima riga indica la versione del modulo.

Esempi

Esempio 1

Get-MailHeaderAnalysis -Path .\nachricht.eml | ConvertTo-MailHeaderReport | Set-Clipboard

Genera un rapporto Markdown e lo inserisce negli appunti.

# Email header analysis

- Subject: Service-Report für März
- From: Beispiel Newsletter <[email protected]>
- Date: 2026-08-03T09:14:27Z
- Message-ID: <[email protected]>

## Authentication

- spf: pass
- dkim: pass
- dmarc: pass
- compauth: pass (reason=100: passed authentication)
- Results without authserv-id (Microsoft 365 style)
- DMARC alignment: SPF Strict, DKIM Strict

## Delivery chain (total: 42 s)

| # | From | By | Protocol | TLS | Time (UTC) | Delay |
|---|---|---|---|---|---|---|
| 1 | client.example.net (198.51.100.34) | mail.example.org | ESMTPSA | - | 2026-08-03T09:14:28Z | - |
| 2 | mail.example.org (203.0.113.25) | mx.eur02.prod.protection.outlook.com | Microsoft SMTP Server | TLS 1.3 | 2026-08-03T09:15:09Z | 41 s |
| 3 | AM0EUR02FT056.eop-EUR02.prod.protection.outlook.com | ZR0P278MB0570.CHEP278.PROD.OUTLOOK.COM | Microsoft SMTP Server | TLS 1.2 | 2026-08-03T09:15:10Z | 1 s |

Esempio 2

Get-MailHeaderAnalysis -FromClipboard | ConvertTo-MailHeaderReport -Format Text

Emette il rapporto come testo senza formattazione Markdown, ad esempio per e-mail o log della console.

Esempio 3

Import-Module MailHeaderAnalyzer
Get-MailHeaderAnalysis -Path 'C:\Temp\bounce.eml' | ConvertTo-MailHeaderReport -Format Text

Utilizzo nella Exchange Management Shell. Se $env:PSModulePath è limitato da criteri di gruppo, caricare il modulo con Import-Module e il percorso completo del file .psd1.

Parametri

-Analysis

L’oggetto di analisi di Get-MailHeaderAnalysis. Il cmdlet rifiuta altri tipi di oggetto con un errore di binding.

-Format

Il formato di output. Valori validi:

• Markdown: titoli, elenchi e catena di consegna come tabella. Predefinito.
• Text: titoli in maiuscolo, righe rientrate, catena di consegna come elenco numerato.

Input

MailHeaderAnalyzer.Analysis: il risultato di Get-MailHeaderAnalysis.

Output

System.String: il rapporto, una stringa per ogni oggetto di analisi.

Oggetto di output

Get-MailHeaderAnalysis restituisce un oggetto di tipo MailHeaderAnalyzer.Analysis per ogni input. La visualizzazione predefinita mostra il riepilogo dell’esempio 1; tutte le proprietà sono accessibili tramite Select-Object, Format-List * o ConvertTo-Json.

MailHeaderAnalyzer.Analysis

MailHeaderAnalyzer.Hop

Ogni elemento in Hops corrisponde a una riga Received. L’ordine è cronologico, quindi inverso rispetto all’ordine nell’intestazione.

AuthTrust: provenienza dei risultati di verifica

Una riga Authentication-Results può essere scritta in un messaggio da qualsiasi mittente. Secondo RFC 8601, sezione 5, è determinante solo la riga dell’organizzazione ricevente e il relativo authserv-id deve poter essere associato a una stazione della catena di consegna. Il cmdlet confronta l’authserv-id di ogni riga con gli host by della catena Received (stesso dominio o sottodominio, sempre al confine del punto, nessuna sottostringa).

Se l’intestazione contiene righe di verifica da più fonti, il finding AuthMixedOrigins segnala la situazione. Se manca una riga di verifica, ma è presente una riga Received-SPF, il relativo risultato viene adottato come Spf e contrassegnato con ReceivedSpfOnly.

Allineamento DMARC

SpfAlignment confronta il dominio del mittente envelope con il dominio From, DkimAlignment confronta il dominio d= della firma verificata con il dominio From. Strict indica domini identici, Relaxed lo stesso dominio organizzativo, None nessuna corrispondenza. Il dominio organizzativo viene determinato euristicamente: le ultime due etichette, oppure le ultime tre per terminazioni multipartite note come co.uk o com.au. Non è inclusa una Public Suffix List completa.

MailHeaderAnalyzer.ExchangeClassification

Se l’intestazione contiene i campi X-MS-Exchange-Organization-*, X-OriginatorOrg o X-MS-Exchange-CrossTenant-*, il cmdlet popola la proprietà Exchange. I significati seguono l’articolo «Demystifying hybrid mail flow» del team Exchange; il contesto è illustrato nell’articolo Intestazioni ibride Exchange: interne o esterne?.

MailHeaderAnalyzer.SpamAssessment

La proprietà Spam riassume le valutazioni dei filtri noti. I valori provengono da sistemi esterni e vengono decodificati, ma non valutati.

L’elenco completo dei Reason Code compauth è disponibile nell’articolo Microsoft 365 compauth: Reason Code.

Findings

Il cmdlet restituisce le anomalie come oggetti in Findings, ciascuno con Severity (Info, Warning, Fail), un Code stabile per filtri e script e una spiegazione in Message.

Funzionamento e limiti

Il modulo legge ciò che è indicato nell’intestazione e ne deduce ciò che può essere dimostrato senza query esterne. Ne derivano alcuni limiti:

• Nessuna verifica crittografica. Le firme DKIM non vengono ricalcolate e non vengono eseguite query DNS. Spf, Dkim e Dmarc sono sempre il giudizio del server ricevente, integrato dalla verifica che tale giudizio provenga effettivamente da esso.
• È comprovata solo l’ultima riga Received. Tutte le righe sottostanti sono state fornite dal mittente e possono essere state costruite arbitrariamente. Attested contrassegna questa differenza; i ritardi degli hop precedenti si basano sulle indicazioni di tali righe.
• Domini organizzativi euristici. Per il Relaxed Alignment, il modulo utilizza un breve elenco di terminazioni multipartite, non una Public Suffix List completa.
• AuthMechanism documentato solo parzialmente. A eccezione del valore 10, Microsoft non ha pubblicato i codici; il modulo non ne inventa il significato.
• Set di caratteri. I valori RFC 2047 vengono decodificati con le codifiche conosciute da .NET sul rispettivo sistema. I set di caratteri sconosciuti restano invariati.

Protezione dei dati

Un’intestazione completa contiene nomi host interni, indirizzi IP, mittenti, destinatari e oggetto. Il motivo per cui queste informazioni non dovrebbero essere inserite in uno strumento online è spiegato nell’articolo Analizzare le intestazioni e-mail senza caricare l’e-mail. Per il modulo vale la stessa promessa della versione browser: nessun accesso alla rete. La suite di test del modulo include un test che fallisce non appena nel codice sorgente compare un cmdlet di rete o DNS.

Codice sorgente e versioni

Il codice sorgente è disponibile con licenza MIT su GitHub. La logica di analisi è una conversione della libreria usata anche dall’Header Analyzer su questo sito; entrambi condividono i casi di test. La Continuous Integration verifica ogni modifica con PSScriptAnalyzer e Pester su Windows PowerShell 5.1, PowerShell 7 in Windows, Ubuntu e macOS. Le pubblicazioni nella PowerShell Gallery avvengono automaticamente da tag versionati; le modifiche di ogni versione sono riportate nel Changelog.

Accolgo errori e richieste di estensione come issue su GitHub. Anonimizzare i test header per le segnalazioni di errori; i casi di test inclusi utilizzano esclusivamente domini di esempio secondo RFC 2606 e indirizzi secondo RFC 5737.