About this documentation

• 1: Overview
• 2: Output Formats
• 3: Operational Best Practices
• 4: Troubleshooting
• 5: Module commands reference
• 5.1: Convert-DNSDebugLogFile
• 6: Usage Examples
• 6.1: Practical usage in a Domain Environment (GPO-driven collection and conversion)
• 6.2: Scheduled Task Example
• 6.3: Security Analysis Workflow with SQL Server

1 - Overview

DNSServer.DebugLogParser is a PowerShell module that transforms Windows DNS Server debug log files into structured, analyzable CSV data for security analysis, performance monitoring, troubleshooting, and compliance reporting.

What is a DNS debug log?

DNS debug logging is a feature of Windows DNS Server that records detailed information about DNS operations. When enabled, the DNS Server writes log entries to a text file (typically dns.log) in the DNS Server’s directory.

Each log entry contains up to 16 fields including:

• Date and time of the query
• Protocol used (UDP or TCP)
• Direction (Send or Receive)
• Client IP address
• Query type (A, AAAA, MX, PTR, etc.)
• Domain name queried
• Response code (NOERROR, NXDOMAIN, etc.)
• Query flags and options
• IP address in response (for successful queries)
• Port numbers and additional technical details

Why parse DNS debug logs?

DNS logs are critical for:

Troubleshooting

• Diagnose name resolution failures
• Identify misconfigured clients or applications
• Track down the source of problematic queries
• Verify proper DNS configuration and zone transfers

Performance monitoring

• Identify high-volume query sources
• Analyze query types and patterns to optimize DNS infrastructure
• Detect configuration issues causing excessive queries
• Track response times and success rates
• Monitor DNS server load and capacity

Security analysis

• Detect DNS tunneling and data exfiltration attempts
• Identify domains associated with malware and command-and-control servers
• Track suspicious query patterns that may indicate compromised systems
• Monitor for DNS amplification attacks
• Investigate security incidents and trace attacker activity

Compliance and auditing

• Meet regulatory requirements for logging and retention
• Document network activity for audit trails
• Generate reports for management and compliance officers
• Demonstrate due diligence in security monitoring

How the module works (high level)

The module is optimized for large files and processes DNS debug logs into structured CSV output. It supports multi-line records (for example PACKET detail blocks and indented continuation lines) so that event/diagnostic messages and packet details stay attached to the correct record.

Key capabilities:

• Parses the native DNS debug log fields and produces a consistent CSV layout
• Handles multiple DNS Server versions (2012 R2 through 2025)
• Supports both PowerShell Desktop (5.1+) and Core (7.x)
• Processes files of any size (tested with 100MB+ files)
• Validates log file headers to ensure data integrity
• Generates optional statistical summaries
• Supports batch processing via PowerShell pipeline
• Optionally compresses output files to save disk space
• Can automatically remove source files after successful processing
• Culture-aware date parsing for international DNS server logs
• Culture-aware date formatting for international output requirements

Licensing and support

The module is released under the MIT License. Community support is available through GitHub Issues.

• GitHub repository: https://github.com/AndiBellstedt/DNSServer.DebugLogParser
• PowerShell Gallery: https://www.powershellgallery.com/packages/DNSServer.DebugLogParser

2 - Output Formats

DNSServer.DebugLogParser can generate two types of output:

• A CSV data file containing all parsed entries
• Optional statistics files for daily aggregation

To see real-world examples of each output type, check the sample in this article.

CSV data file

Example output files:

• en-US (no details): WithComputerName, NoComputerName
• de-DE (no details): WithComputerName, NoComputerName
• de-DE (with details / Details JSON populated for Packet detail blocks): WithComputerName, NoComputerName

The CSV data file contains all parsed log entries with the following columns:

