关于本说明文档

• 1: 概述
• 2: 输出格式
• 3: 参数和选项
• 4: 性能
• 5: 与分析工具的集成
• 6: 运营最佳实践
• 7: 故障排除
• 8: 模块命令参考
• 8.1: Convert-DNSDebugLogFile
• 9: 使用示例
• 9.1: 使用 SQL Server 的安全分析工作流
• 9.2: 域环境中的实际应用（基于 GPO 的收集与转换）
• 9.3: 计划任务示例

1 - 概述

Windows DNS 服务器可以写入调试日志。它是一个纯文本文件，设计供人类阅读，在繁忙的域控制器上每天会增长数百兆字节。这样的组合使得当你想回答诸如*“昨晚哪个客户端查询了这个域名 40,000 次？”*这样的问题时，几乎毫无用处。

DNSServer.DebugLogParser 将该文本文件转换为 CSV 表格。一条日志行变成一行带有命名列的记录，这样你就可以用 Excel 打开它，加载到 Power BI，批量插入到 SQL Server，或者发送到你的 SIEM。

该模块包含一个命令：

Convert-DNSDebugLogFile -InputFile "C:\Windows\System32\dns\dns.log"

这就是整个入口点。本站的其他内容都是关于如何大规模、定时以及跨多台服务器执行转换。

DNS 调试日志的样子

原始条目是一行带有位置字段的文本，其中一些字段用括号括起来：

2026-01-20 23:00:16 0FE0 PACKET 000002C53117D990 UDP Rcv 10.0.0.2 c049 Q [0001 D NOERROR] A (3)odc(9)officeapps(4)live(3)com(0)

转换后，同一事件变成可筛选和排序的 CSV 行：

DateTime;ThreadId;Context;PacketId;Protocol;Direction;ClientIP;Xid;Type;Opcode;FlagsHex;FlagsChar;ResponseCode;QuestionType;QuestionName;Information;Details;ComputerName
2026-01-20 23:00:16;0FE0;Packet;000002C53117D990;UDP;Rcv;10.0.0.2;c049;Query;Standard;0001;RecursionDesired;NOERROR;A;"odc.officeapps.live.com";"";"";dc01

注意原始格式难以处理而解析器帮你处理的两点：

• 查询的名称以 DNS 线格式存储，即 (3)odc(9)officeapps(4)live(3)com(0)，转换后变成正常的 FQDN。
• 一个事件不总是单行。PACKET 详情块和事件消息会继续出现在缩进的后续行。解析器会将它们附加到所属记录，而不是丢弃或生成孤立行。

每条记录最多包含 16 个原生字段——时间戳、协议、方向、客户端 IP、查询类型、查询名称、响应代码、标志等。完整列列表详见输出格式。

为什么要转换

故障排除

• 查明名称无法解析的原因，以及查询是否到达服务器
• 识别配置错误的客户端或频繁请求服务器的应用
• 跟踪问题查询的实际来源
• 验证区域传送和 DNS 的整体行为

性能与容量

• 按查询量排名客户端，找出“吵闹”的客户端
• 查看哪些记录类型主导流量
• 发现导致不必要查询的配置错误
• 跟踪服务器负载变化，而不是凭猜测

安全分析

• 检测 DNS 隧道和数据外泄（通常表现为过多的 TXT 流量——参见SQL Server 分析示例）
• 查找针对恶意软件和指挥控制域的查询
• 识别被攻陷主机的查询模式
• 监控 DNS 放大攻击滥用
• 重建事件发生过程

合规与审计

• 满足日志记录和保留要求
• 保持网络活动的审计轨迹
• 为管理层或审计员生成报告

模块工作原理

Convert-DNSDebugLogFile 以流方式读取日志并以流方式写入 CSV。文件从未整体加载到内存，因此 100 MB 的日志消耗的内存大致与 10 MB 的日志相同。详情见性能。

它提供的功能：

活动日志与轮换日志

实际操作模式是启用 DNS 服务器的日志轮换，让定时转换跳过最新文件：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME

基于组策略的完整实现记录在基于 GPO 的收集示例中。

下一步去哪儿

• 输出格式 — 列含义及真实示例文件
• 参数和选项 — 详细解释各种参数
• 性能 — 为什么快以及如何保持快速
• 集成 — Excel、Power BI、SQL、SIEM、Python
• 运维最佳实践 — 生产环境运行指南
• 使用示例 — 定时任务、GPO 部署、SQL 分析
• 命令参考 — 权威参数列表

许可和支持

MIT 许可证。社区支持通过 GitHub Issues 进行，欢迎提交错误报告和功能请求。

• GitHub 仓库：AndiBellstedt/DNSServer.DebugLogParser
• PowerShell Gallery：DNSServer.DebugLogParser

2 - 输出格式

Convert-DNSDebugLogFile 每个输入日志最多生成三个文件：

Both 是默认值。输出文件会放在输入文件旁边，除非你设置了 -OutputFile。

本页链接的示例文件是真实的转换结果，而非模拟。下载一个并用 Excel 打开，确认后再设计你的管道。

CSV 数据文件

示例输出：

真实转换的两行示例——一个 DNS 查询和一个服务器内部备注：

DateTime;ThreadId;Context;PacketId;Protocol;Direction;ClientIP;Xid;Type;Opcode;FlagsHex;FlagsChar;ResponseCode;QuestionType;QuestionName;Information;Details;ComputerName
2026-01-20 23:00:16;0FE0;Packet;000002C53117D990;UDP;Rcv;10.0.0.2;c049;Query;Standard;0001;RecursionDesired;NOERROR;A;"odc.officeapps.live.com";"";"";dc01
2026-01-20 23:00:16;DF0;Note;;;;;;;;;;;;"";"got GQCS failure on a dead socket context status=995, socket=904";"";dc01

列说明

始终有 18 列，且顺序固定：

需要注意两点：

• 并非每行每列都有数据。 只有 Packet 条目有客户端 IP、查询名称和响应码。Note 和 Event 行的文本在 Information 中，协议相关列为空。请据此设计数据库结构和仪表盘过滤器。
• ComputerName 总是最后一列，即使未使用 -ComputerName 参数。 此时该列为空。这样所有服务器的布局一致，方便合并多个 DNS 服务器的文件，无需列映射。

Details 列

只有当 DNS 服务器配置为记录完整包细节时，才会出现细节块。存在时，解析器将其转换为单个 JSON 值，使该行仍为一行：

{
  "Socket": "848",
  "Remote": "addr 10.10.0.11, port 60580",
  "Buflength": "0x10000 (65536)",
  "Message": {
    "XID": "0x0001",
    "OPCODE": "0 (QUERY)",
    "RCODE": "0 (NOERROR)",
    "QUESTION": [ { "Name": "berlin.de", "QTYPE": "A (1)", "QCLASS": "1" } ],
    "ANSWER": []
  }
}

解析这些块会消耗时间并显著增加 CSV 文件大小。如果不需要，使用 -NoDetailsParsing 参数——该列仍存在但为空，转换速度更快。详见性能。

统计文件

统计是每日汇总。当你想要趋势或汇总数据，而不想移动完整记录集时使用——它们比数据文件小几个数量级。

上下文统计（*_Statistic.csv）

回答：每天发生了多少种类的活动？

Date;Context;Count;ComputerName
2026-01-20;Event;2;dc01
2026-01-20;Note;2;dc01
2026-01-20;Packet;12;dc01

示例文件：en-US WithComputerName, en-US NoComputerName, de-DE WithComputerName, de-DE NoComputerName

包统计（*_PacketStatistic.csv）

回答：谁查询了什么，频率如何，每天？

Date;ClientIP;Protocol;Direction;QuestionType;Count;ComputerName
2026-01-20;10.0.0.1;UDP;Rcv;A;3;dc01
2026-01-20;10.0.0.1;UDP;Snd;A;3;dc01
2026-01-20;10.0.0.2;UDP;Rcv;A;3;dc01

