audnet 0.1.2__py3-none-any.whl

audnet/__init__.py

@@ -0,0 +1,8 @@
+"""Network Security & Compliance State Auditor."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("audnet")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

audnet/cli.py

@@ -0,0 +1,222 @@
+"""CLI entry point for audnet."""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import structlog
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from audnet import __version__
+from audnet.collector import collect_all
+from audnet.compliance import run_checks
+from audnet.config import load_inventory, load_baseline
+from audnet.models import AuditReport
+from audnet.reporter import render_markdown, render_html
+
+# Async collector is imported lazily to avoid requiring asyncssh unless --async is used.
+_collect_all_async = None
+
+app = typer.Typer(help="Network Security & Compliance State Auditor")
+console = Console()
+logger = structlog.get_logger("audnet")
+
+_SECRET_KEYS = frozenset({"password", "key_file", "secret", "passwd", "token"})
+
+
+def _redact_secrets(
+    _logger: logging.Logger, _method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Structlog processor that redacts sensitive values from log events."""
+    for key in event_dict:
+        if key.lower() in _SECRET_KEYS and event_dict[key] is not None:
+            event_dict[key] = "***REDACTED***"
+    return event_dict
+
+
+def _setup_logging(verbose: bool = False) -> None:
+    """Configure structlog with JSON or console output and secret redaction."""
+    level = logging.DEBUG if verbose else logging.INFO
+    shared_processors: list[Any] = [
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
+        _redact_secrets,
+    ]
+    renderer: Any
+    if verbose:
+        renderer = structlog.dev.ConsoleRenderer()
+    else:
+        renderer = structlog.processors.JSONRenderer()
+
+    structlog.configure(
+        processors=[*shared_processors, renderer],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+    logging.basicConfig(
+        format="%(message)s",
+        level=level,
+    )
+
+
+@app.command()
+def audit(
+    inventory: str = typer.Option("inventories/devices.yaml", help="Device inventory YAML"),
+    baseline: str = typer.Option("baselines/security_baseline.yaml", help="Security baseline YAML"),
+    output: str = typer.Option("audit_report", help="Output file prefix"),
+    format: str = typer.Option("both", help="Output format: md, html, or both"),
+    workers: int = typer.Option(4, help="Max parallel SSH connections"),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Enable debug logging"),
+    device: str | None = typer.Option(None, "--device", help="Filter to single device by name"),
+    check: list[str] = typer.Option(
+        [],
+        "--check",
+        help="Filter to specific checks (repeatable; supports comma-separated in one arg)",
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Output JSON summary to stdout"),
+    dry_run: bool = typer.Option(
+        False,
+        "-n",
+        "--dry-run",
+        help="Validate config and show what would be audited without connecting to devices",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Fail if any device has a plaintext password (no ${ENV_VAR} reference)",
+    ),
+    no_fail: bool = typer.Option(
+        False,
+        "--no-fail",
+        help="Always exit 0 even on compliance failures (informational mode)",
+    ),
+    async_mode: bool = typer.Option(
+        False,
+        "--async",
+        help="Use asyncio-based SSH collector (recommended for >20 devices)",
+    ),
+) -> None:
+    """Run a full compliance audit against all (or filtered) devices.
+
+    Supports device/check filters, JSON output, dry-run mode, and strict secret handling for CI/automation.
+    """
+    _setup_logging(verbose)
+    console.print(f"[bold blue]audnet v{__version__} — Starting audit...[/bold blue]")
+
+    _, devices = load_inventory(inventory, strict=strict)
+    baseline_data = load_baseline(baseline)
+
+    if device:
+        devices = [d for d in devices if d.name == device]
+        if not devices:
+            console.print(f"[red]Device '{device}' not found in inventory[/red]")
+            return
+
+    check_names = set(baseline_data.get("checks", {}).keys())
+    console.print(f"Loaded {len(devices)} devices, {len(check_names)} checks")
+
+    if dry_run:
+        console.print("[bold yellow]DRY RUN — no device connections will be made[/bold yellow]")
+        console.print("[yellow]Devices that would be audited:[/yellow]")
+        for d in devices:
+            console.print(f"  • {d.name} ({d.host}) — {d.device_type}")
+        console.print("[yellow]Checks that would be run:[/yellow]")
+        for name in sorted(check_names):
+            console.print(f"  • {name}")
+        if check:
+            check_set = {c.strip() for item in check for c in item.split(",")}
+            unknown = check_set - check_names
+            if unknown:
+                console.print(
+                    f"[yellow]Warning: unknown check(s) {', '.join(sorted(unknown))} — "
+                    f"available: {', '.join(sorted(check_names))}[/yellow]"
+                )
+        console.print("[green]Dry run complete — config and baseline are valid[/green]")
+        return
+
+    # Collect with status
+    console.print("[yellow]Collecting device data...[/yellow]")
+    if async_mode:
+        import asyncio
+
+        global _collect_all_async
+        if _collect_all_async is None:
+            from audnet.collector_async import collect_all_async
+
+            _collect_all_async = collect_all_async
+        snapshots = asyncio.run(_collect_all_async(devices, max_workers=workers))
+    else:
+        snapshots = collect_all(devices, max_workers=workers)
+
+    # Resolve check filter
+    if check:
+        check_set = {c.strip() for item in check for c in item.split(",")}
+        unknown = check_set - check_names
+        if unknown:
+            console.print(
+                f"[yellow]Warning: unknown check(s) {', '.join(sorted(unknown))} — "
+                f"available: {', '.join(sorted(check_names))}[/yellow]"
+            )
+    else:
+        check_set = set()
+
+    # Audit
+    reports = []
+    for snap in snapshots:
+        if snap.collection_error:
+            console.print(f"[red]ERROR {snap.device_name}: {snap.collection_error}[/red]")
+            reports.append(AuditReport(device_name=snap.device_name, overall_pass=False, checks=[]))
+            continue
+
+        results = run_checks(snap, baseline_data)
+        if check_set:
+            results = [r for r in results if r.check_name in check_set]
+        overall = all(r.passed for r in results) if results else False
+        reports.append(
+            AuditReport(device_name=snap.device_name, overall_pass=overall, checks=results)
+        )
+
+    # Terminal summary
+    table = Table(title="Audit Results")
+    table.add_column("Device")
+    table.add_column("Status")
+    table.add_column("Passed")
+    table.add_column("Failed")
+    for r in reports:
+        status = "[green]PASS[/green]" if r.overall_pass else "[red]FAIL[/red]"
+        table.add_row(r.device_name, status, str(r.pass_count), str(r.fail_count))
+    console.print(table)
+
+    # Write reports
+    if format in ("md", "both"):
+        md_path = Path(f"{output}.md")
+        md_path.write_text(render_markdown(reports))
+        console.print(f"[green]Markdown report: {md_path}[/green]")
+
+    if format in ("html", "both"):
+        html_path = Path(f"{output}.html")
+        html_path.write_text(render_html(reports))
+        console.print(f"[green]HTML report: {html_path}[/green]")
+
+    if json_out:
+        json_data = [r.model_dump(mode="json") for r in reports]
+        console.print_json(json.dumps(json_data))
+
+    if not no_fail and reports and not all(r.overall_pass for r in reports):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def version() -> None:
+    """Show the audnet version."""
+    console.print(f"audnet {__version__}")
+
+
+if __name__ == "__main__":
+    app()

audnet/collector.py

@@ -0,0 +1,180 @@
+"""Parallel SSH collector for network device data.
+
+Uses the vendor registry for multi-vendor command dispatch.
+"""
+
+import logging
+import concurrent.futures
+from concurrent.futures import ThreadPoolExecutor
+from typing import cast
+
+from netmiko import ConnectHandler
+from netmiko.exceptions import (
+    NetmikoTimeoutException,
+    NetmikoAuthenticationException,
+    ConfigInvalidException,
+    ConnectionException,
+    ReadException,
+    NetmikoParsingException,
+)
+from paramiko.ssh_exception import SSHException
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception
+
+from audnet.exceptions import ParseError
+from audnet.models import Device, DeviceSnapshot, ParsedInterfaces, ParsedVersion, ParsedConfig
+from audnet.parser import parse_interfaces, parse_version, parse_config
+from audnet.vendor_registry import Slot, get_commands
+
+logger = logging.getLogger(__name__)
+
+# Transient exceptions that are safe to retry on
+_RETRYABLE_EXCEPTIONS = (
+    NetmikoTimeoutException,
+    ConnectionException,
+    ReadException,
+    SSHException,
+    NetmikoParsingException,
+    OSError,
+    ConnectionError,
+)
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    """Return True if *exc* is a transient error worth retrying.
+
+    Explicitly excludes authentication failures — those are never transient.
+    """
+    if isinstance(exc, NetmikoAuthenticationException):
+        return False
+    return isinstance(exc, _RETRYABLE_EXCEPTIONS)
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=2, max=10),
+    retry=retry_if_exception(_is_retryable),
+    reraise=True,
+)
+def _do_ssh_collect(device: Device) -> dict[Slot, str]:
+    """Internal function that performs the actual SSH collection.
+
+    Retries transient errors up to 3 times with exponential backoff.
+    Returns a dict mapping Slot -> raw CLI output.
+    """
+    params = {
+        "device_type": device.device_type,
+        "host": device.host,
+        "username": device.username,
+        "password": device.get_password(),
+        "port": device.port,
+        "timeout": device.timeout,
+    }
+    if device.use_keys:
+        params["use_keys"] = True
+        if device.key_file:
+            params["key_file"] = device.key_file
+    commands = get_commands(device.device_type)
+    slot_map = (Slot.INTERFACES, Slot.VERSION, Slot.RUNNING_CONFIG)
+    with ConnectHandler(**params) as conn:
+        return {slot: cast(str, conn.send_command(cmd)) for slot, cmd in zip(slot_map, commands)}
+
+
+def collect_device(device: Device) -> DeviceSnapshot:
+    """Collect data from one device (with internal retry for transient SSH issues)."""
+    logger.info("Collecting data from %s (%s)", device.name, device.host)
+    try:
+        raw_outputs = _do_ssh_collect(device)
+
+        logger.info("Successfully collected from %s", device.name)
+        parsed_version = parse_version(raw_outputs[Slot.VERSION], device_type=device.device_type)
+        return DeviceSnapshot(
+            device_name=device.name,
+            interfaces=ParsedInterfaces(
+                interfaces=parse_interfaces(
+                    raw_outputs[Slot.INTERFACES], device_type=device.device_type
+                )
+            ),
+            version=ParsedVersion(**parsed_version, raw=raw_outputs[Slot.VERSION]),
+            config=ParsedConfig(
+                lines=parse_config(raw_outputs[Slot.RUNNING_CONFIG]),
+                raw=raw_outputs[Slot.RUNNING_CONFIG],
+            ),
+        )
+    except (
+        NetmikoTimeoutException,
+        NetmikoAuthenticationException,
+        ConfigInvalidException,
+        ConnectionException,
+        ReadException,
+        NetmikoParsingException,
+        SSHException,
+        OSError,
+        ValueError,
+        ConnectionError,
+        ParseError,
+    ) as exc:
+        logger.error("Failed to collect from %s: %s", device.name, exc)
+        return DeviceSnapshot(
+            device_name=device.name,
+            interfaces=ParsedInterfaces(),
+            version=ParsedVersion(),
+            config=ParsedConfig(),
+            collection_error=str(exc),
+        )
+
+
+def collect_all(
+    devices: list[Device],
+    max_workers: int = 4,
+    timeout: float | None = None,
+) -> list[DeviceSnapshot]:
+    """Run parallel collection across devices.
+
+    Args:
+        devices: List of devices to collect from.
+        max_workers: Maximum parallel SSH connections.
+        timeout: Optional per-device timeout in seconds. If a device takes
+            longer than this, its collection is aborted and an error snapshot
+            is returned. None means no timeout.
+    """
+    from time import monotonic
+
+    deadline = monotonic() + timeout if timeout else None
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        future_to_dev = {pool.submit(collect_device, d): d for d in devices}
+        pending = set(future_to_dev)
+        completed: dict[str, DeviceSnapshot] = {}
+        while pending:
+            wait_timeout = None
+            if deadline:
+                wait_timeout = max(0, deadline - monotonic())
+            done, pending = concurrent.futures.wait(
+                pending,
+                timeout=wait_timeout,
+                return_when=concurrent.futures.FIRST_COMPLETED,
+            )
+            for future in done:
+                dev = future_to_dev[future]
+                try:
+                    completed[dev.name] = future.result(timeout=0)
+                except TimeoutError:
+                    logger.error("Collection from %s timed out after %ss", dev.name, timeout)
+                    completed[dev.name] = DeviceSnapshot(
+                        device_name=dev.name,
+                        interfaces=ParsedInterfaces(),
+                        version=ParsedVersion(),
+                        config=ParsedConfig(),
+                        collection_error=f"Collection timed out after {timeout}s",
+                    )
+            if deadline and monotonic() >= deadline:
+                for fut in pending:
+                    d = future_to_dev[fut]
+                    completed[d.name] = DeviceSnapshot(
+                        device_name=d.name,
+                        interfaces=ParsedInterfaces(),
+                        version=ParsedVersion(),
+                        config=ParsedConfig(),
+                        collection_error=f"Collection timed out after {timeout}s",
+                    )
+                break
+    return [completed[d.name] for d in devices]

