# mgf-vm-forensics

> **VM-forensics analysis library for the Magogi Foundation distributed
> vm-vmanager-app.** pcap / dpkt analyzers, case management, top-talkers,
> DNS extraction, TLS-SNI extraction. Sibling library extracted from
> the original vm-vmanager-app forensics subsystem.

| Field | Value |
|---|---|
| **Status** | `0.1.0` (unreleased). Extracted per D-C1 in `vm-vmanager-docs/DECISIONS.md`. |
| **Federation sibling.** | Depends on `mgf-common>=0.41,<0.43` + `mgf-vm-core>=0.1,<0.2` + `dpkt`. (Drained off the `mgf-vm` umbrella — now RETIRED & DELETED — on 2026-06-05.) |
| **Surface.** | [`PUBLIC_API.md`](PUBLIC_API.md) · [`PUBLIC_API.json`](PUBLIC_API.json). |
| **Conformance level.** | **L2 — Standard.** Per-rule ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). |
| **License.** | MIT. |
| **Python.** | 3.11 / 3.12 / 3.13. |

---

## Where the docs live

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/` ·
> Codeberg: `vm-vmanager-docs`

| What | Where |
|---|---|
| End-to-end architecture | `vm-vmanager-docs/ARCHITECTURE.md` |
| Why this is its own sibling (D-C1) | `vm-vmanager-docs/DECISIONS.md` Category C |
| Component inventory | `vm-vmanager-docs/COMPONENTS.md` |
| Roadmap (Phase 0 Stream F — sibling extractions) | `vm-vmanager-docs/ROADMAP.md` |
| Test strategy | `vm-vmanager-docs/TESTING.md` |

---

## What this library is — and why it's a sibling

The forensics surface (pcap parsing, packet analyzers, case management,
TLS-SNI / DNS / top-talkers extraction) is **not VM-engine primitive**
— it doesn't belong in `mgf-vm-core`. It is also **not fleet logic**
— it doesn't belong in the control plane. And it has **genuine reuse
value beyond vm-vmanager-app** (security researchers, incident-response
tooling, anyone analyzing captured network bytes).

That makes it a **sibling library** per D-C1: lifted out of the old
vm-vmanager-app forensics subsystem, exposed via its own PyPI distribution,
consumed by `vm-vmanager-app` (and by anyone else who wants pcap
analysis with the `mgf-common` discipline).

## What this library contains

(Phase 0 — sibling extraction from current `mgf-vm/src/mgf/vm/forensics/`.)

```
src/mgf/vm/forensics/
├── __init__.py          # public re-exports (AP-01)
├── py.typed
├── case.py              # Case / Artifact frozen data model
├── store.py             # CaseStore — atomic CRUD + status state machine
├── manifest.py          # SHA-256 integrity manifest
├── archive.py           # bundle a case into tar.gz
├── render.py            # orchestrate report rendering for a case
├── live.py              # live tcpdump tail + rolling stats
├── capture/             # network / filesystem / memory / screenshot capture
├── analysis/            # read-only analyzers: network, filesystem, ioc, timeline
└── reports/             # rendered findings → typed report objects (Markdown)
```

The original surface from `mgf.vm.forensics` ports here largely as-is.
Phase 0 work is the extraction + the conformance audit, not a rewrite.

---

## What this library does NOT contain

- **No VM driving** — that's `mgf-vm-libvirt` / `mgf-vm-firecracker`.
- **No GUI / CLI** — consumers (e.g., `vm-vmanager-app`'s forensics
  windows) render the typed reports + own the command orchestration.
  This library exposes the capture/analysis functions; the consumer
  wires them to commands and windows.

---

## Install

```bash
pip install mgf-vm-forensics
```

## Develop

```bash
cd ~/PycharmProjects/mgf-vm-forensics
uv venv --python 3.12
uv sync --extra dev
uv run pytest -q
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports
uv run python tools/generate_public_api_json.py   # regenerate PUBLIC_API.json
```

## Federation context

Sibling library. Per discipline:
- **`DEPS.md`** — bidirectional dependency manifest (§1 what it depends
  on, §2 who depends on it — replaces the former `USERS.md` per DOC-16)
- **`STANDARDS_NOTE.md`** — conformance argument
- **`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`** — per-rule status

Security: `dpkt` parses attacker-controllable bytes — see `SECURITY.md`
(SH-05 carried forward from the original vm-vmanager-app).