示例文件：en-US WithComputerName, en-US NoComputerName, de-DE WithComputerName, de-DE NoComputerName

分隔符和日期格式

两种输出类型都支持 -Delimiter（默认 ;）和 -OutputCulture。对于机器导入，建议使用类似 ISO 的时间戳格式：

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputCulture 'sv-SE'

这会生成 2026-01-20 23:00:16，SQL Server、Power BI 和 pandas 都能无格式提示正确读取。详情见参数和选项。

3 - 参数和选项

本页以通俗语言解释各选项，且按你通常需要的顺序排列。它是指南，不是规范——权威且始终最新的参数列表在命令参考和：

Get-Help Convert-DNSDebugLogFile -Full

简短版

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log"

这单行命令已经给你合理的行为：同时生成数据和统计文件，分隔符为分号，使用你机器的日期格式，启用头部验证，源日志不变。以下内容是微调。

输入和输出

-InputFile

要转换的日志路径。接受数组，也接受管道输入——这就是为什么下面这样写有效：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" | Convert-DNSDebugLogFile

Get-ChildItem 输出带有 FullName 属性的对象，-InputFile 通过属性名接受它（别名包括 FullName、Path、FilePath）。无需 ForEach-Object。

本地路径和 SMB/UNC 路径都支持：

Convert-DNSDebugLogFile -InputFile "\\dc01\C$\Administration\Logs\DNSServer\dns.log"

命令还能打开 DNS 服务器当前打开的日志。使用前请参阅下面的活动日志。

-OutputFile

不指定时，CSV 文件会放在输入文件旁，基名相同，扩展名为 .csv。指定后，你控制目标位置。

-Delimiter

默认是分号，因为在逗号是小数点分隔符的地区，Excel 期望使用分号。对于假定经典逗号分隔值的工具和数据库，使用 -Delimiter ","；制表符用 -Delimiter "`t"。

无论选什么，导入时用相同的值。不匹配是“所有内容都挤到一列”的头号原因。

标记和过滤

-ComputerName

填充 ComputerName 列。该列无论如何都会存在；此选项只是赋值。

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ComputerName $env:COMPUTERNAME

当多个服务器合并到一个数据集时，务必设置它——否则事后无法区分哪行来自哪个 DC。

-OutputType

• CSV — 仅数据文件
• Statistic — 仅两个汇总文件，无行级数据
• Both — 三个文件都生成 (默认)

当只需每日趋势时，Statistic 是快速且小巧的选项。下游系统自行聚合时，选 CSV。

-ContextFilter

DNS 调试日志混合了实际查询流量和服务器内部通信。-ContextFilter 决定哪些内容保留到输出。

# 仅真实 DNS 流量
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter Packet

# 流量加服务器事件，但无诊断注释
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter Packet, Event

其他上下文类型（DSPoll、Init、Lookup、Recurse、Remote、Tombstone）包含在 All 中。

过滤为仅 Event 或 Note 时，仅填充 DateTime、ThreadId、Context 和 Information——协议列为空，因为这些条目不携带该信息。

-ContextFilter Packet 是安全和报告管道的常用选择：它去除噪声，显著缩小输出。

国际日志

DNS 服务器以其运行机器的 Windows 区域设置写时间戳。德国 DC 写 20.01.2026 23:00:16；美国服务器写 1/20/2026 11:00:16 PM。如果工作站区域设置与服务器不同，解析会出错——更糟的是，日期和月份会被悄悄交换。

-InputCulture

告诉解析器源日志使用的区域设置：

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns-berlin.log" -InputCulture 'de-DE'

默认是运行命令的会话文化。在混合区域环境中，显式设置它而非依赖默认——且记住以 SYSTEM 运行的计划任务可能没有你交互测试时的文化。

-OutputCulture

控制时间戳写入 CSV 的格式：

# 类 ISO 输出，SQL Server、Power BI 和 pandas 都能理解
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputCulture 'sv-SE'

# 同效果，显式不变文化
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" `
    -OutputCulture ([System.Globalization.CultureInfo]::InvariantCulture)

经验法则：如果人用 Excel 打开文件，匹配本地文化；机器读取时，使用 sv-SE 或不变文化，别担心导入端的区域设置。

这两个参数独立——你可以读取瑞典日志，写出美式格式。

速度和存储

-NoDetailsParsing

如果 DNS 服务器记录完整数据包细节，解析器会把每个细节块转成 Details 列的 JSON。这有用，但也是运行中最耗时的部分，且膨胀 CSV。

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -NoDetailsParsing

该列仍存在但为空；TCP/UDP 细节头行仍在 Information 中。细节块丰富的日志可节省 30–50% 处理时间。只要查询级信息够用，就用它。

-CompressOutput

压缩生成的 CSV 文件，删除未压缩文件。dns.log 生成 dns.zip 替代 dns.csv。

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput

此类 CSV 通常压缩率 90% 以上，归档和网络传输几乎免费节省存储。

-RemoveSourceFile

成功转换后删除源 .log 文件——仅当所有输出文件都创建成功时才删除。

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput -RemoveSourceFile

保护措施

-SkipHeaderValidation

默认命令会检查文件是否真的是 DNS 服务器调试日志，才开始解析。这样能捕获指向错误文件夹的经典错误。

仅对真正不寻常的情况关闭：手工编辑日志、预过滤提取、自定义格式。其他情况保持开启——它开销小，是防止拼写错误导致垃圾行的屏障。

-WhatIf 和 -Confirm

命令支持两者。-WhatIf 是查看新批处理会影响哪些文件的正确方式：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Convert-DNSDebugLogFile -RemoveSourceFile -WhatIf

-Confirm 在处理每个文件、删除源文件和覆盖现有输出前都会提示。

活动日志

Convert-DNSDebugLogFile 可以读取 DNS 服务器当前打开的文件。方便临时查看当前情况。

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME

综合示例

域控制器上的典型生产调用：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile `
        -ComputerName $env:COMPUTERNAME `
        -Delimiter ';' `
        -OutputType Both `
        -ContextFilter Packet `
        -OutputCulture 'sv-SE' `
        -CompressOutput

意思是：取除活动日志外的所有轮换日志，仅保留 DNS 流量，用服务器名标记每行，写机器可读时间戳，留下压缩档案。完整的计划任务和组策略版本见GPO 驱动的收集示例。

4 - 性能

繁忙域控制器上的 DNS 调试日志文件很大。Convert-DNSDebugLogFile 就是为这种情况设计的：它已经经过测试，能够处理 100 MB 及以上的日志，并且在普通服务器硬件上几分钟内完成处理。

为什么它很快

你不需要了解这些细节就能使用该模块，但了解这些可以解释你观察到的行为。

重要的结果是：整个日志文件从未全部加载到内存中。 一个 500 MB 的日志不需要 500 MB 的内存。这就是该模块与大多数自制脚本“读取文件、拆分、构建对象”方法的区别——后者在处理 5 MB 样本时表现良好，但在真实的域控制器日志上会崩溃。

如何最大化运行效率

转换轮换的日志块，而不是一个巨大的文件

配置 DNS 服务器在可控大小时滚动日志——50 到 200 MB 是个不错的范围。多个中等大小的文件转换时间可预测，且允许计划任务在时间窗口内完成。而一个不断增长的文件最终会拖慢速度。

日志轮换还会生成已关闭的文件，这正是你想要的：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME

不需要详细解析时跳过

如果 DNS 服务器写入了完整的数据包详情，将这些块转换为 JSON 是转换过程中最耗时的部分。

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -NoDetailsParsing

在包含许多详情块的日志上，转换速度可提升 30–50%，且生成的 CSV 文件更小。你仍然会获得查询级别的数据和 Information 中的 TCP/UDP 详情头行。详见参数和选项。

早期过滤

-ContextFilter Packet 会在写入之前丢弃服务器注释和事件。输出减少意味着 I/O 减少，文件更小，下游处理更轻松。

只请求你需要的内容

-OutputType Statistic 完全跳过写入行级 CSV。如果你的仪表盘只显示每日计数，这是最节省资源的选项。

