Repository navigation
XMAT-021: Headless XMAT - add xmat, a command line that analyzes captures without the GUI - #158
Draft
Gerardo Malpartida (GerardoMal-ATG) wants to merge 5 commits into
Conversation
The UI test fixture deleted its per-run app storage only at process exit, which the test host usually kills first, so runs leaked XMAT-UI-Tests-* folders. A custom assembly runner now stops the app, closes its log and deletes the run's own folder before the assembly reports completion; a folder that can't be deleted fails the run instead of leaking. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 270d0c0c-8578-4bd6-aa1d-c32a56075710
AnalyzeCaptureOperation runs the existing rules on .saz files, .xmatcap files and the GUI's records, and the GUI analyzer becomes an adapter with unchanged report formats. It returns a summary of findings per device and console without request data. Fiddler archives pass the same archive check as GUI imports and are then read within source, entry, total and record limits; HTTP bodies stay opaque, and malformed parts are skipped with data-free warnings. Capture databases are opened through the same guarded, read-only path as the GUI, and the input's SHA-256 is computed from that same open file. The polling and repeated-call rules pair and link calls without rescanning them and group calls by their exact request body instead of a 32-bit hash, so findings change only where two different bodies collided. The throttled-call, batch-frequency and call-frequency rules no longer rescan their calls or build regular expressions per call, and Small-Batch Detection keeps its statistics per run. All rule work in one analysis shares a work and memory budget; a capture that exceeds it fails with analysis.rules.work-limit, or an error in the GUI, instead of continuing unbounded rule evaluation. Report JSON is streamed to its files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 270d0c0c-8578-4bd6-aa1d-c32a56075710
Saving to a .xmatcap file that XMAT has open in a tab, including through a different letter case or a hard link, is now refused up front with an error message instead of failing with an unhandled file-in-use error. A save now writes the capture to a short temporary file in the destination folder and then moves it over the destination, so a failed or interrupted save leaves the original file untouched. Save failures show a message that contains no capture data. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 270d0c0c-8578-4bd6-aa1d-c32a56075710
xmat.exe analyzes .saz and .xmatcap files without the GUI: analyze, doctor, help and --version, one JSON document on stdout, stable exit codes, staged atomic output and Ctrl+C handling. xmat analyze takes --max-input-mib, --max-data-mib, --max-record-mib and --max-records within fixed ranges; anything else is a usage error that names the option but never its value. Captures the GUI refuses are refused here too, with exit code 3: SQLite journal or write-ahead log files next to the capture (-journal, -wal or -shm), or a database in write-ahead-log mode, report analysis.input.live-database; a location without a normalized path reports analysis.input.location-unsupported; and a file another program has open for writing reports analysis.input.unreadable. xmat asks the .NET garbage collector to conserve memory; the GUI's setting is unchanged. Every GUI entry point is classified as supported, planned or GUI-only, non-UI code may not add dialog or dispatcher calls, and the headless code may not use GUI globals. docs/cli.md covers usage, output, exit codes, compatibility and the capability table, and CONTRIBUTING describes the parity rules and the operation layer. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 270d0c0c-8578-4bd6-aa1d-c32a56075710
CI copies xmat.exe next to the GUI and smoke-runs its --version and doctor commands from the packaged folder, and the README points to the command line. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 270d0c0c-8578-4bd6-aa1d-c32a56075710
Gerardo Malpartida (GerardoMal-ATG)
requested a review
from Stephen Spiller (sspiller-atg)
October 31, 2026 07:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
xmat.exe, a command line that analyzes existing captures without the GUI (#58), and parity checks that classify every discovered GUI entry point as supported, planned or GUI-only, so command-line support is tracked as features are added. It also hardens and speeds up the analysis code that both front ends now share.Stacked on #156. This diff shows only the headless changes; it retargets to
mainwhen #156 merges.xmatopens captures through #156's checks, so it refuses the same files as the GUI.Try it (from the build output, next to the GUI)
Commits (each builds and passes tests)
AnalyzeCaptureOperation, with bounded SAZ reading, faster rules under a shared work budget, and repeated and polling calls grouped by their exact request body.xmatcommand line (analyze,doctor, JSON output, exit codes,--max-*limits), the parity checks,docs/cli.mdand CONTRIBUTING.xmat.exe.Please review first
docs/cli.md: exit codes, thexmat-cli/1andxmat-analysis/1JSON, limits and budgets.GUI behavior changes
Limits: 512 MiB input, 256 MiB data, 32 MiB per record and 100,000 records by default, raisable to 2,048, 512, 128 and 250,000. On the input-limit test corpus, runs at the defaults stayed under 1.4 GiB and 15 seconds, and at the maximums under 2.4 GiB and 25 seconds. These are observations, not bounds: run xmat with time and memory limits.
--outmust be on storage with Windows permissions, such as NTFS.Not in this PR: command-line versions of live capture, sanitized conversion, HTML reports and network-trace analysis; the GUI already has these.
docs/cli.mdlists them as planned, andxmatrejects them as unknown commands until they ship.Once this merges, a PR that adds GUI commands or windows (for example #145) also classifies each new entry point in
CapabilityRegistry.cs; the parity test names any it misses.