f5audit 0.1.0__py3-none-any.whl

f5audit/__init__.py

@@ -0,0 +1,8 @@
+"""f5audit: read-only audit tool for F5 BIG-IP LTM configurations.
+
+Collects configuration and statistics via iControl REST (GET only),
+correlates object references, and reports orphaned / inactive objects
+as input for a human-driven, change-controlled cleanup.
+"""
+
+__version__ = "0.1.0"

f5audit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

f5audit/analyzer.py

@@ -0,0 +1,301 @@
+"""Verdict rules.
+
+Cross-cutting rules (spec section 8):
+- No object touched by dynamic pool-selection logic can ever be ORPHAN;
+  the ceiling is MANUAL REVIEW.
+- Traffic-based verdicts are only trusted when the device is ACTIVE;
+  on a standby unit they are either skipped (default) or emitted as
+  UNRELIABLE (standby) with --allow-standby.
+- Incomplete inventory (denied partitions/endpoints) degrades orphan
+  verdicts, because a reference could live in an invisible partition.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .correlator import Correlation, is_builtin_monitor
+from .parsing import ParsedData
+
+
+class Verdict:
+    ORPHAN = "ORPHAN"
+    MANUAL_REVIEW = "MANUAL REVIEW"
+    INACTIVE = "INACTIVE"
+    UNRELIABLE_STANDBY = "UNRELIABLE (standby)"
+    UNRELIABLE_INVENTORY = "UNRELIABLE (incomplete inventory)"
+    IN_USE = "IN USE"
+
+
+@dataclass
+class ObjectVerdict:
+    verdict: str
+    notes: str = ""
+
+
+@dataclass
+class ManualReviewItem:
+    object_type: str
+    full_path: str
+    reason: str
+    caused_by: str = ""
+
+
+@dataclass
+class AnalysisResult:
+    node_verdicts: dict[str, ObjectVerdict] = field(default_factory=dict)
+    pool_verdicts: dict[str, ObjectVerdict] = field(default_factory=dict)
+    virtual_verdicts: dict[str, ObjectVerdict] = field(default_factory=dict)
+    monitor_verdicts: dict[str, ObjectVerdict] = field(default_factory=dict)
+    manual_review: list[ManualReviewItem] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    stats_analysis_skipped: bool = False
+
+    def verdict_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for verdicts in (
+            self.node_verdicts,
+            self.pool_verdicts,
+            self.virtual_verdicts,
+            self.monitor_verdicts,
+        ):
+            for object_verdict in verdicts.values():
+                counts[object_verdict.verdict] = counts.get(object_verdict.verdict, 0) + 1
+        return counts
+
+
+def _conns_zero(total_conns: int | None) -> bool:
+    return total_conns is not None and int(total_conns) == 0
+
+
+class Analyzer:
+    def __init__(
+        self, parsed: ParsedData, correlation: Correlation, *, allow_standby: bool = False
+    ):
+        self.parsed = parsed
+        self.correlation = correlation
+        self.allow_standby = allow_standby
+
+        system = parsed.system
+        self.is_standby = system.failover_state == "standby"
+        self.inventory_complete = not system.partitions_denied and not any(
+            "/ltm/node" in ep or "/ltm/pool" in ep or "/ltm/virtual" in ep
+            for ep in system.missing_endpoints
+        )
+        self.irules_available = not any("/ltm/rule" in ep for ep in system.missing_endpoints)
+        # Uptime context: traffic counters reset on reboot / stats reset.
+        self.traffic_note = (
+            "Traffic counters reset on reboot/stats-reset; "
+            f"{system.uptime or 'device uptime unknown'}."
+        )
+
+    # ------------------------------------------------------------------
+
+    def run(self) -> AnalysisResult:
+        result = AnalysisResult()
+        self._collect_warnings(result)
+        self._analyze_nodes(result)
+        self._analyze_virtuals(result)
+        self._analyze_pools(result)
+        self._analyze_monitors(result)
+        self._analyze_irules(result)
+        return result
+
+    def _collect_warnings(self, result: AnalysisResult) -> None:
+        system = self.parsed.system
+        if self.is_standby:
+            if self.allow_standby:
+                result.warnings.append(
+                    "Device is STANDBY: traffic statistics are not "
+                    "representative. Traffic-based verdicts are marked "
+                    "UNRELIABLE (standby). Re-run against the ACTIVE unit."
+                )
+            else:
+                result.stats_analysis_skipped = True
+                result.warnings.append(
+                    "Device is STANDBY: traffic-based analysis was SKIPPED "
+                    "(configuration-orphan analysis still ran). Re-run "
+                    "against the ACTIVE unit, or use --allow-standby to "
+                    "force traffic verdicts marked as UNRELIABLE."
+                )
+        if system.partitions_denied:
+            result.warnings.append(
+                "Access denied to partition(s): "
+                + ", ".join(system.partitions_denied)
+                + ". Orphan verdicts are degraded to UNRELIABLE (incomplete "
+                "inventory) because objects could be referenced from an "
+                "invisible partition."
+            )
+        if not self.irules_available:
+            result.warnings.append(
+                "ltm/rule was not readable: pool orphan verdicts are capped "
+                "at MANUAL REVIEW (an iRule could reference them)."
+            )
+        for endpoint in system.missing_endpoints:
+            if "/ltm/rule" not in endpoint:
+                result.warnings.append(f"Endpoint not collected: {endpoint}")
+
+    # ------------------------------------------------------------------
+
+    def _analyze_nodes(self, result: AnalysisResult) -> None:
+        for path, _node in self.parsed.nodes.items():
+            pools = self.correlation.node_to_pools.get(path)
+            if pools:
+                result.node_verdicts[path] = ObjectVerdict(Verdict.IN_USE)
+            elif not self.inventory_complete:
+                result.node_verdicts[path] = ObjectVerdict(
+                    Verdict.UNRELIABLE_INVENTORY,
+                    "Not a member of any visible pool, but some partitions were not readable.",
+                )
+            else:
+                result.node_verdicts[path] = ObjectVerdict(
+                    Verdict.ORPHAN, "Not a member of any pool."
+                )
+
+    def _analyze_virtuals(self, result: AnalysisResult) -> None:
+        for path, virtual in self.parsed.virtuals.items():
+            if virtual.admin_state == "disabled":
+                result.virtual_verdicts[path] = ObjectVerdict(
+                    Verdict.INACTIVE, "Administratively disabled."
+                )
+                continue
+            if not virtual.default_pool and (virtual.irules or virtual.policies):
+                result.virtual_verdicts[path] = ObjectVerdict(
+                    Verdict.MANUAL_REVIEW,
+                    "No default pool; traffic is steered by iRules/policies.",
+                )
+                result.manual_review.append(
+                    ManualReviewItem(
+                        "virtual_server",
+                        path,
+                        "No default pool but has iRules/policies attached",
+                        ", ".join(virtual.irules + virtual.policies),
+                    )
+                )
+                continue
+            if _conns_zero(virtual.total_conns):
+                self._traffic_verdict(
+                    result.virtual_verdicts,
+                    path,
+                    "Enabled but zero total connections. " + self.traffic_note,
+                )
+                continue
+            result.virtual_verdicts[path] = ObjectVerdict(Verdict.IN_USE)
+
+    def _traffic_verdict(self, verdicts: dict[str, ObjectVerdict], path: str, note: str) -> None:
+        """Emit a traffic-based INACTIVE verdict, degraded on standby."""
+        if self.is_standby:
+            if self.allow_standby:
+                verdicts[path] = ObjectVerdict(
+                    Verdict.UNRELIABLE_STANDBY,
+                    "Zero traffic, but this device is standby. " + note,
+                )
+            else:
+                verdicts[path] = ObjectVerdict(
+                    Verdict.IN_USE,
+                    "Traffic analysis skipped (standby device).",
+                )
+        else:
+            verdicts[path] = ObjectVerdict(Verdict.INACTIVE, note)
+
+    def _analyze_pools(self, result: AnalysisResult) -> None:
+        for path, _pool in self.parsed.pools.items():
+            virtuals = self.correlation.pool_to_virtuals.get(path, set())
+            irule_refs = self.correlation.pool_to_irules.get(path, set())
+            policy_refs = self.correlation.pool_to_policies.get(path, set())
+
+            if not virtuals and not irule_refs and not policy_refs:
+                self._unreferenced_pool_verdict(result, path)
+                continue
+
+            # Referenced pool: inactive if every attached VS has zero traffic.
+            if (
+                virtuals
+                and all(
+                    _conns_zero(self.parsed.virtuals[v].total_conns)
+                    for v in virtuals
+                    if v in self.parsed.virtuals
+                )
+                and any(v in self.parsed.virtuals for v in virtuals)
+            ):
+                self._traffic_verdict(
+                    result.pool_verdicts,
+                    path,
+                    "All attached virtual servers have zero total "
+                    "connections. " + self.traffic_note,
+                )
+                continue
+            result.pool_verdicts[path] = ObjectVerdict(Verdict.IN_USE)
+
+    def _unreferenced_pool_verdict(self, result: AnalysisResult, path: str) -> None:
+        if not self.inventory_complete:
+            result.pool_verdicts[path] = ObjectVerdict(
+                Verdict.UNRELIABLE_INVENTORY,
+                "No visible references, but some partitions were not readable.",
+            )
+        elif not self.irules_available:
+            result.pool_verdicts[path] = ObjectVerdict(
+                Verdict.MANUAL_REVIEW,
+                "No VS/policy references; iRules could not be read "
+                "(ltm/rule denied), so an iRule reference cannot be ruled out.",
+            )
+            result.manual_review.append(
+                ManualReviewItem(
+                    "pool",
+                    path,
+                    "Unreferenced, but ltm/rule was not readable",
+                )
+            )
+        elif self.correlation.has_attached_dynamic_irules:
+            dynamic = ", ".join(self.correlation.attached_dynamic_irules)
+            result.pool_verdicts[path] = ObjectVerdict(
+                Verdict.MANUAL_REVIEW,
+                "No static references, but dynamic pool-selection iRules "
+                f"are active ({dynamic}); the pool could be selected at "
+                "runtime.",
+            )
+            result.manual_review.append(
+                ManualReviewItem(
+                    "pool",
+                    path,
+                    "No static references but dynamic iRules are active",
+                    dynamic,
+                )
+            )
+        else:
+            result.pool_verdicts[path] = ObjectVerdict(
+                Verdict.ORPHAN,
+                "Not referenced by any virtual server, iRule or policy.",
+            )
+
+    def _analyze_monitors(self, result: AnalysisResult) -> None:
+        for path, _monitor in self.parsed.monitors.items():
+            if is_builtin_monitor(path):
+                result.monitor_verdicts[path] = ObjectVerdict(
+                    Verdict.IN_USE, "F5 built-in monitor (excluded from orphan analysis)."
+                )
+                continue
+            users = self.correlation.monitor_users.get(path)
+            if users:
+                result.monitor_verdicts[path] = ObjectVerdict(Verdict.IN_USE)
+            elif not self.inventory_complete:
+                result.monitor_verdicts[path] = ObjectVerdict(
+                    Verdict.UNRELIABLE_INVENTORY,
+                    "Unused in visible partitions, but some partitions were not readable.",
+                )
+            else:
+                result.monitor_verdicts[path] = ObjectVerdict(
+                    Verdict.ORPHAN, "Not used by any node or pool."
+                )
+
+    def _analyze_irules(self, result: AnalysisResult) -> None:
+        for path, irule in self.parsed.irules.items():
+            if irule.has_dynamic_pool_selection:
+                result.manual_review.append(
+                    ManualReviewItem(
+                        "irule",
+                        path,
+                        "Selects pools dynamically ($variable, [command] or "
+                        "datagroup); static analysis cannot resolve its targets",
+                    )
+                )

f5audit/cli.py

@@ -0,0 +1,338 @@
+"""Command line interface: collect / analyze / validate."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import logging
+import os
+import sys
+from datetime import datetime
+
+from . import __version__
+from .analyzer import Analyzer
+from .client import F5APIError, F5AuthError, F5ClientError, F5ReadOnlyClient
+from .collector import CollectionData, Collector, RawStore, load_from_raw
+from .correlator import correlate
+from .parsing import parse_collection
+from .report import build_tables, default_report_name, write_csv, write_xlsx
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_WARNINGS = 2
+
+logger = logging.getLogger("f5audit")
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+
+def _add_connection_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--host", help="BIG-IP management address")
+    parser.add_argument(
+        "--user",
+        help="Username (or set the F5_USER environment variable)",
+    )
+    parser.add_argument(
+        "--login-provider",
+        default="tmos",
+        help="Auth provider for token login (default: tmos; use the remote "
+        "provider name for TACACS+/RADIUS setups)",
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Skip TLS certificate verification (self-signed mgmt certs)",
+    )
+    parser.add_argument(
+        "--delay",
+        type=float,
+        default=0.1,
+        help="Delay in seconds between requests (default: 0.1)",
+    )
+    parser.add_argument(
+        "--top",
+        type=int,
+        default=100,
+        help="Page size for collection pagination (default: 100)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="f5audit",
+        description="Read-only audit of an F5 BIG-IP LTM configuration. Never modifies the device.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "--verbose", action="store_true", help="Debug logging (never prints passwords/tokens)"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    collect_parser = subparsers.add_parser(
+        "collect", help="Collect configuration and stats, save raw JSON"
+    )
+    _add_connection_args(collect_parser)
+    collect_parser.add_argument(
+        "--save-raw",
+        metavar="DIR",
+        help="Directory for raw JSON cache (default: ./f5audit_raw_<host>_<ts>)",
+    )
+
+    analyze_parser = subparsers.add_parser(
+        "analyze", help="Analyze (from a live device or a raw cache) and report"
+    )
+    _add_connection_args(analyze_parser)
+    analyze_parser.add_argument(
+        "--from-raw", metavar="DIR", help="Analyze a previously saved raw cache"
+    )
+    analyze_parser.add_argument(
+        "--save-raw", metavar="DIR", help="Also save raw JSON while collecting"
+    )
+    analyze_parser.add_argument("--out", help="Output report path")
+    analyze_parser.add_argument("--format", choices=["xlsx", "csv"], default="xlsx")
+    analyze_parser.add_argument(
+        "--allow-standby",
+        action="store_true",
+        help="On a standby unit, emit traffic verdicts marked UNRELIABLE "
+        "instead of skipping traffic analysis",
+    )
+
+    validate_parser = subparsers.add_parser(
+        "validate", help="Probe access: login plus key GET endpoints"
+    )
+    _add_connection_args(validate_parser)
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_credentials(args) -> tuple:
+    username = args.user or os.environ.get("F5_USER")
+    if not username:
+        print(
+            "Error: provide a username with --user or the F5_USER environment variable.",
+            file=sys.stderr,
+        )
+        sys.exit(EXIT_ERROR)
+    # Password never travels as a CLI argument (visible in process lists).
+    password = os.environ.get("F5_PASS")
+    if not password:
+        password = getpass.getpass(f"Password for {username}@{args.host}: ")
+    return username, password
+
+
+def _build_client(args) -> F5ReadOnlyClient:
+    if not args.host:
+        print("Error: --host is required for this command.", file=sys.stderr)
+        sys.exit(EXIT_ERROR)
+    username, password = _resolve_credentials(args)
+    if args.insecure:
+        print(
+            "WARNING: TLS certificate verification is DISABLED "
+            "(--insecure). Only use this on a trusted management network.",
+            file=sys.stderr,
+        )
+        try:
+            import urllib3
+
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+        except ImportError:
+            pass
+    return F5ReadOnlyClient(
+        args.host,
+        username,
+        password,
+        verify_tls=not args.insecure,
+        login_provider=args.login_provider,
+        delay=args.delay,
+        page_size=args.top,
+    )
+
+
+def _collect(args, save_raw_dir: str | None) -> CollectionData:
+    client = _build_client(args)
+    raw_store = RawStore(save_raw_dir) if save_raw_dir else None
+    collector = Collector(client, raw_store=raw_store)
+    data = collector.collect()
+    if save_raw_dir:
+        print(f"Raw JSON saved to: {save_raw_dir}")
+    if data.meta.get("aborted"):
+        print(f"Collection aborted early: {data.meta['aborted']}", file=sys.stderr)
+        print(f"Partial data ({len(data.datasets)} datasets) was kept.", file=sys.stderr)
+    return data
+
+
+def _default_raw_dir(host: str) -> str:
+    stamp = datetime.now().strftime("%Y%m%d-%H%M")
+    return f"./f5audit_raw_{host}_{stamp}"
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+
+def cmd_collect(args) -> int:
+    save_raw_dir = args.save_raw or _default_raw_dir(args.host or "unknown")
+    data = _collect(args, save_raw_dir)
+    if data.meta.get("aborted"):
+        return EXIT_ERROR
+    print(
+        f"Collected {len(data.datasets)} datasets. "
+        f"Analyze offline with: f5audit analyze --from-raw {save_raw_dir}"
+    )
+    return EXIT_OK
+
+
+def cmd_analyze(args) -> int:
+    if args.from_raw:
+        data = load_from_raw(args.from_raw)
+        print(
+            f"Loaded raw cache from {args.from_raw} "
+            f"(collected at {data.meta.get('collected_at', 'unknown')})."
+        )
+    else:
+        data = _collect(args, args.save_raw)
+        if data.meta.get("aborted"):
+            return EXIT_ERROR
+
+    parsed = parse_collection(data)
+    correlation = correlate(parsed)
+    analysis = Analyzer(parsed, correlation, allow_standby=args.allow_standby).run()
+
+    # Prominent standby warning happens before writing anything.
+    for warning in analysis.warnings:
+        print(f"\nWARNING: {warning}", file=sys.stderr)
+
+    tables = build_tables(parsed, correlation, analysis)
+    out = args.out or default_report_name(parsed.system.hostname, args.format)
+    if args.format == "csv":
+        written = write_csv(tables, out)
+        print(f"\nCSV report written: {len(written)} files in {out}/")
+    else:
+        write_xlsx(tables, out)
+        print(f"\nExcel report written: {out}")
+
+    counts = analysis.verdict_counts()
+    print(
+        "Verdict counts: "
+        + ", ".join(f"{verdict}={count}" for verdict, count in sorted(counts.items()))
+    )
+    return EXIT_WARNINGS if analysis.warnings else EXIT_OK
+
+
+VALIDATE_PROBES = [
+    ("sys/version", "/mgmt/tm/sys/version", None),
+    ("auth/partition", "/mgmt/tm/auth/partition", {"$top": 1}),
+    ("ltm/pool", "/mgmt/tm/ltm/pool", {"$top": 1}),
+    ("ltm/virtual", "/mgmt/tm/ltm/virtual", {"$top": 1}),
+    ("ltm/node", "/mgmt/tm/ltm/node", {"$top": 1}),
+    ("ltm/rule", "/mgmt/tm/ltm/rule", {"$top": 1}),
+    ("ltm/virtual/stats", "/mgmt/tm/ltm/virtual/stats", None),
+    ("sys/failover", "/mgmt/tm/sys/failover", None),
+]
+
+
+def _diagnose(endpoint: str, status: object) -> str:
+    if status == 200:
+        return "OK"
+    if status == 401:
+        return "Unauthorized: check credentials / REST access for this account"
+    if status == 403:
+        if endpoint == "ltm/rule":
+            return "Forbidden: pool orphan verdicts will be capped at MANUAL REVIEW"
+        return "Forbidden: this account cannot read this endpoint"
+    if status == 404:
+        return "Not found: endpoint missing on this BIG-IP version"
+    if status == "timeout":
+        return "Timeout: check network/firewall path to the management interface"
+    return f"Unexpected response ({status})"
+
+
+def cmd_validate(args) -> int:
+    client = _build_client(args)
+    print(f"Validating read access to {args.host}...\n")
+    try:
+        client.login()
+    except F5AuthError as exc:
+        print(f"LOGIN FAILED: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except F5ClientError as exc:
+        print(f"CONNECTION FAILED: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    auth_mode = getattr(client, "_auth_mode", "token")
+    print(
+        f"Login: OK (auth mode: {auth_mode}"
+        + (", old BIG-IP without token auth" if auth_mode == "basic" else "")
+        + ")\n"
+    )
+
+    print(f"{'Endpoint':<22} {'Status':<8} Diagnosis")
+    print("-" * 78)
+    failures = 0
+    for endpoint, path, params in VALIDATE_PROBES:
+        try:
+            client.get(path, params=params)
+            status: object = 200
+        except F5APIError as exc:
+            status = exc.status_code
+        except F5ClientError:
+            status = "timeout"
+        if status != 200:
+            failures += 1
+        print(f"{endpoint:<22} {str(status):<8} {_diagnose(endpoint, status)}")
+
+    if failures:
+        print(f"\n{failures} probe(s) failed. Collection may be degraded.")
+        return EXIT_WARNINGS
+    print("\nAll probes passed. The account is ready for 'f5audit collect'.")
+    return EXIT_OK
+
+
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+    handlers = {
+        "collect": cmd_collect,
+        "analyze": cmd_analyze,
+        "validate": cmd_validate,
+    }
+    try:
+        return handlers[args.command](args)
+    except F5AuthError as exc:
+        print(f"Authentication error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except F5ClientError as exc:
+        if args.verbose:
+            logger.exception("Client error")
+        print(f"Error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return EXIT_ERROR
+    except Exception as exc:  # noqa: BLE001 - no raw tracebacks for end users
+        if args.verbose:
+            logger.exception("Unexpected error")
+        print(
+            f"Unexpected error: {exc.__class__.__name__}: {exc}. "
+            "Re-run with --verbose for details.",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())