VLANVerify

Security & trust

Why should you trust VLANVerify?

VLANVerify typically runs as root, connected to a trunk port carrying every VLAN on your network, and its report is meant to stand as audit evidence. That only works if the tool, and the site you downloaded it from, earn the same scrutiny you'd give any privileged, unattended software producing evidence you rely on. Here is what we do so that they can.

Trusting the tool

Every line is readable

VLANVerify is open source under the MIT License. There is no closed-source component, no obfuscation and no compiled blob: the code you run is the code in the repository.

Tests reachability only

A scan creates VLAN sub-interfaces on the one device it runs on and sends ordinary ICMP pings and TCP connection attempts. It never edits switch, router or firewall configuration, and never blocks, redirects, spoofs or injects traffic on any VLAN.

No telemetry, no automatic external calls

VLANVerify never phones home. The only network activity is the scan you explicitly run against your own policy file, plus one deliberate reachability test to whichever internet_target your policy configures (1.1.1.1 by default) when a rule targets internet.

Small, named dependencies

Four MIT/BSD-licensed Python libraries (Click, pydantic, PyYAML, Jinja2), each listed with its licence on the documentation page. No third-party source is vendored into the project.

Tested with the network mocked

Live interface orchestration and probing need root and real hardware, so the test suite exercises the schema, verdict logic and report rendering entirely against the dry-run/mock backends. The thin modules that actually touch ip and open sockets are deliberately the smallest surface.

Fails loudly, not silently

A VLAN that never gets an address, or a rule with no live host to test against, is reported as such (and marked INCONCLUSIVE) rather than fabricated or silently skipped. Live scanning on a non-Linux OS exits with a clear error instead of pretending to run.

The report is self-contained

report.html has no external CSS, JavaScript, fonts or images. Opening it fetches nothing, and its content is entirely determined by your policy file and what the scan actually measured.

What VLANVerify touches on your machine

A live scan reads your policy YAML file, and writes to two places you control: temporary VLAN sub-interfaces on the trunk NIC you point it at (removed again afterwards unless --keep-interfaces is given), and the HTML report file at the path you pass to --output. It shells out to the system ip command to create/delete those sub-interfaces, and to a DHCP client if a VLAN is configured to try DHCP. Beyond that, its only network activity is the ICMP pings and TCP connection attempts your policy's rules describe.

TCP probes are bound to the correct VLAN sub-interface with SO_BINDTODEVICE rather than relying on the OS routing table, so a probe can't silently be sent out the wrong VLAN and invalidate the test it's supposed to be running.

Running as root safely

Creating a tagged VLAN sub-interface requires elevated privileges (root, or CAP_NET_ADMIN at minimum), so a live vlanverify scan typically runs under sudo. VLANVerify does not modify system-wide network configuration, DNS, routing tables beyond what a sub-interface needs, or any file outside the report path you specify; sub-interfaces it creates are torn down at the end of the run unless you explicitly ask it to keep them.

Destructive actions never happen silently

VLANVerify has no command that deletes data, credentials or configuration. The closest thing, tearing down the VLAN sub-interfaces it created for the scan, is the default behaviour at the end of every run and is announced in the console output; --keep-interfaces opts out of it entirely.

The honest limit

VLANVerify reports what it actually measured, at the moment it measured it. A scan is a point-in-time snapshot, not continuous monitoring: a configuration change made after a scan could reopen a path that held during it, and an INCONCLUSIVE verdict means exactly that, not a disguised pass. A tool that claimed otherwise would be the one not to trust. Re-scan after any change to segmentation-relevant configuration.

Trusting this website

