vlan-probe 0.1.0__py3-none-any.whl

vlan_probe/__init__.py

@@ -0,0 +1,11 @@
+"""
+VLAN Isolation & Network Permission Probe Tool.
+
+Probes target VLAN subnets, IPs, and ports from the host environment to verify
+isolation policies and detect unauthorized inter-VLAN access violations.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["probe_target", "get_local_ips"]
+
+from .probe import get_local_ips, probe_target

vlan_probe/__main__.py

@@ -0,0 +1,6 @@
+"""Module entrypoint for vlan_probe package."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

vlan_probe/cli.py

@@ -0,0 +1,159 @@
+"""CLI interface for VLAN probe tool."""
+
+import argparse
+import datetime
+import json
+import os
+import sys
+
+from .config import DEFAULT_CONFIG_PATH, load_config
+from .probe import get_local_ips, probe_target
+
+# ANSI color codes for interactive (TTY) output.
+_COLORS = {
+    "reset": "\033[0m",
+    "bold": "\033[1m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "cyan": "\033[36m",
+}
+
+
+def colorize(text: str, color: str) -> str:
+    """Apply ANSI color to text if color is enabled."""
+    if not color:
+        return text
+    return f"{_COLORS[color]}{text}{_COLORS['reset']}"
+
+
+def may_colorize() -> bool:
+    """Check if output should be colorized."""
+    return sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def resolve_color_mode(mode: str) -> bool:
+    """Resolve color mode setting to boolean."""
+    if mode == "always":
+        return True
+    if mode == "never":
+        return False
+    return may_colorize()
+
+
+def colorize_json_statuses(line: str, color: bool) -> str:
+    """Colorize JSON status values in output."""
+    if not color:
+        return line
+    line = line.replace('"status": "PASS"', f'"status": "{colorize("PASS", "green")}"')
+    line = line.replace('"status": "FAIL"', f'"status": "{colorize("FAIL", "red")}"')
+    return line
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(description="Probe VLAN network access and verify isolation permissions.")
+    parser.add_argument("-c", "--config", default=DEFAULT_CONFIG_PATH, help="Path to config JSON file")
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["ndjson", "json", "table"],
+        default="ndjson",
+        help="Output format (default: ndjson).",
+    )
+    parser.add_argument(
+        "-t",
+        "--timeout",
+        type=float,
+        default=2.0,
+        help="Socket connection timeout in seconds",
+    )
+    parser.add_argument(
+        "-s",
+        "--strict",
+        action="store_true",
+        help="Exit with code 1 if any access violation / test failure occurs",
+    )
+    parser.add_argument(
+        "--color",
+        choices=["auto", "always", "never"],
+        default="auto",
+        help="Colorize table output. auto = on when stdout is a TTY",
+    )
+    args = parser.parse_args()
+    color = resolve_color_mode(args.color)
+
+    targets = load_config(args.config)
+
+    results = []
+    violations = []
+    local_ips = get_local_ips()
+
+    for target in targets:
+        res = probe_target(target, timeout=args.timeout, local_ips=local_ips)
+        results.append(res)
+        if res["status"] == "FAIL":
+            violations.append(res)
+
+        if args.format == "ndjson":
+            print(colorize_json_statuses(json.dumps(res), color))
+
+    if args.format == "json":
+        summary = {
+            "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "total_probed": len(results),
+            "passed": len(results) - len(violations),
+            "failed": len(violations),
+            "violations": [
+                {
+                    "vlan": v["target_vlan"],
+                    "target": v["target_name"],
+                    "ip": v["target_ip"],
+                    "port": v["port"],
+                    "error": v["error"],
+                }
+                for v in violations
+            ],
+            "results": results,
+        }
+        print(colorize_json_statuses(json.dumps(summary, indent=2), color))
+
+    elif args.format == "table":
+        if color:
+            header = (
+                f"{colorize('VLAN', 'cyan'):<12} "
+                f"{colorize('TARGET', 'cyan'):<30} "
+                f"{colorize('ENDPOINT', 'cyan'):<22} "
+                f"{colorize('STATUS', 'cyan'):<8} "
+                f"{colorize('DETAILS', 'cyan')}"
+            )
+            divider = colorize("-" * 90, "cyan")
+        else:
+            header = f"{'VLAN':<12} {'TARGET':<30} {'ENDPOINT':<22} {'STATUS':<8} {'DETAILS'}"
+            divider = "-" * 90
+        print(header)
+        print(divider)
+        for r in results:
+            endpoint = f"{r['target_ip']}:{r['port']} ({r['protocol']})"
+            details = r["error"] if r["error"] else "OK"
+            status = r["status"]
+            if color:
+                status_color = "red" if status == "FAIL" else "green"
+                details_color = "red" if status == "FAIL" else "green"
+                status = colorize(str(status), status_color)
+                details = colorize(str(details), details_color)
+            print(f"{r['target_vlan']:<12} {r['target_name']:<30} {endpoint:<22} {status:<8} {details}")
+
+    if args.strict and violations:
+        head = f"{len(violations)} unauthorized connection(s) detected!"
+        if color:
+            head = colorize(colorize("VLAN ISOLATION VIOLATION FAILURE:", "bold") + " " + head, "red")
+        sys.stderr.write(f"\n🚨 {head}\n")
+        for v in violations:
+            line = f"  - {v['error']}"
+            sys.stderr.write((colorize(line, "red") if color else line) + "\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

vlan_probe/config.py

@@ -0,0 +1,64 @@
+"""Configuration loading for vlan_probe."""
+
+import sys
+from typing import Any, Dict, List
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    try:
+        import tomli as tomllib  # Fallback for Python < 3.11
+    except ImportError:
+        tomllib = None
+
+DEFAULT_CONFIG_PATH = "/etc/vlan_probe.toml"
+
+
+def load_config(config_path: str) -> List[Dict[str, Any]]:
+    """
+    Load and parse configuration file.
+
+    Supports TOML and JSON formats based on file extension.
+
+    Args:
+        config_path: Path to configuration file
+
+    Returns:
+        List of target dictionaries
+
+    Raises:
+        SystemExit: On configuration loading or parsing errors
+    """
+    try:
+        if config_path.endswith(".toml"):
+            if tomllib is None:
+                sys.stderr.write(
+                    "Error: TOML support requires 'tomli' package for Python < 3.11. Install with: pip install tomli\n"
+                )
+                sys.exit(2)
+            with open(config_path, "rb") as f:
+                config_data = tomllib.load(f)
+        else:
+            # Fallback to JSON for other extensions
+            import json
+
+            with open(config_path, "r", encoding="utf-8") as f:
+                config_data = json.load(f)
+    except FileNotFoundError:
+        sys.stderr.write(f"Error: Config file not found: {config_path}\n")
+        sys.exit(2)
+    except Exception as e:
+        sys.stderr.write(f"Error loading config file '{config_path}': {e}\n")
+        sys.exit(2)
+
+    # Extract targets from config (support nested structure)
+    if isinstance(config_data, dict):
+        targets = config_data.get("targets", [])
+    else:
+        targets = config_data if isinstance(config_data, list) else []
+
+    if not isinstance(targets, list):
+        sys.stderr.write("Error: 'targets' in config must be a list\n")
+        sys.exit(2)
+
+    return targets

vlan_probe/probe.py

@@ -0,0 +1,125 @@
+"""Core VLAN probe functionality."""
+
+import datetime
+import socket
+import subprocess
+import time
+from typing import Dict, Optional, Set
+
+DEFAULT_TIMEOUT = 2.0
+
+
+def get_local_ips() -> Set[str]:
+    """Get all local IP addresses on this host."""
+    ips: Set[str] = {"127.0.0.1"}
+    try:
+        out = subprocess.check_output(["ip", "-o", "-4", "addr", "show"], text=True, timeout=2)
+        for line in out.splitlines():
+            parts = line.split()
+            if len(parts) >= 4:
+                ip = parts[3].split("/")[0]
+                ips.add(ip)
+    except Exception:
+        try:
+            hostname = socket.gethostname()
+            for ip in socket.gethostbyname_ex(hostname)[2]:
+                ips.add(ip)
+        except Exception:
+            pass
+    return ips
+
+
+def probe_target(
+    target: Dict[str, object], timeout: float = DEFAULT_TIMEOUT, local_ips: Optional[Set[str]] = None
+) -> Dict[str, object]:
+    """
+    Probe a single target to verify VLAN access permissions.
+
+    Args:
+        target: Dict with keys: name, vlan, ip, port, protocol, expected_blocked
+        timeout: Socket timeout in seconds
+        local_ips: Set of local IPs (auto-detected if None)
+
+    Returns:
+        Dict with probe result including status, latency, and error details
+    """
+    if local_ips is None:
+        local_ips = get_local_ips()
+
+    name = str(target.get("name", "Unknown Target"))
+    vlan = str(target.get("vlan", "Unknown VLAN"))
+    ip = str(target.get("ip"))
+    port_raw = target.get("port", 80)
+    port = int(port_raw) if isinstance(port_raw, (int, str)) else 80
+    protocol = str(target.get("protocol", "tcp")).lower()
+    expected_blocked = bool(target.get("expected_blocked", True))
+
+    is_self = ip in local_ips
+
+    start_time = time.time()
+    reachable = False
+    error_msg: Optional[str] = None
+
+    if protocol == "tcp":
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        try:
+            sock.connect((ip, port))
+            reachable = True
+            sock.close()
+        except (socket.timeout, ConnectionRefusedError, OSError):
+            reachable = False
+    elif protocol == "udp":
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.settimeout(timeout)
+        try:
+            if port == 53:
+                dns_query = b"\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x07example\x03com\x00\x00\x01\x00\x01"
+                sock.sendto(dns_query, (ip, port))
+            else:
+                sock.sendto(b"\x00", (ip, port))
+            sock.recvfrom(1024)
+            reachable = True
+        except socket.timeout:
+            reachable = False
+        except Exception:
+            reachable = False
+        finally:
+            sock.close()
+
+    latency_ms = round((time.time() - start_time) * 1000, 2)
+
+    if is_self:
+        passed = True
+        error_details: Optional[str] = (
+            f"EXEMPT_SELF_HOST: Target {ip}:{port} ({name}) is the local interface of the probing host"
+        )
+    elif expected_blocked:
+        passed = not reachable
+        if reachable:
+            error_details = (
+                f"UNAUTHORIZED_CONNECTIVITY_VIOLATION: Host can connect outside to "
+                f"restricted VLAN '{vlan}' at {ip}:{port} ({name})"
+            )
+        else:
+            error_details = None
+    else:
+        passed = reachable
+        if not passed:
+            error_details = f"EXPECTED_CONNECTIVITY_FAILED: Failed to connect to {name} ({ip}:{port})"
+        else:
+            error_details = None
+
+    return {
+        "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "target_name": name,
+        "target_vlan": vlan,
+        "target_ip": ip,
+        "port": port,
+        "protocol": protocol,
+        "reachable": reachable,
+        "expected_blocked": expected_blocked,
+        "status": "PASS" if passed else "FAIL",
+        "latency_ms": latency_ms,
+        "error": error_details or error_msg,
+    }

vlan_probe-0.1.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: vlan-probe
+Version: 0.1.0
+Summary: VLAN Isolation & Network Permission Probe Tool
+Project-URL: Homepage, https://github.com/hellqvio86/vlan-probe
+Project-URL: Repository, https://github.com/hellqvio86/vlan-probe
+Author: hellqvio
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: tomli>=1.2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# vlan-probe
+
+VLAN Isolation & Network Permission Probe Tool — standalone project extracted
+from the Ansible role in ansible-home-baseline.
+
+`vlan-probe` is a command-line tool. Install it with [pipx](https://pipx.pypa.io/)
+so it runs in an isolated environment and the `vlan-probe` command is available
+on your `PATH`.
+
+## Requirements
+
+- Python 3.10 or newer
+
+## Installation
+
+### Install with pipx (recommended)
+
+```bash
+pipx install vlan-probe
+```
+
+Upgrade to a newer release:
+
+```bash
+pipx upgrade vlan-probe
+```
+
+If you do not already have pipx, install it first (macOS/Homebrew, Debian/Ubuntu
+or Arch examples; see the [pipx docs](https://pipx.pypa.io/) for other systems):
+
+```bash
+brew install pipx && pipx ensurepath
+# or
+apt install pipx && pipx ensurepath
+# or
+pacman -S python-pipx && pipx ensurepath
+```
+
+### Install from source
+
+```bash
+# with pipx
+pipx install .
+
+# with uv (alternative)
+uv tool install .
+
+# or install directly into your environment
+pip install .
+```
+
+## Usage
+
+1. Install or copy to a host.
+2. Create a TOML config at `/etc/vlan_probe.toml` or pass `-c` to point to a different file.
+3. Run `vlan-probe -f table` or `python -m vlan_probe -f table`.
+
+### Configuration
+
+Configuration uses TOML format for easy human readability and simplicity:
+
+```toml
+[[targets]]
+name = "Internal - Device A SSH"
+vlan = "Internal"
+ip = "192.168.1.10"
+port = 22
+protocol = "tcp"
+expected_blocked = true
+
+[[targets]]
+name = "Internal - Gateway HTTP"
+vlan = "Internal"
+ip = "192.168.2.1"
+port = 80
+protocol = "tcp"
+expected_blocked = true
+
+[[targets]]
+name = "External - Public DNS"
+vlan = "External"
+ip = "8.8.8.8"
+port = 53
+protocol = "udp"
+expected_blocked = false
+```
+
+### Options
+
+```
+-c, --config PATH         Path to config TOML file (default: /etc/vlan_probe.toml)
+-f, --format FORMAT       Output format: ndjson, json, or table (default: ndjson)
+-t, --timeout SECONDS     Socket connection timeout (default: 2.0)
+-s, --strict              Exit with code 1 if any violations occur
+--color [auto|always|never]  Colorize output (default: auto)
+```
+
+### Examples
+
+```bash
+# Display as table
+vlan-probe -c ./vlan_probe.toml -f table
+
+# Output JSON
+vlan-probe -f json
+
+# Strict mode with custom timeout
+vlan-probe -s -t 5.0
+
+# No color output
+vlan-probe -f table --color never
+```
+
+## Development
+
+```bash
+uv sync          # install dev dependencies
+uv run pytest    # run tests
+uv run ruff check . && uv run ruff format --check .   # lint
+uv run mypy src  # type check
+```
+
+## License
+
+MIT (see LICENSE)

vlan_probe-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+vlan_probe/__init__.py,sha256=TCq8CZROxw24wS8sbZ3AlBScNmnczCGuupp1eVjcSCg,324
+vlan_probe/__main__.py,sha256=mh23umaaV-HntetBr-saUihxqaBgsGDtGxB3gSczPNc,110
+vlan_probe/cli.py,sha256=T6hYHE9mHUDp5XHpduf0hp-pGvmohfqzRhqjgzQCr2A,5138
+vlan_probe/config.py,sha256=LMz9Z3jH96Eo8K5UyEmzTVmhu0SP0Cmg_Y9-UiyOjws,1883
+vlan_probe/probe.py,sha256=Z__1edtn5YPOBXhNOs1GW_7f466rBt5LI_ojTlaDGWI,4016
+vlan_probe-0.1.0.dist-info/METADATA,sha256=7K-un1h3oQIsFxi5Vv9FaZEaRpGkgpTdGrCp75UCLRA,3137
+vlan_probe-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+vlan_probe-0.1.0.dist-info/entry_points.txt,sha256=raJAYMaxPIKuMakWaQHAHYlYOlC0hLXl2JCaeN_cfVE,51
+vlan_probe-0.1.0.dist-info/licenses/LICENSE,sha256=dh_ozxjkgzEj63HxBsSRHCaa1FugZLJaAO4AuzPSdWY,1065
+vlan_probe-0.1.0.dist-info/RECORD,,

vlan_probe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vlan_probe-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vlan-probe = vlan_probe.cli:main

vlan_probe-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hellqvio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.