This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
evtx: anetstandard2.0NuGet library (package idevtx) that parses Windows event logs (MS-EVEN6).EvtxECmd: the command line tool (net472;net10.0) that uses it. Its CSV, JSON and XML output is what people compare and script against, so keep column order and formats stable.evtx/Maps: the YAML maps (Channel_Provider_EventID.map) that EvtxECmd uses to fill PayloadData1-6 and the other columns.--syncdownloads them from this repo's master branch..github/skills/evtxecmd-mapsdescribes how to write them, andverify.ymlruns yamllint on them.
Input may be corrupt or hostile.
The SDK is pinned in global.json (.NET 10). The library uses LangVersion 10. Tests target net10.0 and use NUnit 5 + FluentAssertions 7 (pinned to [7.2.2,8.0.0), since 8.x requires a commercial license).
dotnet build -c Release # builds evtx.slnx (EvtxECmd for net472 and net10.0)
dotnet test -c Release # CI; CorpusTests is [Explicit] and skipped
dotnet test -c Release --filter "FullyQualifiedName~CorpusTests" # every .evtx in ../Corpus/EventLogs (or EVTX_CORPUS), slow
dotnet test --filter "FullyQualifiedName~BinXmlTests" # one fixture
dotnet pack -c Release # only the library is packable- File: a 4 KB header (
ElfFile, chunk count, flags, CRC of 0x00-0x77), then 64 KB chunks.EventLogreads the chunks and parses them in parallel batches (each chunk has its own string and template tables).GetEventRecordsyields the records in file order. A chunk without theElfChnksignature is skipped, and a short last chunk is padded with zeros. - Chunk (
ChunkInfo): a 512 byte header, then records up to the free space offset, or to the end of the chunk when that offset is bad. Parsing stops after the record whose number is the header's last record id; everything after it is slack. The header CRC covers 0x00-0x77 and 0x80-0x1FF;DataCrccovers the records. Both are only reported, never enforced. - Record:
**\0\0, size, record number, FILETIME, BinXml, then the size again. A record whose size does not fit stops the chunk. A record that throws goes toErrorRecords(keyed by record number), and parsing continues with the next one. - Hidden records (DanderSpritz's eventlogedit grows a record over the one it deletes):
ExtraDataOffsetis a**within 16 bytes after the BinXml ends (the old heuristic, kept for the CSV column). If a whole record with a different number is there, it is parsed and returned withHiddenRecord. - BinXml (
BinXml/):BinXmlParserbuilds nodes,Renderersubstitutes template values into anOutElementtree, and the outputs are written from that tree.- Elements inside template definitions carry a 2 byte dependency id after the token. Record-level elements and nested BinXml (type 0x21) values do not. Forwarded events have no templates, so getting this wrong is what broke them (issue #15).
- Names and template definitions are either inline (their offset is the current position) or references to an earlier offset in the chunk. Template definitions are cached per chunk by offset.
- ValueText tokens are a type byte followed by the value (strings are length-prefixed).
- MS-EVEN6 says an element whose dependency value is NULL is not rendered, but they are (as old EvtxECmd and the Rust parser do). Leaving them out dropped
<Binary></Binary>and empty<Data>from many records. - CharRef, EntityRef, CDATA and PI tokens are supported.
- Values (
ValueFormatter) keep the old EvtxECmd text formats: hex for HexInt,0x..for size_t, and SIDs read by their subauthority count. A FILETIME or SYSTEMTIME that is not valid is shown as hex. Runs of control characters become ", ". Real64 arrays are supported.
The old code built XML text and reloaded it into XmlDocument, XPathDocument and Json.NET. The new code writes all of these from the tree, and reproduces the old output byte for byte (except for fixes such as no double escaping of &). Keep it that way: the corpus comparisons depend on it.
XmlTextOutputmatches XmlDocument's beautified output (ConvertPayloadToXml,--xml).Payloadis the EventData/UserData XML with LF line breaks, as the old XmlReader extract had them.JsonOutputmatches Json.NET'sSerializeXmlNode:@attr,#text, arrays for repeated names,nullfor<x/>and""for<x></x>. The payload uses LF (PayloadAsJson); the whole event uses CRLF (EventAsJson, for--fj).OutNavigatoris an XPathNavigator over the tree. Maps run their XPath queries against it, with the same values an XPathDocument of the event XML had: no xmlns attributes, whitespace-only text dropped, CRLF in text.RenderingInfo(from forwarded events) is JSON, and EvtxECmd writes it as the last CSV column.EventLog.PreparePayloadJson/PrepareXmlbuild the JSON or XML while chunks are parsed in parallel.
EventLog.LoadMapsdeserializes every*.mapin parallel (YamlDotNet is most of a small log's run time), then, in name order, validates it (FluentValidation), and keys it byEventId-Channel-Provider. It returns true when a map had errors. A second map for the same key is skipped with a warning (issue #241 was a check that left out the provider, so it threw).- A map's
Lookupstranslate values;Mapscombine XPathValuesinto a property withPropertyValue(%name%placeholders). EventRecord.MapValue: aValuethat is a path gives the first node's text; an expression (issue #99, e.g.round(a div b * 100)) gives its result, numbers formatted like XPath'sstring(), NaN/Infinity as not found. XPaths are compiled once and checked when maps load. Older EvtxECmd versions drop the event when a Value is an expression, and--syncgives them the repo's maps, so maps in the repo don't use expressions yet.
EventLogParseException(Offset,Field) means the file is not an event log ("Invalid signature! Expected 'ElfFile'").- Everything else is logged (Serilog) and listed in
EventLog.ErrorRecords/ChunkInfo.ErrorRecords, and parsing continues. --co(Issues #259, on by default,--co falseturns it off): the console messages also go to<ts>_EvtxECmd_<version>_ConsoleLog.txt(ConsoleLog.cs;tsis the UTC time of the output file names) in the first of--csv,--json,--xml, with the[HH:mm:ss.fff LVL]template; without an output directory there is no log file (no warning:--cois on by default). The sameConsoleLog.csis in every EZ Tools CLI tool.DateTimeOffsetFormatteruses--dtonly when the placeholder has no format of its own (the log template's{Timestamp:HH:mm:ss.fff}was shown with--dt).- EvtxECmd exit codes are only 0 and 1. 1 is a failure of the tool: a bad argument, a missing -f/-d path, a file that can't be opened or read (in use and not readable raw, IO error), a folder under -d that can't be read (reported as "Unable to read folder : " and the run goes on; net10.0 uses the
EvtxFinderFileSystemEnumerator, net472 the AlphaFSErrorFilter, withoutContinueOnException, which would skip such folders without calling it), or output that can't be written. Damaged files (not an event log, record errors) are reported and exit 0.
evtx.Test (net10.0) references the library and EvtxECmd. TestFiles/ and the maps are copied to the output.
BinXmlTests(withEvtxBuilder/ChunkBuilder, which build chunks token by token): templates, nested BinXml, forwarded-style records, references, hidden records, bad input. Add regression tests here.SampleTests: the gzipped samples from omerbenamram/evtx (MIT) inTestFiles/rust-evtx(see the README there). The record counts match the Rustevtx_dump.CliTests: EvtxECmd output and exit codes.MapTests: every map inevtx/Mapsloads, with no duplicates.CorpusTests: every.evtxin a local collection that is not in the repo,Corpus/EventLogsnext to the repo (orEVTX_CORPUS). Never copy its files into the repo.- Validation against the old EvtxECmd and the Rust parser over the corpus plus the DFIR Artifact Museum (1,039 logs): the counts match Rust (1,614,510 records vs 1,614,500; the 10 extra are in a ForwardedEvents chunk that Rust drops), and payload JSON and map fields match the old Json.NET/XPathDocument results for every record.
- The library's version comes from the git tag through MinVer (bare tags like
2026.10.0). There is no<Version>in its csproj. The 2026.5.0 tag is not in master's history, so MinVer ignores it. - EvtxECmd has
<Version>in its csproj, bumped by hand. It is not packed. - To release the library: push to
master, thengit tag <ver> && git push origin <ver> && gh release create <ver> --verify-tag --generate-notes. .github/workflows/publish.ymlis identical to GuidMapping's. It packs, validates and tests on PRs and on pushes tomaster. When a GitHub Release is published, it pushes to NuGet.org with trusted publishing (NuGet/loginwith theNUGET_USERrepo variable,EricRZimmerman).- Dependabot (
.github/dependabot.yml) opens monthly PRs for GitHub Actions and NuGet updates. - Release builds are staged, signed and zipped by
Build-ZimmermanTools.ps1in the get-zimmermantools repository (cloned next to this one). Its program table says what goes in this tool's download zip (the files taken from the build, folders copied from the repositories, files kept from the current release zip); a new output file, a content folder or a change in how the tool is built (single file, another framework) needs that entry updated. - pdbs are embedded in the assemblies (
DebugType embedded,EmbedUntrackedSources) and Release builds setContinuousIntegrationBuild(source paths/_/...), both inDirectory.Build.props: stack traces and Exceptionless reports have file and line numbers, and no .pdb file ships. Don't addDebugType(orDebugSymbols,IncludeSymbols, snupkg) to project files.