本地转换，移动结果

模块支持读取 SMB/UNC 路径，但将 200 MB 的原始日志通过网络拉取到中央解析效率低下。建议在 DNS 服务器上转换，然后移动（压缩后的）CSV 文件——通常只有原始日志大小的十分之一。这是基于 GPO 的收集示例的设计思路。

压缩以便传输和归档

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput

此类 CSV 通常可压缩 90% 以上。压缩会在运行结束时消耗少量 CPU，但之后节省大量磁盘和网络资源。

当运行速度比预期慢时

请按顺序检查以下几点：

1. 磁盘，而非 CPU。 转换过程 I/O 密集。日志位于繁忙卷上或通过慢速链路读取，会成为运行时间的瓶颈。
2. 详情块。 如果日志包含完整数据包详情且未使用 -NoDetailsParsing，时间主要花在这里。
3. 文件大小。 单个多 GB 的日志无论如何都会耗时。应通过日志轮换解决，而非参数调整。
4. 杀毒软件。 实时扫描源日志和生成的 CSV 会使有效 I/O 成本翻倍。为日志目录设置排除是常见且合理的措施。
5. 内存压力。 模块采用流式处理，理论上不会导致问题，但服务器如果已经在交换，会导致整体变慢。

更多症状和解决方案请参见故障排除。

5 - 与分析工具的集成

转换 DNS 调试日志的意义在于后续的处理。选择 CSV 是因为几乎所有工具都能读取它——但“所有工具都能读 CSV”背后隐藏着两个设置，这两个设置决定了导入是轻松完成还是要折腾一下午。

决定一切的两个设置

分隔符。 默认是 ;。对于使用逗号作为小数点的 Excel 区域设置，保持默认即可。对于大多数数据库和数据科学工具，切换为 ,。无论选择哪个，都要确保导入端使用相同的设置。

日期格式。 -OutputCulture 控制时间戳的写入格式。对于机器读取的任何内容，使用 sv-SE（或不变文化），这样 DateTime 会输出为 2026-01-20 23:00:16：

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputCulture 'sv-SE'

下面所有消费者都能无提示地理解该格式。区域特定的输出如 20.01.2026 会被导入为文本，或者更糟，被误读为月/日格式。

Microsoft Excel

查看单个转换日志的最快方式。

• 使用默认的 ; 分隔符且区域设置匹配时，双击文件即可正确分列打开。
• 如果所有内容都落在 A 列，说明分隔符与 Excel 设置不匹配。可以重新运行时加上 -Delimiter ","，或者通过 数据 → 从文本/CSV 导入时选择正确的分隔符。
• 将区域转换为表格（Ctrl+T），然后基于 ClientIP、QuestionName 或 QuestionType 创建数据透视表。找出最活跃的客户端和域名只需一分钟。
• 超过几十万行时，建议使用 Power Query 或下面介绍的其他选项。

*_Statistic.csv 和 *_PacketStatistic.csv 文件通常是更好的 Excel 目标——它们是预聚合的，文件体积小。详见输出格式。

Power BI

导入 CSV 文件，构建 DNS 活动、顶级客户端、查询趋势和错误率的仪表盘。

• 指向包含转换文件的文件夹，而非单个文件。不同服务器和日期的布局相同，文件会自动追加。
• ComputerName 列使多服务器报告成为可能——转换时设置 -ComputerName，否则无法按服务器切片。
• ResponseCode 和 QuestionType 是自然的切片字段；DateTime 作为时间轴。
• 使用 *_PacketStatistic.csv 而非完整数据文件，可以在只需日趋势时保持模型体积小。

SQL 数据库

将 CSV 批量导入 SQL Server、PostgreSQL 或其他支持 SQL 的数据库，实现长期存储和可重复查询。

一套现成的操作流程——表定义、转换、SqlBulkCopy 导入及检测可疑 TXT 活动的查询——详见使用 SQL Server 的安全分析工作流。

首次导入前值得规划的要点：

• 使用 -OutputCulture 'sv-SE'，使时间戳直接落入 datetime2 列，无需转换技巧。
• Information 和 Details 字段可能很长，建议用 nvarchar(max)。
• 索引你实际查询的字段——通常是 DateTime、ClientIP 和 QuestionName。
• 保持 -ComputerName 字段填充，合并后仍能追踪来源。

SIEM 系统

Splunk、Elastic、Sentinel 等平台通过 CSV 进行安全遥测的关联和告警。

• 发送压缩输出（-CompressOutput）——体积约为原文件的十分之一，大多数采集器能自动解压。
• 字段映射定义一次即可；列布局在不同运行和服务器间保持不变，包括始终存在的尾部 ComputerName 列。
• 让采集器去重，或者归档已处理的 .log 文件。否则重复处理同一轮换日志会重复发送相同数据。
• -ContextFilter Packet 在不需要服务器注释的场景下，降低采集量（及许可费用）。

Python、R 和数据科学工具

结构化输出可直接用于异常检测、基线分析和自定义分析。

import pandas as pd

df = pd.read_csv(
    r"C:\Administration\Logs\DNSServer\dns.csv",
    sep=";",
    parse_dates=["DateTime"],
)

# 查询次数最多的前 20 个名称，仅限查询方向
top = (
    df[df["Direction"] == "Rcv"]
    .groupby("QuestionName")
    .size()
    .sort_values(ascending=False)
    .head(20)
)
print(top)

parse_dates 在使用 -OutputCulture 'sv-SE' 导出时开箱即用。接下来，pandas、scikit-learn 或 R 可以照常处理聚类、季节性和异常检测。

继续使用 PowerShell

你不必离开 PowerShell 就能快速得到答案：

$dns = Import-Csv "C:\Administration\Logs\DNSServer\dns.csv" -Delimiter ';'

# 最活跃的客户端
$dns | Where-Object Direction -eq 'Rcv' |
    Group-Object ClientIP |
    Sort-Object Count -Descending |
    Select-Object -First 10 Count, Name

# 查询失败的记录
$dns | Where-Object ResponseCode -eq 'NXDOMAIN' |
    Group-Object QuestionName |
    Sort-Object Count -Descending |
    Select-Object -First 10 Count, Name

Import-Csv 会将整个文件读入内存，适合处理轮换后的文件块，不适合多 GB 的导出文件——这时应使用数据库或 SIEM 方案。

6 - 运营最佳实践

手动转换日志很简单。关键是如何设计，让它能每晚在每个域控制器上运行多年而无人干预。这些是实践中重要的点。

1. 转换已轮换的日志，而非活动日志

在 DNS 服务器上启用日志轮换，只转换已关闭的文件。模块可以读取 DNS 服务器当前正在写入的日志，但该文件在转换过程中会发生变化：最新的条目可能缺失，最后一条记录可能被截断。两次运行会产生不同的结果。

标准做法是跳过最新的文件：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME

需要权衡的是：在低流量服务器上，轮换可能超过一天，因此当天的数据会一直未转换，直到文件轮换。请据此调整轮换阈值。

2. 计划任务，并赋予合适的身份运行

任务计划程序是常用方案——每天运行是合理的默认。针对域控制器的完整组策略实现，请参见 基于 GPO 的收集示例，独立任务示例见 计划任务示例。

这里常见的三个坑：

• 模块可发现性。 以 SYSTEM 身份运行且带 -NoProfile 的任务只会看到机器范围的模块路径。请将模块安装为机器范围，或在任务动作中显式添加 Import-Module。
• 区域设置。 运行任务的账户可能没有你交互测试时的区域设置。请显式设置 -InputCulture 和 -OutputCulture，不要依赖默认值。
• 网络访问。 如果源或目标是 UNC 路径，SYSTEM 会以计算机账户身份认证。请授予计算机账户（或 Domain Controllers 组）共享和 NTFS 权限，或使用专用服务账户运行任务。

3. 轮换到你能处理的大小

每个文件 50–200 MB 让转换可预测，且夜间任务能在时间窗内完成。单个文件无限增长最终会拖慢转换。详见 性能。

