MailHeaderAnalyzer: analizar encabezados de correo electrónico en PowerShell sin acceso a la red

MailHeaderAnalyzer es un módulo de PowerShell con dos cmdlets. Get-MailHeaderAnalysis analiza el encabezado de un correo electrónico: la cadena de entrega con retrasos e información de TLS, los resultados de SPF, DKIM, DMARC y ARC, incluida la comprobación de si estos resultados proceden del servidor receptor, la alineación de DMARC, la clasificación híbrida de Exchange Online, las evaluaciones de Microsoft Defender, SpamAssassin y Rspamd, así como anomalías como líneas From duplicadas o caracteres de control Unicode. ConvertTo-MailHeaderReport genera a partir de ello un informe para tickets. El módulo funciona completamente sin conexión: sin consultas DNS ni conexiones HTTP. Es la versión de línea de comandos del analizador de encabezados de este sitio web y utiliza la misma lógica de análisis.

Resumen de parámetros

Ambos cmdlets admiten los parámetros comunes -Verbose, -ErrorAction, -ErrorVariable, -OutVariable y los demás de about_CommonParameters.

Instalación

Install-Module -Name MailHeaderAnalyzer -Scope CurrentUser

En un sistema sin acceso a Internet, descargue el módulo en otro equipo con Save-Module -Name MailHeaderAnalyzer -Path C:\Temp y copie la carpeta MailHeaderAnalyzer en un directorio de $env:PSModulePath, por ejemplo %USERPROFILE%\Documents\WindowsPowerShell\Modules (Windows PowerShell 5.1) o %USERPROFILE%\Documents\PowerShell\Modules (PowerShell 7). Update-Module -Name MailHeaderAnalyzer obtiene actualizaciones y Get-Module -Name MailHeaderAnalyzer -ListAvailable muestra la versión instalada.

Get-MailHeaderAnalysis

Analiza el encabezado de un correo electrónico y devuelve un objeto de análisis.

Sintaxis

Text (predeterminado)

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

Path

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

Clipboard

Get-MailHeaderAnalysis
    -FromClipboard
    [<CommonParameters>]

Descripción

El cmdlet descompone el encabezado sin procesar en campos, despliega los plegados RFC 5322 y descodifica valores RFC 2047 en el asunto y las direcciones. A partir de las líneas Received forma la cadena de entrega en orden cronológico, calcula el retraso de cada estación y lee la versión de TLS, el cifrado y la clase de protocolo según RFC 3848. A partir de Authentication-Results, Received-SPF, DKIM-Signature y la cadena ARC determina los resultados de autenticación y comprueba si la línea de verificación procede realmente de una estación de la cadena de entrega (RFC 8601, sección 5). También incluye la alineación de DMARC, la clasificación híbrida de Exchange Online, las evaluaciones de los filtros antispam y una lista de anomalías.

El cmdlet no realiza consultas DNS ni abre conexiones de red. Por ello, Spf, Dkim y Dmarc son siempre el veredicto del servidor receptor, complementado con la comprobación de si dicho veredicto procede de él. Las firmas DKIM no se verifican criptográficamente.

Las entradas se leen de forma tolerante: una línea en blanco finaliza el encabezado e ignora el cuerpo del mensaje posterior. Las líneas sin nombre de campo y sin espacio inicial, como las que se producen al copiar desde diálogos de clientes, pertenecen al campo anterior. Se omite una línea separadora mbox From ... antes del primer campo y se elimina una marca de orden de bytes. Se analizan como máximo 200 líneas Received, contadas desde la entrega.

Ejemplos

Ejemplo 1

Get-MailHeaderAnalysis -FromClipboard

Analiza el encabezado que se encuentra en el portapapeles. En Outlook para Windows encontrará el encabezado en Archivo, Propiedades, Encabezados de Internet; en Outlook en la web, en las opciones del mensaje, en «Ver detalles del mensaje».

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

Ejemplo 2

Get-MailHeaderAnalysis -Path .\nachricht.eml

Analiza un mensaje guardado. El archivo puede contener solo el encabezado o el mensaje completo; el cuerpo del mensaje se ignora.

Ejemplo 3

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

Muestra la cadena de entrega como tabla, con el primer salto primero.

#   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

Ejemplo 4

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

Lee el encabezado línea por línea desde un archivo de texto y muestra solo las anomalías. -Raw en Get-Content no es necesario, ya que el cmdlet combina las líneas por sí mismo.

Ejemplo 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

