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 dati TLS, risultati SPF, DKIM, DMARC e ARC inclusa la verifica della provenienza rispetto all’authserv-id del gateway, 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 un report per i ticket. Il modulo opera interamente offline: nessuna query DNS, nessuna connessione HTTP. È la versione a riga di comando dell’analizzatore di intestazioni su questo sito e usa 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[]>
    [-TrustedAuthServId <String[]>]
    [<CommonParameters>]

Path

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

Clipboard

Get-MailHeaderAnalysis
    -FromClipboard
    [-TrustedAuthServId <String[]>]
    [<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 crea la catena di consegna in ordine cronologico, calcola il ritardo per ciascuna stazione e legge versione TLS, cifrario e classe di protocollo secondo RFC 3848. Da Authentication-Results, Received-SPF, DKIM-Signature e dalla catena ARC determina i risultati dell’autenticazione e assegna una provenienza a ogni riga di verifica (RFC 8601, sezione 5): comprovata se il suo authserv-id è in -TrustedAuthServId, altrimenti soltanto plausibile o non comprovata; vedere AuthTrust. 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 né apre connessioni di rete. Spf, Dkim, Dmarc e Arc sono quindi sempre il giudizio del server ricevente. Le firme DKIM e ARC non vengono ricalcolate crittograficamente; per la catena ARC il cmdlet verifica soltanto la struttura (ArcStructure).

Gli input vengono letti in modo tollerante: una riga vuota termina l’intestazione e l’eventuale corpo del messaggio successivo viene ignorato. Le righe prive di nome campo e senza spazio iniziale, come possono risultare copiando da finestre di dialogo del 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, contando dalla consegna.

Esempi

Esempio 1

Get-MailHeaderAnalysis -FromClipboard

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

Subject     : Service-Report für März
From        : Beispiel Newsletter <news@example.org>
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, perché il cmdlet combina 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 riunisce i codici Finding.

Esempio 6

Get-ChildItem .\export\*.eml |
    Get-MailHeaderAnalysis -TrustedAuthServId 'mx.example.org' |
    Where-Object AuthTrust -ne 'Trusted' |
    Select-Object Source, AuthTrust, AuthServId, DeliveredBy

Elenca i messaggi i cui risultati di verifica non provengono dal gateway in ingresso mx.example.org. Nelle analisi di phishing questo è un primo filtro. Senza -TrustedAuthServId si può filtrare soltanto in base a Unmatched; una falsificazione che includa anche una riga Received corrispondente apparirà allora come Matched e passerà il 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, mentre l’array Hops è basato su 0.

Esempio 8

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

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

Parametri

-Header

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

Alias: Text, Raw, InputObject

-Path

Percorso di 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 distinto; 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 se gli appunti sono vuoti.

-TrustedAuthServId

L’authserv-id o gli authserv-id che il gateway in ingresso scrive in Authentication-Results, ad esempio mx.example.org. Il cmdlet confronta in modo esatto, senza distinzione tra maiuscole e minuscole e senza sottodomini. Le righe di verifica con uno di questi ID ricevono AuthTrust = Trusted, e solo esse confluiscono quindi in Spf, Dkim, Dmarc e Arc. Lo stesso vale per receiver= di una riga Received-SPF.

Il risultato è affidabile solo quanto il gateway: deve rimuovere le righe Authentication-Results in entrata che rivendicano il proprio authserv-id (RFC 8601, sezione 5). Non è possibile stabilire da un’intestazione se lo faccia. Se due righe con ID attendibile sono in contraddizione, il cmdlet segnala AuthTrustedConflict. Microsoft 365 non scrive alcun authserv-id nella propria riga di verifica; se Exchange Online riceve la posta, omettere il parametro.

Il valore può essere impostato come predefinito per un’intera sessione, ad esempio nel profilo PowerShell:

$PSDefaultParameterValues['Get-MailHeaderAnalysis:TrustedAuthServId'] = 'mx.example.org'

Input

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

System.IO.FileInfo: oggetti file di Get-ChildItem, la cui proprietà 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 (le spiegazioni in Findings, CompAuthReasonMeaning e nei campi di significato) è in inglese, affinché possa essere inserito invariato nei ticket internazionali. L’output della visualizzazione standard può essere mostrato per intero con Format-List *.

ConvertTo-MailHeaderReport

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

Sintassi

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

Descrizione

Il report include oggetto, mittente, data e Message-ID, risultati dell’autenticazione con indicazione della provenienza e allineamento, tutti i Finding, la catena di consegna, la classificazione Exchange e i valori dei filtri antispam. I caratteri di controllo Unicode per la direzione di scrittura rimangono visibili nel report come <U+...>, affinché non possano passare dal report a 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 report Markdown e lo copia negli appunti.

# Email header analysis

- Subject: Service-Report für März
- From: Beispiel Newsletter <news@example.org>
- Date: 2026-08-03T09:14:27Z
- Message-ID: <20260803091427.4Wq2Wx5RbTz@mail.example.org>

## 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 report come testo senza formattazione Markdown, ad esempio per e-mail o registri 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 associazione.

-Format

Il formato di output. Valori validi:

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

Input

MailHeaderAnalyzer.Analysis: il risultato di Get-MailHeaderAnalysis.

Output

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

Oggetto di output

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

MailHeaderAnalyzer.Analysis

MailHeaderAnalyzer.Hop

Ogni voce 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 inserita in un messaggio da qualsiasi mittente, così come una riga Received corrispondente. Pertanto, dalla sola intestazione non è possibile comprovare chi abbia scritto una riga di verifica. Secondo RFC 8601, sezione 5, è determinante soltanto la riga il cui authserv-id è noto come proprio all’organizzazione ricevente, e il gateway in ingresso deve rimuovere le righe in entrata con questo ID. Il cmdlet implementa questa regola tramite -TrustedAuthServId. Senza questo parametro confronta l’authserv-id soltanto con gli host by della catena Received (stesso dominio o sottodominio, sempre al confine del punto, nessuna sottostringa); è una verifica di plausibilità.

Se l’intestazione contiene righe di verifica di più provenienze, 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.

Con -TrustedAuthServId vengono aggiunti due Finding: AuthNotTrusted, se nessuna riga di verifica reca un ID attendibile, e AuthTrustedConflict, se due righe di questo tipo riportano risultati diversi per spf, dmarc, arc o compauth. Il secondo caso significa che almeno una riga non proviene dal gateway e che il gateway non l’ha rimossa. In questo caso il cmdlet adotta la riga più in alto; dall’intestazione non è possibile stabilire quale delle due sia autentica. DKIM è escluso da questo confronto, poiché più firme possono legittimamente avere risultati differenti.

Catena ARC: struttura e giudizio

Per ARC il cmdlet fornisce due indicazioni separate. Arc è il risultato arc= dalla riga di verifica determinante, ossia il giudizio del destinatario che ha verificato le firme della catena. ArcStructure è la verifica del modulo e riguarda soltanto la struttura secondo RFC 8617: numeri di istanza consecutivi da i=1 a i=n (al massimo 50), esattamente un ARC-Seal, un ARC-Message-Signature e un ARC-Authentication-Results per istanza, nonché cv=none nell’istanza 1 e cv=pass in tutte le successive. Il modulo non ricalcola le firme; pertanto Consistent non dice nulla sull’autenticità della catena. Le discrepanze sono riportate in ArcStructureIssues e nel Finding ArcStructureInconsistent.

Le indicazioni in ARC-Authentication-Results sono affermazioni del rispettivo inoltro. Il Finding DkimBrokenAfterForward classifica quindi un errore DKIM come conseguenza di un inoltro soltanto se il destinatario stesso segnala arc=pass e un’istanza precedente ha registrato un DKIM-pass per lo stesso dominio.

Allineamento DMARC

SpfAlignment confronta il dominio del mittente envelope con il dominio From, mentre DkimAlignment confronta il dominio d= della firma verificata con il dominio From. Strict significa dominio identico, Relaxed lo stesso dominio organizzativo, None nessuna corrispondenza. Il dominio organizzativo viene determinato euristicamente: le ultime due etichette oppure, per finali composti noti quali co.uk o com.au, le ultime tre. 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 è disponibile 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 codici motivo compauth è disponibile nell’articolo Microsoft 365 compauth: codici motivo.

Finding

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

Funzionamento e limiti

Il modulo legge ciò che è presente nell’intestazione e ne deduce ciò che è possibile comprovare senza query esterne. Ne derivano alcuni limiti:

• Nessuna verifica crittografica. Le firme DKIM e ARC non vengono ricalcolate e non vengono interrogati record DNS. Spf, Dkim, Dmarc e Arc sono sempre il giudizio del server ricevente; ArcStructure verifica solo la struttura della catena.
• Provenienza comprovabile solo con conoscenza del gateway. Senza -TrustedAuthServId, AuthTrust è una verifica di plausibilità. Con il parametro, l’affermazione dipende dal fatto che il gateway rimuova le righe di verifica esterne con il proprio authserv-id; il modulo non può verificarlo.
• Solo l’ultima riga Received è comprovata. Tutte le righe sottostanti sono state fornite dal mittente e possono essere modellate arbitrariamente. Attested contrassegna questa differenza; i ritardi degli hop precedenti si basano sulle indicazioni di queste righe.
• Domini organizzativi euristici. Per l’allineamento Relaxed, il modulo usa un breve elenco di finali composti e non una Public Suffix List completa.
• AuthMechanism documentato solo in parte. Oltre al valore 10, Microsoft non ha pubblicato i codici; il modulo non ne inventa i significati.
• Set di caratteri. I valori RFC 2047 sono decodificati con le codifiche note a .NET sul sistema specifico. I set di caratteri sconosciuti rimangono invariati.

Protezione dei dati

Un’intestazione completa contiene nomi host interni, indirizzi IP, mittenti, destinatari e oggetto. Il motivo per cui questi dati non dovrebbero essere inseriti in uno strumento online è spiegato nell’articolo Analizzare 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 contiene 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 è un porting della libreria usata anche dall’analizzatore di intestazioni di questo sito; entrambi condividono i casi di test. L’integrazione continua 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 per versione sono riportate nel changelog.

La versione 0.2.0 del 26 settembre 2026 ha rafforzato il modello di provenienza in seguito a un’osservazione durante una revisione di @saltyslugga: parametro -TrustedAuthServId, livello Trusted, Matched solo come plausibilità. La proprietà ArcValid è stata rimossa e sostituita da ArcStructure e ArcStructureIssues; gli script che analizzano ArcValid devono essere adattati.

Segnalazioni di errori e richieste di miglioramento sono accettate come issue su GitHub. Anonimizzare gli header di test prima di segnalarli; i casi di test inclusi usano esclusivamente domini di esempio secondo RFC 2606 e indirizzi secondo RFC 5737.

Cronologia delle modifiche

• 25 ottobre 2026: sostituita la fonte RFC 7489 con RFC 9989, che sostituisce la specifica DMARC dal maggio 2026.