4. 自动化前先验证首批输出

手动转换两三个真实日志，打开 CSV 检查：

• 时间戳正确吗——没有日/月颠倒？（如果有，设置 -InputCulture。）
• 分隔符符合下游需求吗？
• ComputerName 字段是否填充？
• 需要的上下文是否存在，不需要的是否被过滤？

-WhatIf 会显示批处理将处理哪些文件，但不实际操作：

Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Convert-DNSDebugLogFile -RemoveSourceFile -WhatIf

5. 决定处理完的日志如何处置

仅转换“除最新之外的所有日志”的任务会每天重复处理相同文件。这样简单且稳健，但会覆盖输出，可能导致下游出现重复行。

选一种方案：

• 将处理过的 .log 文件移动到归档文件夹
• 在信任管道后用 -RemoveSourceFile 删除它们
• 让下游采集器去重

无论选哪种，都要写下来——这是让后续管理员不迷惑的细节。

6. 规划存储和保留

压缩（-CompressOutput）通常能让 CSV 减少 90% 以上，但数据量仍会积累。根据实际查询率和保留义务估算，设定数据的终止日期，避免无限增长。

长期保留时，考虑使用 -OutputType Statistic：每日汇总数据体积小，且通常能回答旧的行级数据所关注的趋势问题。

7. 将输出视为敏感信息

解析后的 DNS 日志描述了你的内部命名结构和查询内容，比大多数基础设施日志更具泄露风险，且在某些司法辖区可能被视为个人数据。

• 限制输出文件夹的 NTFS 和共享权限。
• 不要“临时”将 CSV 放在通用文件共享上。
• 将 DNS 日志数据纳入保留和删除策略，而非仅备份策略。
• 压缩输出只是减小体积，不等于保护——关键时刻请使用加密或访问控制。

8. 保持头部验证开启

默认的文件头验证确保文件确实是 DNS 调试日志，零成本且防止路径错误导致成千上万无意义行。仅对真正不寻常的格式使用 -SkipHeaderValidation，且注意命令不允许与 -RemoveSourceFile 一起使用，正是基于此原因。

9. 监控任务，而不仅仅是服务器

无人值守的转换悄无声息地停止，比不转换更糟，因为只有在需要数据时才发现缺口。

• 关注非零错误输出；GPO 参考实现故意在 $Error.Count -gt 0 时抛出异常，让任务报告失败。
• 监控计划任务的最后结果代码，而不仅仅是任务是否存在。
• 检查输出文件是否真的出现且时间戳是最近的。
• 监控日志卷和输出目标的剩余磁盘空间。

常见失败原因——访问被拒、日志损坏、无效头部——详见 故障排除。

10. 记录工作流程

日志写在哪儿，任务何时运行，使用了哪些参数，输出去哪儿，谁消费，保留多久。六行运维 Wiki 内容。它让整个设置可审计且易于交接。

7 - 故障排除

“该文件不是有效的 DNS 调试日志文件”

头部检查拒绝了输入。通常是路径错误——同一文件夹下的 .log 文件不是 DNS 调试日志，或者文件只包含了一个轮换头部。

请按以下步骤排查：

1. 打开文件。DNS 调试日志以类似 Message logging started at … 的头部行开始，后续是带时间戳的查询条目。

2. 确认 DNS 调试日志确实已启用并写入你预期的路径：

   Get-DnsServerDiagnostics | Select-Object Enable, LogFilePath, MaxMBFileSize
   

3. 如果文件确实是 DNS 日志，但头部不寻常——手动编辑过、预过滤过、或自定义导出——可跳过检查：

   Convert-DNSDebugLogFile -InputFile "C:\Logs\odd.log" -SkipHeaderValidation
   

其他地方请保持验证开启。注意 -SkipHeaderValidation 不能与 -RemoveSourceFile 一起使用，因此未经验证的文件转换后无法被删除。

输出文件为空或行数远少于预期

请按顺序检查：

• 日志中是否包含查询条目？ 刚轮换的日志如果还没发生查询，可能只有头部。
• 是否使用了 -ContextFilter？ -ContextFilter Packet 会移除 Event 和 Note 条目。如果过滤为 Event 或 Note，大多数列也会为空——这些条目只包含 DateTime、ThreadId、Context 和 Information。
• 源日志是否仍在写入？ DNS 服务器正在写入的文件在转换时可能变化；最新条目可能缺失，最后一条记录可能被截断。需要完整输出时，请转换已轮换且关闭的日志。
• 文件是否损坏或截断？ 检查日志末尾是否有半写入的行。

日期错误、偏移或日月颠倒

日志由与转换会话不同 Windows 区域设置的服务器写入。20.01.2026 和 01/20/2026 表示同一时间，但前提是双方对格式达成一致。

# 日志来自德国服务器
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns-berlin.log" -InputCulture 'de-DE'

计划任务中请显式设置 -InputCulture，不要依赖运行账户的区域设置。如果输出需要机器可读，添加 -OutputCulture 'sv-SE'。详情见参数和选项。

导入后所有内容都在一列

分隔符不匹配。模块默认写入 ;，而你的导入程序期望 ,（或反之）。

要么重新运行转换，指定导入程序需要的分隔符：

Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -Delimiter ","

…要么告诉导入程序文件使用的分隔符——Excel 中通过 数据 → 从文本/CSV，PowerShell 中通过 Import-Csv -Delimiter ';'。

“访问被拒绝”

• DNS 日志目录通常需要管理员权限。以提升权限启动 PowerShell，或用有访问权限的账户运行计划任务。
• 检查输出目录的写权限，不仅是日志的读权限。
• 对 SMB/UNC 路径：以 SYSTEM 运行的任务在网络上以计算机账户身份认证。请授予该计算机账户（或 Domain Controllers 组）共享和 NTFS 权限，或使用专用服务账户。
• 如果 -RemoveSourceFile 在成功运行后失败，说明账户有读取权限但无删除权限。

处理速度非常慢

1. 先看磁盘——转换受 I/O 限制。繁忙的卷或慢速网络路径会主导运行时间。
2. 如果不需要数据包详细 JSON，使用 -NoDetailsParsing；对细节丰富的日志可节省 30–50% 时间。
3. 使用 -ContextFilter Packet 减少写入量。
4. 使用 DNS 服务器日志轮换拆分超大日志，而不是转换一个巨大文件。
5. 考虑为日志目录设置杀毒软件排除。

更多信息见性能。

压缩后的输出比预期大

内容非常多样的日志——许多唯一域名、许多不同客户端——压缩效果不如重复性强的日志。这是正常的。ZIP 通常仍能大幅减小文件；如果没有，检查 Details 列是否膨胀文件，以及你是否真的需要它。

统计数据与预期不符

• 确认使用了 -OutputType Both 或 -OutputType Statistic。使用 -OutputType CSV 时不会写入统计文件。
• Count 是总计数，不是唯一计数。一个客户端请求同一名称 500 次计为 500。这是“数字不对”的最常见原因。
• 统计按天分组。跨两天的日志会产生两天的行。
• 如果统计文件中 ComputerName 为空，说明转换时未设置 -ComputerName。

计划任务交互式运行正常，但作为任务运行失败

几乎总是以下三种情况之一：

• 找不到模块。 SYSTEM 账户加上 -NoProfile 只看到机器范围的模块路径。请机器范围安装模块，或在任务动作中显式添加 Import-Module DNSServer.DebugLogParser。
• 区域设置错误。 任务账户的区域设置与你不同。显式设置 -InputCulture 和 -OutputCulture。
• 执行策略或脚本未签名。 使任务的 -ExecutionPolicy 与你的签名策略匹配，并解除从其他地方复制文件的阻止。

在相同上下文（例如用 PsExec 以 SYSTEM 身份）手动运行任务命令行以复现问题。

报告问题

如果以上都无效：

1. 更新到最新模块版本并重试。

2. 在 GitHub issues 搜索相同症状。