audnet/collector_async.py

@@ -0,0 +1,199 @@
+"""Async SSH collector prototype for network device data.
+
+This module provides an asyncio-based alternative to the ThreadPool + Netmiko
+collector. It uses asyncssh for SSH connections and is designed to scale to
+hundreds of devices with lower memory and thread overhead.
+
+Architecture:
+    - asyncio event loop manages all concurrent SSH sessions
+    - asyncssh handles SSH transport (no thread per connection)
+    - Same DeviceSnapshot output format as sync collector
+    - Same retry logic via tenacity (async-compatible)
+
+Trade-offs vs sync collector (collector.py):
+    + Single-threaded: no GIL contention, lower memory per connection
+    + Native concurrency: scales to 100s of devices without thread overhead
+    + No thread pool sizing: concurrency limited by semaphore, not OS threads
+    - Requires asyncssh dependency (not in current dependency tree)
+    - No Netmiko device-type abstraction: commands sent raw
+    - Prototype status: not yet integrated into CLI
+
+Migration path:
+    1. Install asyncssh: uv add asyncssh
+    2. Switch collector import in cli.py: from audnet.collector_async import collect_all
+    3. Add --workers flag maps to asyncio.Semaphore limit
+    4. Keep sync collector as fallback for environments without asyncssh
+"""
+
+import asyncio
+import logging
+from typing import cast
+
+import asyncssh
+from asyncssh import (
+    ChannelOpenError,
+    DisconnectError,
+    PermissionDenied,
+    TimeoutError as AsyncSshTimeoutError,
+)
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception
+
+from audnet.models import Device, DeviceSnapshot, ParsedInterfaces, ParsedVersion, ParsedConfig
+from audnet.parser import parse_interfaces, parse_version, parse_config
+from audnet.vendor_registry import Slot, get_commands
+
+logger = logging.getLogger(__name__)
+
+# Transient exceptions that are safe to retry on (asyncssh equivalents)
+_RETRYABLE_EXCEPTIONS = (
+    DisconnectError,
+    ChannelOpenError,
+    AsyncSshTimeoutError,
+    OSError,
+    ConnectionError,
+)
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    """Return True if *exc* is a transient error worth retrying.
+
+    Explicitly excludes authentication failures -- those are never transient.
+    """
+    if isinstance(exc, PermissionDenied):
+        return False
+    return isinstance(exc, _RETRYABLE_EXCEPTIONS)
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=2, max=10),
+    retry=retry_if_exception(_is_retryable),
+    reraise=True,
+)
+async def _do_ssh_collect(device: Device, known_hosts: str | None = None) -> dict[Slot, str]:
+    """Perform async SSH collection with retry for transient errors.
+
+    Args:
+        device: Device to collect from.
+        known_hosts: Path to known_hosts file. ``None`` uses the system default
+            (``~/.ssh/known_hosts``). Pass an empty string to disable verification
+            (lab/testing only).
+    """
+    commands = get_commands(device.device_type)
+    password = device.get_password()
+    slot_map = (Slot.INTERFACES, Slot.VERSION, Slot.RUNNING_CONFIG)
+    async with asyncssh.connect(
+        device.host,
+        port=device.port,
+        username=device.username,
+        password=password,
+        known_hosts=known_hosts,
+        connect_timeout=device.timeout or 30,
+    ) as conn:
+        results: dict[Slot, str] = {}
+        for slot, cmd in zip(slot_map, commands):
+            result = await conn.run(cmd, timeout=device.timeout)
+            results[slot] = cast(str, result.stdout)
+        return results
+
+
+async def collect_device_async(
+    device: Device,
+    known_hosts: str | None = None,
+) -> DeviceSnapshot:
+    """Collect data from one device asynchronously.
+
+    Same interface as sync collect_device(), but uses asyncio + asyncssh
+    instead of ThreadPool + Netmiko.
+
+    Args:
+        device: Device to collect from.
+        known_hosts: Path to known_hosts file. ``None`` uses the system default
+            (``~/.ssh/known_hosts``). Pass an empty string to disable verification
+            (lab/testing only).
+    """
+    logger.info("Collecting data from %s (%s)", device.name, device.host)
+    try:
+        raw_outputs = await _do_ssh_collect(device, known_hosts=known_hosts)
+
+        logger.info("Successfully collected from %s", device.name)
+        parsed_version = parse_version(raw_outputs[Slot.VERSION], device_type=device.device_type)
+        return DeviceSnapshot(
+            device_name=device.name,
+            interfaces=ParsedInterfaces(
+                interfaces=parse_interfaces(
+                    raw_outputs[Slot.INTERFACES], device_type=device.device_type
+                )
+            ),
+            version=ParsedVersion(**parsed_version, raw=raw_outputs[Slot.VERSION]),
+            config=ParsedConfig(
+                lines=parse_config(raw_outputs[Slot.RUNNING_CONFIG]),
+                raw=raw_outputs[Slot.RUNNING_CONFIG],
+            ),
+        )
+    except (
+        PermissionDenied,
+        DisconnectError,
+        ChannelOpenError,
+        AsyncSshTimeoutError,
+        OSError,
+        ValueError,
+        ConnectionError,
+    ) as exc:
+        logger.error("Failed to collect from %s: %s", device.name, exc)
+        return DeviceSnapshot(
+            device_name=device.name,
+            interfaces=ParsedInterfaces(),
+            version=ParsedVersion(),
+            config=ParsedConfig(),
+            collection_error=str(exc),
+        )
+
+
+async def collect_all_async(
+    devices: list[Device],
+    max_workers: int = 50,
+    timeout: float | None = None,
+    known_hosts: str | None = None,
+) -> list[DeviceSnapshot]:
+    """Run async collection across all devices concurrently.
+
+    Uses an asyncio.Semaphore to limit concurrent connections, which is
+    more memory-efficient than a ThreadPool for large inventories.
+
+    Args:
+        devices: List of devices to collect from.
+        max_workers: Maximum concurrent SSH connections (semaphore limit).
+            Defaults to 50 -- much higher than the sync default of 4
+            because async connections have minimal per-connection overhead.
+        timeout: Optional per-device timeout in seconds.
+        known_hosts: Path to known_hosts file. ``None`` uses the system default
+            (``~/.ssh/known_hosts``). Pass an empty string to disable
+            verification (lab/testing only).
+
+    Returns:
+        List of DeviceSnapshot results, one per device.
+    """
+    semaphore = asyncio.Semaphore(max_workers)
+
+    async def _bounded_collect(device: Device) -> DeviceSnapshot:
+        async with semaphore:
+            if timeout:
+                try:
+                    return await asyncio.wait_for(
+                        collect_device_async(device, known_hosts=known_hosts),
+                        timeout=timeout,
+                    )
+                except asyncio.TimeoutError:
+                    logger.error("Collection from %s timed out after %ss", device.name, timeout)
+                    return DeviceSnapshot(
+                        device_name=device.name,
+                        interfaces=ParsedInterfaces(),
+                        version=ParsedVersion(),
+                        config=ParsedConfig(),
+                        collection_error=f"Collection timed out after {timeout}s",
+                    )
+            return await collect_device_async(device, known_hosts=known_hosts)
+
+    tasks = [asyncio.create_task(_bounded_collect(d)) for d in devices]
+    return list(await asyncio.gather(*tasks))