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 dell’origine 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 da riga di comando dell’analizzatore delle intestazioni 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 di 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 sono ottenuti da 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 scompone l’intestazione grezza in campi, espande le piegature RFC 5322 e decodifica i valori RFC 2047 nell’oggetto e negli indirizzi. Dalle righe Received forma 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 assegna a ogni riga di verifica un’origine (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 e non 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 sono 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 quelle generate copiando dalle finestre di dialogo dei client, appartengono al campo precedente. Una riga separatrice mbox From ... prima del primo campo viene ignorata e un Byte Order Mark viene rimosso. 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 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 testo 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 unisce le righe autonomamente.

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 di rilevamento.

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 dell’organizzazione. Nelle analisi di phishing questo è un primo filtro. Senza -TrustedAuthServId si può filtrare soltanto per Unmatched; una falsificazione che include anche una riga Received corrispondente appare quindi come Matched e passa 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 come JSON. -Depth 6 è necessario perché Hops, DkimSignatures e Exchange sono oggetti annidati; il valore predefinito 2 li mostrerebbe solo 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 alla fine uniti in un’intestazione, pertanto Get-Content datei | Get-MailHeaderAnalysis funziona senza -Raw. Per analizzare più intestazioni separatamente, 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 considerato un Byte Order Mark, senza BOM viene usato 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; su Linux e macOS il cmdlet termina con un messaggio di errore, così come con appunti 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 effettua il confronto esatto, senza distinzione tra maiuscole e minuscole e senza sottodomini. Le righe di verifica con uno di questi ID ricevono AuthTrust = Trusted, e soltanto esse confluiscono quindi in Spf, Dkim, Dmarc e Arc. Lo stesso vale per il receiver= di una riga Received-SPF.

Il risultato è affidabile solo quanto il gateway: esso deve rimuovere le righe Authentication-Results in ingresso 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 conflitto, il cmdlet segnala AuthTrustedConflict. Microsoft 365 non scrive un authserv-id nella propria riga di verifica; se Exchange Online riceve la posta, omettere il parametro.

Per un’intera sessione, il valore può essere memorizzato come predefinito, 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 da 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 (spiegazioni in Findings, CompAuthReasonMeaning e nei campi di significato) è in inglese per poter essere inserito invariato nei ticket internazionali. L’output della visualizzazione predefinita può essere mostrato completamente con Format-List *.

ConvertTo-MailHeaderReport

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

Sintassi

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

Descrizione

Il report comprende oggetto, mittente, data e Message-ID, risultati di autenticazione con indicazione dell’origine e allineamento, tutti i rilevamenti, la catena di consegna, la classificazione Exchange e i valori dei filtri antispam. I caratteri di controllo Unicode per la direzione della scrittura rimangono visibili nel report come <U+...>, affinché non arrivino in un sistema di ticket tramite il report. 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 inserisce 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

Restituisce 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 da Get-MailHeaderAnalysis. Il cmdlet rifiuta altri tipi di oggetti 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 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 voce in Hops corrisponde a una riga Received. L’ordine è cronologico, quindi inverso rispetto all’ordine nell’intestazione.

AuthTrust: origine dei risultati di verifica

Una riga Authentication-Results può essere scritta nel messaggio dal mittente stesso, così come una riga Received corrispondente. Dalla sola intestazione non è pertanto possibile dimostrare chi abbia scritto una riga di verifica. Secondo RFC 8601, sezione 5, è determinante soltanto la riga il cui authserv-id è noto all’organizzazione ricevente come proprio, e il gateway in ingresso deve rimuovere le righe in ingresso con questo ID. Il cmdlet implementa questa regola con -TrustedAuthServId. Senza questo parametro confronta l’authserv-id solo con gli host by della catena Received (stesso dominio o sottodominio, sempre al confine del punto, nessuna sottostringa); si tratta di una verifica di plausibilità.

Se l’intestazione contiene righe di verifica di origini diverse, il rilevamento 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 rilevamenti: 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 indica 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ù alta; dalla sola intestazione non è possibile decidere quale delle due sia autentica. DKIM è escluso da questo confronto, poiché più firme possono legittimamente avere risultati diversi.

Catena ARC: struttura e giudizio

Per ARC il cmdlet fornisce due informazioni separate. Arc è il risultato arc= della riga di verifica determinante, ossia il giudizio del destinatario che ha verificato le firme della catena. ArcStructure è la verifica propria del modulo e riguarda solo la struttura secondo RFC 8617: numeri di istanza consecutivi i=1 fino 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; Consistent non afferma quindi nulla sull’autenticità della catena. Le discrepanze sono riportate in ArcStructureIssues e nel rilevamento ArcStructureInconsistent.

Le informazioni in ARC-Authentication-Results sono dichiarazioni del rispettivo inoltro. Il rilevamento DkimBrokenAfterForward classifica quindi un errore DKIM come conseguenza di un inoltro solo se il destinatario stesso riporta 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 indica un dominio identico, 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 riunisce 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.

Rilevamenti

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 è presente nell’intestazione e ne deduce ciò che può essere dimostrato senza query esterne. Ne derivano alcuni limiti:

• Nessuna verifica crittografica. Le firme DKIM e ARC non vengono ricalcolate e le voci DNS non vengono interrogate. Spf, Dkim, Dmarc e Arc sono sempre il giudizio del server ricevente; ArcStructure verifica soltanto la struttura della catena.
• L’origine è comprovabile solo conoscendo il gateway. Senza -TrustedAuthServId, AuthTrust è una verifica di plausibilità. Con il parametro, l’affermazione dipende dal fatto che il gateway rimuova le righe di verifica estranee 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 strutturate arbitrariamente. Attested contrassegna questa differenza; i ritardi degli hop precedenti si basano sulle informazioni di tali righe.
• Domini organizzativi euristici. Per l’allineamento relaxed, il modulo utilizza un breve elenco di terminazioni multipartite, non una Public Suffix List completa.
• AuthMechanism documentato solo in parte. Oltre al valore 10, Microsoft non ha pubblicato i codici; il modulo non inventa significati.
• Set di caratteri. I valori RFC 2047 vengono decodificati con le codifiche note a .NET nel sistema in uso. I set di caratteri sconosciuti restano invariati.

Privacy

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 è illustrato 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 contiene un test che fallisce non appena nel codice sorgente appare 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 utilizzata anche dall’analizzatore delle intestazioni 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 con versione; le modifiche per versione sono disponibili nel changelog.

La versione 0.2.0 del 26 settembre 2026 ha rafforzato il modello di origine dopo un’osservazione nella 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 adeguati.

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