Add openvixdisklib as an open NBD replacement for VMware VDDK.

VDDK is no longer publicly distributed, so this library reverse-engineers the vSphere NFC path and exposes ConnectEx, Open, Read, and Write without the proprietary SDK. Co-authored-by: Cursor <[email protected]>
2026-09-07 11:41:01 +00:00
commit 4ddf0c015d
31 changed files with 4089 additions and 0 deletions
@@ -0,0 +1,68 @@
+# AI agent guidelines
+
+## Overview
+
+- This is a test project meant to bypass/replace VDDK, which is no longer
+  publicly available.
+- The end goal is to have a Python library that can be used as a VDDK replacement
+  to retrieve VMware disk contents.
+- Integration tests under `tests/integration/` are a good starting point for
+  interacting with the VMware NBD / NFC APIs. They inherit lab credentials and
+  VM/disk settings from `tests.integration.base.TestBase`. The base
+  class creates a temporary empty VM for the run. We can make use of
+  them to reverse engineer the VMware protocol, for example making various
+  calls, capturing the request and replies and then trying to determine the
+  structures used by the protocol.
+- tcpdump may be used to intercept the communication with ESXI
+- if deemed helpful, we may write a simple service that impersonates ESXI,
+  capturing the information sent by VDDK
+- we should reuse pyVmomi for any operation that it supports. It's publicly
+  available and safe to use.
+- `docs/` contains various documents that describe the reverse engineered
+  vmware APIs and resulting modules.
+- Use `docs/reverse_engineering_procedure.md` to best describe the steps that
+  were undertaken to reverse engineer the Vmware APIs.
+
+
+## Architecture
+
+- The project uses Python and must be Python 3.12 compatible.
+- Library code lives in the `openvixdisklib` package (`nfc_auth`, `nfc_open`,
+  `openvixdisklib`).
+- The `.vddk` dir contains the VDDK libraries and their dependencies, including
+  `libvixDiskLib`. These files shouldn't be included in git commits due to
+  licensing constrains.
+- `tests/integration/vixdisklib.py` is a Python wrapper on top of
+  `libvixDiskLib`, used to cross-check the replacement against native VDDK.
+- Integration tests live under `tests/integration/`, use the unittest
+  framework, and inherit `tests.integration.base.TestBase`. Lab vCenter
+  credentials, datacenter, and datastore come from repo-root
+  `.test_config.yaml` (gitignored; sample in `README.md`). Each test
+  class shares a temporary empty VM with a 10 GiB disk created in
+  `TestBase.setUpClass` and destroyed in `tearDownClass`. Run them with
+  `tox -e integration` or
+  `.venv/bin/python -m unittest discover -s tests/integration`.
+
+
+## Other rules
+
+- AI agents should ignore folders that start with a dot, e.g. .mypy_cache, .ruff_cache, .tox
+- AI agents may use the `.venv/` virtual env, it is expected to have
+  all project dependencies, including the `pyVmomi` vmware client
+- AI agents should not generate unit or integration tests unless asked to.
+- When modifying Markdown tables, the columns should be properly aligned.
+- If an agent regenerates a file, avoid appending the new content, but instead
+  replace the file contents. We don't want duplicate definitions.
+- Empty __init__.py files should not contain license headers.
+- Use Linux style line endings.
+- All public methods should include docstrings. Subclasses may reuse the ones
+  from the parent class.
+- Avoid defining new methods for trivial checks such as `server.power_status == "RUNNING"`,
+  make the checks inline.
+- Avoid removing inline comments that are still applicable.
+- Agents should use type hints when the argument type can be determined.
+- When writing unit tests, assert_has_calls is preferred instead of checking
+  the call cound and call parameters separately.
+- When writing unit tests, mock decorators are preferred instead of context
+  managers.
+- If a folder or file under this directory is inaccessible, ask for permissions.