VLANVerify

Get VLANVerify · v0.1.1

Download & install

VLANVerify is an MVP: source and releases live on GitHub; this site hosts no binaries, and there is no packaged PyPI release yet. It requires Python 3.10+ everywhere, and Linux (developed and tested on Raspberry Pi OS / Debian) for a live scan, since that needs ip (iproute2), a DHCP client (dhclient or dhcpcd) and SO_BINDTODEVICE. --dry-run mode works on any OS with Python 3.10+, no root and no real network interface required.

Releases on GitHub Source repository

1. pip, straight from GitHub (quickest)

Installs the vlanverify package and its CLI launcher without cloning the repository yourself. Pin a tag rather than floating on main if you want a stable copy.

python3 -m venv ~/.venvs/vlanverify
~/.venvs/vlanverify/bin/pip install git+https://github.com/rosscooney/vlanverify.git

# pin a specific tagged release instead of the latest commit on main:
~/.venvs/vlanverify/bin/pip install \
    git+https://github.com/rosscooney/[email protected]

Live scanning needs raw interface control, so scan typically runs under sudo. A pip install --user or venv install puts vlanverify somewhere sudo's reset PATH may not see; run it with the venv's full path if so:

sudo ~/.venvs/vlanverify/bin/vlanverify scan --policy policy.yaml \
    --interface eth0 --output report.html

2. From a checkout (development, or to read the source first)

git clone https://github.com/rosscooney/vlanverify && cd vlanverify
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

# with the dev extra, for the test suite:
pip install -e ".[dev]"
pytest

The test suite runs entirely against the dry-run/mock backends (see Security & trust), so it needs no root privileges, no Linux, and no real network.

Verify your install

vlanverify --help
vlanverify validate --policy policies/example.yaml

policies/example.yaml, included in the repository, is a three-VLAN (corp/guest/iot) policy you can read as a starting point for your own; see the policy file schema.

Before you rely on a report

Run VLANVerify on a Linux device connected to a trunk port carrying every VLAN you want to test, as root or with CAP_NET_ADMIN at minimum (creating VLAN sub-interfaces requires it). A scan is a point-in-time snapshot: re-run it after any change to switch, firewall or VLAN configuration rather than relying on an older report.

Upgrading

There is no auto-update mechanism; VLANVerify makes no automatic network calls of its own. Re-install from a newer tag or from main:

pip install --upgrade --force-reinstall \
    git+https://github.com/rosscooney/vlanverify.git

The changelog and the GitHub releases call out any change to the policy schema, verdict logic or CLI flags.