3. 收集诊断信息：

   $PSVersionTable
   Get-Module DNSServer.DebugLogParser -ListAvailable | Select-Object Name, Version, Path
   Get-Culture
   

   以及你运行的确切命令、完整错误信息（包括堆栈跟踪），如果可以分享，附上能复现问题的日志小段（已匿名处理）。

4. 使用这些信息新建 issue。

8 - 模块命令参考

点击命令后，你将进入一个详细页面，提供该命令的全面信息，包括语法、参数、示例以及任何额外的使用说明或技巧。

8.1 - Convert-DNSDebugLogFile

SYNOPSIS

将 Windows DNS 服务器调试日志转换为结构化的 CSV 格式，便于分析和报告。

SYNTAX

__AllParameterSets

Convert-DNSDebugLogFile [-InputFile] <string[]> [[-OutputFile] <string>] [[-Delimiter] <string>]
 [[-ComputerName] <string>] [[-OutputType] <string>] [[-ContextFilter] <string[]>]
 [[-InputCulture] <cultureinfo>] [[-OutputCulture] <cultureinfo>] [-SkipHeaderValidation]
 [-RemoveSourceFile] [-CompressOutput] [-NoDetailsParsing] [-WhatIf] [-Confirm]

ALIASES

此 cmdlet 有以下别名，

DESCRIPTION

将 Windows DNS 服务器调试日志文件转换为结构化的 CSV 数据，可在 Excel、Power BI、SQL 数据库或 SIEM 工具中进行分析。 设计用于安全分析、性能监控、故障排除和合规报告。

该 cmdlet 解析 DNS 调试日志并输出一致的 CSV 格式以供分析。 CSV 输出包含 18 列，包括用于事件/诊断文本的 Information 列、可选的包含数据包详细信息块的 Details JSON 列，以及始终存在的 ComputerName 列（除非指定，否则为空）。

主要功能：

• 流式处理，避免将整个文件加载到内存中（适合超大日志）
• 针对大文件（100MB+）优化的高性能解析
• 可自定义 CSV 分隔符（默认分号）
• 可选的统计汇总和聚合指标
• 上下文过滤（Packet、Event、Note 及其他上下文）以聚焦特定日志条目类型
• 支持文化感知的日期解析和格式化，适用于国际服务器
• 支持管道批量处理多个文件
• 可选输出文件压缩（ZIP 格式）
• 可选处理后自动删除源文件
• 头部验证确保数据完整性

输出格式： ComputerName 列始终包含在每条记录的末尾。 如果未指定 -ComputerName 参数，该列将为空。 这保证了多服务器合并场景下输出结构的一致性。

性能： 使用带 64KB 缓冲区的 StreamReader/StreamWriter 优化，流式处理实现内存高效处理大文件，使用字符串操作替代正则表达式，手动生成 CSV，采用高效的哈希表统计收集。

兼容性：

• PowerShell 5.1+（桌面版和核心版）
• Windows Server 2016+
• 支持 DNS Server 2012 R2 至 2025 日志格式

EXAMPLES

示例 1

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log"

使用默认设置转换 DNS 调试日志（生成数据文件和统计文件，分隔符为分号）。 输出：

• C:\Logs\dns.csv
• C:\Logs\dns_Statistic.csv
• C:\Logs\dns_PacketStatistic.csv

示例 2

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputType CSV

仅生成数据文件，不生成统计文件。 输出：C:\Logs\dns.csv

示例 3

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputType Statistic

仅生成带聚合指标的统计文件。 输出：

• C:\Logs\dns_Statistic.csv
• C:\Logs\dns_PacketStatistic.csv

示例 4

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputFile "C:\Output\parsed.csv"

将日志转换到自定义输出位置。 输出：C:\Output\parsed.csv

示例 5

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -Delimiter "," -ComputerName "DNS01" -OutputType Both

使用逗号分隔符转换，并添加值为 “DNS01” 的 ComputerName 列。 输出：

• C:\Logs\dns.csv
• C:\Logs\dns_Statistic.csv
• C:\Logs\dns_PacketStatistic.csv

示例 6

PS C:\> Get-ChildItem "C:\Logs\*.log" | Convert-DNSDebugLogFile -OutputType Both

通过管道批量处理多个 DNS 调试日志文件。 输出：为每个 .log 文件生成 .csv 和 _statistic.csv 文件

示例 7

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput

转换并压缩输出为 ZIP 归档。 输出：C:\Logs\dns.zip（包含 dns.csv 及统计文件）

示例 8

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -RemoveSourceFile -Verbose

转换日志并在成功处理后删除源文件。 详细输出确认文件已删除。

示例 9

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -InputCulture 'de-DE' -OutputCulture 'en-US'

解析德国日期格式（DD.MM.YYYY），输出为美国格式（MM/DD/YYYY）。 用于处理来自不同区域设置服务器的日志。

示例 10

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter 'Packet'

仅转换 DNS 查询/响应数据包条目，排除 EVENT 和 Note 条目。 用于聚焦实际 DNS 流量分析。

示例 11

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter 'Packet','Event'

转换 DNS 查询/响应数据包和服务器事件，排除 Note 和其他条目。 用于同时分析 DNS 流量和服务器事件上下文。

示例 12

PS C:\> Get-ChildItem "C:\Logs\*.log" | Convert-DNSDebugLogFile -RemoveSourceFile -CompressOutput

自动日志归档：处理所有日志，压缩输出，并删除源文件。 适合计划任务的日志处理管道。

示例 13

PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\large-dns.log" -NoDetailsParsing

处理大型日志文件，禁用详细解析以获得最大性能。 PACKET 详细块被跳过，Details 列保持为空。 适用于处理非常大的文件且不需要详细数据包结构时。

PARAMETERS

-CompressOutput

在创建后将输出的 CSV 文件压缩为 ZIP 归档。

创建一个包含生成的 CSV 文件的 .zip 文件，然后删除未压缩的 CSV 文件。 ZIP 文件与输出 CSV 文件位于同一目录，且具有相同的基本名称。

优点：

• 大幅减少磁盘空间（CSV 文件通常可压缩 90% 以上）
• 简化文件管理和归档
• 适合长期存储

示例：输入 ‘dns.log’ 生成 ‘dns.csv’，压缩为 ‘dns.zip’，然后删除 ‘dns.csv’。

Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ComputerName

指定 CSV 输出中 ComputerName 列的值。 ComputerName 列始终包含在输出中——如果未指定此参数，该列将为空。

当合并多个 DNS 服务器日志时，使用此参数标识源服务器。

注意：这不是远程参数。 它仅用于标记输出。 如果 -InputFile 指向 UNC 路径，文件将直接从该路径读取（不执行 WinRM/远程操作）。

Type: String
DefaultValue: ''
SupportsWildcards: false
Aliases:
- Server
- DNSServer
- HostName
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Confirm

在运行 cmdlet 前提示确认。

指定后，会在以下操作前提示确认：

• 处理每个 DNS 调试日志文件
• 删除源文件（当指定 -RemoveSourceFile 时）
• 覆盖已存在的输出文件

适合交互式处理时控制处理文件。

Type: SwitchParameter
DefaultValue: ''
SupportsWildcards: false
Aliases:
- cf
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ContextFilter

过滤要包含在输出中的日志条目类型。 支持单个或多个值。

DNS 调试日志包含不同上下文类型：

• PACKET：DNS 查询和响应数据包信息（主要数据）
• EVENT：DNS 服务器事件（例如，“DNS 服务器已启动。”）
• Note：诊断注释和警告（例如，套接字错误、内部状态）
• DSPoll、Init、Lookup、Recurse、Remote、Tombstone：其他上下文类型

有效值：

• ‘All’：包含所有上下文类型（默认）
• ‘Packet’：仅包含 PACKET 条目（DNS 查询/响应）
• ‘Event’：仅包含 EVENT 条目（服务器事件）
• ‘Note’：仅包含 Note 条目（诊断信息）
• 任意组合：指定多个值以包含特定上下文类型

默认：All

示例：