Analiza todos los mensajes de una carpeta y escribe un archivo CSV con una línea por mensaje. La columna calculada resume los códigos de hallazgos.

Ejemplo 6

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

Enumera los mensajes cuya línea Authentication-Results no procede del sistema de entrega. En análisis de phishing, es un primer filtro rápido.

Ejemplo 7

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

Muestra la estación con el mayor retraso. SlowestHopIndex empieza en 1, mientras que el array Hops empieza en 0.

Ejemplo 8

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

Escribe el análisis completo como JSON. -Depth 6 es necesario porque Hops, DkimSignatures y Exchange son objetos anidados; el valor predeterminado 2 solo los mostraría como nombres de tipo.

Parámetros

-Header

El encabezado como texto. El parámetro acepta una única cadena con todo el encabezado o varias cadenas; las entradas de canalización se recopilan y se combinan al final en un encabezado, por lo que Get-Content datei | Get-MailHeaderAnalysis funciona sin -Raw. Para analizar varios encabezados por separado, use -Path con varios archivos.

Alias: Text, Raw, InputObject

-Path

Ruta a un archivo que contiene el encabezado o un mensaje .eml completo. Las rutas relativas se resuelven respecto al directorio actual. El archivo se lee con [System.IO.File]::ReadAllText: se tiene en cuenta una marca de orden de bytes; sin BOM se usa UTF-8. Cada archivo genera su propio objeto de resultado; los archivos inexistentes producen un error no terminante.

Alias: FullName, PSPath, LiteralPath

-FromClipboard

Lee el encabezado del portapapeles con Get-Clipboard -Raw. El parámetro solo está disponible en Windows; en Linux y macOS el cmdlet termina con un mensaje de error, igual que si el portapapeles está vacío.

Entradas

System.String: líneas de encabezado o el encabezado completo, para -Header.

System.IO.FileInfo: objetos de archivo de Get-ChildItem, cuya propiedad FullName se vincula a -Path.

Salidas

MailHeaderAnalyzer.Analysis: un objeto por cada encabezado analizado. Las propiedades se describen en la sección Objeto de salida.

Notas

El texto de análisis (las explicaciones en Findings, CompAuthReasonMeaning y los campos de significado) está en inglés para que pueda incorporarse sin cambios a tickets internacionales. La salida de la vista predeterminada se puede mostrar íntegramente con Format-List *.

ConvertTo-MailHeaderReport

Genera un informe en Markdown o texto a partir de un objeto de análisis.

Sintaxis

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

Descripción

El informe incluye asunto, remitente, fecha y Message-ID, los resultados de autenticación con indicación de origen y alineación, todos los hallazgos, la cadena de entrega, la clasificación de Exchange y los valores de los filtros antispam. Los caracteres de control Unicode de dirección de escritura permanecen visibles en el informe como <U+...>, para que no lleguen a un sistema de tickets a través del informe. La última línea indica la versión del módulo.

Ejemplos

Ejemplo 1

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

Genera un informe Markdown y lo coloca en el portapapeles.

# 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 |

Ejemplo 2

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

Genera el informe como texto sin formato Markdown, por ejemplo para correos electrónicos o registros de consola.

Ejemplo 3

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

Uso en Exchange Management Shell. Si $env:PSModulePath está restringido allí por directivas de grupo, cargue el módulo con Import-Module y la ruta completa al archivo .psd1.

Parámetros

-Analysis

El objeto de análisis de Get-MailHeaderAnalysis. El cmdlet rechaza otros tipos de objeto con un error de vinculación.

-Format

El formato de salida. Valores válidos:

• Markdown: encabezados, listas y la cadena de entrega como tabla. Predeterminado.
• Text: encabezados en mayúsculas, líneas con sangría y la cadena de entrega como lista numerada.

Entradas

MailHeaderAnalyzer.Analysis: el resultado de Get-MailHeaderAnalysis.

Salidas

System.String: el informe, una cadena por objeto de análisis.

Objeto de salida

Get-MailHeaderAnalysis devuelve un objeto de tipo MailHeaderAnalyzer.Analysis por entrada. La vista predeterminada muestra el resumen del ejemplo 1; se puede acceder a todas las propiedades mediante Select-Object, Format-List * o ConvertTo-Json.

MailHeaderAnalyzer.Analysis

MailHeaderAnalyzer.Hop

Cada entrada en Hops corresponde a una línea Received. El orden es cronológico, es decir, inverso al orden en el encabezado.

AuthTrust: origen de los resultados de verificación