vlanverify.com is a static-feeling PHP site whose only job is to document the project and point you at the real artifacts.

  • No third-party requests. No analytics, no tag managers, no tracking pixels, no A/B tools, no web fonts and no CDN. Every asset (CSS, JavaScript, images) is served from vlanverify.com itself. The only JavaScript is a small menu toggle and the terminal replay on the home page.
  • No cookies, no accounts, no forms. The site sets no cookies and collects nothing from you. There is nothing to log in to and nothing to submit.
  • Locked-down headers. A strict Content-Security-Policy built on default-src 'self' with object-src 'none' and frame-ancestors 'none', plus X-Content-Type-Options: nosniff, X-Frame-Options: DENY, a tight Referrer-Policy, a Permissions-Policy that denies camera, microphone and geolocation, and HTTP Strict Transport Security. HTTPS is forced and all plain-HTTP requests are redirected.
  • The site is open source too. It lives in its own repository under the same MIT licence, so you can read or diff exactly what is serving these pages.
  • This site is documentation, not the source of truth. Every install instruction points at GitHub. If this domain ever disappeared, nothing about VLANVerify would change.

Standard web-server access logs (IP, timestamp, requested path, user agent) may be retained for a short period for abuse and reliability purposes. That is the extent of it.

Verifying your download

Install VLANVerify only from this source:

SourceCanonical location
Source & releasesgithub.com/rosscooney/vlanverify

VLANVerify is not yet published on PyPI or any other package index; treat anything claiming to be a "VLANVerify" package elsewhere with suspicion until it is. Before you install or upgrade:

  • Pin a tag rather than floating on main, and read the release notes and the diff for that tag on GitHub.
  • Inspect the source if you want to; it is pure Python with no compiled or obfuscated component. Clone the repository and read it directly.
# Pin an exact tag rather than floating on main
pip install git+https://github.com/rosscooney/[email protected]

# Confirm what you got, offline
vlanverify --help
vlanverify validate --policy policies/example.yaml

Running it well

VLANVerify's usefulness depends on the scan actually testing what you think it's testing:

  • Confirm the trunk port really carries every VLAN in your policy before scanning; a switch port that isn't trunking a VLAN under test produces misleading INCONCLUSIVE results, not a false pass.
  • Run with sudo, or grant CAP_NET_ADMIN to a non-root user. Without it, VLANVerify cannot create the VLAN sub-interfaces a live scan needs.
  • Re-scan after any change to switch, firewall or VLAN configuration; see the honest limit above.
  • Treat an INCONCLUSIVE verdict as a gap to close (add a target_ip, check the VLAN actually got an address), not as a pass.
  • Keep the policy file that produced a report alongside it; the report records the policy's file hash so the two can be tied together as one piece of evidence.

See the usage documentation for the full command reference.

Reporting a vulnerability

If you believe you have found a security vulnerability in VLANVerify, please report it privately. Do not open a public GitHub issue for security vulnerabilities.

  • GitHub private vulnerability reporting: use the “Report a vulnerability” button under the repository's Security tab (Security → Advisories).
  • Email: [email protected].

Please include:

  • a description of the issue and its impact,
  • steps to reproduce or a proof of concept,
  • affected version(s) or commit hash,
  • any suggested remediation.

In scope, for example: a way for a scan to modify switch, router or firewall configuration, or to send traffic beyond an ICMP ping and a TCP connect attempt to the addresses your policy describes; a way for VLANVerify to bind a probe to the wrong VLAN sub-interface without reporting it; unsafe handling of the policy file or the generated report; a way for the report to embed unsanitised, attacker-controlled content (for example from a device's response) that could execute when opened in a browser; or a way for a live scan to leave VLAN sub-interfaces or other state behind that a subsequent, unrelated scan would silently reuse. Not in scope: “VLANVerify reported INCONCLUSIVE instead of a definitive verdict” on its own is not a vulnerability (it's the intended, honest behaviour when evidence is incomplete), though improvements to discovery or target-resolution coverage are welcome as normal issues or pull requests.

What to expect from us

  • Acknowledgement of your report as soon as reasonably possible.
  • An assessment of the issue and, where accepted, a fix or mitigation.
  • Credit in the release notes if you would like it.

VLANVerify is built and maintained by Stable State Consulting Ltd (www.stablestate.co.uk).