• ‘Packet’ 仅过滤 DNS 流量
• ‘Packet’,‘Event’ 包含 DNS 流量和服务器事件
• ‘Note’,‘Event’ 包含诊断注释和服务器事件

注意：过滤为 ‘Event’ 或 ‘Note’ 时，只有 DateTime、ThreadId、Context 和 Information 列有数据。 其他列（协议、客户端 IP 等）为空。

Type: String[]
DefaultValue: "@('All')"
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 5
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Delimiter

指定 CSV 输出的分隔符字符。

默认：分号 (;)

常用替代：逗号 (,)、制表符 (`t)、管道符 (|)

在使用逗号作为小数点分隔符的地区（欧洲）使用分号。 对于标准 CSV 工具和期望逗号分隔的数据库，使用逗号。

Type: String
DefaultValue: ;
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-InputCulture

指定用于解析 DNS 调试日志中日期/时间值的文化/区域设置。

DNS 服务器调试日志使用生成日志的服务器 Windows 区域设置的日期格式。 处理来自不同区域设置服务器的日志时使用此参数。

默认：当前文化

常见示例：

• ‘de-DE’ 或 ‘de-AT’：德国格式（DD.MM.YYYY 或 DD/MM/YYYY）
• ’en-US’：美国格式（MM/DD/YYYY，含 AM/PM）
• ’en-GB’：英国格式（DD/MM/YYYY，24 小时制）
• ‘sv-SE’：瑞典/ISO 格式（YYYY-MM-DD）

Type: CultureInfo
DefaultValue: '[System.Globalization.CultureInfo]::CurrentCulture'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 6
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-InputFile

指定要解析的 DNS 调试日志文件路径。 支持数组以处理多个文件。

接受来自 Get-ChildItem 或其他生成文件的 cmdlet 的管道输入。

Type: String[]
DefaultValue: ''
SupportsWildcards: false
Aliases:
- FullName
- FilePath
- InputPath
- File
- Path
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: true
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-NoDetailsParsing

跳过将 PACKET 详细块解析为结构化 JSON 格式。

指定后，包含详细块的 PACKET 记录将在 Information 列显示 TCP/UDP 信息行，但 Details 列保持为空。 这显著提升处理大型日志文件时的性能，适合不需要详细数据包结构分析的场景。

使用场景：

• 处理非常大的日志文件（100MB+），只需基本查询信息
• 不需要分析详细结构（消息标志、DNS 区段）
• 优先最大化解析速度而非数据完整性

性能影响：对于包含大量 PACKET 详细块的日志，处理速度可提升 30-50%。

Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OutputCulture

指定用于格式化输出 CSV 文件中日期/时间值的文化/区域设置。

控制 DateTime 值写入 CSV 的格式。 当 CSV 文件将被特定区域设置的应用或系统使用时，使用此参数。

默认：当前文化

常见示例：

• ’en-US’：美国格式（MM/DD/YYYY）
• ‘de-DE’：德国格式（DD.MM.YYYY）
• ‘sv-SE’ 或 InvariantCulture：ISO 格式（YYYY-MM-DD），兼容性最佳

Type: CultureInfo
DefaultValue: '[System.Globalization.CultureInfo]::CurrentCulture'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 7
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OutputFile

指定输出 CSV 文件的路径。 如果未指定，使用输入文件名并更改扩展名为 .csv，输出到输入文件所在目录。

重要：必须是文件路径，不能是目录。 如果想使用输入文件目录但自定义文件名，请指定包含文件名的完整路径。

Type: String
DefaultValue: ''
SupportsWildcards: false
Aliases:
- Output
- Destination
- OutFile
- OutputPath
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OutputType

指定生成的输出类型。

有效值：

• ‘CSV’：仅生成包含所有解析日志条目的数据文件
• ‘Statistic’：仅生成带聚合指标的统计文件
• ‘Both’：同时生成数据和统计文件（默认）

默认：Both

生成统计时，会创建两个独立文件：

• ‘_Statistic.csv’：按日期和上下文类型的汇总计数（日期、上下文、计数、计算机名）
• ‘_PacketStatistic.csv’：按日期、客户端 IP、协议、方向和查询类型的详细 PACKET 计数（日期、客户端 IP、协议、方向、查询类型、计数、计算机名）

Type: String
DefaultValue: Both
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 4
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-RemoveSourceFile

成功处理后删除源 DNS 调试日志文件。

适用于自动化日志处理管道或磁盘空间管理。 仅当处理成功且所有输出文件均已创建时才删除源文件。

安全性：不能与 -SkipHeaderValidation 一起使用，以防止意外删除无效文件。

警告：源文件将被永久删除。 使用此选项前请确保输出文件有效。

Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-SkipHeaderValidation

跳过 DNS 调试日志头部验证检查。

默认情况下，cmdlet 会验证输入文件是否具有有效的 DNS 服务器调试日志头部。 使用此开关可处理无验证的文件，适用于：

• 修改或自定义日志格式
• 解决验证问题
• 非标准或预处理日志

警告：如果文件不是有效的 DNS 日志，可能导致处理错误。

Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-WhatIf

显示如果运行 cmdlet 会发生什么。 cmdlet 不会实际执行。

指定后，显示将执行的操作的详细信息，但不执行。 适用于：

• 预览将处理的文件
• 验证输出文件路径
• 在生产环境运行前测试脚本

Type: SwitchParameter
DefaultValue: ''
SupportsWildcards: false
Aliases:
- wi
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。详情请参阅 about_CommonParameters。

INPUTS

System.String[]

NOTES

版本 : 1.7.2.1
作者 : Andi Bellstedt, Copilot, Patrick Charbonnier (Silent Waters IT Consulting S.L.)
日期 : 2026-07-24
关键词 : Microsoft Windows Server, DNSServer, DNS, DebugLog, LogParser

RELATED LINKS

• github.com/AndiBellstedt/DNSServer.DebugLogParser

9 - 使用示例

这些示例提供了更多的深度和背景。如果你只想了解模块命令的用法，请查看命令参考。

9.1 - 使用 SQL Server 的安全分析工作流

此示例展示了一个实用的安全分析工作流：使用 Convert-DNSDebugLogFile 解析 DNS 调试日志，将生成的 CSV 导入 SQL Server，并运行查询以突出显示异常大量的 TXT 记录查询。

为了最佳的互操作性，此示例通过使用 -OutputCulture 'sv-SE' 以类似 ISO 的格式写入时间戳。

所需模块

此示例使用以下 PowerShell 模块：

• DNSServer.DebugLogParser
• SqlServer

如有需要，请安装它们：

Install-Module -Name DNSServer.DebugLogParser -Scope CurrentUser
Install-Module -Name SqlServer -Scope CurrentUser

场景

当你想将解析后的 DNS 调试日志数据移入 SQL Server，以便你可以：

• 高效搜索大数据集
• 构建可重复使用的检测查询
• 关联多个 DNS 服务器的活动
• 保留规范化数据以供后续调查

时，请使用此工作流。

转换步骤的输出

Convert-DNSDebugLogFile 不直接写入 SQL Server。它首先创建一个 CSV 文件。该 CSV 文件即为导入数据库的数据集。

在此示例中：

• 输入日志：C:\Administration\Logs\DNS\dns.log
• 生成的 CSV：C:\Administration\Logs\DNS\dns.csv
• 目标表：dbo.DNSQueries

创建目标表

在 SQL Server 中运行以下语句一次，创建目标表。

IF OBJECT_ID('dbo.DNSQueries', 'U') IS NULL
BEGIN
    CREATE TABLE dbo.DNSQueries (
        DateTime      datetime2(0)   NOT NULL,
        ThreadId      int            NULL,
        Context       nvarchar(20)   NULL,
        PacketId      int            NULL,
        Protocol      nvarchar(10)   NULL,
        Direction     nvarchar(10)   NULL,
        ClientIP      nvarchar(64)   NULL,
        Xid           nvarchar(16)   NULL,
        Type          nvarchar(16)   NULL,
        Opcode        nvarchar(16)   NULL,
        FlagsHex      nvarchar(16)   NULL,
        FlagsChar     nvarchar(16)   NULL,
        ResponseCode  nvarchar(32)   NULL,
        QuestionType  nvarchar(32)   NULL,
        QuestionName  nvarchar(512)  NULL,
        Information   nvarchar(max)  NULL,
        Details       nvarchar(max)  NULL,
        ComputerName  nvarchar(256)  NULL
    );
END;

转换日志并导入 CSV

以下 PowerShell 示例执行完整工作流：

1. 导入所需模块
2. 将 DNS 调试日志转换为 CSV
3. 加载生成的 CSV
4. 批量导入行到 SQL Server

# Requires -Modules DNSServer.DebugLogParser, SqlServer

Import-Module -Name DNSServer.DebugLogParser -ErrorAction Stop
Import-Module -Name SqlServer -ErrorAction Stop

$logPath = 'C:\Administration\Logs\DNS\dns.log'
$csvPath = 'C:\Administration\Logs\DNS\dns.csv'
$serverInstance = 'SQLServer'
$databaseName = 'DNSLogs'
$delimiter = ';'

$createTableSql = @'
IF OBJECT_ID('dbo.DNSQueries', 'U') IS NULL
BEGIN
    CREATE TABLE dbo.DNSQueries (
        DateTime      datetime2(0)   NOT NULL,
        ThreadId      int            NULL,
        Context       nvarchar(20)   NULL,
        PacketId      int            NULL,
        Protocol      nvarchar(10)   NULL,
        Direction     nvarchar(10)   NULL,
        ClientIP      nvarchar(64)   NULL,
        Xid           nvarchar(16)   NULL,
        Type          nvarchar(16)   NULL,
        Opcode        nvarchar(16)   NULL,
        FlagsHex      nvarchar(16)   NULL,
        FlagsChar     nvarchar(16)   NULL,
        ResponseCode  nvarchar(32)   NULL,
        QuestionType  nvarchar(32)   NULL,
        QuestionName  nvarchar(512)  NULL,
        Information   nvarchar(max)  NULL,
        Details       nvarchar(max)  NULL,
        ComputerName  nvarchar(256)  NULL
    );
END
'@

Convert-DNSDebugLogFile `
    -InputFile $logPath `
    -ComputerName 'DNS01' `
    -OutputType CSV `
    -OutputFile $csvPath `
    -Delimiter $delimiter `
    -OutputCulture 'sv-SE'

$rows = Import-Csv -Path $csvPath -Delimiter $delimiter

if (-not $rows) {
    throw "生成的 CSV 文件 '$csvPath' 不包含任何行。"
}

$dataTable = [System.Data.DataTable]::new()
foreach ($columnName in $rows[0].PSObject.Properties.Name) {
    $null = $dataTable.Columns.Add($columnName, [string])
}

foreach ($row in $rows) {
    $dataRow = $dataTable.NewRow()
    foreach ($column in $dataTable.Columns) {
        $columnName = $column.ColumnName
        $dataRow[$columnName] = $row.$columnName
    }

    $null = $dataTable.Rows.Add($dataRow)
}

$connectionString = "Server=$serverInstance;Database=$databaseName;Integrated Security=True"
$connection = [System.Data.SqlClient.SqlConnection]::new($connectionString)

try {
    $connection.Open()

    $command = $connection.CreateCommand()
    $command.CommandText = $createTableSql
    $null = $command.ExecuteNonQuery()

    $bulkCopy = [System.Data.SqlClient.SqlBulkCopy]::new($connection)
    $bulkCopy.DestinationTableName = 'dbo.DNSQueries'

    foreach ($column in $dataTable.Columns) {
        $null = $bulkCopy.ColumnMappings.Add($column.ColumnName, $column.ColumnName)
    }

    $bulkCopy.WriteToServer($dataTable)
}
finally {
    $connection.Dispose()
}

查询可疑的 TXT 记录活动

数据进入 SQL Server 后，你可以搜索发出异常大量 TXT 记录查询的客户端。

SELECT
    ComputerName,
    ClientIP,
    QuestionName,
    COUNT(*) AS QueryCount
FROM dbo.DNSQueries
WHERE QuestionType = 'TXT'
GROUP BY
    ComputerName,
    ClientIP,
    QuestionName
HAVING COUNT(*) > 100
ORDER BY QueryCount DESC;

如果你更喜欢从 PowerShell 运行查询，可以使用 SqlServer 模块中的 Invoke-Sqlcmd：

$query = @'
SELECT
    ComputerName,
    ClientIP,
    QuestionName,
    COUNT(*) AS QueryCount
FROM dbo.DNSQueries
WHERE QuestionType = 'TXT'
GROUP BY
    ComputerName,
    ClientIP,
    QuestionName
HAVING COUNT(*) > 100
ORDER BY QueryCount DESC;
'@

Invoke-Sqlcmd `
    -ServerInstance 'SQLServer' `
    -Database 'DNSLogs' `
    -Query $query

为什么 TXT 查询很有意义

大量的 TXT 记录查询值得关注，因为它们可能表明：

• DNS 隧道
• 通过 DNS 进行数据外泄
• 恶意软件或工具滥用 TXT 记录
• 异常嘈杂或配置错误的客户端

此查询只是一个起点。在生产环境中，你应调整阈值并添加符合你环境的过滤条件。

运行注意事项

• Import-Csv 会将整个文件读入内存。对于非常大的日志导出，考虑使用流式处理而非构建完整的 DataTable。
• 在转换步骤中保留 -ComputerName，以便在集中摄取后仍能归属记录。
• 导出和导入时使用一致的分隔符和文化设置。
• 在将此工作流用于长期存储前，验证 SQL Server 中的保留策略、索引和访问控制。

9.2 - 域环境中的实际应用（基于 GPO 的收集与转换）

本文档概述了在 Active Directory 域环境中运行 DNSServer.DebugLogParser 的一个实用端到端示例，重点是转换域控制器上的 Windows DNS 服务器调试日志。

本示例附带一个 ZIP 压缩包，其中包含用于实现本文所述工作流的策略工件。
最相关的工件包括 备份清单、GPO 报告、Files.xml、Set-DNSServerDebugLogging.ps1 和 ScheduledTasks.xml。

场景

• 多台域控制器（DC）托管 DNS 服务器角色。
• 通过计划任务在每台 DC 上启用并一致配置 DNS 调试日志（将日志文件写入 C:\Administration\Logs\DNSServer）。
• 通过集中管理的进程将日志转换为 CSV，用于：
  • 安全分析
  • 运营报告
  • 故障排查
  • 合规/保留

目标成果

• 所有 DC 上转换设置一致
• 输出位置和命名可预测
• 可选压缩以减少存储占用
• 可选统计输出以便快速的每日汇总
• 主机端风险最小，明确重跑和清理策略

建议架构

收集模型：本地转换 + 中央拉取

1. 每台 DC 将 DNS 调试日志写入磁盘，并启用日志轮换。
2. 每台 DC 将轮换后的 *.log 文件转换为数据 CSV 和统计 CSV，然后按计划（任务计划程序）压缩输出为 *.zip。
3. 输出文件写在日志文件旁边，保持管道简单。
4. 中央服务器收集 *.zip 输出，例如通过文件共享采集、定时复制、SIEM 转发器或基于代理的收集器。

该模型最大限度减少了对大型原始日志文件的网络读取，将解析工作保持在数据近旁。

GPO 工作流

该工作流通过组策略（计算机配置）实现，确保所有域控制器的设置一致。

本仓库中包含参考实现（GPO 报告）：

• 归档/报告名称：T0-C-Analytics-DNSDebugLogging
• 备份 ID：{2B6F16BC-0E7C-4787-83D7-2854FED882EE}
• GPO 目标链接：corp.company.com/Domain Controllers
• 项目筛选器（用于文件部署和计划任务）：仅当存在 C:\Windows\System32\dns.exe 时应用

1) 前提条件（文件夹 + 模块）

