# Atlant Scalpel

> **Surgical NTFS timeline extraction for DFIR.** Scope a live volume, disk image, or VSS shadow
> copy by time, file type, path, or filename — then carve a verified, full-fidelity binary slice
> or export a plaso-ready super-timeline. Developed by [Atlant Security](https://atlantsecurity.com) ·
> Freeware · [Download](https://atlantsecurity.com/downloads) · see [MARKETING.md](MARKETING.md) for the full overview.

A Windows DFIR tool that loads an NTFS `$MFT` and USN Change Journal (`$J`), lets you pick a date/time window, and carves a **smaller-but-valid binary slice** of those artifacts for that window — plus MFTECmd-schema CSV exports and an enriched MFT+USN timeline.

**Genuine novelty:** no existing open-source or commercial tool performs time-windowed *binary* slicing of `$MFT`/`$J`. Binary carvers (MftCarver, UsnJrnlCarver, TSK `icat`) filter by structure only. Date-range tools (Velociraptor, plaso, MFTECmd, analyzeMFT) emit text/rows only. The intersection — filter by timestamp window *and* emit a valid binary artifact — is what this tool does.

---

## What it produces

| Output | Description |
|--------|-------------|
| **Binary `$MFT` slice** | Position-preserving, sparse, re-parse-verified. Retains in-window records + system metafiles + all ancestor directories. Opens in MFTECmd, analyzeMFT, TSK without modification. |
| **Binary `$J` slice** | USN records verbatim, original offsets preserved via sparse gaps, 8-byte alignment maintained. |
| **`slice.manifest.json`** | Provenance sidecar written alongside every binary slice. Documents chain-of-custody so a DFIR analyst can defend the derived artifact. Fields: `tool`, `toolVersion`, `generatedUtc`, `source` (label + kind), `window` (fromUtc/toUtc), `recordSize`, `mft` (slicePath, sourceRecordCount, retainedCount, verification), `usn` (slicePath, or absent when no `$J` was sliced), `filters` (extensionMode, extensions, excludedPaths). |
| **MFT-only CSV** | 34-column MFTECmd schema. Drops straight into Timeline Explorer. |
| **USN-only CSV** | MFTECmd `JEntryOut` schema (13 columns). |
| **Enriched timeline CSV** | USN events as spine, each row enriched with full path, MACB timestamps, file size, `SeqMatch`, `SI<FN`, `uSecZeros` from the MFT. |

---

## Sources

| Source | How |
|--------|-----|
| Extracted `$MFT` / `$J` files | **Load ▾ → Open $MFT file…** (then *Attach $J journal…*); FTK Imager / KAPE / RawCopy dumps |
| Raw/dd disk images | **Load ▾ → Open disk image…** — DiscUtils opens the container, enumerates partitions, presents the NTFS volume |
| VHD / VHDX / VMDK images | Same path as raw/dd |
| Live NTFS volume (`\\.\C:`) | **Load ▾ → Open volume…** — requires Administrator; sector-size queried from the volume, not assumed |
| Mounted volume (any drive letter) | Same path as live — mount an E01 in FTK/Arsenal Image Mounter and point at the drive letter |

> **E01/EWF:** no native managed reader yet. Workaround: mount the E01 with FTK Imager or Arsenal Image Mounter, then use "Load volume…" with the resulting drive letter.

---

## Features

- **Binary time-slice (hero)** — position-preserving + sparse; FILE record fixup arrays preserved verbatim; retention rule includes system metafiles (located by walking `$Extend` index, never hardcoded entry numbers), all `$FN`-parent directories, base/extension record pairs; orphaned records land in lost-and-found rather than failing; slice is re-parsed and verified before reporting success.
- **CSV export** — MFT-only (34 cols), USN-only (13 cols), enriched timeline; row-per-file or event-per-timestamp projection; MFTECmd/Timeline Explorer compatible.
- **Correlation** — 64-bit `FILE_REFERENCE` join (48-bit entry number + 16-bit sequence number); `SeqMatch = false` surfaces slot-reuse (the USN event refers to a now-overwritten file); `SI<FN` and `uSecZeros` timestomp indicators.
- **GUI** — WPF, native Windows 11 Mica/Acrylic glass (WPF-UI 4.3), theme follows OS with manual light/dark toggle; MFT / USN / Enriched views; event-density histogram; **"Anomalies only" filter** (one toggle to surface just the timestomped `SI<FN` / `µsec=0` and slot-reused records); file-type + path export filters; "N of M records in window" live counter with an in-window anomaly count.
- **Bounded memory** — `MftIndex` + streaming parse; a 1M-record / ~1 GB `$MFT` runs at ~650 MB working set. Grid display capped at 200,000 rows (narrow the time window for larger datasets; true match count is always shown).
- **Source abstraction** — `IArtifactProvider` interface; all sources reduce to two seekable streams (`$MFT`, `$J`) before the engine sees them.

---

## Architecture

```
AtlantScalpel.Core   (headless engine — reusable, no WPF dependency)
├── Sources/   IArtifactProvider + ExtractedFilesProvider, VolumeArtifactProvider,
│              ImageArtifactProvider, SectorReader
├── Mft/       RawMftReader, MftLayout, MftRecord, MftInterpreter, MftIndex,
│              PathResolver, Anomalies, Frn, Fixup
├── Usn/       RawUsnReader, UsnRecord, UsnReason
├── Slicing/   TimeWindow, FilterPredicate, RetentionSet, SelectionBuilder,
│              MftSliceWriter, UsnSliceWriter, SliceVerifier, ExportFilter,
│              SliceManifest, SliceManifestWriter
├── Correlate/ Enricher, EnrichedEvent
├── Export/    MftCsvWriter, UsnCsvWriter, EnrichedCsvWriter, CsvExportEngine, Csv
└── Io/        SparseFile
SliceEngine.cs  (top-level orchestrator)

AtlantScalpel.App    (WPF GUI over AtlantScalpel.Core)
└── MainViewModel, MainWindow (FluentWindow + Mica), CsvExportDialog, SampleVolume, …
```

Target: `net10.0-windows` (WPF). Core library is `net10.0` (no Windows dependency — usable headlessly).

Key dependencies: [DiscUtils (LTRData fork)](https://github.com/LTRData/DiscUtils) for image/NTFS/volume access and [WPF-UI (lepoco)](https://github.com/lepoco/wpfui) for Fluent controls and Mica/Acrylic. CSV writing and the in-memory MFT index are hand-rolled in `AtlantScalpel.Core` — no ORM, CSV-library, or database dependency.

---

## Build & run

**Prerequisites:** .NET 10 SDK; Windows (WPF + raw volume access).

```powershell
# Build everything
dotnet build

# Run tests (390+ passing)
dotnet test

# Run the GUI
dotnet run --project src/AtlantScalpel.App
```

### Startup arguments

| Argument | Effect |
|----------|--------|
| `--sample` | Auto-load the built-in sample VHDX on launch (demo / screenshot mode) |
| `--light` / `--dark` | Force theme; skips OS-follow (useful for deterministic screenshots) |
| `--view mft\|usn\|enriched` | Select initial grid tab |
| `--load <mft-path>` | Auto-load an extracted `$MFT` file on launch |
| `--loadusn <j-path>` | Attach a `$J` to the `--load` MFT |
| `--loadimage <image-path>` | Auto-open a disk image (raw/dd, VHD, VHDX, VMDK) |
| `--loadvolume <drive-letter>` | Auto-open a live or mounted NTFS volume (requires Admin) |

Example: `AtlantScalpel.App.exe --load C:\evidence\MFT --loadusn C:\evidence\J`

---

## CLI (`scalpel`)

`AtlantScalpel.Cli` is a thin, scriptable front-end over the same `AtlantScalpel.Core` engine used by the GUI.
Build it once and pipe its output into other tools or shell scripts.

```powershell
# Run from source (no publish needed)
dotnet run --project src/AtlantScalpel.Cli -- --help
```

### Commands

| Command | Description |
|---------|-------------|
| `slice` | Time-window binary slice of `$MFT` (and `$J` when available) |
| `csv`   | Export `$MFT` / `$J` / enriched timeline as CSV |
| `vss`   | List Volume Shadow Copies (requires Administrator) |

### Source resolution (`--source`)

| Value | Provider |
|-------|----------|
| `C` / `C:` / `C:\` | Live or mounted NTFS volume (`\\.\C:`) — requires Administrator |
| `vss:N` | Nth shadow copy, newest-first (run `scalpel vss` to list) — requires Administrator |
| `\\?\GLOBALROOT\Device\HarddiskVolumeShadowCopyN` | Shadow copy device path (from `scalpel vss` DeviceObject column) — requires Administrator |
| Path ending in `.vhdx/.vhd/.vmdk/.raw/.dd/.img/.001` | Disk image via DiscUtils |
| Any other path | Extracted `$MFT` file; pair with `--usn <j-path>` for journal |

### Quick examples

```powershell
# List shadow copies (run elevated):
scalpel vss

# Slice the newest shadow copy (run elevated):
scalpel slice --source vss:1 --from "2023-01-01 00:00:00" --to "2023-12-31 23:59:59" --out D:\out

# Slice a live volume (run elevated):
scalpel slice --source C --from "2023-01-01 00:00:00" --to "2023-12-31 23:59:59" --out D:\out

# Slice an image, exclude Windows noise:
scalpel slice --source E:\evidence.vhdx --from 2023-06-01 --to 2023-06-30 --out D:\out `
              --exclude-path "\Windows;\$Extend"

# Slice extracted files, include-only exe/dll:
scalpel slice --source C:\triage\MFT --usn C:\triage\J `
              --from "2023-06-01 00:00:00" --to "2023-06-30 23:59:59" `
              --out D:\out --ext exe,dll --include

# Enriched timeline CSV from an image:
scalpel csv --source E:\evidence.vhdx --kind enriched --layout event `
            --from "2023-01-01 00:00:00" --to "2023-12-31 23:59:59" --out D:\timeline.csv
```

Progress and diagnostics go to **stderr**; machine-readable key=value output goes to **stdout**.

Exit codes: `0` ok · `1` usage error · `2` source error · `3` verification failed (slice only).

---

## Publish (self-contained)

```powershell
.\publish.ps1
```

Produces a **folder** publish at `src\AtlantScalpel.App\bin\Release\net10.0-windows\win-x64\publish\` (~150 MB, ~411 files). Every DLL ships beside `AtlantScalpel.App.exe` — no `%TEMP%` native-extraction at launch (the single-file bundle mode extracts native libs to `%TEMP%`, touching a host you may be analyzing).

The script contains a commented Authenticode signing step (`signtool sign /fd SHA256 /a /tr <timestamp-url> /td SHA256`) to enable with your own cert before distribution.

If E01 support is later added via `libewf`, ship `libewf.dll` as a loose file beside the exe (LGPL-3.0 user-relinking provision; also keeps it at a fixed path so AV/EDR does not flag extraction-to-temp).

---

## Status

| Phase | Status | Delivers |
|-------|--------|----------|
| 1 — Core + hero slice | Done | Source abstraction, raw-record reader, MFT index, path resolver, binary slicer, round-trip verifier |
| 2 — Correlate + CSV | Done | FRN join, SeqMatch, timestomp indicators, MFT/USN/enriched CSV (MFTECmd schema), projections |
| 3 — WPF GUI | Done | Mica/Acrylic window, virtualized grid, density histogram, details pane, export bar, theme toggle |
| 4 — Real sources | Done | Live volume (`\\.\C:`), mounted drive, disk images (raw/VHD/VHDX/VMDK), sector-size-aware reads |
| 5 — CLI + package | Done | `AtlantScalpel.Cli` — `slice` + `csv` commands, hand-rolled arg parser, full source resolution, 50 CLI tests |
| 6 — VSS CLI surface | Done | `scalpel vss` list command; `--source vss:N` index resolution; shadow-copy device-path source; injected enumerator seam for tests |

**Not yet implemented:** native E01 reader (use mount workaround); `$LogFile` parsing; bodyfile/plaso output.

**Tests:** 390+ xUnit tests passing (unit, integration, large-scale synthetic MFT round-trip, CLI).

---

## Docs

- [Design specification](docs/superpowers/specs/2026-06-23-atlant-scalpel-design.md) — full architecture, binary slice algorithm, retention rule, schema, packaging rationale
- [Phase 1 plan](docs/superpowers/plans/2026-06-23-atlant-scalpel-phase1-core-slice.md)
- [Phase 2 plan](docs/superpowers/plans/2026-06-23-atlant-scalpel-phase2-correlation-csv.md)
- [Phase 4 plan](docs/superpowers/plans/2026-06-24-atlant-scalpel-phase4-sources.md)