• DateTime: Date and time of the DNS query/response
• ThreadId: Internal DNS server thread identifier
• Context: Operation context (for example Packet, Event, Note, DSPoll, Init, Lookup, Recurse, Remote, Tombstone)
• PacketId: DNS packet identifier
• Protocol: UDP or TCP
• Direction: Rcv (received/query) or Snd (sent/response)
• ClientIP: Client IP address
• Xid: Transaction ID (hex)
• Type: Query or Response
• Opcode: Standard, Notify, Update, or Unknown
• FlagsHex: Query/response flags (hex)
• FlagsChar: Flags decoded (Authoritative, Truncated, RecursionDesired, RecursionAvailable)
• ResponseCode: NOERROR, NXDOMAIN, SERVFAIL, etc.
• QuestionType: DNS record type (A, AAAA, MX, PTR, etc.)
• QuestionName: Domain name queried
• Information: Additional information (for Event/Note/etc.; for Packet detail blocks, contains the TCP/UDP detail header line)
• Details: JSON data for Packet entries that include detail blocks (empty otherwise)
• ComputerName: Source server name (always present; empty if not specified)

Note: The ComputerName column is always included at the end of each record to ensure consistent output structure. This facilitates multi-server log consolidation scenarios.

Statistics files (optional)

Example output files:

• Context statistics: en-US (WithComputerName), en-US (NoComputerName), de-DE (WithComputerName), de-DE (NoComputerName)
• Packet statistics: en-US (WithComputerName), en-US (NoComputerName), de-DE (WithComputerName), de-DE (NoComputerName)

When statistics are generated, two separate files are created:

1) Context statistics (*_Statistic.csv)

Columns:

• Date: Date (yyyy-MM-dd)
• Context: Context name (for example Packet, Event, Note)
• Count: Number of records
• ComputerName: Source server name

2) Packet statistics (*_PacketStatistic.csv)

Columns:

• Date: Date (yyyy-MM-dd)
• ClientIP: Client IP address
• Protocol: UDP or TCP
• Direction: Rcv or Snd
• QuestionType: DNS record type
• Count: Number of records
• ComputerName: Source server name

3 - Operational Best Practices

When using DNSServer.DebugLogParser in production:

1. Schedule regular processing

   • Use Task Scheduler to automatically convert new log files daily or weekly.

2. Rotate logs appropriately

   • DNS debug logs can grow quickly; configure rotation at a manageable size (for example 100MB).

3. Validate output

   • Verify the first few converted files before fully automating.

4. Plan storage requirements

   • Even with compression, plan storage based on DNS volume and retention.

5. Secure sensitive data

   • DNS logs can be sensitive; protect outputs with appropriate access controls.

6. Document your workflow

   • Document processing schedules, storage locations, and analysis usage.

7. Test with sample files

   • Validate parameters and output format before processing critical logs.

8. Monitor for errors

   • Watch for corrupted logs, access issues, or insufficient disk space.

4 - Troubleshooting

Common issues and solutions

“The file is not a valid DNS debug log file”

• Ensure you’re converting an actual DNS Server debug log.
• The file should start with Message logging started at or contain DNS query entries.
• If you’re certain the file is valid but the header differs, use -SkipHeaderValidation.

Output file is empty or incomplete

• Confirm the input file contains valid log entries.
• Some logs may only contain header information if no queries occurred.
• Verify the log file isn’t corrupted and contains actual query data.

Processing is very slow

• Ensure sufficient memory and that the disk is not heavily loaded.
• Consider processing smaller log files.
• Consider -CompressOutput with scheduled processing to handle smaller batches.

“Access denied” errors

• Run PowerShell with appropriate permissions to read the source log files and write to the destination directory.
• DNS log files may require administrator access.

Compressed output is larger than expected

• Logs with many unique values compress less efficiently; this can be normal.
• ZIP compression still typically achieves substantial reduction.

Statistics file doesn’t match expectations

• Verify you’re using -OutputType Both or -OutputType Statistic.
• Statistics are aggregated counts (daily groupings), so values represent totals.

Reporting issues

If you encounter problems not covered here:

1. Verify you’re using the latest version of the module.
2. Check GitHub Issues for similar problems.
3. Collect diagnostic information:
   • PowerShell version ($PSVersionTable)
   • Module version (Get-Module DNSServer.DebugLogParser)
   • Sample log file (if possible)
   • Full error message and stack trace