Cualquier remitente puede escribir una línea Authentication-Results en un mensaje. Según RFC 8601, sección 5, solo es determinante la línea de la organización receptora, y su authserv-id debe poder asignarse a una estación de la cadena de entrega. El cmdlet compara el authserv-id de cada línea con los hosts by de la cadena Received (mismo dominio o subdominio, siempre en el límite de punto, sin subcadenas).

Si el encabezado contiene líneas de verificación de varios orígenes, el hallazgo AuthMixedOrigins informa de ello. Si falta una línea de verificación, pero hay una línea Received-SPF, se adopta su resultado como Spf y se identifica con ReceivedSpfOnly.

Alineación de DMARC

SpfAlignment compara el dominio del remitente de sobre con el dominio From; DkimAlignment compara el dominio d= de la firma verificada con el dominio From. Strict significa dominio idéntico, Relaxed el mismo dominio organizativo y None ninguna coincidencia. El dominio organizativo se determina de forma heurística: las dos últimas etiquetas; en terminaciones compuestas conocidas como co.uk o com.au, las tres últimas. No se incluye una Public Suffix List completa.

MailHeaderAnalyzer.ExchangeClassification

Si el encabezado contiene los campos X-MS-Exchange-Organization-*, X-OriginatorOrg o X-MS-Exchange-CrossTenant-*, el cmdlet rellena la propiedad Exchange. Los significados siguen el artículo «Demystifying hybrid mail flow» del equipo de Exchange; los antecedentes se explican en el artículo Encabezados híbridos de Exchange: ¿interno o externo?.

MailHeaderAnalyzer.SpamAssessment

La propiedad Spam resume las evaluaciones de los filtros conocidos. Los valores proceden de sistemas ajenos y se descodifican, pero no se evalúan.

La lista completa de códigos de motivo compauth se encuentra en el artículo Microsoft 365 compauth: códigos de motivo.

Hallazgos

El cmdlet proporciona las anomalías como objetos en Findings, cada uno con Severity (Info, Warning, Fail), un Code estable para filtros y scripts, y una explicación en Message.

Funcionamiento y límites

El módulo lee lo que contiene el encabezado e infiere de ello lo que puede demostrarse sin consultas externas. De ello se derivan algunos límites:

• Sin verificación criptográfica. Las firmas DKIM no se recalculan y no se consultan registros DNS. Spf, Dkim y Dmarc son siempre el veredicto del servidor receptor, complementado con la comprobación de si dicho veredicto procede realmente de él.
• Solo la última línea Received está acreditada. El remitente proporcionó todas las líneas inferiores y puede haberlas creado arbitrariamente. Attested marca esta diferencia; los retrasos de saltos anteriores se basan en los datos de estas líneas.
• Dominios organizativos heurísticos. Para la alineación relajada, el módulo utiliza una lista corta de terminaciones compuestas, no una Public Suffix List completa.
• AuthMechanism solo está parcialmente documentado. Salvo el valor 10, Microsoft no ha publicado los códigos; el módulo no inventa significados.
• Conjuntos de caracteres. Los valores RFC 2047 se descodifican con las codificaciones que .NET reconoce en el sistema correspondiente. Los conjuntos de caracteres desconocidos permanecen sin cambios.

Protección de datos

Un encabezado completo contiene nombres de host internos, direcciones IP, remitentes, destinatarios y asuntos. El motivo por el que estos datos no pertenecen a una herramienta en línea se explica en el artículo Analizar encabezados de correo electrónico sin subir el mensaje. Para el módulo se aplica la misma promesa que para la versión de navegador: sin accesos a la red. La suite de pruebas del módulo incluye una prueba que falla en cuanto aparece un cmdlet de red o DNS en el código fuente.

Código fuente y versiones

El código fuente está disponible bajo licencia MIT en GitHub. La lógica de análisis es una adaptación de la biblioteca que también utiliza el analizador de encabezados de este sitio web; ambos comparten los casos de prueba. La integración continua comprueba cada cambio con PSScriptAnalyzer y Pester en Windows PowerShell 5.1, PowerShell 7 en Windows, Ubuntu y macOS. Las publicaciones en la PowerShell Gallery se realizan automáticamente a partir de etiquetas versionadas; los cambios de cada versión se encuentran en el changelog.

Recibo errores y solicitudes de ampliación como issue en GitHub. Anonimice los encabezados de prueba antes de enviar informes de errores; los casos de prueba incluidos utilizan exclusivamente dominios de ejemplo según RFC 2606 y direcciones según RFC 5737.