f5audit

Read-only audit tool for F5 BIG-IP LTM. It collects configuration and statistics via iControl REST (GET only), correlates object references, and produces a multi-sheet Excel report identifying unused objects (nodes, pools, virtual servers, monitors) as input for a human-driven, change- controlled cleanup.

This tool never modifies the device. The "suggested command" columns in the report are informational text only; nothing is ever executed.

Safety design

• The HTTP client (F5ReadOnlyClient) exposes a single get() method. There are no post/patch/put/delete methods. The only internal write is the token login, hardcoded to /mgmt/shared/authn/login. This is enforced by structural tests.
• No tmsh/bash execution endpoints are used or referenced anywhere.
• No explicit logout (deleting the token would be a write); tokens expire on their own (~20 minutes).
• Passwords are read from an interactive prompt (getpass) or the F5_PASS environment variable — never from a CLI argument, and never written to disk or logs.
• Management-plane friendly: sequential requests only, $top/$skip pagination, per-request delay (--delay, default 0.1 s), 30 s timeout, max 2 retries with exponential backoff.

Requirements

• Python >= 3.9, requests, openpyxl
• An account with a read-only role (Auditor/Guest) and iControl REST access on the BIG-IP
• Network access to the management interface (TCP 443)

Installation

pip install f5audit

From source: pip install . — or without installing, from the project directory: python -m f5audit ...

Usage

1. Validate access first

f5audit validate --host 192.0.2.1 --user auditor --insecure

Probes login plus the key GET endpoints and prints a diagnosis per response code (bad credentials, missing REST access, denied endpoints, old BIG-IP versions, network timeouts).

2. Collect once, analyze offline N times

f5audit collect --host 192.0.2.1 --user auditor --insecure --save-raw ./raw/
f5audit analyze --from-raw ./raw/ --out report.xlsx

collect saves every raw JSON response (with timestamps) to disk; analyze --from-raw re-analyzes from that cache without touching the F5 again. This is the recommended workflow: one collection per session, all further analysis offline.

One-step alternative

f5audit analyze --host 192.0.2.1 --user auditor --insecure --save-raw ./raw/ --out report.xlsx

Options

Exit codes: 0 OK · 1 connection/auth error · 2 analysis completed with warnings (standby device, denied partitions, missing endpoints).

Verdicts

Operational warning

• Collect on the ACTIVE unit of the HA pair. On a standby unit traffic counters are zeros and the tool will skip traffic analysis (or mark it UNRELIABLE with --allow-standby).
• Traffic counters reset on reboot / stats reset. Ideally collect after several weeks of uptime; the report includes the failover-state age as context.
• INACTIVE means "no traffic since the counters started", not "safe to delete". Use the planned compare workflow (v2) — two collections some weeks apart — to distinguish real zero traffic from a recent reset. The raw cache already stores per-file timestamps to enable this.
• Availability is point-in-time: an OFFLINE chain reflects monitor state at collection time and may mean maintenance rather than decommissioning. Always confirm with the config owner before requesting deletion.

Report sheets

1. Summary — hostname, version, HA state, uptime context, partitions, verdict counts, active warnings.
2. Inventory — one row per pool member (plus rows for pool-less nodes), fully correlated: node ↔ pool ↔ virtual server ↔ monitor ↔ iRule/policy references, statuses, traffic and verdict.
3. Orphan Nodes · 4. Orphan-Inactive Pools · 5. Inactive Virtual Servers — filtered views with informational tmsh commands for the change request.
4. Dead Chains — one row per pool with an OFFLINE (decommission candidate) verdict, grouping the whole chain (virtual servers → pool → member nodes) with per-object verdicts and the informational tmsh delete lines to take to the config owner. Nodes still alive in another pool get no delete line here.
5. Orphan Monitors — filtered view with informational tmsh commands.
6. Manual Review — objects touched by dynamic logic, with the iRule/policy that causes the doubt.

Color coding: red = ORPHAN · yellow = MANUAL REVIEW / UNRELIABLE · orange = INACTIVE · purple = OFFLINE · green = IN USE.

Development

pip install -e ".[dev]"
ruff check f5audit tests && ruff format --check f5audit tests
pytest

No test touches the network; everything runs from anonymized JSON fixtures and mocked HTTP sessions. Structural tests assert the client exposes no write verbs and that no forbidden endpoint appears in the source. CI runs lint plus the test suite on Python 3.9 through 3.14; all checks must pass before a PR can merge.

Releases are published to PyPI automatically: bump __version__ in f5audit/__init__.py, merge, and create a GitHub release tagged v<version>. The release workflow verifies the tag matches the package version, builds, and publishes via PyPI Trusted Publishing (no stored API tokens).