# PUBLIC_API — `mgf-vm-forensics`

> **Master-HEAD banner (REL-03):** reflects CURRENT main/release; verify your pin via `pip show mgf-vm-forensics` + `mgf.vm.forensics.__version__` (mirrors pyproject). `PUBLIC_API.json` is generated from `__all__` + pinned in CI.


> The contract surface of this library: every public name, its
> stability tier, the version it appeared in, and a one-line
> description. Tracks `__all__` per **AP-10** / **DOC-08**; the
> machine-readable companion is [`PUBLIC_API.json`](PUBLIC_API.json),
> generated by [`tools/generate_public_api_json.py`](tools/generate_public_api_json.py).
> Both are pinned in CI against the source (`tests/unit/.../test_public_api_pin.py`).

| Field | Value |
|---|---|
| Version | `0.1.0` |
| Import namespace | `mgf.vm.forensics` |
| Stability | **Experimental** across the board — pre-`1.0`; surfaces may change without a deprecation cycle (per **AP-03** `0.x`). |

## Stability tiers

- **Stable** — covered by the deprecation policy; breaking changes only on MAJOR.
- **Experimental** — may change/break on any MINOR while `0.x` (**AP-03**).
- **Internal** — underscored modules / names; not importable as contract (**AP-14**).

Everything below is **Experimental** at `0.1.0`. Names appeared in `0.1.0`
unless noted.

---

## `mgf.vm.forensics` (top-level re-exports)

The curated convenience surface — re-exports the most common case,
capture, and manifest names so consumers can `from mgf.vm.forensics
import Case, CaseStore, ...`.

| Name | Kind | Description |
|---|---|---|
| `__version__` | str | Library version string. |
| `Case` | dataclass | One forensic investigation, persisted to `case.yaml`. |
| `CaseStatus` | enum | Case lifecycle state (PREPARING → ACTIVE → COMPLETED → ARCHIVED). |
| `Artifact` | dataclass | One captured piece of evidence inside a case. |
| `ArtifactKind` | enum | Discriminator for `Artifact` (pcap, fs.diff, memory.dump, …). |
| `CASE_SCHEMA_VERSION` | int | On-disk `Case` schema version. |
| `CaseStore` | class | Atomic CRUD + status state machine over the case directory. |
| `CASE_FILENAME` | str | The case YAML filename (`case.yaml`). |
| `default_forensics_dir` | func | Canonical forensics root (`~/.local/share/vmanager/forensics`). |
| `Manifest` / `ManifestEntry` | model | SHA-256 integrity manifest + one row. |
| `VerifyResult` | model | Outcome of `verify_manifest`. |
| `MANIFEST_FILENAME` / `MANIFEST_SCHEMA_VERSION` | str / int | Manifest file name + schema version. |
| `build_manifest` / `save_manifest` / `load_manifest` / `verify_manifest` | func | Manifest build / persist / read / integrity-check. |
| `FilesystemBaseline` / `FilesystemDiff` / `FileEntry` | model | Filesystem capture types. |
| `FS_BASELINE_SCHEMA_VERSION` / `FS_DIFF_SCHEMA_VERSION` | int | FS capture schema versions. |
| `capture_filesystem_baseline` / `capture_filesystem_diff` / `walk_tree` | func | Filesystem capture entry points. |
| `capture_memory` / `capture_screenshot` | func | Memory dump + screenshot capture. |
| `NetworkCaptureHandle` / `NetworkCaptureStatus` | dataclass | Network-capture handle + status. |
| `start_network_capture` / `stop_network_capture` / `network_capture_status` / `list_network_captures` | func | Persistent pcap-capture lifecycle. |

## `mgf.vm.forensics.case`

| Name | Kind | Description |
|---|---|---|
| `Case` | dataclass | Frozen investigation record (round-trips through YAML). |
| `CaseStatus` | enum | Lifecycle state. |
| `Artifact` | dataclass | One captured evidence file + its hash/metadata. |
| `ArtifactKind` | enum | Artifact discriminator. |
| `CASE_SCHEMA_VERSION` | int | `Case` schema version. |

## `mgf.vm.forensics.store`

| Name | Kind | Description |
|---|---|---|
| `CaseStore` | dataclass | Atomic create/load/save/list/delete + status transitions. |
| `CASE_FILENAME` | str | `case.yaml`. |
| `default_forensics_dir` | func | Canonical forensics root, resolved at call time (CF-04). |

