Metadata-Version: 2.4
Name: mgf-vm-forensics
Version: 0.1.9
Summary: Magogi Foundation VM-forensics — pcap / dpkt analyzers, case management, top-talkers, DNS, TLS-SNI. Sibling library extracted from vm-vmanager-app.
Project-URL: Documentation, https://codeberg.org/magogi-admin/vm-vmanager-docs
Project-URL: Source, https://codeberg.org/magogi-admin/mgf-vm-forensics
Author: Bassam Alsanie, mgf-vm-forensics contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: dpkt,forensics,mgf,pcap,security,vm
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Requires-Dist: dpkt<2,>=1.9
Requires-Dist: mgf-common<1.0,>=0.41
Requires-Dist: mgf-vm-core<0.2,>=0.1.9
Provides-Extra: dev
Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mgf-test-supervisor<0.2,>=0.1.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml<7,>=6.0; extra == 'dev'
Provides-Extra: standards
Requires-Dist: mgf-common[standards]<1.0,>=0.46; extra == 'standards'
Description-Content-Type: text/markdown

# 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).
