magogi/prod/: flotilla-forensics-0.2.0 metadata and description

Simple index

Flotilla's VM forensics (formerly mgf-vm-forensics) — pcap / dpkt analyzers, case management, top-talkers, DNS, TLS-SNI. Sibling library extracted from the Flotilla app (formerly vm-vmanager-app).

author	Bassam Alsanie, flotilla-forensics contributors
classifiers	Development Status :: 2 - Pre-Alpha Intended Audience :: Developers Intended Audience :: Information Technology License :: OSI Approved :: Apache Software License Operating System :: POSIX :: Linux Programming Language :: Python :: 3 Programming Language :: Python :: 3.11 Programming Language :: Python :: 3.12 Programming Language :: Python :: 3.13 Topic :: Security Topic :: System :: Networking :: Monitoring
description_content_type	text/markdown
keywords	dpkt, flotilla, forensics, mgf, pcap, security, vm
license	Apache-2.0
license_file	LICENSE NOTICE
metadata_version	2.5
project_urls	Documentation, https://codeberg.org/magogi-admin/flotilla-docs Source, https://codeberg.org/magogi-admin/flotilla-forensics
requires_dist	dpkt<2,>=1.9 flotilla-core<0.3,>=0.2 mgf-common<1.0,>=0.41 hypothesis<7,>=6.100; extra == 'dev' import-linter<3,>=2.0; extra == 'dev' mgf-test-supervisor<0.2,>=0.1.2; extra == 'dev' mypy<2,>=1.10; extra == 'dev' pytest-cov<7,>=5.0; extra == 'dev' pytest-timeout<3,>=2.3; extra == 'dev' pytest<9,>=8.0; extra == 'dev' ruff<0.16,>=0.4; extra == 'dev' types-pyyaml<7,>=6.0; extra == 'dev' mgf-common[standards]<1.0,>=0.46; extra == 'standards'
requires_python	>=3.11

Because this project isn't in the mirror_whitelist, no releases from root/pypi are included.

File	Tox results	History
flotilla_forensics-0.2.0-py3-none-any.whl Size 63 KB Type Python Wheel Python 3		Uploaded to magogi/prod by magogi 2026-10-13 19:14:40
flotilla_forensics-0.2.0.tar.gz Size 199 KB Type Source		Uploaded to magogi/prod by magogi 2026-10-13 19:14:41

flotilla-forensics

Formerly mgf-vm-forensics (renamed at 0.2.0, D25). import mgf.vm.forensics still works through the mgf-vm-forensics 0.2.0 compat distribution until flotilla-forensics 0.4.0.

VM-forensics analysis library for Flotilla (the Magogi Foundation's distributed VM manager, currently 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.2.0`. Extracted per D-C1 in `flotilla-docs/DECISIONS.md`.
Federation sibling.	Depends on `mgf-common>=0.41,<1.0` + `flotilla-core>=0.2,<0.3` + `dpkt`. (Drained off the `mgf-vm` umbrella — now RETIRED & DELETED — on 2026-06-05.)
Surface.	`PUBLIC_API.md` · `PUBLIC_API.json`.
Conformance level.	L2 — Standard. Per-rule ledger: `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`.
License.	Apache-2.0.
Python.	3.11 / 3.12 / 3.13.

Where the docs live

flotilla-docs — ~/PycharmProjects/flotilla-docs/ · Codeberg: flotilla-docs

What	Where
End-to-end architecture	`flotilla-docs/ARCHITECTURE.md`
Why this is its own sibling (D-C1)	`flotilla-docs/DECISIONS.md` Category C
Component inventory	`flotilla-docs/COMPONENTS.md`
Roadmap (Phase 0 Stream F — sibling extractions)	`flotilla-docs/ROADMAP.md`
Test strategy	`flotilla-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 flotilla-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/flotilla/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 (now mgf.flotilla.forensics). 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

pip install flotilla-forensics

Develop

cd ~/PycharmProjects/flotilla-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).

devpi