## `mgf.vm.forensics.manifest`

| Name | Kind | Description |
|---|---|---|
| `Manifest` / `ManifestEntry` | model | Integrity manifest + row. |
| `VerifyResult` | model | Verification outcome (mismatches / missing / unexpected). |
| `MANIFEST_FILENAME` / `MANIFEST_SCHEMA_VERSION` | str / int | File name + schema version. |
| `build_manifest` / `save_manifest` / `load_manifest` / `verify_manifest` | func | Build / persist / read / integrity-check. |

## `mgf.vm.forensics.archive`

| Name | Kind | Description |
|---|---|---|
| `archive_case` | func | Bundle a case directory into a `tar.gz`; transition to ARCHIVED. |

## `mgf.vm.forensics.render`

| Name | Kind | Description |
|---|---|---|
| `render_case_report` | func | Render a Markdown report for a case to `<case>/reports/`. |

## `mgf.vm.forensics.live`

| Name | Kind | Description |
|---|---|---|
| `live_network_tail` | func | Stream `tcpdump -nl` for a bridge until cancelled. |
| `live_network_stats` | func | Stream pcap from tcpdump + print rolling counters. |
| `LiveCounter` | dataclass | Mutable rolling counters for live stats. |
| `format_stats` | func | Render a `LiveCounter` to a multi-line display. |
| `update_counter_from_pcap_chunk` | func | Feed a pcap byte-chunk into a `LiveCounter`. |
| `DEFAULT_STATS_INTERVAL` | float | Default refresh interval (1.0 s). |

## `mgf.vm.forensics.analysis`

| Name | Kind | Description |
|---|---|---|
| `analyze_pcap` | func | Stream-analyse a pcap → `NetworkAnalysis`. |
| `iter_packets` | func | Yield `(timestamp, raw_bytes)` per packet (pcap/pcapng). |
| `NetworkAnalysis` / `ProtocolBreakdown` / `TalkerPair` | dataclass | Network analyzer outputs. |
| `DnsQuery` / `TlsSni` / `HttpRequest` | dataclass | Per-protocol extracted records. |
| `load_diff` / `summarize_diff` / `render_diff_table` | func | Filesystem-diff analysis helpers. |
| `DiffSummary` / `DiffRenderRow` | dataclass | FS-diff analysis outputs. |
| `extract_strings` / `hash_file` / `scan_yara` | func | IOC analyzers (strings, multi-hash, optional YARA). |
| `StringHit` / `FileHashes` / `YaraMatch` | dataclass | IOC analyzer outputs. |
| `default_yara_rule_dir` | func | Default YARA rules directory. |
| `DEFAULT_MIN_STRING_LENGTH` | int | Default minimum string length for `extract_strings`. |
| `build_timeline` | func | Build a chronological `TimelineEvent` list for a case. |
| `TimelineEvent` | dataclass | One event on the case timeline. |

## `mgf.vm.forensics.capture`

| Name | Kind | Description |
|---|---|---|
| `capture_filesystem_baseline` / `capture_filesystem_diff` / `walk_tree` / `load_baseline` | func | Filesystem baseline + diff capture. |
| `FilesystemBaseline` / `FilesystemDiff` / `FileEntry` | model | Filesystem capture types. |
| `BASELINE_SCHEMA_VERSION` / `DIFF_SCHEMA_VERSION` | int | FS capture schema versions. |
| `capture_memory` / `capture_screenshot` | func | Memory dump + screenshot capture. |
| `start_network_capture` / `stop_network_capture` / `network_capture_status` / `list_network_captures` | func | Persistent pcap-capture lifecycle. |
| `NetworkCaptureHandle` / `NetworkCaptureStatus` | dataclass | Network-capture handle + status. |

## `mgf.vm.forensics.reports`

| Name | Kind | Description |
|---|---|---|
| `render_markdown_report` | func | Render `ReportInputs` → a Markdown report string. |
| `ReportInputs` | dataclass | Aggregated analyzer outputs fed to the renderer. |

---

## Transitional note

While the `mgf-vm` umbrella is the dependency (pre `mgf-vm-core`
Phase 0 Stream A), the umbrella ships a copy of `mgf.vm.forensics` as a
regular package, which shadows this repo's tree at import time. This
PUBLIC_API is generated **statically** from this repo's source so it
always describes the surface this repo ships. See
[`tools/generate_public_api_json.py`](tools/generate_public_api_json.py)
and `DEPS.md`.