4. Open a new GitHub issue with details.

5 - Module commands reference

By clicking on a command, you will be taken to a detailed page that provides comprehensive information about the command, including its syntax, parameters, examples, and any additional notes or tips for usage.

5.1 - Convert-DNSDebugLogFile

SYNOPSIS

Transforms Windows DNS Server debug logs into structured CSV format for analysis and reporting.

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] [<CommonParameters>]

ALIASES

This cmdlet has the following aliases,

DESCRIPTION

Converts Windows DNS Server debug log files into structured CSV data that can be analyzed in Excel, Power BI, SQL databases, or SIEM tools. Designed for security analysis, performance monitoring, troubleshooting, and compliance reporting.

The cmdlet parses DNS debug logs and writes a consistent CSV output for analysis. The CSV output contains 18 columns, including an Information column for event/diagnostic text, an optional Details JSON column for Packet detail blocks, and an always-present ComputerName column (empty unless specified).

KEY FEATURES:

• High-performance parsing optimized for large files (100MB+)
• Customizable CSV delimiter (default: semicolon)
• Optional statistical summaries with aggregated metrics
• Context filtering (Packet, Event, Note, and additional contexts) to focus on specific log entry types
• Culture-aware date parsing and formatting for international servers
• Pipeline support for batch processing multiple files
• Optional compression of output files (ZIP format)
• Optional automatic removal of source files after processing
• Header validation to ensure data integrity

OUTPUT FORMAT: The ComputerName column is always included at the end of each record. If the -ComputerName parameter is not specified, the column will be empty. This ensures consistent output structure for multi-server consolidation scenarios.

PERFORMANCE: Optimized using StreamReader/StreamWriter with 64KB buffers, string operations instead of regex, manual CSV generation, and efficient hashtable-based statistics collection.

COMPATIBILITY:

• PowerShell 5.1+ (Desktop and Core editions)
• Windows Server 2016+
• DNS Server 2012 R2 through 2025 log formats

EXAMPLES

EXAMPLE 1

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

Converts the DNS debug log using default settings (both data and statistics files with semicolon delimiter). Output:

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

EXAMPLE 2

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

Generates only the data file without statistics. Output: C:\Logs\dns.csv

EXAMPLE 3

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

Generates only the statistics file with aggregated metrics. Output:

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

EXAMPLE 4

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

Converts the log to a custom output location. Output: C:\Output\parsed.csv

EXAMPLE 5

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

Converts with comma delimiter and adds ComputerName column with value “DNS01”. Output:

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

EXAMPLE 6

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

Batch processes multiple DNS debug log files via pipeline. Output: For each .log file, generates .csv and _statistic.csv files

EXAMPLE 7

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

Converts and compresses output to ZIP archive. Output: C:\Logs\dns.zip (containing dns.csv + statistics files)

EXAMPLE 8

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

Converts the log and removes the source file after successful processing. Verbose output confirms file removal.

EXAMPLE 9

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

Parses German date format (DD.MM.YYYY) and outputs in US format (MM/DD/YYYY). Use when processing logs from servers with different regional settings.

EXAMPLE 10

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

Converts only DNS query/response packet entries, excluding EVENT and Note entries. Use to focus analysis on actual DNS traffic.

EXAMPLE 11

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

Converts both DNS query/response packets and server events, excluding Note and other entries. Use to analyze DNS traffic along with server event context.

EXAMPLE 12

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

Automated log archival: processes all logs, compresses output, and removes source files. Ideal for scheduled log processing pipelines.

EXAMPLE 13

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

Processes a large log file with detail parsing disabled for maximum performance. PACKET detail blocks are skipped, keeping the Details column empty. Use when processing very large files and detailed packet structure is not needed.

PARAMETERS

-CompressOutput

Compresses output CSV files into a ZIP archive after creation.

Creates a .zip file containing the generated CSV file(s), then removes the uncompressed CSV(s). The ZIP file is created in the same directory as the output CSV with the same base name.