提供的备份假设以下文件夹已存在。如果希望部署时自动创建，请添加单独的 GPP 项目：

• C:\Administration\Scripts
• C:\Administration\Logs\DNSServer

备份还假设 Convert-DNSDebugLogFile 已在 DC 上可用。转换任务启动 Windows PowerShell 5.1，使用 -NoProfile，且不显式导入模块，因此模块必须安装在对 LocalSystem 可见的机器范围 Windows PowerShell 模块路径中。推荐做法：

• 在 DC 上安装 DNSServer.DebugLogParser，例如通过 PowerShell Gallery（如果策略允许）。
• 通过内部仓库/文件共享部署模块，使其可在 $env:PSModulePath 中发现。
• 如果需要确定性加载行为，可在任务操作中显式添加 Import-Module。

2) 部署调试日志配置脚本（GPP 文件）

GPO 部署脚本：

• 源（SYSVOL 中通过 GPP）：%GptPath%\Preferences\Files\Set-DNSServerDebugLogging.ps1
• 目标（每台 DC 上）：C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1

此项在 Files.xml 的 GPP 文件首选项中实现。

3) 计划任务：配置 DNS 调试日志

GPO 创建名为 Set-DNSServerDebugLogging 的计划任务。

• 备份中安全上下文：SYSTEM，登录类型为 S4U
• 备份中触发器：每日（开始时间 2025-03-01T00:00:01）
• 操作定义在 ScheduledTasks.xml：
  • powershell.exe -ExecutionPolicy RemoteSigned -command " & { C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1 }"
  • 工作目录：C:\Administration\Scripts

