Metadata-Version: 2.5
Name: flotilla-forensics
Version: 0.2.0
Summary: 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).
Project-URL: Documentation, https://codeberg.org/magogi-admin/flotilla-docs
Project-URL: Source, https://codeberg.org/magogi-admin/flotilla-forensics
Author: Bassam Alsanie, flotilla-forensics contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: dpkt,flotilla,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: flotilla-core<0.3,>=0.2
Requires-Dist: mgf-common<1.0,>=0.41
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

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

```bash
pip install flotilla-forensics
```

## Develop

```bash
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).