Benefits:

• Significantly reduces disk space (CSV files typically compress 90%+)
• Simplifies file management and archival
• Suitable for long-term storage

Example: Input ‘dns.log’ generates ‘dns.csv’ compressed to ‘dns.zip’, then ‘dns.csv’ is removed.

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

Specifies the value for the ComputerName column in the CSV output. The ComputerName column is always present in the output - if this parameter is not specified, the column will be empty.

Use this when consolidating logs from multiple DNS servers to identify the source server in combined datasets.

Note: This is NOT a remoting parameter. The cmdlet processes local files only.

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

Prompts you for confirmation before running the cmdlet.

When specified, prompts for confirmation before:

• Processing each DNS debug log file
• Removing source files (when -RemoveSourceFile is specified)
• Overwriting existing output files

Useful for interactive processing when you want to control which files are processed.

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

Filters which log entry types to include in the output. Accepts single or multiple values.

DNS debug logs contain different context types:

• PACKET: DNS query and response packet information (primary data)
• EVENT: DNS server events (e.g., “The DNS server has started.”)
• Note: Diagnostic notes and warnings (e.g., socket errors, internal states)
• DSPoll, Init, Lookup, Recurse, Remote, Tombstone: Additional context types

Valid values:

• ‘All’: Include all context types (default)
• ‘Packet’: Include only PACKET entries (DNS queries/responses)
• ‘Event’: Include only EVENT entries (server events)
• ‘Note’: Include only Note entries (diagnostic information)
• Any combination: Specify multiple values to include specific context types

Default: All

Examples:

• ‘Packet’ filters to only DNS traffic
• ‘Packet’,‘Event’ includes both DNS traffic and server events
• ‘Note’,‘Event’ includes diagnostic notes and server events

Note: When filtering to ‘Event’ or ‘Note’, only DateTime, ThreadId, Context, and Information columns will contain data. Other columns (Protocol, ClientIP, etc.) will be empty.

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

Specifies the delimiter character for the CSV output.

Default: Semicolon (;)