关联的 Set-DNSServerDebugLogging.ps1 脚本通过 Get-DnsServerDiagnostics / Set-DnsServerDiagnostics 配置 DNS 调试日志，重点包括：

• 启用文件日志和轮换
• 写入路径：C:\Administration\Logs\DNSServer\DnsDebugLog_<COMPUTERNAME>.<Domain>_.log
• 每个文件使用 10 MB 轮换大小
• 主要捕获查询相关活动（查询 + 通知 + 更新 + 查询事务），排除完整数据包日志

4) 计划任务：转换轮换的调试日志为压缩 CSV

GPO 创建名为 Convert-DNSDebugLogs 的计划任务。

• 备份中安全上下文：SYSTEM，登录类型为 InteractiveToken
• 备份中触发器：每日（开始时间 2026-01-01T00:30:00）
• 工作目录：C:\Administration\Logs\DNSServer
• 操作定义在 ScheduledTasks.xml（格式化便于阅读）：

Get-ChildItem .\*.log |
  Sort-Object lastwritetime, Name -Descending |
  Select-Object -Skip 1 |
  Convert-DNSDebugLogFile `
    -ComputerName $env:COMPUTERNAME `
    -Delimiter ';' `
    -OutputType Both `
    -ContextFilter Packet `
    -OutputCulture sv-SE `
    -CompressOutput

设计说明：

• Select-Object -Skip 1 有意跳过最新（活动）日志文件。Convert-DNSDebugLogFile 能读取 DNS 服务器当前打开的日志，但该文件在读取时会变化：输出可能缺失最新条目或以截断记录结尾，两次运行结果不一致。跳过活动文件保证计划输出可复现。
• 这意味着当前数据仅在轮换后导出；在低流量 DC 上，活动日志可能超过一天未处理。若延迟过长，可降低轮换大小。
• 由于 Convert-DNSDebugLogFile 默认 -OutputFile 为“同文件夹、同名 .csv”，输出文件与 *.log 输入文件并列。
• 使用 -CompressOutput 时，每个处理的日志生成一个 *.zip，中间 CSV 文件被删除。
• 除非归档或删除已处理的 *.log 文件，否则后续运行会再次处理所有非活动日志。
• 任务在 $Error.Count -gt 0 时抛出异常，表示运行失败。

5) 中央采集

选项（任选其一）：

• 文件共享采集：DC 将 C:\Administration\Logs\DNSServer\*.zip 写入（或复制到）\\fileserver\share\dns\$env:COMPUTERNAME\...（为 DC 计算机账户或域控制器组授予共享和 NTFS 权限，如果任务以 SYSTEM 运行）
• 拉取模型：中央作业读取 \\dc\C$\Administration\Logs\DNSServer\*.zip（最不推荐；需要管理员共享）
• 代理转发：SIEM / 日志管道转发 *.zip 输出

运营注意事项

• 最小权限：任务以 SYSTEM 运行；确保本地文件夹可写，且任何 UNC 目标对计算机账户开放访问（如果使用）。
• 签名策略：两个任务均使用 -ExecutionPolicy RemoteSigned；根据策略签名或解除阻止部署的脚本和模块。
• 磁盘使用：-CompressOutput 显著节省空间，但此工作流不删除源日志；请规划保留和清理策略。
• 重复处理行为：除非归档或删除已处理日志，转换任务会在后续运行中再次处理所有非活动 *.log 文件。此方案简单且稳健，但可能覆盖输出，且如果采集器不去重，可能产生重复下游数据。
• 多 DC 合并：包含 -ComputerName $env:COMPUTERNAME，确保合并数据集可追溯。注意 -ComputerName 仅标记输出，不执行远程连接。
• 网络共享：Convert-DNSDebugLogFile 可读取 SMB/UNC 路径的源日志，但本地转换并传输压缩结果是处理大型原始日志的更佳方案。如果使用 UNC 路径，记住以 SYSTEM 运行的任务在网络上以计算机账户身份认证，需要共享和 NTFS 权限。
• 日期格式：故意使用 -OutputCulture sv-SE，使时间戳写为 2026-01-20 23:00:16。该格式被 SQL Server、Power BI 及大多数导入工具无提示识别，无论生成日志的 DC 区域设置如何。
• 验证：保持启用标题验证，因为任务未使用 -SkipHeaderValidation（推荐做法）。

使用 ZIP 进行验证和调整

使用 ZIP 压缩包 作为参考实现，然后根据你的环境调整以下方面：

• 目标范围：哪些 DC / OU 接收策略
• 执行身份：确认两个计划任务使用预期的登录类型（S4U 与 InteractiveToken），或统一为标准
• 文件夹创建：决定 C:\Administration\Scripts 和 C:\Administration\Logs\DNSServer 是预先创建还是由额外 GPP 项目创建
• 路径：确认 C:\Administration\Scripts 和 C:\Administration\Logs\DNSServer 符合你的标准
• 保留策略：决定是否保留原始日志及保留时长（尤其是启用清理选项时）
• 采集：确认 CSV/ZIP 输出写入位置及中央采集方式

如果想验证 GPO 配置而不导入，仓库中的权威资源包括：

• manifest.xml（备份元数据）
• gpreport.xml（人类可读完整报告）
• Files.xml（文件部署）
• Set-DNSServerDebugLogging.ps1（脚本内容）
• ScheduledTasks.xml（计划任务）

9.3 - 计划任务示例

此脚本创建了一个每天凌晨 2:00 运行的 Windows 计划任务。它导入模块并处理脚本执行所在文件夹中的所有日志文件（本例中为 “C:\Administration\Logs\DNS”）。该过程会将输出压缩成 ZIP 文件，并删除原始文件以保持整洁。

$actionParams = @{
    Execute = "powershell.exe"
    Argument = '-ExecutionPolicy RemoteSigned -Command "Import-Module DNSServer.DebugLogParser; Get-ChildItem .\*.log | Sort-Object lastwritetime, Name -Descending | Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME -Delimiter \";\" -OutputType Both -ContextFilter Packet -OutputCulture sv-SE -CompressOutput"'
    WorkingDirectory = "C:\Administration\Logs\DNS"
}
$Action = New-ScheduledTaskAction @actionParams

$Trigger = New-ScheduledTaskTrigger -Daily -At "2:00AM"

Register-ScheduledTask -TaskName "Process DNS Logs" -Action $Action -Trigger $Trigger -Description "Convert DNS debug logs to CSV daily"