Common alternatives: Comma (,), Tab (`t), Pipe (|)

Use semicolon in regions where comma is the decimal separator (Europe). Use comma for standard CSV tools and databases that expect comma-separated values.

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

-InputCulture

Specifies the culture/locale to use for parsing date/time values in the DNS debug log.

DNS Server debug logs use the date format of the Windows locale on the server where the log was generated. Use this parameter when processing logs from servers with different regional settings.

Default: Current culture

Common examples:

• ‘de-DE’ or ‘de-AT’: German format (DD.MM.YYYY or DD/MM/YYYY)
• ’en-US’: US format (MM/DD/YYYY with AM/PM)
• ’en-GB’: UK format (DD/MM/YYYY with 24-hour time)
• ‘sv-SE’: Swedish/ISO format (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

Specifies the path to the DNS debug log file to parse. Supports arrays for processing multiple files.

Accepts pipeline input from Get-ChildItem or other file-producing cmdlets.

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

Skips parsing PACKET detail blocks into structured JSON format.

When specified, PACKET records with detail blocks will have the TCP/UDP info line in the Information column, but the Details column will remain empty. This significantly improves processing performance for large log files when detailed packet structure analysis is not needed.

Use this switch when:

• Processing very large log files (100MB+) and only need basic query information
• Detail structure (Message flags, DNS sections) is not required for analysis
• Maximizing parsing speed is more important than data completeness

Performance impact: Can improve processing speed by 30-50% for logs with many PACKET detail blocks.

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

Specifies the culture/locale to use for formatting date/time values in the output CSV files.

Controls how DateTime values are written to the CSV. Use this when CSV files will be consumed by applications or systems with specific regional settings.

Default: Current culture

Common examples:

• ’en-US’: US format (MM/DD/YYYY)
• ‘de-DE’: German format (DD.MM.YYYY)
• ‘sv-SE’ or InvariantCulture: ISO format (YYYY-MM-DD) for maximum compatibility

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

Specifies the path for the output CSV file. If not specified, uses the input filename with .csv extension in the same directory as the input file.

Important: Must be a file path, not a directory. If you want to use the input file’s directory with a custom name, specify the full path including filename.

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

Specifies the type of output to generate.

Valid values:

• ‘CSV’: Generate only the data file with all parsed log entries
• ‘Statistic’: Generate only the statistics files with aggregated metrics
• ‘Both’: Generate both data and statistics files (default)

Default: Both

When statistics are generated, two separate files are created:

• ‘_Statistic.csv’: Summary counts per context type per day (Date, Context, Count, ComputerName)
• ‘_PacketStatistic.csv’: Detailed PACKET counts per day by client IP, protocol, direction, and query type (Date, ClientIP, Protocol, Direction, QuestionType, Count, ComputerName)

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

Removes the source DNS debug log file after successful processing.

Use this for automated log processing pipelines or disk space management. The source file is only removed if processing completes successfully and all output files are created.

Safety: Cannot be used with -SkipHeaderValidation to prevent accidental deletion of invalid files.

Warning: Source files are permanently deleted. Ensure output files are valid before using this option.

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

Bypasses the DNS debug log header validation check.

By default, the cmdlet validates that input files have a valid DNS Server debug log header. Use this switch to process files without validation, which can be useful for:

• Modified or custom log formats
• Troubleshooting validation issues
• Non-standard or pre-processed logs

Warning: May result in processing errors if the file is not a valid DNS log.

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

Shows what would happen if the cmdlet runs. The cmdlet is not run.

When specified, displays detailed information about the operations that would be performed without actually executing them. Useful for:

• Previewing which files would be processed
• Verifying output file paths before processing
• Testing scripts before running in production

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

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String[]

NOTES

Version : 1.7.0.0 Author : Andi Bellstedt, Copilot Date : 2026-01-25 Keywords : Microsoft Windows Server, DNSServer, DNS, DebugLog, LogParser

RELATED LINKS

• github.com/AndiBellstedt/DNSServer.DebugLogParser

6 - Usage Examples

These are examples with a little more depth and context. If you want to just the usage of the commands from the module, check out the command reference.

6.1 - Practical usage in a Domain Environment (GPO-driven collection and conversion)

This document outlines a practical, end-to-end example of running DNSServer.DebugLogParser in an Active Directory domain environment, focused on converting Windows DNS Server debug logs on domain controllers.

This example is accompanied by a ZIP archive, which provide the policy artifacts used to implement the workflow described here.
The most relevant artifacts are backup manifest, GPO report, Files.xml, Set-DNSServerDebugLogging.ps1, and ScheduledTasks.xml.

Scenario

• Multiple domain controllers (DCs) host the DNS Server role.
• DNS debug logging is enabled and configured consistently on each DC via a scheduled task (writing log files to C:\Administration\Logs\DNSServer).
• A centrally managed process converts logs into CSV for:
  • security analytics
  • operational reporting
  • troubleshooting
  • compliance/retention

Target outcomes

• Consistent conversion settings across all DCs
• Predictable output location and naming
• Optional compression to reduce storage footprint
• Optional statistics outputs for quick daily rollups
• Minimal host-side risk, with explicit rerun and cleanup considerations

Suggested architecture

Collection model: local convert + central pull

1. Each DC writes DNS debug logs to disk with rollover enabled.
2. Each DC converts rotated *.log files into a data CSV and statistics CSVs, then compresses the outputs into *.zip on a schedule (Task Scheduler).
3. Outputs are written next to the log files so the pipeline stays simple.
4. A central server collects the *.zip outputs, for example via file share ingestion, scheduled copy, SIEM forwarder, or an agent-based collector.

This model minimizes network reads of large raw log files and keeps parsing close to the data.

GPO workflow

The workflow is implemented through Group Policy (computer configuration) to ensure consistent settings across all domain controllers.

Reference implementation included in this repository (GPO report):

• Archive/report name: T0-C-Analytics-DNSDebugLogging
• Backup ID: {2B6F16BC-0E7C-4787-83D7-2854FED882EE}
• GPO link target: corp.company.com/Domain Controllers
• Item filter (used for both file deployment and scheduled tasks): only applies if C:\Windows\System32\dns.exe exists

1) Prerequisites (folders + module)

The provided backup assumes these folders already exist. Add separate GPP items if you want the deployment to create them automatically:

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

The provided backup also assumes Convert-DNSDebugLogFile is already available on the DCs. The conversion task starts Windows PowerShell 5.1 with -NoProfile and does not import the module explicitly, so the module must be installed in a machine-wide Windows PowerShell module path that is visible to LocalSystem. Recommended approaches:

• Install DNSServer.DebugLogParser on the DCs. For example, from PowerShell Gallery (if policy allows).
• Deploy the module via internal repo / file share so it is discoverable in $env:PSModulePath
• Add an explicit Import-Module to the task action if you want deterministic loading behavior

2) Deploy the debug logging configuration script (GPP Files)

The GPO deploys the script:

• Source (in SYSVOL via GPP): %GptPath%\Preferences\Files\Set-DNSServerDebugLogging.ps1
• Target (on each DC): C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1

This is implemented in the GPP Files preference item in Files.xml.

3) Scheduled task: configure DNS debug logging

The GPO creates a scheduled task named Set-DNSServerDebugLogging.

• Security context in the supplied backup: SYSTEM with logon type S4U
• Trigger in the supplied backup: daily (start boundary 2025-03-01T00:00:01)
• Action in ScheduledTasks.xml:
  • powershell.exe -ExecutionPolicy RemoteSigned -command " & { C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1 }"
  • Working directory: C:\Administration\Scripts

The linked Set-DNSServerDebugLogging.ps1 script configures DNS debug logging via Get-DnsServerDiagnostics / Set-DnsServerDiagnostics and (notably):

• Enables logging to file + rollover
• Writes to: C:\Administration\Logs\DNSServer\DnsDebugLog_<COMPUTERNAME>.<Domain>_.log
• Uses a 10 MB rollover size per file
• Captures primarily query-related activity (queries + notifications + updates + question transactions) and excludes full packet logging

4) Scheduled task: convert rotated debug logs to compressed CSV

The GPO creates a scheduled task named Convert-DNSDebugLogs.

• Security context in the supplied backup: SYSTEM with logon type InteractiveToken
• Trigger in the supplied backup: daily (start boundary 2026-01-01T00:30:00)
• Working directory: C:\Administration\Logs\DNSServer
• Action in ScheduledTasks.xml (formatted for readability):

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

Design notes:

• Select-Object -Skip 1 intentionally avoids processing the newest (active) log file.
• That means current data is exported only after rollover; on low-volume DCs, the active log may stay unprocessed for more than a day.
• Because Convert-DNSDebugLogFile defaults -OutputFile to “same folder, same name, .csv”, outputs land next to the *.log inputs.
• With -CompressOutput, each processed log produces a *.zip and the intermediate CSVs are removed.
• Unless you archive or delete processed *.log files, later runs will reprocess every non-active log again.
• The task throws if $Error.Count -gt 0 to signal a failed run.

5) Central ingestion

Options (pick one):

• File share ingestion: DC writes (or copies) C:\Administration\Logs\DNSServer\*.zip to \\fileserver\share\dns\$env:COMPUTERNAME\... (grant share and NTFS rights to the DC computer accounts or the Domain Controllers group if the task runs as SYSTEM)
• Pull model: central job reads \\dc\C$\Administration\Logs\DNSServer\*.zip (least preferred; requires admin shares)
• Agent forwarder: SIEM / log pipeline that ships the *.zip outputs

Operational considerations

• Least privilege: tasks run as SYSTEM; ensure the local folders are writable and that any UNC targets grant access to the computer account if used.
• Signing policy: both tasks use -ExecutionPolicy RemoteSigned; sign or unblock the deployed script and module according to your policy.
• Disk usage: -CompressOutput helps significantly, but this workflow does not remove source logs; plan retention and cleanup.
• Re-processing behavior: unless you archive or delete processed logs, the conversion task will process every non-active *.log file again on later runs. This is simple and robust, but it can overwrite outputs and create duplicate downstream ingestion if your collector does not deduplicate.
• Multi-DC consolidation: -ComputerName $env:COMPUTERNAME is included so consolidated datasets remain traceable.
• Validation: header validation remains enabled because the task does not use -SkipHeaderValidation (recommended).

Validate and adapt (using the ZIP)

Use the ZIP archive as the reference implementation, then align the following aspects to your environment:

• Target scope: which DCs / OUs receive the policy
• Execution identity: confirm both scheduled tasks use the intended logon type (S4U vs InteractiveToken) or normalize them to your standard
• Folder creation: decide whether C:\Administration\Scripts and C:\Administration\Logs\DNSServer are pre-staged elsewhere or should be created by additional GPP items
• Paths: confirm C:\Administration\Scripts and C:\Administration\Logs\DNSServer match your standards
• Retention: decide whether to keep raw logs and for how long (especially if enabling cleanup options)
• Ingestion: confirm where CSV/ZIP outputs are written and how they are collected centrally

If you want to validate the exact GPO configuration without importing it, the authoritative sources in this repo are:

• manifest.xml for backup metadata
• gpreport.xml for the human-readable full report
• Files.xml for file deployment
• Set-DNSServerDebugLogging.ps1 for script content
• ScheduledTasks.xml for scheduled tasks

6.2 - Scheduled Task Example

This script creates a Windows Scheduled Task that runs daily at 2:00 AM. It imports the module and processes all the log file in the folder where the script is executed (in this example “C:\Administration\Logs\DNS”). The process does compress the output into ZIP-files and removes the original to maintain hygiene.

$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"

6.3 - Security Analysis Workflow with SQL Server

This example shows a practical workflow for security analytics: parse a DNS debug log with Convert-DNSDebugLogFile, import the generated CSV into SQL Server, and run a query that highlights unusually high volumes of TXT record lookups.

For best interoperability, this example writes timestamps in an ISO-like format by using -OutputCulture 'sv-SE'.

Required modules

This example uses the following PowerShell modules:

• DNSServer.DebugLogParser
• SqlServer

Install them if needed:

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

Scenario

Use this workflow when you want to move parsed DNS debug log data into SQL Server so you can:

• search large datasets efficiently
• build repeatable detection queries
• correlate activity across multiple DNS servers
• retain normalized data for later investigation

Output of the conversion step

Convert-DNSDebugLogFile does not write directly to SQL Server. It first creates a CSV file. That CSV file is the dataset imported into the database.

In this example:

• input log: C:\Administration\Logs\DNS\dns.log
• generated CSV: C:\Administration\Logs\DNS\dns.csv
• destination table: dbo.DNSQueries

Create the target table

Run the following statement once in SQL Server to create the target table.

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 the log and import the CSV

The following PowerShell example performs the full workflow:

1. imports the required modules
2. converts the DNS debug log to CSV
3. loads the generated CSV
4. bulk imports the rows into 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 "The generated CSV file '$csvPath' does not contain any rows."
}

$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()
}

Query for suspicious TXT record activity

Once the data is in SQL Server, you can search for clients that issue unusually high numbers of TXT record queries.

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;

If you prefer to run the query from PowerShell, use Invoke-Sqlcmd from the SqlServer module:

$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

Why TXT queries are interesting

High volumes of TXT record lookups can be worth reviewing because they may indicate:

• DNS tunneling
• data exfiltration over DNS
• abuse of TXT records by malware or tooling
• unusually noisy or misconfigured clients

This query is only a starting point. In production, you should tune the threshold and add filters that match your environment.

Operational notes

• Import-Csv reads the full file into memory. For very large log exports, consider a streaming approach instead of building a full DataTable.
• Keep -ComputerName in the conversion step so records remain attributable after central ingestion.
• Use a consistent delimiter and culture during export and import.
• Validate retention, indexing, and access control in SQL Server before using this workflow for long-term storage.